Durable Facts Architecture¶
Reasoning is replaceable. Facts belong to their authoritative owner.
Companion to Capability Convergence Framework: capability convergence resolves who owns a capability; this standard resolves where durable facts live and who is permitted to compute over them.
Core Principle¶
Every durable engineering fact has exactly one authoritative owner. Reasoning engines never become an additional owner. Their responsibility is to retrieve facts from authoritative systems, compose them, explain them, and prioritize work. They do not calculate deterministic metrics that another system already owns.
Responsibility Boundaries¶
| Layer | Owns | Versioned By |
|---|---|---|
| Engineering Standard | Vocabulary, semantics, invariants, contracts | Git |
| Beads | Categorical facts | Dolt |
| SQL Views | Deterministic computation | Dolt |
| Agents | Consistent classification during execution | Runtime |
| Oracle (reasoning engine) | Interpretation, prioritization, receipts | Git |
Layer Responsibilities¶
Engineering Standard — defines meaning¶
Defines: capability, authority, lifecycle, verification, ownership, invariants, migration rules.
- It SHALL NOT define SQL.
- It SHALL NOT define implementation details.
- It SHALL define the contracts that implementations satisfy.
Beads — records categorical facts¶
capability:documentation
authority:git
lifecycle:transfer
verification:verified
Labels classify. Labels never contain derived metrics.
SQL Views — own deterministic computation¶
Contracts (examples): authority_coverage, consumer_adoption, verification_debt, capability_summary, ownership_delta.
Views are the public contract; they hide implementation. If lifecycle:transfer is later renamed or moved out of labels entirely, only the Beads implementation changes — the SQL contract stays stable and Oracle is unchanged.
Agents — classify work¶
Agents apply the vocabulary consistently (authority:git, verification:pending, lifecycle:transfer). Agents do not calculate metrics.
Oracle (reasoning engine) — explanation only¶
- Oracle SHALL consume only stable view contracts (e.g.
SELECT * FROM authority_coverage;). - Oracle SHALL NOT query implementation tables directly except when diagnosing the Beads implementation itself.
- Oracle owns explanation, prioritization, planning, receipts. Oracle does not own arithmetic.
Migration Completion¶
A migration is complete only when its adoption metric reaches 100%. Deterministic KPIs, not narrative:
- Vocabulary adoption — how many capability records use the canonical vocabulary.
- Authority adoption — how many consumers reference the authoritative owner.
- Consumer adoption — how many implementations consume the canonical interface.
- Verification debt — how many candidate changes remain unverified.
Narrative progress is never completion. Only deterministic adoption metrics determine completion.
Public Contracts & Implementation Independence¶
Oracle consumes only public SQL views. Oracle SHALL NOT depend on label names, table layouts, or schema internals — only view contracts are public; everything else is implementation.
Valid: Engineering Standard → vocabulary + invariants → Beads labels → SQL views → Oracle.
Invalid: Engineering Standard → SQL. The Standard defines requirements; Beads implements them.
Success Criteria (reasoning-engine replaceability)¶
A reasoning engine is replaceable when another engine can (1) read the same view contracts, (2) produce identical metrics, and (3) explain those metrics independently. If changing reasoning engines changes deterministic numbers, the architecture is incorrect. Changing engines should change only the explanation — never the facts.
Canonical Invariant¶
Reasoning is replaceable. Facts belong to their authoritative owner.