Decision Log (ADRs)¶
This directory holds Cairn's Architecture Decision Records. Each ADR captures why a decision was made — the context, the choice, and its consequences. Aspect documents in ../ describe what the architecture is; ADRs explain why it is that way.
Rules¶
- Append-only and immutable. An ADR is never edited to reverse it. To change a decision, write
a new ADR that supersedes the old one; mark the old one
Status: Superseded by ADR-NNNNand the new oneSupersedes: ADR-NNNN. This is the project's own "never erase, always overlay" (identity §5.1) applied to its documentation. (Typo/clarity fixes that don't change meaning are fine.) - Numbered and dated.
NNNN-short-slug.md, zero-padded, allocated in order. - Read before reopening. Before reopening a settled question, read its ADR — the rationale is there on purpose.
- The spec carries no in-file changelogs; git is the line history and ADRs are the rationale.
Index¶
| ADR | Title | Status | Date |
|---|---|---|---|
| 0000 | Pre-ADR changelog history (spec v0.1 → v0.6) | Imported (historical) | 2026-06-13 |
| 0001 | Postgres-intelligence cluster: fat Postgres, thin Rust daemon | Accepted | 2026-06-13 |
| 0002 | In-database Rust (pgrx) as the projection escape hatch | Accepted (refines 0001) | 2026-06-14 |
| 0003 | Bitemporal event time and acknowledged uncertainty | Accepted | 2026-06-14 |
| 0004 | Dynamic sync scope: a prefetch hint, not an authority | Accepted | 2026-06-14 |
| 0005 | Erasure as key-custody redistribution: crypto-shredding and a policy-neutral severity ladder | Accepted | 2026-06-14 |
| 0006 | Visibility-scope vs. sync-scope: replication is not the confidentiality boundary; the safety projection and graded sensitivity | Accepted | 2026-06-14 |
| 0007 | Authorship is compositional; accountability is separable | Accepted | 2026-06-15 |
| 0008 | Point-of-care identity: possession binding, fast authentication, and work-salvage | Accepted | 2026-06-15 |
| 0009 | The notification economy: unbundling priority, responsibility-routing, and the acknowledgment floor | Accepted | 2026-06-15 |
| 0010 | Additive-vs-suppressing classification: structural derivation, the demotion boundary, and automation-complacency detection | Accepted (refines 0007) | 2026-06-15 |
| 0011 | The actor registry: version-pinned immutable identity, behavioral-configuration granularity, and key custody | Accepted (refines 0007) | 2026-06-15 |
| 0012 | Schema evolution, event-format migration across the offline fleet, and legibility across time | Accepted | 2026-06-15 |
| 0013 | Attachments: content-addressed blobs, the lazy byte tier, and reference-eager replication | Accepted | 2026-06-15 |
| 0014 | Locale-pluggable matcher comparators: content-addressed profiles that travel with the data | Accepted | 2026-06-16 |
| 0015 | Event serialization, signatures, and content addressing: tagged, migratable primitives over three structural moves | Accepted | 2026-06-16 |
| 0016 | National-scale record discovery: the replicated essential-state tier and federation admission | Accepted | 2026-06-16 |
| 0017 | Federation admission: the sovereignty floor, mutual peering, pluggable trust anchors, and the custodian contract | Accepted | 2026-06-16 |
| 0018 | Federation revocation: counterparty enforcement, cascade, and the anchor as a position of power | Accepted (refines 0017) | 2026-06-16 |
| 0019 | Author-scoped record export: the clinician's medico-legal copy | Accepted (refines 0007) | 2026-06-16 |
| 0020 | The active-write model: thin encounters, type-through authoring, and the delete-vs-erase distinction | Accepted | 2026-06-17 |
| 0021 | Layering, the node API, and UI pluralism: uniform core, plural edges | Accepted | 2026-06-17 |
| 0022 | The validated submit surface: the node's write path | Accepted (refines 0021) | 2026-06-17 |
| 0023 | The native API contract: capability description and executable conformance | Accepted (refines 0021) | 2026-06-17 |
| 0024 | Hard policy expression: the policy-assertion stream and the effective-policy projection | Accepted (refines 0021) | 2026-06-17 |
| 0025 | ICD-11 as the canonical classification interlingua and the local-terminology overlay | Accepted | 2026-06-19 |
| 0026 | Node durability and disaster recovery: backup-as-cold-peer, new-identity restore, and shred-aware backups | Accepted (refines 0005) | 2026-06-20 |
| 0027 | Trusted-time anchoring: the clock-confidence grade, the bracketed t_recorded, and the pluggable multi-anchor |
Accepted (refines 0003) | 2026-06-20 |
| 0028 | The finalized closed contributor-role enum | Accepted (refines 0007) | 2026-06-20 |
| 0029 | Skill-epoch (and served-model digest) as a pinned determinant of an agent actor's identity | Accepted (refines 0011) | 2026-06-21 |
| 0030 | The advisory-actor integration contract: L2/L3 attachment and authorship through the in-DB floor | Accepted (refines 0021) | 2026-06-21 |
| 0031 | Canonical identifiers and node-local surrogate keys: the dual-identifier discipline | Accepted (refines 0021) | 2026-06-22 |
| 0032 | Culture-neutral address representation: the three-facet address value | Accepted (refines 0014) | 2026-06-27 |
| 0033 | Patient-identifier representation: namespace/profile split and the matching-survivable normalized form | Accepted (refines 0014) | 2026-06-27 |
| 0034 | The demographic legibility twin: every demographic assertion stays human-readable without its profile | Accepted (refines 0012) | 2026-06-27 |
| 0035 | Entities, relationships, and the provider-number relational model | Accepted (refines 0033, 0014) | 2026-06-27 |
| 0036 | Demographic name display: recency-first within the legal tier | Accepted (refines §4.2, 0014) | 2026-06-28 |
| 0037 | Administrative-sex provenance-first + per-field winner-policy selector; karyotype = distinct field | Accepted (refines §4.2, 0036, 0014) | 2026-06-28 |
| 0038 | Demographic address display: per-use recency-first (volatile field; follows 0036) | Accepted (refines §4.3, 0032, follows 0036) | 2026-06-28 |
| 0039 | Globalise the authored legibility twin; honest-degradation floor for non-demographic types | Accepted (refines 0012, 0034) | 2026-06-28 |
| 0040 | Signing-context domain separation (content-type + external_aad); one signature per event, co-signing by overlay | Accepted (refines 0015, 0007, 0030) | 2026-07-02 |
| 0041 | The progress-note narrative format: one signed event, markdown narrative, manifest-keyed media anchors | Accepted (refines 0012, 0013, 0020, 0039) | 2026-07-04 |
| 0042 | The concrete attachment-reference shape (Attachment / Rendition / SealRef) | Accepted (refines 0013) | 2026-07-08 |
| 0043 | Suppression is self-only (human-authored content); disagreement is additive; agent advisories dismissable | Accepted (refines 0010, 0022) | 2026-07-09 |
| 0044 | Enroll fails closed on actor_id collision; human actors carry a person-distinguishing determinant |
Accepted (refines 0011, 0029) | 2026-07-09 |
| 0045 | Collation-independent projection winner tiebreaks | Accepted (refines principle 1; relates to 0031, #115) | 2026-07-10 |
| 0046 | Enroll fails closed on key→actor dual mapping (the B-direction whole-history guard) | Accepted (refines 0044, 0011) | 2026-07-12 |
| 0047 | Medication reconciliation is a link, not a cessation; symmetric collapse; latest-effective group status | Accepted (refines principle 2, 0010) | 2026-07-13 |
| 0048 | The per-type twin/floor-check registry: one stable dispatcher, register-by-row, unified check-fn signature | Accepted (refines 0039/0022) | 2026-07-13 |
| 0049 | Commitment-based sign-off currency: separable per-thread attestation overlay; staleness by set-commitment compare; supersede, never retract | Accepted (refines 0007, principle 10) | 2026-07-14 |
| 0050 | Dose correction is a per-field patch: explicit strike, corrected effective drives the winner | Accepted (refines principle 4, §3.6) | 2026-07-15 |
| 0051 | Contributor-role vocabulary floor: recorded ratified (12th member, contributory); responsibility = {held_by, on_behalf_of?} object; future members partition-prefixed; strict-submit/lenient-apply |
Accepted (refines 0028/0007/0049/0012) | 2026-07-16 |
| 0052 | Born-sealed clinical bodies: erasability as the shipped default; erasable vs. sequestered; seal-then-sign container + twin-under-seal; the event_dek/event_clear/erasure_shred_log custody plane; strict-submit refuses unsealed clinical.* |
Accepted (refines 0005/0006/0026/0048/0051) | 2026-07-17 |
| 0053 | Per-write human authorship: authoring signature + authorship binding + authorship-confidence grade | Accepted (refines 0008/0007/0051/0052/0012) | 2026-07-18 |
| 0054 | Actor-registry federation: admit-and-dispute; signed actor-event wire shape on the node plane; derived live-bindings disputed state — content never waits, permissions always wait; adjudication = supersede by human ceremony | Accepted (refines 0011/0044/0046) | 2026-07-19 |
| 0055 | Distribution trust root: channels with the steward as default anchor; chained threshold-capable root document (N=1 first-class, no expiry); root/release role split; fork-freeze; transparency by ADR-0027 reuse; one root shape for §7.6/§7.9/§7.7 | Accepted (refines 0012/0024; applies 0017/0018) | 2026-07-20 |
| 0056 | Unknown event types are admitted uninterpreted: custody total, interpretation deferred, power earned; strict door still fail-closes; refusal + durable re-offer kept as the residual contract | Accepted (refines 0012/0022; extends 0054; upholds 0010/0051) | 2026-07-20 |
| 0057 | Generic reprojection: a projection lives only in its registered apply function; healing is generic replay run by the loader on generation change; heal/rebuild semantics; the cairn_replay_eligible #266 seam |
Accepted (refines 0048/0045; upholds 0056 decision 4) | 2026-07-21 |
| 0058 | Grade-gated t_effective ceiling: the born clock-confidence grade bounds the ceiling's rejecting power; flag-never-reject at self-asserted/unknown; remote door never rejects on the ceiling; ADR-0027 §6 upper = RTC corrected to RTC + W(grade) |
Accepted (refines 0003/0027) | 2026-07-22 |
| 0059 | Medication drug-identity coding: anchor on drugref's immortal moiety_uuid (INN is display, never key); structured substance.coding {system, code, display} replacing the reserved inn_code slot; separately-authored inline-or-overlay coding act; advisory + honest-degrading — drugref-absent nodes still read/sync/reconcile, and the §5.9 safety class is captured pre-seal on the coding node and carried, never re-derived by the reader — the drug-axis companion to ADR-0025 |
Accepted (refines 0025/0047; applies 0007/0014/0052/0057) | 2026-07-25 |
Template¶
# ADR-NNNN — <title>
- **Status:** Proposed | Accepted | Superseded by ADR-NNNN
- **Date:** YYYY-MM-DD
- **Supersedes:** ADR-NNNN (if any)
## Context
<the forces at play: the problem, constraints, and what made this a real decision.>
## Decision
<the choice, stated plainly.>
## Consequences
<what becomes easier, what becomes harder, what we are now betting on, and how we'd know if the
bet fails.>