M9 — Audit · Compliance · Guardrails

1. 📌 Overview & Purpose

2. 🛡️ 5 Guardrail Layers

3. ✅ Functional Requirements

4. ⚙️ Non-Functional Requirements

5. 🗄️ Data Model

5a. Audit Log (PostgreSQL · partitioned monthly)

CREATE TABLE audit_log (
  id              BIGSERIAL,
  ts              TIMESTAMPTZ DEFAULT now(),
  request_id      UUID,                    -- correlates across spans
  tenant_id       UUID NOT NULL,
  user_id         UUID,                    -- staff (null for patient/system)
  patient_id      UUID,                    -- subject (null for non-patient ops)
  agent_id        VARCHAR(20),             -- M1, M4, M5, M7, M9, system
  action          VARCHAR(80) NOT NULL,    -- e.g. "rx.create", "soap.sign_off"
  resource_type   VARCHAR(40),             -- e.g. "prescription", "encounter"
  resource_id     VARCHAR(80),
  before_state    JSONB,                   -- mutation diff
  after_state     JSONB,
  metadata        JSONB,                   -- agent metadata, citations, confidence
  ip_address      INET,
  user_agent      TEXT,
  geo_country     CHAR(2),
  outcome         VARCHAR(20),             -- success, blocked, failed
  PRIMARY KEY (id, ts)
) PARTITION BY RANGE (ts);

-- monthly partitions auto-create
CREATE INDEX idx_audit_ts ON audit_log (ts DESC);
CREATE INDEX idx_audit_user_ts ON audit_log (user_id, ts DESC);
CREATE INDEX idx_audit_patient_ts ON audit_log (patient_id, ts DESC);
CREATE INDEX idx_audit_action ON audit_log (action, ts DESC);
CREATE INDEX idx_audit_tenant_ts ON audit_log (tenant_id, ts DESC);

5b. Other Tables

6. 🔌 API + Middleware

6a. Audit Query API

GET    /api/v1/audit/logs
       Query: from, to, user_id, patient_id, action, agent_id, tenant_id, limit, cursor
       Returns: paginated audit entries · super_admin/clinic_admin only

GET    /api/v1/audit/logs/{id}
       Detail single entry

GET    /api/v1/audit/timeline/patient/{patient_id}
       Patient lifecycle view (intake → encounter → RX → adverse → discharge)

GET    /api/v1/audit/timeline/staff/{user_id}
       Staff activity audit (today/week/month)

GET    /api/v1/audit/incidents
       Security/safety incidents only · severity filter

6b. HITL API

POST   /api/v1/hitl/request
       Body: { agent_id, proposed_action, context, requires_role, expires_in_sec }
       Returns: { hitl_id, expires_at }

GET    /api/v1/hitl/pending                 # for current user role
POST   /api/v1/hitl/{id}/respond
       Body: { decision: "approved|rejected|modified", reason, modified_action? }

GET    /api/v1/hitl/{id}/wait
       Long-poll for agent · returns when responded or timeout

6c. Feature Flag API

GET    /api/v1/flags                          # all flags for current tenant
GET    /api/v1/flags/{flag_key}               # specific
PUT    /api/v1/flags/{flag_key}               # toggle (admin only)
       Body: { enabled, reason }
       → triggers audit log + Redis cache invalidate

6d. PDPA / DSAR API

POST   /api/v1/pdpa/dsar                       # patient initiates request
       Body: { request_type: "access|export|delete", justification }
GET    /api/v1/pdpa/dsar/{id}                  # status check
GET    /api/v1/pdpa/dsar/{id}/export           # download FHIR Bundle ZIP
DELETE /api/v1/pdpa/data/{patient_id}          # cascade soft-delete (admin only)
POST   /api/v1/pdpa/breach                     # internal breach declaration
       → triggers MOH/PDP notification workflow

6e. Middleware (Laravel + Python)

Laravel:
  app/Http/Middleware/PIIStrip.php          (request body sanitise)
  app/Http/Middleware/AuditWriter.php       (response wrap · log async)
  app/Http/Middleware/RBACEnforcer.php      (route gate · per-tenant)
  app/Http/Middleware/FeatureFlagGate.php   (route enable check)
  app/Http/Middleware/RateLimiter.php       (per-user · per-endpoint)

Python (agents/medieco/guardrails/):
  pii_filter.py         (regex + NER · 50ms target)
  citation_enforcer.py  (LLM response validator · retry logic)
  hitl_gate.py          (decorator @requires_approval)
  block_list.py         (clinical safety gate)
  audit_emitter.py      (structured event → Redis stream)

7. 🎚️ Feature Flags Catalog

Default OFF untuk semua clinical AI features. Owner enable bila ready.

8. 📜 Audit Event Schema

Standard Event Format

{
  "ts": "2026-05-26T10:45:23.412Z",
  "request_id": "req_abc123def456",
  "tenant_id": "klinik_pilot_001",
  "user_id": "doctor_007",
  "patient_id": "patient_2026-001245",
  "agent_id": "M4",
  "action": "rx.create",
  "resource_type": "prescription",
  "resource_id": "rx_xyz789",
  "before_state": null,
  "after_state": {
    "items": [{ "drug_code": "AMX500", "dose": "500mg PO TDS x 5/7" }],
    "ai_suggested": true,
    "doctor_modified": false
  },
  "metadata": {
    "model_used": "llama-3.1-70b-q5",
    "tokens_total": 845,
    "latency_ms": 312,
    "citations": ["MOH CPG URTI 2019"],
    "confidence": 0.84,
    "hitl_id": "hitl_pqr",
    "approved_at": "2026-05-26T10:45:18.123Z",
    "approver_id": "doctor_007"
  },
  "ip_address": "10.0.1.45",
  "user_agent": "Mozilla/5.0...",
  "geo_country": "MY",
  "outcome": "success"
}

Common Action Types

auth.login                           consent.granted          rx.create
auth.logout                          consent.withdrawn        rx.sign
auth.failed                          patient.create            rx.dispense
auth.locked                          patient.update            rx.cancel
encounter.create                     patient.access            order.create
encounter.brief_received             patient.delete            order.send
encounter.scribe_start               patient.export (DSAR)     ddi.block
encounter.scribe_stop                                          allergy.alert
encounter.soap_draft                 audit.query               feature_flag.toggle
encounter.soap_edit                  hitl.request              hitl.approve
encounter.sign_off                   hitl.reject               hitl.timeout
referral.create                      pii.strip                 citation.miss (refused)
billing.claim_submit                 pii.detok                 incident.detected
billing.einvoice_submit              breach.declared           safety_block.refused

9. 🎨 UI / Dashboards

10. ✔️ Acceptance Criteria

• AC-9.1: 100% clinical actions audited (test: 50 sample actions traced end-to-end)
• AC-9.2: PII strip detect 95%+ of 12 PII types in 100 sample messages (regex + NER)
• AC-9.3: Citation enforcer rejects LLM responses without citation in 100% test cases
• AC-9.4: HITL gate blocks 30 jailbreak attempts (auto-RX · auto-order) → 0 success
• AC-9.5: Audit log query 30-day window returns <2s for typical patient
• AC-9.6: Feature flag toggle reflects in <5s across all instances (cache invalidate)
• AC-9.7: DSAR export generates valid FHIR Bundle for sample patient · machine-parseable
• AC-9.8: Right-to-erasure soft-deletes patient data · audit retain · cross-table cascade tested
• AC-9.9: Breach simulation (cross-tenant access attempt) → alert <30s · account auto-lock
• AC-9.10: Audit log immutability — attempt UPDATE/DELETE returns DB-level error
• AC-9.11: Q5 PDPA self-audit pass · DPO sign-off documented
• AC-9.12: All other modules (M1, M4, M5, M7) pass through M9 middleware in test suite

11. 🧪 Test Plan

12. 🔗 Dependencies & Integration

• Hard: NONE — M9 first to build (Sprint 1.1)
• External: Vault (Hashicorp) atau equivalent for PII token store · PostgreSQL 16 · Redis 7 · Loki/Grafana stack
• Library reuse: Laravel Sanctum · Spatie Permissions · Laravel Audit package as base · custom extensions
• Downstream consumers: M1, M4, M5, M7 — semua import M9 middleware/decorators
• Compliance reference: PDPA 2010 · MOH CPG library · MMC scope of practice docs

13. 🏃 Sprint Allocation

14. ⚠️ Module-Specific Risks