A geometric red cardinal weaving twigs into a nest

The Cardinal application

The system of record.

For: developers and reviewers

Everything Cardinal knows lives in one database, and one rule governs how it gets there: data is never written by a raw insert. Every write — agent or human — goes through a stored procedure that checks the actor, makes the write idempotent, and appends a hash-chained audit row. This page is that contract, and the families of records it protects.

One write-path Append-only audit spine Read base tables, write via procedures

🔑 The golden rule 🗂️ The record families 🏷️ Status vocabularies ⚖️ The audit spine

The golden write-path rule

To read, you query a base table. To write, you call a stored procedure — never an insert or update directly. Each procedure enforces four things, in order, every time.

flowchart LR
  CALL(["✍️ A write
agent · human · system"]):::input

  G1{{"1 · Right actor?
role + RLS check"}}:::gate
  G2{{"2 · Idempotent?
operation_id dedupe"}}:::gate
  G3{{"3 · Apply"}}:::gate

  WRITE[("📊 base table")]:::db
  AUDIT[("🔗 hash-chained
audit row")]:::chain

  REJ[/"❌ rejected"/]:::bad
  SKIP[/"⏭ return prior result"/]:::skip

  CALL ==> G1
  G1 == ✅ ==> G2
  G1 -- ❌ --> REJ
  G2 == ✅ first time ==> G3
  G2 -- ⏭ replay --> SKIP
  G3 ==> WRITE
  G3 ==> AUDIT

  classDef input fill:#fce4ec,stroke:#b11f4b,stroke-width:2.5px,color:#7a1132
  classDef gate fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#78350f
  classDef db fill:#f1f5f9,stroke:#475569,stroke-width:2px,color:#0f172a
  classDef chain fill:#1f2937,stroke:#111827,stroke-width:2.5px,color:#f9fafb
  classDef bad fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#7f1d1d
  classDef skip fill:#e2e8f0,stroke:#64748b,stroke-width:2px,color:#1e293b

Why a procedure, not an insert

A raw insert could skip the actor check, double-apply on a retry, or land without an audit row. Routing every write through a procedure makes those mistakes impossible by construction.

Agents write through a shim

Agents write by inserting into a thin "in" view whose trigger calls the procedure. Humans hit the same procedures through the API. Both end up on the identical, audited path.

The record families

The schema groups into a handful of families. (Exact table counts are an implementation detail and drift over time; this site describes the model, not a fixed inventory.)

Engagement artifacts

Decisions, ADRs, risks/issues/blockers, workstreams, conversations, documents, notes, and recognitions — the substance of the engagement.

Reports & briefs

The generated reports and the twice-daily 5-3-2-1 brief, with their publication and export records.

The conversation substrate

Conversations, communications, and the classifier and embedding records that group inbound messages into threads.

The publishing substrate

Publications, their per-target delivery rows, and the acknowledgements that come back.

Cost & governance

Cost telemetry, configuration and budgets, and the various operational state tables.

The audit spine

The hash-chained ledger, its payloads, the role snapshots and rotation log, and the leases.

Conversation is a first-class backbone. Conversation is now a fully implemented record family, not a proposal. Every inbound item — an email reply, a Teams message, a meeting — is grouped into a conversation thread, so related signals hang together instead of scattering across the schema. Grouping runs in two stages: a deterministic pass links the obvious matches (an exact reply-to, a known thread, a meeting series), and a retrieval-first classifier resolves the rest — auto-linking when it is confident, suggesting when it is unsure, and opening a new conversation when nothing fits. Embeddings over each conversation's summary power that retrieval.

Status vocabularies

Several record types move through a defined lifecycle. The exact state names are validated against the database; the shapes below are the ones a reader meets most often.

Decisions

Move from proposed, through accepted/decided, to ratified or resolved — or are superseded or rejected.

ADRs

Move through draft → reviewed → compliance-checked → ratified before they are settled.

Publications

Move from pending approval, through queued and in-flight, to sent — or failed, superseded, or withdrawn.

Sensitivity

Documents carry a label from general through internal and confidential to regulated — gating who may read the body.

The audit spine

The heart of the model is an append-only ledger where each row is hash-linked to the one before it. It is never updated or deleted; corrections are new rows. A verification routine walks the chain and returns OK only if every link holds — so tampering is detectable, not merely discouraged. The Steward runs that verification continuously.

Verify it yourself. The strongest thing a reviewer can do is not trust a claim but follow the chain — from a signal, to the brief that mentioned it, to the decision it became, to the outbound it produced — and confirm it all reconciles.

See the write-path in the end-to-end flow → · The guarantees it underpins →