Design invariants

Executive summary

Eight rules decide every architectural trade-off in Faurenis, and each is enforced by code, a database constraint or a CI gate rather than by convention. Behind them sit numbered clinical invariants — for artifacts, tenant isolation, recovery, Scribe, Perio, evidence and voice — that a change must not regress. A regression against any of them stops a pull request, regardless of what else it delivers.

The eight laws

1
Law
The clinician decides. Generation is never review; only an authenticated clinician action moves an AI draft into the record.
Enforced by
Artifact lifecycle service owns every state transition (ART-01–03); acceptance gates on Scribe and Perio
2
Law
Deterministic where an algorithm exists. Staging, grading, indices, fees and scheduling rules are code, not model output.
Enforced by
Perio staging in shared/services/perio; treatment-plan rules; documents fill numbers, codes and dates from deterministic slots
3
Law
Tenant isolation lives in the database kernel. Application filters are a second line, not the first.
Enforced by
FORCE ROW LEVEL SECURITY keyed on a transaction-local clinic id; RLS-coverage lint; adversarial cross-tenant suite in CI
4
Law
Every AI output is attributable. Model, prompt version, consent, cost and hashes are recorded per call; claims link to the passages that support them.
Enforced by
ai_decision_log with an outbox; provenance outbox with reconciliation; immutable evidence snapshots
5
Law
Fail closed on the unknown. Missing consent, an unapproved region, an unregistered model, a stale model release or an ambiguous patient binding is a refusal, not a guess.
Enforced by
Consent policy, residency validator at boot, model-registry load guards, imaging release verifier, recovery binding rules
6
Law
History is append-only. Locked content is corrected by successor, never mutated; the audit trail is hash-chained.
Enforced by
Supersession and amendment chains; database triggers refusing UPDATE and DELETE on the audit trail; scheduled chain verification
7
Law
Schema changes are forward-only. Rollback means redeploying an older build against an expanded schema, never running down-SQL.
Enforced by
Migration v2 ledger with phase declarations; destructive-change approval preflight; weekly restore drill
8
Law
Data stays in the EU. Processing happens only in approved EU regions, and the service refuses to start otherwise.
Enforced by
Approved-region allow-list; production residency validation that exits the container on boot

#	Law	Enforced by
1	The clinician decides. Generation is never review; only an authenticated clinician action moves an AI draft into the record.	Artifact lifecycle service owns every state transition (ART-01–03); acceptance gates on Scribe and Perio
2	Deterministic where an algorithm exists. Staging, grading, indices, fees and scheduling rules are code, not model output.	Perio staging in `shared/services/perio`; treatment-plan rules; documents fill numbers, codes and dates from deterministic slots
3	Tenant isolation lives in the database kernel. Application filters are a second line, not the first.	`FORCE ROW LEVEL SECURITY` keyed on a transaction-local clinic id; RLS-coverage lint; adversarial cross-tenant suite in CI
4	Every AI output is attributable. Model, prompt version, consent, cost and hashes are recorded per call; claims link to the passages that support them.	`ai_decision_log` with an outbox; provenance outbox with reconciliation; immutable evidence snapshots
5	Fail closed on the unknown. Missing consent, an unapproved region, an unregistered model, a stale model release or an ambiguous patient binding is a refusal, not a guess.	Consent policy, residency validator at boot, model-registry load guards, imaging release verifier, recovery binding rules
6	History is append-only. Locked content is corrected by successor, never mutated; the audit trail is hash-chained.	Supersession and amendment chains; database triggers refusing UPDATE and DELETE on the audit trail; scheduled chain verification
7	Schema changes are forward-only. Rollback means redeploying an older build against an expanded schema, never running down-SQL.	Migration v2 ledger with phase declarations; destructive-change approval preflight; weekly restore drill
8	Data stays in the EU. Processing happens only in approved EU regions, and the service refuses to start otherwise.	Approved-region allow-list; production residency validation that exits the container on boot

Clinical invariant families

The laws are expanded into numbered, testable invariants in docs/clinical-invariants/. Each row names the rule, the code that owns it and the test that proves it. They are binding on every change to orchestration, Scribe, Perio, Copilot clinical context, review, recovery, audio ownership, artifacts, facts, provenance or tenant joins.

ART-01…12
Scope
Artifacts, facts, provenance, review
Representative rule
Machine-derived facts are born proposed; audited clinician confirmation is the only route into the confirmed record.
TENANT-01…12
Scope
Tenant and patient isolation
Representative rule
Clinic id is derived from authenticated server context, never from request data; patient, encounter, session, artifact and fact ids are ownership-checked jointly.
REC-01…12
Scope
Recovery, offline work, version skew
Representative rule
Server state is authoritative whenever the server can answer; ambiguous patient binding produces a blocking screen, never a guessed merge.
SCRIBE-01…10
Scope
Capture and documentation
Representative rule
Structuring never fabricates missing content; finalize is idempotent; a locked note is corrected only by additive amendment.
PERIO-01…
Scope
Voice periodontal charting
Representative rule
A voice result updates the chart only after deterministic parsing and live clinical validation; a negated finding never satisfies a positive rule.
EVID-01…
Scope
Evidence grounding
Representative rule
AI-generated content never counts as evidence for itself; each response resolves to exactly one immutable evidence snapshot.
VOUT-01…
Scope
Spoken output vs. capture
Representative rule
Spoken output yields to clinical capture and stops mid-sentence the moment a capture claims the microphone.
PM-01…08
Scope
Patient Mode
Representative rule
Containment binds an artifact and a version, not a patient; every disclosure is recorded as evidence or it does not happen.

Family	Scope	Representative rule
ART-01…12	Artifacts, facts, provenance, review	Machine-derived facts are born `proposed`; audited clinician confirmation is the only route into the confirmed record.
TENANT-01…12	Tenant and patient isolation	Clinic id is derived from authenticated server context, never from request data; patient, encounter, session, artifact and fact ids are ownership-checked jointly.
REC-01…12	Recovery, offline work, version skew	Server state is authoritative whenever the server can answer; ambiguous patient binding produces a blocking screen, never a guessed merge.
SCRIBE-01…10	Capture and documentation	Structuring never fabricates missing content; finalize is idempotent; a locked note is corrected only by additive amendment.
PERIO-01…	Voice periodontal charting	A voice result updates the chart only after deterministic parsing and live clinical validation; a negated finding never satisfies a positive rule.
EVID-01…	Evidence grounding	AI-generated content never counts as evidence for itself; each response resolves to exactly one immutable evidence snapshot.
VOUT-01…	Spoken output vs. capture	Spoken output yields to clinical capture and stops mid-sentence the moment a capture claims the microphone.
PM-01…08	Patient Mode	Containment binds an artifact and a version, not a patient; every disclosure is recorded as evidence or it does not happen.

Architecture decision records

Structural decisions are recorded as ADRs in docs/adr/. Several of them are release gates in their own right: ADR 0014 makes generated architecture manifests (the route-protocol manifest among them) a build-blocking check, so the documentation of the HTTP surface cannot drift from the code.

0003
Decision
One clinical encounter is the parent of every capability session in a visit
0009 · 0012
Decision
Forward-only migrations; expand → migrate → verify → switch → contract
0010
Decision
Stay a modular monolith; no network services for in-process domains
0013
Decision
Application rollback by artifact redeploy; database restore is disaster recovery only
0014
Decision
Architecture manifests are release gates
0017
Decision
Operatory state has exactly one owner per row
0005 · 0006
Decision
Clinical and research data are physically separated; imaging models ship only as signed, approved releases
0026 · 0027
Decision
One Faurenis voice and one microphone across the whole application

ADR	Decision
0003	One clinical encounter is the parent of every capability session in a visit
0009 · 0012	Forward-only migrations; expand → migrate → verify → switch → contract
0010	Stay a modular monolith; no network services for in-process domains
0013	Application rollback by artifact redeploy; database restore is disaster recovery only
0014	Architecture manifests are release gates
0017	Operatory state has exactly one owner per row
0005 · 0006	Clinical and research data are physically separated; imaging models ship only as signed, approved releases
0026 · 0027	One Faurenis voice and one microphone across the whole application

How changes are made

Code reaches production through a fixed pipeline shared by every contributor, human or agent (docs/pipeline/core.md): plan, implement with tests, a focused safety audit, commit, pull request, independent AI code review against the pipeline and the clinical invariants, full CI, then merge. A push after review voids the review. Merging with a red check, force-pushing a shared branch and administrator merges are prohibited.

SOURCE OF TRUTH

docs/clinical-invariants/
docs/adr/
docs/pipeline/core.md
AGENTS.md