Healthcare Core

Healthcare Core

Shared model for the healthcare cluster. The privacy, EMR, CDSS, and eval spokes all depend on these interlocking concepts — keep them consistent here so no spoke contradicts another.

1. The data-protection contract (this cluster's defining model)

Every healthcare app turns on one three-layer contract. Treat data as protected by default:

Classify (what is sensitive) ──> Access-control (who may see it) ──> Audit (who did see it)

• Classify — PHI is anything that identifies a patient and relates to health (name, DOB, address, national ID, MRN, diagnosis, meds, labs, imaging, claims, admissions). PII is non-patient sensitive data (staff details, doctor payouts, salaries, vendor payments). Tag PHI/PII columns at the schema level. → healthcare-phi-compliance
• Access-control — Row-Level Security scoped to facility/role; the anon/publishable key on the client, never service_role; minimum-necessary slice only. → healthcare-phi-compliance
• Audit — every PHI create/read/update/delete/print/export is logged to an insert-only, tamper-proof trail (no update, no delete). → healthcare-phi-compliance

Rule: grant the narrowest access that works; prefer opaque UUIDs over names/MRNs/IDs; treat any new data path (vendor, LLM, analytics, export) as a privacy change worth stating.

2. The patient-safety bias (defaults fail safe)

Clinical software is patient-safety critical, so the safe default is block, not pass:

• A critical drug interaction blocks prescribing; the clinician must document an override reason (stored in the audit trail). → healthcare-cdss-patterns, healthcare-emr-patterns
• A mg/kg dose with missing weight returns invalid — it never silently passes.
• Critical alerts are non-dismissable modals, never toasts; abnormal values are always flagged.
• Signed encounters are locked — corrections are addenda (linked records), never edits.

3. Alert-severity matrix (shared by CDSS and EMR)

CDSS produces these; the EMR renders them; the eval harness asserts they never regress.

4. The deploy-gate thresholds (shared by eval + CI)

Five eval categories, two tiers. A single CRITICAL failure blocks the deploy.

CRITICAL suites run with --bail; never lower a CRITICAL threshold to get green. → healthcare-eval-harness

5. Jurisdiction / standards matrix

6. Conventions

• CDSS is a pure, side-effect-free function library — input clinical data, output alerts; fully testable, no any types, errors surface loudly (never silently caught).
• Interaction pairs are bidirectional (A↔B) and live in a maintainable data structure, not hardcoded inline.
• Test runner is illustrative (examples use Jest); thresholds and categories are framework-agnostic (Vitest, pytest, PHPUnit all fine).

7. Shared guardrails

• Protect-by-default: classify → restrict → audit; minimum-necessary; opaque UUIDs.
• No PHI in logs, error strings, URLs, browser storage, screenshots, or LLM prompts.
• Fail safe: critical alert blocks; missing weight blocks; signed encounter locks.
• Critical clinical alerts are non-dismissable — never toasts; override reasons are audited.
• Third-party SaaS / LLM / observability vendors are blocked-by-default until the data boundary (and a BAA, under HIPAA) is established.
• A single CRITICAL eval failure blocks the deploy; don't weaken the gate.