# Verixa — User Requirements Specification

# Module 8: Tenant Management / Tenant Lifecycle

| Field | Value |
|---|---|
| Document ID | VRX-URS-08 |
| Version | 1.0 |
| Status | Final — ready for QA, Validation, Regulatory Affairs, Information Security, Legal, and Founder approval. URS approval is separate from validation execution. This document becomes "Approved Controlled URS — released for engineering implementation and validation planning" only after signature capture in the Document Approval block. It becomes "Released for validation execution" only after the module migration evidence gate (URS-08-VAL-008) and validation evidence pack are satisfied. |
| Document Type | User Requirements Specification (URS) |
| GAMP 5 Category | Category 5 — Custom Application |
| Regulatory Classification | Critical infrastructure substrate — operates the canonical tenant identity, the tenant onboarding workflow with legal-entity verification and KYC, the tenant lifecycle state machine (`pending → in_setup → active → suspended → in_offboarding → offboarded`), tenant data residency, regulatory framework defaults, retention defaults, contract terms / entitlements / feature gating, the offboarding data-export contract, the chain-sealing handshake with URS-06, and the cross-tenant collaboration prerequisite consumed by URS-07. Module 8 is the foundation that every other Verixa module builds on; tenant isolation, data residency, and inter-tenant boundaries flow from this module. |
| Date of Issue | 2026-05-06 |
| Module Owner (Engineering) | Tenant Lifecycle / Platform Foundations Squad |
| Module Owner (Quality Validation) | CSV / CSA Lead — Tenant Management |
| Module Owner (Compliance) | Quality Assurance, Regulatory Affairs, Information Security, Legal, Privacy / DPO |
| Approving Authority | Founder / Chairman & MD; QA Head; Validation Head; RA Head; Information Security Head; Legal / Privacy lead |

## Document Approval

| Role | Name | Signature | Date |
|---|---|---|---|
| Author — Platform Architecture | _____________________ | _____________________ | __________ |
| Reviewer — Engineering Lead | _____________________ | _____________________ | __________ |
| Reviewer — QA / Validation Lead | _____________________ | _____________________ | __________ |
| Reviewer — Information Security Lead | _____________________ | _____________________ | __________ |
| Reviewer — Regulatory Affairs Lead | _____________________ | _____________________ | __________ |
| Reviewer — Legal / Privacy Lead | _____________________ | _____________________ | __________ |
| Approving Authority — Founder, Chairman & MD | _____________________ | _____________________ | __________ |

## Version History

| Version | Date | Summary |
|---|---|---|
| 1.0 | 2026-05-06 | First issued user requirements specification for Module 8. |

---

## 0. Document Framing

### 0.1 Purpose of this document

This URS defines the target expected state for Verixa's Tenant Management / Tenant Lifecycle module (Module 8). It is the binding contract between product, engineering, quality validation, regulatory affairs, information security, legal / privacy, and the executive authority for the design, implementation, validation, release, and on-going periodic review of the canonical tenant identity, the tenant onboarding workflow including legal-entity verification and pharma-specific licence verification, the tenant lifecycle state machine, the tenant data residency model, the regulatory framework defaults for the tenant, the retention defaults, the contract terms / entitlements / feature gating, the tenant suspension model, the offboarding data-export contract, the chain-sealing handshake with URS-06, the controlled migration paths (residency change, platform version migration), and the cross-tenant collaboration prerequisite consumed by URS-07. Compliance with this URS is mandatory.

### 0.2 Audience

Engineering, QA, Validation, Regulatory Affairs, Information Security, Legal / Privacy / Data Protection Officer, executive authority, the platform's Implementation team, internal and external auditors, and inspectors from regulatory bodies including the United States Food and Drug Administration, the European Medicines Agency / national competent authorities, the Medicines and Healthcare products Regulatory Agency, Health Canada, the Central Drugs Standard Control Organisation of India, and Pharmaceutical Inspection Co-operation Scheme members. The plain-language primer (§0.4) and worked examples (§3.5) make Module 8 accessible to non-domain engineers, product owners, validation engineers, sales-engineering, customer-success, and contract counsel who have not previously specified tenant-lifecycle substrates for regulated GxP SaaS platforms.

### 0.3 How to read this document

Each requirement has a unique identifier. "MUST" denotes a mandatory requirement; "SHOULD" denotes a strong recommendation; "MAY" denotes an option. The document is self-contained: front end (§5), back end (§6), data model (§6.2), application programming interface (§6.3), workflow (§6.4), business rules (§6.5), audit (§6.6), security (§12), regulatory mapping (§14), test cases (§16), and validation evidence (§17) are all in this single file.

### 0.4 Plain-language primer for non-domain readers

A **tenant** is the customer organisation that uses Verixa — typically a pharmaceutical manufacturer, a contract research organisation (CRO), a contract development and manufacturing organisation (CDMO), a biotech, a generics company, a clinical-trial sponsor, a hospital pharmacy, or a compounding pharmacy. Every Verixa user belongs to a tenant; every Verixa record is owned by a tenant; every workflow runs in the context of a tenant. The "tenant" is the unit of data isolation, billing, regulatory accountability, and contractual relationship. Module 8 owns the tenant record itself and the lifecycle that surrounds it.

A tenant has eight lifecycle states: six operational states — **pending** (Verixa has received an onboarding request but has not yet verified the legal entity), **in setup** (legal entity verified; tenant administrator is configuring residency, regulatory framework defaults, initial users, and the seed Tier 2 catalogue), **active** (tenant is fully operational), **suspended** (tenant is operationally paused under controlled circumstances — payment default, regulatory concern, security incident, or customer-requested pause), **in offboarding** (tenant has initiated termination; data export and chain sealing are in progress), and **offboarded** (terminal state; tenant retains read-only export access for the contractual window; Verixa retains the audit and snapshot chains for the regulatory minimum) — plus two terminal pre-activation states: **rejected** (onboarding declined before activation) and **withdrawn** (prospective tenant abandons setup before activation).

Onboarding has seven prerequisites that must all be satisfied before a tenant can transition from `pending` to `active`: **(1) legal-entity verification** — the platform verifies the tenant's legal registration in its primary jurisdiction (e.g., US Secretary of State filing, UK Companies House, India MCA, EU equivalent); **(2) pharma-specific licence verification** — where the tenant's posture asserts a regulated activity, the appropriate licence must be verified (FDA establishment registration, EMA marketing authorisation, CDSCO drug manufacturing licence, MHRA wholesale dealer's licence, Health Canada DEL, etc.); **(3) signed master services agreement** — the contract terms that define the tenant's entitlements and obligations; **(4) signed Data Processing Agreement (DPA)** — controller / processor terms, cross-border transfer authorisations (Standard Contractual Clauses for EU export, equivalent mechanisms for other regions), DPO co-sign per `legal_dpo_authority`; **(5) data residency selection** — at launch the tenant chooses one of the three available residency regions (US, EU, India); **(6) regulatory framework defaults** — per-study-type default regulatory anchors per Module 7 DEC-07-11; **(7) initial tenant administrator** — the first human with `tenant_admin_authority` who completes the rest of setup. The executive authority co-signs every tenant activation as the platform's "we accept this customer" signature, with explicit executive authority review where the tenant operates in a high-risk vertical (cell and gene therapy, sterile manufacturing, pharmacy compounding, clinical trials).

**Data residency** is regulatorily significant. Each tenant's content data lives in exactly one residency region; cross-region replication is for backup and disaster recovery only, not for active read/write traffic. URS-35 owns the storage infrastructure; Module 8 owns the residency selection and the residency-change migration path (which is a major event requiring executive authority approval and minimum 30-day customer preparation).

**Tenant suspension** is the controlled-pause mechanism. A tenant in `suspended` state cannot mutate any record; reads continue to function for the inspection / audit surface; cross-tenant collaboration where this tenant is a partner is suspended in lockstep. Suspension reasons are categorised: payment default, regulatory concern (the tenant has lost a required licence; the tenant is under enforcement action), security incident (the tenant's account has been compromised; investigation in progress), customer-requested (the tenant has asked for an operational pause). Each reason has a different reversibility profile and a different Founder-approval gate.

**Offboarding** is terminal but considered. The tenant requests offboarding (or Verixa initiates it after extended suspension or contract termination); the platform produces a comprehensive data export bundle including every audit row, every regulated record, every controlled document, the snapshot chains, and the integrity manifest; both Verixa and the tenant electronically sign the export package; URS-06 chains for the tenant are sealed (no further inserts; final external anchor publication); the tenant moves to `offboarded`; Verixa retains the chains for the regulatory minimum (typically 25 years for authority snapshots, 7 years for general audit) but cannot access tenant content for any purpose other than legal / regulatory mandate. The tenant retains read-only export access for the contractual window (typically 7 years).

**Cross-tenant collaboration** (Module 7's sponsor-CRO model) requires both tenants to be in `active` state at the moment of grant proposal AND grant acceptance; if either falls out of `active` during the active grant, the partner-tenant access is suspended in lockstep with the underlying tenant. Module 8 is the source of truth that URS-07 consults at every collaboration grant lifecycle event.

Module 8 is the **foundation** module: every other Verixa module assumes that a valid `active`-state tenant exists for every record, every signature, every authority resolution, every audit row. Module 8's correctness is existential to the platform's tenant-isolation, data-residency, and regulatory-accountability posture.

### 0.5 Tenant lifecycle diagram

```mermaid
stateDiagram-v2
  [*] --> pending : Onboarding request received
  pending --> in_setup : Legal-entity verification + pharma-licence verification + signed MSA
  pending --> rejected : Verification failed (terminal)
  in_setup --> active : executive authority co-sign + initial admin appointed; emits TENANT_ACTIVATED into the existing tenant chain (genesis already emitted at pending creation)
  in_setup --> withdrawn : Tenant abandons onboarding pre-activation (terminal)
  active --> suspended : Suspension event (payment / regulatory / security / customer-requested)
  suspended --> active : Suspension reason resolved + executive authority co-sign
  suspended --> in_offboarding : Suspension prolonged or contract terminated
  active --> in_offboarding : Tenant requests offboarding OR contract terminated
  in_offboarding --> offboarded : Data export signed + URS-06 chain sealing + executive authority co-sign
  offboarded --> [*] : Terminal; export read access for contractual window
  rejected --> [*]
  withdrawn --> [*]
```

Diagram 0.5-A — Tenant lifecycle. Activation requires executive authority co-sign as the platform's "we accept this customer" signature. Suspension is reversible only when the suspension reason is resolved and executive authority co-signs return-to-active. Offboarding seals the URS-06 chains; tenant retains export read access for the contractual window.

### 0.6 Glossary of key terms used in this document

| Term | Definition |
|---|---|
| Active state | Tenant is fully operational; users can authenticate, regulated decisions can be signed, cross-tenant collaboration is permitted. |
| Beneficial ownership | The natural persons who ultimately own or control the tenant legal entity; required disclosure during onboarding for KYC purposes. |
| Chain sealing | The URS-06 operation at offboarding that publishes a final external anchor of the tenant's chain HEADs and disables further inserts on the tenant's chains. Performed only at offboarding per URS-06 BR-06-17. |
| Contract terms | The signed master services agreement (MSA) that defines the tenant's entitlements, obligations, and feature scope; structured in Module 8 as `tenant_contract_terms_jsonb` and gates feature flags. |
| Data residency | The geographic region in which a tenant's content data is stored at rest. Launch options: US, EU, India. Cross-region replication is for backup / DR only. |
| Entitlement | A per-tenant capability driven by contract terms; examples include `clinical_phase_1_activation_eligible`, `cross_tenant_collaboration_eligible`, `max_user_count`, `max_concurrent_studies`. |
| executive authority co-sign | An additional electronic signature by the executive authority required for tenant activation, return-to-active from suspension, and offboarding completion; a platform-level governance gate beyond the tenant administrator's own signatures. |
| KYC | Know-your-customer; the verification process that confirms the tenant's legal entity, beneficial ownership, sanctions status, and pharma-specific licence portfolio. |
| Lead tenant | In a cross-tenant study (URS-07), the tenant that owns the study record and the regulatory accountability; per URS-07 DEC-07-07. |
| Master services agreement (MSA) | The signed contract between Verixa and the tenant that defines the tenant's commercial and operational relationship; required as part of `in_setup → active`. |
| Pharma-licence verification | The onboarding step that confirms the tenant holds the regulatory licence appropriate to its asserted activities (e.g., FDA establishment registration, EMA marketing authorisation, CDSCO licence). Required before `pending → in_setup`. |
| Residency-change migration | A controlled migration path that moves a tenant's content data from one residency region to another. Major event; requires executive authority approval, minimum 30-day customer preparation, separate validation pack. |
| Sanctions screening | The onboarding check against US OFAC, EU sanctions lists, UK HM Treasury sanctions, India OFAC equivalent, and the UN Security Council consolidated list. |
| Suspended state | Tenant is operationally paused; mutations blocked; reads continue for inspection / audit surface; cross-tenant partner access suspended in lockstep. |
| Suspension reason | Categorised reason for suspension: `payment_default`, `regulatory_concern`, `security_incident`, `customer_requested`. Each carries a different reversibility profile and Founder-approval gate. |
| Tenant | The customer organisation that uses Verixa; the unit of data isolation, billing, regulatory accountability, and contractual relationship. |
| Tenant administrator | The user with `tenant_admin_authority` Authority Profile; performs in-tenant management actions; cannot complete activation, suspension, or offboarding alone (executive authority co-sign required). |

### 0.7 Module 8 architectural picture

```mermaid
graph LR
  subgraph M8 [Module 8 — Tenant Management]
    REC[Tenant Record]
    LCY[Tenant Lifecycle]
    KYC[Onboarding + KYC]
    RES[Data Residency]
    ENT[Entitlements / Feature Gating]
    CONFIG[Tenant Configuration]
    EXP[Offboarding Export]
  end

  M1[URS-01 Auth] --> KYC
  M4[URS-04 Workflow / E-Sign] --> LCY
  M5[URS-05 Authority] --> KYC
  M6[URS-06 Audit Substrate] --> LCY
  M7[URS-07 Study] --> ENT
  M12[URS-12 Document Control] --> KYC
  M30[URS-30 Notifications] --> LCY
  M35[URS-35 Storage / Backup / Cold] <--> RES
  ENT --> ALL[All other modules consume tenant entitlements]
  LCY --> M6
  EXP --> M6
```

Diagram 0.7-A — Module 8 sits at the foundation: every other Verixa module's tenant scope, residency, entitlements, and access posture flows from this module. URS-06 receives the `CHAIN_GENESIS` event at tenant record creation (`pending` state — sequence 1, so every pre-activation event is also chained) and `TENANT_CHAINS_SEALED_AT_OFFBOARDING` at offboarding. URS-35 owns the residency-scoped storage. URS-12 holds the onboarding documents (signed MSA, signed DPA, licence verification packs, KYC pack).

---

## 1. Module Purpose

Module 8 establishes Tenant Management / Tenant Lifecycle as the foundation substrate of Verixa. It owns the canonical tenant identity, the tenant onboarding workflow with legal-entity verification, pharma-specific licence verification, sanctions screening, and beneficial-ownership disclosure; the tenant lifecycle state machine (`pending → in_setup → active → suspended → in_offboarding → offboarded`); the data residency selection and migration path; the regulatory framework defaults seeded into Module 7 at activation; the retention defaults seeded into URS-06 at activation; the contract terms / entitlements / feature gating that drive every other module's per-tenant capability set; the tenant suspension model with categorised reasons and executive-authority-controlled return-to-active; the offboarding workflow with comprehensive data export and URS-06 chain sealing; the controlled migration paths (residency change, platform version migration); and the cross-tenant collaboration prerequisite consumed by URS-07.

Module 8 is consumed by every other Verixa module as the source of truth for "is this tenant operational right now?" If Module 8 says the tenant is anything other than `active`, mutations across the platform are blocked at the tenant hook (URS-02 §6.4 / URS-04 §6.7). Module 8's correctness is existential to data isolation, residency, accountability, and regulatory acceptability of the platform.

---

## 2. Scope

### 2.1 In scope

- The canonical tenant record per DEC-08-01: `id`, `legal_name`, `display_name`, `legal_entity_jurisdiction`, `legal_entity_registration_number`, `pharma_licences_jsonb` (array of verified licences with type, jurisdiction, number, expiry, evidence reference), `beneficial_ownership_jsonb`, `sanctions_screening_jsonb` (last screening date, providers used, verdict), `data_residency_region`, `regulatory_framework_defaults_jsonb`, `retention_defaults_jsonb`, `tenant_contract_terms_jsonb`, `entitlements_jsonb`, `lifecycle_state`, `created_at`, `activated_at`, `suspended_at`, `offboarding_initiated_at`, `offboarded_at`, `created_by_platform_user_id`, `tenant_administrator_user_id` (the initial admin), `executive_authority_signed_e_sig_id_at_activation`.
- The tenant lifecycle state machine (DEC-08-02): `pending`, `in_setup`, `active`, `suspended`, `in_offboarding`, `offboarded`, plus terminal pre-activation states `rejected` and `withdrawn`.
- Onboarding workflow with seven prerequisites (DEC-08-03): (1) legal-entity verification, (2) pharma-specific licence verification, (3) signed MSA, (4) signed DPA (Data Processing Agreement), (5) data residency selection, (6) regulatory framework defaults, (7) initial tenant administrator. All seven MUST be satisfied before activation; missing any returns `ONBOARDING_PREREQUISITE_NOT_SATISFIED`.
- executive authority co-sign at activation, at every return-to-active from suspension, and at offboarding completion (DEC-08-04).
- Data residency at launch: `us` (US-East), `eu` (EU-Frankfurt), `in` (India-Mumbai); forward roadmap `uk`, `ca` (DEC-08-05). Cross-region replication for backup / DR only; URS-35 owns the storage infrastructure.
- Tenant suspension model (DEC-08-06): four categorised suspension reasons (`payment_default`, `regulatory_concern`, `security_incident`, `customer_requested`) each with documented reversibility profile and Founder-approval gate; suspension blocks mutations across all modules; reads continue for audit / inspection surface; cross-tenant partners suspended in lockstep.
- Offboarding workflow (DEC-08-07): tenant request OR Verixa-initiated offboarding (after prolonged suspension or contract termination); comprehensive data export bundle (every audit row, every regulated record, every controlled document, snapshot chains, integrity manifest); both-side electronic signature; URS-06 chain sealing per URS-06 BR-06-17; tenant retains read-only export access for the contractual window (default 7 years; tenant-configurable upward).
- Pre-offboarding cross-module gate (DEC-08-08): offboarding is blocked while open studies exist where this tenant is the lead-tenant (URS-07 BR-07-18) OR open cross-tenant collaboration grants where this tenant is the lead OR open authority delegations crossing tenant boundary; remediation list is surfaced.
- Contract terms / entitlements / feature gating (DEC-08-09): per-tenant capability flags driven by contract terms; canonical entitlement keys at launch include `clinical_phase_1_activation_eligible`, `clinical_phase_2_activation_eligible`, `clinical_phase_3_activation_eligible`, `cross_tenant_collaboration_eligible`, `max_user_count`, `max_concurrent_studies`, `data_residency_change_eligible`, `controlled_substance_handling_eligible`, `gxp_module_set_jsonb` (the modules the tenant has contracted for: GMP / GLP / GCP / GVP / GDP).
- Residency-change migration path (DEC-08-10): controlled migration with Founder approval, minimum 30-day customer preparation, separate validation pack, dual-residency operation during cutover, integrity verification at both source and destination, customer notification per privacy policy.
- Sub-tenant / business unit hierarchy (DEC-08-11): forward roadmap; not in launch scope. Tenants with multiple business units operate in a single tenant in launch; per-business-unit scope is achieved through URS-05 scope dimensions (`business_unit`).
- Cross-tenant collaboration prerequisite consumed by URS-07: both tenants MUST be in `active` state at grant proposal, grant acceptance, and at every cross-tenant access; suspension cascades automatically.
- Executive-authority-explicit-review high-risk vertical list (DEC-08-12): cell and gene therapy manufacturers, sterile injectables, compounding pharmacies, clinical-trial sponsors, controlled-substance manufacturers, infant formula, vaccines. These tenants require explicit executive authority review at activation beyond the standard executive authority co-sign.
- Tenant onboarding artifacts retained in URS-12 (DEC-08-13): signed MSA, signed DPA (Data Processing Agreement), legal-entity verification pack, pharma-licence verification pack, KYC pack including beneficial ownership disclosure, sanctions-screening evidence, executive authority activation review memo. Retention 25 years for activation pack, 7 years post-offboarding for operational documents.
- Tenant configuration surfaces: per-tenant administrative pages for residency review (read-only post-activation), regulatory framework defaults, retention defaults, entitlement view, suspension status, offboarding initiation.
- Reports and dashboards: tenant catalogue (platform-administrator), tenant lifecycle status, suspension register, offboarding register, residency-distribution dashboard, entitlement utilisation dashboard, KYC re-verification register (per DEC-08-14).
- Front-end: platform-administrator tenant catalogue and onboarding wizard, per-tenant administrative configuration surface, suspension surface, offboarding surface, residency-change request surface.
- Cross-module wiring: every URS-01..URS-35 module consumes the tenant lifecycle state through the tenant hook; URS-06 receives `CHAIN_GENESIS` at tenant record creation (`pending` state — sequence 1) and `TENANT_CHAINS_SEALED_AT_OFFBOARDING` at offboarding; URS-07 consumes the `active` prerequisite for cross-tenant collaboration; URS-12 stores the onboarding documents; URS-30 delivers notifications; URS-35 owns residency-scoped storage and backup / DR.

### 2.2 Out of scope

- Authentication, multi-factor authentication, password policy, session lifecycle (URS-01).
- Permission matrix and base role catalogue (URS-02).
- Active context and approval-scope check (URS-03).
- Workflow templates, runtime, e-signature ceremony, HITL lifecycle (URS-04).
- Authority Profile catalogue, assignments, delegations, SoD (URS-05; Module 8 seeds the tenant's catalogue at activation).
- Audit substrate (URS-06; Module 8 is a major writer of lifecycle events).
- Study management (URS-07; Module 8 gates cross-tenant collaboration).
- Master data CRUD for sites, products, studies, suppliers (URS-09 / URS-10 / URS-11).
- Document control implementation (URS-12; Module 8 stores onboarding documents through URS-12).
- Domain-specific record semantics (every domain module owns its own state model).
- Storage infrastructure (URS-35 owns the residency-scoped object store, replication, backup, restore).
- Billing and payments processing (out of platform scope; Module 8 receives `payment_default` events from external billing system as a suspension trigger).
- AI-driven decision-making (explicitly prohibited; AI suggestion paths are advisory only).

### 2.3 Closed launch decisions

| Identifier | Closed launch decision |
|---|---|
| DEC-08-01 | The tenant record schema is fixed at launch and immutable through Class 1 change governance: the field set listed in §2.1 first paragraph is the launch schema. Adding a column is a Class 1 change. |
| DEC-08-02 | Tenant lifecycle states are exactly eight values: six operational (`pending`, `in_setup`, `active`, `suspended`, `in_offboarding`, `offboarded`) plus two terminal pre-activation states (`rejected`, `withdrawn`). Allowed transitions: `pending → in_setup → active → suspended ↔ active → in_offboarding → offboarded`; `suspended → in_offboarding`; `pending → rejected`; `in_setup → withdrawn`; `offboarded → [terminal]`. All other transitions are forbidden. `offboarded → active` is forbidden (a re-engaged former tenant onboards as a new tenant with a successor reference). |
| DEC-08-03 | Onboarding has seven prerequisites; ALL MUST be satisfied before `in_setup → active`: (1) legal-entity verification confirms the tenant's legal registration in its primary jurisdiction; (2) pharma-specific licence verification confirms the tenant holds the regulatory licence appropriate to its asserted activities; (3) signed master services agreement is linked in URS-12; (4) signed Data Processing Agreement (DPA) is linked in URS-12, with controller / processor terms, cross-border transfer authorisations (Standard Contractual Clauses for EU export, equivalent mechanisms for other regions), and `legal_dpo_authority` co-sign; (5) data residency selected from the launch options; (6) regulatory framework defaults set per Module 7 DEC-07-11; (7) initial tenant administrator user is appointed and has acknowledged onboarding terms with electronic signature. Missing any prerequisite returns `ONBOARDING_PREREQUISITE_NOT_SATISFIED` with the specific missing item. |
| DEC-08-04 | executive authority co-sign is mandatory at three lifecycle transitions: `in_setup → active` (tenant activation), `suspended → active` (return-to-active from suspension), and `in_offboarding → offboarded` (offboarding completion). The Founder signature is recorded in `executive_authority_signed_e_sig_id_at_activation`, `executive_authority_signed_e_sig_id_at_return_to_active` (per occurrence), and `executive_authority_signed_e_sig_id_at_offboarding`. Multi-factor step-up is required for every executive authority co-sign. |
| DEC-08-05 | Data residency options at launch are exactly three: `us` (US-East), `eu` (EU-Frankfurt), `in` (India-Mumbai). Forward roadmap adds `uk` and `ca` per Founder activation. Cross-region replication is permitted only for backup and disaster recovery per URS-35; active read / write traffic stays within the selected region. The tenant's residency MUST be selected at `pending → in_setup`; changes after activation use the residency-change migration path (DEC-08-10). |
| DEC-08-06 | Tenant suspension model: four categorised reasons each with documented reversibility profile. (a) `payment_default`: triggered by external billing event; auto-reversible after payment receipt; executive authority co-sign required at return-to-active beyond the auto-reverse (e.g., for repeat defaults). (b) `regulatory_concern`: tenant has lost a required licence, is under enforcement action, or has been notified of a material regulatory finding; reversible only after executive authority review of the resolution evidence; mandatory executive authority co-sign. (c) `security_incident`: tenant account compromised or platform-side incident affecting tenant; reversible only after Information Security Lead + executive authority co-sign with the post-incident report. (d) `customer_requested`: tenant has asked for an operational pause; reversible at customer request with tenant-administrator + executive authority co-sign. While suspended, mutations across all modules are blocked; reads continue for audit / inspection surface; cross-tenant partner access is suspended in lockstep. |
| DEC-08-07 | Offboarding workflow: tenant request OR Verixa-initiated (after prolonged suspension > 90 days OR contract termination). The offboarding sequence is: (1) initiate offboarding (state `in_offboarding`); (2) cross-module gate check per DEC-08-08; (3) comprehensive data export bundle composed (every audit row, every regulated record, every controlled document, snapshot chains, integrity manifest); (4) tenant administrator electronically signs export receipt; (5) Verixa platform administrator electronically signs export issuance; (6) executive authority co-sign at offboarding completion; (7) URS-06 emits `TENANT_CHAINS_SEALED_AT_OFFBOARDING` (per URS-06 BR-06-17); state moves to `offboarded`. The tenant retains read-only export access for the contractual window (default 7 years; tenant-configurable upward at MSA negotiation). Verixa retains the chains for the regulatory minimum (per URS-06 retention class) but cannot access tenant content for any purpose other than legal / regulatory mandate. |
| DEC-08-08 | Pre-offboarding cross-module gate blocks `active → in_offboarding` (and `suspended → in_offboarding`) while ANY of the following remain open: (a) lead-tenant active studies in URS-07 (BR-07-18); (b) lead-tenant active cross-tenant collaboration grants in URS-07 (DEC-07-07); (c) authority delegations crossing tenant boundary where this tenant is the delegator OR delegate, per URS-05 BR-05-15 cascade; (d) open critical findings on regulated records that the tenant is named as accountable for in URS-12..URS-34. Each blocker returns one of `OFFBOARDING_BLOCKED_BY_OPEN_STUDIES`, `OFFBOARDING_BLOCKED_BY_ACTIVE_COLLABORATIONS`, `OFFBOARDING_BLOCKED_BY_OPEN_DELEGATIONS`, or `OFFBOARDING_BLOCKED_BY_OPEN_FINDINGS` per blocker category, with the remediation list surfaced; tenant resolves before retrying. |
| DEC-08-09 | Tenant entitlements / feature gating: the canonical entitlement registry at launch includes `clinical_phase_1_activation_eligible`, `clinical_phase_2_activation_eligible`, `clinical_phase_3_activation_eligible`, `cross_tenant_collaboration_eligible`, `max_user_count`, `max_concurrent_studies`, `data_residency_change_eligible`, `controlled_substance_handling_eligible`, `gxp_module_set_jsonb` (subset of `gmp` / `glp` / `gcp` / `gvp` / `gdp`). Entitlements are set at activation from `tenant_contract_terms_jsonb` and changed only through controlled MSA amendment (signed by both tenant and Verixa platform administrator + executive authority co-sign for high-risk entitlements like clinical activation). Adding an entitlement key to the registry is a Class 1 change. |
| DEC-08-10 | Residency-change migration path: tenant administrator requests a residency change; the request requires executive authority approval; minimum 30-day customer preparation window between approval and cutover; URS-35 performs dual-residency operation during cutover (writes mirrored to both regions; reads served from source until cutover); cutover requires platform-administrator + executive authority co-sign; integrity verification runs at both source and destination on every chain (every URS-06 chain HEAD must match across regions before cutover); customer notification per privacy policy. The migration is itself a separately validated pack with Class 1 change governance. Residency change is forbidden during `suspended` state. |
| DEC-08-11 | Sub-tenant / business unit hierarchy is **forward roadmap**, not in launch scope. Tenants with multiple business units operate within a single tenant; per-business-unit scope is achieved via URS-05 §6.2.1 `business_unit` scope dimension. Adding a sub-tenant model is a Class 1 change with full validation pack. |
| DEC-08-12 | Executive-authority-explicit-review high-risk vertical list at launch: `cell_and_gene_therapy`, `sterile_injectables`, `compounding_pharmacy`, `clinical_trial_sponsor`, `controlled_substance_manufacturer`, `infant_formula`, `vaccine_manufacturer`. Tenants whose declared posture intersects this list require explicit executive authority review at activation beyond the standard executive authority co-sign — typically including a executive-authority-led readiness call, a documented vertical-specific risk register, and an explicit acceptance memo stored in URS-12. The list is platform-managed; adding to the list is a Class 2 change. |
| DEC-08-13 | Tenant onboarding artifacts retained in URS-12: signed MSA, signed DPA, legal-entity verification pack, pharma-licence verification pack (per licence type), KYC pack including beneficial-ownership disclosure, sanctions-screening evidence (with provider attribution and timestamp), executive authority activation review memo, vertical-specific risk register (where applicable per DEC-08-12), data residency selection memo, regulatory framework defaults memo. Retention: 25 years for activation pack components (MSA, DPA, KYC, executive authority memo); 7 years post-offboarding for operational documents. The retention is enforced by URS-06 retention class assigned at document linkage. |
| DEC-08-14 | KYC re-verification cadence: pharma-licence verification re-runs annually per tenant; sanctions screening re-runs quarterly per tenant; beneficial ownership disclosure refresh annually OR on customer-initiated material change. Re-verification runs are scheduled by URS-30; failures trigger `regulatory_concern` suspension after a configurable grace window (default 30 days from licence expiry, immediate from sanctions hit). |
| DEC-08-15 | Offboarding data export contract: the export bundle includes (a) every audit row from every URS-06 chain owned by the tenant, with integrity manifest including Merkle proofs to per-tenant root and global anchor (per URS-06 BR-06-10), (b) every regulated record from every URS-12..URS-34 module owned by the tenant, (c) every controlled document, (d) all `electronic_signatures` and `approval_authority_snapshots` linked to the tenant, (e) the URS-06 chain HEAD hashes at sealing, (f) the platform-published external anchor manifest covering the tenant's last anchor cycle. Format: PDF readable summary + JSON machine-readable bundle + binary attachments where applicable. Bundle is electronically signed by both tenant administrator and Verixa platform administrator + executive authority co-sign per DEC-08-04. Signed download URL with extended TTL (24 hours; longer than standard exports) given the bundle size. |
| DEC-08-16 | Verixa post-offboarding access posture: after `offboarded` state, Verixa MUST NOT access tenant content data for any purpose other than (a) legal / regulatory mandate (court order, regulatory inspection request), (b) the tenant's own re-engagement with the export read access surface, (c) URS-06 integrity verification on the sealed chains (no content access; only chain hashes). Every access by Verixa post-offboarding is itself audited as `OFFBOARDED_TENANT_DATA_ACCESS` and reported to the former tenant within the contractual window via URS-30. Internal Verixa access to offboarded tenant content is prohibited by access-control posture; only the platform Information Security Lead + executive authority can authorise such access for a documented legal / regulatory purpose. |
| DEC-08-17 | Cross-tenant collaboration cascade: when a tenant moves out of `active` (suspended OR in_offboarding OR offboarded), every cross-tenant collaboration grant where this tenant is the lead OR partner is automatically suspended in lockstep; affected partner-tenant access is removed; URS-30 notifies both tenants. When the tenant returns to `active` (only from `suspended`), suspended collaboration grants resume; if the tenant is offboarded, the grants are revoked. Cross-tenant authority delegations cascade similarly per URS-05 BR-05-15 / URS-07 BR-07-09. |
| DEC-08-18 | Tenant lifecycle events emit a comprehensive audit row in BOTH (a) the tenant's own per-tenant URS-06 chain (created at tenant record creation, entering `pending` state — sequence 1, so every pre-activation lifecycle event is captured) and (b) the URS-06 global chain (because tenant lifecycle is a platform-level event affecting the global posture). Bidirectional reference is preserved per URS-06 DEC-06-18. |
| DEC-08-19 | Tenant identity verification (KYC) at onboarding uses three independent providers at minimum: a legal-entity registry verification provider (e.g., DataCompliance, KYC-Chain), a sanctions-screening provider (e.g., World-Check, Dow Jones Risk and Compliance, Refinitiv), and a pharma-licence verification provider OR direct integration with the regulatory authority's public verification surface where available (FDA Establishment Registration query, UK MHRA wholesale dealers register, India CDSCO licence database where accessible). Provider qualification per URS-08 §17.1. Three independent providers reduce single-provider reliance risk for onboarding decisions. |

---

## 3. User Roles and Permissions

### 3.1 Architecture

Module 8 is operated primarily by **platform identities** (`platform_admin`, `super_admin`) on the Verixa platform side and by `tenant_admin_authority` holders on the tenant side, with **executive authority co-sign** at the three lifecycle gates per DEC-08-04. There is no `viewer` / `reviewer` / `quality_lead` access to Module 8 administrative surfaces; tenant-level read access is restricted to `tenant_admin_authority` and `auditor` roles. Module 8 owns three administrative surfaces: (a) the platform-administrator tenant catalogue and onboarding wizard, (b) the per-tenant administrative configuration surface, (c) the executive authority co-sign queue. Module 8 also owns the read-only **tenant identity** surface that consuming modules query at every action.

### 3.2 Role definitions

The five tenant-level base roles defined by URS-02 (`admin`, `quality_lead`, `reviewer`, `auditor`, `viewer`) and the two cross-tenant platform identities (`platform_admin`, `super_admin`) apply unchanged. Module 8 introduces one additional role contour at the platform level:

| Platform role | Description | Cardinality |
|---|---|---|
| `platform_tenant_onboarding_specialist` | A platform-administrator restricted to tenant-onboarding operations (cannot perform other platform-administrator actions); used to scope third-party onboarding teams or contracted KYC operators. | 0 or more (optional) |

The executive authority is treated as a distinct role in Module 8 per DEC-08-04; the executive authority identity is established in URS-01 and the executive authority co-sign Authority Profile per URS-05 §3.3.

### 3.3 Authority Profiles consumed by Module 8

| Authority Profile (consumed) | Module 8 action gated |
|---|---|
| `tenant_admin_authority` | In-tenant configuration: regulatory framework defaults, retention defaults, residency-change request, suspension acknowledgement, offboarding initiation. |
| `cross_tenant_collaboration_authority` | Sign cross-tenant collaboration acceptance (per Module 7); Module 8 verifies prerequisite. |
| Executive-authority-level authority (`executive_authority`) | Co-sign tenant activation, return-to-active from suspension, offboarding completion, residency-change cutover, clinical-type entitlement, high-risk vertical activation memo. |
| Platform-administrator identity | Tenant onboarding workflow operation, suspension issuance / management, offboarding execution, KYC re-verification, residency-change orchestration. |
| `regulatory_oversight_admin` | Co-sign regulatory-concern suspension and return-to-active when a regulatory licence event drives the suspension. |
| `information_security_lead_authority` | Co-sign security-incident suspension and return-to-active. |
| `legal_dpo_authority` | Co-sign DPA terms at onboarding, GDPR / DPDP cross-border transfer attestations during residency-change migration, post-offboarding data-access authorisations. |

### 3.4 Segregation-of-Duties rules consumed by Module 8

| SoD rule (consumed from URS-05) | Module 8 application |
|---|---|
| `AUTHOR_NEQ_APPROVER` | The platform user who initiated an onboarding cannot also be the executive authority co-signer (executive authority is a distinct role; SoD is satisfied by role separation). |
| `REVIEWER_NEQ_FINAL_APPROVER` | The platform user who reviewed a KYC pack cannot also be the platform administrator who issues the activation. |
| `TENANT_ACTIVATION_DUAL_PLATFORM_SIGNATURE` (Tier 1, Module 8 specific) | Tenant activation requires two distinct platform-administrator signatures (initiating and approving) in addition to executive authority co-sign — three independent signatures total at activation. |
| `OFFBOARDING_DUAL_SIGNATURE_BOTH_SIDES` (Tier 1, Module 8 specific) | Offboarding completion requires the tenant administrator's electronic signature (acceptance of the export bundle) AND the Verixa platform administrator's signature (issuance) AND the executive authority co-sign. |

### 3.5 Worked examples

#### Worked example A — Pharmaceutical manufacturer onboarding

PharmaCorp Inc., a US-based generic-drug manufacturer, requests onboarding through the Verixa sales process. The Verixa platform-tenant-onboarding-specialist creates the tenant record (state `pending`; URS-06 per-tenant chain genesis is emitted at this point — sequence 1 — so every pre-activation lifecycle event is captured); initiates legal-entity verification through a third-party provider, which confirms the Delaware C-corp registration; queries the FDA Establishment Registration database, which confirms PharmaCorp's manufacturing-establishment registration is current; runs sanctions screening through World-Check, no hits; obtains beneficial-ownership disclosure from PharmaCorp's General Counsel covering all 25%+ owners; reviews the KYC pack. The Verixa platform legal lead confirms the signed MSA and signed DPA. The platform-administrator initiates `pending → in_setup` (state moves; tenant administrator from PharmaCorp is named; the transition is appended to the existing tenant chain). PharmaCorp's tenant administrator (a QA Director appointed in the MSA) authenticates, electronically acknowledges onboarding terms, configures data residency (selects `us`), configures regulatory framework defaults (`['21_cfr_part_211', 'fda_csa', 'ich_q9', 'ich_q10']`), seeds Tier 2 catalogue (no Tier 2 entries at first; deferred), and submits the tenant for activation. Two distinct platform administrators sign activation independently (per `TENANT_ACTIVATION_DUAL_PLATFORM_SIGNATURE`); the executive authority receives the activation request via URS-30, opens the activation surface, reviews the executive authority activation review memo, electronically co-signs with multi-factor step-up. URS-06 emits `TENANT_ACTIVATED` into the existing tenant chain (no second genesis row is created), the tenant moves to `active`. PharmaCorp can now create studies, sign regulated decisions, invite users, etc.

#### Worked example B — Cell-and-gene therapy tenant requires Founder explicit review

GeneTechPharma is a cell-and-gene therapy manufacturer. Their declared posture intersects the Executive-authority-explicit-review high-risk vertical list (DEC-08-12). Beyond the standard executive authority co-sign, the executive authority leads a 90-minute readiness call covering GeneTechPharma's contamination control strategy, their adventitious-agent testing programme, their EU GMP Annex 1 (revised) readiness, their deviation-investigation maturity, and their leadership team's QA experience. The Executive authority authors the documented vertical-specific risk register and the explicit acceptance memo (stored in URS-12). Only after this pack is complete does the executive authority co-sign activation. The vertical-specific risk register is then re-visited at every annual KYC re-verification.

#### Worked example C — Tenant suspension for regulatory concern

Mid-2026, PharmaCorp receives an FDA Form 483 with serious observations from a routine inspection. The platform's monitoring system detects this through the FDA establishment registration data feed; emits a `regulatory_concern` suspension event to Module 8. The Verixa platform Information Security Lead and Regulatory Affairs Lead jointly review and confirm the suspension is warranted; the platform administrator issues the suspension with reason `regulatory_concern` and a 30-day grace window (during which PharmaCorp can submit a corrective response). The tenant moves to `suspended`; mutations across PharmaCorp's tenant blocked; reads continue for the inspection / audit surface; cross-tenant collaboration where PharmaCorp is partner is suspended in lockstep. Three weeks later, PharmaCorp submits a comprehensive corrective response with documented root-cause analysis and CAPA plan; the FDA acknowledges the response. PharmaCorp's tenant administrator opens the return-to-active surface; provides the FDA acknowledgement; URS-30 notifies the executive authority; the executive authority reviews; co-signs return-to-active with `regulatory_oversight_admin` co-sign; tenant returns to `active`. Cross-tenant grants resume.

#### Worked example D — Tenant offboarding (customer-initiated)

After three years on the platform, BiotechMicro decides to migrate to an alternative QMS provider. Their tenant administrator initiates offboarding through the offboarding surface; provides the contract-termination notice (90 days per their MSA). Module 8 runs the pre-offboarding cross-module gate: BiotechMicro has zero open lead-tenant studies (good); zero open cross-tenant collaboration grants (good); zero open cross-tenant authority delegations (good); two open critical findings on regulated records (blocker). Module 8 surfaces the remediation list; BiotechMicro closes the two findings. The gate clears; offboarding proceeds. Verixa composes the comprehensive data export bundle: 47,000 audit rows, 2,300 regulated records, 890 controlled documents, all snapshot chains, integrity manifest with Merkle proofs to the per-tenant root and the global anchor. BiotechMicro's tenant administrator signs export receipt; Verixa platform administrator signs issuance; the executive authority co-signs offboarding completion. URS-06 publishes the final external anchor on BiotechMicro's per-tenant chain; emits `TENANT_CHAINS_SEALED_AT_OFFBOARDING`; the tenant's chains are sealed. BiotechMicro retains read-only export access for the contractual 7-year window. Verixa retains the chains for 25 years for authority snapshots, 7 years for general audit; cannot access tenant content except for legal mandate.

#### Worked example E — Residency-change migration

LatinPharma operates from `us` residency at activation. After year two, EU regulatory updates require LatinPharma to maintain EU-resident records for their EMA-authorised product line. Their tenant administrator requests a residency change to `eu`; the request is reviewed by the executive authority; approval granted. The 30-day customer preparation window begins (LatinPharma updates internal documentation, retrains staff on the new region's residency posture). At cutover, URS-35 has been operating dual-residency for the prep window with writes mirrored to both regions; integrity verification at both regions confirms every URS-06 chain HEAD matches; platform administrator and executive authority co-sign cutover; reads switch from `us` to `eu`. LatinPharma is notified; URS-30 emits to all members of LatinPharma's tenant; URS-06 captures the migration. Customer notification per privacy policy goes out within 24 hours.

#### Worked example F — Pre-offboarding gate blocked by open studies

ContractPharma decides to terminate their Verixa contract. Their tenant administrator initiates offboarding. The pre-offboarding gate fails: ContractPharma has 14 open lead-tenant studies (per URS-07 BR-07-18); 3 active cross-tenant collaboration grants where ContractPharma is the lead. The gate returns `OFFBOARDING_BLOCKED_BY_OPEN_STUDIES`, `OFFBOARDING_BLOCKED_BY_ACTIVE_COLLABORATIONS`. ContractPharma must resolve each: complete or formally close the 14 studies (URS-07 close-out flow), revoke the 3 collaboration grants. Only after every blocker clears does Module 8 permit `active → in_offboarding`.

#### Worked example G — Suspension cascade to cross-tenant collaboration

SponsorPharma (lead tenant in a clinical-trial collaboration) goes into `suspended` state due to a security incident. Per DEC-08-17, the cross-tenant collaboration with CROServices is automatically suspended in lockstep. CROServices receives a URS-30 notification explaining the suspension and the cross-tenant impact; CROServices' access to SponsorPharma's study scope is removed; CROServices' active study contributions are paused (cannot mutate within the collaboration scope). SponsorPharma's security incident is resolved after two days; Information Security Lead + executive authority co-sign return-to-active; SponsorPharma's tenant returns to `active`; the cross-tenant collaboration with CROServices automatically resumes.

#### Worked example H — KYC re-verification finding licence expiry

Annual pharma-licence re-verification runs for ManufactureCorp. The provider returns `licence_expired` for ManufactureCorp's CDSCO drug-manufacturing licence (was due to renew on 2026-08-15; current date 2026-09-12). URS-30 alerts the platform RA Lead and executive authority. The platform issues a `regulatory_concern` suspension with a 30-day grace window. ManufactureCorp's tenant administrator submits the renewed licence within 5 days; KYC re-verification provider confirms the new licence; suspension is lifted with `regulatory_oversight_admin` + executive authority co-sign; tenant returns to `active`.

### 3.6 Role-permission matrix (Module 8 administrative surface only)

| Action (within Module 8) | viewer | reviewer | quality_lead | auditor | admin | platform_admin | super_admin | Founder | Authority Profile |
|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|---|
| Read tenant identity (own tenant) | — | — | — | ✓ | ✓ | ✓ | ✓ | ✓ | `tenant_admin_authority` / `auditor` |
| Read platform tenant catalogue | — | — | — | — | — | ✓ | ✓ | ✓ | platform identity |
| Initiate tenant onboarding | — | — | — | — | — | ✓ + sign | ✓ + sign | — | platform identity |
| Issue legal-entity verification request | — | — | — | — | — | ✓ | ✓ | — | platform identity |
| Issue pharma-licence verification request | — | — | — | — | — | ✓ | ✓ | — | platform identity |
| Issue sanctions screening | — | — | — | — | — | ✓ | ✓ | — | platform identity |
| Configure tenant residency (during in_setup only) | — | — | — | — | ✓ + sign | ✓ + sign | ✓ + sign | — | `tenant_admin_authority` |
| Configure regulatory framework defaults (during in_setup) | — | — | — | — | ✓ + sign | ✓ + sign | ✓ + sign | — | `tenant_admin_authority` |
| Sign onboarding terms acknowledgement (initial admin) | — | — | — | — | ✓ + sign | — | — | — | initial admin |
| Sign tenant activation (platform side, initiating) | — | — | — | — | — | ✓ + sign + MFA | ✓ + sign + MFA | — | platform identity |
| Sign tenant activation (platform side, approving) | — | — | — | — | — | ✓ + sign + MFA (different user) | ✓ + sign + MFA (different user) | — | platform identity |
| Sign tenant activation (executive authority co-sign) | — | — | — | — | — | — | — | ✓ + sign + MFA | Founder |
| Issue tenant suspension | — | — | — | — | — | ✓ + sign + MFA + reason category | ✓ + sign + MFA + reason category | — | platform identity (+ regulatory or IS lead per reason) |
| Sign return-to-active from suspension | — | — | — | — | — | ✓ + sign + MFA | ✓ + sign + MFA | ✓ + sign + MFA (executive authority co-sign) | platform identity + executive authority; per reason: + RA / IS lead |
| Initiate offboarding (tenant side) | — | — | — | — | ✓ + sign + MFA | — | — | — | `tenant_admin_authority` |
| Initiate offboarding (Verixa side, after prolonged suspension) | — | — | — | — | — | ✓ + sign + MFA | ✓ + sign + MFA | — | platform identity |
| Sign offboarding completion (tenant side) | — | — | — | — | ✓ + sign + MFA | — | — | — | `tenant_admin_authority` |
| Sign offboarding completion (platform side) | — | — | — | — | — | ✓ + sign + MFA | ✓ + sign + MFA | — | platform identity |
| Sign offboarding completion (executive authority co-sign) | — | — | — | — | — | — | — | ✓ + sign + MFA | Founder |
| Request residency change | — | — | — | — | ✓ + sign | — | — | — | `tenant_admin_authority` |
| Approve residency change | — | — | — | — | — | — | — | ✓ + sign + MFA | Founder |
| Sign residency-change cutover | — | — | — | — | — | ✓ + sign + MFA | ✓ + sign + MFA | ✓ + sign + MFA (executive authority co-sign) | platform identity + executive authority |
| Modify entitlements (MSA amendment) | — | — | — | — | ✓ + sign | ✓ + sign | ✓ + sign | ✓ + sign for high-risk | `tenant_admin_authority` + platform identity + executive authority for clinical / controlled-substance |
| KYC re-verification trigger | — | — | — | — | — | scheduled / manual ✓ | ✓ | — | platform identity |
| Read suspension register | — | — | — | ✓ | ✓ | ✓ | ✓ | ✓ | `tenant_admin_authority` (own tenant) / platform / Founder |
| Read offboarding register | — | — | — | ✓ | — | ✓ | ✓ | ✓ | platform / Founder |
| Read KYC re-verification register | — | — | — | ✓ | — | ✓ | ✓ | ✓ | platform / Founder |
| Authorise post-offboarding tenant data access (legal mandate) | — | — | — | — | — | — | — | ✓ + sign + IS Lead co-sign | Founder + Information Security Lead |

External identities (URS-01 §3.2.3) cannot reach Module 8 administrative surfaces.

#### 3.6.1 Platform-identity tenant actions — controlled support / break-glass posture

Per URS-02 §3.6.1, platform identities (`platform_admin`, `super_admin`) MAY perform tenant-scoped Module 8 actions only under a controlled support / break-glass posture: target tenant identifier, business-justification reason, support-ticket / customer-reference identifier, electronic signature, `PLATFORM_TENANT_ACCESS_USED` audit emit (URS-06 global chain) plus `PLATFORM_TENANT_ACCESS_NOTIFIED` in the target tenant chain, Security Operations Centre alert, customer notification within 24 hours per privacy policy. Module 8 lifecycle operations (onboarding, suspension, offboarding) are themselves the platform-controlled administrative path and do NOT require break-glass posture; they are the normal platform-administrator flow with their own audit and executive authority co-sign.

---

## 4. End-to-End User Journeys

### J-01 — Tenant onboarding initiated

- Trigger: sales / business-development confirms a new customer; platform-tenant-onboarding-specialist begins onboarding.
- Steps: specialist creates tenant record (state `pending`); initiates legal-entity verification, pharma-licence verification, sanctions screening through three independent providers (DEC-08-19); collects beneficial-ownership disclosure; reviews KYC pack.
- Audit: `TENANT_ONBOARDING_INITIATED` (URS-06 global chain).

### J-02 — Legal-entity and pharma-licence verification

- Trigger: provider responses received.
- Steps: specialist confirms legal entity registration matches MSA party; confirms pharma-licence portfolio aligns with declared posture; logs evidence to URS-12; if all clear, advances toward `pending → in_setup`; if any issue, escalates to platform RA Lead and Legal.
- Audit: `LEGAL_ENTITY_VERIFIED`, `PHARMA_LICENCE_VERIFIED`, `SANCTIONS_SCREENING_PASSED`.

### J-03 — Move to in-setup

- Trigger: all KYC checks passed; signed MSA and DPA confirmed.
- Steps: platform-administrator transitions tenant to `in_setup`; tenant administrator account is provisioned (per URS-01); `TENANT_MOVED_TO_IN_SETUP` is appended to the existing tenant chain (per-tenant chain genesis was already emitted at tenant record creation, entering `pending` state — sequence 1); tenant administrator receives onboarding link.
- Audit: `TENANT_MOVED_TO_IN_SETUP`.

### J-04 — Tenant administrator setup steps

- Trigger: tenant administrator authenticates and opens setup surface.
- Steps: administrator electronically acknowledges onboarding terms; selects data residency from launch options; configures regulatory framework defaults per study type per Module 7 DEC-07-11; configures retention defaults; submits tenant for activation.
- Audit: `TENANT_ADMIN_ACKNOWLEDGED_TERMS`, `TENANT_RESIDENCY_SELECTED`, `TENANT_REGULATORY_FRAMEWORK_DEFAULTS_SET`, `TENANT_SUBMITTED_FOR_ACTIVATION`.

```mermaid
sequenceDiagram
  autonumber
  participant TA as Tenant Administrator
  participant FE as Setup UI
  participant API as Module 8 API
  participant LOG as URS-06 Audit

  TA->>FE: open setup
  TA->>API: POST /tenant/setup/acknowledge-terms (e-sign)
  API->>LOG: TENANT_ADMIN_ACKNOWLEDGED_TERMS
  TA->>API: POST /tenant/setup/residency
  API->>LOG: TENANT_RESIDENCY_SELECTED
  TA->>API: POST /tenant/setup/regulatory-framework-defaults
  API->>LOG: TENANT_REGULATORY_FRAMEWORK_DEFAULTS_SET
  TA->>API: POST /tenant/setup/submit-for-activation (e-sign)
  API->>LOG: TENANT_SUBMITTED_FOR_ACTIVATION
```

### J-05 — Tenant activation (three-signature gate)

- Trigger: tenant submitted for activation.
- Steps: platform administrator A signs initiating activation (with MFA step-up); platform administrator B (different user; per `TENANT_ACTIVATION_DUAL_PLATFORM_SIGNATURE`) signs approving activation; URS-30 routes Founder activation request; Executive authority reviews activation review memo; executive authority co-signs (with MFA step-up); Module 8 emits `TENANT_ACTIVATED` into the existing tenant chain (per-tenant chain genesis was already emitted at `pending` creation — sequence 1; activation MUST NOT create a second genesis row); tenant moves to `active`.
- Audit: `TENANT_ACTIVATION_INITIATED`, `TENANT_ACTIVATION_APPROVED`, `TENANT_ACTIVATED`.

### J-06 — High-risk vertical activation with explicit executive authority review

- Trigger: tenant declared a high-risk vertical (DEC-08-12).
- Steps: standard activation flow plus executive-authority-led readiness call (logged in URS-12 as a meeting record); vertical-specific risk register authored and signed; explicit acceptance memo authored; only after these artifacts are complete does executive authority co-sign.
- Audit: `HIGH_RISK_VERTICAL_REVIEW_LOGGED`, `HIGH_RISK_VERTICAL_RISK_REGISTER_PUBLISHED`, `HIGH_RISK_VERTICAL_ACCEPTANCE_MEMO_PUBLISHED`, then standard `TENANT_ACTIVATED`.

### J-07 — Tenant suspension for regulatory concern

- Trigger: monitoring detects regulatory event (e.g., FDA 483; licence expiry).
- Steps: platform RA Lead reviews; confirms suspension warranted; platform administrator + RA Lead jointly issue suspension with reason `regulatory_concern`; URS-30 notifies tenant administrator; mutations across the tenant blocked; cross-tenant grants suspended in lockstep per DEC-08-17; URS-06 captures.
- Audit: `TENANT_SUSPENSION_ISSUED` with reason category.

### J-08 — Return to active from regulatory-concern suspension

- Trigger: regulatory event resolved.
- Steps: tenant administrator submits resolution evidence (e.g., FDA acknowledgement; renewed licence); platform RA Lead reviews; co-signs with `regulatory_oversight_admin`; Executive authority reviews; co-signs return-to-active with MFA step-up; tenant returns to `active`; cross-tenant grants resume.
- Audit: `TENANT_RETURN_TO_ACTIVE_INITIATED`, `TENANT_RETURNED_TO_ACTIVE`.

### J-09 — Tenant suspension for security incident

- Trigger: SOC detects compromise (account takeover, key exposure, etc.).
- Steps: Information Security Lead reviews; immediate suspension issued with reason `security_incident`; URS-30 notifies tenant administrator + executive authority + Verixa security team; investigation begins.
- Audit: `TENANT_SUSPENSION_ISSUED` with reason `security_incident`.

### J-10 — Return to active from security-incident suspension

- Trigger: investigation closed; remediation complete.
- Steps: Information Security Lead authors post-incident report; reviews remediation evidence (forced password reset, key rotation, MFA enforcement, account audit); co-signs return-to-active with `information_security_lead_authority`; Executive authority reviews; co-signs return-to-active with MFA step-up; tenant returns to `active`.
- Audit: `TENANT_RETURNED_TO_ACTIVE`.

### J-11 — Customer-requested suspension and resumption

- Trigger: tenant has requested an operational pause (e.g., for an internal restructuring).
- Steps: tenant administrator opens suspension surface; provides reason; platform-administrator confirms; suspension issued with reason `customer_requested`; tenant moves to `suspended`. Later, tenant administrator requests resumption; platform-administrator + executive authority co-sign return-to-active; tenant returns to `active`.
- Audit: `TENANT_SUSPENSION_ISSUED`, `TENANT_RETURNED_TO_ACTIVE` (both with reason `customer_requested`).

### J-12 — Suspension cascade to cross-tenant collaboration

- Trigger: tenant moves to `suspended`.
- Steps: Module 8 enumerates all cross-tenant collaboration grants where this tenant is lead OR partner; suspends each grant in URS-07 in lockstep; partner-tenant access removed; URS-30 notifies both tenants of every affected grant.
- Audit: per-grant `CROSS_TENANT_COLLABORATION_SUSPENDED` (in both tenants' chains).

### J-13 — Suspension cascade resumption on return-to-active

- Trigger: suspended tenant returns to `active`.
- Steps: Module 8 resumes every cross-tenant collaboration grant that was suspended in lockstep with this tenant (provided the partner tenant is also `active`); URS-30 notifies both tenants.
- Audit: per-grant `CROSS_TENANT_COLLABORATION_RESUMED`.

### J-14 — Tenant offboarding initiated by tenant

- Trigger: tenant administrator decides to terminate; provides contract-termination notice.
- Steps: opens offboarding surface; signs initiation; Module 8 runs pre-offboarding cross-module gate per DEC-08-08; if blockers exist, surfaces remediation list; if clear, advances to `in_offboarding`.
- Audit: `TENANT_OFFBOARDING_INITIATED`.

### J-15 — Pre-offboarding gate blocks

- Trigger: open studies or active grants exist.
- Steps: gate returns specific blocker codes; tenant administrator resolves each; retries.
- Audit: `OFFBOARDING_BLOCKED_BY_OPEN_STUDIES` / `OFFBOARDING_BLOCKED_BY_ACTIVE_COLLABORATIONS` / `OFFBOARDING_BLOCKED_BY_OPEN_DELEGATIONS` / `OFFBOARDING_BLOCKED_BY_OPEN_FINDINGS`.

### J-16 — Offboarding data export composition

- Trigger: pre-offboarding gate cleared; tenant in `in_offboarding`.
- Steps: Verixa platform composes the comprehensive export bundle per DEC-08-15 (every audit row, every regulated record, every controlled document, snapshot chains, integrity manifest with Merkle proofs, external anchor manifest); signed download URL with extended TTL (24 hours).
- Audit: `OFFBOARDING_EXPORT_BUNDLE_COMPOSED`.

### J-17 — Offboarding completion (three-signature gate + chain sealing)

- Trigger: export bundle composed.
- Steps: tenant administrator signs export receipt; platform administrator signs export issuance; executive authority co-signs offboarding completion with MFA step-up; URS-06 publishes the final external anchor on the tenant's per-tenant chain; emits `TENANT_CHAINS_SEALED_AT_OFFBOARDING`; chain is sealed; tenant moves to `offboarded`.
- Audit: `OFFBOARDING_EXPORT_RECEIPT_SIGNED`, `OFFBOARDING_EXPORT_ISSUED`, `TENANT_OFFBOARDED`, `TENANT_CHAINS_SEALED_AT_OFFBOARDING`.

```mermaid
flowchart TD
  A[Tenant requests offboarding] --> B[TENANT_OFFBOARDING_INITIATED]
  B --> C[Pre-offboarding gate]
  C --> D{Blockers?}
  D -- yes --> E[Surface remediation list]
  E --> C
  D -- no --> F[State in_offboarding]
  F --> G[Compose comprehensive export bundle]
  G --> H[Tenant administrator signs export receipt]
  H --> I[Platform administrator signs export issuance]
  I --> J[executive authority co-signs offboarding completion]
  J --> K[URS-06 publishes final external anchor; seals chains]
  K --> L[State offboarded]
  L --> M[Tenant retains read-only export access for contractual window]
```

### J-18 — Verixa-initiated offboarding after prolonged suspension

- Trigger: tenant in `suspended` state for > 90 days; reason unresolved; platform legal pursues contract termination.
- Steps: platform legal initiates contract-termination procedure per MSA; once terminated, platform-administrator initiates `suspended → in_offboarding`; standard offboarding flow proceeds (gate, export, chain sealing).
- Audit: `TENANT_OFFBOARDING_INITIATED_BY_PLATFORM`.

### J-19 — Residency-change request

- Trigger: tenant administrator requests residency change (e.g., US → EU due to new regulatory requirement).
- Steps: opens residency-change request surface; provides rationale; signs; URS-30 notifies Founder; Executive authority reviews; approves with MFA step-up.
- Audit: `RESIDENCY_CHANGE_REQUESTED`, `RESIDENCY_CHANGE_APPROVED`.

### J-20 — Residency-change preparation window

- Trigger: residency-change approved.
- Steps: 30-day customer preparation window begins; URS-35 begins dual-residency operation (writes mirrored to both regions); tenant updates internal documentation; URS-30 reminders at T-15, T-7, T-1.
- Audit: `RESIDENCY_CHANGE_DUAL_OPERATION_BEGAN`.

### J-21 — Residency-change cutover

- Trigger: end of preparation window.
- Steps: integrity verification at both regions confirms every URS-06 chain HEAD matches; platform administrator signs cutover with MFA step-up; executive authority co-signs cutover with MFA step-up; URS-35 switches reads from source to destination region; URS-30 notifies tenant; customer notification per privacy policy goes out within 24 hours.
- Audit: `RESIDENCY_CHANGE_CUTOVER_COMPLETED`.

### J-22 — Annual KYC re-verification

- Trigger: scheduled annual job per DEC-08-14.
- Steps: KYC providers re-run pharma-licence verification, beneficial-ownership refresh; sanctions screening re-runs quarterly; results logged; failures escalate per J-07.
- Audit: `KYC_REVERIFICATION_RUN`, `KYC_REVERIFICATION_PASSED` / `KYC_REVERIFICATION_FAILED`.

### J-23 — Sanctions hit triggers immediate suspension

- Trigger: sanctions-screening provider returns hit.
- Steps: platform RA Lead and Information Security Lead review; immediate suspension issued with reason `regulatory_concern`; Founder notified; investigation engaged with legal counsel.
- Audit: `SANCTIONS_HIT_DETECTED`, `TENANT_SUSPENSION_ISSUED`.

### J-24 — Beneficial ownership material change

- Trigger: tenant administrator submits material change in beneficial ownership (e.g., acquisition).
- Steps: platform RA Lead reviews; new owners run through KYC providers; new sanctions screening; if all clear, beneficial-ownership disclosure refreshed; if any concern, escalation per J-23.
- Audit: `BENEFICIAL_OWNERSHIP_REFRESHED` or `BENEFICIAL_OWNERSHIP_REVIEW_ESCALATED`.

### J-25 — Entitlement change (MSA amendment)

- Trigger: tenant requests entitlement change (e.g., enable cross-tenant collaboration eligibility).
- Steps: tenant administrator opens entitlement-change surface; documents requested change; URS-30 routes to Verixa platform legal; if MSA amendment needed (typical), legal drafts and routes for tenant signature; returned signed amendment; platform administrator updates entitlements; executive authority co-sign for high-risk entitlements (clinical activation, controlled-substance handling).
- Audit: `ENTITLEMENT_CHANGE_REQUESTED`, `ENTITLEMENT_AMENDMENT_SIGNED`, `ENTITLEMENTS_UPDATED`.

### J-26 — Post-offboarding tenant export read access

- Trigger: offboarded tenant accesses the export read surface within the contractual window.
- Steps: former tenant administrator authenticates (URS-01 maintains the credentials for the contractual window); opens the read-only export surface; downloads the export bundle (with regenerated signed URL).
- Audit: `OFFBOARDED_TENANT_EXPORT_ACCESS_USED`.

### J-27 — Post-offboarding Verixa access for legal mandate

- Trigger: court order or regulatory inspection request involving an offboarded tenant.
- Steps: Founder + Information Security Lead jointly review the legal mandate; co-sign authorisation; Verixa platform administrator accesses the offboarded tenant's data for the documented purpose; URS-06 emits `OFFBOARDED_TENANT_DATA_ACCESS`; URS-30 reports the access to the former tenant within the contractual window.
- Audit: `OFFBOARDED_TENANT_DATA_ACCESS`.

### J-28 — Auditor reads tenant lifecycle history

- Trigger: regulatory inspection or internal audit.
- Steps: auditor (with `auditor` base role) opens the tenant lifecycle history surface; system returns the full lifecycle event chain from `pending` to current state, with every transition's signatures and audit references; auditor exports through Controlled Approval Modal.
- Audit: `TENANT_LIFECYCLE_HISTORY_EXPORTED`.

---

## 5. Front-End Expected State

### 5.1 Routes

| Route | Surface | Role / Authority gate | Notes |
|---|---|---|---|
| `/platform/tenants` | Platform tenant catalogue | platform identity | filterable by lifecycle state, residency, vertical |
| `/platform/tenants/new` | Onboarding wizard (stage A: pending → in_setup) | platform identity | initiates KYC providers |
| `/platform/tenants/:id` | Per-tenant administrative detail | platform identity / Founder | read; configuration; suspension; offboarding |
| `/platform/tenants/:id/activation` | Activation surface (three-signature gate) | platform identity + executive authority | dual platform sign + executive authority co-sign |
| `/platform/tenants/:id/suspension` | Suspension issuance / management | platform identity | reason category required |
| `/platform/tenants/:id/return-to-active` | Return-to-active surface | platform identity + executive authority + per reason: RA / IS lead | resolution evidence required |
| `/platform/tenants/:id/offboarding` | Offboarding workflow | platform identity + executive authority | gate, export, sealing |
| `/platform/tenants/:id/residency-change` | Residency-change orchestration | platform identity + executive authority | dual-residency operation; cutover |
| `/platform/tenants/:id/kyc-reverification` | KYC re-verification register and triggers | platform identity | scheduled and manual |
| `/platform/tenants/:id/post-offboarded-access` | Post-offboarding legal-mandate access surface | Founder + Information Security Lead | documented purpose required |
| `/admin/tenant/identity` | Per-tenant identity (read-only post-activation) | `tenant_admin_authority` / `auditor` | residency, framework, retention, entitlements |
| `/admin/tenant/configuration` | Per-tenant configuration (during in_setup) | `tenant_admin_authority` | residency, framework defaults, retention defaults |
| `/admin/tenant/setup-acknowledge` | Initial admin acknowledges onboarding terms | initial admin (with `tenant_admin_authority`) | one-time |
| `/admin/tenant/submit-for-activation` | Tenant administrator submits for activation | `tenant_admin_authority` | end of in_setup |
| `/admin/tenant/suspension-status` | Read suspension banner and status | `tenant_admin_authority` / `auditor` | banner persists in `suspended` |
| `/admin/tenant/offboarding-initiate` | Tenant initiates offboarding | `tenant_admin_authority` | gate-checked |
| `/admin/tenant/residency-change-request` | Tenant administrator requests residency change | `tenant_admin_authority` | rationale required |
| `/admin/tenant/entitlement-change` | Tenant administrator requests entitlement change | `tenant_admin_authority` | typically requires MSA amendment |
| `/admin/tenant/lifecycle-history` | Tenant administrator views lifecycle history (own tenant) | `tenant_admin_authority` / `auditor` | exportable |
| `/post-offboarding-export` | Former tenant accesses export read | offboarded-tenant credentials | contractual window |

### 5.2 Component requirements

- **Platform tenant catalogue** — high-density list with lifecycle badges, residency chips, vertical chips, last-Founder-action timestamps; filters by lifecycle, residency, vertical, last-suspension-reason; clear "high-risk vertical" highlight per DEC-08-12.
- **Onboarding wizard** — multi-step: identity → legal-entity verification (provider integration; live result) → pharma-licence verification (per declared activity) → sanctions screening → beneficial-ownership disclosure → MSA upload (URS-12 link) → DPA upload → review pack. Each step is itself audited.
- **Activation surface** — three-signature gate with each signer's status (initiating platform admin: signed / pending; approving platform admin: signed / pending; Founder: signed / pending); each signature opens the Controlled Approval Modal with multi-factor step-up.
- **Per-tenant administrative detail** — tabbed view: Identity, Lifecycle History, Configuration, Suspension, Offboarding, KYC Re-verification, Residency Change, Entitlements. Read access is broader than write; Executive-authority-only sections clearly badged.
- **Suspension surface** — categorised reason picker (`payment_default` / `regulatory_concern` / `security_incident` / `customer_requested`); each category surfaces the specific co-sign requirements; Controlled Approval Modal.
- **Return-to-active surface** — resolution-evidence upload (per reason category); routes appropriate co-signer; executive authority co-sign always.
- **Offboarding surface** — pre-offboarding gate runs at open; surfaces remediation list with deep-links to URS-07 study close-out, URS-07 cross-tenant grant revocation, URS-05 delegation revocation, URS-12 finding closure; only when all blockers cleared does the export-bundle composition step become available.
- **Export bundle download** — signed download URL with extended TTL (24 hours per DEC-08-15); integrity manifest accompanies; clear "this is the only authorised offboarding export download" framing.
- **Residency-change orchestration** — request, approval, preparation-window timer (T-30 day countdown), dual-residency operation status, integrity verification status (per chain), cutover surface.
- **Per-tenant tenant-administrator surface** — read-only identity post-activation (residency, framework, retention, entitlements); suspension banner during `suspended`; offboarding initiation surface; lifecycle history.
- **Post-offboarding export read surface** — minimal authentication (former tenant administrator credentials); read-only access to the export bundle download; clear "this tenant is offboarded" banner; access logged.

### 5.3 Accessibility and internationalisation

- WCAG 2.1 Level AA across every Module 8 surface.
- Lifecycle states and suspension reasons translated; identifiers remain canonical.
- Date / time displayed in user time zone; stored UTC; ISO 8601.
- Cross-tenant impact (e.g., during suspension cascade) clearly visualised.

---

## 6. Back-End Expected State

### 6.1 Domain entities

- `tenants` — the canonical tenant record per DEC-08-01.
- `tenant_lifecycle_events` — append-only log of every lifecycle transition with the signatures that caused it.
- `tenant_kyc_packs` — per-tenant KYC pack rows referencing URS-12 documents.
- `tenant_pharma_licence_records` — per-licence verification record with provider attribution and re-verification cadence.
- `tenant_sanctions_screenings` — per-screening record with provider attribution and verdict.
- `tenant_suspensions` — per-suspension event record with reason category and resolution evidence.
- `tenant_offboarding_runs` — per-offboarding workflow record with pre-gate status and export bundle reference.
- `tenant_residency_changes` — per-residency-change-event record with approval, preparation, cutover phases.
- `tenant_entitlements_versions` — per-version entitlement set with MSA amendment reference.
- `cross_tenant_grant_cascade_log` — per-cascade row capturing the suspension / resumption of cross-tenant collaboration grants in lockstep with tenant lifecycle.
- `offboarded_tenant_post_access_log` — per-access log for post-offboarding tenant data access.

### 6.1.1 Diagram 6.1-A — Module 8 entity-relationship overview

```mermaid
erDiagram
  TENANTS ||--o{ TENANT_LIFECYCLE_EVENTS : has
  TENANTS ||--o{ TENANT_KYC_PACKS : verified_via
  TENANTS ||--o{ TENANT_PHARMA_LICENCE_RECORDS : holds
  TENANTS ||--o{ TENANT_SANCTIONS_SCREENINGS : screened_by
  TENANTS ||--o{ TENANT_SUSPENSIONS : may_be_suspended_via
  TENANTS ||--o| TENANT_OFFBOARDING_RUNS : offboarded_via
  TENANTS ||--o{ TENANT_RESIDENCY_CHANGES : changes_residency_via
  TENANTS ||--o{ TENANT_ENTITLEMENTS_VERSIONS : entitled_via
  TENANT_LIFECYCLE_EVENTS }o--|| ELECTRONIC_SIGNATURES : signed_by
  TENANT_OFFBOARDING_RUNS ||--o{ CROSS_TENANT_GRANT_CASCADE_LOG : cascades_grants
  TENANT_SUSPENSIONS ||--o{ CROSS_TENANT_GRANT_CASCADE_LOG : cascades_grants
  TENANTS ||--o{ OFFBOARDED_TENANT_POST_ACCESS_LOG : post_offboarding_access
```

### 6.1.2 Diagram 6.1-B — Tenant lifecycle state machine

```mermaid
stateDiagram-v2
  [*] --> pending : TENANT_ONBOARDING_INITIATED
  pending --> in_setup : TENANT_MOVED_TO_IN_SETUP
  pending --> rejected : TENANT_REJECTED
  in_setup --> active : TENANT_ACTIVATED
  in_setup --> withdrawn : TENANT_WITHDRAWN_PRE_ACTIVATION
  active --> suspended : TENANT_SUSPENSION_ISSUED
  suspended --> active : TENANT_RETURNED_TO_ACTIVE
  suspended --> in_offboarding : TENANT_OFFBOARDING_INITIATED_BY_PLATFORM
  active --> in_offboarding : TENANT_OFFBOARDING_INITIATED
  in_offboarding --> offboarded : TENANT_OFFBOARDED
  offboarded --> [*]
  rejected --> [*]
  withdrawn --> [*]
```

### 6.1.3 Diagram 6.1-C — Suspension cascade to cross-tenant collaboration

```mermaid
flowchart TD
  A[Tenant moves to suspended] --> B[Module 8 enumerates cross-tenant grants where this tenant is lead OR partner]
  B --> C[For each grant: suspend in URS-07 in lockstep]
  C --> D[Partner-tenant access removed]
  D --> E[URS-30 notify both tenants]
  F[Tenant returns to active] --> G[Module 8 enumerates suspended grants caused by this tenant's suspension]
  G --> H{Partner tenant also active?}
  H -- yes --> I[Resume grant in URS-07; URS-30 notify both]
  H -- no --> J[Grant remains suspended until partner returns to active]
```

### 6.2 Data model requirements

| Entity | Purpose | Key fields | Required | Unique | Tenant isolation | Versioning | Retention | Soft-delete | Audit | E-sig link |
|---|---|---|---|---|---|---|---|---|---|---|
| `tenants` | Canonical tenant record per DEC-08-01 | `id`, `legal_name`, `display_name`, `legal_entity_jurisdiction`, `legal_entity_registration_number`, `pharma_licences_jsonb`, `beneficial_ownership_jsonb`, `data_residency_region` (`us` / `eu` / `in` / forward roadmap), `regulatory_framework_defaults_jsonb`, `retention_defaults_jsonb`, `tenant_contract_terms_jsonb`, `entitlements_jsonb`, `lifecycle_state` (per DEC-08-02), `vertical_classification_jsonb`, `created_at`, `activated_at`, `suspended_at`, `offboarding_initiated_at`, `offboarded_at`, `created_by_platform_user_id`, `tenant_administrator_user_id` (initial), `executive_authority_signed_e_sig_id_at_activation`, `current_msa_document_id` (FK to URS-12), `current_dpa_document_id` (FK to URS-12) | per-state per DEC-08-02 | unique(`id`); semantic uniqueness on `(legal_name, legal_entity_jurisdiction, legal_entity_registration_number)` warning-only | platform-context (registry is global; per-tenant fields RLS within tenant where the tenant has read access to their own) | stateful + append-only audit history | per `retention_defaults_jsonb`; never below regulatory minimum | yes (rejected, withdrawn, offboarded preserved; never hard-deleted) | yes (per state) | yes (per state) |
| `tenant_lifecycle_events` | Append-only lifecycle transition log | `id`, `tenant_id`, `from_state`, `to_state`, `event_code` (per audit vocabulary), `signature_set_jsonb` (array of {role, e_sig_id, signed_at} — derived read snapshot only; authoritative multi-signature evidence is stored in the module signature-slot table), `reason_jsonb`, `triggered_at`, `audit_log_id` (FK URS-06), `previous_hash`, `record_hash` | all | unique(`tenant_id`, `id`); unique(`record_hash`) | platform-context | append-only | retain (long-term) | not applicable | yes | yes |
| `tenant_kyc_packs` | KYC pack metadata (URS-12 holds the documents) | `id`, `tenant_id`, `legal_entity_verification_provider`, `legal_entity_verification_evidence_document_id` (FK URS-12), `pharma_licence_verification_provider`, `pharma_licence_verification_evidence_document_id`, `sanctions_screening_provider`, `sanctions_screening_evidence_document_id`, `beneficial_ownership_disclosure_document_id`, `kyc_pack_complete_at`, `kyc_pack_signed_e_sig_id` | all | unique(`tenant_id`, `kyc_pack_complete_at`) | platform-context | versioned (annual re-verification produces new version) | retain (25 years per DEC-08-13) | not applicable | yes | yes |
| `tenant_pharma_licence_records` | Per-licence record | `id`, `tenant_id`, `licence_type` (`fda_establishment_registration` / `ema_marketing_authorisation` / `cdsco_drug_manufacturing` / `mhra_wholesale_dealer` / etc.), `jurisdiction`, `licence_number`, `effective_from`, `effective_to`, `verification_provider`, `last_verified_at`, `last_verified_verdict` (`current` / `expired` / `revoked` / `pending_renewal`), `evidence_document_id` (FK URS-12) | all | unique active(`tenant_id`, `licence_type`, `licence_number`) | platform-context | stateful | retain | yes (revoked / expired preserved) | yes | yes |
| `tenant_sanctions_screenings` | Per-screening record | `id`, `tenant_id`, `screening_provider`, `screened_at`, `target_entity_jsonb` (legal entity + beneficial owners), `verdict` (`clear` / `hit` / `pending_review`), `hit_details_jsonb` (nullable), `evidence_document_id` (FK URS-12), `review_state` (`open` / `cleared` / `escalated`) | all | unique(`tenant_id`, `screening_provider`, `screened_at`) | platform-context | append-only | retain (long-term) | not applicable | yes | not applicable |
| `tenant_suspensions` | Per-suspension event | `id`, `tenant_id`, `reason_category` (per DEC-08-06), `reason_detail_jsonb`, `issued_by_platform_user_id`, `issued_e_sig_id`, `issued_at`, `co_sign_e_sig_ids_jsonb` (e.g., RA / IS lead per category — derived read snapshot only; authoritative multi-signature evidence is stored in the module signature-slot table), `state` (`active` / `lifted` / `escalated_to_offboarding`), `lifted_at` (nullable), `lifted_by_platform_user_id` (nullable), `lifted_co_sign_e_sig_ids_jsonb` (nullable; RA / IS / Founder — derived read snapshot only; authoritative multi-signature evidence is stored in the module signature-slot table), `resolution_evidence_document_id` (nullable; FK URS-12) | per-state | unique(`tenant_id`, `id`) | platform-context | stateful | retain (long-term) | not applicable | yes | yes (per stage) |
| `tenant_offboarding_runs` | Per-offboarding workflow record | `id`, `tenant_id`, `initiated_by` (`tenant` / `platform`), `initiating_user_id`, `initiated_e_sig_id`, `initiated_at`, `gate_check_results_jsonb` (per blocker category result), `gate_cleared_at`, `export_bundle_composed_at`, `export_bundle_reference`, `tenant_export_receipt_e_sig_id`, `platform_export_issuance_e_sig_id`, `founder_offboarding_e_sig_id`, `chain_sealing_at`, `state` (`initiated` / `gate_pending` / `gate_cleared` / `export_composed` / `signed` / `chain_sealed` / `offboarded`) | per-state | unique(`tenant_id`) | platform-context | stateful | retain (long-term) | not applicable | yes | yes (per stage) |
| `tenant_residency_changes` | Per-residency-change-event record | `id`, `tenant_id`, `from_region`, `to_region`, `requested_by_user_id`, `requested_e_sig_id`, `founder_approved_e_sig_id`, `preparation_window_starts_at`, `preparation_window_ends_at`, `dual_operation_active`, `cutover_at`, `cutover_signed_e_sig_ids_jsonb` (platform admin + executive authority — derived read snapshot only; authoritative multi-signature evidence is stored in the module signature-slot table), `state` (`requested` / `approved` / `dual_operation` / `cutover_completed` / `rejected`), `customer_notified_at` | per-state | unique(`tenant_id`, `id`) | platform-context | stateful | retain (long-term) | not applicable | yes | yes |
| `tenant_entitlements_versions` | Per-version entitlement set | `id`, `tenant_id`, `version`, `entitlements_jsonb`, `effective_from`, `effective_to` (nullable), `set_by_platform_user_id`, `set_e_sig_id`, `tenant_e_sig_id` (MSA amendment signer), `founder_e_sig_id` (for high-risk entitlements), `msa_amendment_document_id` (FK URS-12), `previous_hash`, `record_hash` | all | unique(`tenant_id`, `version`); unique(`record_hash`) | platform-context | versioned | retain (long-term) | not applicable | yes | yes |
| `cross_tenant_grant_cascade_log` | Per-cascade-event log | `id`, `triggering_tenant_id`, `affected_grant_id` (FK URS-07), `affected_partner_tenant_id`, `cascade_type` (`suspension` / `resumption` / `revocation_due_to_offboarding`), `triggered_at`, `urs07_event_audit_log_id` (FK URS-06) | all | none | platform-context (visible to both involved tenants) | append-only | retain (long-term) | not applicable | yes | not applicable |
| `offboarded_tenant_post_access_log` | Per-access log for post-offboarding access | `id`, `offboarded_tenant_id`, `access_type` (`legal_mandate` / `tenant_export_read` / `integrity_verification`), `access_purpose_document_id` (FK URS-12 for legal mandate), `accessed_by_platform_user_id`, `founder_co_sign_e_sig_id` (for legal mandate), `is_lead_co_sign_e_sig_id` (for legal mandate), `accessed_at`, `notified_former_tenant_at` | all | none | platform-context | append-only | retain (long-term) | not applicable | yes | yes (for legal mandate) |

### 6.3 API requirements

#### 6.3.1 Tenant catalogue and identity

| Method | Endpoint | Actor | Request | Response | Permission | Audit | Error codes |
|---|---|---|---|---|---|---|---|
| GET | `/platform/tenants` | platform identity | filters | `Tenant[]` | platform identity | none | none |
| GET | `/platform/tenants/:id` | platform identity / Founder | none | full tenant detail | platform identity | none | `NOT_FOUND` |
| GET | `/admin/tenant/identity` | tenant-scoped | none | tenant identity (read-only post-activation) | `tenant_admin_authority` / `auditor` | none | none |
| GET | `/admin/tenant/lifecycle-history` | tenant-scoped | filters | `LifecycleEvent[]` | `tenant_admin_authority` / `auditor` | `TENANT_LIFECYCLE_HISTORY_VIEW_OPENED` once per session | none |

#### 6.3.2 Onboarding

| Method | Endpoint | Actor | Request | Response | Permission | Audit | Error codes |
|---|---|---|---|---|---|---|---|
| POST | `/platform/tenants` | platform identity | tenant identity fields | `201` (state `pending`) | platform identity | `TENANT_ONBOARDING_INITIATED` | validation |
| POST | `/platform/tenants/:id/legal-entity-verification` | platform identity | `{provider, evidenceDocumentId}` (electronic-signed) | `200` | platform identity | `LEGAL_ENTITY_VERIFIED` | validation |
| POST | `/platform/tenants/:id/pharma-licence-verification` | platform identity | `{licenceType, jurisdiction, licenceNumber, provider, evidenceDocumentId}` (electronic-signed) | `200` | platform identity | `PHARMA_LICENCE_VERIFIED` | `LICENCE_NOT_VERIFIED`, `LICENCE_EXPIRED` |
| POST | `/platform/tenants/:id/sanctions-screening` | platform identity | `{provider, evidenceDocumentId, verdict}` (electronic-signed) | `200` | platform identity | `SANCTIONS_SCREENING_RUN`, `SANCTIONS_SCREENING_PASSED` or `SANCTIONS_HIT_DETECTED` | validation |
| POST | `/platform/tenants/:id/move-to-in-setup` | platform identity | reason (electronic-signed) | `200` | platform identity | `TENANT_MOVED_TO_IN_SETUP` | `ONBOARDING_PREREQUISITE_NOT_SATISFIED` |
| POST | `/platform/tenants/:id/reject` | platform identity | reason (electronic-signed) | `200` | platform identity | `TENANT_REJECTED` | `STATE_NOT_PENDING` |
| POST | `/admin/tenant/setup-acknowledge` | initial admin | acknowledgement (electronic-signed) | `200` | initial admin | `TENANT_ADMIN_ACKNOWLEDGED_TERMS` | `STATE_NOT_IN_SETUP` |
| POST | `/admin/tenant/setup/residency` | tenant administrator | `{residency}` (electronic-signed) | `200` | `tenant_admin_authority` | `TENANT_RESIDENCY_SELECTED` | `STATE_NOT_IN_SETUP`, `RESIDENCY_NOT_AVAILABLE` |
| POST | `/admin/tenant/setup/regulatory-framework-defaults` | tenant administrator | per-study-type defaults (electronic-signed) | `200` | `tenant_admin_authority` | `TENANT_REGULATORY_FRAMEWORK_DEFAULTS_SET` | `STATE_NOT_IN_SETUP` |
| POST | `/admin/tenant/submit-for-activation` | tenant administrator | summary (electronic-signed) | `200` | `tenant_admin_authority` | `TENANT_SUBMITTED_FOR_ACTIVATION` | `STATE_NOT_IN_SETUP`, `ONBOARDING_PREREQUISITE_NOT_SATISFIED` |

#### 6.3.3 Activation

| Method | Endpoint | Actor | Request | Response | Permission | Audit | Error codes |
|---|---|---|---|---|---|---|---|
| POST | `/platform/tenants/:id/activate/initiate` | platform identity (initiating) | reason (electronic-signed + MFA) | `200` | platform identity | `TENANT_ACTIVATION_INITIATED` | `STATE_NOT_SUBMITTED_FOR_ACTIVATION` |
| POST | `/platform/tenants/:id/activate/approve` | platform identity (approving; different user) | reason (electronic-signed + MFA) | `200` | platform identity (`AUTHOR_NEQ_APPROVER`-equivalent role separation) | `TENANT_ACTIVATION_APPROVED` | `APPROVER_IS_INITIATOR`, `STATE_NOT_INITIATED` |
| POST | `/platform/tenants/:id/activate/executive-cosign` | Founder | reason (electronic-signed + MFA) | `200` | Founder | `TENANT_ACTIVATED` | `STATE_NOT_APPROVED` |

#### 6.3.4 Suspension and return

| Method | Endpoint | Actor | Request | Response | Permission | Audit | Error codes |
|---|---|---|---|---|---|---|---|
| POST | `/platform/tenants/:id/suspend` | platform identity | `{reasonCategory, reasonDetail, coSignerProfiles}` (electronic-signed + MFA + per-category co-sign) | `200` | platform identity + per-category co-signer | `TENANT_SUSPENSION_ISSUED` | `INVALID_REASON_CATEGORY`, `MISSING_COSIGN`, `STATE_NOT_ACTIVE` |
| POST | `/platform/tenants/:id/return-to-active` | platform identity | `{resolutionEvidenceDocumentId, coSignerProfiles}` (electronic-signed + MFA + executive authority co-sign + per-category co-sign) | `200` | platform identity + executive authority + per-category | `TENANT_RETURNED_TO_ACTIVE` | `RESOLUTION_EVIDENCE_MISSING`, `MISSING_FOUNDER_COSIGN`, `STATE_NOT_SUSPENDED` |
| GET | `/admin/tenant/suspension-status` | tenant-scoped | none | suspension banner detail | `tenant_admin_authority` / `auditor` | none | none |

#### 6.3.5 Offboarding

| Method | Endpoint | Actor | Request | Response | Permission | Audit | Error codes |
|---|---|---|---|---|---|---|---|
| POST | `/admin/tenant/offboarding-initiate` | tenant administrator | reason (electronic-signed + MFA) | `200` | `tenant_admin_authority` | `TENANT_OFFBOARDING_INITIATED` | gate blockers |
| POST | `/platform/tenants/:id/offboarding-initiate` | platform identity | reason (electronic-signed + MFA + executive authority co-sign for prolonged suspension) | `200` | platform identity (+ executive authority where required) | `TENANT_OFFBOARDING_INITIATED_BY_PLATFORM` | gate blockers |
| GET | `/platform/tenants/:id/offboarding/gate-status` | platform identity / tenant administrator | none | gate result with blockers | platform identity / `tenant_admin_authority` | none | none |
| POST | `/platform/tenants/:id/offboarding/compose-export-bundle` | platform identity | none (electronic-signed + MFA) | bundle reference + signed download URL (24h TTL) | platform identity | `OFFBOARDING_EXPORT_BUNDLE_COMPOSED` | `GATE_NOT_CLEARED` |
| POST | `/admin/tenant/offboarding/sign-export-receipt` | tenant administrator | reason (electronic-signed + MFA) | `200` | `tenant_admin_authority` | `OFFBOARDING_EXPORT_RECEIPT_SIGNED` | `STATE_NOT_EXPORT_COMPOSED` |
| POST | `/platform/tenants/:id/offboarding/sign-issuance` | platform identity | reason (electronic-signed + MFA) | `200` | platform identity | `OFFBOARDING_EXPORT_ISSUED` | `STATE_NOT_RECEIPT_SIGNED` |
| POST | `/platform/tenants/:id/offboarding/executive-cosign` | Founder | reason (electronic-signed + MFA) | `200` | Founder | `TENANT_OFFBOARDED`, `TENANT_CHAINS_SEALED_AT_OFFBOARDING` | `STATE_NOT_ISSUED` |

#### 6.3.6 Residency change

| Method | Endpoint | Actor | Request | Response | Permission | Audit |
|---|---|---|---|---|---|---|
| POST | `/admin/tenant/residency-change-request` | tenant administrator | `{toRegion, rationale}` (electronic-signed) | `201` | `tenant_admin_authority` | `RESIDENCY_CHANGE_REQUESTED` |
| POST | `/platform/tenants/:id/residency-change/:requestId/approve` | Founder | reason (electronic-signed + MFA) | `200` | Founder | `RESIDENCY_CHANGE_APPROVED` |
| POST | `/platform/tenants/:id/residency-change/:requestId/begin-dual-operation` | platform identity | none (electronic-signed) | `200` | platform identity | `RESIDENCY_CHANGE_DUAL_OPERATION_BEGAN` |
| POST | `/platform/tenants/:id/residency-change/:requestId/cutover` | platform identity + executive authority | none (electronic-signed + MFA + executive authority co-sign) | `200` | platform identity + executive authority | `RESIDENCY_CHANGE_CUTOVER_COMPLETED` |

#### 6.3.7 KYC re-verification and entitlements

| Method | Endpoint | Actor | Request | Response | Permission | Audit |
|---|---|---|---|---|---|---|
| POST | `/platform/tenants/:id/kyc-reverification/run` | platform identity / scheduled | `{providers}` | `KycReverificationResult` | platform identity | `KYC_REVERIFICATION_RUN`, `KYC_REVERIFICATION_PASSED` / `KYC_REVERIFICATION_FAILED` |
| GET | `/platform/tenants/:id/kyc-reverification/register` | platform identity / auditor | filters | history | platform identity | none |
| POST | `/admin/tenant/entitlement-change` | tenant administrator | `{requestedEntitlements, rationale}` (electronic-signed) | `201` | `tenant_admin_authority` | `ENTITLEMENT_CHANGE_REQUESTED` |
| POST | `/platform/tenants/:id/entitlements/amend` | platform identity | `{newEntitlementsJsonb, msaAmendmentDocumentId}` (electronic-signed + tenant counter-sign + executive authority co-sign for high-risk) | `200` | platform identity + tenant + executive authority | `ENTITLEMENTS_UPDATED` |

#### 6.3.8 Post-offboarding

| Method | Endpoint | Actor | Request | Response | Permission | Audit |
|---|---|---|---|---|---|---|
| GET | `/post-offboarding-export` | offboarded-tenant credentials | none | signed download URL (regenerated; 24h TTL) | offboarded-tenant credentials within contractual window | `OFFBOARDED_TENANT_EXPORT_ACCESS_USED` |
| POST | `/platform/tenants/:id/post-offboarded-access/legal-mandate` | Founder + Information Security Lead | `{purposeDocumentId, dataScope}` (electronic-signed + MFA + co-sign) | `200` | Founder + Information Security Lead | `OFFBOARDED_TENANT_DATA_ACCESS` |

### 6.4 Workflow / lifecycle requirements

| Workflow | Step | Time-to-live or timer | Auto-action | Reminder |
|---|---|---|---|---|
| Onboarding | pending → in_setup | 60 days default | auto-reject if KYC not completed | T-30, T-7 |
| Activation | submitted → activated | 14 days | escalate to platform leadership | T-7, T-1 |
| Suspension grace window | suspended → resolved or escalated | per reason category (default 30d) | auto-escalate to offboarding-initiation review | T-15, T-3 |
| Offboarding | initiated → offboarded | 90 days default | escalate to platform leadership; legal review | T-30, T-7, T-1 |
| Residency change preparation | approved → cutover | 30 days minimum | dual-operation status maintained | T-15, T-7, T-1 |
| KYC re-verification (annual) | scheduled | continuous | auto-trigger; alerts on failure | none |
| Sanctions screening (quarterly) | scheduled | continuous | auto-trigger; alerts on hit | none |
| Beneficial-ownership refresh (annual) | scheduled | continuous | auto-trigger | T-30 |
| Post-offboarding export read access | offboarded | per contractual window (default 7 years) | auto-revoke at end | T-90, T-30, T-7 |

### 6.5 Business rules

- **BR-08-01** — Tenant activation requires three independent electronic signatures: initiating platform administrator, approving platform administrator (different user; `TENANT_ACTIVATION_DUAL_PLATFORM_SIGNATURE` per §3.4), and executive authority co-sign with MFA step-up.
- **BR-08-02** — All seven onboarding prerequisites per DEC-08-03 MUST be satisfied before `in_setup → active`; missing any returns `ONBOARDING_PREREQUISITE_NOT_SATISFIED` with the specific missing item.
- **BR-08-03** — Suspension cascades to cross-tenant collaboration grants per DEC-08-17 in lockstep; resumption requires the affected tenant AND the partner tenant both be in `active` state.
- **BR-08-04** — Pre-offboarding cross-module gate per DEC-08-08 MUST clear all blockers before `active → in_offboarding` (or `suspended → in_offboarding`).
- **BR-08-05** — Offboarding completion requires three signatures: tenant administrator (export receipt), platform administrator (issuance), and executive authority co-sign with MFA step-up.
- **BR-08-06** — Chain sealing at offboarding fires URS-06's `TENANT_CHAINS_SEALED_AT_OFFBOARDING` per URS-06 BR-06-17; the tenant's chains accept no further inserts after this event.
- **BR-08-07** — Post-offboarding Verixa access is restricted to (a) legal / regulatory mandate with Founder + Information Security Lead co-sign, (b) tenant's own export read access, (c) URS-06 integrity verification (chain hashes only). Any other access is forbidden.
- **BR-08-08** — Residency-change migration requires executive authority approval, minimum 30-day customer preparation window, dual-residency operation during cutover, integrity verification at both regions, platform administrator + executive authority co-sign at cutover, customer notification within 24 hours.
- **BR-08-09** — KYC re-verification scheduling per DEC-08-14 MUST run automatically; failures trigger `regulatory_concern` suspension after the configured grace window (or immediately for sanctions hits).
- **BR-08-10** — Tenant entitlements MUST be set at activation from `tenant_contract_terms_jsonb` and changed only through controlled MSA amendment with tenant counter-sign + executive authority co-sign for high-risk entitlements (clinical activation, controlled-substance handling).
- **BR-08-11** — Founder-explicit-review high-risk vertical tenants per DEC-08-12 require the documented vertical-specific risk register and acceptance memo before executive authority co-sign.
- **BR-08-12** — Tenant lifecycle events emit dual audit per DEC-08-18: in the tenant's per-tenant URS-06 chain AND in the URS-06 global chain.
- **BR-08-13** — Sub-tenant / business unit hierarchy is forward roadmap; per-business-unit scope at launch uses URS-05 §6.2.1 `business_unit` scope dimension.
- **BR-08-14** — Tenant record creation (entering `pending` state) triggers URS-06 per-tenant chain genesis row at sequence 1 (per URS-06 DEC-06-17 / DEC-06-23) so every pre-activation lifecycle event is captured in the chain.
- **BR-08-15** — Post-offboarding tenant retains read-only export access for the contractual window (default 7 years; tenant-configurable upward at MSA negotiation).
- **BR-08-16** — Verixa retains the tenant's chains for the URS-06 retention class (typically 25 years for authority snapshots, 7 years for general audit) regardless of tenant offboarding.
- **BR-08-17** — Offboarded tenant data access by Verixa is itself audited as `OFFBOARDED_TENANT_DATA_ACCESS` and reported to the former tenant within the contractual window.
- **BR-08-18** — `offboarded → active` is forbidden; a re-engaging former tenant onboards as a new tenant with a successor reference per DEC-08-02.
- **BR-08-19** — Audit-log writes are atomic with the originating action per URS-04 BR-04-15 / URS-06 BR-06-01.
- **BR-08-20** — Tenant lifecycle hook is consumed by every URS-01..URS-35 module at every mutation: if the tenant is anything other than `active`, mutations are blocked with the specific lifecycle-state error.

### 6.6 Audit trail requirements

Module 8 governance event vocabulary (canonical launch list; every code MUST have at least one writer and one regression test; adding a code is a Class 3 change):

`TENANT_ONBOARDING_INITIATED`, `LEGAL_ENTITY_VERIFIED`, `LEGAL_ENTITY_VERIFICATION_FAILED`, `PHARMA_LICENCE_VERIFIED`, `PHARMA_LICENCE_VERIFICATION_FAILED`, `LICENCE_EXPIRED`, `SANCTIONS_SCREENING_RUN`, `SANCTIONS_SCREENING_PASSED`, `SANCTIONS_HIT_DETECTED`, `BENEFICIAL_OWNERSHIP_DISCLOSED`, `BENEFICIAL_OWNERSHIP_REFRESHED`, `BENEFICIAL_OWNERSHIP_REVIEW_ESCALATED`, `MSA_LINKED`, `DPA_LINKED`, `TENANT_MOVED_TO_IN_SETUP`, `TENANT_REJECTED`, `TENANT_ADMIN_ACKNOWLEDGED_TERMS`, `TENANT_RESIDENCY_SELECTED`, `TENANT_REGULATORY_FRAMEWORK_DEFAULTS_SET`, `TENANT_RETENTION_DEFAULTS_SET`, `TENANT_SUBMITTED_FOR_ACTIVATION`, `TENANT_ACTIVATION_INITIATED`, `TENANT_ACTIVATION_APPROVED`, `TENANT_ACTIVATED`, `TENANT_WITHDRAWN_PRE_ACTIVATION`, `HIGH_RISK_VERTICAL_REVIEW_LOGGED`, `HIGH_RISK_VERTICAL_RISK_REGISTER_PUBLISHED`, `HIGH_RISK_VERTICAL_ACCEPTANCE_MEMO_PUBLISHED`, `TENANT_SUSPENSION_ISSUED`, `TENANT_RETURN_TO_ACTIVE_INITIATED`, `TENANT_RETURNED_TO_ACTIVE`, `CROSS_TENANT_COLLABORATION_SUSPENDED` (cascade in both tenant chains), `CROSS_TENANT_COLLABORATION_RESUMED` (cascade), `TENANT_OFFBOARDING_INITIATED`, `TENANT_OFFBOARDING_INITIATED_BY_PLATFORM`, `OFFBOARDING_BLOCKED_BY_OPEN_STUDIES`, `OFFBOARDING_BLOCKED_BY_ACTIVE_COLLABORATIONS`, `OFFBOARDING_BLOCKED_BY_OPEN_DELEGATIONS`, `OFFBOARDING_BLOCKED_BY_OPEN_FINDINGS`, `OFFBOARDING_EXPORT_BUNDLE_COMPOSED`, `OFFBOARDING_EXPORT_RECEIPT_SIGNED`, `OFFBOARDING_EXPORT_ISSUED`, `TENANT_OFFBOARDED`, `TENANT_CHAINS_SEALED_AT_OFFBOARDING` (URS-06 emits; Module 8 references), `OFFBOARDED_TENANT_EXPORT_ACCESS_USED`, `OFFBOARDED_TENANT_DATA_ACCESS`, `RESIDENCY_CHANGE_REQUESTED`, `RESIDENCY_CHANGE_APPROVED`, `RESIDENCY_CHANGE_REJECTED`, `RESIDENCY_CHANGE_DUAL_OPERATION_BEGAN`, `RESIDENCY_CHANGE_CUTOVER_COMPLETED`, `KYC_REVERIFICATION_RUN`, `KYC_REVERIFICATION_PASSED`, `KYC_REVERIFICATION_FAILED`, `ENTITLEMENT_CHANGE_REQUESTED`, `ENTITLEMENT_AMENDMENT_SIGNED`, `ENTITLEMENTS_UPDATED`, `TENANT_LIFECYCLE_HISTORY_EXPORTED`, `TENANT_LIFECYCLE_HISTORY_VIEW_OPENED` (coarse; once per session per tenant scope), `PLATFORM_TENANT_ACCESS_USED` (during break-glass surfaces), `PLATFORM_TENANT_ACCESS_DENIED`.

### 6.7 Record versioning and class-of-change governance

- Versioned (immutable per published version): `tenant_kyc_packs` (per re-verification cycle), `tenant_entitlements_versions`, `tenant_lifecycle_events` (each event is an append-only row with hash linkage).
- Stateful with append-only audit history: `tenants` (lifecycle state machine), `tenant_pharma_licence_records`, `tenant_suspensions`, `tenant_offboarding_runs`, `tenant_residency_changes`.
- Append-only: `tenant_sanctions_screenings`, `cross_tenant_grant_cascade_log`, `offboarded_tenant_post_access_log`.
- Soft-delete: `tenants` (rejected / withdrawn / offboarded preserved; never hard-deleted).

---

## 7. Cross-Module Wiring and Change-Impact

### 7.1 Cross-module wiring

#### Diagram 7-A — Module 8 in the suite

```mermaid
graph LR
  subgraph M8 [Module 8 — Tenant Management]
    REC[Tenant Record]
    LCY[Tenant Lifecycle]
    KYC[Onboarding + KYC]
    RES[Data Residency]
    ENT[Entitlements / Feature Gating]
    EXP[Offboarding Export]
  end

  M1[URS-01 Auth] <--> KYC
  M2[URS-02 RBAC] --> ENT
  M3[URS-03 Active Scope] --> ENT
  M4[URS-04 Workflow / E-Sign] --> LCY
  M5[URS-05 Authority] --> KYC
  M6[URS-06 Audit Substrate] <--> LCY
  M7[URS-07 Study] --> ENT
  M12[URS-12 Document Control] <--> KYC
  M28[URS-28 Training Management & Qualification] --> KYC
  M30[URS-30 Notifications] --> LCY
  M35[URS-35 Storage / Backup / Cold] <--> RES
  ENT --> ALL[All other URS modules consume tenant entitlements + lifecycle state]
```

Module 8 is the foundation for tenant isolation, residency, entitlements, and lifecycle gates that every other module consults. URS-06 receives `CHAIN_GENESIS` at tenant record creation (`pending` state — sequence 1; per URS-06 DEC-06-17) and `TENANT_CHAINS_SEALED_AT_OFFBOARDING` at offboarding (per URS-06 BR-06-17). URS-35 owns the residency-scoped object store, replication, backup, and restore. URS-12 holds the onboarding documents (signed MSA, signed DPA, KYC pack components, executive authority activation memo, vertical-specific risk registers).

### 7.2 Change-Impact Matrix (CIM)

| Change | Class | Impact on (modules) | Required revalidation |
|---|---|---|---|
| Add lifecycle state (DEC-08-02) | 1 | every consuming module's tenant hook | Full regression |
| Add residency region (DEC-08-05) | 1 | URS-35 storage classes; URS-08 migration path | Full regression including DR drill |
| Change executive authority co-sign gates (DEC-08-04) | 1 | governance posture | Full regression |
| Change pre-offboarding gate categories (DEC-08-08) | 1 | URS-07 BR-07-18; URS-05 BR-05-15 | Full regression |
| Add entitlement key (DEC-08-09) | 1 | every consuming module that gates on the key | Full regression |
| Change offboarding export contract (DEC-08-15) | 1 | URS-06 export integrity manifest; URS-12 documents | Full regression |
| Change suspension reason category | 1 | URS-30 routing; per-category co-signers | Full regression |
| Change KYC re-verification cadence (DEC-08-14) | 2 | URS-30 schedule | Targeted regression |
| Add high-risk vertical to list (DEC-08-12) | 2 | onboarding flow | Targeted regression |
| Add KYC provider | 2 | URS-08 onboarding | Targeted regression including provider qualification |
| Change preparation-window default for residency change | 3 | URS-30 reminders | Unit regression |
| Add audit event code | 3 | URS-06 | Writer-presence regression |
| UI copy or layout change | 4 | none | Visual regression |

### 7.3 Cross-module dependencies (consumed by Module 8)

| Dependency | Source | Impact | Blocking? |
|---|---|---|---|
| Authentication, MFA step-up | URS-01 | Substrate | Blocking |
| Effective permissions | URS-02 | Tenant administrator role | Blocking |
| Workflow / e-sig ceremony | URS-04 | Lifecycle signatures | Blocking |
| Authority resolver | URS-05 | executive authority, RA / IS lead authority | Blocking |
| Audit substrate | URS-06 | Lifecycle audit, chain genesis, chain sealing | Blocking |
| Cross-tenant collaboration | URS-07 | Suspension cascade; offboarding gate | Blocking |
| Document control | URS-12 | Onboarding documents | Blocking |
| Notifications | URS-30 | Lifecycle reminders, escalations | Non-blocking (direct e-mail fallback) |
| Storage, backup, residency | URS-35 | Residency-scoped storage; DR | Blocking for PQ |
| External billing system | external | Suspension trigger for `payment_default` | Non-blocking (manual trigger fallback) |
| External KYC providers | external (3 minimum per DEC-08-19) | Onboarding verifications | Blocking |

---

## 8. AI / Automation / Human-in-the-Loop Controls

Module 8 contains **no AI / ML components** in the lifecycle, KYC, onboarding, suspension, offboarding, residency-migration, or entitlement-management paths. Every lifecycle decision is human-driven with explicit electronic signature; KYC verification verdicts are returned by external regulated providers; entitlement changes require MSA amendment with both-side signatures; residency-change cutover requires executive authority co-sign. AI suggestions in URS-32 / MIRA that inform onboarding (e.g., suggesting a vertical classification or surfacing a regulatory framework default) are advisory only and MUST set `ai_advisory = true` per URS-06 DEC-06-15.

The HITL lifecycle is owned by URS-04. Module 8 consumes the Controlled Approval Modal for every electronic signature.

Static analysis MUST verify zero references to LLM SDKs in Module 8 source per CLAUDE.md QS-21.

---

## 9. Reports, Dashboards, and Exports

| Report | Purpose | Audience | Format |
|---|---|---|---|
| Platform tenant catalogue | Tenant inventory and lifecycle posture | Platform administrator, executive authority | CSV + PDF |
| Per-tenant lifecycle history | Lifecycle event chain with signatures | Tenant administrator, auditor, inspector | PDF + JSON + integrity manifest |
| Suspension register | Active and historical suspensions | Platform administrator, executive authority, auditor | CSV + PDF |
| Offboarding register | Active and historical offboarding runs | Platform administrator, executive authority, auditor | CSV + PDF |
| Residency-distribution dashboard | Tenant counts per region; lifecycle states per region | Platform administrator, executive authority | Dashboard |
| Entitlement utilisation dashboard | Per-entitlement adoption across tenants | Platform administrator, executive authority, sales-engineering | Dashboard |
| KYC re-verification register | Per-tenant per-cycle KYC results | Platform administrator, RA Lead, executive authority | CSV + PDF |
| Founder-explicit-review high-risk vertical register | High-risk vertical tenants with risk registers and acceptance memos | Founder, QA, RA | PDF |
| Offboarded-tenant post-access log | Per-access log with mandates | Founder, IS Lead, auditor | CSV + PDF |
| Cross-tenant cascade log | Suspension / resumption / revocation cascades | Tenant administrator (own tenant), platform administrator | CSV + PDF |
| Tenant onboarding pack export | Aggregated KYC pack + activation memo | Founder, RA Lead, auditor, regulatory inspector | PDF (electronically signed) |
| Tenant offboarding export bundle | Comprehensive data export per DEC-08-15 | Tenant administrator (post-offboarding), regulatory inspector | PDF + JSON + binaries + integrity manifest |

Every export routes through the Controlled Approval Modal, carries an electronic signature, a signed download URL with 15-minute TTL (24-hour TTL for the offboarding export bundle); and an integrity manifest accompanies every export per URS-06 DEC-06-10.

---

## 10. Notifications and Queues

| Trigger | Recipient | Channel | Latency |
|---|---|---|---|
| Tenant onboarding initiated | platform-tenant-onboarding-specialist; tenant primary contact | URS-30 in-app + e-mail | within 60 seconds |
| KYC verification result | platform RA Lead; tenant primary contact | URS-30 in-app + e-mail | within 60 seconds |
| Tenant submitted for activation | Founder; platform administrators | URS-30 in-app + e-mail | within 60 seconds |
| Tenant activated | tenant administrator; Founder; sales-engineering | URS-30 in-app + e-mail | within 60 seconds |
| Tenant suspension issued | tenant administrator; cross-tenant partners (cascade); Founder | URS-30 in-app + e-mail | within 60 seconds |
| Tenant returned to active | tenant administrator; cross-tenant partners (cascade); Founder | URS-30 in-app + e-mail | within 60 seconds |
| Cross-tenant cascade event (suspended / resumed) | both tenants' administrators | URS-30 in-app + e-mail | within 60 seconds |
| Tenant offboarding initiated | Founder; platform administrators; cross-tenant partners | URS-30 in-app + e-mail | within 60 seconds |
| Pre-offboarding gate failure | tenant administrator | URS-30 in-app + e-mail | immediate (synchronous response) |
| Tenant offboarded | tenant administrator (export-access onboarding); Founder | URS-30 in-app + e-mail | within 60 seconds |
| Residency change requested | Founder | URS-30 in-app + e-mail | within 60 seconds |
| Residency change approved | tenant administrator; URS-35 operations | URS-30 in-app + e-mail | within 60 seconds |
| Residency change cutover completed | tenant administrator; customer-data-residency contact; URS-35 operations | URS-30 in-app + e-mail; customer notification per privacy policy | within 24 hours |
| KYC re-verification approaching due | platform RA Lead | URS-30 e-mail | T-30, T-7 |
| KYC re-verification failure (e.g., licence expired) | platform RA Lead; Founder; tenant administrator | URS-30 in-app + e-mail | within 60 seconds |
| Sanctions hit detected | platform RA Lead; IS Lead; Founder; legal counsel | URS-30 in-app + e-mail; SOC chat | within 60 seconds |
| Founder activation request | Founder | URS-30 in-app + e-mail | within 60 seconds |
| Post-offboarding tenant data access by Verixa (legal mandate) | former tenant administrator | URS-30 e-mail | within 24 hours per privacy policy |
| Post-offboarding export read access used | former tenant administrator (confirmation); platform administrator | URS-30 in-app + e-mail | within 60 seconds |

---

## 11. Error Handling and Negative Paths

### 11.1 Error envelope

Standard envelope (human message, machine code in upper-snake-case, optional structured details, correlation identifier).

### 11.2 Error-code catalogue

| Code | HTTP | Path | UI behaviour |
|---|---|---|---|
| ONBOARDING_PREREQUISITE_NOT_SATISFIED | 409 | onboarding lifecycle endpoints | inline list of missing prerequisites |
| LICENCE_NOT_VERIFIED | 422 | pharma-licence verification | inline error citing provider response |
| LICENCE_EXPIRED | 422 | pharma-licence verification | inline error citing provider response |
| SANCTIONS_HIT_DETECTED | 422 | sanctions screening | banner; SOC alert; route to escalation |
| RESIDENCY_NOT_AVAILABLE | 400 | tenant setup / residency-change request | inline error |
| INVALID_REASON_CATEGORY | 400 | tenant suspension | inline error |
| MISSING_COSIGN | 401 | tenant suspension / return-to-active | open co-signer route |
| MISSING_FOUNDER_COSIGN | 401 | activation / return / offboarding / cutover | open executive authority co-sign route |
| RESOLUTION_EVIDENCE_MISSING | 400 | return-to-active | inline error |
| APPROVER_IS_INITIATOR | 403 | activation approval | inline error |
| OFFBOARDING_BLOCKED_BY_OPEN_STUDIES | 409 | offboarding initiation | inline list with deep-links to URS-07 |
| OFFBOARDING_BLOCKED_BY_ACTIVE_COLLABORATIONS | 409 | offboarding initiation | inline list with deep-links to URS-07 |
| OFFBOARDING_BLOCKED_BY_OPEN_DELEGATIONS | 409 | offboarding initiation | inline list with deep-links to URS-05 |
| OFFBOARDING_BLOCKED_BY_OPEN_FINDINGS | 409 | offboarding initiation | inline list with deep-links to URS-12..URS-34 |
| GATE_NOT_CLEARED | 409 | export bundle composition | inline message |
| STATE_NOT_PENDING | 409 | lifecycle endpoints | inline error |
| STATE_NOT_IN_SETUP | 409 | lifecycle endpoints | inline error |
| STATE_NOT_ACTIVE | 409 | lifecycle endpoints | inline error |
| STATE_NOT_SUSPENDED | 409 | lifecycle endpoints | inline error |
| STATE_NOT_INITIATED | 409 | lifecycle endpoints | inline error |
| STATE_NOT_APPROVED | 409 | lifecycle endpoints | inline error |
| STATE_NOT_SUBMITTED_FOR_ACTIVATION | 409 | lifecycle endpoints | inline error |
| STATE_NOT_EXPORT_COMPOSED | 409 | lifecycle endpoints | inline error |
| STATE_NOT_RECEIPT_SIGNED | 409 | lifecycle endpoints | inline error |
| STATE_NOT_ISSUED | 409 | lifecycle endpoints | inline error |
| TENANT_OFFBOARDED_NO_MUTATIONS_PERMITTED | 403 | mutations after offboarding | inline error |
| TENANT_SUSPENDED_NO_MUTATIONS_PERMITTED | 403 | mutations during suspension | banner |
| ENTITLEMENT_AMENDMENT_REQUIRES_FOUNDER_COSIGN | 401 | entitlement change for high-risk | open executive authority co-sign route |
| RESIDENCY_CHANGE_FORBIDDEN_DURING_SUSPENSION | 409 | residency-change request | inline error |
| AUDIT_TRAIL_WRITE_FAILED | 500 | any state-changing action | toast; the originating action did NOT commit |
| PLATFORM_TENANT_ACCESS_DENIED | 403 | platform identity outside support envelope | inline error; SOC alert |

### 11.3 Negative-path catalogue

| Scenario | Detection | Response | UI behaviour |
|---|---|---|---|
| Activation attempted before all prerequisites | back end | `409 ONBOARDING_PREREQUISITE_NOT_SATISFIED` | inline list |
| Activation initiator is also approver | back end | `403 APPROVER_IS_INITIATOR` | inline error |
| Activation submitted without executive authority co-sign | back end | `401 MISSING_FOUNDER_COSIGN` | open executive authority co-sign route |
| Suspension issued without category co-signer | back end | `401 MISSING_COSIGN` | open co-signer route |
| Return-to-active without resolution evidence | back end | `400 RESOLUTION_EVIDENCE_MISSING` | inline error |
| Mutation in `suspended` state | back end | `403 TENANT_SUSPENDED_NO_MUTATIONS_PERMITTED` | banner |
| Mutation in `offboarded` state | back end | `403 TENANT_OFFBOARDED_NO_MUTATIONS_PERMITTED` | banner |
| Offboarding while open studies / grants / delegations / findings | back end | one of `409 OFFBOARDING_BLOCKED_BY_OPEN_STUDIES`, `409 OFFBOARDING_BLOCKED_BY_ACTIVE_COLLABORATIONS`, `409 OFFBOARDING_BLOCKED_BY_OPEN_DELEGATIONS`, `409 OFFBOARDING_BLOCKED_BY_OPEN_FINDINGS` per blocker category | inline list |
| Sanctions hit | back end / scheduler | `422 SANCTIONS_HIT_DETECTED` | banner; SOC alert |
| Pharma licence expired | back end / scheduler | `422 LICENCE_EXPIRED` | banner; URS-30 to RA |
| Residency change during suspension | back end | `409 RESIDENCY_CHANGE_FORBIDDEN_DURING_SUSPENSION` | inline error |
| Audit-write failure mid-decision | back end | `500 AUDIT_TRAIL_WRITE_FAILED` | toast; the regulated decision did NOT commit |

---

## 12. Security, Privacy, and Tenant Isolation

### 12.1 Authentication dependency

URS-08 administrative surfaces are reached only through an authenticated session per URS-01. Every Module 8 mutation goes through the URS-04 Controlled Approval Modal with electronic signature; activation, return-to-active, offboarding completion, residency-change cutover, and post-offboarding legal-mandate access additionally require multi-factor step-up.

### 12.2 Authorisation pipeline

`authenticate hook → tenant hook → rbac hook → context gate hook → module8 hook → esigService.createSignature where applicable → module8 surface action`. Module 8 owns the **tenant hook** position itself: every URS-01..URS-35 module's mutation pipeline consults Module 8's tenant lifecycle state and refuses if the tenant is anything other than `active`.

### 12.3 Tenant isolation

Module 8 is platform-level for the catalogue (across tenants) and tenant-scoped for the per-tenant identity / lifecycle history surfaces. Every tenant-scoped query routes through TDAL with tenant context bound. Cross-tenant cascade events emit in BOTH affected tenants' chains.

### 12.4 Encryption

At rest: KYC packs, beneficial-ownership disclosures, sanctions-screening evidence, MSA / DPA documents may contain personal data and commercially sensitive material; protected by RLS plus KMS at the storage layer; tenant-residency-scoped storage per URS-35. In transit: TLS 1.2 or higher with HSTS preload.

### 12.5 Logging hygiene

Logs scrub passwords, MFA tokens, KYC sensitive-data fields. Structured logs carry the correlation identifier on every request.

### 12.6 Privacy and data residency

Module 8 is the source of truth for tenant data residency. KYC packs and beneficial-ownership disclosures contain regulated personal data and are retained per the residency's privacy regime (GDPR for `eu`, India DPDP for `in`, US state privacy laws and HIPAA where applicable for `us`). DPA terms negotiated at onboarding capture controller / processor relationship and cross-border transfer authorisations (Standard Contractual Clauses for EU export, equivalent mechanisms for other regions).

### 12.7 Periodic access review

Per URS-05 §12.7: the Module 8 administrative roles (`platform_admin`, `super_admin`, `platform_tenant_onboarding_specialist`) are reviewed annually under URS-05's periodic access review apparatus.

### 12.8 Periodic audit-trail review

Per URS-06 DEC-06-14: high-risk Module 8 events triaged within one business day: `TENANT_SUSPENSION_ISSUED` (especially `regulatory_concern` and `security_incident`), `TENANT_OFFBOARDED`, `OFFBOARDED_TENANT_DATA_ACCESS`, `RESIDENCY_CHANGE_CUTOVER_COMPLETED`, `SANCTIONS_HIT_DETECTED`, `LICENCE_EXPIRED`.

### 12.9 Security-operations alert thresholds

| Pattern | Threshold | Severity | Channel |
|---|---|---|---|
| `SANCTIONS_HIT_DETECTED` | any single event | critical | SOC chat + executive authority e-mail + legal counsel |
| `LICENCE_EXPIRED` | any single event | high | SOC chat + RA Lead |
| `TENANT_SUSPENSION_ISSUED` reason `security_incident` | any single event | critical | SOC chat + IS Lead + executive authority |
| `TENANT_SUSPENSION_ISSUED` reason `regulatory_concern` | any single event | high | SOC chat + RA Lead + executive authority |
| `OFFBOARDED_TENANT_DATA_ACCESS` | any single event | informational (real-time) | SOC chat + former tenant notification |
| `RESIDENCY_CHANGE_CUTOVER_COMPLETED` | any single event | informational (real-time) | SOC chat |
| `KYC_REVERIFICATION_FAILED` | any single event | high | SOC chat + RA Lead |
| `PLATFORM_TENANT_ACCESS_USED` for Module 8 | any single event | informational (real-time) | SOC chat |
| `OFFBOARDING_BLOCKED_BY_OPEN_STUDIES` / `OFFBOARDING_BLOCKED_BY_ACTIVE_COLLABORATIONS` / `OFFBOARDING_BLOCKED_BY_OPEN_DELEGATIONS` / `OFFBOARDING_BLOCKED_BY_OPEN_FINDINGS` cluster | multiple blockers across categories same tenant | medium | SOC e-mail digest |

### 12.10 Self-modification block

Activation initiator cannot also be the approver (`APPROVER_IS_INITIATOR`). The executive authority co-sign is structurally separate (Founder is not a platform administrator). Tenant administrator cannot complete activation, suspension, return-to-active, residency-change cutover, or offboarding alone — executive authority co-sign is mandatory at all three lifecycle gates per DEC-08-04.

### 12.11 Secure export

Every export routes through the Controlled Approval Modal. Signed download URLs with 15-minute TTL (24-hour TTL for the offboarding export bundle per DEC-08-15). Integrity manifest accompanies every export per URS-06.

### 12.12 Cross-border data transfer posture

Cross-border data transfers are governed by the residency selection (DEC-08-05) and the DPA. Cross-region replication is permitted only for backup / DR per URS-35; active read / write traffic stays within the selected region. Residency-change migration is the only authorised path to move data across regions, and it requires executive authority approval, customer notification, and post-cutover validation. EU residency tenants exporting to other regions require Standard Contractual Clauses or equivalent mechanism in the DPA; India residency tenants exporting per DPDP Act 2023 cross-border rules.

---

## 13. Data Integrity and ALCOA+ Controls

| Principle | Module 8 control | Requirement | Verification |
|---|---|---|---|
| Attributable | Every tenant lifecycle event records the signing user(s); platform identities and Founder distinct | URS-08-AUD-001 | Integration test |
| Legible | Tenant detail rendered in structured form; exports in PDF + JSON | URS-08-REP-001 | Export test |
| Contemporaneous | Server-set timestamps; client-supplied dropped | URS-08-AUD-002 | Integration test |
| Original | Append-only lifecycle events; KYC packs versioned per re-verification cycle; entitlements versioned | URS-08-AUD-003 | Validation test |
| Accurate | Three-signature gates at activation; pre-offboarding gate; KYC verifications by independent providers | URS-08-DATA-001 | Validation test |
| Complete | Every event in §6.6 has at least one writer | URS-08-AUD-004 | Validation test |
| Consistent | URS-06 chain genesis at tenant record creation (`pending` state — sequence 1); chain sealing at offboarding; cross-tenant cascade preserves both-side audit | URS-08-AUD-005 | Concurrency test |
| Enduring | KYC pack 25-year retention; entitlements long-term retention; chain sealing preserves history | URS-08-DATA-002 | Migration test |
| Available | Tenant lifecycle history surface; offboarded export read access for contractual window | URS-08-REP-002 | End-to-end test |

---

## 14. Regulatory Mapping

| Identifier | Control | Regulation / Guidance | Clause | Applicable | Implementation expectation |
|---|---|---|---|---|---|
| RG-08-001 | Audit trail | 21 CFR Part 11 | §11.10(e) | Yes | URS-06 substrate |
| RG-08-002 | Limit access to authorised individuals | 21 CFR Part 11 | §11.10(d) | Yes | Three-signature activation; controlled support posture |
| RG-08-003 | Supplier oversight (the platform is a service provider to tenants; tenant onboarding is the customer-relationship governance) | EU GMP Annex 11 | §3 | Yes | Onboarding KYC pack; signed MSA / DPA |
| RG-08-004 | Validation of computerised systems | EU GMP Annex 11 | §4 | Yes | CSV / CSA pack per §17 |
| RG-08-005 | Records retention | EU GMP Annex 11 | §17 | Yes | Per `retention_defaults_jsonb`; never below regulatory minimum |
| RG-08-006 | Risk-based assurance | FDA Computer Software Assurance for Production and Quality Management System Software, Final Guidance, February 2026 | applicable | Yes | Risk classification per validation pack |
| RG-08-007 | ALCOA+ data integrity | MHRA Data Integrity Guidance (2018) | nine principles | Yes | §13 mapping |
| RG-08-008 | EU AI Act applicability | Regulation (EU) 2024/1689 | Article 3(1) | Not applicable to this module | No AI; documented exclusion |
| RG-08-009 | EU GMP Annex 22 (Draft 2025) | EU GMP Annex 22 | applicable forward-looking | Forward-looking only | No Annex-22-dependent control |
| RG-08-010 | GDPR | Regulation (EU) 2016/679 | applicable | Yes (EU-residency tenants and EU-data-subject coverage) | DPA terms; SCCs for cross-border; DPO involvement; right-to-erasure substrate per URS-06 |
| RG-08-011 | India DPDP Act 2023 | Digital Personal Data Protection Act 2023 | applicable | Yes (India-residency) | DPA terms; cross-border transfer rules |
| RG-08-012 | HIPAA Business Associate Agreement | 45 CFR Parts 160-164 | applicable | Conditional (US tenants handling PHI) | BAA terms in DPA |
| RG-08-013 | Sanctions compliance | OFAC, EU sanctions, UK HMT sanctions, UN Security Council consolidated list | applicable | Yes | Sanctions screening at onboarding + quarterly re-screening |
| RG-08-014 | Anti-money-laundering KYC | per jurisdiction (FinCEN, EU AMLD, India PMLA) | applicable | Yes (where the tenant relationship is regulated as a financial relationship) | KYC pack per DEC-08-13 |
| RG-08-015 | ISO/IEC 27001 / 27701 | A-series controls / Privacy extension | applicable | Yes | Tenant lifecycle access control; DPA |
| RG-08-016 | FDA establishment registration | 21 CFR Part 207 | §207.49 | Yes (US pharma tenants) | Pharma-licence verification at onboarding |
| RG-08-017 | EMA marketing authorisation | EU pharma framework | applicable | Yes (EU pharma tenants) | Pharma-licence verification |
| RG-08-018 | India CDSCO drug manufacturing licence — D&C Act 1940 + Drugs Rules 1945 + Revised Schedule M (where manufacturing scope) + CDSCO product registration / approval references (where product master scope) | India Drugs and Cosmetics Act 1940; Drugs Rules 1945; Revised Schedule M; CDSCO licence forms (Form 25 / Form 28 where manufacturing site licensing in scope) | Applicable per India tenant operation and jurisdictional regulatory assessment | Yes (India pharma tenants) | Pharma-licence verification at onboarding (CDSCO licence references captured in `tenant_pharma_licence_records`); external jurisdictional legal / RA confirmation required for clause / form applicability per India tenant scope |
| RG-08-019 | MHRA wholesale dealer's licence | UK Human Medicines Regulations 2012 | applicable | Conditional | Pharma-licence verification |
| RG-08-020 | Health Canada DEL | Canadian Food and Drugs Act | applicable | Conditional | Pharma-licence verification |
| RG-08-021 | EU Schrems II / Standard Contractual Clauses | C-311/18 + EDPB Recommendations | applicable | Yes (cross-border transfer from EU) | DPA terms include SCCs |

### 14.1 Predicate-rule applicability matrix

| Record / artifact | Predicate-rule basis | Part 11 applicable? | Retention | Owner | Evidence |
|---|---|---|---|---|---|
| Tenant record (lifecycle states) | Customer-relationship + governance evidence | Yes (Part 11 §11.10(e)) | per `retention_defaults_jsonb` | Platform / QA / Founder | Lifecycle event chain audit trail |
| Onboarding KYC pack | Supplier-oversight + AML / KYC evidence | Yes | 25 years per DEC-08-13 | Platform / Legal | KYC pack rows + URS-12 documents |
| Signed MSA | Customer-contract evidence | Yes (operational) | 25 years | Platform / Legal | URS-12 document with signatures |
| Signed DPA | Privacy + cross-border transfer evidence | Yes (operational) | 25 years | Platform / Legal / DPO | URS-12 document with signatures |
| Pharma-licence verification record | Regulated-activity authorisation evidence | Yes | per licence retention | Platform / RA | Per-licence record + provider evidence |
| Sanctions-screening record | Sanctions compliance evidence | Yes | 7 years | Platform / Legal / IS Lead | Per-screening record + provider evidence |
| Tenant suspension record | Operational-pause evidence | Yes (operational) | retain (long-term) | Platform / Founder | Per-suspension record + signatures |
| Tenant offboarding record | Termination + data-export evidence | Yes | retain (long-term) | Platform / Founder | Per-offboarding record + chain sealing |
| Founder activation memo | Customer-acceptance evidence | Yes | 25 years | Founder | URS-12 memo with Founder signature |
| Vertical-specific risk register (high-risk vertical) | Risk-acceptance evidence | Yes | 25 years | Founder + QA | URS-12 register with Founder signature |
| Residency-change record | Cross-border data movement evidence | Yes | retain (long-term) | Platform / Founder / DPO | Per-residency-change record + cutover signatures |
| Entitlement version | Contract-amendment evidence | Yes | retain (long-term) | Platform / Legal / executive authority for high-risk | Per-version row + MSA amendment + signatures |

---

## 15. URS Requirements Register

### 15.1 Front-end (FE)

- URS-08-FE-001 — Onboarding wizard MUST surface live KYC provider integration and require evidence-document linkage at each step. Priority MUST. Risk HIGH. Maps RG-08-002, RG-08-003, RG-08-013, RG-08-014.
- URS-08-FE-002 — Activation surface MUST present three-signature gate with each signer's status. Priority MUST. Risk HIGH. Maps RG-08-002.
- URS-08-FE-003 — Suspension surface MUST require categorised reason picker and surface per-category co-sign requirements. Priority MUST. Risk HIGH.
- URS-08-FE-004 — Pre-offboarding gate MUST surface remediation list with deep-links to URS-07 / URS-05 / URS-12..URS-34. Priority MUST. Risk HIGH.
- URS-08-FE-005 — Offboarding export bundle download MUST use 24-hour TTL signed URL. Priority MUST. Risk MEDIUM.
- URS-08-FE-006 — Residency-change orchestration MUST present preparation-window timer and cutover gate. Priority MUST. Risk HIGH.
- URS-08-FE-007 — Cross-tenant cascade events MUST be surfaced to both affected tenant administrators in real time. Priority MUST. Risk HIGH.
- URS-08-FE-008 — Per-tenant tenant-administrator surface MUST present read-only identity post-activation; suspension banner during suspension. Priority MUST. Risk MEDIUM.
- URS-08-FE-009 — Post-offboarding export read surface MUST authenticate former tenant administrator with limited credentials and clearly indicate `offboarded` state. Priority MUST. Risk HIGH.
- URS-08-FE-010 — All Module 8 surfaces MUST meet WCAG 2.1 Level AA. Priority MUST. Risk MEDIUM.
- URS-08-FE-011 — Every route in §5.1 MUST be registered in the application router before release. Priority MUST. Risk LOW.

### 15.2 Back-end (BE)

- URS-08-BE-001 — Tenant activation MUST require three independent electronic signatures (initiating platform admin, approving platform admin, executive authority) per BR-08-01. Priority MUST. Risk CRITICAL.
- URS-08-BE-002 — All seven onboarding prerequisites MUST be satisfied before `in_setup → active`. Priority MUST. Risk CRITICAL.
- URS-08-BE-003 — Suspension cascades to cross-tenant collaboration grants per DEC-08-17 in lockstep. Priority MUST. Risk HIGH.
- URS-08-BE-004 — Pre-offboarding cross-module gate MUST clear all blockers per DEC-08-08. Priority MUST. Risk HIGH.
- URS-08-BE-005 — Offboarding completion requires three signatures (tenant admin, platform admin, executive authority co-sign). Priority MUST. Risk CRITICAL.
- URS-08-BE-006 — Chain sealing at offboarding fires URS-06's `TENANT_CHAINS_SEALED_AT_OFFBOARDING`. Priority MUST. Risk CRITICAL.
- URS-08-BE-007 — Post-offboarding Verixa access restricted to legal mandate (Founder + IS Lead co-sign), tenant export read access, integrity verification (chain hashes only). Priority MUST. Risk CRITICAL.
- URS-08-BE-008 — Residency-change migration requires executive authority approval, 30-day preparation, dual-residency operation, integrity verification at both regions, cutover co-sign, customer notification. Priority MUST. Risk HIGH.
- URS-08-BE-009 — KYC re-verification MUST run automatically per DEC-08-14 cadence; failures trigger `regulatory_concern` suspension after grace window. Priority MUST. Risk HIGH.
- URS-08-BE-010 — Tenant entitlements MUST be set at activation and changed only through MSA amendment; high-risk entitlements require executive authority co-sign. Priority MUST. Risk HIGH.
- URS-08-BE-011 — Founder-explicit-review high-risk vertical tenants require risk register and acceptance memo before activation. Priority MUST. Risk HIGH.
- URS-08-BE-012 — Tenant lifecycle events emit dual audit per DEC-08-18 (tenant chain + global chain). Priority MUST. Risk HIGH.
- URS-08-BE-013 — Sub-tenant hierarchy is forward roadmap per DEC-08-11. Priority MUST. Risk LOW.
- URS-08-BE-014 — Tenant record creation (entering `pending` state) triggers URS-06 per-tenant chain genesis at sequence 1, so every pre-activation lifecycle event is captured in the chain. Priority MUST. Risk CRITICAL.
- URS-08-BE-015 — Post-offboarding export read access for contractual window default 7 years. Priority MUST. Risk MEDIUM.
- URS-08-BE-016 — Verixa retains tenant chains for URS-06 retention class regardless of offboarding. Priority MUST. Risk HIGH.
- URS-08-BE-017 — Offboarded tenant data access by Verixa is itself audited and reported to former tenant. Priority MUST. Risk HIGH.
- URS-08-BE-018 — `offboarded → active` is forbidden; re-engagement is a new tenant with successor reference. Priority MUST. Risk MEDIUM.
- URS-08-BE-019 — Audit-log writes atomic with originating action per URS-04 BR-04-15. Priority MUST. Risk CRITICAL.
- URS-08-BE-020 — Tenant lifecycle hook consumed by every URS-01..URS-35 module's mutation pipeline. Priority MUST. Risk CRITICAL.

### 15.3 Workflow (WF)

- URS-08-WF-001 — Tenant lifecycle state machine per Diagram 6.1-B. Priority MUST. Risk CRITICAL.
- URS-08-WF-002 — Suspension state machine: `active` → `suspended` → `active` OR `in_offboarding`. Priority MUST. Risk HIGH.
- URS-08-WF-003 — Offboarding state machine: `initiated` → `gate_pending` → `gate_cleared` → `export_composed` → `signed` → `chain_sealed` → `offboarded`. Priority MUST. Risk HIGH.
- URS-08-WF-004 — Residency-change state machine: `requested` → `approved` → `dual_operation` → `cutover_completed`. Priority MUST. Risk HIGH.
- URS-08-WF-005 — KYC re-verification annual / quarterly schedules per DEC-08-14. Priority MUST. Risk HIGH.

### 15.4 Data (DATA)

- URS-08-DATA-001 — Tenant record schema fixed per DEC-08-01. Priority MUST. Risk CRITICAL.
- URS-08-DATA-002 — KYC packs versioned per re-verification cycle; 25-year retention for activation pack. Priority MUST. Risk HIGH.
- URS-08-DATA-003 — Per-suspension and per-offboarding records preserve history. Priority MUST. Risk HIGH.

### 15.5 Security (SEC)

- URS-08-SEC-001 — Tenant isolation via TDAL + RLS where tenant-scoped; platform-scoped catalogue accessible only to platform identity. Priority MUST. Risk CRITICAL.
- URS-08-SEC-002 — Multi-factor step-up required for activation, return-to-active, offboarding completion, residency cutover, post-offboarding legal-mandate access. Priority MUST. Risk HIGH.
- URS-08-SEC-003 — Self-modification block: activation initiator cannot also be approver. Priority MUST. Risk HIGH.
- URS-08-SEC-004 — Cross-border data transfer governance per DPA terms; Standard Contractual Clauses for EU export. Priority MUST. Risk HIGH.
- URS-08-SEC-005 — Sanctions-hit handling: immediate suspension with reason `regulatory_concern`. Priority MUST. Risk HIGH.

### 15.6 Audit (AUD)

- URS-08-AUD-001 — Every Module 8 mutation produces an audit row through URS-06. Priority MUST. Risk CRITICAL.
- URS-08-AUD-002 — Server-set timestamps; client-supplied dropped. Priority MUST. Risk HIGH.
- URS-08-AUD-003 — Append-only lifecycle events; per-cycle KYC pack versioning. Priority MUST. Risk HIGH.
- URS-08-AUD-004 — Every event in §6.6 has at least one writer + regression test. Priority MUST. Risk HIGH.
- URS-08-AUD-005 — Cross-tenant cascade emits in BOTH tenants' chains. Priority MUST. Risk HIGH.

### 15.7 AI / HITL (AI)

- URS-08-AI-001 — Module 8 contains no AI / ML components in core path; static analysis MUST find zero LLM SDK references. Priority MUST. Risk HIGH.
- URS-08-AI-002 — AI suggestions in onboarding (e.g., vertical classification suggestions) MUST set `ai_advisory = true`. Priority MUST. Risk HIGH.

### 15.8 Integration (INT)

- URS-08-INT-001 — URS-06 chain genesis at tenant record creation (`pending` state — sequence 1); chain sealing at offboarding. Priority MUST. Risk CRITICAL.
- URS-08-INT-002 — URS-07 cross-tenant collaboration prerequisite consumed at every collaboration lifecycle event. Priority MUST. Risk HIGH.
- URS-08-INT-003 — URS-12 holds onboarding documents (MSA, DPA, KYC pack, executive authority memos). Priority MUST. Risk HIGH.
- URS-08-INT-004 — URS-30 delivers notifications. Priority MUST. Risk MEDIUM.
- URS-08-INT-005 — URS-35 owns residency-scoped storage; dual-residency operation during cutover. Priority MUST. Risk HIGH.
- URS-08-INT-006 — Three independent KYC providers per DEC-08-19. Priority MUST. Risk HIGH.

### 15.9 Reporting (REP)

- URS-08-REP-001 — Every report in §9 MUST be exportable with electronic signature and integrity manifest. Priority MUST. Risk MEDIUM.
- URS-08-REP-002 — Offboarding export bundle 24-hour TTL signed URL with integrity manifest. Priority MUST. Risk HIGH.
- URS-08-REP-003 — Per-tenant lifecycle history exportable to tenant administrator and auditor. Priority MUST. Risk MEDIUM.

### 15.10 Notifications (NOTIF)

- URS-08-NOTIF-001 — Every notification in §10 delivered through URS-30 with specified latency. Priority MUST. Risk MEDIUM.
- URS-08-NOTIF-002 — Cross-tenant cascade notifications reach both tenants. Priority MUST. Risk HIGH.
- URS-08-NOTIF-003 — Customer notification within 24 hours per privacy policy for residency change cutover and post-offboarding access. Priority MUST. Risk HIGH.

### 15.11 Validation (VAL)

- URS-08-VAL-001 — Test execution covers IQ (schema, RLS, indexes, constraints, lifecycle bootstrap), OQ (per URS-08-VAL-002), PQ (per URS-08-VAL-003), regression (per URS-08-VAL-004).
- URS-08-VAL-002 — OQ validates every API endpoint, every error code, every state transition, every audit event writer.
- URS-08-VAL-003 — PQ validates onboarding-to-activation flow under representative tenant volume; offboarding export bundle composition under representative data volume.
- URS-08-VAL-004 — Regression on every Class 1 / Class 2 change.
- URS-08-VAL-005 — Requirements-to-test traceability per §16.4.
- URS-08-VAL-006 — Supplier qualification pack per §17.1.
- URS-08-VAL-007 — Inspection-ready evidence index per §17.2.
- URS-08-VAL-008 — Migration evidence gate: schema migrations idempotent; lifecycle bootstrap creates valid `pending` tenant with all signatures recorded; restore drill verifies tenant lifecycle integrity; chain genesis / sealing reproducible.

---

## 16. Acceptance Criteria and Test Cases

### 16.1 Plain-language test cases

- TC-PLAIN-001 — A new pharma tenant cannot be activated without legal-entity verification, pharma-licence verification, signed MSA and DPA, residency selection, regulatory framework defaults, and an initial admin.
- TC-PLAIN-002 — Tenant activation requires three independent signatures: initiating platform admin, approving platform admin, and Founder.
- TC-PLAIN-003 — A high-risk vertical tenant (cell-and-gene therapy, sterile injectables, etc.) requires explicit executive authority review including a risk register and acceptance memo.
- TC-PLAIN-004 — A suspended tenant cannot mutate any record; reads continue for inspection.
- TC-PLAIN-005 — When a lead tenant is suspended, all cross-tenant collaborations involving it are suspended in lockstep.
- TC-PLAIN-006 — Returning a tenant from suspension to active requires the per-category co-sign (RA Lead for regulatory; IS Lead for security) plus executive authority co-sign.
- TC-PLAIN-007 — Offboarding cannot complete while open studies, active collaborations, open delegations, or open critical findings remain on the tenant.
- TC-PLAIN-008 — Offboarding produces a comprehensive data export bundle with integrity manifest signed by both tenant and Verixa, with executive authority co-sign.
- TC-PLAIN-009 — Once a tenant is offboarded, no Verixa user can access tenant content except for documented legal mandate (Founder + IS Lead co-sign), the tenant's own export read access, or chain integrity verification.
- TC-PLAIN-010 — Residency change requires executive authority approval, 30-day customer preparation, integrity verification at both regions, and Founder + platform-admin co-sign at cutover.
- TC-PLAIN-011 — Annual KYC re-verification can detect an expired pharma licence and trigger `regulatory_concern` suspension.
- TC-PLAIN-012 — Sanctions hits trigger immediate suspension and Founder + legal review.
- TC-PLAIN-013 — Clinical types are disabled by default at every tenant; activation requires executive authority co-sign and tenant supplemental contract terms.
- TC-PLAIN-014 — A re-engaging former tenant onboards as a new tenant; the offboarded predecessor is referenced but not re-activated.

### 16.2 Technical test cases

- TC-TECH-001 — Activation without all seven prerequisites returns `409 ONBOARDING_PREREQUISITE_NOT_SATISFIED` with the specific missing item enumerated.
- TC-TECH-002 — Activation initiator equal to approver returns `403 APPROVER_IS_INITIATOR`.
- TC-TECH-003 — Activation without executive authority co-sign returns `401 MISSING_FOUNDER_COSIGN`.
- TC-TECH-004 — Suspension without per-category co-sign returns `401 MISSING_COSIGN`.
- TC-TECH-005 — Mutation while suspended returns `403 TENANT_SUSPENDED_NO_MUTATIONS_PERMITTED`.
- TC-TECH-006 — Mutation while offboarded returns `403 TENANT_OFFBOARDED_NO_MUTATIONS_PERMITTED`.
- TC-TECH-007 — Offboarding while open studies exist returns `409 OFFBOARDING_BLOCKED_BY_OPEN_STUDIES` with study list.
- TC-TECH-008 — Offboarding while active cross-tenant grants exist returns `409 OFFBOARDING_BLOCKED_BY_ACTIVE_COLLABORATIONS` with grant list.
- TC-TECH-009 — Offboarding while delegations cross tenant boundary returns `409 OFFBOARDING_BLOCKED_BY_OPEN_DELEGATIONS`.
- TC-TECH-010 — Offboarding while open critical findings exist returns `409 OFFBOARDING_BLOCKED_BY_OPEN_FINDINGS`.
- TC-TECH-011 — Offboarding completion without executive authority co-sign returns `401 MISSING_FOUNDER_COSIGN`.
- TC-TECH-012 — Chain sealing emits `TENANT_CHAINS_SEALED_AT_OFFBOARDING` per URS-06 BR-06-17.
- TC-TECH-013 — Suspension cascades cross-tenant collaboration grants in lockstep; each cascade emits in both tenant chains.
- TC-TECH-014 — Resumption-cascade re-activates suspended grants only when both tenants are `active`.
- TC-TECH-015 — Residency change during suspension returns `409 RESIDENCY_CHANGE_FORBIDDEN_DURING_SUSPENSION`.
- TC-TECH-016 — Residency-change cutover emits `RESIDENCY_CHANGE_CUTOVER_COMPLETED` only after dual-region integrity verification passes.
- TC-TECH-017 — Annual KYC re-verification of expired pharma licence triggers `LICENCE_EXPIRED` and after grace window triggers `regulatory_concern` suspension.
- TC-TECH-018 — Sanctions-screening hit triggers `SANCTIONS_HIT_DETECTED` and immediate suspension.
- TC-TECH-019 — `offboarded → active` transition refused with state error.
- TC-TECH-020 — Schema migrations idempotent; RLS enabled where applicable.
- TC-TECH-021 — Penetration test: cross-tenant query without break-glass returns RLS-empty.
- TC-TECH-022 — Penetration test: post-offboarding access without Founder + IS Lead co-sign returns `403`.
- TC-TECH-023 — Tenant lifecycle event emits dual audit (tenant chain + global chain) per DEC-08-18.
- TC-TECH-024 — Static analysis finds zero LLM SDK references in Module 8.
- TC-TECH-025 — Tenant record creation (entering `pending` state) triggers URS-06 per-tenant chain genesis row at sequence 1.
- TC-TECH-026 — Founder-explicit-review high-risk vertical tenant cannot reach executive authority co-sign without risk register and acceptance memo linked.
- TC-TECH-027 — Offboarding export bundle TTL is 24 hours; integrity manifest contains Merkle proofs to per-tenant root and global anchor per URS-06 BR-06-10.
- TC-TECH-028 — Cross-tenant cascade resumption skips offboarded partner tenants (cannot resume after partner offboarding).
- TC-TECH-029 — Three independent KYC providers consulted at onboarding; verdicts logged separately.

### 16.3 Acceptance criteria (Given / When / Then)

- AC-08-FUN-01 — Given tenant activation attempted with missing prerequisite, When called, Then `409 ONBOARDING_PREREQUISITE_NOT_SATISFIED`.
- AC-08-FUN-02 — Given activation initiator and approver are the same user, When called, Then `403 APPROVER_IS_INITIATOR`.
- AC-08-FUN-03 — Given executive authority co-sign missing, When activation submitted, Then `401 MISSING_FOUNDER_COSIGN`.
- AC-08-FUN-04 — Given tenant in `suspended`, When mutation attempted, Then `403 TENANT_SUSPENDED_NO_MUTATIONS_PERMITTED`.
- AC-08-FUN-05 — Given lead tenant suspension, When applied, Then all cross-tenant grants involving the tenant are suspended in lockstep with audit in both chains.
- AC-08-FUN-06 — Given offboarding attempted while blockers exist, When called, Then `409` with one of `OFFBOARDING_BLOCKED_BY_OPEN_STUDIES`, `OFFBOARDING_BLOCKED_BY_ACTIVE_COLLABORATIONS`, `OFFBOARDING_BLOCKED_BY_OPEN_DELEGATIONS`, `OFFBOARDING_BLOCKED_BY_OPEN_FINDINGS` per blocker category, with remediation list.
- AC-08-FUN-07 — Given offboarding completion, When all three signatures captured, Then `TENANT_CHAINS_SEALED_AT_OFFBOARDING` emitted and tenant moves to `offboarded`.
- AC-08-FUN-08 — Given `offboarded` state, When mutation attempted, Then `403 TENANT_OFFBOARDED_NO_MUTATIONS_PERMITTED`.
- AC-08-PERM-01 — Given non-executive-authority, When attempting activation co-sign, Then `403`.
- AC-08-PERM-02 — Given non-platform identity, When attempting Module 8 administrative endpoints, Then `403`.
- AC-08-AUD-01 — Every Module 8 mutation produces an audit row through URS-06 in both tenant chain and global chain.
- AC-08-AUD-02 — Audit-write failure rolls back originating action.
- AC-08-DI-01 — Tenant record creation (entering `pending` state) creates URS-06 per-tenant chain genesis row at sequence 1.
- AC-08-DI-02 — Backup-restore drill produces same lifecycle history and chain HEAD as source.
- AC-08-INT-01 — URS-06 chain genesis at tenant record creation (`pending` state — sequence 1); chain sealing at offboarding.
- AC-08-INT-02 — URS-07 cross-tenant collaboration prerequisite enforced at every grant lifecycle event.
- AC-08-INT-03 — URS-30 delivers all notifications.
- AC-08-INT-04 — URS-35 dual-residency operation during cutover; integrity verification at both regions.
- AC-08-REP-01 — Every export carries integrity manifest + electronic signature + executive authority co-sign where required.
- AC-08-AI-01 — Static analysis finds zero LLM SDK references.
- AC-08-NEG-01 — Every error code in §11.2 reachable by automated test.
- AC-08-PERF-01 — Tenant onboarding wizard p95 ≤ 3 s per step (excluding KYC provider response).
- AC-08-PERF-02 — Offboarding export bundle composition ≤ 1 hour for representative tenant volume.
- AC-08-SEC-01 — Penetration test: cross-tenant query without active collaboration returns RLS-empty.
- AC-08-SEC-02 — Penetration test: post-offboarding access without Founder + IS Lead co-sign blocked.
- AC-08-MIG-01 — Module 8 migrations idempotent.
- AC-08-MIG-02 — Migrations bootstrap valid `pending` tenant fixture; restore drill reproducible.

### 16.4 Requirements-to-test traceability

| Requirement | Plain-language | Technical | Given / When / Then |
|---|---|---|---|
| URS-08-FE-001 | TC-PLAIN-001 | TC-TECH-001, TC-TECH-029 | AC-08-FUN-01 |
| URS-08-FE-002 | TC-PLAIN-002 | TC-TECH-002, TC-TECH-003 | AC-08-FUN-02, AC-08-FUN-03 |
| URS-08-FE-003 | — | TC-TECH-004 | AC-08-FUN-04 |
| URS-08-FE-004 | TC-PLAIN-007 | TC-TECH-007..010 | AC-08-FUN-06 |
| URS-08-FE-005 | TC-PLAIN-008 | TC-TECH-027 | — |
| URS-08-FE-006 | TC-PLAIN-010 | TC-TECH-016 | — |
| URS-08-FE-007 | TC-PLAIN-005 | TC-TECH-013 | AC-08-FUN-05 |
| URS-08-FE-008 | — | TC-TECH-005 | AC-08-FUN-04 |
| URS-08-FE-009 | TC-PLAIN-009 | TC-TECH-022 | — |
| URS-08-FE-010 | — | (accessibility test) | — |
| URS-08-FE-011 | — | TC-TECH-020 | — |
| URS-08-BE-001 | TC-PLAIN-002 | TC-TECH-002, TC-TECH-003 | AC-08-FUN-02, AC-08-FUN-03 |
| URS-08-BE-002 | TC-PLAIN-001 | TC-TECH-001 | AC-08-FUN-01 |
| URS-08-BE-003 | TC-PLAIN-005 | TC-TECH-013 | AC-08-FUN-05 |
| URS-08-BE-004 | TC-PLAIN-007 | TC-TECH-007..010 | AC-08-FUN-06 |
| URS-08-BE-005 | TC-PLAIN-008 | TC-TECH-011 | AC-08-FUN-07 |
| URS-08-BE-006 | TC-PLAIN-008 | TC-TECH-012 | AC-08-FUN-07 |
| URS-08-BE-007 | TC-PLAIN-009 | TC-TECH-022 | — |
| URS-08-BE-008 | TC-PLAIN-010 | TC-TECH-015, TC-TECH-016 | — |
| URS-08-BE-009 | TC-PLAIN-011 | TC-TECH-017 | — |
| URS-08-BE-010 | TC-PLAIN-013 | (entitlement amendment test) | — |
| URS-08-BE-011 | TC-PLAIN-003 | TC-TECH-026 | — |
| URS-08-BE-012 | — | TC-TECH-023 | AC-08-AUD-01 |
| URS-08-BE-013 | — | (sub-tenant gating test) | — |
| URS-08-BE-014 | — | TC-TECH-025 | AC-08-DI-01 |
| URS-08-BE-015 | — | (export read access test) | — |
| URS-08-BE-016 | — | (URS-06 retention test) | — |
| URS-08-BE-017 | TC-PLAIN-009 | TC-TECH-022 | — |
| URS-08-BE-018 | TC-PLAIN-014 | TC-TECH-019 | — |
| URS-08-BE-019 | — | TC-TECH-020 | AC-08-AUD-02 |
| URS-08-BE-020 | TC-PLAIN-004 | TC-TECH-005, TC-TECH-006 | AC-08-FUN-04, AC-08-FUN-08 |
| URS-08-WF-001 | — | TC-TECH-019 | — |
| URS-08-WF-002 | TC-PLAIN-006 | TC-TECH-004 | — |
| URS-08-WF-003 | TC-PLAIN-008 | TC-TECH-011, TC-TECH-012 | AC-08-FUN-07 |
| URS-08-WF-004 | TC-PLAIN-010 | TC-TECH-015, TC-TECH-016 | — |
| URS-08-WF-005 | TC-PLAIN-011 | TC-TECH-017 | — |
| URS-08-DATA-001 | — | TC-TECH-020 | — |
| URS-08-DATA-002 | — | (KYC re-verification retention test) | — |
| URS-08-DATA-003 | — | TC-TECH-020 | — |
| URS-08-SEC-001 | — | TC-TECH-020, TC-TECH-021 | AC-08-SEC-01 |
| URS-08-SEC-002 | — | (MFA step-up test) | — |
| URS-08-SEC-003 | TC-PLAIN-002 | TC-TECH-002 | AC-08-FUN-02 |
| URS-08-SEC-004 | TC-PLAIN-010 | (DPA / SCC test) | — |
| URS-08-SEC-005 | TC-PLAIN-012 | TC-TECH-018 | — |
| URS-08-AUD-001 | — | TC-TECH-023 | AC-08-AUD-01 |
| URS-08-AUD-002 | — | (server timestamp test) | — |
| URS-08-AUD-003 | — | TC-TECH-020 | — |
| URS-08-AUD-004 | — | (writer-presence test) | — |
| URS-08-AUD-005 | TC-PLAIN-005 | TC-TECH-013 | AC-08-FUN-05 |
| URS-08-AI-001 | — | TC-TECH-024 | AC-08-AI-01 |
| URS-08-AI-002 | — | (URS-32 integration test) | — |
| URS-08-INT-001 | TC-PLAIN-008 | TC-TECH-012, TC-TECH-025 | AC-08-INT-01 |
| URS-08-INT-002 | TC-PLAIN-005 | TC-TECH-013 | AC-08-INT-02 |
| URS-08-INT-003 | TC-PLAIN-001 | (URS-12 linkage test) | — |
| URS-08-INT-004 | — | (notification test) | AC-08-INT-03 |
| URS-08-INT-005 | TC-PLAIN-010 | TC-TECH-016 | AC-08-INT-04 |
| URS-08-INT-006 | TC-PLAIN-001 | TC-TECH-029 | — |
| URS-08-REP-001 | — | TC-TECH-027 | AC-08-REP-01 |
| URS-08-REP-002 | TC-PLAIN-008 | TC-TECH-027 | — |
| URS-08-REP-003 | — | (export test) | — |
| URS-08-NOTIF-001 | — | (notification test) | — |
| URS-08-NOTIF-002 | TC-PLAIN-005 | TC-TECH-013 | — |
| URS-08-NOTIF-003 | TC-PLAIN-010 | TC-TECH-016 | — |
| URS-08-VAL-001 | — | TC-TECH-020 | — |
| URS-08-VAL-002 | All applicable | All applicable | All applicable |
| URS-08-VAL-003 | — | (PQ test) | AC-08-PERF-01, AC-08-PERF-02 |
| URS-08-VAL-004 | — | full TC-TECH suite | — |
| URS-08-VAL-005 | — | this table is the seed | — |
| URS-08-VAL-006 | — | (supplier qualification) | — |
| URS-08-VAL-007 | — | (evidence index) | — |
| URS-08-VAL-008 | — | TC-TECH-020 | AC-08-MIG-01, AC-08-MIG-02 |

---

## 17. Validation and CSV/CSA Evidence Expectations

| Item | Required evidence |
|---|---|
| URS traceability | Per §16.4 |
| Risk assessment | GAMP 5 risk register; risk-based assurance per FDA CSA |
| Configuration specification | Documented seed of `tenants` table fixtures (including a `pending` tenant for IQ); seed of high-risk vertical list; KYC provider catalogue |
| Functional specification | Matches §6 |
| Design specification | Matches §6.1–§6.4 |
| Test protocols | IQ (schema, RLS, indexes, constraints, lifecycle bootstrap, KYC fixture seed); OQ per URS-08-VAL-002; PQ per URS-08-VAL-003; regression per URS-08-VAL-004 |
| Test evidence | Pass / fail per protocol step, traced to requirement |
| Defect log | Defects mapped to URS requirements |
| Requirements traceability matrix | Per §16.4 |
| Release approval | Electronically signed by Quality Lead, Validation Lead, Information Security Lead, Regulatory Affairs Lead, Legal / DPO Lead, executive authority |
| Training record | Engineering, QA, validation, operations, sales-engineering, customer-success, contract counsel trained on Module 8 |
| Periodic review | Annual per Annex 11 §11; trigger reviews on every Class 1 / Class 2 change |
| Data migration evidence | Backfill of tenant fixtures; KYC pack migrations idempotent; chain genesis / sealing reproducible across restore drill |

### 17.1 Supplier and service-provider qualification pack

| Category | Required evidence |
|---|---|
| Cloud hosting provider | Inherited from URS-01 §17.1 |
| Object-storage / cold-archive provider | Inherited from URS-06 §17.1 |
| Notification provider | Inherited from URS-01 §17.1 |
| Backup / restore provider (URS-35) | Inherited from URS-35 |
| Legal-entity verification provider | Provider qualification pack: data sources, jurisdictional coverage, accuracy SLA, right-to-audit, response-time SLA |
| Pharma-licence verification provider | Provider qualification pack: regulatory authority data sources, jurisdictional coverage, expiry-detection mechanism, right-to-audit |
| Sanctions-screening provider | Provider qualification pack: lists covered (OFAC, EU, UK HMT, UN consolidated), update cadence, false-positive handling, right-to-audit |
| Beneficial-ownership disclosure provider (where outsourced) | KYC AML provider qualification |
| Document e-signature provider (URS-04) | Inherited from URS-04 |
| Security-operations / SIEM | Alert routing per §12.9 |

### 17.2 Inspection-ready evidence index

| Evidence item | Owner | Location / system of record | Retention | Linked requirement | Inspection use |
|---|---|---|---|---|---|
| Tenant record (lifecycle states) | Platform / QA | `tenants` + `tenant_lifecycle_events` + URS-06 | per `retention_defaults_jsonb` | URS-08-WF-001 | demonstrate customer relationship governance |
| Tenant lifecycle event chain | Platform / QA | `tenant_lifecycle_events` + URS-06 dual-chain | retain (long-term) | URS-08-AUD-005 | demonstrate every transition with signatures |
| KYC pack per cycle | Platform / Legal / DPO | `tenant_kyc_packs` + URS-12 documents | 25 years | URS-08-DATA-002 | demonstrate KYC compliance |
| Pharma-licence verification records | Platform / RA | `tenant_pharma_licence_records` + URS-12 evidence | per licence retention | URS-08-BE-009 | demonstrate regulated-activity authorisation |
| Sanctions-screening records | Platform / Legal / IS Lead | `tenant_sanctions_screenings` + URS-12 evidence | 7 years | URS-08-SEC-005 | demonstrate sanctions compliance |
| Suspension records | Platform / Founder | `tenant_suspensions` + signatures + resolution evidence | retain (long-term) | URS-08-WF-002 | demonstrate operational pause governance |
| Offboarding records + export bundles | Platform / Founder + Tenant | `tenant_offboarding_runs` + bundle reference + integrity manifest | retain (long-term) | URS-08-WF-003 | demonstrate termination + data-export |
| Founder activation memos | Founder | URS-12 with Founder signature | 25 years | URS-08-BE-011 | demonstrate customer-acceptance |
| Vertical-specific risk registers | Founder + QA | URS-12 with Founder signature | 25 years | URS-08-BE-011 | demonstrate high-risk vertical risk acceptance |
| Residency change records | Platform / Founder / DPO | `tenant_residency_changes` + cutover signatures | retain (long-term) | URS-08-WF-004 | demonstrate cross-border data movement governance |
| Entitlement versions | Platform / Legal / Founder | `tenant_entitlements_versions` + MSA amendments + signatures | retain (long-term) | URS-08-BE-010 | demonstrate contract-amendment trail |
| Cross-tenant cascade log | Platform | `cross_tenant_grant_cascade_log` (in both tenant chains) | retain (long-term) | URS-08-BE-003 | demonstrate cascade compliance |
| Offboarded-tenant post-access log | Founder + IS Lead | `offboarded_tenant_post_access_log` | retain (long-term) | URS-08-BE-007 | demonstrate post-offboarding access governance |
| Validation evidence pack (IQ / OQ / PQ) | Validation | testing system of record | retain per release | URS-08-VAL-001..008 | release approval |
| Release approval (electronically signed) | Founder, QA, RA, Validation, IS, Legal / DPO | URS-12 | retain per release | URS-08-VAL-007 | demonstrate authority chain for release |

---

## 18. Closed Decision and Dependency Register

### 18.1 Closed Launch Decisions Register

| Closed decision | Spec reference |
|---|---|
| Tenant record schema fixed at launch | DEC-08-01 |
| Lifecycle state machine | DEC-08-02 |
| Six onboarding prerequisites | DEC-08-03 |
| executive authority co-sign at three lifecycle gates | DEC-08-04 |
| Data residency launch options | DEC-08-05 |
| Tenant suspension model with categorised reasons | DEC-08-06 |
| Offboarding workflow with comprehensive export | DEC-08-07 |
| Pre-offboarding cross-module gate | DEC-08-08 |
| Entitlements / feature gating registry | DEC-08-09 |
| Residency-change migration path | DEC-08-10 |
| Sub-tenant hierarchy forward roadmap | DEC-08-11 |
| High-risk vertical list with explicit executive authority review | DEC-08-12 |
| Tenant onboarding artifacts retained in URS-12 | DEC-08-13 |
| KYC re-verification cadence | DEC-08-14 |
| Offboarding data export contract | DEC-08-15 |
| Verixa post-offboarding access posture | DEC-08-16 |
| Cross-tenant collaboration cascade | DEC-08-17 |
| Lifecycle events emit dual audit (tenant chain + global chain) | DEC-08-18 |
| Three independent KYC providers minimum | DEC-08-19 |

### 18.2 Dependencies

| ID | Dependency | Source | Impact | Blocking? | Mitigation |
|---|---|---|---|---|---|
| DEP-08-01 | URS-01 authentication, MFA step-up | URS-01 | Substrate | Blocking | none |
| DEP-08-02 | URS-02 base roles | URS-02 | Tenant administrator role | Blocking | none |
| DEP-08-03 | URS-04 e-sig ceremony | URS-04 | Lifecycle / activation / offboarding signatures | Blocking | none |
| DEP-08-04 | URS-05 authority resolver, executive authority | URS-05 | Activation / suspension / offboarding co-signs | Blocking | none |
| DEP-08-05 | URS-06 audit substrate, chain genesis, chain sealing | URS-06 | Audit; chain lifecycle | Blocking | none |
| DEP-08-06 | URS-07 study management cross-tenant grants | URS-07 | Suspension cascade; offboarding gate | Blocking | none |
| DEP-08-07 | URS-12 document control | URS-12 | Onboarding documents (MSA, DPA, KYC, memos) | Blocking | none |
| DEP-08-08 | URS-30 notifications | URS-30 | Lifecycle reminders, escalations | Non-blocking | direct e-mail fallback |
| DEP-08-09 | URS-35 storage / backup / cold storage; residency-scoped | URS-35 | Data residency; DR drill | Blocking for PQ | DR drill |
| DEP-08-10 | External billing system | external | Suspension trigger for `payment_default` | Non-blocking | manual trigger fallback |
| DEP-08-11 | External KYC providers (3 minimum) | external | Onboarding verifications | Blocking | provider qualification pack |

---

## 19. Completeness Checklist

| Item | Yes / No | Evidence |
|---|---|---|
| Controlled-document metadata complete? | Yes | front matter |
| Approval block complete? | Yes (signatures pending) | Document Approval section |
| Version history complete? | Yes | Version History |
| Glossary complete? | Yes | §0.6 |
| Scope complete? | Yes | §2 |
| Roles and permissions complete? | Yes | §3 |
| User journeys complete? | Yes | §4 (28 journeys) |
| Front-end complete? | Yes | §5 |
| Backend complete? | Yes | §6 |
| Data model complete? | Yes | §6.2 |
| APIs complete? | Yes | §6.3 |
| Workflow / lifecycle complete? | Yes | §6.4 |
| Business rules complete? | Yes | §6.5 |
| Audit trail complete? | Yes | §6.6 |
| AI / Human-in-the-Loop complete? | Yes (no AI in core) | §8 |
| Reports complete? | Yes | §9 |
| Notifications complete? | Yes | §10 |
| Cross-module wiring complete? | Yes | §7 |
| Change-impact matrix complete? | Yes | §7.2 |
| Negative paths complete? | Yes | §11 |
| Security / privacy / tenant isolation complete? | Yes | §12 |
| ALCOA+ complete? | Yes | §13 |
| Regulatory mapping complete? | Yes | §14 |
| Predicate-rule applicability matrix complete? | Yes | §14.1 |
| Requirements register complete? | Yes | §15 |
| Acceptance tests complete? | Yes | §16 |
| Requirements-to-test traceability complete? | Yes | §16.4 |
| Validation evidence complete? | Yes | §17 |
| Supplier and service-provider qualification pack complete? | Yes | §17.1 |
| Decisions and dependencies registered (no internal decisions outstanding)? | Yes | §18.1, §18.2 |
| Final quality gate answered? | Yes | §20 |

---

## 20. Final Module Output Quality Gate

**URS approval is separate from validation execution.** This document becomes "Approved Controlled URS — released for engineering implementation and validation planning" upon signature capture in the Document Approval block; it becomes "Released for validation execution" only after URS-08-VAL-008 (Migration Evidence Gate) and the §17 validation evidence pack are satisfied. **No Module 8 internal open questions remain.**

- **Specification ready for engineering review?** Yes — every MUST requirement is declarative, atomic, and testable. Front end, back end, data, APIs, lifecycle, suspension, offboarding, residency-change, entitlements, KYC re-verification, cross-tenant cascade, and integrations are covered as a single self-contained contract.
- **Specification ready for quality validation review?** Yes — IQ/OQ/PQ scope specified; traceability matrix in §16.4; lifecycle bootstrap fixture enumerated.
- **Specification ready for compliance review?** Yes — ALCOA+ table, regulatory mapping (21 CFR Part 11, Annex 11, GDPR, DPDP, HIPAA, sanctions, AML, ISO 27001/27701), predicate-rule applicability matrix populated.
- **Specification ready for legal / privacy review?** Yes — DPA, SCCs, BAA, sanctions, AML, residency, post-offboarding access posture explicitly scoped.
- **Specification ready for inspector / client review?** Yes — every regulated assertion traces to a regulatory clause and to a test case; no internal item remains open.
- **Specification ready for Founder approval?** Yes.
- **Blocking gaps?** None internal. Cross-module dependencies (§18.2) are owned by their named companion modules and tracked at the program level. The Installation Qualification gate URS-08-VAL-008 and the §17 evidence pack govern only the transition to "Released for validation execution".
- **Two-step release path:**
  1. **Approved Controlled URS — released for engineering implementation and validation planning.** Reached upon signature capture.
  2. **Released for validation execution.** Reached after URS-08-VAL-008 is satisfied and the §17 evidence pack is complete.

---

## Appendix A — Tenant Lifecycle Composite

```mermaid
flowchart TD
  A([Onboarding initiated]) --> B[TENANT_ONBOARDING_INITIATED state pending]
  B --> C[Three KYC providers consulted: legal entity + pharma licence + sanctions]
  C --> D[Beneficial ownership disclosed]
  D --> E[MSA + DPA linked]
  E --> F{All seven prerequisites met?}
  F -- no --> G[ONBOARDING_PREREQUISITE_NOT_SATISFIED; remediate]
  G --> C
  F -- yes --> H[TENANT_MOVED_TO_IN_SETUP state in_setup]
  H --> I[Tenant administrator acknowledges + selects residency + sets framework defaults]
  I --> J[Tenant submits for activation]
  J --> K[Three-signature gate: initiating PA + approving PA + executive authority]
  K --> L[High-risk vertical? then risk register + acceptance memo first]
  L --> M[TENANT_ACTIVATED state active — URS-06 chain genesis was emitted earlier at pending creation sequence 1]
  M --> N{Suspension event?}
  N -- yes --> O[TENANT_SUSPENSION_ISSUED state suspended; cross-tenant grants suspended in lockstep]
  O --> P{Resolved?}
  P -- yes --> Q[TENANT_RETURNED_TO_ACTIVE; cross-tenant grants resumed where partner active]
  Q --> N
  P -- no, prolonged --> R[TENANT_OFFBOARDING_INITIATED_BY_PLATFORM]
  N -- no --> S{Tenant requests offboarding?}
  S -- no --> N
  S -- yes --> T[TENANT_OFFBOARDING_INITIATED]
  T --> U[Pre-offboarding gate: studies, collaborations, delegations, findings]
  U --> V{Blockers?}
  V -- yes --> W[Surface remediation list]
  W --> U
  V -- no --> X[Compose comprehensive export bundle 24h TTL]
  X --> Y[Three signatures: tenant + platform admin + executive authority]
  Y --> Z[URS-06 publishes final external anchor; TENANT_CHAINS_SEALED_AT_OFFBOARDING]
  Z --> AA[TENANT_OFFBOARDED state offboarded; tenant retains export read for contractual window; Verixa retains chains for retention class]
  R --> X
```

— End of Module 8 User Requirements Specification —