# Verixa — User Requirements Specification

# Module 32: MIRA AI Chat Command Center and Agent Orchestration

| Field | Value |
|---|---|
| Document ID | VRX-URS-32 |
| Version | 1.0 |
| Status | Final — ready for QA, Validation, Regulatory Affairs, **Information Security Head (Co-Primary Owner — AI Gateway / model qualification)**, **Chief AI Officer / AI-ML Lead (Co-Primary Owner — model governance)**, Manufacturing Head, Site Quality Lead, Qualified Person Authority, Legal Authority (AI Act / data minimization), 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-32-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 `mira` + `ai-gateway` + `panel`, expected API mounts `/api/v1/mira/*` (MIRA conversational/agent surface) + `/api/v1/ai/*` (AI Gateway chokepoint with `/api/v1/ai/health` per DEC-32-13), expected supporting modules `audit-log`, `auth/rbac`, `electronic_signatures`, `hitl`, `documents` (URS-12), expected event-bus emission for `mira_conversation_created`, `mira_message_persisted`, `mira_action_classified`, `mira_handover_task_created`, `mira_handover_task_completed`, `mira_handover_task_rejected`, `mira_handover_task_cancelled`, `mira_handover_task_manual_continuation`, `mira_outcome_label_assigned`, `mira_bypass_ai_invoked`, `mira_ai_unavailable`, `mira_policy_rejected`, `mira_rate_limited`, `mira_model_unqualified`, `ai_governance_event_emitted`, `mira_event_dlq_persisted`, `mira_program_locked`, `mira_program_reopened`, expected outbound consumer integration with **every other URS module that MIRA influences** (MIRA influences are advisory only per DEC-32-01 and emit `outcome_label` per DEC-32-07 to: URS-13, URS-14, URS-15, URS-16, URS-17, URS-18, URS-19, URS-20, URS-21, URS-22, URS-23, URS-24, URS-25, URS-26, URS-27, URS-28, URS-29, URS-31), expected URS-12 Document Control linkage for prompt-template + policy-version controlled storage, expected URS-13 Change Control linkage for model-qualification effective release + prompt-template effective release + policy-version effective release per DEC-32-09 / DEC-32-10, expected URS-21 findings emission for AI governance event clustering + DLQ stale messages, expected URS-18 CAPA emission for chronic AI governance failures, expected URS-28 training qualification-gate consumption for human-on-loop reviewer authority, expected URS-30 Notifications outbound consumer for AI availability state changes + DLQ alerts, expected Authority Profile + HITL + e-signature integration for non-bypassable handover task acceptance / rejection (where `state_change_request` / `signature_controlled` / `external_transmission` action classes apply) / model qualification / prompt-template release / program lock / reopen, expected platform_admin / super_admin support / break-glass only paths. 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** — the **canonical binding module** (MIRA is the platform's primary AI surface; ARCH-AI-001 was authored largely in response to MIRA design questions). The full ARCH-AI-001 acceptance criteria set AC-1.AC-7 binds MIRA: AC-1 (primary action operable without AI — DEC-32-15 `bypass_ai`), AC-2 (AI availability surfaced to user — DEC-32-13 persistent banner + `/api/v1/ai/health` + `/api/v1/mira/availability`), AC-3 (policy-rejection path explicit — DEC-32-04 `ai_governance_events` policy_reject + DEC-32-08 HITL bind), AC-4 (manual continuation persisted — DEC-32-15 `bypass_ai: boolean` + `bypass_reason: string` + DEC-32-07 `ai_unavailable_manual` outcome label), AC-5 (no silent swallow of AI errors — DEC-32-04 `ai_governance_events` for every error class + DEC-32-12 `mira_event_dlq`), AC-6 (AI output never directly binds GxP field — DEC-32-08 normative UI gate + DEC-32-11 `hitl_decision_id` linkage mandatory for state_change_request+), AC-7 (outcome provenance label — DEC-32-07 `outcome_label` enum mandatory on every downstream artifact MIRA influences). Verixa adopts the **EU AI Act (Regulation 2024/1689) Annex III + Articles 9–15** control concepts as internal forward-looking AI governance for MIRA per DEC-32-01 / DEC-32-04 through DEC-32-15. Internal adoption covers: risk management (Art. 9 — risk register §11), data and data governance (Art. 10 — context scope + data-categories-accessed per DEC-32-05), technical documentation (Art. 11 — model qualification per DEC-32-09), record-keeping / logging (Art. 12 — `ai_governance_events` per DEC-32-04 + per-message persistence per DEC-32-14), **transparency obligation to user (Art. 13 — DEC-32-13 + DEC-32-07)**, **human oversight (Art. 14 — DEC-32-08 + DEC-32-15)**, accuracy / robustness / cybersecurity (Art. 15). Jurisdiction-specific legal enforceability remains subject to a future jurisdiction-specific legal assessment. **MIRA is suggestion-only and non-authoritative under ARCH-AI-001 binding** (Module specification explicit position): MIRA orchestrates controlled, classified actions against authoritative modules through the AI Gateway chokepoint; MIRA produces recommendations and drafts, never authoritative state changes; every state change of regulatory consequence transits HITL + bound e-signature + downstream authoritative module per DEC-32-08. 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 AI in MIRA is permitted only as advisory drafts with mandatory human acceptance via HITL handover tasks; generative / probabilistic AI is **PROHIBITED from being the sole path to finalize any GxP state change, sign any regulated record, or transmit externally**. **GMLP (Good Machine Learning Practices — 10 principles, FDA/MHRA/Health Canada joint guidance)** is adopted as an internal model-qualification control for MIRA per DEC-32-09 / DEC-32-10. Jurisdiction-specific legal enforceability of Annex 22 and the EU AI Act remains subject to a future jurisdiction-specific legal assessment. This module binds ARCH-AI-001 AC-1, AC-2, AC-3, AC-4, AC-5, AC-6, and AC-7 (all seven). |
| Regulatory Classification | Critical infrastructure substrate — operates the canonical MIRA AI Chat Command Center and Agent Orchestration system covering: (a) the **MIRA suggestion-only non-authoritative position** (canonical binding) per DEC-32-01 — MIRA produces recommendations and drafts, never authoritative state changes; the platform's primary AI surface bound by ARCH-AI-001 across AC-1.AC-7; (b) the **Controlled Action Taxonomy** per DEC-32-02 — `mira_action_registry` with `action_class` ENUM `{read_only, recommendation, draft_creation, state_change_request, signature_controlled, external_transmission}` (closes controlled-action block 002); (c) the **Handover Task Lifecycle** per DEC-32-06 — `mira_handover_tasks` with states `{pending_classification, pending_handover, pending_execution, completed, rejected, cancelled, manual_continuation}` linked to downstream `hitl_decision_id` per DEC-32-11 — the sole path by which MIRA influences authoritative state (closes controlled-action block 006); (d) the **Outcome Label Vocabulary** per DEC-32-07 — `outcome_label` ENUM `{ai_assisted_accepted, ai_assisted_rejected, ai_assisted_overridden, ai_unavailable_manual, manual_only}` mandatory on every downstream artifact MIRA influenced; immutable after write; the regulator-facing answer to "did AI influence this decision, and if so, was the human the decider?" (closes controlled-action block 007 + closes ARCH-AI-001 AC-7 v1.0 binding); (e) the **AI Gateway chokepoint** (`/api/v1/ai/*`) per DEC-32-04 with mandatory transit of every MIRA AI invocation; feature-flag / rate-limit / model-qualification / prompt-version evaluation; five outcome classes (`ok` / `policy_reject` / `rate_limited` / `model_unqualified` / `unavailable`) all NON-SILENT emitting `ai_governance_events` rows; (f) the **minimum-necessary context binding** per DEC-32-05 — MIRA binds to a `context_scope` enum and a `data_categories_accessed` annotation on every request — HIPAA §164.502(b) and GDPR Art. 5(1)(c) minimum-necessary and data-minimization obligations apply; (g) the **model qualification + prompt versioning + policy versioning** per DEC-32-09 / DEC-32-10 — model qualification per GMLP 10 principles + URS-13 CR linkage on effective release; prompt templates stored as URS-12 controlled documents with version control; policy versions controlled; (h) the **AI Gateway availability surface** per DEC-32-13 — `/api/v1/ai/health` + `/api/v1/mira/availability` + persistent banner UI surfacing AI availability state changes; AI availability never a precondition of revenue-generating authoritative flow per Doctrine Mandate 13; (i) the **Manual Fallback for Agentic Workflows (`bypass_ai`)** per DEC-32-15 — `bypass_ai: boolean` + `bypass_reason: string` first-class on every agentic workflow surface (closes controlled-action block 015 + ARCH-AI-001 AC-1 binding); (j) the **HITL-bound MIRA UI gate per ARCH-AI-001 AC-6** — AI output never directly binds a GxP field; `state_change_request` / `signature_controlled` / `external_transmission` action classes mandate `hitl_decision_id` linkage per DEC-32-08 / DEC-32-11; (k) the **AI governance event substrate** (`ai_governance_events`) per DEC-32-04 — every gateway outcome emits a row; the platform-wide AI activity ledger; (l) the **MIRA event dead-letter queue** (`mira_event_dlq`) per DEC-32-12 — no silent swallow of AI errors per ARCH-AI-001 AC-5 binding; (m) the multi-dimensional context capture (`tenant_id` mandatory, `user_id` for conversation attribution, `conversation_id`, `message_id`, `context_scope` ENUM, `data_categories_accessed` TEXT[], `action_class` ENUM); (n) the canonical API contract `/api/v1/mira/*` + `/api/v1/ai/*` (per DEC-32-01); (o) the typed schema validation across every route; (p) the controlled frontend route surface; (q) the audit-trail coverage with reason-for-change discipline + per-message persistence per DEC-32-14; (r) the Authority/HITL/e-signature substrate on every handover task acceptance for `state_change_request` / `signature_controlled` / `external_transmission` action classes per DEC-32-08; (s) the post-locked record immutability across the MIRA program; (t) the controlled reopen workflow with executive authority co-sign and Qualified Person co-sign per DEC-32-22; (u) the canonical findings-source emission to URS-21 per DEC-32-15; (v) the canonical CAPA-source emission to URS-18 for chronic AI governance failures per DEC-32-16; (w) the **outbound provenance integration with every other URS module that MIRA influences** per DEC-32-23 — every downstream artifact MIRA touches receives `outcome_label`; and the per-jurisdictional regulatory expectations under FDA 21 CFR Part 11 (§11.10(a) validation; §11.10(d) authority checks; §11.10(e) audit trails — every MIRA message persisted; §11.50 signature manifestations; §11.70 signature/record linking; §11.200 electronic signature controls); EU GMP Annex 11 (§4 validation; §5 data; §9 audit trails; §12 security; §14 electronic records / signatures; §16 incident management); EU GMP Annex 22 Draft 2025 §7 (HITL — internal forward-looking control); **EU AI Act (Regulation 2024/1689) Annex III + Articles 9, 10, 11, 12, 13, 14, 15** (adopted as internal forward-looking AI governance); MHRA Data Integrity Guidance (ALCOA+); GAMP 5 Cat 5; **FDA Computer Software Assurance (CSA) — September 2025 Final Guidance** (MIRA classified as not-high-process-risk for pure read-only / recommendation classes; high-process-risk for any state-change-influencing action — those subject to rigorous assurance); **GMLP (Good Machine Learning Practices — 10 principles, FDA/MHRA/Health Canada joint guidance)** for model qualification; **WHO TRS 996 Annex 5** (Computerised Systems); **HIPAA §164.502(b) (minimum necessary) + GDPR Article 5(1)(c) (data minimisation)** for context-scope binding per DEC-32-05; **ICH Q9 R1** (Quality Risk Management) for AI risk classification; **ICH E6(R3)** GCP adjunct where MIRA touches clinical artifacts; **ISO/IEC 27001** (information security for AI Gateway); and India CDSCO Schedule M (Revised) §16 + NDCT 2019 §27 subject to a future jurisdiction-specific legal assessment for Verixa's exact CDSCO obligations. |
| Date of Issue | 2026-05-07 |
| Module Owner (Engineering) | MIRA Platform Squad |
| Module Owner (Quality Validation) | CSV / CSA Lead — MIRA AI |
| Module Owner (Compliance) | **Information Security (Co-Primary Owner — AI Gateway / model qualification)**, **Chief AI Officer / AI-ML Lead (Co-Primary Owner — model governance)**, Quality Assurance, Regulatory Affairs, Legal Authority (AI Act / data minimization) |
| Approving Authority | Founder / Chairman & MD; QA Head; **Information Security Head (Co-Primary Owner)**; **Chief AI Officer / AI-ML Lead (Co-Primary Owner)**; Manufacturing Head; Validation Head; RA Head; Legal Authority; Qualified Person (QP) Authority; Site Quality Lead |

---

## 0. Document Framing

### 0.1 Purpose of this document

This URS defines the target expected state for Verixa's MIRA AI Chat Command Center and Agent Orchestration module (Module 32) — **the platform's primary AI surface and the canonical binding module for ARCH-AI-001**. It is the binding contract between product, engineering, quality validation, regulatory affairs, **information security (co-primary owner — AI Gateway / model qualification)**, **Chief AI Officer / AI-ML Lead (co-primary owner — model governance)**, manufacturing, the Qualified Person authority, distribution, laboratory operations, legal authority (AI Act / data minimization), and the executive authority for the design, implementation, validation, release, and on-going periodic review of the regulated MIRA substrate: the **MIRA suggestion-only non-authoritative position** (canonical binding) per DEC-32-01; the **Controlled Action Taxonomy** per DEC-32-02 (closes controlled-action block 002); the AI Gateway chokepoint per DEC-32-04 with five non-silent outcome classes; the minimum-necessary context binding per DEC-32-05; the **Handover Task Lifecycle** per DEC-32-06 (closes controlled-action block 006); the **Outcome Label Vocabulary** per DEC-32-07 (closes controlled-action block 007 + closes ARCH-AI-001 AC-7 v1.0 binding); the HITL-bound MIRA UI gate per DEC-32-08; the model qualification + prompt versioning + policy versioning per DEC-32-09 / DEC-32-10; the HITL decision-record linkage per DEC-32-11; the MIRA event dead-letter queue per DEC-32-12; the AI Gateway availability surface per DEC-32-13; the per-message persistence with full audit per DEC-32-14; the **Manual Fallback for Agentic Workflows (`bypass_ai`)** per DEC-32-15 (closes controlled-action block 015); the multi-dimensional context capture; the canonical API contract `/api/v1/mira/*` + `/api/v1/ai/*`; the typed schema validation; the controlled frontend route surface; the audit-trail coverage with reason-for-change discipline; the Authority/HITL/e-signature substrate per DEC-32-08; the post-locked record immutability; the controlled reopen workflow per DEC-32-22; the canonical findings emission to URS-21 per DEC-32-15; the canonical CAPA emission to URS-18 per DEC-32-16; the **outbound provenance integration with every other URS module that MIRA influences** per DEC-32-23 — every downstream artifact MIRA touches receives `outcome_label`; the audit trail coverage with reason-for-change discipline; and the per-jurisdictional regulatory expectations including the **EU AI Act Annex III internal forward-looking AI governance set** (Articles 9, 10, 11, 12, 13, 14, 15) per internal forward-looking governance + GMLP 10 principles + HIPAA §164.502(b) + GDPR Art. 5(1)(c) for context-scope binding. Compliance with this URS is mandatory.

### 0.2 Audience

Engineering, QA, RA, Manufacturing, Qualified Person Authority, Distribution, Laboratory Operations, Validation, **Information Security** (co-primary owner — AI Gateway / model qualification / IMAP-equivalent credential governance for AI provider authentication), **Chief AI Officer / AI-ML Lead** (co-primary owner — model governance / prompt governance / policy governance), Legal Authority (AI Act / data minimization / HIPAA / GDPR), 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, WHO). The plain-language primer (§0.4) and worked examples (§3.5) make Module 32 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 MIRA mutation
- **URS-02** RBAC & Permissions — the dedicated `mira:*` and `ai_gateway:*` permission set: `mira:conversation:*`, `mira:message:*`, `mira:action_registry:*`, `mira:handover_task:*`, `mira:outcome_label:*`, `mira:bypass_ai:*`, `ai_gateway:invoke`, `ai_gateway:health:read`, `ai_gateway:model_qualification:*`, `ai_gateway:prompt_template:*`, `ai_gateway:policy_version:*`, `ai_gateway:dlq:read`
- **URS-03** Context Gate & Approval Scope — context-gate enforcement; minimum-necessary `context_scope` binding per DEC-32-05
- **URS-04** Workflow / HITL / E-Signature / Approval Authority — Controlled Approval Modal contract for handover task acceptance / rejection (where state_change_request / signature_controlled / external_transmission action classes apply); model qualification effective release; prompt-template effective release; policy-version effective release; program lock / reopen
- **URS-05** Authority Profile / Delegation / SoD — Authority Profiles consumed (`mira_handover_acceptance_authority`, `model_qualification_release_authority`, `prompt_template_release_authority`, `policy_version_release_authority`, `qualified_person_authority`, `final_quality_approver`, `executive_authority`, `information_security_authority`, `ai_ml_lead_authority`, `legal_ai_act_authority`)
- **URS-06** Audit Trail / Hash Chain / Tamper-Evident — append-only audit substrate; **per-message persistence with full audit** per DEC-32-14 / 21 CFR Part 11 §11.10(e); **`ai_governance_events` substrate**
- **URS-07** Study Management — optional study-scope dimension
- **URS-08** Tenant Management Lifecycle — tenant context for MIRA records
- **URS-09** Site / Facility Management — site-scope inherited via `studies` parent
- **URS-10** Product / SKU / Drug Master Data — optional product-scope dimension
- **URS-12** Document Control / SOP — **primary linkage**: prompt templates stored as URS-12 controlled documents with version control per DEC-32-09; policy versions stored as URS-12 controlled documents per DEC-32-10
- **URS-13** Change Control — model qualification effective release linkage; prompt-template effective release linkage; policy-version effective release linkage
- **URS-14** Complaints — **outbound provenance consumer per DEC-32-23**: complaints MIRA influences receive `outcome_label`
- **URS-15** OOS / OOT — outbound provenance consumer
- **URS-16** Deviations — outbound provenance consumer
- **URS-17** RCA — outbound provenance consumer
- **URS-18** CAPA — outbound provenance consumer + primary downstream consumer for chronic AI governance failure CAPA per DEC-32-16
- **URS-19** Risk Assessment — outbound provenance consumer
- **URS-20** Reviews — outbound provenance consumer
- **URS-21** Findings — outbound provenance consumer + primary downstream consumer for AI governance event clustering + DLQ stale messages per DEC-32-15
- **URS-22** Inspection Mgmt — outbound provenance consumer
- **URS-23** Batch Records — outbound provenance consumer
- **URS-24** Stability — outbound provenance consumer
- **URS-25** EM — outbound provenance consumer
- **URS-26** APQR — outbound provenance consumer
- **URS-27** Regulatory Intelligence — outbound provenance consumer
- **URS-28** Training — outbound provenance consumer + **inbound qualification-gate consumer** for human-on-loop reviewer authority per DEC-32-08
- **URS-29** Screen Reader / Data Capture — outbound provenance consumer
- **URS-30** Notifications — outbound provenance consumer + outbound consumer for AI availability state changes + DLQ alerts
- **URS-31** DQG — outbound provenance consumer
- **URS-33** GMP Manufacturing — outbound provenance consumer
- **URS-34** GDP Distribution — outbound provenance consumer
- **URS-35** Infrastructure / Backup-Restore — operational continuity; secret-store linkage for AI provider credentials

### 0.4 Plain-language primer

In a regulated pharmaceutical operation, **MIRA ("Modular Intelligent Regulatory Assistant")** is the platform's persistent conversational and agentic AI surface — the primary place users interact with AI inside Verixa. MIRA is **suggestion-only and non-authoritative** under the canonical ARCH-AI-001 binding: MIRA produces recommendations and drafts, never authoritative state changes. Every state change of regulatory consequence transits human-in-the-loop (HITL) decision capture, controlled e-signature (where 21 CFR Part 11 §11.50 / §11.70 / §11.200 apply), and a downstream authoritative module. Module 32 is in the highest regulatory scope under: **FDA 21 CFR Part 11 §§11.10(a)/(d)/(e), 11.50, 11.70, 11.200**; **EU GMP Annex 11 §§4, 5, 9, 12, 14, 16**; **EU AI Act (Regulation 2024/1689) Annex III + Articles 9–15** (adopted as internal forward-looking AI governance — risk management, data governance, technical documentation, record-keeping/logging, transparency to user, human oversight, accuracy/robustness/cybersecurity); **EU GMP Annex 22 Draft 2025 §7** (HITL — internal forward-looking control); **GMLP (Good Machine Learning Practices) 10 principles**; **MHRA Data Integrity (ALCOA+)**; **FDA CSA September 2025**; **GAMP 5 Cat 5**; **HIPAA §164.502(b) + GDPR Art. 5(1)(c)** (minimum necessary / data minimization); **WHO TRS 996 Annex 5**.

The most consequential design principle in MIRA is the **boundary between MIRA and authoritative modules** — enforced by three first-class mechanisms canonically identified in the Module specification as: (a) **Controlled Action Taxonomy (DEC-32-02)** — every action MIRA can initiate is pre-registered in `mira_action_registry` with an `action_class` from `{read_only, recommendation, draft_creation, state_change_request, signature_controlled, external_transmission}`; the three escalated classes (`state_change_request`, `signature_controlled`, `external_transmission`) MUST transit HITL and (for the latter two) bound e-signature; (b) **Handover Task Lifecycle (DEC-32-06)** — every action crossing the MIRA boundary materializes a row in `mira_handover_tasks` with states `{pending_classification, pending_handover, pending_execution, completed, rejected, cancelled, manual_continuation}` linked to downstream `hitl_decision_id` per DEC-32-11 — the sole path by which MIRA influences authoritative state; (c) **Outcome Label Vocabulary (DEC-32-07)** — every downstream authoritative artifact that MIRA influenced carries an `outcome_label` from `{ai_assisted_accepted, ai_assisted_rejected, ai_assisted_overridden, ai_unavailable_manual, manual_only}`; immutable after write; the regulator-facing answer to "did AI influence this decision, and if so, was the human the decider?". The fourth most consequential design principle is the **AI Gateway chokepoint (DEC-32-04)** — every MIRA AI invocation MUST transit `/api/v1/ai/*`; the Gateway is the sole choke where feature flags / rate limits / model qualification / prompt-version binding are evaluated; all five outcome classes (`ok` / `policy_reject` / `rate_limited` / `model_unqualified` / `unavailable`) are NON-SILENT and emit `ai_governance_events` rows. The fifth most consequential design principle is the **Manual Fallback for Agentic Workflows (`bypass_ai`) (DEC-32-15)** — every agentic workflow surface has `bypass_ai: boolean` + `bypass_reason: string` first-class; **MIRA availability is never a precondition of revenue-generating authoritative flow** per Doctrine Mandate 13.

The **AI/ML governance posture for MIRA** is exhaustive and layered: MIRA's LLM substrate is federated through the AI Gateway and is subject to **model qualification (per GMLP 10 principles + DEC-32-09 / DEC-32-10 + URS-13 CR linkage)**; every prompt template is a URS-12 controlled document with version-immutable lifecycle per DEC-32-09; every policy version is a URS-12 controlled document per DEC-32-10; the HITL boundary enforcement at the UI gate per DEC-32-08 ensures **AI output never directly binds a GxP field**. MIRA emits `outcome_label` to every downstream artifact it influences across all 18 other regulated URS modules per DEC-32-23 — making MIRA's influence transparent to auditors regardless of which downstream module the artifact lives in.

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-32-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 |
|---|---|
| MIRA | "Modular Intelligent Regulatory Assistant" — the platform's primary AI chat command center and agent orchestration surface; suggestion-only and non-authoritative under canonical ARCH-AI-001 binding. |
| AI Gateway | The chokepoint at `/api/v1/ai/*` through which every MIRA AI invocation MUST transit per DEC-32-04; sole evaluation point for feature flags, rate limits, model qualification, prompt versioning, policy versioning. |
| Action class | An ENUM value from the Controlled Action Taxonomy (`mira_action_registry.action_class`) per DEC-32-02: `{read_only, recommendation, draft_creation, state_change_request, signature_controlled, external_transmission}`. The three escalated classes mandate HITL + (for latter two) bound e-signature. |
| Handover task | A row in `mira_handover_tasks` materializing every action crossing the MIRA boundary; lifecycle `{pending_classification, pending_handover, pending_execution, completed, rejected, cancelled, manual_continuation}` linked to downstream `hitl_decision_id` per DEC-32-06 / DEC-32-11. |
| Outcome label | An ENUM value from the Outcome Label Vocabulary (`outcome_label`) per DEC-32-07: `{ai_assisted_accepted, ai_assisted_rejected, ai_assisted_overridden, ai_unavailable_manual, manual_only}`. Mandatory on every downstream artifact MIRA influences. Immutable after write. |
| Context scope | An ENUM value bound to every MIRA request per DEC-32-05 (HIPAA §164.502(b) / GDPR Art. 5(1)(c) minimum-necessary binding); accompanied by `data_categories_accessed` annotation. |
| AI governance event | A row in `ai_governance_events` per DEC-32-04 emitted on every Gateway outcome (ok / policy_reject / rate_limited / model_unqualified / unavailable); platform-wide AI activity ledger. |
| MIRA event DLQ | The `mira_event_dlq` table per DEC-32-12 capturing AI errors that cannot be processed; closes ARCH-AI-001 AC-5 binding (no silent swallow of AI errors). |
| `bypass_ai` | First-class boolean field per DEC-32-15 (binds ARCH-AI-001 AC-1) on every agentic workflow surface allowing the user to bypass AI; accompanied by `bypass_reason: string`. |
| Model qualification | Controlled approval of an AI model for use in MIRA per GMLP 10 principles + DEC-32-09 / DEC-32-10 + URS-13 CR linkage. |
| Prompt template | A URS-12 controlled document defining a MIRA prompt with version-immutable lifecycle per DEC-32-09. |
| Policy version | A URS-12 controlled document defining a MIRA policy (e.g., content moderation, output filtering) per DEC-32-10. |
| Reopen | A governed transition event from `locked → in_progress` requiring `executive_authority` co-sign AND `qualified_person_authority` co-sign + documented reason; appends a new program iteration without mutating prior locked evidence per DEC-32-22. |
| ARCH-AI-001 | Platform architecture binding requiring manual continuity for every AI surface (AC-1.AC-7) — **canonically authored largely in response to MIRA design questions; MIRA binds all seven AC gates**. |
| Annex 22 | EU GMP Annex 22 (Draft 2025) §7. Verixa treats EU GMP Annex 22 Draft 2025 and EU AI Act high-risk / transparency concepts as internal forward-looking AI governance controls unless a jurisdiction-specific legal assessment determines otherwise. Binding predicate-rule obligations remain those listed in §14. AI may draft advisory with mandatory human acceptance via HITL handover tasks; AI is prohibited from being the sole path to finalize any GxP state change. Binding predicate-rule obligations remain those listed in §14. |
| GMLP | Good Machine Learning Practices — 10 principles (FDA / MHRA / Health Canada joint guidance for model qualification). Verixa adopts the GMLP 10 principles as an internal model-qualification control for MIRA per DEC-32-09 / DEC-32-10. Jurisdiction-specific legal enforceability remains subject to a future jurisdiction-specific legal assessment. |

### 0.7 Module-32 architectural picture

```mermaid
flowchart TD
 USR[User] --> UI[/MIRA UI — confidence pill + bypass_ai control + AI availability banner/]
 UI --> CONV[/MIRA Conversations — persistent multi-session/]
 CONV --> MSG[/MIRA Messages — per-message audit per DEC-32-14/]
 MSG --> CTX[Context Scope binding per DEC-32-05]
 CTX --> CLS[Action Intent Classification per DEC-32-02]
 CLS --> AGW[/AI Gateway Chokepoint — /api/v1/ai/* — DEC-32-04/]
 AGW --> FF{Feature Flag}
 AGW --> RL{Rate Limiter}
 AGW --> MQ{Model Qualification per DEC-32-09}
 AGW --> PV{Prompt Version per DEC-32-09}
 AGW --> PL{Policy Version per DEC-32-10}
 FF -. flag_off.-> AGE[/ai_governance_events/]
 RL -. rate_limited.-> AGE
 MQ -. model_unqualified.-> AGE
 AGW -- ok --> LLM[LLM Invocation via Secret Store]
 AGW -- policy_reject --> AGE
 AGW -- unavailable --> AGE
 LLM --> RESP[MIRA Response Composer]
 AGE -. critical errors.-> DLQ[/mira_event_dlq per DEC-32-12/]
 RESP --> CONF[Confidence Band Classification]
 CONF --> HCLASS{action_class}
 HCLASS -- read_only / recommendation --> RENDER[Render to UI]
 HCLASS -- draft_creation / state_change_request / signature_controlled / external_transmission --> HT[/MIRA Handover Tasks per DEC-32-06/]
 HT --> PEND[pending_handover]
 PEND --> HITL[HITL Decision Record per DEC-32-08 / DEC-32-11]
 HITL --> ACC[Accept]
 HITL --> REJ[Reject]
 HITL --> CANCEL[Cancel]
 HITL -. AI unavailable.-> MC[manual_continuation per DEC-32-15]
 ACC --> ESIG[Bound E-Sign for signature_controlled / external_transmission]
 ESIG --> DOWN[/Downstream Authoritative Module/]
 DOWN --> OL[/Outcome Label per DEC-32-07/]
 OL --> M14[URS-14 Complaints]
 OL --> M15[URS-15 OOS]
 OL --> M16[URS-16 Deviations]
 OL --> M17[URS-17 RCA]
 OL --> M18[URS-18 CAPA]
 OL --> M19[URS-19 Risk]
 OL --> M20[URS-20 Reviews]
 OL --> M21[URS-21 Findings]
 OL --> M22[URS-22 Inspection]
 OL --> M23[URS-23 Batch]
 OL --> M24[URS-24 Stability]
 OL --> M25[URS-25 EM]
 OL --> M26[URS-26 APQR]
 OL --> M27[URS-27 Regulatory]
 OL --> M28[URS-28 Training]
 OL --> M29[URS-29 Screen Reader]
 OL --> M30[URS-30 Notifications]
 OL --> M31[URS-31 DQG]
 HEALTH[/api/v1/ai/health + /api/v1/mira/availability per DEC-32-13/] --> UI
 BYPASS[bypass_ai per DEC-32-15] --> UI
 M28T[URS-28 Training Qualification Gate] --> HITL (human-on-loop reviewer authority verification)
 M12[URS-12 Document Control] --> PT[Prompt Templates per DEC-32-09]
 M12 --> PoV[Policy Versions per DEC-32-10]
 M13[URS-13 Change Control] --> MQ (model qualification CR linkage); --> PT (prompt CR linkage); --> PoV (policy CR linkage)
 M21F[URS-21 Findings] <-- AI governance event clustering / DLQ stale per DEC-32-15
 M18C[URS-18 CAPA] <-- chronic AI governance failure CAPA per DEC-32-16
 M30N[URS-30 Notifications] <-- AI availability state change / DLQ alerts
 LOCK[Program Lock] --> CONV
 LOCK -. governed reopen + executive + QP co-sign.-> CONV
```

The platform shall implement: **suggestion-only non-authoritative MIRA position** per DEC-32-01 (canonical binding); Controlled Action Taxonomy per DEC-32-02; AI Gateway chokepoint with five non-silent outcome classes per DEC-32-04; minimum-necessary context binding per DEC-32-05; Handover Task Lifecycle per DEC-32-06; Outcome Label Vocabulary per DEC-32-07; HITL-bound MIRA UI gate per DEC-32-08; model qualification per GMLP per DEC-32-09; prompt versioning + policy versioning per DEC-32-09 / DEC-32-10; HITL decision-record linkage per DEC-32-11; MIRA event DLQ per DEC-32-12 (closes AC-5); AI Gateway availability surface per DEC-32-13 (closes AC-2); per-message persistence per DEC-32-14; `bypass_ai` per DEC-32-15 (closes AC-1 + AC-4); canonical API contract; typed schema validation; controlled frontend route surface; audit-trail coverage; Authority/HITL/e-signature substrate; post-locked record immutability; governed reopen; canonical findings/CAPA emission; **outbound provenance integration with all 18 other regulated URS modules** per DEC-32-23; URS-28 qualification-gate inbound consumption for human-on-loop reviewer authority; and per-jurisdictional regulatory expectations including the EU AI Act Annex III internal forward-looking AI governance set + GMLP 10 principles + HIPAA / GDPR data minimization.

### 0.8 Locked Launch Controls

| Locked control | Authority | Rationale |
|---|---|---|
| Two-step release path: signature → engineering implementation → validation execution | DEC-32-01 / VAL-008 | Mirrors every other Module. |
| "No Module 32 internal decisions outstanding" | §11.6 | Captured in locked decisions DEC-32-01..DEC-32-23 (§3.2), including the four controlled-action blocks (Controlled Action Taxonomy, Handover Task Lifecycle, Outcome Label Vocabulary, Manual Fallback for Agentic Workflows). |
| `platform_admin` / `super_admin` support / break-glass only | DEC-32-20 / SoD-32-07 | Operating-tenant MIRA ownership is the regulated path. |
| Target implementation binding language | Module bindings | URS specifies expected implementation. |
| **MIRA suggestion-only non-authoritative position** with **canonical ARCH-AI-001 full AC-1.AC-7 binding** | Architecture Bindings / DEC-32-01 | Canonical binding; MIRA produces recommendations and drafts, never authoritative state changes; full ARCH-AI-001 acceptance criteria set binds MIRA. |
| **EU AI Act (Regulation 2024/1689) Annex III + Articles 9–15** adopted as internal forward-looking AI governance | Architecture Bindings | Internal adoption covers risk management, data governance, technical documentation, record-keeping, transparency, human oversight, accuracy; jurisdiction-specific legal enforceability remains subject to a future jurisdiction-specific legal assessment. |
| **GMLP (Good Machine Learning Practices) 10 principles** for model qualification | DEC-32-09 / DEC-32-10 | Adopted as internal model-qualification control. FDA / MHRA / Health Canada joint guidance referenced; jurisdiction-specific legal enforceability remains subject to a future jurisdiction-specific legal assessment. |
| Enumerated error codes | §6.7 | Stable machine-readable error contract. |
| JSON multi-signature evidence as **derived snapshot** | §6.6 | The `electronic_signatures` substrate is the system of record. |
| India CDSCO Schedule M §16 + NDCT 2019 §27 row | §14 | India CDSCO records and clinical trial documentation captured (subject to a future jurisdiction-specific legal assessment). |
| Version 1.0 posture | Header | First binding version. |
| Canonical API mounts `/api/v1/mira/*` + `/api/v1/ai/*` | DEC-32-01 | Frontend hooks + route comments aligned. |
| **Controlled Action Taxonomy** | DEC-32-02 | `mira_action_registry` with 6-value `action_class` ENUM; three escalated classes mandate HITL + bound e-sign. |
| AI Gateway chokepoint with five non-silent outcome classes | DEC-32-04 | Every MIRA AI invocation transits `/api/v1/ai/*`; `ai_governance_events` substrate. |
| Minimum-necessary context binding | DEC-32-05 | `context_scope` enum + `data_categories_accessed` per HIPAA §164.502(b) / GDPR Art. 5(1)(c). |
| **Handover Task Lifecycle** | DEC-32-06 | `mira_handover_tasks` with 7-state machine; sole path by which MIRA influences authoritative state. |
| **Outcome Label Vocabulary** (binds ARCH-AI-001 AC-7) | DEC-32-07 | `outcome_label` 5-value ENUM; mandatory + immutable on every MIRA-influenced downstream artifact. |
| HITL-bound MIRA UI gate per ARCH-AI-001 AC-6 | DEC-32-08 | AI output never directly binds GxP field; `hitl_decision_id` linkage mandatory. |
| Model qualification per GMLP + URS-13 CR linkage | DEC-32-09 | `mira_model_qualification_status` ENUM per GMLP 10 principles. |
| Prompt template versioning + policy version controlled lifecycle | DEC-32-09 / DEC-32-10 | Prompt templates + policy versions stored as URS-12 controlled documents. |
| HITL decision-record linkage | DEC-32-11 | `hitl_decision_id` linked from handover tasks. |
| **MIRA event DLQ** (closing ARCH-AI-001 AC-5 v1.0 PARTIAL) | DEC-32-12 | `mira_event_dlq` substrate; no silent swallow of AI errors. |
| **AI Gateway availability surface** (closing ARCH-AI-001 AC-2 binding) | DEC-32-13 | `/api/v1/ai/health` + `/api/v1/mira/availability` + persistent banner UI. |
| Per-message persistence with full audit | DEC-32-14 | Every MIRA message persisted in `mira_messages` + audit-trail. |
| **Manual Fallback for Agentic Workflows (`bypass_ai`)** (binds ARCH-AI-001 AC-1) | DEC-32-15 | `bypass_ai: boolean` + `bypass_reason: string` first-class. |
| URS-28 training qualification-gate consumer for human-on-loop reviewer authority (target requirement) | DEC-32-08 / DEC-32-23 | Human-on-loop reviewer must satisfy URS-28 qualification-gate. |
| Bound e-signature persistence on every regulated final action | DEC-32-08 / DEC-32-23 | All regulated finals carry bound e-signature. |
| Governed reopen pattern (`locked → in_progress`) | DEC-32-22 / SoD-32-06 | Append-only iteration; executive + QP co-sign; does NOT mutate prior locked evidence. |
| **Outbound provenance integration with all 18 other regulated URS modules** | DEC-32-23 | Every downstream artifact MIRA touches receives `outcome_label` per DEC-32-07. |

---

## 1. Scope and Out-of-Scope

### 1.1 In-scope

- The MIRA suggestion-only non-authoritative position.
- The Controlled Action Taxonomy.
- The AI Gateway chokepoint with five non-silent outcome classes.
- The minimum-necessary context binding.
- The Handover Task Lifecycle.
- The Outcome Label Vocabulary.
- The HITL-bound MIRA UI gate.
- The model qualification per GMLP.
- The prompt template + policy version controlled lifecycle.
- The HITL decision-record linkage.
- The MIRA event DLQ.
- The AI Gateway availability surface.
- The per-message persistence with full audit.
- The Manual Fallback for Agentic Workflows (`bypass_ai`).
- The Authority/HITL/e-signature substrate on every regulated final action.
- The audit-trail coverage with reason-for-change discipline.
- The findings emission to URS-21.
- The CAPA emission to URS-18.
- The URS-12 Document Control linkage for prompt templates + policy versions.
- The URS-13 Change Control linkage for model qualification + prompt + policy effective release.
- The URS-28 training qualification-gate inbound consumer for human-on-loop reviewer authority.
- The outbound provenance integration with all 18 other regulated URS modules.
- The governed reopen workflow.
- The per-jurisdictional regulatory expectations including the EU AI Act Annex III internal forward-looking AI governance set + GMLP + HIPAA / GDPR data minimization.

### 1.2 Out-of-scope

- The CAPA register itself (URS-18).
- The change-control register itself (URS-13).
- The findings register itself (URS-21).
- The document-control register itself (URS-12).
- The training qualification-gate substrate itself (URS-28).
- The notifications dispatcher itself (URS-30).
- The secret-store substrate itself (URS-35).
- The HITL substrate itself (URS-04).
- The authority substrate itself (URS-05).
- The e-signature substrate itself (URS-04).
- The LLM substrate itself (federated through AI Gateway from external providers Anthropic / Azure OpenAI per CLAUDE.md context).
- Authoritative scoring / approval / state changes — these belong to downstream regulated modules; MIRA is suggestion-only.
- Autonomous agent operation without HITL — MIRA agentic operations are orchestrated, classified, rate-limited, auditable, human-gated.

---

## 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), change-control (URS-13), training qualification-gate (URS-28), notifications (URS-30), all regulated downstream modules (URS-13.URS-31, URS-33.URS-35), and infrastructure secret-store (URS-35) are released and operational at validation time.
- MIRA platform owners, model qualification authority, prompt-template release authority, policy-version release authority, human-on-loop reviewers, Qualified Person, Information Security authority, AI-ML Lead, Legal Authority are trained, attributable users with documented authority.
- Human-on-loop reviewers are qualified per URS-28 DEC-28-23 qualification-gate.
- AI-assisted MIRA surfaces are advisory only.
- The tenant operating jurisdiction(s) are configured.
- LLM substrate is federated through AI Gateway from external providers with secret-store credential governance.

### 2.2 Dependencies

- URS-01.URS-31, URS-33.URS-35 platform contracts.
- The `electronic_signatures` substrate.
- The `authority` substrate.
- The `hitl` substrate.
- The `audit_trail` substrate.
- The `documents` substrate (URS-12 — prompt templates + policy versions).
- The `secret_store` substrate (URS-35 — AI provider credentials).
- The `change_control` substrate (URS-13).
- The training `qualification-gate` substrate (URS-28).
- The `notifications` substrate (URS-30).
- All regulated downstream modules (URS-13.URS-31, URS-33.URS-35) for outbound provenance integration.

### 2.3 Constraints

- The canonical API mounts are `/api/v1/mira/*` + `/api/v1/ai/*`.
- **MIRA is suggestion-only and non-authoritative** — never the sole path to advance any regulated workflow per ARCH-AI-001 binding.
- Every MIRA AI invocation MUST transit the AI Gateway chokepoint per DEC-32-04.
- All five Gateway outcome classes are NON-SILENT.
- AI provider credentials sourced from secret store; inline credentials rejected.
- MIRA availability is never a precondition of revenue-generating authoritative flow per Doctrine Mandate 13 / DEC-32-13.
- Effective model qualification + prompt template + policy versions are immutable; revisions create new version rows.
- Action classes `state_change_request` / `signature_controlled` / `external_transmission` MUST transit HITL per DEC-32-08; the latter two MUST also transit bound e-signature.
- Every downstream artifact MIRA influences MUST carry `outcome_label` per DEC-32-07.
- Context scope binding mandatory per DEC-32-05.
- Per-message persistence mandatory per DEC-32-14 / 21 CFR Part 11 §11.10(e).
- `bypass_ai` first-class on every agentic workflow per DEC-32-15.
- Human-on-loop reviewer MUST satisfy URS-28 qualification-gate per DEC-32-08 / DEC-32-23.

---

## 3. Closed Launch Decisions

### 3.1 Decision register

| Decision ID | Title | Locked decision |
|---|---|---|
| DEC-32-01 | Two-step release path + canonical API contract + **MIRA suggestion-only non-authoritative position with canonical ARCH-AI-001 full AC-1.AC-7 binding** | Module 32 follows the same two-step release path; canonical API mounts `/api/v1/mira/*` + `/api/v1/ai/*`; MIRA is suggestion-only and non-authoritative — never the sole path to advance any regulated workflow per ARCH-AI-001 binding (Module specification explicit position); MIRA produces recommendations and drafts, never authoritative state changes; every state change of regulatory consequence transits HITL + (where applicable) bound e-signature + downstream authoritative module. |
| DEC-32-02 | **Controlled Action Taxonomy** | `mira_action_registry` table persists the controlled set of actions MIRA can initiate; each action carries `action_class` from ENUM `{read_only, recommendation, draft_creation, state_change_request, signature_controlled, external_transmission}`; `state_change_request` action class MUST transit HITL handover per DEC-32-06 + URS-28 qualification-gate verified human-on-loop reviewer per DEC-32-23; `signature_controlled` action class MUST additionally transit bound e-signature per DEC-32-08; `external_transmission` action class MUST additionally transit bound e-signature + URS-13 CR for transmission-target change; `read_only` and `recommendation` action classes do not require HITL handover but DO require `outcome_label` emission per DEC-32-07; `draft_creation` action class requires HITL handover but does not require bound e-signature. |
| DEC-32-03 | Multi-dimensional context model | `tenant_id` mandatory, `user_id` for conversation attribution, `conversation_id`, `message_id`, `context_scope` ENUM per DEC-32-05, `data_categories_accessed` TEXT[] per DEC-32-05, `action_class` ENUM per DEC-32-02. |
| DEC-32-04 | **AI Gateway chokepoint with five non-silent outcome classes + `ai_governance_events` substrate** | Every MIRA AI invocation MUST transit the AI Gateway at `/api/v1/ai/invoke`; the Gateway is the sole evaluation point for: (a) feature flag (FAIL_CLOSED if disabled emitting `flag_off` event); (b) rate limiter (tenant + user + action_class — FAIL_CLOSED on `budget_exceeded` emitting `rate_limited` event); (c) model qualification per DEC-32-09 (FAIL_CLOSED if `qualification_status ≠ qualified` emitting `model_unqualified` event); (d) prompt-version binding per DEC-32-09 (latest effective prompt-template version); (e) policy-version binding per DEC-32-10 (latest effective policy version); the Gateway returns one of five outcome classes — `ok` / `policy_reject` / `rate_limited` / `model_unqualified` / `unavailable` — **all five are NON-SILENT** and emit a row in `ai_governance_events` table; `ai_governance_events` is the platform-wide AI activity ledger; closes ARCH-AI-001 AC-3 v1.0 PARTIAL via explicit policy-rejection path + AC-5 binding. |
| DEC-32-05 | Minimum-necessary context binding per HIPAA §164.502(b) / GDPR Art. 5(1)(c) | Every MIRA request binds a `context_scope` ENUM (`{tenant_only, study, product, batch, complaint, oos, deviation, capa, finding, inspection, batch_record, stability, em, apqr, regulatory_submission, training, dqg_artifact, screen_reader_capture, custom}`) AND a `data_categories_accessed` TEXT[] annotation enumerating the data category labels the request accessed (e.g., `['phi_clinical', 'gxp_quality_record', 'regulatory_submission_metadata']`); the AI Gateway enforces context-scope-driven data-minimization at the prompt-assembly layer (only data within the context_scope is included in the prompt context); HIPAA §164.502(b) and GDPR Art. 5(1)(c) minimum-necessary and data-minimization obligations apply; closes EU AI Act Article 10 (data and data governance) binding. |
| DEC-32-06 | **Handover Task Lifecycle** | `mira_handover_tasks` table materializes every action crossing the MIRA boundary (action classes `draft_creation`, `state_change_request`, `signature_controlled`, `external_transmission`); state machine is `{pending_classification, pending_handover, pending_execution, completed, rejected, cancelled, manual_continuation}`; transition `pending_handover → pending_execution` requires `mira_handover_acceptance_authority` + URS-28 qualification-gate verified human-on-loop reviewer per DEC-32-23 + HITL decision-record per DEC-32-11; transition `pending_execution → completed` linked to downstream authoritative module's record creation; transition `pending_execution → rejected` requires reviewer reason; transition `pending_execution → cancelled` permitted by reviewer or system (e.g., upstream record withdrawal); transition `pending_handover → manual_continuation` permitted when AI unavailable per DEC-32-15 (closes ARCH-AI-001 AC-4 binding); the state machine is auditable, linkable to the downstream `hitl_decision_id` per DEC-32-11, and is the **sole path** by which MIRA influences authoritative state. |
| DEC-32-07 | **Outcome Label Vocabulary** (binds ARCH-AI-001 AC-7) | Every downstream authoritative artifact that MIRA influences carries an `outcome_label` from ENUM `{ai_assisted_accepted, ai_assisted_rejected, ai_assisted_overridden, ai_unavailable_manual, manual_only}`; the label is set at the moment of downstream artifact creation/state-change; the label is **immutable after write** (DB-level constraint); the label is surfaced in audit trail and in the regulator-facing inspection export; **the label is the regulator-facing answer to "did AI influence this decision, and if so, was the human the decider?"**; semantics: `ai_assisted_accepted` (human accepted MIRA suggestion as-is); `ai_assisted_rejected` (MIRA suggestion was generated but human rejected); `ai_assisted_overridden` (MIRA suggestion was generated and human modified before accepting); `ai_unavailable_manual` (MIRA was unavailable / bypassed and human completed manually with `bypass_ai = true`); `manual_only` (MIRA was not invoked for this artifact). |
| DEC-32-08 | **HITL-bound MIRA UI gate per ARCH-AI-001 AC-6 + URS-28 qualification-gate consumer + bound e-signature on signature-controlled action classes** | The MIRA UI gate enforces ARCH-AI-001 AC-6 — AI output NEVER directly binds a GxP field; `state_change_request` / `signature_controlled` / `external_transmission` action classes MUST link to a `hitl_decision_id` per DEC-32-11; the human-on-loop reviewer (the user accepting the handover task) MUST satisfy URS-28 qualification-gate per DEC-32-23 (parallel to URS-29 / URS-31 patterns); `signature_controlled` and `external_transmission` action classes MUST additionally transit bound e-signature persisted via the `electronic_signatures` substrate; the UI presents handover task details, AI confidence band, prompt-template version, model identifier + version, policy version, suggested action, and the bound e-signature ceremony where applicable. |
| DEC-32-09 | **Model qualification per GMLP 10 principles + prompt template versioning + URS-13 CR linkage** | Model qualification persisted in `mira_model_qualification` table; `qualification_status` ENUM `{draft, under_review, qualified, deprecated, withdrawn}`; release to `qualified` requires `model_qualification_release_authority` + HITL + bound e-signature + URS-13 CR linkage + GMLP 10-principle evidence pack (1. Multi-disciplinary expertise; 2. Good software engineering / data quality / security practices; 3. Representative training data; 4. Independent training and test datasets; 5. Reference standards; 6. Model design tailored to data + clinical use; 7. Performance evaluation in clinically relevant setting; 8. Performance evaluation by independent reviewers; 9. Clear info to users; 10. Deployed monitoring); prompt templates persisted in URS-12 with `prompt_template_release_change_request_id` FK to URS-13; effective prompt-template versions are immutable; AI Gateway binds the latest effective prompt-template version at invocation time (`prompt_version_snapshot` in `ai_requests`). |
| DEC-32-10 | Policy version controlled lifecycle | Policy versions (e.g., content moderation policy, output filtering policy, tone policy, regulated-domain hallucination filter) persisted in URS-12 as controlled documents with `policy_version_release_change_request_id` FK to URS-13; effective policy versions are immutable; AI Gateway binds the latest effective policy version at invocation time (`policy_version_snapshot` in `ai_requests`). |
| DEC-32-11 | HITL decision-record linkage | `mira_handover_tasks.hitl_decision_id` FK to the platform-wide `hitl_decisions` substrate (URS-04); the linkage is mandatory for `state_change_request` / `signature_controlled` / `external_transmission` action classes per DEC-32-08; the HITL decision record persists the actor, decision (accept/reject/cancel), timestamp, and (where applicable) bound e-signature reference. |
| DEC-32-12 | **MIRA event dead-letter queue (`mira_event_dlq`)** (closing ARCH-AI-001 AC-5 binding) | `mira_event_dlq` table captures AI errors that cannot be processed (e.g., AI Gateway transient failures beyond retry budget, downstream record-creation failures during handover task execution, unprocessable governance events); each DLQ row persists `original_event_payload_json`, `error_class`, `error_message`, `retry_count`, `last_error_at`, `disposition` (ENUM `{pending_review, replayed, abandoned}`); stale DLQ items emit `dqg_finding_created`-style event to URS-21 per DEC-32-15; closes ARCH-AI-001 AC-5 binding (no silent swallow of AI errors). |
| DEC-32-13 | **AI Gateway availability surface** (closing ARCH-AI-001 AC-2 binding + Doctrine Mandate 13) | The AI Gateway exposes `/api/v1/ai/health` (returns Gateway operational state, model qualification status, rate-limit remaining budget, active feature flag) AND `/api/v1/mira/availability` (returns MIRA-specific availability state derived from Gateway health + MIRA-specific feature flags); the MIRA UI displays a persistent banner reflecting AI availability state changes; **AI availability is never a precondition of revenue-generating authoritative flow** per Doctrine Mandate 13 — the underlying authoritative module remains operable via `bypass_ai = true` per DEC-32-15 even when AI is unavailable; URS-30 Notifications consumes AI availability state changes for tenant-admin alerts. |
| DEC-32-14 | Per-message persistence with full audit per 21 CFR Part 11 §11.10(e) | Every MIRA message (user and assistant) persisted in `mira_messages` with full audit-trail entry including `tenant_id`, `user_id`, `conversation_id`, `message_id`, `role` (user/assistant/system), `content`, `context_scope`, `data_categories_accessed`, `action_class` (where applicable), `ai_request_id` (where applicable), `outcome_label` (assistant messages where applicable), `bypass_ai` (where applicable), `created_at`; messages are append-only post-creation (immutable). |
| DEC-32-15 | **Manual Fallback for Agentic Workflows (`bypass_ai`)** (binds ARCH-AI-001 AC-1) | Every agentic workflow surface (every place MIRA can offer assistance) has `bypass_ai: boolean` (default `false`) + `bypass_reason: string` (required when `bypass_ai = true`) first-class fields; UI surfaces a clearly visible "Bypass AI" control; when `bypass_ai = true`, the underlying authoritative workflow proceeds without invoking the AI Gateway; the resulting downstream artifact carries `outcome_label = ai_unavailable_manual` per DEC-32-07; **AI availability is never a precondition of revenue-generating authoritative flow** per Doctrine Mandate 13; bypass-ai uses are audited; closes ARCH-AI-001 AC-1 binding. |
| DEC-32-16 | Findings emission to URS-21 + CAPA emission to URS-18 | AI governance event clustering (≥ configurable threshold of `policy_reject` / `rate_limited` / `model_unqualified` / `unavailable` events per period per tenant), DLQ stale messages (≥ configurable threshold per period), and chronic AI Gateway availability degradation emit `mira_finding_created` event to URS-21 with `mira_ai_governance` source type; chronic patterns escalated to CAPA emit `mira_capa_linked` event consumed by URS-18 (`mira_ai_governance` source type per URS-18 declared source set). |
| DEC-32-17 | URS-12 Document Control linkage for prompt templates + policy versions | Per DEC-32-09 / DEC-32-10. |
| DEC-32-18 | URS-13 change-control linkage for model qualification + prompt + policy effective release | Per DEC-32-09 / DEC-32-10. |
| DEC-32-19 | Authority/HITL/e-sign on every regulated final action | Per DEC-32-08. |
| DEC-32-20 | platform_admin / super_admin | `platform_admin` / `super_admin` are support / break-glass only paths. |
| DEC-32-21 | Reason-for-change on material updates | Captured per DEC-32-14. |
| DEC-32-22 | MIRA program reopen as governed transition | Program `locked → in_progress` requires `executive_authority` co-sign AND `qualified_person_authority` co-sign + documented reason; appends a new program iteration without mutating prior locked evidence (consistent with M14.M31 reopen pattern). |
| DEC-32-23 | **Outbound provenance integration with all 18 other regulated URS modules + URS-28 qualification-gate inbound consumer** | MIRA emits `outcome_label` per DEC-32-07 to every downstream artifact it influences across URS-13 / URS-14 / URS-15 / URS-16 / URS-17 / URS-18 / URS-19 / URS-20 / URS-21 / URS-22 / URS-23 / URS-24 / URS-25 / URS-26 / URS-27 / URS-28 / URS-29 / URS-30 / URS-31 (every regulated module that MIRA can influence); the `outcome_label` is persisted on the downstream artifact (e.g., `mira_outcome_label` column on `complaints`, `oos_results`, etc.) — NOT only in MIRA's own tables; this is the regulator-facing audit linkage; MIRA inbound consumes URS-28 qualification-gate API for human-on-loop reviewer authority verification per DEC-32-08 / DEC-32-23. |

### 3.2 Locked-decision rationale narrative

The decisions above define the binding launch posture for Module 32 v1.0. The most consequential locked controls are: (a) **DEC-32-01 anchors MIRA's suggestion-only non-authoritative position** with canonical ARCH-AI-001 full AC-1..AC-7 binding — making MIRA's AI prohibition the broadest in the URS pack; (b) **DEC-32-02 introduces the Controlled Action Taxonomy** with 6-value `action_class` ENUM and clear handover/HITL/e-sign requirements per class; (c) **DEC-32-04 anchors the AI Gateway as the sole chokepoint** for every MIRA AI invocation with five non-silent outcome classes + `ai_governance_events` ledger — providing the platform-wide AI activity audit substrate; (d) **DEC-32-05 binds MIRA to HIPAA / GDPR data-minimization** via context-scope + data-categories-accessed annotation; (e) **DEC-32-06 introduces the 7-state Handover Task Lifecycle** as the sole path by which MIRA influences authoritative state; (f) **DEC-32-07 introduces the Outcome Label Vocabulary** providing the regulator-facing answer to "did AI influence this decision?" and binds ARCH-AI-001 AC-7; (g) **DEC-32-09 / DEC-32-10 anchor model qualification** per GMLP 10 principles + prompt + policy controlled lifecycle; (h) **DEC-32-12 mandates the MIRA event DLQ** — no silent swallow of AI errors (binds ARCH-AI-001 AC-5); (i) **DEC-32-13 mandates the AI Gateway availability surface** (binds ARCH-AI-001 AC-2); (j) **DEC-32-15 mandates `bypass_ai` first-class** on every agentic workflow surface (binds ARCH-AI-001 AC-1 + AC-4); (k) **DEC-32-23 introduces the keystone outbound provenance integration** with all 18 other regulated URS modules — making MIRA's influence transparent to auditors regardless of which downstream module the artifact lives in; (l) DEC-32-22 defines reopen as a governed append-only transition consistent with the Module-14..-31 reopen pattern.

### 3.3 Closed launch decisions: cross-link to controlled items

| Specification item | Locked control at v1.0 | Locked decision |
|---|---|---|
| Controlled Action Taxonomy | 6-value `action_class` ENUM with handover/HITL/e-sign requirements per class | DEC-32-02 |
| Handover Task Lifecycle | 7-state machine as the sole path by which MIRA influences authoritative state | DEC-32-06 |
| Outcome Label Vocabulary | 5-value ENUM mandatory + immutable on every MIRA-influenced downstream artifact | DEC-32-07 |
| Manual Fallback for Agentic Workflows | `bypass_ai: boolean` + `bypass_reason: string` first-class on every agentic workflow surface | DEC-32-15 |
| ARCH-AI-001 AC-1 (Primary action operable without AI) | Bound | DEC-32-15 |
| ARCH-AI-001 AC-2 (AI availability surfaced to user) | Bound | DEC-32-13 |
| ARCH-AI-001 AC-3 (Policy-rejection path explicit) | Bound | DEC-32-04 / DEC-32-08 |
| ARCH-AI-001 AC-4 (Manual continuation persisted) | Bound | DEC-32-15 / DEC-32-07 |
| ARCH-AI-001 AC-5 (No silent swallow of AI errors) | Bound | DEC-32-04 / DEC-32-12 |
| ARCH-AI-001 AC-6 (AI output never directly binds GxP field) | Bound | DEC-32-08 / DEC-32-11 |
| ARCH-AI-001 AC-7 (Outcome provenance label) | Bound | DEC-32-07 |

### 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 — Read-only / Recommendation action class (no HITL required).**
A user opens MIRA chat and asks "What's the status of complaint COMPLAINT-2026-08-12-001?" MIRA classifies the action as `read_only` per DEC-32-02. The AI Gateway invokes; outcome `ok`; `ai_governance_events` row emitted per DEC-32-04. MIRA returns the complaint status. No handover task created (read-only doesn't cross MIRA boundary). The downstream complaint record is **not modified**, so no `outcome_label` is needed at the complaint level — but the `mira_messages` row carries `action_class = read_only`.

**Worked example 2 — Draft creation action class with HITL.**
The user asks MIRA "Draft a deviation report for the OOS we just discussed." MIRA classifies the action as `draft_creation` per DEC-32-02. AI Gateway invokes; outcome `ok`; `ai_governance_events` row. MIRA composes a draft deviation report. A handover task `mira_handover_task_id = HT-001` is created with `state = pending_handover` per DEC-32-06. The user (URS-28-qualified per DEC-32-23) reviews the draft, modifies a few fields, and accepts the handover with `mira_handover_acceptance_authority` + HITL decision capture per DEC-32-08 / DEC-32-11. State `pending_handover → pending_execution → completed`. A new URS-16 deviation record is created; **the deviation record carries `mira_outcome_label = ai_assisted_overridden`** per DEC-32-07 (because the user modified MIRA's draft).

**Worked example 3 — State change request action class.**
The user asks MIRA "Mark the OOS investigation as complete." MIRA classifies the action as `state_change_request` per DEC-32-02. Handover task created. The reviewer (URS-28 qualified) accepts with HITL + `mira_handover_acceptance_authority` per DEC-32-08. State `pending_execution → completed`. The URS-15 OOS investigation transitions to complete; **the OOS record carries `mira_outcome_label = ai_assisted_accepted`** per DEC-32-07.

**Worked example 4 — Signature controlled action class (with bound e-signature).**
The user asks MIRA "Sign the QA review of batch BR-PTabs-2026-08-12-001." MIRA classifies the action as `signature_controlled` per DEC-32-02 — this MUST transit bound e-signature per DEC-32-08. Handover task created. The reviewer (URS-28 qualified Qualified Person) accepts with HITL + bound e-signature persisted via `electronic_signatures` substrate. State `pending_execution → completed`. The URS-23 batch record QA review transitions; **the batch record carries `mira_outcome_label = ai_assisted_accepted`** per DEC-32-07. **AI cannot finalize this signature on its own** — only the qualified human QP can sign per ARCH-AI-001 AC-6 binding.

**Worked example 5 — External transmission action class.**
The user asks MIRA "Submit the regulatory submission to FDA ESG." MIRA classifies the action as `external_transmission` per DEC-32-02 — MUST transit bound e-signature + URS-13 CR for transmission-target change per DEC-32-02. Handover task created with the URS-13 CR linkage. The reviewer accepts with HITL + bound e-signature. The URS-27 regulatory submission transitions to `submitted`; **the regulatory submission record carries `mira_outcome_label = ai_assisted_accepted`** per DEC-32-07.

**Worked example 6 — Policy reject (AI Gateway non-silent outcome).**
The user asks MIRA "Generate marketing claims for Product P." MIRA classifies the action as `draft_creation`. The AI Gateway invokes and the policy filter detects regulated-domain content (drug marketing claims require regulatory pre-approval); outcome `policy_reject`; `ai_governance_events` row emitted with `event_type = policy_reject` per DEC-32-04. MIRA returns a policy-rejection message to the user with the explanation; an HITL handover task is created with state `pending_handover` per DEC-32-08 binding the policy-rejected draft for human review per DEC-32-08.

**Worked example 7 — Rate limited (AI Gateway non-silent outcome).**
The user makes their 51st MIRA invocation in 60 seconds (configured rate limit). The AI Gateway invokes and rate limiter returns `budget_exceeded`; outcome `rate_limited`; `ai_governance_events` row emitted per DEC-32-04. MIRA returns a rate-limit message to the user with `manual_continuation` offered per DEC-32-15. The user can `bypass_ai = true` and proceed with the manual workflow per DEC-32-15.

**Worked example 8 — Model unqualified (AI Gateway non-silent outcome).**
The configured MIRA model `claude-sonnet-4` has its `qualification_status` set to `deprecated` due to drift detection in periodic monitoring per DEC-32-09. The next MIRA invocation evaluates model qualification at the AI Gateway and finds `qualification_status ≠ qualified`; outcome `model_unqualified`; `ai_governance_events` row emitted per DEC-32-04; manual continuation forced per DEC-32-15. URS-30 Notifications dispatches an alert to the AI-ML Lead per DEC-32-13.

**Worked example 9 — AI unavailable (AI Gateway non-silent outcome) + `bypass_ai`.**
External LLM provider has an outage. The AI Gateway invokes and detects unavailability; outcome `unavailable`; `ai_governance_events` row emitted per DEC-32-04. The MIRA UI persistent banner displays "AI temporarily unavailable" per DEC-32-13. The user clicks "Bypass AI" per DEC-32-15; `bypass_ai = true` set on the underlying authoritative workflow; the downstream artifact carries `mira_outcome_label = ai_unavailable_manual` per DEC-32-07. **The user completes the regulated workflow successfully** per Doctrine Mandate 13 — AI availability is never a precondition of revenue-generating flow.

**Worked example 10 — DLQ stale messages → URS-21 finding.**
Over 30 days, 47 AI errors accumulate in `mira_event_dlq` per DEC-32-12 without disposition. The stale-DLQ detector emits `mira_finding_created` event to URS-21 per DEC-32-15 / DEC-32-16 with `severity = major`, `source_type = mira_ai_governance`. URS-21 standalone finding created. If the pattern persists, URS-18 CAPA opens via `mira_capa_linked` per DEC-32-16.

**Worked example 11 — Governed reopen of locked MIRA program.**
On `2027-04-15` an inspection finding (URS-22) reveals a previously locked MIRA program may have under-recorded one outcome label. The Manufacturing Head initiates a reopen; per DEC-32-22 + SoD-32-06, both `executive_authority` co-sign AND `qualified_person_authority` co-sign + documented reason are required. On both co-signs the program transitions `locked → in_progress` and a new program iteration is appended; the prior locked evidence is NOT mutated.

---

## 4. End-to-End User Journeys (28 launch journeys)

| # | Journey | Actor | Pre-condition | Path | Post-condition |
|---|---|---|---|---|---|
| 1 | Create MIRA conversation | User | `mira:conversation:create` | Create conversation with `tenant_id` + `user_id` | Conversation persisted; audit entry |
| 2 | Send user message | User | Conversation exists | POST message; persist `mira_messages` row per DEC-32-14 | Message persisted; audit entry |
| 3 | Action intent classification (read_only) | System | User message received | Classify `action_class = read_only` per DEC-32-02 | Read-only action; no handover required |
| 4 | AI Gateway invocation (ok outcome) | System | Action classified | Transit AI Gateway per DEC-32-04; outcome `ok`; emit `ai_governance_events` row | AI Gateway invocation logged |
| 5 | AI Gateway invocation (policy_reject outcome) | System | Policy filter triggered | AI Gateway returns `policy_reject`; emit `ai_governance_events` row + HITL handover for draft per DEC-32-04 / DEC-32-08 | Policy-rejection logged; handover created |
| 6 | AI Gateway invocation (rate_limited outcome) | System | Rate limit budget exceeded | AI Gateway returns `rate_limited`; emit `ai_governance_events` row; offer `manual_continuation` per DEC-32-15 | Rate-limit logged; manual continuation offered |
| 7 | AI Gateway invocation (model_unqualified outcome) | System | Model qualification ≠ qualified | AI Gateway returns `model_unqualified`; emit `ai_governance_events` row; force manual path per DEC-32-15 | Model-unqualified logged |
| 8 | AI Gateway invocation (unavailable outcome) | System | AI provider outage | AI Gateway returns `unavailable`; emit `ai_governance_events` row; force manual path | Unavailable logged; banner updated per DEC-32-13 |
| 9 | Context scope binding | System | Per request | Bind `context_scope` + `data_categories_accessed` per DEC-32-05 | Minimum-necessary enforced |
| 10 | Materialize handover task | System | Action class ∈ {draft_creation, state_change_request, signature_controlled, external_transmission} | Create `mira_handover_tasks` row in `pending_classification → pending_handover` per DEC-32-06 | Handover task created |
| 11 | URS-28 qualification gate check | System | Handover task `pending_handover` | Verify human-on-loop reviewer URS-28 qualified per DEC-32-23 | If qualified: proceeds; if not: rejects |
| 12 | Accept handover (state_change_request) | `mira_handover_acceptance_authority` (URS-28 qualified) | Handover `pending_handover` | HITL + DEC-32-08 + create `hitl_decision_id` per DEC-32-11 | Handover `pending_execution`; HITL decision recorded |
| 13 | Accept handover (signature_controlled) | `mira_handover_acceptance_authority` (URS-28 qualified) | Handover `pending_handover` | HITL + bound e-sign per DEC-32-08 | Handover `pending_execution`; bound e-signature persisted |
| 14 | Accept handover (external_transmission) | `mira_handover_acceptance_authority` (URS-28 qualified) | Handover `pending_handover`; URS-13 CR for target | HITL + bound e-sign + URS-13 CR linkage per DEC-32-02 | Handover `pending_execution`; bound e-signature + CR linkage |
| 15 | Reject handover | Reviewer | Handover `pending_handover` or `pending_execution` | Reject with reason | Handover `rejected` |
| 16 | Cancel handover | Reviewer or System | Handover `pending_handover` or `pending_execution` | Cancel | Handover `cancelled` |
| 17 | Manual continuation (AI unavailable) | User | AI Gateway `unavailable` outcome | Offer manual continuation per DEC-32-15; transition `pending_handover → manual_continuation` | Handover `manual_continuation`; underlying workflow proceeds without AI |
| 18 | Bypass AI on agentic workflow | User | Agentic workflow surface | Set `bypass_ai = true` + `bypass_reason` per DEC-32-15; underlying authoritative workflow proceeds without AI | Workflow proceeds; downstream artifact carries `outcome_label = ai_unavailable_manual` |
| 19 | Emit outcome label to downstream artifact (ai_assisted_accepted) | System | Handover `completed` and downstream artifact created | Persist `mira_outcome_label = ai_assisted_accepted` on downstream artifact per DEC-32-07 / DEC-32-23 | Downstream artifact carries immutable outcome label |
| 20 | Emit outcome label (ai_assisted_overridden) | System | Handover completed with reviewer modifications | Persist `mira_outcome_label = ai_assisted_overridden` | Outcome label recorded |
| 21 | Emit outcome label (ai_assisted_rejected) | System | Handover rejected by reviewer | Persist `mira_outcome_label = ai_assisted_rejected` on the source-record context | Outcome label recorded |
| 22 | Emit outcome label (manual_only) | System | Workflow completed without MIRA invocation | Persist `mira_outcome_label = manual_only` | Outcome label recorded |
| 23 | DLQ persistence on AI error | System | AI error beyond retry budget | Persist `mira_event_dlq` row per DEC-32-12 | DLQ row persisted |
| 24 | DLQ stale → URS-21 finding | System (scheduled) | DLQ items ≥ 30 days unprocessed | Emit `mira_finding_created` to URS-21 per DEC-32-15 | URS-21 finding created |
| 25 | AI availability state change → URS-30 notification | System | AI Gateway health state change | Emit availability event consumed by URS-30 per DEC-32-13 | Notification dispatched |
| 26 | Model qualification effective release | `model_qualification_release_authority` | Model `under_review`; URS-13 CR; GMLP evidence | HITL + bound e-sign + URS-13 CR + GMLP evidence pack per DEC-32-09 | Model `qualified`; bound e-signature |
| 27 | Prompt template / policy version effective release | Respective release authority | Template/policy `under_review`; URS-13 CR | HITL + bound e-sign + URS-13 CR per DEC-32-09 / DEC-32-10 | Template/policy `effective` |
| 28 | Reopen locked MIRA program (governed transition) | Manufacturing Head + Executive Authority + Qualified Person | Program `locked` | Executive co-sign AND QP co-sign + reason; transition `locked → in_progress`; append new iteration per DEC-32-22 | Program `in_progress`; new iteration appended; prior locked evidence NOT mutated |

---

## 5. Front-end Requirements

### 5.1 MIRA Chat UI

The MIRA chat UI (URS-32-FE-001) renders persistent multi-session multi-conversation chat with: confidence pill on assistant messages, action class CTAs per `action_class`, **`bypass_ai` control** per DEC-32-15, **persistent AI availability banner** per DEC-32-13, suggestion details, handover task surfaces; uses canonical `/mira/*` hooks.

### 5.2 Handover Task Console

The handover task console (URS-32-FE-002) renders pending handover tasks with action class, AI confidence band, prompt-template version, model identifier + version, policy version, suggested action; HITL decision ceremony with bound e-signature where applicable per DEC-32-08; URS-28 qualification-gate UI feedback per DEC-32-23.

### 5.3 Action Registry Console

The action registry console (URS-32-FE-003) renders the controlled action taxonomy with `action_class` distribution and per-class governance requirements per DEC-32-02.

### 5.4 AI Gateway Health Console

The AI Gateway health console (URS-32-FE-004) renders Gateway operational state, model qualification status, rate-limit remaining budget, active feature flag, recent `ai_governance_events` per DEC-32-04 / DEC-32-13.

### 5.5 AI Governance Events Console

The AI governance events console (URS-32-FE-005) renders the platform-wide AI activity ledger with filtering by event type, tenant, user, action class.

### 5.6 DLQ Console

The DLQ console (URS-32-FE-006) renders MIRA event DLQ items with disposition controls (replay / abandon) per DEC-32-12.

### 5.7 Model Qualification Console

The model qualification console (URS-32-FE-007) supports model qualification draft authoring with GMLP 10-principle evidence pack; release flow with HITL + bound e-signature + URS-13 CR per DEC-32-09.

### 5.8 Prompt Template Console

The prompt template console (URS-32-FE-008) supports prompt template draft authoring; release flow with HITL + bound e-signature + URS-13 CR per DEC-32-09 (templates stored as URS-12 documents).

### 5.9 Policy Version Console

The policy version console (URS-32-FE-009) supports policy version draft authoring; release flow with HITL + bound e-signature + URS-13 CR per DEC-32-10.

### 5.10 Outcome Label Audit Viewer

The outcome label audit viewer (URS-32-FE-010) renders MIRA-influenced downstream artifacts grouped by `outcome_label` per DEC-32-07 across all 18 other regulated URS modules per DEC-32-23 — the regulator-facing transparency surface.

### 5.11 Accessibility

WCAG 2.1 AA accessible.

---

## 6. Back-end Requirements

### 6.1 Module structure

`packages/backend/src/modules/mira/` + `packages/backend/src/modules/ai-gateway/` + `packages/backend/src/modules/panel/` with `plugin.ts`, `routes.ts`, `service.ts` (Controlled Action Taxonomy classifier; Handover Task Lifecycle engine; Outcome Label Vocabulary emitter; AI Gateway chokepoint; minimum-necessary context binding; per-message persistence; bypass_ai handling; URS-28 qualification-gate consumer; outbound provenance integration), `schemas.ts`, `events.ts`, `ai-gateway.service.ts` (5-outcome-class chokepoint per DEC-32-04), `model-qualification-engine.ts` (per DEC-32-09 GMLP), `prompt-template-engine.ts` (per DEC-32-09), `policy-version-engine.ts` (per DEC-32-10), `dlq-handler.ts` (per DEC-32-12), `availability-monitor.ts` (per DEC-32-13).

### 6.2 Data model

#### 6.2.1 `mira_conversations`

`id`, `tenant_id`, `user_id`, `created_at`, `updated_at`, audit columns. RLS enabled.

#### 6.2.2 `mira_messages`

`id`, `tenant_id`, `conversation_id` (FK), `role` (ENUM `user` / `assistant` / `system`), `content` (TEXT), `context_scope` (ENUM per DEC-32-05), `data_categories_accessed` (TEXT[] per DEC-32-05), `action_class` (ENUM nullable per DEC-32-02), `ai_request_id` (FK nullable to `ai_requests`), `outcome_label` (ENUM nullable per DEC-32-07 — set on assistant messages where applicable), `bypass_ai` (BOOLEAN DEFAULT false per DEC-32-15), `bypass_reason` (TEXT nullable), `created_at` (TIMESTAMPTZ — server-attributed), audit columns. Append-only post-creation per DEC-32-14.

#### 6.2.3 `mira_action_registry`

`id`, `tenant_id`, `action_code`, `action_name`, `action_class` (ENUM `read_only` / `recommendation` / `draft_creation` / `state_change_request` / `signature_controlled` / `external_transmission` per DEC-32-02), `description`, `requires_hitl` (BOOLEAN), `requires_bound_e_signature` (BOOLEAN), `requires_urs13_cr` (BOOLEAN), `target_module` (TEXT — e.g., `urs_14_complaints`), audit columns.

#### 6.2.4 `mira_handover_tasks`

`id`, `tenant_id`, `conversation_id` (FK), `message_id` (FK), `action_id` (FK), `action_class` (ENUM), `state` (ENUM `pending_classification` / `pending_handover` / `pending_execution` / `completed` / `rejected` / `cancelled` / `manual_continuation` per DEC-32-06), `accepted_by` (FK nullable), `accepted_at`, `acceptance_e_signature_id` (FK nullable per DEC-32-08), `hitl_decision_id` (FK nullable per DEC-32-11), `rejection_reason` (TEXT nullable), `target_module_record_id` (UUID nullable — the downstream artifact created), `urs28_qualification_evidence_json` (JSONB nullable per DEC-32-23), audit columns.

#### 6.2.5 `mira_model_qualification`

`id`, `tenant_id`, `model_id`, `model_version`, `qualification_status` (ENUM `draft` / `under_review` / `qualified` / `deprecated` / `withdrawn` per DEC-32-09), `release_change_request_id` (FK to URS-13), `gmlp_evidence_pack_document_id` (FK to URS-12 — GMLP 10-principle evidence), `approved_by`, `approved_at`, `e_signature_id`, audit columns.

#### 6.2.6 `mira_prompt_templates`

`id`, `tenant_id`, `template_code`, `version` (INTEGER NOT NULL), `template_document_id` (FK to URS-12 NOT NULL per DEC-32-09), `release_change_request_id` (FK to URS-13), `effective_from`, `effective_to`, `supersedes_template_id` (self-FK nullable), `approved_by`, `approved_at`, `e_signature_id`, `status` (ENUM `draft` / `under_review` / `effective` / `superseded` / `archived`), audit columns.

#### 6.2.7 `mira_policy_versions`

`id`, `tenant_id`, `policy_code`, `version` (INTEGER NOT NULL), `policy_document_id` (FK to URS-12 NOT NULL per DEC-32-10), `release_change_request_id` (FK to URS-13), `effective_from`, `effective_to`, `supersedes_policy_id` (self-FK nullable), `approved_by`, `approved_at`, `e_signature_id`, `status` (ENUM `draft` / `under_review` / `effective` / `superseded` / `archived`), audit columns.

#### 6.2.8 `ai_governance_events`

`id`, `tenant_id`, `user_id`, `conversation_id` (FK nullable), `message_id` (FK nullable), `event_type` (ENUM `flag_off` / `rate_limited` / `model_unqualified` / `policy_reject` / `unavailable` / `ok` per DEC-32-04), `event_payload_json` (JSONB), `model_id_snapshot`, `model_version_snapshot`, `prompt_template_version_snapshot`, `policy_version_snapshot`, `created_at`, audit columns. Append-only.

#### 6.2.9 `ai_requests`

`id`, `tenant_id`, `conversation_id` (FK), `message_id` (FK), `model_id`, `model_version`, `prompt_template_id` (FK to URS-12), `prompt_version_snapshot` (INTEGER), `policy_version_snapshot` (INTEGER), `request_payload_json` (JSONB), `response_payload_json` (JSONB nullable), `outcome_class` (ENUM per DEC-32-04), `processing_time_ms`, `confidence`, `created_at`, audit columns.

#### 6.2.10 `mira_event_dlq`

`id`, `tenant_id`, `original_event_payload_json` (JSONB), `error_class`, `error_message`, `retry_count` (INTEGER DEFAULT 0), `last_error_at`, `disposition` (ENUM `pending_review` / `replayed` / `abandoned` per DEC-32-12), `dispositioned_by`, `dispositioned_at`, audit columns.

#### 6.2.11 `mira_program_locks`

`id`, `tenant_id`, `period_start`, `period_end`, `locked_by`, `locked_at`, `lock_e_signature_id`, `reopened_at`, `reopened_by`, `reopen_executive_co_signer`, `reopen_qp_co_signer`, `reopen_reason`, audit columns.

#### 6.2.12 Outbound provenance integration per DEC-32-23

Every regulated downstream module (URS-13.URS-31, URS-33.URS-35) MUST add a `mira_outcome_label` ENUM column to its primary record table (e.g., `complaints.mira_outcome_label`, `oos_results.mira_outcome_label`, `deviations.mira_outcome_label`, etc.) per DEC-32-07 / DEC-32-23. The column is mandatory + immutable post-write.

#### 6.2.13 RLS

All Module 32 tables have RLS enabled.

### 6.3 API contract

| Route | Method | Permission | Status |
|---|---|---|---|
| `/api/v1/mira/conversations` | GET / POST | `mira:conversation:read` / `mira:conversation:create` | |
| `/api/v1/mira/conversations/:id` | GET | `mira:conversation:read` | |
| `/api/v1/mira/messages` | POST | `mira:message:create` (transits AI Gateway per DEC-32-04) | |
| `/api/v1/mira/messages/:id` | GET | `mira:message:read` | |
| `/api/v1/mira/handover-tasks` | GET | `mira:handover_task:read` | |
| `/api/v1/mira/handover-tasks/:id` | GET | `mira:handover_task:read` | |
| `/api/v1/mira/handover-tasks/:id/accept` | POST | `mira_handover_acceptance_authority` + URS-28 qualification gate per DEC-32-23 + HITL + (where applicable) bound e-sign per DEC-32-08 | target route |
| `/api/v1/mira/handover-tasks/:id/reject` | POST | `mira_handover_acceptance_authority` + reason | target route |
| `/api/v1/mira/handover-tasks/:id/cancel` | POST | reviewer or system | target route |
| `/api/v1/mira/availability` | GET | `mira:availability:read` per DEC-32-13 | target route |
| `/api/v1/mira/bypass-ai` | POST | per agentic workflow per DEC-32-15 | target route |
| `/api/v1/mira/action-registry` | GET / POST | `mira:action_registry:read` / `mira:action_registry:create` | target route |
| `/api/v1/mira/outcome-labels` | GET | `mira:outcome_label:read` (the regulator-facing transparency endpoint per DEC-32-07 / DEC-32-23) | target route |
| `/api/v1/ai/invoke` | POST | `ai_gateway:invoke` (the AI Gateway chokepoint per DEC-32-04) | |
| `/api/v1/ai/health` | GET | `ai_gateway:health:read` per DEC-32-13 | target route |
| `/api/v1/ai/governance-events` | GET | `ai_gateway:governance_events:read` | target route |
| `/api/v1/ai/dlq` | GET | `ai_gateway:dlq:read` per DEC-32-12 | target route |
| `/api/v1/ai/dlq/:id/replay` | POST | `ai_gateway:dlq:replay` per DEC-32-12 | target route |
| `/api/v1/ai/dlq/:id/abandon` | POST | `ai_gateway:dlq:abandon` + reason | target route |
| `/api/v1/ai/model-qualifications` | GET / POST | `ai_gateway:model_qualification:read` / `ai_gateway:model_qualification:create` | target route |
| `/api/v1/ai/model-qualifications/:id/release` | POST | `model_qualification_release_authority` + HITL + bound e-sign + URS-13 CR + GMLP evidence per DEC-32-09 | target route |
| `/api/v1/ai/prompt-templates` | GET / POST | `ai_gateway:prompt_template:read` / `ai_gateway:prompt_template:create` | target route |
| `/api/v1/ai/prompt-templates/:id/release` | POST | `prompt_template_release_authority` + HITL + bound e-sign + URS-13 CR per DEC-32-09 | target route |
| `/api/v1/ai/policy-versions` | GET / POST | `ai_gateway:policy_version:read` / `ai_gateway:policy_version:create` | target route |
| `/api/v1/ai/policy-versions/:id/release` | POST | `policy_version_release_authority` + HITL + bound e-sign + URS-13 CR per DEC-32-10 | target route |
| `/api/v1/mira/program-locks` | POST | `final_quality_approver` + HITL + bound e-sign | target route |
| `/api/v1/mira/program-locks/:id/reopen` | POST | `executive_authority` co-sign AND `qualified_person_authority` co-sign + HITL + reason per DEC-32-22 | target route |

### 6.4 Workflow

#### 6.4.1 MIRA conversation lifecycle

```mermaid
sequenceDiagram
 participant U as User
 participant UI as MIRA UI
 participant CONV as Conversation Controller
 participant MSG as Message Router
 participant CLS as Action Classifier
 participant AGW as AI Gateway
 participant LLM as LLM
 participant HT as Handover Task Engine
 participant HITL as HITL Decision
 participant DOWN as Downstream Module
 U->>UI: send message
 UI->>CONV: POST /mira/messages (with bypass_ai flag per DEC-32-15)
 alt bypass_ai = false
 CONV->>MSG: persist message; bind context_scope per DEC-32-05
 MSG->>CLS: classify action_class per DEC-32-02
 CLS->>AGW: invoke per DEC-32-04
 AGW->>AGW: feature_flag + rate_limiter + model_qualification + prompt_version + policy_version
 alt outcome = ok
 AGW->>LLM: invoke
 LLM-->>AGW: response
 AGW->>MSG: ai_request persisted; ai_governance_events emit ok
 MSG->>UI: render response
 alt action_class ∈ {draft_creation, state_change_request, signature_controlled, external_transmission}
 MSG->>HT: materialize handover task per DEC-32-06
 HT->>HITL: pending_handover; URS-28 qualification gate per DEC-32-23
 HITL->>U: review and accept/reject
 alt accepted
 HITL->>DOWN: create downstream artifact + bind hitl_decision_id per DEC-32-11
 DOWN->>DOWN: persist mira_outcome_label = ai_assisted_accepted/overridden per DEC-32-07
 end
 end
 else outcome ∈ {policy_reject, rate_limited, model_unqualified, unavailable}
 AGW->>MSG: ai_governance_events emit non-ok event
 MSG->>UI: render error + manual_continuation offered per DEC-32-15
 end
 else bypass_ai = true
 CONV->>DOWN: proceed without AI Gateway
 DOWN->>DOWN: persist mira_outcome_label = ai_unavailable_manual per DEC-32-07
 end
```

#### 6.4.2 Handover task lifecycle

```mermaid
stateDiagram-v2
 [*] --> pending_classification: action class determined
 pending_classification --> pending_handover: classified
 pending_handover --> pending_execution: accept (mira_handover_acceptance_authority + URS-28 qualification + HITL + bound e-sign — DEC-32-08 / DEC-32-23)
 pending_handover --> rejected: reject + reason
 pending_handover --> cancelled: cancel
 pending_handover --> manual_continuation: AI unavailable per DEC-32-15
 pending_execution --> completed: downstream artifact created + outcome_label persisted per DEC-32-07
 pending_execution --> rejected: reject
 pending_execution --> cancelled: cancel
```

### 6.5 Business rules

- BR-32-01: MIRA is suggestion-only and non-authoritative per DEC-32-01.
- BR-32-02: Every MIRA AI invocation MUST transit the AI Gateway chokepoint per DEC-32-04.
- BR-32-03: All five Gateway outcome classes are non-silent and emit `ai_governance_events` rows.
- BR-32-04: Action class enum per DEC-32-02; three escalated classes mandate HITL + (latter two) bound e-sign.
- BR-32-05: Context scope binding mandatory per DEC-32-05.
- BR-32-06: Handover task lifecycle per DEC-32-06; sole path by which MIRA influences authoritative state.
- BR-32-07: Outcome label vocabulary mandatory + immutable on every MIRA-influenced downstream artifact per DEC-32-07.
- BR-32-08: HITL-bound MIRA UI gate per DEC-32-08; AI output never directly binds GxP field.
- BR-32-09: Model qualification per GMLP 10 principles per DEC-32-09.
- BR-32-10: Prompt templates + policy versions stored as URS-12 controlled documents per DEC-32-09 / DEC-32-10.
- BR-32-11: HITL decision-record linkage mandatory for state_change_request / signature_controlled / external_transmission per DEC-32-11.
- BR-32-12: MIRA event DLQ per DEC-32-12; no silent swallow of AI errors.
- BR-32-13: AI Gateway availability surface per DEC-32-13; AI never a precondition of revenue-generating flow.
- BR-32-14: Per-message persistence with full audit per DEC-32-14.
- BR-32-15: `bypass_ai` first-class on every agentic workflow per DEC-32-15.
- BR-32-16: Human-on-loop reviewer URS-28 qualification-gate verified per DEC-32-23.
- BR-32-17: Outbound provenance integration with all 18 other regulated URS modules per DEC-32-23.
- BR-32-18: Material updates require structured reason-for-change per DEC-32-21.
- BR-32-19: Bound e-signature persistence on every regulated final action per DEC-32-08.
- BR-32-20: Program reopen `locked → in_progress` requires `executive_authority` co-sign AND `qualified_person_authority` co-sign + reason per DEC-32-22.
- BR-32-21: `platform_admin` / `super_admin` are support / break-glass only paths per DEC-32-20.

### 6.6 Audit trail

Every Module 32 record mutation persists an audit-trail entry. Per-message persistence per DEC-32-14. AI governance events per DEC-32-04. DLQ events per DEC-32-12. Material updates persist `reason_for_change` per DEC-32-21. Regulated final actions persist a bound e-signature via the `electronic_signatures` substrate. Append-only.

### 6.7 Error handling

| Code | HTTP | Meaning |
|---|---|---|
| `MIRA_VALIDATION_FAILED` | 400 | Schema validation failure |
| `MIRA_UNAUTHORIZED` | 401 | Authentication required |
| `MIRA_FORBIDDEN` | 403 | RBAC denied |
| `MIRA_NOT_FOUND` | 404 | Resource not found |
| `MIRA_INVALID_TRANSITION` | 422 | Lifecycle transition not permitted |
| `MIRA_ACTION_CLASS_REQUIRES_HITL` | 422 | Action class requires HITL handover per DEC-32-02 / DEC-32-08 |
| `MIRA_ACTION_CLASS_REQUIRES_E_SIGNATURE` | 422 | Action class requires bound e-signature per DEC-32-08 |
| `MIRA_ACTION_CLASS_REQUIRES_URS13_CR` | 422 | Action class (external_transmission) requires URS-13 CR per DEC-32-02 |
| `MIRA_HANDOVER_ACCEPTANCE_AUTHORITY_REQUIRED` | 422 | `mira_handover_acceptance_authority` missing |
| `MIRA_HUMAN_ON_LOOP_QUALIFICATION_GATE_FAILED` | 422 | URS-28 qualification gate failed per DEC-32-23 |
| `AI_GATEWAY_FEATURE_FLAG_OFF` | 503 | Feature flag disabled per DEC-32-04 |
| `AI_GATEWAY_RATE_LIMITED` | 429 | Rate limit budget exceeded per DEC-32-04 |
| `AI_GATEWAY_MODEL_UNQUALIFIED` | 503 | Model qualification ≠ qualified per DEC-32-09 |
| `AI_GATEWAY_POLICY_REJECT` | 422 | Policy filter rejection per DEC-32-04 |
| `AI_GATEWAY_UNAVAILABLE` | 503 | AI provider unavailable per DEC-32-04 |
| `MIRA_CONTEXT_SCOPE_REQUIRED` | 422 | Context scope binding missing per DEC-32-05 |
| `MIRA_OUTCOME_LABEL_REQUIRED` | 422 | Outcome label not persisted on downstream artifact per DEC-32-07 / DEC-32-23 |
| `MIRA_OUTCOME_LABEL_IMMUTABLE` | 422 | Attempt to modify outcome label after write per DEC-32-07 |
| `MIRA_HITL_DECISION_REQUIRED` | 422 | HITL decision capture missing |
| `MIRA_E_SIGNATURE_REQUIRED` | 422 | Bound e-signature persistence missing |
| `MIRA_REASON_FOR_CHANGE_REQUIRED` | 422 | Material update without reason-for-change |
| `MIRA_BYPASS_AI_REASON_REQUIRED` | 422 | `bypass_ai = true` without `bypass_reason` per DEC-32-15 |
| `MIRA_AI_AS_AUTHORITATIVE_PROHIBITED` | 422 | AI service attempted to advance authoritative workflow per ARCH-AI-001 / DEC-32-01 |
| `AI_GATEWAY_CHOKEPOINT_BYPASSED` | 422 | AI invocation attempted outside Gateway per DEC-32-04 |
| `MIRA_REOPEN_AUTHORITY_REQUIRED` | 422 | Reopen attempted without executive AND QP co-sign per DEC-32-22 |
| `MIRA_INTERNAL` | 500 | Sanitized server error |

### 6.8 Configuration rules

- AI Gateway rate-limit budgets configurable per tenant per user per action class per DEC-32-04.
- Model qualification GMLP evidence package required for release per DEC-32-09.
- Prompt template + policy version effective release require URS-13 CR per DEC-32-09 / DEC-32-10.
- AI Gateway feature flag toggleable per tenant.
- Stale DLQ threshold (default 30 days) configurable per tenant per DEC-32-12 / DEC-32-15.
- AI provider credentials sourced from secret store.

---

## 7. Non-functional Requirements

- NFR-32-01: List pagination (default 50, max 200).
- NFR-32-02: AI Gateway invocation p95 < 5s including LLM round trip.
- NFR-32-03: Handover task creation p95 < 500ms.
- NFR-32-04: Outcome label emission p95 < 200ms.
- NFR-32-05: AI Gateway availability `/api/v1/ai/health` p95 < 200ms.
- NFR-32-06: Audit-trail append p99 < 200ms (per-message critical path).
- NFR-32-07: Concurrent MIRA conversations per tenant: 500.
- NFR-32-08: Storage scalability: 100M messages per tenant.
- NFR-32-09: Backup / restore RPO ≤ 15 min; RTO ≤ 4 hours per URS-35.
- NFR-32-10: Bound e-signature persistence transaction p95 < 1.5s.
- NFR-32-11: URS-28 qualification-gate consumption p95 < 200ms.
- NFR-32-12: AI Gateway availability SLO ≥ 99.5% (advisory; revenue flow remains operable via `bypass_ai` per DEC-32-15).

---

## 8. Localization

English (en-US, en-GB), Hindi (hi-IN), Marathi (mr-IN), Japanese (ja-JP) at launch.

---

## 9. Migration

### 9.1 Migration scope

Greenfield at launch.

### 9.2 Schema migration

Migration baseline aligned with target migrations columns: add `mira_action_registry`, `mira_handover_tasks`, `ai_governance_events`, `mira_event_dlq`, `mira_model_qualification`, `mira_prompt_templates`, `mira_policy_versions`, `mira_program_locks` tables per DEC-32-02 / DEC-32-04 / DEC-32-06 / DEC-32-07 / DEC-32-09 / DEC-32-10 / DEC-32-12 / DEC-32-22; add `outcome_label` ENUM and `bypass_ai` / `bypass_reason` columns on `mira_messages` per DEC-32-07 / DEC-32-15; **add `mira_outcome_label` column on every regulated downstream module's primary record table** (URS-13.URS-31, URS-33.URS-35) per DEC-32-23; add `release_change_request_id` FK to URS-13 on `mira_model_qualification`, `mira_prompt_templates`, `mira_policy_versions` per DEC-32-09 / DEC-32-10; add immutable constraint trigger on `outcome_label` columns post-write per DEC-32-07.

### 9.3 Migration evidence gate (URS-32-VAL-008)

(a) all migrations applied; (b) RLS verified; (c) typed schema validation verified; (d) Controlled Action Taxonomy 6-value enum verified per DEC-32-02; (e) AI Gateway chokepoint verified — direct AI invocation outside Gateway rejected with `AI_GATEWAY_CHOKEPOINT_BYPASSED`; (f) Five non-silent outcome classes verified — each emits `ai_governance_events` row; (g) Context scope binding verified per DEC-32-05; (h) Handover Task Lifecycle 7-state machine verified per DEC-32-06; (i) Outcome Label Vocabulary 5-value enum verified + immutable post-write per DEC-32-07; (j) HITL-bound MIRA UI gate verified per DEC-32-08; (k) URS-28 qualification-gate consumption verified per DEC-32-23; (l) Model qualification GMLP evidence + URS-13 CR linkage verified per DEC-32-09; (m) Prompt template + policy version controlled lifecycle verified per DEC-32-09 / DEC-32-10; (n) HITL decision-record linkage verified per DEC-32-11; (o) MIRA event DLQ verified per DEC-32-12; (p) AI Gateway availability surface `/api/v1/ai/health` + `/api/v1/mira/availability` + persistent banner verified per DEC-32-13; (q) Per-message persistence verified per DEC-32-14; (r) `bypass_ai` first-class verified per DEC-32-15; (s) Outbound provenance integration with all 18 other regulated URS modules verified per DEC-32-23 — `mira_outcome_label` column persists on every regulated downstream module; (t) cross-module event emission verified; (u) audit-trail coverage verified; (v) governed reopen verified; (w) §17 validation evidence pack signed.

---

## 10. Decommissioning

Module 32 records subject to platform record-retention policy. AI governance events retained per regulatory record-retention rules. On tenant decommissioning, records exported per URS-35.

---

## 11. Decisions, Dependencies, Risks, and Error Handling
### 11.1 Closed decision posture

**No Module 32 internal decisions outstanding.** All decision items including the four controlled-action blocks (Controlled Action Taxonomy, Handover Task Lifecycle, Outcome Label Vocabulary, Manual Fallback for Agentic Workflows) are captured in the locked decisions DEC-32-01..DEC-32-23 above.

### 11.2 External dependencies

- URS-04 HITL substrate must support `mira_handover_acceptance_authority` + bound e-signature.
- URS-12 Document Control must support prompt template + policy version + GMLP evidence document storage per DEC-32-09 / DEC-32-10.
- URS-13 change-control register must support model qualification + prompt template + policy version effective release linkage per DEC-32-09 / DEC-32-10.
- URS-18 CAPA register must accept `mira_ai_governance` source type per DEC-32-16.
- URS-21 findings register must accept `mira_ai_governance` source type per DEC-32-15.
- URS-28 training must expose qualification-gate API for human-on-loop reviewer authority per DEC-32-08 / DEC-32-23.
- URS-30 Notifications must consume AI availability state changes + DLQ alerts per DEC-32-13.
- **All 18 other regulated downstream URS modules (URS-13.URS-31, URS-33.URS-35) must add `mira_outcome_label` column to their primary record tables per DEC-32-23**.
- URS-35 infrastructure must support secret-store integration for AI provider credentials.

### 11.3 Risks

- Risk-32-01: AI provider availability (LLM provider outages). Mitigation: NFR-32-12 SLO; `bypass_ai` per DEC-32-15 ensures revenue flow remains operable.
- Risk-32-02: Model drift detection latency. Mitigation: GMLP principle 10 deployed monitoring; periodic revalidation per DEC-32-09.
- Risk-32-03: Outcome label adoption across 18 other regulated modules. Mitigation: DEC-32-23 mandates the column on every regulated downstream module's primary record table; URS-32-VAL-008 verifies.
- Risk-32-04: Reopen workflow gravity may delay urgent investigations. Mitigation: documented reopen SLA.
- Risk-32-05: AI governance event volume at scale. Mitigation: NFR-32-06 latency budget; partitioned `ai_governance_events` table.

### 11.4 Out-of-scope risks tracked elsewhere

- LLM-substrate technical risks (handled via AI Gateway + secret store).
- Specific LLM provider lock-in (mitigated via federated AI Gateway).

### 11.5 Risk owner

Module-32 risk register owned by MIRA Platform Squad with quarterly review by **Information Security Head (Co-Primary Owner)** + **Chief AI Officer / AI-ML Lead (Co-Primary Owner)** + QA Head + Validation Head + Qualified Person Authority + Legal Authority.

### 11.6 Decision discipline

No Module 32 internal decisions outstanding.

### 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-32-01: Tenant isolation enforced at RLS on every Module 32 table.
- SEC-32-02: RBAC enforced on every route via `requirePermission(.)` using dedicated `mira:*` and `ai_gateway:*` permission set.
- SEC-32-03: Authority resolution enforced on regulated final actions before HITL + e-signature.
- SEC-32-04: HITL decision capture enforced before bound e-signature persistence.
- SEC-32-05: Bound e-signature persistence via `electronic_signatures` substrate.
- SEC-32-06: PII / PHI redaction in logs (MIRA messages may contain PHI; redaction enforced).
- SEC-32-07: Audit-trail integrity via URS-06 hash chain.
- SEC-32-08: AI provider credentials via tenant-controlled secret store; inline credentials rejected.
- SEC-32-09: `platform_admin` / `super_admin` break-glass actions logged per DEC-32-20.
- SEC-32-10: AI Gateway is the sole chokepoint per DEC-32-04; direct AI invocation outside Gateway rejected.
- SEC-32-11: All five Gateway outcome classes non-silent per DEC-32-04.
- SEC-32-12: Outcome label immutable post-write per DEC-32-07.
- SEC-32-13: Per-message persistence with full audit per DEC-32-14.
- SEC-32-14: HIPAA §164.502(b) + GDPR Art. 5(1)(c) minimum-necessary binding per DEC-32-05.
- SEC-32-15: EU AI Act (Regulation 2024/1689) Annex III + Articles 9–15 adopted as internal forward-looking AI governance per Architecture Bindings.

---

## 13. Segregation of Duties

| SoD ID | Constraint |
|---|---|
| SoD-32-01 | The model qualification releaser MUST NOT be the model qualification author. |
| SoD-32-02 | The prompt template releaser MUST NOT be the prompt template author. |
| SoD-32-03 | The policy version releaser MUST NOT be the policy version author. |
| SoD-32-04 | The handover task acceptor MUST NOT be the user who initiated the originating MIRA message (DB-level constraint where applicable). |
| SoD-32-05 | The DLQ disposition actor MUST NOT be the user who originally encountered the DLQ-causing error (where attributable). |
| SoD-32-06 | The reopen co-signers (executive AND Qualified Person per DEC-32-22) MUST NOT be the original lock signer. |
| SoD-32-07 | The `platform_admin` / `super_admin` support / break-glass action MUST NOT be a regulated production action; logged and reviewed per DEC-32-20. |

---

## 14. Regulatory Mapping

| Predicate rule | Section | Module 32 binding |
|---|---|---|
| **FDA 21 CFR Part 11 §11.10(a)** | Validation | URS-32-VAL-008 |
| **FDA 21 CFR Part 11 §11.10(d)** | Authority checks | Authority/HITL/e-sign substrate |
| **FDA 21 CFR Part 11 §11.10(e)** | Audit trails | Per-message persistence per DEC-32-14 + audit-trail substrate |
| **FDA 21 CFR Part 11 §11.50** | Signature manifestations | Bound e-signature manifestations on signature_controlled / external_transmission action classes |
| **FDA 21 CFR Part 11 §11.70** | Signature/record linking | Bound e-signature linked via `electronic_signatures` substrate |
| **FDA 21 CFR Part 11 §11.200** | Electronic signature controls | E-sign substrate compliance |
| **EU GMP Annex 11 §4** | Validation | URS-32-VAL-008 |
| **EU GMP Annex 11 §5** | Data | Context scope binding + minimum-necessary per DEC-32-05 |
| **EU GMP Annex 11 §9** | Audit Trails | Per-message persistence per DEC-32-14 |
| **EU GMP Annex 11 §12** | Security including credential governance | Secret-store credential governance for AI providers |
| **EU GMP Annex 11 §14** | Electronic Records / Signatures | Bound e-signature on every regulated final action |
| **EU GMP Annex 11 §16** | Incident Management | URS-21 finding emission + URS-18 CAPA escalation |
| EU GMP Annex 22 Draft 2025 | §7 — HITL / GenAI advisory only | Internal forward-looking control |
| **EU AI Act (Regulation 2024/1689) Annex III + Articles 9–15** | Adopted as internal forward-looking AI governance | Internal adoption per DEC-32-01 / DEC-32-04 / DEC-32-08 / DEC-32-13 / DEC-32-15; jurisdiction-specific legal enforceability remains subject to a future jurisdiction-specific legal assessment |
| **EU AI Act Article 9** | Risk management system | Risk register §11 + ARCH-AI-001 binding |
| **EU AI Act Article 10** | Data and data governance | Context scope + data_categories_accessed per DEC-32-05 |
| **EU AI Act Article 11** | Technical documentation | Model qualification GMLP evidence per DEC-32-09 |
| **EU AI Act Article 12** | Record-keeping / logging | `ai_governance_events` per DEC-32-04 + per-message persistence per DEC-32-14 |
| **EU AI Act Article 13** | Transparency obligation to user | AI availability surface per DEC-32-13 + outcome label per DEC-32-07 |
| **EU AI Act Article 14** | Human oversight | HITL handover per DEC-32-06 + bypass_ai per DEC-32-15 |
| **EU AI Act Article 15** | Accuracy, robustness, cybersecurity | Model qualification per DEC-32-09 + AI Gateway chokepoint per DEC-32-04 |
| **MHRA Data Integrity Guidance** | ALCOA+ | Per-message ALCOA+-compliant persistence |
| GAMP 5 Cat 5 | Custom-application validation lifecycle | URS-32 validation evidence pack per URS-32-VAL-008 |
| **FDA Computer Software Assurance (CSA) — September 2025 Final Guidance** | Risk-based validation for AI systems | URS-32 risk-based validation aligned with CSA |
| **GMLP (Good Machine Learning Practices) — 10 principles** | Adopted as internal model-qualification control (FDA / MHRA / Health Canada joint guidance referenced) | Model qualification per DEC-32-09 |
| **HIPAA §164.502(b)** | Minimum necessary | Context scope binding per DEC-32-05 |
| **GDPR Article 5(1)(c)** | Data minimisation | Context scope binding per DEC-32-05 |
| **WHO TRS 996 Annex 5** | Computerised Systems | Computerised system qualification |
| **ISO/IEC 27001** | Information security | AI Gateway secret-store credential governance |
| **ICH Q9 R1** | Quality Risk Management | AI risk classification |
| **ICH E6(R3) GCP adjunct** | GCP for clinical artifacts | Where MIRA touches clinical artifacts |
| **India CDSCO Schedule M (Revised) §16** | Records and Reports | India operations subject to a future jurisdiction-specific legal assessment |
| **India CDSCO NDCT 2019 §27** | Clinical trial documentation | India clinical trial subject to a future jurisdiction-specific legal assessment |

---

## 15. Code Modules

| Code module | Path | Status |
|---|---|---|
| `mira` plugin | `apps/backend/src/mira/plugin.ts` | |
| `mira` routes | `apps/backend/src/mira/routes.ts` | |
| `mira` service | `apps/backend/src/mira/service.ts` | (target service) |
| `mira` schemas | `apps/backend/src/mira/schemas.ts` | |
| `mira` events | `apps/backend/src/mira/events.ts` | target route |
| `ai-gateway` service | `apps/backend/src/ai-gateway/ai-gateway.service.ts` | (5 non-silent outcome classes per DEC-32-04) |
| `ai-gateway` model-qualification engine | `apps/backend/src/ai-gateway/model-qualification-engine.ts` | target route per DEC-32-09 |
| `ai-gateway` prompt-template engine | `apps/backend/src/ai-gateway/prompt-template-engine.ts` | target route per DEC-32-09 |
| `ai-gateway` policy-version engine | `apps/backend/src/ai-gateway/policy-version-engine.ts` | target route per DEC-32-10 |
| `ai-gateway` DLQ handler | `apps/backend/src/ai-gateway/dlq-handler.ts` | target route per DEC-32-12 |
| `ai-gateway` availability monitor | `apps/backend/src/ai-gateway/availability-monitor.ts` | target route per DEC-32-13 |
| `panel` plugin | `apps/backend/src/panel/plugin.ts` | |
| Migration | `apps/backend/src/db/migrations/.` | (per §9.2) |
| Shared types | `packages/shared/src/types/mira.ts` | |
| Shared schemas | `packages/shared/src/schemas/mira.schema.ts` | |
| Frontend hooks | `apps/frontend/src/mira/hooks/useMira.ts` | |
| Frontend chat UI | `apps/frontend/src/mira/MIRAChat.tsx` | (`bypass_ai` control + AI availability banner) |
| Frontend handover task console | `apps/frontend/src/mira/HandoverTaskConsole.tsx` | target route per DEC-32-06 |
| Frontend action registry console | `apps/frontend/src/mira/ActionRegistryConsole.tsx` | target route per DEC-32-02 |
| Frontend AI Gateway health console | `apps/frontend/src/mira/AIGatewayHealthConsole.tsx` | target route per DEC-32-13 |
| Frontend AI governance events console | `apps/frontend/src/mira/AIGovernanceEventsConsole.tsx` | target route per DEC-32-04 |
| Frontend DLQ console | `apps/frontend/src/mira/DLQConsole.tsx` | target route per DEC-32-12 |
| Frontend model qualification console | `apps/frontend/src/mira/ModelQualificationConsole.tsx` | target route per DEC-32-09 |
| Frontend prompt template console | `apps/frontend/src/mira/PromptTemplateConsole.tsx` | target route per DEC-32-09 |
| Frontend policy version console | `apps/frontend/src/mira/PolicyVersionConsole.tsx` | target route per DEC-32-10 |
| Frontend outcome label audit viewer | `apps/frontend/src/mira/OutcomeLabelAuditViewer.tsx` | target route per DEC-32-07 / DEC-32-23 |

---

## 16. Test Cases

### 16.1 Unit tests

- TC-32-U-001: Action class enum 6-value validation per DEC-32-02.
- TC-32-U-002: Direct AI invocation outside AI Gateway rejected with `AI_GATEWAY_CHOKEPOINT_BYPASSED`.
- TC-32-U-003: AI Gateway feature flag off emits `flag_off` event + `AI_GATEWAY_FEATURE_FLAG_OFF` error.
- TC-32-U-004: AI Gateway rate-limit emits `rate_limited` event + `AI_GATEWAY_RATE_LIMITED` error.
- TC-32-U-005: AI Gateway model unqualified emits `model_unqualified` event + `AI_GATEWAY_MODEL_UNQUALIFIED` error.
- TC-32-U-006: AI Gateway policy reject emits `policy_reject` event + `AI_GATEWAY_POLICY_REJECT` error + HITL handover created.
- TC-32-U-007: AI Gateway unavailable emits `unavailable` event + `AI_GATEWAY_UNAVAILABLE` error + manual_continuation offered.
- TC-32-U-008: Context scope missing rejects with `MIRA_CONTEXT_SCOPE_REQUIRED` per DEC-32-05.
- TC-32-U-009: Action class `state_change_request` without HITL handover rejects with `MIRA_ACTION_CLASS_REQUIRES_HITL`.
- TC-32-U-010: Action class `signature_controlled` without bound e-signature rejects with `MIRA_ACTION_CLASS_REQUIRES_E_SIGNATURE`.
- TC-32-U-011: Action class `external_transmission` without URS-13 CR rejects with `MIRA_ACTION_CLASS_REQUIRES_URS13_CR`.
- TC-32-U-012: Handover acceptance without URS-28 qualification rejects with `MIRA_HUMAN_ON_LOOP_QUALIFICATION_GATE_FAILED`.
- TC-32-U-013: Outcome label modification post-write rejects with `MIRA_OUTCOME_LABEL_IMMUTABLE` per DEC-32-07.
- TC-32-U-014: Outcome label missing on downstream artifact rejects with `MIRA_OUTCOME_LABEL_REQUIRED`.
- TC-32-U-015: `bypass_ai = true` without `bypass_reason` rejects with `MIRA_BYPASS_AI_REASON_REQUIRED` per DEC-32-15.
- TC-32-U-016: `bypass_ai = true` results in `outcome_label = ai_unavailable_manual` on downstream artifact.
- TC-32-U-017: Per-message persistence verified per DEC-32-14.
- TC-32-U-018: AI service attempting to advance authoritative workflow rejects with `MIRA_AI_AS_AUTHORITATIVE_PROHIBITED`.
- TC-32-U-019: Reopen without executive AND QP co-sign rejects.

### 16.2 Integration tests

- TC-32-I-001: Read-only action class per Worked Example 1.
- TC-32-I-002: Draft creation with HITL per Worked Example 2.
- TC-32-I-003: State change request per Worked Example 3.
- TC-32-I-004: Signature controlled per Worked Example 4.
- TC-32-I-005: External transmission per Worked Example 5.
- TC-32-I-006: Policy reject per Worked Example 6.
- TC-32-I-007: Rate limited per Worked Example 7.
- TC-32-I-008: Model unqualified per Worked Example 8.
- TC-32-I-009: AI unavailable + bypass_ai per Worked Example 9.
- TC-32-I-010: DLQ stale → URS-21 finding per Worked Example 10.
- TC-32-I-011: Governed reopen per Worked Example 11.
- TC-32-I-012: Outbound provenance to URS-14 complaints — `mira_outcome_label` persists.
- TC-32-I-013: Outbound provenance to URS-15 OOS — `mira_outcome_label` persists.
- TC-32-I-014: Outbound provenance to URS-16 deviations — `mira_outcome_label` persists.
- TC-32-I-015: Outbound provenance to URS-23 batch records — `mira_outcome_label` persists with bound e-signature on signature_controlled.
- TC-32-I-016: URS-28 qualification-gate consumed at handover acceptance per DEC-32-23.
- TC-32-I-017: Cross-tenant `platform_admin` break-glass logged per DEC-32-20.
- TC-32-I-018: AI Gateway availability surface `/api/v1/ai/health` returns operational state.
- TC-32-I-019: AI availability state change → URS-30 notification per DEC-32-13.
- TC-32-I-020: Model qualification GMLP evidence pack required at release per DEC-32-09.

### 16.3 End-to-end tests

- TC-32-E-001: Read-only scenario per Worked Example 1.
- TC-32-E-002: Draft creation scenario per Worked Example 2.
- TC-32-E-003: State change scenario per Worked Example 3.
- TC-32-E-004: Signature controlled scenario per Worked Example 4.
- TC-32-E-005: External transmission scenario per Worked Example 5.
- TC-32-E-006: All 4 non-ok outcome scenarios per Worked Examples 6–9.
- TC-32-E-007: DLQ scenario per Worked Example 10.
- TC-32-E-008: Reopen scenario per Worked Example 11.
- TC-32-E-009: Concurrent MIRA conversations — 500 — NFR-32-07.
- TC-32-E-010: India CDSCO scenarios.

### 16.4 Performance tests

- TC-32-P-001: AI Gateway invocation p95 latency (NFR-32-02).
- TC-32-P-002: Handover task creation p95 latency (NFR-32-03).
- TC-32-P-003: Outcome label emission p95 latency (NFR-32-04).
- TC-32-P-004: AI Gateway availability p95 latency (NFR-32-05).
- TC-32-P-005: Audit-trail append p99 latency (NFR-32-06).
- TC-32-P-006: Bound e-signature p95 latency (NFR-32-10).
- TC-32-P-007: URS-28 qualification-gate p95 latency (NFR-32-11).

### 16.5 Security tests

- TC-32-S-001: Cross-tenant access rejected by RLS.
- TC-32-S-002: Missing RBAC rejected.
- TC-32-S-003: Missing Authority Profile rejected.
- TC-32-S-004: Missing HITL rejected.
- TC-32-S-005: Missing bound e-signature rejected.
- TC-32-S-006: SQL injection rejected.
- TC-32-S-007: Audit-trail UPDATE / DELETE rejected.
- TC-32-S-008: AI service attempting authoritative advancement rejected.
- TC-32-S-009: PII / PHI redaction in logs verified.
- TC-32-S-010: Inline AI provider credentials rejected.
- TC-32-S-011: Direct AI invocation outside Gateway rejected.
- TC-32-S-012: Outcome label tampering detected (immutable post-write).
- TC-32-S-013: Context scope minimum-necessary enforced.

---

## 17. Validation Evidence

### 17.1 URS-32-VAL-001: Requirements traceability matrix

Complete RTM mapping every URS-32 requirement (DEC-32-01.DEC-32-23, BR-32-01.BR-32-21, NFR-32-01.NFR-32-12, SoD-32-01.SoD-32-07, SEC-32-01.SEC-32-15) to test cases (TC-32-U-001.TC-32-U-019, TC-32-I-001.TC-32-I-020, TC-32-E-001.TC-32-E-010, TC-32-P-001.TC-32-P-007, TC-32-S-001.TC-32-S-013) and code modules (§15).

### 17.2 URS-32-VAL-002: Design qualification (DQ)

Architecture, data model, API contract, workflow, business rules, audit trail, security, integration; signed by Validation Head, QA Head, **Information Security Head (Co-Primary Owner)**, **Chief AI Officer / AI-ML Lead (Co-Primary Owner)**, RA Head, Manufacturing Head, Qualified Person Authority, Legal Authority.

### 17.3 URS-32-VAL-003: Installation qualification (IQ)

Migration application + RLS verification + route mount verification + frontend hook resolution + AI Gateway integration + secret-store integration verification.

### 17.4 URS-32-VAL-004: Operational qualification (OQ)

Happy-path execution of every test case with evidence captures.

### 17.5 URS-32-VAL-005: Performance qualification (PQ)

NFR-32-01.NFR-32-12 verification.

### 17.6 URS-32-VAL-006: AI/ML governance evidence

Per ARCH-AI-001 — **the canonical binding module**: (a) all seven AC gates (AC-1..AC-7) bound and validated at runtime; (b) GMLP 10-principle evidence pack for each qualified model; (c) **EU AI Act (Regulation 2024/1689) Annex III + Articles 9–15 internal forward-looking AI governance adoption evidence**; (d) AI Gateway 5-outcome-class non-silent verification; (e) outcome label vocabulary mandatory + immutable verification; (f) URS-28 qualification-gate consumption evidence; (g) outbound provenance integration with all 18 other regulated URS modules verified.

### 17.7 URS-32-VAL-007: Regulatory mapping evidence

FDA 21 CFR Part 11 §§11.10(a)/(d)/(e), 11.50, 11.70, 11.200; EU GMP Annex 11 §§4, 5, 9, 12, 14, 16; Annex 22 Draft 2025 §7; **EU AI Act (Regulation 2024/1689) Annex III + Articles 9, 10, 11, 12, 13, 14, 15** adopted as internal forward-looking AI governance; MHRA Data Integrity (ALCOA+); GAMP 5 Cat 5; FDA CSA September 2025; **GMLP 10 principles**; **HIPAA §164.502(b) + GDPR Art. 5(1)(c)**; WHO TRS 996 Annex 5; ISO/IEC 27001; ICH Q9 R1; ICH E6(R3); India CDSCO Schedule M §16 + NDCT 2019 §27.

### 17.8 URS-32-VAL-008: Migration evidence gate

Per §9.3.

### 17.9 URS-32-VAL-009: Signature manifest

QA Head, RA Head, Validation Head, Manufacturing Head, **Information Security Head (Co-Primary Owner)**, **Chief AI Officer / AI-ML Lead (Co-Primary Owner)**, Qualified Person Authority, Legal Authority, Site Quality Lead, Founder / Chairman & MD per §19.

### 17.10 URS-32-VAL-010: Post-launch periodic-review pack

(a) MIRA metrics (conversations per tenant, message throughput, action class distribution, handover acceptance rate, outcome label distribution); (b) AI Gateway metrics (5-outcome-class distribution, rate-limit utilization, model qualification status); (c) DLQ metrics (item count, disposition rate); (d) bypass_ai utilization; (e) audit-trail integrity; (f) reopen-event audit; (g) cross-tenant break-glass audit; (h) outbound provenance integration verification across all 18 other regulated URS modules; (i) URS-28 qualification-gate compliance; periodic review at quarterly cadence by Information Security Head + Chief AI Officer / AI-ML Lead + QA Head + Validation Head + Qualified Person Authority + Legal Authority.

---

## 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 32. |

---

## 19. Document Approval

| Role | Name | Signature | Date |
|---|---|---|---|
| Founder / Chairman & MD | Vimal | __________ | __________ |
| QA Head | __________ | __________ | __________ |
| RA Head | __________ | __________ | __________ |
| Validation Head | __________ | __________ | __________ |
| Manufacturing Head | __________ | __________ | __________ |
| Information Security Head (Co-Primary Owner) | __________ | __________ | __________ |
| Chief AI Officer / AI-ML Lead (Co-Primary Owner) | __________ | __________ | __________ |
| Legal Authority (AI Act / Data Minimization) | __________ | __________ | __________ |
| Qualified Person Authority | __________ | __________ | __________ |
| Site Quality Lead | __________ | __________ | __________ |

---

## 20. Cross-Module Event Contract

| Event | Emitter | Consumer | Payload key fields |
|---|---|---|---|
| `mira_conversation_created` | Module 32 | URS-30 | `conversation_id`, `tenant_id`, `user_id` |
| `mira_message_persisted` | Module 32 | — | `message_id`, `conversation_id`, `role`, `action_class` |
| `mira_action_classified` | Module 32 | — | `message_id`, `action_class` |
| `mira_handover_task_created` | Module 32 | URS-30 | `handover_task_id`, `action_class` |
| `mira_handover_task_completed` | Module 32 | URS-30 | `handover_task_id`, `accepted_by`, `acceptance_e_signature_id`, `hitl_decision_id` |
| `mira_handover_task_rejected` | Module 32 | URS-30 | `handover_task_id`, `rejection_reason` |
| `mira_handover_task_cancelled` | Module 32 | URS-30 | `handover_task_id` |
| `mira_handover_task_manual_continuation` | Module 32 | URS-30 | `handover_task_id` |
| `mira_outcome_label_assigned` | Module 32 | **All 18 other regulated URS modules per DEC-32-23** | `target_module`, `target_record_id`, `outcome_label` |
| `mira_bypass_ai_invoked` | Module 32 | URS-30 | `target_module`, `target_record_id`, `bypass_reason` |
| `mira_ai_unavailable` | Module 32 | **URS-30 Notifications (primary consumer per DEC-32-13)** | `availability_state`, `affected_features` |
| `mira_policy_rejected` | Module 32 | URS-30 | `message_id`, `policy_version_snapshot` |
| `mira_rate_limited` | Module 32 | URS-30 | `user_id`, `action_class`, `budget_window` |
| `mira_model_unqualified` | Module 32 | URS-30, URS-21 | `model_id`, `qualification_status` |
| `ai_governance_event_emitted` | Module 32 | — | `event_id`, `event_type`, `tenant_id` |
| `mira_event_dlq_persisted` | Module 32 | URS-30 | `dlq_id`, `error_class` |
| `mira_finding_created` | Module 32 | **URS-21 (Findings — primary consumer)**, URS-30 | `finding_id` (URS-21), `severity`, `finding_type`, `source_record_id` |
| `mira_capa_linked` | Module 32 | **URS-18 (CAPA — primary consumer)**, URS-30 | `capa_id`, `linked_by`, `source_type = mira_ai_governance` |
| `mira_program_locked` | Module 32 | URS-30 | `program_lock_id`, `locked_by`, `lock_e_signature_id` |
| `mira_program_reopened` | Module 32 | URS-30, URS-21 (governed-reopen audit) | `program_lock_id`, `reopened_by`, `executive_co_signer`, `qp_co_signer`, `reopen_reason` |

---

## 21. References

- **ARCH-AI-001 — AI Optionality and Manual Continuity (canonical binding architecture; MIRA is the canonical binding module)**
- VRX-SPEC-URS-032-MIRA-AI-Chat-Command-Center-and-Agent-Orchestration.md (Module specification)
- URS-01.URS-31, URS-33.URS-35 (cross-module contracts — every regulated module receives `mira_outcome_label`)
- **FDA 21 CFR Part 11** §§11.10(a)/(d)/(e), 11.50, 11.70, 11.200
- **EU GMP Annex 11** §§4, 5, 9, 12, 14, 16
- EU GMP Annex 22 (Draft 2025) §7 — internal forward-looking control
- **EU AI Act (Regulation 2024/1689) Annex III + Articles 9, 10, 11, 12, 13, 14, 15** — adopted as internal forward-looking AI governance
- **MHRA Data Integrity Guidance (2018)** — ALCOA+
- GAMP 5 Cat 5
- **FDA Computer Software Assurance (CSA) — September 2025 Final Guidance**
- **GMLP (Good Machine Learning Practices) — 10 principles** (FDA / MHRA / Health Canada joint guidance)
- **HIPAA §164.502(b)** — minimum necessary
- **GDPR Article 5(1)(c)** — data minimisation
- **WHO TRS 996 Annex 5** — Computerised Systems
- **ISO/IEC 27001** — information security
- **ICH Q9 R1** — Quality Risk Management
- **ICH E6(R3)** — GCP adjunct
- India CDSCO Schedule M (Revised) §16
- India CDSCO NDCT 2019 §27

---

**END OF VRX-URS-32 — MIRA AI CHAT COMMAND CENTER AND AGENT ORCHESTRATION — VERSION 1.0**