# Verixa — User Requirements Specification # Module 22: Inspection Management & Readiness | Field | Value | |---|---| | Document ID | VRX-URS-22 | | Version | 1.0 | | Status | Final — ready for QA, Validation, Regulatory Affairs, Information Security, Manufacturing Head, Clinical / PV Head, Site Quality Lead, 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-22-VAL-008) and validation evidence pack are satisfied. | | Document Type | User Requirements Specification (URS) | | GAMP 5 Category | Category 5 — Custom Application | | Code Modules | Target implementation binding: expected primary code module `inspection`, expected API mounts `/api/v1/inspections/*` (canonical plural), expected supporting modules `audit-log`, `context-filter`, `documents`, `authority`, `hitl`, `electronic_signatures`, `ai_requests`, `mira_context_access_log`, `regulatory_inspection_records`, expected event-bus emission for `inspection_calendar_created`, `inspection_calendar_status_changed`, `self_inspection_completed`, `mock_drill_completed`, `readiness_scorecard_generated`, `back_room_request_completed`, `deficiency_response_submitted`, `deficiency_response_accepted`, `deficiency_response_closed`, `commitment_capa_linked`, `lesson_published`, `inspection_response_submitted`, `inspection_closed`, `inspection_reopened`, expected MIRA context integration through the `useMiraRecord('inspection_calendar', id)`, `useMiraRecord('self_inspection', id)`, `useMiraRecord('mock_drill', id)`, `useMiraRecord('back_room_request', id)`, and `useMiraRecord('deficiency_response', id)` mappings, expected findings-source emission consumed by URS-21 (standalone observation findings from FDA 483 / EIR / EU GMP / MHRA / CDSCO inspections), expected CAPA-source emission consumed by URS-18 (`audit_observation` source-type per URS-18 declared source set), expected risk-assessment integration with URS-19 for inspection-precipitated risk records, expected change-control linkage to URS-13 for formula-version changes on readiness scoring rules, expected document-control linkage to URS-12 for back-room retrieval document version provenance, expected Authority Profile + HITL + e-signature integration through the `authority` and `hitl` subsystems for non-bypassable submission, acceptance, verification, publication, archive, closure, and reopen, expected inspection-readiness export consumer pulling from every URS-01.URS-21 / URS-23.URS-35 module, expected platform_admin / super_admin support / break-glass only paths for cross-tenant inspection coordination. Implementation evidence remains subject to repository verification and validation evidence. | | Architecture Bindings | This module is subject to **ARCH-AI-001 AI Optionality and Manual Continuity**. Verixa internally classifies this AI surface as **high-risk under internal AI governance**, aligned with the high-risk classification approach in **EU AI Act (Regulation 2024/1689) Annex III**, unless a jurisdiction-specific legal assessment determines otherwise — escalated under Annex III where AI output supports direct regulator-facing response (FDA / EMA / MHRA / CDSCO inspection response). AI-assisted inspection surfaces (AI readiness scoring, AI narrative draft, MIRA inspection copilot, AI RAG-backed response suggestions, AI document retrieval, AI inspection-prep checklist, AI mock-drill question generation) are advisory only under internal AI governance aligned with EU AI Act Article 13 transparency principles. Every AI surface shall provide a fully functional manual readiness, narrative, retrieval, and response path; inspection record creation, readiness assessment, document preparation, narrative authoring, sign-off, and inspection closure shall be executable when AI services are disabled, degraded, or overridden by the inspection owner. AI-generated drafts shall be visibly labeled as advisory; the `mira_assisted_draft` content shall not be promoted to the system-of-record narrative without explicit human confirmation and e-signature. **No AI service shall be the sole path to finalize inspection readiness or send a regulator response.** This module binds ARCH-AI-001 AC-1, AC-2, AC-3, AC-4, AC-5, AC-6, and AC-7. Verixa treats **EU GMP Annex 22 Draft 2025 §7** as an internal forward-looking architectural control (not an enacted predicate rule); under that internal control, generative / probabilistic AI is **PROHIBITED** in regulator-facing inspection-response narrative finalization, deficiency disposition decisions, commitment-to-CAPA linkage decisions, readiness-score formula authoring, and inspection-closure decision paths. Static deterministic AI may surface similar prior inspection observations, prior-response templates, retrieval suggestions, and historical readiness patterns as advisory help; the inspection owner's signed disposition is the system of record. Jurisdiction-specific legal enforceability of Annex 22 and the EU AI Act remains subject to a future jurisdiction-specific legal assessment. | | Regulatory Classification | Critical infrastructure substrate — operates the canonical Inspection Management register, the inspection-calendar lifecycle state machine (`planned → in_progress → completed → archived`; reopen is a governed transition event from `archived → in_progress` per DEC-22-22 + SoD-22-06 that appends a new inspection iteration and does not mutate or erase the prior archived evidence), the self-inspection lifecycle (`draft → in_progress → review → completed`; reopen is a governed transition from `completed → in_progress` per DEC-22-23 + SoD-22-06), the controlled-checklist lifecycle (`draft → effective → superseded → archived` with immutable historical versions per DEC-22-06), the SME question-bank lifecycle (`draft → effective → superseded → archived` per DEC-22-07), the mock-drill lifecycle (`scheduled → in_progress → completed → archived` per DEC-22-08), the back-room-request lifecycle (`pending → in_retrieval → retrieved | unable_to_locate → completed` per DEC-22-10), the deficiency-response lifecycle (`draft → in_review → submitted → accepted → closed` per DEC-22-11), the commitment lifecycle (`open → in_progress → completed → verified → closed` per DEC-22-12) with explicit CAPA escalation linkage to URS-18, the lessons-learned lifecycle (`draft → published → archived` per DEC-22-13) with controlled publication, the readiness-scorecard generation as immutable versioned snapshots per DEC-22-09, the multi-dimensional context capture (`site_id` mandatory at calendar level, `study_id` optional, `product_id` optional, `supplier_id` optional, `batch_id` optional, `project_id` optional, `process_scope` optional) aligned with the platform context filter, the canonical API contract correction `/api/v1/inspections/*`, the typed schema validation across every route, the AI/RAG provenance enforcement on `mock_drill_questions`, `back_room_requests`, and `mira_assisted_draft`, the document-version + hash + retrieval-snapshot capture on every back-room retrieval, the explicit explainable readiness scoring with formula version and component inputs, the authority-gated status transitions across deficiency response, commitment, lesson publication, calendar archive, and inspection closure, the bound e-signature persistence on every regulated final action, the post-closure record immutability across the inspection calendar header, self-inspection records, mock drills, deficiency responses, commitments, and lessons learned, the controlled reopen workflow with executive authority co-sign, the canonical findings-source emission to URS-21 for standalone findings created from inspection observations (FDA 483 / EIR / EU GMP / MHRA / CDSCO), the canonical CAPA-source emission to URS-18 with `audit_observation` source type, the inspection-readiness export consuming evidence from every other URS module, the MIRA copilot read-only context integration on inspection records, and the per-jurisdictional regulatory expectations under FDA 21 CFR Part 11, FDA 21 CFR 211 (cGMP), FDA Form 483 / EIR observation handling, EU GMP Annex 11, EU GMP Annex 22 Draft 2025 §7 (HITL for AI readiness scoring / inspection prep — internal forward-looking control), EU AI Act (Regulation 2024/1689) Art. 13 transparency / Annex III high-risk approach (internal forward-looking control), MHRA Data Integrity Guidance (ALCOA+), GAMP 5 Cat 5, ICH Q9 (Quality Risk Management), ICH Q10 §3.2.4 (Internal Audit / Inspection), ICH E6(R3) §5.20 (sponsor inspection cooperation for GCP module use), and India CDSCO Schedule M-III §5 / §14 (internal audit and inspection cooperation for India operations subject to a future jurisdiction-specific legal assessment for Verixa's exact CDSCO obligations). | | Date of Issue | 2026-05-07 | | Module Owner (Engineering) | Quality / Inspection Squad | | Module Owner (Quality Validation) | CSV / CSA Lead — Inspection Management | | Module Owner (Compliance) | Quality Assurance, Regulatory Affairs, Manufacturing, Clinical / Pharmacovigilance, Distribution, Laboratory Operations, Supply Quality | | Approving Authority | Founder / Chairman & MD; QA Head; Manufacturing Head; Clinical / PV Head; Validation Head; RA Head; Information Security Head; Site Quality Lead | --- ## 0. Document Framing ### 0.1 Purpose of this document This URS defines the target expected state for Verixa's Inspection Management & Readiness module (Module 22). It is the binding contract between product, engineering, quality validation, regulatory affairs, manufacturing, clinical / pharmacovigilance, distribution, laboratory operations, supply quality, information security, and the executive authority for the design, implementation, validation, release, and on-going periodic review of the regulated inspection-management substrate: the canonical inspection-calendar register; the inspection-calendar lifecycle state machine (`planned → in_progress → completed → archived` with reopen as a governed transition event from `archived → in_progress` per executive authority co-sign + reason — DEC-22-22 + SoD-22-06 — that appends a new inspection iteration without mutating or erasing the prior archived evidence); the self-inspection lifecycle (`draft → in_progress → review → completed` with reopen `completed → in_progress` per DEC-22-23); the controlled-checklist lifecycle (`draft → effective → superseded → archived` with immutable historical versions per DEC-22-06); the SME question-bank lifecycle (`draft → effective → superseded → archived` per DEC-22-07); the mock-drill lifecycle (`scheduled → in_progress → completed → archived` per DEC-22-08); the back-room-request lifecycle (`pending → in_retrieval → retrieved | unable_to_locate → completed` per DEC-22-10); the deficiency-response lifecycle (`draft → in_review → submitted → accepted → closed` per DEC-22-11); the commitment lifecycle (`open → in_progress → completed → verified → closed` per DEC-22-12) with explicit CAPA escalation linkage to URS-18 via `commitment_capa_linked` event; the lessons-learned lifecycle (`draft → published → archived` per DEC-22-13) with controlled publication; the readiness-scorecard generation as immutable versioned snapshots per DEC-22-09 with explicit formula version, component inputs, and explainable component scores; the multi-dimensional context model (`site_id` mandatory at calendar level, `study_id` optional, `product_id` optional, `supplier_id` optional, `batch_id` optional, `project_id` optional, `process_scope` optional) with at least site anchor required and aligned with the platform context filter; the canonical API contract correction `/api/v1/inspections/*`; the typed schema validation across every route; the AI/RAG provenance enforcement on `mock_drill_questions`, `back_room_requests`, and `mira_assisted_draft`; the document-version + hash + retrieval-snapshot capture on every back-room retrieval; the explicit explainable readiness scoring with formula version and component inputs; the authority-gated status transitions across deficiency response submission / acceptance / closure, commitment verification / closure, lesson publication, calendar archive, self-inspection completion, and inspection closure; the bound e-signature persistence on every regulated final action; the post-closure record immutability across the inspection calendar header, self-inspection records, mock drills, deficiency responses, commitments, and lessons learned; the controlled reopen workflow with executive authority co-sign; the canonical findings-source emission to URS-21 for standalone findings created from inspection observations (FDA 483 / EIR / EU GMP / MHRA / CDSCO); the canonical CAPA-source emission to URS-18 with `audit_observation` source type; the inspection-readiness export consuming evidence from every other URS module (URS-01.URS-21, URS-23.URS-35); the MIRA copilot read-only context integration through `useMiraRecord(.)` mappings, with no MIRA write paths; the audit trail coverage with reason-for-change discipline; the canonical-status-model alignment; and the per-jurisdictional regulatory expectations. Compliance with this URS is mandatory. ### 0.2 Audience Engineering, QA, RA, Manufacturing, Clinical / Pharmacovigilance, Distribution, Laboratory Operations, Supply Quality, Validation, Information Security, executive authority, the platform's Implementation team, internal and external auditors, and inspectors from regulatory bodies (FDA, EMA, MHRA, Health Canada, CDSCO, PIC/S, PMDA). The plain-language primer (§0.4) and worked examples (§3.5) make Module 22 accessible to non-domain engineers, product owners, validation engineers, and quality investigators. ### 0.3 Cross-references - **URS-01** Authentication, Session & Access Control — identity envelope for every inspection-record mutation - **URS-02** RBAC & Permissions — the `inspections:*`, `inspections:back_room:*`, `inspections:deficiency:*`, `inspections:commitment:*`, `inspections:lessons:*`, `inspections:readiness:*`, `inspections:checklist:*`, `inspections:sme:*`, `inspections:drill:*` permission set - **URS-03** Context Gate & Approval Scope — context-gate enforcement for inspection scope dimensions - **URS-04** Workflow / HITL / E-Signature / Approval Authority — Controlled Approval Modal contract for self-inspection completion / checklist release / SME question-bank release / mock-drill completion / deficiency-response submission / acceptance / closure / commitment verification / lesson publication / calendar archive / inspection closure / reopen - **URS-05** Authority Profile / Delegation / SoD — Authority Profiles consumed (`inspection_owner_authority`, `back_room_coordinator_authority`, `deficiency_review_authority`, `commitment_verification_authority`, `lesson_publication_authority`, `final_quality_approver`, `executive_authority`, `controlled_content_approver`) - **URS-06** Audit Trail / Hash Chain / Tamper-Evident — append-only audit substrate - **URS-07** Study Management — optional study-scope dimension consumed - **URS-08** Tenant Management Lifecycle — tenant context for inspection records - **URS-09** Site / Facility Management — mandatory site-scope dimension consumed at calendar level - **URS-10** Product / SKU / Drug Master Data — optional product-scope dimension - **URS-11** Supplier Management — optional supplier-scope dimension; supplier-audit consumer - **URS-12** Document Control / SOP — document-version + hash provenance for back-room retrieval; checklist citation linkage; document-version registry consumed for retrieval evidence - **URS-13** Change Control — readiness-scoring formula version changes; checklist effective-state release - **URS-14** Complaints — complaint-trend evidence input to readiness scorecard - **URS-15** OOS / OOT — OOS-trend evidence input to readiness scorecard - **URS-16** Deviations — deviation-trend evidence input to readiness scorecard - **URS-17** RCA — RCA records as readiness-scorecard input where root-cause investigations are pending or unresolved - **URS-18** CAPA — primary downstream consumer for commitment-to-CAPA linkage (`commitment_capa_linked` event); audit-observation CAPA source type per URS-18 declared source set - **URS-19** Risk Assessment — inspection-precipitated risk records; risk-status input to readiness scorecard - **URS-20** Reviews — inspection-completion review consumer - **URS-21** Findings — primary downstream consumer for standalone findings created from inspection observations (FDA 483 / EIR / EU GMP / MHRA / CDSCO); `inspection_observation_finding_created` event emission - **URS-23** Batch Records — optional batch-scope dimension; batch-record evidence retrieval source - **URS-24** Stability — stability evidence retrieval source for inspection - **URS-25** Environmental Monitoring — EM evidence retrieval source for inspection - **URS-26** APQR — periodic inspection consumer - **URS-27** Regulatory Intelligence — predicate-rule citation source for checklist regulatory references - **URS-28** Training — training-evidence retrieval source; SME training session source - **URS-30** Notifications — notification delivery for inspection lifecycle events - **URS-31** DQG — data-quality gate evidence input to readiness scorecard - **URS-32** MIRA AI — read-only MIRA copilot context integration on inspection records; AI request provenance via `ai_requests` and `mira_context_access_log` - **URS-33** GMP Manufacturing — GMP evidence retrieval source for FDA / EMA / MHRA inspections - **URS-34** GDP Distribution — GDP evidence retrieval source for distribution inspections - **URS-35** Infrastructure / Backup-Restore — operational continuity ### 0.4 Plain-language primer In a regulated pharmaceutical operation, **an inspection is the formal external or internal examination of the operation's compliance with regulatory predicate rules and the operation's own quality system**. Inspections are conducted by FDA (typically issuing FDA Form 483 observations and EIRs), EMA / national competent authorities (issuing EU GMP inspection reports), MHRA (issuing MHRA inspection reports), Health Canada, CDSCO (India — issuing CDSCO inspection reports), PMDA (Japan), notified bodies for medical devices, internal QA (issuing internal audit observations), and supplier-audit teams (issuing supplier-audit observations). Each inspection requires structured handling under **21 CFR Part 11, 21 CFR 211 cGMP, EU GMP Annex 11, MHRA Data Integrity Guidance, ICH Q10 §3.2.4 (Internal Audit), ICH E6(R3) §5.20 (sponsor inspection cooperation for GCP), and the operating company's own quality manual**: (1) plan the inspection on the inspection calendar with site / scope / type, (2) prepare with self-inspections, mock drills, controlled checklists, and SME training, (3) generate a readiness scorecard with explicit formula version, (4) execute the inspection with back-room retrieval (document version + hash provenance), (5) draft and submit the deficiency response with reviewer-signed evidence, (6) accept and close the deficiency response only after all response items are verified and commitments are linked to CAPA where escalation is required, (7) capture lessons learned and publish through controlled review, (8) close and archive the inspection calendar. Module 22 is the target specification for this regulated workflow. The most common mistake in regulated inspection handling is **back-room retrieval without document-version provenance**. The regulator's tell-tale at inspection is a back-room request marked complete without document hash, document version ID, retrieval method, retriever identity, retrieval timestamp, retrieval outcome, or, where AI-assisted, the `ai_request_id` and citation snapshot. Module 22 enforces the pathway: every retrieved request MUST carry document-version + hash + retrieval method + retriever + retrieval outcome (per DEC-22-10); every AI-assisted retrieval MUST carry `ai_request_id`, confidence, accepted_by, accepted_at, and citation snapshot (per DEC-22-15); every retrieved request that cannot be located MUST carry an `unable_to_locate_reason`; the inspection response cannot be closed without all back-room requests in `completed` state. The second most common mistake is **deficiency closure without linked CAPA for critical / major observations**. Module 22 enforces severity-gated mandatory commitment-to-CAPA linkage per DEC-22-12 / DEC-22-21. The **AI-assistance** dimension is critical. Static deterministic AI may surface "similar prior inspection observations" or "prior-response templates by deficiency type" or "historical readiness patterns by site / product line" or "retrieval suggestions for FDA 483 §X observations" as advisory help. Generative AI (LLMs / MIRA copilot) is **prohibited** from finalizing the regulator-facing inspection-response narrative, deficiency disposition, commitment-to-CAPA linkage decisions, readiness-score formula authoring, or inspection closure decisions under the internal Annex 22 Draft 2025 §7 forward-looking AI governance control. MIRA copilot may read inspection records and propose advisory drafts (visibly labeled as advisory) via `useMiraRecord(.)` mappings; the `mira_assisted_draft` content shall not be promoted to the system-of-record narrative without explicit human confirmation and e-signature. The signed disposition is the system of record, attributable to the human inspection owner. The **two-step release path** mirrors every other Module: this URS 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-22-VAL-008 (Migration Evidence Gate) and the §17 validation evidence pack are satisfied. ### 0.5 Conventions 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. Every requirement is mandatory unless explicitly marked SHOULD or MAY. ### 0.6 Glossary | Term | Definition | |---|---| | Inspection calendar | The master planning record for an inspection / audit / readiness activity; site-anchored; carries inspection type, planned date, readiness threshold, and lifecycle status. | | Inspection type | The categorical type of inspection: `fda_routine` / `fda_pai` / `fda_for_cause` / `ema_gmp` / `mhra_gmp` / `cdsco_gmp` / `health_canada` / `pmda` / `notified_body` / `internal_audit` / `supplier_audit` / `mock_drill` / `regulatory_response_followup`. | | Self-inspection | An attributable internal readiness assessment tied to a calendar or standalone inspection context; produces a readiness summary and findings. | | Controlled checklist | A versioned inspection checklist with controlled lifecycle (`draft → effective → superseded → archived`); released with controlled-content approver authority and (where policy requires) e-signature; immutable once superseded. | | SME question bank | A controlled question-bank of subject-matter expert questions with versioned lifecycle; consumed by SME training sessions and mock drills. | | Mock drill | A readiness simulation; produces drill questions (some AI-assisted) and a drill outcome; AI-assisted questions carry full provenance per DEC-22-15. | | Readiness scorecard | An immutable versioned snapshot of inspection readiness generated by an explicit explainable scoring formula; carries formula version, component inputs, component scores, and overall score; the formula is no longer hardcoded heuristic. | | Back-room | The inspection-execution support function that retrieves documents and evidence on demand for the inspector; each retrieval carries document-version + hash + retrieval-method + retriever + retrieval outcome provenance per DEC-22-10. | | Deficiency response | The controlled response record for an inspection observation; lifecycle `draft → in_review → submitted → accepted → closed`; submission and acceptance gated by authority + HITL + e-signature per DEC-22-11. | | Response item | An individual remediation item under a deficiency response; lifecycle `open → in_progress → completed → verified`; verification gated by SoD-distinct verifier per SoD-22-04. | | Commitment | A regulator-bound remediation commitment; lifecycle `open → in_progress → completed → verified → closed`; may escalate to a URS-18 CAPA via `commitment_capa_linked` event per DEC-22-12. | | Lesson learned | A captured operational lesson from an inspection; lifecycle `draft → published → archived`; publication gated by `lesson_publication_authority` + e-signature per DEC-22-13. | | Inspection observation | An observation recorded on FDA Form 483 / EIR / EU GMP report / MHRA report / CDSCO report; emits `inspection_observation_finding_created` to URS-21 for standalone-finding creation. | | Reopen | A governed transition event (calendar `archived → in_progress` per DEC-22-22; self-inspection `completed → in_progress` per DEC-22-23) requiring executive authority co-sign and documented reason; appends a new iteration without mutating prior archived evidence. | | ARCH-AI-001 | Platform architecture binding requiring manual continuity for every AI surface (AC-1.AC-7). | | Annex 22 | EU GMP Annex 22 (Draft 2025) §7. Verixa treats Annex 22 §7 and EU AI Act high-risk / transparency concepts as internal forward-looking AI governance controls unless a jurisdiction-specific legal assessment determines otherwise. Under the internal control, generative / probabilistic AI is prohibited in regulator-facing inspection-response narrative finalization, deficiency disposition decisions, commitment-to-CAPA linkage decisions, readiness-score formula authoring, and inspection-closure decision paths. Binding predicate-rule obligations remain those listed in §14. | | MIRA | The platform's read-only AI copilot service; for Module 22 MIRA is read-only context on inspection records via `useMiraRecord(.)` mappings; `mira_assisted_draft` is advisory-only and not promotable to system-of-record narrative without explicit human confirmation and e-signature. | | Inspection-readiness export | The consolidated read-only export pulled from every URS-01.URS-21 / URS-23.URS-35 module to support regulator-facing inspection prep; rendered as a controlled inspection-prep package; not a system-of-record artifact. | ### 0.7 Module-22 architectural picture ```mermaid flowchart TD U[Inspection Owner / Back-Room Coordinator / Deficiency Reviewer / Closure Authority] --> CAL[/Inspection Calendars/] CAL --> SI[Self-Inspections] CAL --> CL[Controlled Checklists] CAL --> SQB[SME Question Banks] CAL --> MD[Mock Drills - AI-assisted with provenance] CAL --> RS[Readiness Scorecards - versioned formula] CAL --> BR[Back-Room Requests - doc version + hash provenance] CAL --> DR[Deficiency Responses HITL + bound e-sign + SoD-22-03] CAL --> CMT[Commitments - CAPA escalation via URS-18] CAL --> LL[Lessons Learned - controlled publication] CAL --> CLOSE[Inspection Closure HITL + bound e-sign + SoD-22-04 + back-room completion check + deficiency-response closure check + commitment-CAPA terminal check] CLOSE -. governed reopen + executive co-sign.-> CAL M21[URS-21 Findings] <-- CAL (inspection_observation_finding_created) M18[URS-18 CAPA] <-- CMT (commitment_capa_linked) M19[URS-19 Risk Assessment] <-- CAL (inspection-precipitated risk) M12[URS-12 Document Control] --> BR (document version + hash) M13[URS-13 Change Control] --> RS (formula version change) M27[URS-27 Regulatory Intelligence] --> CL (predicate-rule citation) M14[URS-14 Complaints] --> RS (complaint-trend input) M15[URS-15 OOS/OOT] --> RS (OOS-trend input) M16[URS-16 Deviations] --> RS (deviation-trend input) M17[URS-17 RCA] --> RS (RCA-status input) M18 --> RS (CAPA-status input) M19 --> RS (risk-status input) M28[URS-28 Training] --> RS (training-status input); --> SQB (SME training session source) M31[URS-31 DQG] --> RS (data-quality input) M30[URS-30 Notifications] <-- CAL M32[URS-32 MIRA AI] <-- CAL (read-only context); --> MD (AI-assisted question with provenance); --> BR (AI-assisted retrieval with provenance) M33[URS-33 GMP] --> BR (GMP evidence retrieval) M34[URS-34 GDP] --> BR (GDP evidence retrieval) M23[URS-23 Batch Records] --> BR (batch-record evidence) M24[URS-24 Stability] --> BR (stability evidence) M25[URS-25 EM] --> BR (EM evidence) ``` The platform shall implement: a controlled inspection-calendar register (one calendar per planned inspection, site-anchored, multiple inspections per day permitted when context differs); a self-inspection lifecycle with structured completion summary and reviewer-signed evidence; a controlled-checklist lifecycle with version immutability after `effective` release; an SME question-bank lifecycle with version immutability after `effective` release; a mock-drill lifecycle with full AI-assisted question provenance per DEC-22-15; an immutable versioned readiness-scorecard with explicit formula version and component inputs; a back-room-request lifecycle with document-version + hash + retrieval-method + retriever + retrieval-outcome provenance per DEC-22-10; a deficiency-response lifecycle with HITL + bound e-signature on submission / acceptance / closure per DEC-22-11; a response-item lifecycle with SoD-distinct verifier per SoD-22-04; a commitment lifecycle with CAPA escalation via `commitment_capa_linked` event per DEC-22-12; a lessons-learned lifecycle with controlled publication per DEC-22-13; a governed reopen workflow per DEC-22-22 / DEC-22-23 with executive authority co-sign; standalone-finding emission to URS-21 from inspection observations per DEC-22-14; the inspection-readiness export consuming evidence from every other URS module per DEC-22-19; and the per-jurisdictional regulatory expectations. ### 0.8 Locked Launch Controls | Locked control | Authority | Rationale | |---|---|---| | Two-step release path: signature → engineering implementation → validation execution | DEC-22-01 / VAL-008 | Mirrors every other Module; URS approval is separate from validation evidence. | | "No Module 22 internal decisions outstanding" | §11.6 | Captured in locked decisions DEC-22-01..DEC-22-23 (§3.2). | | `platform_admin` / `super_admin` support / break-glass only | DEC-22-20 / SoD-22-07 | Operating-tenant inspection ownership is the regulated path; cross-tenant coordination is support-only. | | Target implementation binding language | Module bindings | URS specifies expected implementation; repository evidence is verified at validation. | | AI overclaim posture as **internal forward-looking governance** | Architecture Bindings | EU GMP Annex 22 Draft 2025 §7 + EU AI Act Art. 13 / Annex III treated as internal controls; not enacted predicate rules; jurisdiction-specific legal assessment deferred. | | Enumerated error codes (no overload of generic 4xx) | §6.7 | Stable machine-readable error contract for client + auditor reproducibility. | | JSON multi-signature evidence as **derived snapshot** | §6.6 | The `electronic_signatures` substrate is the system of record; audit-trail JSON column is a derived snapshot for fast querying / inspection export. | | India CDSCO §14 row | §14 | Schedule M-III §5 / §14 internal-audit cooperation expectations captured for India operations subject to a future jurisdiction-specific legal assessment. | | Version 1.0 posture | Header | First binding version; subsequent revisions follow controlled change control. | | Canonical API mount `/api/v1/inspections/*` | DEC-22-01 / INS-DR-002 | Canonical plural mount; frontend hooks aligned to `/api/v1/inspections/*` shape. | | `site_id` mandatory at calendar level | DEC-22-02 / INS-DR-014 | Schema/context-filter alignment; module is site-scoped, not study-scoped. | | Typed schema validation across every route | DEC-22-03 / INS-DR-003 | Replaces `as any` request casting; defense in depth alongside DB constraints. | | Calendar uniqueness on `(tenant_id, site_id, inspection_type, planned_date)` | DEC-22-04 / INS-DR-004 | Multiple valid inspections per site per day permitted when type differs. | | Self-inspection completion requires structured findings summary + readiness score basis + linked checklist or rationale | DEC-22-05 / INS-DR-005 | Replaces score-and-count completion. | | Controlled-checklist version immutability after `effective` release | DEC-22-06 / INS-DR-006 | Replaces in-place edit on released versions. | | SME question-bank version immutability after `effective` release | DEC-22-07 / INS-DR-007 | Same governance as checklists. | | Mock-drill AI-assisted question provenance | DEC-22-15 / INS-DR-008 | Full provenance: `ai_request_id`, model, model version, prompt version, confidence, accepted_by, accepted_at, human-edited flag, citation snapshot. | | Readiness-scorecard versioned explainable formula | DEC-22-09 / INS-DR-009 | Replaces hardcoded `0.85` constants; `formula_version`, `component_inputs`, `fallback_flags`, frontend contract alignment. | | Back-room retrieval document-version + hash provenance | DEC-22-10 / INS-DR-010 | Replaces document_id-only provenance. | | Deficiency-response authority + HITL + e-sign on submission / acceptance / closure | DEC-22-11 / INS-DR-011 / INS-DR-016 | Replaces generic CRUD-style patch. | | Commitment-to-CAPA linkage via `commitment_capa_linked` event | DEC-22-12 / INS-DR-012 | Replaces free-floating commitment tracking. | | Lessons-learned controlled publication | DEC-22-13 / INS-DR-013 | Replaces draft-only publication state. | | Standalone-finding emission to URS-21 from inspection observations | DEC-22-14 / URS-21 cross-ref | Inspection observations become URS-21 standalone findings via `inspection_observation_finding_created` event. | | Multi-dimensional context model | DEC-22-16 | At-least-one scope anchor (site mandatory; study / product / supplier / batch / project optional). | | Reason-for-change requirement on material updates after draft | DEC-22-17 / INS-DR-016 | Replaces silent updates on regulated records. | | Bound e-signature persistence on every regulated final action | DEC-22-18 / INS-DR-016 | Self-inspection completion / checklist release / SME bank release / mock-drill completion / deficiency submission / acceptance / closure / commitment verification / closure / lesson publication / calendar archive / inspection closure / reopen — all carry bound e-signature persisted via `electronic_signatures` substrate. | | Inspection-readiness export consuming evidence from every URS module | DEC-22-19 | Read-only consolidated export; not a system-of-record artifact. | | Governed reopen pattern (calendar `archived → in_progress`; self-inspection `completed → in_progress`) | DEC-22-22 / DEC-22-23 / SoD-22-06 | Append-only iteration; does NOT mutate or erase prior archived evidence. | --- ## 1. Scope and Out-of-Scope ### 1.1 In-scope - The canonical inspection-calendar register and lifecycle. - The self-inspection lifecycle with structured completion. - The controlled-checklist lifecycle with version immutability after `effective` release. - The SME question-bank lifecycle with version immutability after `effective` release. - The SME training-session lifecycle. - The mock-drill lifecycle with full AI-assisted question provenance. - The readiness-scorecard generation with explicit explainable formula. - The back-room-queue and back-room-request lifecycle with document-version + hash provenance. - The deficiency-response lifecycle with HITL + bound e-signature. - The response-item lifecycle with SoD-distinct verifier. - The commitment lifecycle with CAPA escalation. - The lessons-learned lifecycle with controlled publication. - The inspection-readiness export consuming evidence from every other URS module. - The MIRA copilot read-only context integration. - The standalone-finding emission to URS-21 from inspection observations. - The CAPA-source emission to URS-18 with `audit_observation` source type. - The risk-source emission to URS-19 for inspection-precipitated risk records. - The change-control linkage to URS-13 for readiness-scoring formula version changes. - The governed reopen workflow with executive authority co-sign. - The audit-trail coverage with reason-for-change discipline. - The per-jurisdictional regulatory expectations. ### 1.2 Out-of-scope - The HITL decision substrate itself (URS-04) — this URS consumes the HITL substrate, does not redefine it. - The Authority Profile registry itself (URS-05) — this URS consumes the Authority Profile registry, does not redefine it. - The audit-trail substrate itself (URS-06) — this URS consumes the substrate, does not redefine the hash chain. - The CAPA register itself (URS-18) — this URS emits commitment-to-CAPA linkage events; CAPA closure is the URS-18 contract. - The findings register itself (URS-21) — this URS emits standalone-finding events; finding lifecycle is the URS-21 contract. - The risk-assessment register itself (URS-19) — this URS emits inspection-precipitated risk events; risk lifecycle is the URS-19 contract. - The change-control register itself (URS-13) — this URS consumes change-control for formula versions. - The document-control register itself (URS-12) — this URS consumes document-version registry for retrieval provenance. - The MIRA copilot service itself (URS-32) — this URS consumes MIRA read-only context; MIRA service contract is the URS-32 contract. - The notification delivery substrate itself (URS-30) — this URS emits notification events; delivery is the URS-30 contract. - Regulator portal direct submission (FDA ESG, EMA EudraVigilance for inspection responses where applicable) — out of scope for Module 22 v1.0; tracked as future-state. --- ## 2. Preconditions, Dependencies, Constraints ### 2.1 Operating preconditions The following preconditions MUST hold for this URS to apply at validation time. Each bullet is a binding precondition; deviations require a controlled exception per URS-13 Change Control. - The platform's authentication and session substrate (URS-01), RBAC (URS-02), context gate (URS-03), HITL / e-sign (URS-04), Authority Profile registry (URS-05), audit-trail hash-chain (URS-06), document-control (URS-12), CAPA (URS-18), findings (URS-21), risk assessment (URS-19), and MIRA AI (URS-32) are released and operational at validation time. - Inspection lifecycle handling is performed by trained, attributable users (`inspection_owner`, `back_room_coordinator`, `deficiency_reviewer`, `commitment_verifier`, `lesson_publisher`, `final_quality_approver`, `executive_authority`). - AI-assisted inspection surfaces are advisory only; the human-signed disposition is the system of record. - The inspection-readiness export is a read-only consolidated package; it is not a system-of-record artifact. - The tenant operating jurisdiction(s) are configured and applicable predicate rules surface accordingly (FDA / EMA / MHRA / CDSCO / Health Canada / PMDA / notified body). ### 2.2 Dependencies - URS-01.URS-21, URS-23.URS-35 platform contracts. - The `electronic_signatures` substrate (bound e-signature persistence). - The `authority` substrate (Authority Profile resolution). - The `hitl` substrate (Controlled Approval Modal). - The `audit_trail` substrate (hash-chained audit). - The `documents` substrate (document-version registry). - The `ai_requests` substrate (AI request provenance). - The `mira_context_access_log` substrate (MIRA read-only access log). - The `notifications` substrate (URS-30). ### 2.3 Constraints - The canonical API mount is `/api/v1/inspections/*` (plural). Frontend hooks MUST use the canonical mount; no `/inspection/*` (singular) or `/api/inspection/*` (extra `/api`) paths in the long-term contract. - The inspection module is site-scoped at the calendar level; `site_id` is mandatory; `study_id` / `product_id` / `supplier_id` / `batch_id` / `project_id` are optional. - AI-assisted content is advisory-only; no AI service writes to the system-of-record narrative without explicit human confirmation and e-signature. - Generative AI is prohibited in regulator-facing inspection-response narrative finalization, deficiency disposition, commitment-to-CAPA linkage decisions, readiness-score formula authoring, and inspection-closure decision paths under the internal Annex 22 §7 + EU AI Act Annex III control. - Readiness-scorecard formula version changes require URS-13 change control approval and validation evidence. - Back-room retrieval document references MUST resolve to URS-12 document-version registry entries with hash; free-text retrieval references are not acceptable for regulated inspections. --- ## 3. Closed Launch Decisions The following decisions are LOCKED for Module 22 v1.0. Each decision is the binding executive authority decision for the current launch and are locked and define the binding launch posture. ### 3.1 Decision register | Decision ID | Title | Locked decision | |---|---|---| | DEC-22-01 | Two-step release path | Module 22 follows the same two-step release path as every other Module: URS approval = "Approved Controlled URS — released for engineering implementation and validation planning"; "Released for validation execution" requires URS-22-VAL-008 migration evidence gate + §17 validation evidence pack. | | DEC-22-02 | Multi-dimensional context model anchored at site | At calendar level, `site_id` is mandatory; `study_id`, `product_id`, `supplier_id`, `batch_id`, `project_id`, `process_scope` are optional. Child records inherit and persist parent context. Schema/context-filter alignment is enforced. | | DEC-22-03 | Typed schema validation across every route | Every inspection route validates request params, query strings, and bodies through explicit typed schemas before service execution. No `as any` request casting. | | DEC-22-04 | Calendar uniqueness rule | Calendar uniqueness is `(tenant_id, site_id, inspection_type, planned_date)`; multiple valid inspections per site per day permitted when type differs. | | DEC-22-05 | Self-inspection structured completion | Self-inspection completion requires structured findings summary, readiness score basis, and linked checklist version or rationale when no checklist was used. | | DEC-22-06 | Controlled-checklist version immutability | Controlled-checklist lifecycle is `draft → effective → superseded → archived`; in-place edit on `effective` versions is prohibited; revisions create new version rows; release to `effective` requires `controlled_content_approver` + e-signature where policy requires. | | DEC-22-07 | SME question-bank version immutability | SME question-bank lifecycle mirrors controlled-checklist lifecycle; finalized answer records are immutable after session finalization. | | DEC-22-08 | Mock-drill lifecycle | Mock-drill lifecycle is `scheduled → in_progress → completed → archived`; completion requires structured outcomes (not status-and-score-only). | | DEC-22-09 | Readiness-scorecard versioned explainable formula | Readiness scorecards are immutable versioned snapshots generated by an explicit explainable scoring formula. Hardcoded `0.85` constants are removed. Scorecards persist `formula_version`, `component_inputs`, `component_scores`, `fallback_flags`, and `generated_by_rule`. Frontend contract aligned: response fields match `InspectionCalendarDetail.tsx` expectations exactly. | | DEC-22-10 | Back-room retrieval document-version + hash provenance | Each back-room retrieval persists `document_id`, `document_version_id`, `document_hash`, `retrieval_method`, `retrieval_timestamp`, `requested_by`, `retrieved_by`, `retrieval_outcome`, `unable_to_locate_reason` (where applicable), and citation reference; AI-assisted retrieval additionally persists `ai_request_id`, `mira_confidence_score`, `accepted_by`, `accepted_at`, and `citation_snapshot`. | | DEC-22-11 | Deficiency-response authority + HITL + e-signature | Deficiency-response lifecycle is `draft → in_review → submitted → accepted → closed`; submission, acceptance, and closure are gated by `deficiency_review_authority` + HITL + bound e-signature; reason-for-change required on material updates after draft. | | DEC-22-12 | Commitment lifecycle and CAPA escalation | Commitment lifecycle is `open → in_progress → completed → verified → closed`; commitment-to-CAPA linkage emits the `commitment_capa_linked` event consumed by URS-18 (`audit_observation` source type per URS-18 declared source set); critical and major deficiencies cannot close without linked commitments or approved waiver. | | DEC-22-13 | Lessons-learned controlled publication | Lessons-learned lifecycle is `draft → published → archived`; publication is gated by `lesson_publication_authority` + e-signature where policy requires; published lessons are immutable except controlled archive. | | DEC-22-14 | Standalone-finding emission to URS-21 | Inspection observations (FDA 483 / EIR / EU GMP / MHRA / CDSCO) emit `inspection_observation_finding_created` event to URS-21; the URS-21 standalone finding carries the inspection-record reference and severity. | | DEC-22-15 | Mock-drill AI-assisted question provenance | AI-assisted mock-drill questions persist `content_origin`, `ai_request_id`, model identifier, model version, prompt-or-template version, confidence, `accepted_by`, `accepted_at`, `human_edited`, and `source_citation_snapshot`; AI-assisted content cannot be used for regulated readiness decisions until accepted by a human reviewer. | | DEC-22-16 | Multi-dimensional context model (extended) | The multi-dimensional context model extends to all child records: child rows persist the parent calendar's `site_id` and applicable `study_id` / `product_id` / `supplier_id` / `batch_id` / `project_id`. Queries support filtering by every persisted dimension. | | DEC-22-17 | Reason-for-change on material updates | Material updates on inspection records after the record leaves draft require structured reason-for-change captured in audit; silent updates on regulated records are not permitted. | | DEC-22-18 | Bound e-signature persistence on every regulated final action | Every regulated final action — self-inspection completion, checklist release, SME-bank release, mock-drill completion (where policy requires), deficiency submission / acceptance / closure, commitment verification / closure, lesson publication, calendar archive, inspection closure, governed reopen — persists a bound e-signature via the `electronic_signatures` substrate; the JSON multi-signature evidence in audit-trail is a derived snapshot. | | DEC-22-19 | Inspection-readiness export | The inspection-readiness export consumes read-only evidence from every URS-01.URS-21 / URS-23.URS-35 module to produce a consolidated regulator-facing inspection-prep package; the export is a controlled snapshot, not a system-of-record artifact; export generation is logged in the audit trail. | | DEC-22-20 | platform_admin / super_admin | `platform_admin` / `super_admin` are support / break-glass only paths for cross-tenant inspection coordination; operating-tenant inspection ownership is the regulated path; break-glass actions are logged with reason and reviewed in the platform support audit. | | DEC-22-21 | Severity-gated mandatory commitment-to-CAPA linkage | Critical and major deficiencies cannot close without at least one linked commitment escalated to a URS-18 CAPA via `commitment_capa_linked` event, unless explicitly waived through approved rationale captured in audit. | | DEC-22-22 | Calendar reopen as governed transition | Calendar `archived → in_progress` is a governed transition requiring executive authority co-sign + documented reason; appends a new inspection iteration without mutating prior archived evidence (consistent with M14 / M16 / M17 / M18 / M19 / M20 / M21 reopen pattern). | | DEC-22-23 | Self-inspection reopen as governed transition | Self-inspection `completed → in_progress` is a governed transition requiring `final_quality_approver` co-sign + documented reason; appends a new self-inspection iteration without mutating prior completed evidence. | ### 3.2 Locked-decision rationale narrative The decisions above define the binding launch posture for Module 22 v1.0. The most consequential locked controls are: (a) DEC-22-02 anchors the module at site-level and persists `site_id` mandatorily, with `MODULE_CONTEXT_CONFIG['inspection']` aligned to the persisted schema; (b) DEC-22-09 requires an explicit explainable readiness-score formula with persisted formula version, component inputs, and component scores, and aligns the API response to the frontend contract exactly; (c) DEC-22-10 requires document-version + hash + retrieval-method + retriever + retrieval-outcome on every back-room retrieval, and AI-provenance fields on every AI-assisted retrieval; (d) DEC-22-11 / DEC-22-12 / DEC-22-13 require authority + HITL + bound e-signature on every regulated final action (deficiency submission / acceptance / closure, commitment verification / closure, lesson publication); (e) DEC-22-15 requires full AI-provenance fields on every AI-assisted mock-drill question; (f) DEC-22-22 / DEC-22-23 define reopen as a governed append-only transition consistent with the Module-14 / -16 / -17 / -18 / -19 / -20 / -21 reopen pattern. ### 3.3 Closed launch decisions: cross-link to items | Specification item ID | Specification item | Locked decision | |---|---|---| | INS-DR-002 | Canonical API contract standardization at `/api/v1/inspections` | DEC-22-01 | | INS-DR-003 | Request validation weak (`as any` casting) | DEC-22-03 | | INS-DR-004 | Calendar uniqueness too narrow | DEC-22-04 | | INS-DR-005 | Self-inspection completion too thin | DEC-22-05 | | INS-DR-006 | Controlled-checklist version governance missing | DEC-22-06 | | INS-DR-007 | SME question-bank version governance missing | DEC-22-07 | | INS-DR-008 | Mock-drill AI provenance incomplete | DEC-22-08 / DEC-22-15 | | INS-DR-009 | Readiness scoring heuristic and contract-mismatched | DEC-22-09 | | INS-DR-010 | Back-room retrieval provenance weak | DEC-22-10 | | INS-DR-011 | Deficiency-response lifecycle uncontrolled | DEC-22-11 | | INS-DR-012 | Commitments not closed-loop | DEC-22-12 / DEC-22-21 | | INS-DR-013 | Lessons-learned publication uncontrolled | DEC-22-13 | | INS-DR-014 | Context filtering vs schema mismatch | DEC-22-02 / DEC-22-16 | | INS-DR-016 | Authority / HITL / e-signature missing on regulated finals | DEC-22-11 / DEC-22-17 / DEC-22-18 | | INS-DR-017 | Test coverage too shallow | §16 + §17 | ### 3.4 Locked-decision authority Each locked decision is approved by the Founder / Chairman & MD on signature capture in the Document Approval block of this URS (§19). Decisions cannot be unlocked except through controlled URS revision under the URS change-control process and re-approval. ### 3.5 Worked examples **Worked example 1 — FDA routine inspection on a manufacturing site.** A site-quality lead schedules an FDA routine inspection on the inspection calendar with `site_id = SiteA`, `inspection_type = fda_routine`, `planned_date = 2026-07-14`, and `readiness_threshold = 0.85`. The calendar enters `planned`. A self-inspection is conducted on `2026-06-10` against the latest `effective` controlled checklist `CK-FDA-211-v3.2`; the self-inspection captures structured findings summary, readiness score basis (against checklist version), and a reviewer signs completion with a bound e-signature. A mock drill is run on `2026-06-25` against SME question-bank `SQB-FDA-v2.1` (effective); 12 of the 32 drill questions are AI-assisted (each carries `ai_request_id`, model = `claude-sonnet-4`, model version, prompt version `prompt-fda-drill-v1.4`, confidence ≥ 0.78, accepted_by, accepted_at, citation snapshot from URS-12 document version). A readiness scorecard is generated on `2026-07-01` with `formula_version = readiness-formula-v1.2`; the API response carries `overall_score`, `documentation_score`, `mock_drill_score`, `training_score`, `capa_score`, `deviation_score`, `risk_score`, `data_quality_score`, `component_inputs`, `fallback_flags`, and `generated_by_rule`; the frontend renders the same field names. On `2026-07-14` the FDA inspector arrives; back-room receives 18 retrieval requests; each retrieval persists `document_id`, `document_version_id`, `document_hash`, `retrieval_method = direct`, `retrieved_by = back_room_coordinator_id`, and `retrieval_outcome = retrieved`; 2 retrievals are AI-assisted with full provenance. On `2026-07-15` the FDA issues an FDA Form 483 with 3 observations; a `deficiency_response` record is created in `draft`; observation 1 (critical) becomes a standalone finding in URS-21 via `inspection_observation_finding_created` with `severity = critical`; the deficiency response transitions to `in_review` with reviewer signature, then `submitted` (HITL + e-signature) on `2026-07-30`; FDA accepts on `2026-08-15` and the response transitions to `accepted` (HITL + e-signature). For observation 1 (critical) a commitment is opened, escalated to a URS-18 CAPA via `commitment_capa_linked`, and tracked through CAPA closure. Lessons learned are captured and published with `lesson_publication_authority` + e-signature. On `2026-12-15` after CAPA closure and verification, the deficiency response transitions to `closed`, the calendar transitions to `completed`, and on `2027-01-15` the calendar is archived with archive reason and bound e-signature. **Worked example 2 — EU GMP inspection on the same site.** The site-quality lead schedules an EU GMP inspection with `site_id = SiteA`, `inspection_type = ema_gmp`, `planned_date = 2026-09-22`, on the same site as the FDA inspection. Per DEC-22-04 the calendar uniqueness `(tenant_id, site_id, inspection_type, planned_date)` permits this even though FDA was on `2026-07-14` (different type). The flow proceeds as Worked Example 1; one EU GMP observation is rated "Major" and triggers a standalone finding in URS-21, a commitment, and a CAPA via `commitment_capa_linked`. The inspection-readiness export consumes evidence from every URS module (URS-12 document control, URS-14 complaints, URS-15 OOS, URS-16 deviations, URS-17 RCA, URS-18 CAPA, URS-19 risk, URS-21 findings, URS-23 batch records, URS-25 EM, URS-28 training, URS-31 DQG, URS-33 GMP) into a consolidated read-only inspection-prep package. **Worked example 3 — Reopen of an archived calendar.** On `2027-04-10` a regulator notice arrives requesting clarification on FDA observation 2 from the inspection archived on `2027-01-15`. The site-quality lead initiates a reopen request; the request requires `executive_authority` co-sign + documented reason (per DEC-22-22 + SoD-22-06); on co-sign the calendar transitions `archived → in_progress` and a new inspection-iteration row is appended. The prior archived evidence (deficiency response, commitments, lessons learned) is NOT mutated or erased; the new iteration captures the additional response activity. **Worked example 4 — AI-assisted retrieval rejected.** During the FDA inspection an inspector requests "the latest stability data for Product P, batch B-2024-08-14". The back-room coordinator initiates an AI-assisted retrieval through MIRA; MIRA returns a candidate document version with confidence 0.62 and citation snapshot. The back-room coordinator reviews the snapshot, finds it is the wrong batch, and rejects the AI-assisted suggestion. The retrieval falls back to the URS-12 document registry direct lookup, retrieves the correct document version, and persists the back-room retrieval record with `retrieval_method = direct`, `retrieved_by`, `retrieval_outcome = retrieved`. The rejected AI-assisted retrieval persists `ai_request_id`, confidence 0.62, `accepted_by = null`, `accepted_at = null`, and a "rejected_by_human" flag for AI-quality monitoring. --- ## 4. End-to-End User Journeys (28 launch journeys) The following 28 journeys define the launch user journeys for Module 22. Each journey is a binding contract for the engineering implementation, the validation evidence pack (URS-22-VAL-008), and the inspection-prep training material. | # | Journey | Actor | Pre-condition | Path | Post-condition | |---|---|---|---|---|---| | 1 | Schedule FDA routine inspection | Site Quality Lead | `inspections:create`, `site_id` resolved | Create calendar `(site_id, inspection_type=fda_routine, planned_date, readiness_threshold)` | Calendar in `planned`; audit entry; notification emitted | | 2 | Schedule EU GMP inspection on same site, different date | Site Quality Lead | `inspections:create` | Create calendar with unique `(tenant_id, site_id, inspection_type, planned_date)` | Calendar in `planned`; per DEC-22-04 multiple inspections per site permitted when type differs | | 3 | Conduct internal self-inspection against effective checklist | Inspection Owner | `inspections:self_inspection:create`; effective checklist version | Create self-inspection `draft → in_progress → review → completed` with structured findings summary, readiness score basis, linked checklist version | Self-inspection in `completed`; bound e-signature; audit entry | | 4 | Release controlled checklist `draft → effective` | Controlled Content Approver | `inspections:checklist:release` | HITL + e-signature; new version row; prior version supersedes | Checklist in `effective`; prior version `superseded`; audit entry | | 5 | Revise effective checklist | Controlled Content Approver | Effective checklist exists | Create new revision row; release to `effective`; prior version `superseded` | New version `effective`; prior version `superseded`; immutable historical version | | 6 | Release SME question bank `draft → effective` | Controlled Content Approver | `inspections:sme:release` | HITL + e-signature | Question bank in `effective`; audit entry | | 7 | Run mock drill against effective question bank | Inspection Owner | `inspections:drill:create` | Drill `scheduled → in_progress → completed` with structured outcomes | Drill in `completed`; AI-assisted questions carry full provenance; bound e-signature on completion (where policy requires); audit entry | | 8 | Generate readiness scorecard | Inspection Owner | `inspections:readiness:generate`; calendar in `planned` or `in_progress` | Server computes formula `readiness-formula-v1.2` against component inputs | Scorecard persisted as immutable versioned snapshot with `formula_version`, `component_inputs`, `component_scores`, `fallback_flags`, `generated_by_rule`; frontend renders matching field names | | 9 | Open back-room queue for FDA inspection | Back-Room Coordinator | `inspections:back_room:queue:create`; calendar in `in_progress` | Open queue tied to calendar | Queue in `pending`; audit entry | | 10 | Receive back-room request from inspector | Back-Room Coordinator | Queue `pending`; `inspections:back_room:request:create` | Add request `pending → in_retrieval` | Request in `in_retrieval`; audit entry | | 11 | Retrieve document via direct URS-12 lookup | Back-Room Coordinator | Request `in_retrieval`; `documents:read` | Persist `document_id`, `document_version_id`, `document_hash`, `retrieval_method = direct`, `retrieved_by`, `retrieval_timestamp`, `retrieval_outcome = retrieved` | Request in `retrieved`; audit entry; document-version provenance immutable | | 12 | Retrieve document via AI-assisted MIRA | Back-Room Coordinator | Request `in_retrieval`; `inspections:back_room:ai_assisted` | MIRA returns candidate; coordinator accepts; persist AI provenance fields + document-version | Request in `retrieved`; AI provenance immutable; audit entry | | 13 | Reject AI-assisted retrieval and fall back to direct | Back-Room Coordinator | AI-assisted candidate confidence below threshold or wrong document | Persist rejected AI provenance with `accepted_by = null`; retry direct lookup | Request in `retrieved` via direct method; rejected AI request persisted for monitoring | | 14 | Mark request `unable_to_locate` | Back-Room Coordinator | Document not found | Persist `retrieval_outcome = unable_to_locate`, `unable_to_locate_reason`, retriever | Request in `unable_to_locate → completed`; audit entry; flagged for inspection-response narrative | | 15 | Receive FDA Form 483 / EIR observation list | Inspection Owner | Calendar `in_progress`; `inspections:deficiency:create` | Create `deficiency_response` per observation; emit `inspection_observation_finding_created` to URS-21 for each observation | Deficiency response in `draft`; URS-21 standalone findings created with severity; audit entry | | 16 | Submit deficiency response to regulator | Deficiency Reviewer | `deficiency_review_authority`; response items complete; evidence references | HITL + bound e-signature; transition `in_review → submitted` | Response in `submitted`; audit entry; bound e-signature persisted via `electronic_signatures` substrate | | 17 | Regulator accepts deficiency response | Deficiency Reviewer | Regulator response received | HITL + bound e-signature; transition `submitted → accepted` | Response in `accepted`; audit entry | | 18 | Open commitment for major observation | Inspection Owner | Deficiency response `accepted`; `inspections:commitment:create` | Create commitment `open`; assign owner; due date | Commitment in `open`; audit entry | | 19 | Escalate commitment to URS-18 CAPA | Inspection Owner | Commitment `in_progress`; severity critical or major | Emit `commitment_capa_linked` event; persist `capa_id` on commitment | URS-18 CAPA created with `audit_observation` source type; linkage immutable; audit entry | | 20 | Verify commitment | Commitment Verifier (SoD-distinct) | Commitment `completed`; `commitment_verification_authority` | Verify with structured outcome + evidence | Commitment in `verified`; bound e-signature; audit entry | | 21 | Close commitment after CAPA closed | Commitment Verifier | Commitment `verified`; linked CAPA in terminal status (URS-18 contract) | Close with bound e-signature | Commitment in `closed`; audit entry | | 22 | Capture lesson learned | Inspection Owner | Inspection `in_progress` or `completed` | Create lesson `draft` | Lesson in `draft`; audit entry | | 23 | Publish lesson learned | Lesson Publisher | `lesson_publication_authority`; `inspections:lessons:publish` | HITL + e-signature; transition `draft → published` | Lesson in `published`; immutable; audit entry | | 24 | Close inspection | Inspection Owner / Final Quality Approver | All deficiency responses `closed`; all commitments `closed` or waived; all back-room requests `completed`; all linked CAPAs in terminal status | HITL + bound e-signature; transition `in_progress → completed` | Calendar in `completed`; audit entry | | 25 | Archive inspection calendar | Final Quality Approver | Calendar `completed`; archive reason | HITL + bound e-signature; transition `completed → archived` | Calendar in `archived`; immutable; audit entry | | 26 | Reopen archived calendar (governed transition) | Inspection Owner / Executive Authority | Calendar `archived`; documented reason | Executive authority co-sign; transition `archived → in_progress`; append new inspection-iteration row | Calendar in `in_progress`; new iteration appended; prior archived evidence NOT mutated; audit entry per DEC-22-22 + SoD-22-06 | | 27 | Generate inspection-readiness export | Inspection Owner | Calendar in `planned` / `in_progress`; `inspections:readiness:export` | Read-only consolidated export from URS-01.URS-21 / URS-23.URS-35 | Inspection-readiness export package generated; audit entry; export hash persisted; not a system-of-record artifact | | 28 | platform_admin / super_admin support / break-glass cross-tenant inspection coordination | platform_admin | Break-glass scenario; documented reason | Cross-tenant inspection coordination access; logged with reason | Break-glass action logged in platform support audit; reviewed per DEC-22-20 | --- ## 5. Front-end Requirements ### 5.1 Inspection Dashboard The inspection dashboard (URS-22-FE-001) renders readiness summary cards (overall readiness, documentation readiness, mock-drill readiness, training readiness, CAPA readiness, deviation readiness, risk readiness, data-quality readiness), upcoming inspections (sorted by `planned_date`), open back-room queues, open deficiency responses, open commitments, and recent published lessons learned. The dashboard supports filter-by-context (site, study, inspection type, date range, status). The dashboard uses canonical hooks against `/api/v1/inspections/*`. ### 5.2 Inspection Calendar Detail The inspection calendar detail page (URS-22-FE-002) renders calendar header, readiness scorecard (with explicit `formula_version`, component scores, component inputs, fallback flags), self-inspection list, controlled-checklist list (with version + effective state), mock-drill list (with AI-provenance badges), back-room queue + request list (with document-version + hash + retrieval-method + AI-provenance badges), deficiency response list (with lifecycle state), commitment list (with CAPA linkage badges), lessons-learned list (with publication state), and the inspection-readiness export action. The detail page supports HITL + e-signature flows for self-inspection completion, checklist release, SME-bank release, mock-drill completion (where policy requires), deficiency submission / acceptance / closure, commitment verification / closure, lesson publication, calendar archive, inspection closure, and governed reopen. ### 5.3 Self-Inspection Form The self-inspection form (URS-22-FE-003) supports `draft → in_progress → review → completed` transitions with structured findings summary, readiness score basis, linked checklist version selection (or rationale when no checklist used), evidence references (URS-12 document version), and reviewer signature on completion (bound e-signature). ### 5.4 Controlled Checklist Editor The controlled checklist editor (URS-22-FE-004) supports draft authoring of new checklists or new revisions, item editing within draft, regulatory citation linkage (structured citations, not free text), version metadata, and HITL + e-signature on release `draft → effective`. Effective versions are read-only; revisions create new version rows. ### 5.5 SME Question-Bank Editor The SME question-bank editor (URS-22-FE-005) mirrors the controlled checklist editor for question-bank lifecycle. ### 5.6 Mock-Drill Execution The mock-drill execution screen (URS-22-FE-006) supports scheduling, execution, AI-assisted question generation (with provenance badges and human acceptance UI), drill completion with structured outcomes, and bound e-signature where policy requires. ### 5.7 Back-Room Console The back-room console (URS-22-FE-007) supports queue creation, request intake, retrieval action (direct URS-12 lookup or AI-assisted MIRA), retrieval-outcome capture (`retrieved` / `unable_to_locate` with reason), AI-provenance acceptance/rejection UI, and request completion. Each retrieval persists document-version + hash + retrieval-method + retriever + retrieval-outcome immutably. ### 5.8 Deficiency Response Form The deficiency response form (URS-22-FE-008) supports `draft → in_review → submitted → accepted → closed` transitions with structured response text, response items (lifecycle `open → in_progress → completed → verified`), commitment linkage UI, evidence references, and HITL + bound e-signature on submission / acceptance / closure. ### 5.9 Commitment Tracker The commitment tracker (URS-22-FE-009) supports `open → in_progress → completed → verified → closed` transitions, CAPA linkage UI (escalate to URS-18), verifier sign-off (SoD-distinct from performer), and HITL + bound e-signature on verification / closure. ### 5.10 Lessons-Learned Editor The lessons-learned editor (URS-22-FE-010) supports `draft → published → archived` transitions with HITL + e-signature on publication. ### 5.11 Inspection-Readiness Export The inspection-readiness export action (URS-22-FE-011) generates a consolidated read-only inspection-prep package from every URS-01.URS-21 / URS-23.URS-35 module; the export is a controlled snapshot with export hash; the export action is logged in the audit trail. ### 5.12 MIRA Copilot Integration MIRA copilot (URS-22-FE-012) is read-only context on inspection records via `useMiraRecord('inspection_calendar', id)`, `useMiraRecord('self_inspection', id)`, `useMiraRecord('mock_drill', id)`, `useMiraRecord('back_room_request', id)`, and `useMiraRecord('deficiency_response', id)`. MIRA may propose advisory drafts (visibly labeled as advisory); `mira_assisted_draft` content shall not be promoted to the system-of-record narrative without explicit human confirmation and e-signature. ### 5.13 Accessibility All Module 22 frontend surfaces are WCAG 2.1 AA accessible: keyboard-navigable, screen-reader compatible, high-contrast theme support, focus indicators, semantic landmark structure. Inspection-readiness export is renderable in screen-reader mode for accessibility-assist inspector observation. --- ## 6. Back-end Requirements ### 6.1 Module structure The Module 22 backend module is organized as `packages/backend/src/modules/inspection/` with `plugin.ts` (Fastify plugin registration), `routes.ts` (route definitions, all route handlers wired to typed schemas —), `service.ts` (business logic; HITL / authority / e-signature integration), `schemas.ts` (typed schema contracts — target requirement), `migrations.ts` (referenced from `packages/backend/src/db/migrations/041_inspection_enhancement.sql` and successor migrations for columns), and `events.ts` (event-bus emission for `inspection_calendar_*`, `self_inspection_*`, `mock_drill_*`, `readiness_scorecard_*`, `back_room_request_*`, `deficiency_response_*`, `commitment_capa_linked`, `lesson_published`, `inspection_response_*`, `inspection_observation_finding_created`, `inspection_closed`, `inspection_reopened`). ### 6.2 Data model #### 6.2.1 `inspection_calendars` Persists the master inspection-calendar record. Required columns include `id` (UUID PK), `tenant_id` (UUID FK), `site_id` (UUID FK — mandatory per DEC-22-02), `study_id` (UUID FK nullable), `product_id` (UUID FK nullable), `supplier_id` (UUID FK nullable), `batch_id` (UUID FK nullable), `project_id` (UUID FK nullable), `process_scope` (TEXT nullable), `inspection_type` (ENUM `fda_routine` / `fda_pai` / `fda_for_cause` / `ema_gmp` / `mhra_gmp` / `cdsco_gmp` / `health_canada` / `pmda` / `notified_body` / `internal_audit` / `supplier_audit` / `mock_drill` / `regulatory_response_followup`), `regulatory_body` (ENUM `fda` / `ema` / `mhra` / `cdsco` / `health_canada` / `pmda` / `notified_body` / `internal` / `supplier`), `title` (TEXT NOT NULL), `description` (TEXT nullable), `planned_date` (DATE NOT NULL), `actual_start_date` (DATE nullable), `actual_end_date` (DATE nullable), `readiness_threshold` (NUMERIC(3,2) DEFAULT 0.85), `status` (ENUM `planned` / `in_progress` / `completed` / `archived`), `archived_at` (TIMESTAMPTZ nullable), `archived_by` (UUID nullable), `archive_reason` (TEXT nullable), `reopened_at` (TIMESTAMPTZ nullable), `reopened_by` (UUID nullable), `reopen_reason` (TEXT nullable), `created_by` (UUID NOT NULL), `created_at` (TIMESTAMPTZ DEFAULT NOW), `updated_by` (UUID NOT NULL), `updated_at` (TIMESTAMPTZ NOT NULL), `version` (INTEGER DEFAULT 1). Uniqueness: `(tenant_id, site_id, inspection_type, planned_date)` per DEC-22-04. RLS: `ENABLE ROW LEVEL SECURITY`; policy `tenant_isolation USING (tenant_id = current_setting('app.current_tenant_id')::uuid)`. #### 6.2.2 `self_inspections` Persists self-inspection records. Required columns include `id`, `tenant_id`, `inspection_calendar_id` (UUID FK nullable for standalone self-inspections), `site_id`, `study_id`, `product_id`, `conducted_date`, `conducted_by`, `reviewed_by` (nullable), `reviewed_at` (nullable), `completion_summary` (TEXT — required for `completed` per DEC-22-05), `checklist_id_used` (UUID FK to `inspection_checklists.id` with version), `evidence_package_id` (UUID nullable), `score` (NUMERIC(3,2)), `findings_count` (INTEGER), `status` (ENUM `draft` / `in_progress` / `review` / `completed`), `e_signature_id` (UUID FK to `electronic_signatures` — populated on `completed` per DEC-22-18), `reason_for_change` (TEXT nullable per DEC-22-17), `reopened_at` (TIMESTAMPTZ nullable), `reopened_by` (UUID nullable), `reopen_reason` (TEXT nullable), audit columns. #### 6.2.3 `inspection_checklists` Persists controlled-checklist headers. Required columns include `id`, `tenant_id`, `inspection_type`, `regulatory_body`, `title`, `version` (INTEGER NOT NULL), `effective_from` (TIMESTAMPTZ nullable), `effective_to` (TIMESTAMPTZ nullable), `supersedes_checklist_id` (UUID FK self-reference nullable), `approved_by` (UUID nullable), `approved_at` (TIMESTAMPTZ nullable), `e_signature_id` (UUID FK), `status` (ENUM `draft` / `effective` / `superseded` / `archived`), audit columns. Uniqueness: `(tenant_id, inspection_type, regulatory_body, version)` per DEC-22-06. #### 6.2.4 `inspection_checklist_items` Persists checklist-item rows. Required columns include `id`, `tenant_id`, `inspection_checklist_id` (FK with version preservation), `item_order` (INTEGER), `item_text` (TEXT), `regulatory_citation_id` (UUID FK to `regulatory_intelligence.citations` — structured citation per DEC-22-06), `required` (BOOLEAN), audit columns. Items are immutable on `effective` checklists; revisions create new version rows. #### 6.2.5 `sme_question_banks` Persists SME question-bank headers. Mirrors `inspection_checklists` lifecycle. Columns include `id`, `tenant_id`, `role`, `regulatory_body`, `title`, `version`, `effective_from`, `effective_to`, `supersedes_question_bank_id`, `pass_threshold` (NUMERIC(3,2)), `approved_by`, `approved_at`, `e_signature_id`, `status` (ENUM `draft` / `effective` / `superseded` / `archived`), audit columns. #### 6.2.6 `sme_questions` Persists SME-question rows. Columns include `id`, `tenant_id`, `sme_question_bank_id`, `question_text`, `expected_answer`, `weight`, audit columns. Immutable on effective banks. #### 6.2.7 `sme_training_sessions` Persists SME training-session records. Columns include `id`, `tenant_id`, `sme_question_bank_id`, `question_bank_version`, `scoring_rule_version`, `assigned_to`, `initiated_by`, `completed_by`, `content_release_id`, `started_at`, `completed_at`, `status` (ENUM `in_progress` / `completed` / `passed` / `failed`), `score`, audit columns. #### 6.2.8 `sme_answers` Persists session-answer records. Immutable after session finalization. Columns include `id`, `tenant_id`, `sme_training_session_id`, `sme_question_id`, `answer_text`, `is_correct`, `score_contribution`, audit columns. #### 6.2.9 `mock_drills` Persists mock-drill records. Columns include `id`, `tenant_id`, `inspection_calendar_id` (nullable), `drill_date`, `conducted_by`, `sme_question_bank_id` (effective version), `outcome_summary` (TEXT — required for `completed` per DEC-22-08), `score`, `status` (ENUM `scheduled` / `in_progress` / `completed` / `archived`), `e_signature_id` (nullable; required where policy requires per DEC-22-18), audit columns. #### 6.2.10 `mock_drill_questions` Persists per-drill question rows. Columns include `id`, `tenant_id`, `mock_drill_id`, `question_text`, `expected_answer`, `actual_answer`, `score_contribution`, `content_origin` (ENUM `human` / `ai_assisted` per DEC-22-15), `ai_request_id` (UUID FK nullable to `ai_requests`), `model_id` (TEXT nullable), `model_version` (TEXT nullable), `prompt_version` (TEXT nullable), `mira_confidence_score` (NUMERIC(3,2) nullable), `accepted_by` (UUID nullable), `accepted_at` (TIMESTAMPTZ nullable), `human_edited` (BOOLEAN), `source_citation_snapshot` (JSONB nullable), `mira_feedback` (TEXT nullable), audit columns. #### 6.2.11 `readiness_scorecards` Persists immutable versioned scorecard snapshots per DEC-22-09. Columns include `id`, `tenant_id`, `inspection_calendar_id` (FK), `formula_version` (TEXT NOT NULL), `overall_score` (NUMERIC(3,2)), `documentation_score` (NUMERIC(3,2)), `mock_drill_score` (NUMERIC(3,2)), `training_score` (NUMERIC(3,2)), `capa_score` (NUMERIC(3,2)), `deviation_score` (NUMERIC(3,2)), `risk_score` (NUMERIC(3,2)), `data_quality_score` (NUMERIC(3,2)), `document_retrieval_speed_score` (NUMERIC(3,2) nullable), `component_inputs` (JSONB), `fallback_flags` (JSONB), `generated_by_rule` (TEXT), `generated_by` (UUID NOT NULL), `generated_at` (TIMESTAMPTZ DEFAULT NOW), audit columns. Scorecards are immutable; no UPDATE except corrective platform-level revoke (audit-logged with reason). #### 6.2.12 `back_room_queues` Persists back-room queue headers. Columns include `id`, `tenant_id`, `inspection_calendar_id` (FK), `site_id`, `coordinator_id`, `status` (ENUM `pending` / `active` / `completed`), audit columns. #### 6.2.13 `back_room_requests` Persists per-request retrieval rows per DEC-22-10. Columns include `id`, `tenant_id`, `back_room_queue_id`, `request_number` (INTEGER), `inspector_request_text`, `search_query`, `document_id` (UUID FK to `documents.id`), `document_version_id` (UUID FK to `document_versions.id` per DEC-22-10), `document_hash` (TEXT per DEC-22-10), `retrieval_method` (ENUM `direct` / `ai_assisted`), `retrieval_timestamp` (TIMESTAMPTZ), `requested_by` (UUID), `retrieved_by` (UUID), `retrieval_outcome` (ENUM `retrieved` / `unable_to_locate`), `unable_to_locate_reason` (TEXT nullable), `citation_snapshot` (JSONB nullable), `mira_assisted` (BOOLEAN), `mira_confidence_score` (NUMERIC(3,2) nullable), `ai_request_id` (UUID FK nullable to `ai_requests`), `accepted_by` (UUID nullable), `accepted_at` (TIMESTAMPTZ nullable), `status` (ENUM `pending` / `in_retrieval` / `retrieved` / `unable_to_locate` / `completed`), audit columns. #### 6.2.14 `deficiency_responses` Persists deficiency-response records per DEC-22-11. Columns include `id`, `tenant_id`, `inspection_calendar_id` (FK), `deficiency_number`, `deficiency_text`, `severity` (ENUM `critical` / `major` / `minor` / `observation`), `regulatory_body`, `assigned_to`, `due_date`, `response_text`, `submitted_at`, `submitted_by`, `submitted_e_signature_id`, `accepted_at`, `accepted_by`, `accepted_e_signature_id`, `closed_at`, `closed_by`, `closed_e_signature_id`, `status` (ENUM `draft` / `in_review` / `submitted` / `accepted` / `closed`), `reason_for_change` (TEXT nullable per DEC-22-17), `reviewed_by`, `reviewed_at`, audit columns. #### 6.2.15 `deficiency_response_items` Persists per-item response rows. Columns include `id`, `tenant_id`, `deficiency_response_id`, `item_text`, `item_owner`, `due_date`, `evidence_reference_id`, `verified_by` (UUID — SoD-distinct per SoD-22-04), `verified_at`, `verifier_e_signature_id`, `status` (ENUM `open` / `in_progress` / `completed` / `verified`), audit columns. #### 6.2.16 `inspection_commitments` Persists commitment records per DEC-22-12. Columns include `id`, `tenant_id`, `inspection_calendar_id` (FK), `deficiency_response_id` (FK nullable), `commitment_text`, `severity`, `assigned_to`, `due_date`, `verified_by`, `verified_at`, `verifier_e_signature_id`, `closed_by`, `closed_at`, `closed_e_signature_id`, `capa_id` (UUID FK nullable to `capa.id` per DEC-22-12), `linked_capa_at` (TIMESTAMPTZ nullable), `linked_capa_by` (UUID nullable), `status` (ENUM `open` / `in_progress` / `completed` / `verified` / `closed`), audit columns. #### 6.2.17 `lessons_learned` Persists lessons-learned records per DEC-22-13. Columns include `id`, `tenant_id`, `inspection_calendar_id` (FK), `lesson_text`, `lesson_type`, `applicable_roles` (TEXT[]), `remediation_action` (TEXT nullable), `published_at`, `published_by`, `publication_e_signature_id`, `effective_from`, `superseded_by` (UUID FK self-reference nullable), `status` (ENUM `draft` / `published` / `archived`), audit columns. #### 6.2.18 `inspection_response_narratives` Persists inspection-response narrative drafts including `mira_assisted_draft`. Columns include `id`, `tenant_id`, `deficiency_response_id`, `narrative_text`, `is_mira_assisted` (BOOLEAN), `mira_assisted_draft` (TEXT nullable; advisory only — never promoted to system-of-record narrative without explicit human confirmation and e-signature per ARCH-AI-001 / DEC-22-15), `human_confirmed` (BOOLEAN), `human_confirmed_by` (UUID nullable), `human_confirmed_at` (TIMESTAMPTZ nullable), `e_signature_id` (UUID FK nullable; required for system-of-record narrative), audit columns. #### 6.2.19 RLS Every Module 22 table has `ENABLE ROW LEVEL SECURITY` and tenant-isolation policy. ### 6.3 Application programming interface The canonical API mount is `/api/v1/inspections/*` per DEC-22-01. All routes validate request params, query strings, and bodies through typed schemas before service execution per DEC-22-03. The route table follows. | Route | Method | Permission | Status | |---|---|---|---| | `/api/v1/inspections/calendars` | GET / POST | `inspections:read` / `inspections:create` | (typed schema) | | `/api/v1/inspections/calendars/:id` | GET / PATCH | `inspections:read` / `inspections:update` | | | `/api/v1/inspections/calendars/:id/archive` | POST | `inspection_owner_authority` + HITL + e-sign | target route per DEC-22-18 | | `/api/v1/inspections/calendars/:id/reopen` | POST | `executive_authority` co-sign + HITL + reason | target route per DEC-22-22 | | `/api/v1/inspections/calendars/:id/close` | POST | `final_quality_approver` + HITL + e-sign + back-room/deficiency/commitment terminal check | target route per DEC-22-18 | | `/api/v1/inspections/calendars/:id/readiness-scorecard` | POST | `inspections:readiness:generate` | (versioned formula) | | `/api/v1/inspections/calendars/:id/inspection-readiness-export` | POST | `inspections:readiness:export` | target route per DEC-22-19 | | `/api/v1/inspections/self-inspections` | GET / POST | `inspections:read` / `inspections:self_inspection:create` | | | `/api/v1/inspections/self-inspections/:id` | GET / PATCH | `inspections:read` / `inspections:update` | | | `/api/v1/inspections/self-inspections/:id/complete` | POST | `inspections:self_inspection:complete` + HITL + e-sign | per DEC-22-05 | | `/api/v1/inspections/self-inspections/:id/reopen` | POST | `final_quality_approver` co-sign + HITL + reason | target route per DEC-22-23 | | `/api/v1/inspections/checklists` | GET / POST | `inspections:read` / `inspections:checklist:create` | | | `/api/v1/inspections/checklists/:id` | GET / PATCH | `inspections:read` / `inspections:update` | (draft only) | | `/api/v1/inspections/checklists/:id/release` | POST | `controlled_content_approver` + HITL + e-sign | target route per DEC-22-06 | | `/api/v1/inspections/checklists/:id/items` | GET / POST | `inspections:checklist:items` | (draft only) | | `/api/v1/inspections/checklists/:id/items/:itemId` | PATCH | `inspections:checklist:items` | (draft only) | | `/api/v1/inspections/sme-banks` | GET / POST | `inspections:read` / `inspections:sme:create` | | | `/api/v1/inspections/sme-banks/:id` | GET / PATCH | `inspections:read` / `inspections:update` | (draft only) | | `/api/v1/inspections/sme-banks/:id/release` | POST | `controlled_content_approver` + HITL + e-sign | target route per DEC-22-07 | | `/api/v1/inspections/sme-banks/:id/training-sessions` | GET / POST | `inspections:sme:session` | | | `/api/v1/inspections/training-sessions/:id/answer` | POST | `inspections:sme:session` | | | `/api/v1/inspections/training-sessions/:id/complete` | POST | `inspections:sme:complete` | | | `/api/v1/inspections/mock-drills` | GET / POST | `inspections:read` / `inspections:drill:create` | | | `/api/v1/inspections/mock-drills/:id` | GET / PATCH | `inspections:read` / `inspections:update` | | | `/api/v1/inspections/mock-drills/:id/execute` | POST | `inspections:drill:execute` | | | `/api/v1/inspections/mock-drills/:id/add-question` | POST | `inspections:drill:add_question` (ai-assisted provenance per DEC-22-15) | | | `/api/v1/inspections/mock-drills/:id/complete` | POST | `inspections:drill:complete` + HITL + e-sign (where policy requires) | per DEC-22-08 | | `/api/v1/inspections/back-room-queues` | GET / POST | `inspections:back_room:queue:read` / `inspections:back_room:queue:create` | | | `/api/v1/inspections/back-room-queues/:id/requests` | GET / POST | `inspections:back_room:request:read` / `inspections:back_room:request:create` | | | `/api/v1/inspections/back-room-requests/:id` | GET / PATCH | `inspections:back_room:request:read` / `inspections:back_room:request:update` | per DEC-22-10 | | `/api/v1/inspections/back-room-requests/:id/retrieve` | POST | `inspections:back_room:request:retrieve` | target route per DEC-22-10 | | `/api/v1/inspections/back-room-requests/:id/unable-to-locate` | POST | `back_room_coordinator_authority` | target route per DEC-22-10 | | `/api/v1/inspections/back-room-requests/:id/complete` | POST | `back_room_coordinator_authority` | target route per DEC-22-10 | | `/api/v1/inspections/deficiency-responses` | GET / POST | `inspections:deficiency:read` / `inspections:deficiency:create` | | | `/api/v1/inspections/deficiency-responses/:id` | GET / PATCH | `inspections:deficiency:read` / `inspections:deficiency:update` | per DEC-22-11 | | `/api/v1/inspections/deficiency-responses/:id/items` | GET / POST | `inspections:deficiency:item` | | | `/api/v1/inspections/deficiency-responses/:id/items/:itemId/verify` | POST | `inspections:deficiency:item:verify` (SoD-distinct per SoD-22-04) | target route per DEC-22-11 | | `/api/v1/inspections/deficiency-responses/:id/submit` | POST | `deficiency_review_authority` + HITL + e-sign | target route per DEC-22-11 | | `/api/v1/inspections/deficiency-responses/:id/accept` | POST | `deficiency_review_authority` + HITL + e-sign | target route per DEC-22-11 | | `/api/v1/inspections/deficiency-responses/:id/close` | POST | `deficiency_review_authority` + HITL + e-sign + commitment-CAPA terminal check | target route per DEC-22-11 / DEC-22-21 | | `/api/v1/inspections/commitments` | GET / POST | `inspections:commitment:read` / `inspections:commitment:create` | | | `/api/v1/inspections/commitments/:id` | GET / PATCH | `inspections:commitment:read` / `inspections:commitment:update` | | | `/api/v1/inspections/commitments/:id/link-capa` | POST | `inspection_owner_authority` (emits `commitment_capa_linked`) | target route per DEC-22-12 | | `/api/v1/inspections/commitments/:id/verify` | POST | `commitment_verification_authority` + HITL + e-sign | target route per DEC-22-12 | | `/api/v1/inspections/commitments/:id/close` | POST | `commitment_verification_authority` + HITL + e-sign + linked-CAPA terminal | target route per DEC-22-12 | | `/api/v1/inspections/lessons-learned` | GET / POST | `inspections:lessons:read` / `inspections:lessons:create` | | | `/api/v1/inspections/lessons-learned/:id` | GET / PATCH | `inspections:lessons:read` / `inspections:lessons:update` | (draft only) | | `/api/v1/inspections/lessons-learned/:id/publish` | POST | `lesson_publication_authority` + HITL + e-sign | target route per DEC-22-13 | ### 6.4 Workflow #### 6.4.1 Inspection-calendar lifecycle ```mermaid stateDiagram-v2 [*] --> planned: create planned --> in_progress: start in_progress --> completed: close (HITL + e-sign + back-room/deficiency/commitment terminal) completed --> archived: archive (HITL + e-sign + reason) archived --> in_progress: reopen (executive co-sign + reason — DEC-22-22 + SoD-22-06; appends new iteration) ``` #### 6.4.2 Self-inspection lifecycle ```mermaid stateDiagram-v2 [*] --> draft: create draft --> in_progress: start in_progress --> review: submit for review review --> completed: complete (HITL + e-sign + structured findings summary) completed --> in_progress: reopen (final_quality_approver co-sign + reason — DEC-22-23 + SoD-22-06; appends new iteration) ``` #### 6.4.3 Controlled-checklist lifecycle ```mermaid stateDiagram-v2 [*] --> draft: create draft --> effective: release (controlled_content_approver + HITL + e-sign) effective --> superseded: revise (new version row created) superseded --> archived: archive ``` #### 6.4.4 Mock-drill lifecycle ```mermaid stateDiagram-v2 [*] --> scheduled: create scheduled --> in_progress: execute in_progress --> completed: complete (structured outcomes + e-sign where policy requires) completed --> archived: archive ``` #### 6.4.5 Back-room-request lifecycle ```mermaid stateDiagram-v2 [*] --> pending: create pending --> in_retrieval: assign retriever in_retrieval --> retrieved: retrieve (document version + hash + retrieval method + retriever + retrieval outcome) in_retrieval --> unable_to_locate: cannot locate (with reason) retrieved --> completed: close unable_to_locate --> completed: close ``` #### 6.4.6 Deficiency-response lifecycle ```mermaid stateDiagram-v2 [*] --> draft: create draft --> in_review: submit for review in_review --> submitted: submit to regulator (HITL + e-sign) submitted --> accepted: regulator accept (HITL + e-sign) accepted --> closed: close (HITL + e-sign + commitment-CAPA terminal check) ``` #### 6.4.7 Commitment lifecycle ```mermaid stateDiagram-v2 [*] --> open: create open --> in_progress: start in_progress --> completed: complete completed --> verified: verify (SoD-distinct verifier + HITL + e-sign) verified --> closed: close (HITL + e-sign + linked-CAPA terminal) ``` #### 6.4.8 Lessons-learned lifecycle ```mermaid stateDiagram-v2 [*] --> draft: create draft --> published: publish (lesson_publication_authority + HITL + e-sign) published --> archived: archive ``` ### 6.5 Business rules - BR-22-01: Calendar uniqueness `(tenant_id, site_id, inspection_type, planned_date)` per DEC-22-04. - BR-22-02: `site_id` mandatory at calendar level per DEC-22-02. - BR-22-03: Self-inspection completion requires structured findings summary, readiness score basis, and linked checklist version or rationale per DEC-22-05. - BR-22-04: Effective controlled-checklist versions are immutable; revisions create new version rows per DEC-22-06. - BR-22-05: Effective SME question-bank versions are immutable per DEC-22-07. - BR-22-06: Mock-drill completion requires structured outcomes per DEC-22-08. - BR-22-07: Mock-drill AI-assisted questions persist full provenance per DEC-22-15. - BR-22-08: Readiness scorecards are immutable versioned snapshots with explicit formula version + component inputs per DEC-22-09. - BR-22-09: Back-room retrieval persists document-version + hash + retrieval-method + retriever + retrieval-outcome per DEC-22-10. - BR-22-10: Back-room AI-assisted retrieval persists `ai_request_id`, confidence, accepted_by, accepted_at, citation snapshot per DEC-22-10. - BR-22-11: Deficiency-response submission / acceptance / closure require `deficiency_review_authority` + HITL + bound e-signature per DEC-22-11. - BR-22-12: Response-item verification requires SoD-distinct verifier per SoD-22-04. - BR-22-13: Critical / major deficiencies cannot close without linked commitment escalated to URS-18 CAPA via `commitment_capa_linked` event, unless explicitly waived through approved rationale per DEC-22-21. - BR-22-14: Lessons-learned publication requires `lesson_publication_authority` + HITL + e-signature per DEC-22-13. - BR-22-15: Calendar archive requires `final_quality_approver` + HITL + e-signature + archive reason per DEC-22-18. - BR-22-16: Inspection closure requires all back-room requests `completed`, all deficiency responses `closed`, all commitments `closed` or waived, and all linked CAPAs in terminal status per DEC-22-18. - BR-22-17: Calendar reopen `archived → in_progress` requires `executive_authority` co-sign + documented reason; appends new iteration without mutating prior archived evidence per DEC-22-22. - BR-22-18: Self-inspection reopen `completed → in_progress` requires `final_quality_approver` co-sign + documented reason per DEC-22-23. - BR-22-19: Inspection observations emit `inspection_observation_finding_created` event to URS-21 for standalone-finding creation per DEC-22-14. - BR-22-20: Material updates on regulated records after the record leaves draft require structured reason-for-change per DEC-22-17. - BR-22-21: Bound e-signature persistence on every regulated final action via the `electronic_signatures` substrate per DEC-22-18. - BR-22-22: Inspection-readiness export consumes read-only evidence from every URS-01.URS-21 / URS-23.URS-35 module per DEC-22-19; the export hash is persisted; not a system-of-record artifact. - BR-22-23: `mira_assisted_draft` content shall not be promoted to the system-of-record narrative without explicit human confirmation and e-signature per ARCH-AI-001 + DEC-22-15. - BR-22-24: `platform_admin` / `super_admin` are support / break-glass only paths per DEC-22-20. ### 6.6 Audit trail Every Module 22 record mutation persists an audit-trail entry via `auditTrailService.log(.)` with `tenantId`, `userId`, `action`, `resourceType`, `resourceId`, `details` (field-level diff), `ipAddress`, `timestamp`. Material updates after draft persist `reason_for_change` in the audit `details` JSON per DEC-22-17. Regulated final actions (self-inspection completion, checklist release, SME-bank release, mock-drill completion where required, deficiency submission / acceptance / closure, commitment verification / closure, lesson publication, calendar archive, inspection closure, governed reopen) persist a bound e-signature via the `electronic_signatures` substrate; the JSON multi-signature evidence in the audit-trail `details` JSON is a derived snapshot for fast querying / inspection-prep export per DEC-22-18. The audit trail is append-only; UPDATE / DELETE on the audit-trail table is prohibited; only database-level superuser (infrastructure) can access raw audit tables. ### 6.7 Error handling The Module 22 error-code register follows. All errors return structured `{ error: string, code: string, details?: unknown }` payloads. | Code | HTTP | Meaning | |---|---|---| | `INS_VALIDATION_FAILED` | 400 | Request schema validation failure (per DEC-22-03) | | `INS_UNAUTHORIZED` | 401 | Missing or invalid authentication | | `INS_FORBIDDEN` | 403 | RBAC permission denied | | `INS_NOT_FOUND` | 404 | Resource not found | | `INS_DUPLICATE_KEY` | 409 | Duplicate business key (e.g., calendar uniqueness violation) | | `INS_INVALID_TRANSITION` | 422 | Lifecycle transition not permitted from current status | | `INS_MISSING_REQUIRED_FIELD` | 422 | Required field missing for the requested action | | `INS_AI_PROVENANCE_INCOMPLETE` | 422 | AI-assisted action attempted without full provenance fields | | `INS_DOCUMENT_VERSION_REQUIRED` | 422 | Back-room retrieval missing document-version + hash provenance | | `INS_AUTHORITY_REQUIRED` | 422 | Action requires Authority Profile that the actor does not hold | | `INS_HITL_DECISION_REQUIRED` | 422 | Action requires HITL decision capture | | `INS_E_SIGNATURE_REQUIRED` | 422 | Action requires bound e-signature persistence | | `INS_REASON_FOR_CHANGE_REQUIRED` | 422 | Material update after draft missing reason-for-change | | `INS_CONTEXT_FILTER_MISMATCH` | 422 | Query against context column not present in schema | | `INS_BACK_ROOM_INCOMPLETE` | 422 | Calendar closure attempted with back-room requests not in `completed` status | | `INS_DEFICIENCY_RESPONSE_OPEN` | 422 | Calendar closure attempted with deficiency responses not in `closed` status | | `INS_COMMITMENT_OPEN` | 422 | Calendar closure attempted with commitments not in `closed` or waived status | | `INS_LINKED_CAPA_OPEN` | 422 | Commitment closure attempted with linked CAPA not in URS-18 terminal status | | `INS_REOPEN_AUTHORITY_REQUIRED` | 422 | Reopen attempted without executive authority co-sign | | `INS_FORMULA_VERSION_REQUIRED` | 422 | Readiness-scorecard generation attempted without active formula version | | `INS_INSUFFICIENT_SOURCE_METRICS` | 422 | Scorecard source metrics below rule-policy threshold | | `INS_INTERNAL` | 500 | Unhandled server error (sanitized payload; full error logged server-side) | ### 6.8 Configuration rules - `readiness_threshold` is configurable per calendar; default `0.85`. - Readiness-scorecard formula versions are configured records under URS-13 change control. - Inspection type enumerations may be extended only through approved controlled configuration if the platform supports enum extension safely. - Pass thresholds for SME training sessions are configured per question bank. - Document-category SLA targets for back-room retrieval are configured at platform level. --- ## 7. Non-functional Requirements - NFR-22-01: List endpoint pagination — every list endpoint supports `page`, `pageSize`, `sortBy`, `sortDir`; default `pageSize = 50`, max `pageSize = 200`. - NFR-22-02: Query latency — p95 < 800ms for list endpoints under typical tenant load (100k inspection-calendar rows; 1M back-room-request rows). - NFR-22-03: Readiness-scorecard generation latency — p95 < 5s including cross-module reads. - NFR-22-04: Inspection-readiness export latency — p95 < 60s for full URS-01.URS-21 / URS-23.URS-35 export. - NFR-22-05: Audit-trail append latency — p99 < 200ms. - NFR-22-06: AI-assisted retrieval latency — p95 < 8s including MIRA round-trip. - NFR-22-07: Concurrent-user capacity — 200 concurrent inspection users per tenant. - NFR-22-08: Storage scalability — 10M back-room-request rows per tenant; 1M deficiency-response rows per tenant; 100k commitment rows per tenant. - NFR-22-09: Backup / restore RPO ≤ 15 min; RTO ≤ 4 hours per URS-35. --- ## 8. Localization Module 22 supports English (en-US, en-GB), Hindi (hi-IN), Marathi (mr-IN), and Japanese (ja-JP) for UI labels at launch. Inspection-record content (deficiency text, response text, lesson text) is stored in the user-input language; the platform does not translate regulated narrative. --- ## 9. Migration ### 9.1 Migration scope Module 22 launches with no pre-existing inspection data in production tenants (greenfield). For tenants that pilot internal-audit or supplier-audit data import, the URS-22-VAL-008 migration evidence gate applies: source data must be loaded under a controlled migration run with alignment evidence, sample-row attribution, and post-migration audit. ### 9.2 Schema migration Migration 041 (`041_inspection_enhancement.sql`) is the baseline; target migrations (042+) add `site_id` to `inspection_calendars` and descendant operational tables, add AI-provenance columns to `mock_drill_questions` and `back_room_requests`, add document-version columns to `back_room_requests`, add bound e-signature columns to `self_inspections`, `inspection_checklists`, `sme_question_banks`, `mock_drills`, `deficiency_responses`, `inspection_commitments`, and `lessons_learned`, add reopen columns to `inspection_calendars` and `self_inspections`, replace narrow uniqueness constraints with `(tenant_id, site_id, inspection_type, planned_date)` for calendars and version-aware uniqueness for controlled-content tables, add `formula_version` and `component_inputs` to `readiness_scorecards`, and update `MODULE_CONTEXT_CONFIG.inspection` to match the persisted schema exactly. ### 9.3 Migration evidence gate (URS-22-VAL-008) The migration evidence gate is satisfied when all of the following are true: (a) all target migrations have been applied to the staging environment with no errors; (b) every Module 22 table has `ENABLE ROW LEVEL SECURITY` and tenant-isolation policy verified; (c) every Module 22 route has typed schema validation verified; (d) every regulated final action persists bound e-signature verified; (e) AI-provenance columns are populated on every AI-assisted record verified; (f) document-version + hash provenance is populated on every back-room retrieval verified; (g) readiness-scorecard generation produces frontend-contract-aligned response verified; (h) governed reopen workflow append-only behavior verified; (i) inspection-observation-finding event emission to URS-21 verified; (j) commitment-CAPA linkage event emission to URS-18 verified; (k) inspection-readiness export consumption from every URS-01.URS-21 / URS-23.URS-35 module verified; (l) audit-trail coverage on every mutation verified; (m) reason-for-change discipline on material updates verified; (n) the §17 validation evidence pack signed by Validation Head, QA Head, RA Head. --- ## 10. Decommissioning Module 22 records (inspection calendars, self-inspections, mock drills, readiness scorecards, back-room requests, deficiency responses, commitments, lessons learned, inspection-response narratives) are subject to the platform record-retention policy: retained for the longer of (a) 30 years from inspection closure (FDA 21 CFR Part 211 / 211.180 retention) or (b) 50 years from product expiry (EU GMP). On tenant decommissioning, records are exported to the tenant's controlled archive per the URS-35 backup-restore contract; soft-deleted records remain query-accessible for audit purposes. --- ## 11. Decisions, Dependencies, Risks, and Error Handling ### 11.1 Closed decision posture **No Module 22 internal decisions outstanding.** Launch decisions are captured in the locked decisions above. ### 11.2 External dependencies - URS-12 document-version registry must support `document_hash` column for back-room retrieval provenance. - URS-13 change-control register must support `formula_version` change requests for readiness-scoring formula. - URS-18 CAPA register must accept `audit_observation` source type per URS-18 declared source set. - URS-21 findings register must accept `inspection_observation` source type for standalone findings. - URS-32 MIRA AI must support read-only `useMiraRecord('inspection_calendar',.)`, `useMiraRecord('self_inspection',.)`, `useMiraRecord('mock_drill',.)`, `useMiraRecord('back_room_request',.)`, `useMiraRecord('deficiency_response',.)` mappings. ### 11.3 Risks - Risk-22-01: Cross-module data dependencies on readiness scorecard generation may create latency under high-tenant load. Mitigation: NFR-22-03 latency budget with cross-module read caching; formula-version-aware cache invalidation. - Risk-22-02: AI-assisted retrieval quality may degrade if URS-12 document corpus has low metadata quality. Mitigation: AI-provenance monitoring per URS-32; back-room AI quality dashboard; rejection-rate alerting. - Risk-22-03: Inspection-readiness export size may exceed 100MB for large tenants. Mitigation: NFR-22-04 latency budget; pagination on inner-module reads; export-hash for incremental regeneration. - Risk-22-04: Reopen workflow append-only behavior may surprise users expecting in-place edit. Mitigation: explicit reopen-pattern training per URS-22-VAL-008; UX language reinforcing append-only semantics. ### 11.4 Out-of-scope risks tracked elsewhere - Direct regulator portal integration (FDA ESG, EMA EudraVigilance for inspection responses) — tracked as future-state. ### 11.5 Risk owner The Module-22 risk register is owned by the Inspection Squad with quarterly review by QA Head and RA Head. ### 11.6 Decision discipline No Module 22 internal decisions outstanding. New internal design changes after signature are controlled through URS-13 Change Control. True external dependencies are tracked in §18 or the module dependency register. ### 11.7 Error Handling and Negative Paths This section defines the controlled error envelope, the enumerated machine-code catalogue, and the negative-path response contract required for this module. The error envelope is the standard platform envelope (human message, machine code in upper-snake-case, optional structured details, correlation identifier). Errors are returned with the appropriate HTTP status; the UI surfaces inline errors at the field of cause where applicable, otherwise a controlled error toast or modal. Every error path is logged to the URS-06 audit substrate when the originating action is regulated; errors that occur before authentication are logged without `userId`. Audit-trail write failure on a state-changing action MUST cause the originating action to NOT commit (atomic write per URS-04 BR-04-15). The enumerated machine codes for this module's negative paths are defined alongside the corresponding lifecycle gates, segregation-of-duties controls, and authority-resolution outcomes throughout §6 (Back-end Requirements) and §13 (Segregation of Duties); engineering MUST surface every enumerated machine code through the standard envelope and MUST NOT swallow errors silently. Cross-module error propagation follows the §20 Cross-Module Event Contract. --- ## 12. Security - SEC-22-01: Tenant isolation enforced at RLS on every Module 22 table. - SEC-22-02: RBAC enforced on every route via `requirePermission(.)` before service execution. - SEC-22-03: Authority resolution enforced on regulated final actions before HITL + e-signature. - SEC-22-04: HITL decision capture enforced before bound e-signature persistence. - SEC-22-05: Bound e-signature persistence via the `electronic_signatures` substrate; signature binding includes user identity, action, resource ID, action timestamp, and signature hash. - SEC-22-06: PII / PHI in inspection records (inspector identity, deficiency text, response narrative) is redacted in logs; full content remains in the system-of-record record fields. - SEC-22-07: Audit-trail integrity via URS-06 hash chain. - SEC-22-08: AI-request provenance via `ai_requests` and `mira_context_access_log`; AI-assisted content cannot be promoted to system-of-record without explicit human confirmation + e-signature per ARCH-AI-001. - SEC-22-09: Document-version + hash provenance for back-room retrieval; document hash cryptographically verified at retrieval time. - SEC-22-10: Inspection-readiness export hash persisted; export integrity verifiable post-generation. - SEC-22-11: `platform_admin` / `super_admin` break-glass actions logged with reason and reviewed in platform support audit per DEC-22-20. - SEC-22-12: Deficiency-response narrative redaction supported for inspector-confidential content where regulator instructs. --- ## 13. Segregation of Duties | SoD ID | Constraint | |---|---| | SoD-22-01 | The self-inspection completer MUST NOT be the self-inspection conductor when tenant policy requires reviewer separation. | | SoD-22-02 | The mock-drill completer MUST NOT be the AI-question accepter for the same drill where policy requires content-acceptance separation. | | SoD-22-03 | The deficiency-response submitter MUST NOT be the deficiency-response acceptor (regulator-side action) where regulator-side action is captured in the system. | | SoD-22-04 | The response-item verifier MUST NOT be the response-item performer (verifier SoD-distinct from performer). | | SoD-22-05 | The commitment verifier MUST NOT be the commitment performer (verifier SoD-distinct from performer); the commitment closer MUST NOT be the commitment performer. | | SoD-22-06 | The reopen co-signer (executive authority for calendar reopen per DEC-22-22; final_quality_approver for self-inspection reopen per DEC-22-23) MUST NOT be the original closure / archive signer; reopen append-only semantics enforced. | | SoD-22-07 | The `platform_admin` / `super_admin` support / break-glass action MUST NOT be a regulated production action; break-glass is logged and reviewed per DEC-22-20. | --- ## 14. Regulatory Mapping | Predicate rule | Section | Module 22 binding | |---|---|---| | FDA 21 CFR Part 11 | §11.10(a) — Validation; §11.10(d) — Authority checks; §11.10(e) — Audit trails; §11.50 / §11.70 — Signature manifestation and binding | URS-22-VAL-008 + bound e-sign on every regulated final action + audit-trail on every mutation | | FDA 21 CFR Part 211 (cGMP) | §211.180 — Records and reports retention; §211.192 — Production record review; §211.194 — Laboratory records | Inspection record retention 30+ years; deficiency-response records as quality records; back-room retrieval evidence as quality records | | FDA Form 483 / EIR | FDA Investigations Operations Manual (IOM) §5 — Inspection Conduct | Inspection observation handling; standalone-finding emission to URS-21; deficiency-response submission via Module 22 | | EU GMP Annex 11 | §1 — Risk Management; §4 — Validation; §9 — Audit Trails; §12 — Security; §16 — Incident Management | Module 22 readiness-scorecard, validation evidence, audit-trail integrity, security, deficiency response as incident handling | | EU GMP Annex 22 Draft 2025 | §7 — HITL for AI in pharmaceutical manufacturing | Internal forward-looking control; AI-assisted content advisory only; human-signed disposition is the system of record (subject to a future jurisdiction-specific legal assessment) | | EU AI Act (Regulation 2024/1689) | Annex III — High-Risk AI; Art. 13 — Transparency | Internal forward-looking control; AI-assisted readiness scoring / response narrative drafted by AI is high-risk under internal classification; transparency obligations met via advisory-labeling (subject to a future jurisdiction-specific legal assessment) | | MHRA Data Integrity Guidance | ALCOA+ — Attributable, Legible, Contemporaneous, Original, Accurate, plus Complete, Consistent, Enduring, Available | Audit-trail attributability; bound e-signature; document-version + hash provenance; record retention | | GAMP 5 Cat 5 | Custom-application GxP validation lifecycle | URS-22 validation evidence pack per URS-22-VAL-008 | | ICH Q9 | Quality Risk Management | Inspection-precipitated risk records emitted to URS-19 | | ICH Q10 | §3.2.1 — CAPA system; §3.2.4 — Internal Audit (Inspection) | Module 22 internal-audit + supplier-audit lifecycles; commitment-to-CAPA linkage to URS-18 | | ICH E6(R3) | §5.20 — Sponsor inspection cooperation (GCP) | Sponsor-side inspection support for GCP module use; back-room retrieval evidence for regulatory-inspection cooperation | | ISO 19011 | Audit principles | Internal-audit conduct; auditor independence; audit evidence; audit follow-up | | India CDSCO Schedule M-III | §5 — Quality Management; §14 — Internal Audit / Inspection | Internal-audit cooperation expectations for India operations subject to a future jurisdiction-specific legal assessment for Verixa's exact CDSCO obligations | | India D&C Act 1940 / Drugs Rules 1945 | Predicate drug-control framework | India operations regulatory baseline subject to a future jurisdiction-specific legal assessment | | India NDCT 2019 | §X — Clinical-trial inspection cooperation | Inspection cooperation for Indian clinical-trial scope subject to a future jurisdiction-specific legal assessment | --- ## 15. Code Modules | Code module | Path | Status | |---|---|---| | `inspection` plugin | `packages/backend/src/modules/inspection/plugin.ts` | (canonical mount `/api/v1/inspections`) | | `inspection` routes | `packages/backend/src/modules/inspection/routes.ts` | (typed schemas; route additions per §6.3) | | `inspection` service | `packages/backend/src/modules/inspection/service.ts` | (versioned readiness formula; AI-provenance enforcement; HITL + e-sign integration; reopen append-only logic; commitment-CAPA event emission) | | `inspection` schemas | `packages/backend/src/modules/inspection/schemas.ts` | target route | | `inspection` events | `packages/backend/src/modules/inspection/events.ts` | target route | | Migration 041 | `packages/backend/src/db/migrations/041_inspection_enhancement.sql` | (042+ migrations add `site_id`, AI-provenance, document-version provenance, bound e-sign, reopen, formula_version) | | Shared types | `packages/shared/src/types/inspection.ts` | | | Frontend hooks | `packages/frontend/src/api/hooks/useInspection.ts` | (canonical `/inspections/*` paths) | | Frontend dashboard | `packages/frontend/src/pages/inspection/InspectionDashboard.tsx` | | | Frontend calendar detail | `packages/frontend/src/pages/inspection/InspectionCalendarDetail.tsx` | (frontend contract aligned with versioned readiness scorecard) | | Frontend self-inspection form | `packages/frontend/src/pages/inspection/SelfInspectionForm.tsx` | target route | | Frontend checklist editor | `packages/frontend/src/pages/inspection/ChecklistEditor.tsx` | target route | | Frontend SME bank editor | `packages/frontend/src/pages/inspection/SmeBankEditor.tsx` | target route | | Frontend mock-drill execution | `packages/frontend/src/pages/inspection/MockDrillExecution.tsx` | target route | | Frontend back-room console | `packages/frontend/src/pages/inspection/BackRoomConsole.tsx` | target route | | Frontend deficiency response form | `packages/frontend/src/pages/inspection/DeficiencyResponseForm.tsx` | target route | | Frontend commitment tracker | `packages/frontend/src/pages/inspection/CommitmentTracker.tsx` | target route | | Frontend lessons-learned editor | `packages/frontend/src/pages/inspection/LessonsLearnedEditor.tsx` | target route | | Frontend inspection-readiness export | `packages/frontend/src/pages/inspection/InspectionReadinessExport.tsx` | target route | | Frontend MIRA copilot integration | `packages/frontend/src/pages/inspection/InspectionMiraPanel.tsx` | target route | --- ## 16. Test Cases ### 16.1 Unit tests - TC-22-U-001: calendar create with `(tenant_id, site_id, inspection_type, planned_date)` uniqueness rejects duplicate. - TC-22-U-002: calendar create with missing `site_id` rejects with `INS_VALIDATION_FAILED`. - TC-22-U-003: self-inspection completion without structured findings summary rejects with `INS_MISSING_REQUIRED_FIELD`. - TC-22-U-004: controlled-checklist effective version edit-in-place rejects with `INS_INVALID_TRANSITION`. - TC-22-U-005: SME question-bank effective version edit-in-place rejects. - TC-22-U-006: mock-drill AI-assisted question persisted without provenance fields rejects with `INS_AI_PROVENANCE_INCOMPLETE`. - TC-22-U-007: readiness-scorecard generation persists `formula_version`, `component_inputs`, `component_scores`, `fallback_flags`, `generated_by_rule`. - TC-22-U-008: back-room retrieval persisted without `document_version_id` + `document_hash` rejects with `INS_DOCUMENT_VERSION_REQUIRED`. - TC-22-U-009: deficiency-response submission without `deficiency_review_authority` rejects with `INS_AUTHORITY_REQUIRED`. - TC-22-U-010: response-item verification by performer rejects with SoD violation. - TC-22-U-011: commitment-CAPA linkage emits `commitment_capa_linked` event with `audit_observation` source type for URS-18. - TC-22-U-012: lesson publication without `lesson_publication_authority` rejects. - TC-22-U-013: calendar archive without bound e-signature rejects with `INS_E_SIGNATURE_REQUIRED`. - TC-22-U-014: calendar reopen without executive authority co-sign rejects with `INS_REOPEN_AUTHORITY_REQUIRED`. - TC-22-U-015: calendar reopen appends new iteration row; prior archived evidence not mutated. - TC-22-U-016: self-inspection reopen without `final_quality_approver` co-sign rejects. - TC-22-U-017: inspection-observation-finding emission to URS-21 with `inspection_observation` source type. - TC-22-U-018: critical deficiency closure without linked commitment+CAPA rejects (DEC-22-21). - TC-22-U-019: reason-for-change required on material update after draft per DEC-22-17. - TC-22-U-020: context-filter query against non-existent column rejects with `INS_CONTEXT_FILTER_MISMATCH`. ### 16.2 Integration tests - TC-22-I-001: full FDA-routine inspection lifecycle from calendar create to archive with all gates. - TC-22-I-002: full EU-GMP inspection lifecycle on same site different date (calendar uniqueness validation). - TC-22-I-003: controlled-checklist release lifecycle with HITL + e-signature. - TC-22-I-004: SME-bank release + training session + mock-drill against effective bank. - TC-22-I-005: AI-assisted mock-drill question generation with full provenance + human acceptance. - TC-22-I-006: readiness-scorecard generation with cross-module reads from URS-14, URS-15, URS-16, URS-17, URS-18, URS-19, URS-28, URS-31; frontend contract alignment. - TC-22-I-007: back-room retrieval direct lookup with document-version + hash provenance. - TC-22-I-008: back-room retrieval AI-assisted with provenance fields + human acceptance + rejection paths. - TC-22-I-009: back-room request unable_to_locate path with reason capture. - TC-22-I-010: deficiency-response lifecycle with HITL + e-signature on submission, acceptance, closure. - TC-22-I-011: response-item verification with SoD-distinct verifier. - TC-22-I-012: commitment-CAPA linkage event emission to URS-18; CAPA closure check on commitment closure. - TC-22-I-013: lessons-learned publication with HITL + e-signature. - TC-22-I-014: calendar archive with reason + bound e-signature. - TC-22-I-015: governed reopen `archived → in_progress` appending new iteration; prior archived evidence not mutated. - TC-22-I-016: governed reopen `completed → in_progress` for self-inspection; prior completed evidence not mutated. - TC-22-I-017: inspection-readiness export consumption from every URS-01.URS-21 / URS-23.URS-35 module; export-hash persistence. - TC-22-I-018: MIRA copilot read-only context on inspection records; `mira_assisted_draft` not promoted to system-of-record without human confirmation + e-signature. - TC-22-I-019: standalone-finding creation in URS-21 from FDA Form 483 inspection observation. - TC-22-I-020: cross-tenant `platform_admin` break-glass logged with reason; reviewed in platform support audit. ### 16.3 End-to-end tests - TC-22-E-001: full FDA inspection scenario per Worked Example 1. - TC-22-E-002: full EU GMP inspection scenario per Worked Example 2 with concurrent FDA inspection. - TC-22-E-003: governed reopen scenario per Worked Example 3 — append-only behavior verified. - TC-22-E-004: AI-assisted retrieval rejection scenario per Worked Example 4 — fallback to direct lookup. - TC-22-E-005: CDSCO inspection scenario with India-specific predicate-rule citations. - TC-22-E-006: Internal audit scenario with supplier-audit observation feeding URS-21 standalone finding and URS-18 CAPA. - TC-22-E-007: Inspection-readiness export under typical tenant load — NFR-22-04 latency budget verification. - TC-22-E-008: Concurrent-user inspection scenario — 200 concurrent users per tenant — NFR-22-07 verification. ### 16.4 Performance tests - TC-22-P-001: list endpoint p95 latency under typical load (NFR-22-02). - TC-22-P-002: readiness-scorecard generation p95 latency (NFR-22-03). - TC-22-P-003: inspection-readiness export p95 latency (NFR-22-04). - TC-22-P-004: audit-trail append p99 latency (NFR-22-05). - TC-22-P-005: AI-assisted retrieval p95 latency (NFR-22-06). ### 16.5 Security tests - TC-22-S-001: cross-tenant access attempt rejected by RLS. - TC-22-S-002: missing RBAC permission rejected by `requirePermission(.)`. - TC-22-S-003: missing Authority Profile rejected on regulated final action. - TC-22-S-004: missing HITL decision rejected on regulated final action. - TC-22-S-005: missing bound e-signature rejected on regulated final action. - TC-22-S-006: SQL injection attempt against typed-schema route rejected with `INS_VALIDATION_FAILED`. - TC-22-S-007: PII / PHI redaction in logs verified. - TC-22-S-008: audit-trail UPDATE / DELETE attempt rejected at DB level. - TC-22-S-009: AI-assisted content promotion to system-of-record without human confirmation rejected. - TC-22-S-010: document-hash tampering attempt detected at retrieval time. --- ## 17. Validation Evidence ### 17.1 URS-22-VAL-001: requirements traceability matrix A complete RTM mapping every URS-22 requirement (DEC-22-01.DEC-22-23, BR-22-01.BR-22-24, NFR-22-01.NFR-22-09, SoD-22-01.SoD-22-07, SEC-22-01.SEC-22-12) to test cases (TC-22-U-001.TC-22-U-020, TC-22-I-001.TC-22-I-020, TC-22-E-001.TC-22-E-008, TC-22-P-001.TC-22-P-005, TC-22-S-001.TC-22-S-010) and code modules (§15). ### 17.2 URS-22-VAL-002: design qualification (DQ) DQ documentation covering Module 22 architecture, data model, API contract, workflow, business rules, audit trail, security, and integration points; signed by Validation Head, QA Head, RA Head. ### 17.3 URS-22-VAL-003: installation qualification (IQ) IQ documentation covering staging-environment migration application (041 + 042+), RLS verification on every Module 22 table, route mount verification at `/api/v1/inspections/*`, frontend hook resolution verification. ### 17.4 URS-22-VAL-004: operational qualification (OQ) OQ documentation covering happy-path execution of every URS-22 test case (TC-22-U-001.TC-22-S-010), with evidence captures (request/response payloads, audit-trail entries, e-signature binding evidence). ### 17.5 URS-22-VAL-005: performance qualification (PQ) PQ documentation covering NFR-22-01.NFR-22-09 verification under typical and peak tenant load. ### 17.6 URS-22-VAL-006: AI/ML governance evidence AI/ML governance evidence per ARCH-AI-001 covering: (a) MIRA copilot read-only context integration; (b) AI-assisted mock-drill question provenance; (c) AI-assisted back-room retrieval provenance; (d) `mira_assisted_draft` advisory-labeling and human-confirmation pathway; (e) AI-quality monitoring metrics (acceptance rate, rejection rate, confidence distribution, drift detection); (f) Annex 22 §7 / EU AI Act Art. 13 / Annex III internal forward-looking control compliance evidence. ### 17.7 URS-22-VAL-007: regulatory mapping evidence Regulatory-mapping evidence covering FDA 21 CFR Part 11 + 211, EU GMP Annex 11, EU GMP Annex 22 Draft 2025 §7, EU AI Act Art. 13 / Annex III, MHRA Data Integrity (ALCOA+), GAMP 5 Cat 5, ICH Q9, ICH Q10 §3.2.1 / §3.2.4, ICH E6(R3) §5.20, ISO 19011, India CDSCO Schedule M-III §5 / §14 with binding section citations. ### 17.8 URS-22-VAL-008: migration evidence gate Migration evidence gate per §9.3. ### 17.9 URS-22-VAL-009: signature manifest Signature manifest of QA Head, RA Head, Validation Head, Manufacturing Head, Clinical / PV Head, Information Security Head, Site Quality Lead, Founder / Chairman & MD per §19. ### 17.10 URS-22-VAL-010: post-launch periodic-review pack Post-launch periodic-review pack covering: (a) inspection-record metrics (calendars per tenant, deficiency responses per tenant, commitments per tenant); (b) AI-quality metrics (acceptance / rejection rate, drift detection); (c) audit-trail integrity verification; (d) reopen-event audit; (e) cross-tenant break-glass audit; (f) inspection-readiness export usage; (g) regulator-feedback log (FDA / EMA / MHRA / CDSCO follow-up actions); periodic review at quarterly cadence by QA Head + RA Head + Validation Head. --- ## 18. Document Change History | Version | Date | Author | Change Summary | |---|---|---|---| | 1.0 | 2026-05-07 | Founder Doctrine — Verixa URS Cell | First issued user requirements specification for Module 22. | --- ## 19. Document Approval This document becomes "Approved Controlled URS — released for engineering implementation and validation planning" upon signature capture of every approving authority below. It becomes "Released for validation execution" only after URS-22-VAL-008 migration evidence gate and §17 validation evidence pack are satisfied. | Role | Name | Signature | Date | |---|---|---|---| | Founder / Chairman & MD | Vimal | __________ | __________ | | QA Head | __________ | __________ | __________ | | RA Head | __________ | __________ | __________ | | Validation Head | __________ | __________ | __________ | | Manufacturing Head | __________ | __________ | __________ | | Clinical / PV Head | __________ | __________ | __________ | | Information Security Head | __________ | __________ | __________ | | Site Quality Lead | __________ | __________ | __________ | --- ## 20. Cross-Module Event Contract | Event | Emitter | Consumer | Payload key fields | |---|---|---|---| | `inspection_calendar_created` | Module 22 | URS-30 (notifications) | `calendar_id`, `tenant_id`, `site_id`, `inspection_type`, `planned_date`, `created_by` | | `inspection_calendar_status_changed` | Module 22 | URS-30 | `calendar_id`, `from_status`, `to_status`, `changed_by`, `reason_for_change` | | `self_inspection_completed` | Module 22 | URS-30, URS-19 (risk-assessment-precipitated) | `self_inspection_id`, `score`, `findings_count`, `completed_by`, `e_signature_id` | | `mock_drill_completed` | Module 22 | URS-30 | `mock_drill_id`, `score`, `outcome_summary`, `completed_by` | | `readiness_scorecard_generated` | Module 22 | URS-30, URS-13 (formula version traceability) | `scorecard_id`, `calendar_id`, `formula_version`, `overall_score`, `component_scores`, `generated_by` | | `back_room_request_completed` | Module 22 | URS-30 | `request_id`, `document_version_id`, `document_hash`, `retrieval_outcome`, `retrieved_by` | | `deficiency_response_submitted` | Module 22 | URS-30 | `deficiency_response_id`, `severity`, `regulatory_body`, `submitted_by`, `e_signature_id` | | `deficiency_response_accepted` | Module 22 | URS-30 | `deficiency_response_id`, `accepted_by`, `e_signature_id` | | `deficiency_response_closed` | Module 22 | URS-30 | `deficiency_response_id`, `closed_by`, `e_signature_id` | | `commitment_capa_linked` | Module 22 | **URS-18 (CAPA — primary consumer)**, URS-30 | `commitment_id`, `capa_id`, `linked_by`, `severity`, `source_type = audit_observation` | | `inspection_observation_finding_created` | Module 22 | **URS-21 (Findings — primary consumer)**, URS-30 | `inspection_calendar_id`, `observation_id`, `severity`, `regulatory_body`, `finding_id` (URS-21) | | `lesson_published` | Module 22 | URS-30 | `lesson_id`, `published_by`, `e_signature_id` | | `inspection_response_submitted` | Module 22 | URS-30 | `deficiency_response_id`, `submitted_by` | | `inspection_closed` | Module 22 | URS-30, URS-26 (APQR consumer) | `calendar_id`, `closed_by`, `e_signature_id` | | `inspection_reopened` | Module 22 | URS-30, URS-21 (governed-reopen audit), URS-18 | `calendar_id`, `reopened_by`, `executive_co_signer`, `reopen_reason` | --- ## 21. References - ARCH-AI-001 — AI Optionality and Manual Continuity (binding architecture) - VRX-SPEC-URS-022-Inspection-Management-and-Readiness.md (Module specification) - URS-01.URS-21, URS-23.URS-35 (cross-module contracts) - FDA 21 CFR Part 11 - FDA 21 CFR Part 211 (cGMP) - FDA Form 483 / EIR (FDA Investigations Operations Manual §5) - EU GMP Annex 11 (Computerised Systems) - EU GMP Annex 22 (Draft 2025) §7 — internal forward-looking control - EU AI Act (Regulation 2024/1689) Art. 13 / Annex III — internal forward-looking control - MHRA Data Integrity Guidance (2018) — ALCOA+ - GAMP 5 Cat 5 — Custom-application validation lifecycle - ICH Q9 (Quality Risk Management) - ICH Q10 §3.2.1 (CAPA), §3.2.4 (Internal Audit) - ICH E6(R3) §5.20 (Sponsor inspection cooperation) - ISO 19011 (audit principles) - India CDSCO Schedule M-III §5 / §14 - India D&C Act 1940 / Drugs Rules 1945 - India NDCT 2019 --- **END OF VRX-URS-22 — INSPECTION MANAGEMENT & READINESS — VERSION 1.0**