---
type: Axis
title: schema-authority (source-of-truth axis)
description: The schema-authority architecture axis — where the authoritative shape of state lives (code-first → schema-first → contract-first), the framing under the skill's recurring projection-vs-canonical drift. A system-singleton axis whose commitment surface is the interface/wire contract that fixes which node is canonical and which is derived.
tags: [axis, architecture, schema-authority, source-of-truth, projection, rfc-75, deep]
timestamp: 2026-06-18T00:00:00Z
---

# Schema-authority (source-of-truth axis)

> **DEEP axis (5A.2).** Authored to full §6 depth with a worked example from
> the skill's own history — the projection-vs-canonical tension, lived
> continuously across the 4.2/4.3 lines.

## Concept

Schema-authority is the **source-of-truth** axis (RFC #75 §3 / §3.3): which
*node* holds the authoritative shape of state, and which nodes are *derived*
from it. The ladder runs code-first (the in-code model defines the schema) →
schema-first (a declared schema defines it, code conforms) → contract-first (an
independent contract both code and schema conform to). Its **commitment surface
is the interface/wire contract** (§4): once a node is declared canonical and
others derived, every reader must agree on which is which — collapsing the
distinction is exactly the conflation that hides **projection-vs-canonical
drift** (RFC #75 §3.3: the bug class where a derived read-model is read as if
authoritative). Its **scope is system-singleton** (§5).

## Why it is an axis (discriminator test — §2)

1. **Ordered tiers** — each rung moves authority further from the code and makes
   the canonical/derived split more explicit and external.
2. **Cross-cutting bundle** — a rung dictates the regenerator, the migration
   path, every reader's "am I reading the source or a projection?" discipline,
   and the drift detectors.
3. **Asymmetric migration cost** — promoting a derived node to canonical (or
   relocating authority) is a contract break: every consumer must re-point.
4. **Requirement-keyed selection** — falsifiable probes pick the rung.

## Schema view (the §6 entry — validated by `axis_catalog`)

```yaml
id: schema-authority
kind: architecture-axis
scope: system-singleton
selection:
  probes:
    - "Is there exactly one authoritative store, with all other shapes derived from it? → declare it canonical; everything else is a projection."
    - "Do two readers disagree on which copy is the truth? → the canonical/derived split is unstated; you are at code-first by accident."
    - "Must an external party (another service/agent) agree on the shape independently of your code? → contract-first."
    - "Is the persisted shape declared (DDL/migrations) and the code made to conform? → schema-first."
    - "Is a derived view (FTS index, read-model, OKF FS projection) ever WRITTEN to as if it were the source? → integrity violation; re-point at canonical."
composes_with:
  - "projection-vs-canonical drift = schema-authority × temporality (the skill's recurring bug)"
  - "OKF-as-projection = schema-authority applied to representations (DB canonical, FS OKF derived)"
applies_when: []
tiers:
  - tier: code-first
    commitment_delta:
      surface: interface-wire-contract
      delta: "the in-code model is the implicit source of truth; the persisted/wire shape is whatever the code emits. No external party can pin the shape."
    admin_tool: "none — the shape is read off the code."
    enforcement:
      - "one in-code model owns the shape; serializers derive from it, never the reverse."
    tests:
      - "round-trip: serialize then deserialize reproduces the model."
    forecloses: "an independently-agreed shape; every consumer is coupled to the code."
    migration_cost_to_next: "medium — extract a declared schema + make the code conform to it."
  - tier: schema-first
    commitment_delta:
      surface: interface-wire-contract
      delta: "a declared schema (DDL + migrations) is canonical; code conforms. Derived nodes (read-models, indexes, FS projections) are explicitly non-authoritative."
    admin_tool: "schema/migration tool; a regenerator that rebuilds derived nodes from canonical."
    enforcement:
      - "every reader knows whether it reads canonical or a projection (no projection is ever written as source)."
      - "the regenerator derives projections from canonical; it never lets a projection clobber canonical."
    tests:
      - "a derived node rebuilt from canonical matches; reads of a projection that should hit canonical are caught."
    forecloses: "silent code-shape drift; the schema now gates changes."
    migration_cost_to_next: "high — externalize the contract so non-owned parties conform too."
  - tier: contract-first
    commitment_delta:
      surface: interface-wire-contract
      delta: "an independent contract (the shape, versioned) is canonical; both your code and your schema conform to it, as do external parties."
    admin_tool: "contract registry + compatibility checker; contract-vs-implementation conformance gate."
    enforcement:
      - "code and schema both validate against the published contract before ship."
      - "a contract change is a versioned event with a compatibility window."
    tests:
      - "implementation conforms to the published contract; an incompatible contract change is rejected pre-ship."
    forecloses: "unilateral shape changes; the contract is now a coordination point."
    migration_cost_to_next: "n/a — top of the ladder."
examples:
  - "The skill's own climb: the projection-vs-canonical tension lived continuously — the canonical DB is authoritative, FS milestone.txt/state.txt + the swimlane composer + FTS index are DERIVED projections; reading the projection as if canonical was the recurring bug (4.2.0a5 read-canonical-not-projection; check the .db not FS milestone.txt for fresh writes, 4.2.0a10). OKF-as-projection (#818) makes it explicit: DB canonical, OKF FS derived — schema-first today, contract-first if the OKF spec pin becomes the agreed contract."
```

## Selection procedure (§8)

Bidirectional check: de-escalate ("can two readers safely share an implicit
in-code shape?" — rarely, once anything external reads it) and escalate ("does
any consumer need an independently-pinned shape?"). System-singleton: chosen
once. The chosen rung is recorded in the system architecture record (5A.6);
`architecture_drift_gap` later flags a derived node being written as source.

## Composition (§5)

Schema-authority is half of the skill's signature product: **projection-vs-
canonical drift = schema-authority × temporality** — a derived node read as
canonical *and* stamped as if it owned its own genesis. The interaction rule is
authored in 5A.3.
