# Canonics — Specification

*(formerly the Canon–Epoch Framework, CEF)*

**Spec Position paper (preprint) · July 2026** — accompanying the position paper: *Canonics: Versioning the Frame, Not the Facts*, Lucio Amorim, Position paper (preprint) · July 2026 (https://doi.org/10.5281/zenodo.21268307).

This document is normative. Conformance keywords (MUST, SHOULD, MAY) are defined in [conformance.md](conformance.md) per RFC 2119. Machine-readable schemas for the objects defined here live in [schemas/](schemas/).

---

## 0. Scope and claim

Canonics versions the interpretive regime, not just the data. The framework composes established components — event sourcing, bi-temporal modeling, context logics, belief revision — into what is, to our knowledge after targeted prior-art review, the first framework for LLM-agent memory that operationalizes the interpretive regime itself as a versioned, human-declared object with scoped propagation and source-based re-derivation.

**Scope statement.** The framework as specified here targets a **single operator or a small, high-trust team**. Multi-stakeholder settings raise an epistemic-authority problem and an access-control problem that this version does not model. Enterprise deployment is named future work, not an implied capability. The file-based substrate of the reference implementation is a convenience: the principle — version the interpretive regime — is portable to any infrastructure with transactions and access control; the substrate is not part of the claim.

**Non-claims (normative).** A conforming deployment MUST NOT present Canonics as doing any of the following:

1. Canonics does not detect regime shifts autonomously. It reduces the cost of declaring and propagating regime shifts *once perceived*, and structures and measures perception through the Canon Review.
2. κ is not a validity metric. It is a distance to *declared* marks. κ = 0 under an inactive declaration process certifies nothing.
3. Reprocessing is not automatic. It is machine-proposed and policy-activated; in critical domains, human-gated.
4. Canonics is not enterprise-ready. The scope is a single operator or small high-trust team.
5. The Markdown+Git substrate is not part of the claim; it is the convenience implementation.
6. Operational viability is not demonstrated; it is a falsifiable hypothesis (H-G).
7. Canonics does not eliminate maintenance; it compresses and schedules it.
8. Canonics is not a second brain and does not compete with capture tools; it captures nothing and governs the interpretation of what other systems capture.

## 1. The principle

> **The Canon–Epoch Principle.** In any memory system used for decision-making, every derived interpretation must be evaluated not only against its source facts, but against the interpretive regime under which it was produced — and against the canon events that may have changed that regime since.

The architectural insight in one line: **facts are immutable; interpretations are versioned cache; canon events are the invalidation signal; epochs are the cache key; the Canon Review is the scheduled audit of the invalidation signal itself.**

## 2. Ontology: the five primitives

Canonics' world is built from five primitives, ordered by mutability, plus one transversal dimension (domains). Definitions are reproduced from the paper (§4.2) and are normative.

**Definition 1 (Fact).** A fact f ∈ F is an immutable, append-only record of an observation, event, or communication: f = (content, t_event, t_recorded, source, D_f) with domains D_f ⊆ 𝔻. Facts are never rewritten, only re-read under different lenses.

**Definition 2 (Invariant).** An invariant v ∈ V is an assumption declared to survive all epoch transitions: identity, values, non-negotiable principles. Invariants are the hard core of the knowledge base; changing one is the rarest and most consequential form of canon (Level 5 below).

**Definition 3 (Canon event).** A canon event c ∈ C is a fact *promoted* to metadatum status: it governs how other data must be read. Formally c = (id, t_effective, t_declared, level, δ(c), S(c), declarer) where t_effective may precede t_declared (retroactive declaration is permitted); level is drawn from the severity ladder L1–L5 below; the **regime diff** δ(c) = (A⁻, A⁺) lists assumptions retired and introduced; the **blast radius** S(c) ⊆ 𝔻 (optionally refined by assumption categories) bounds its scope; and declarer identifies the authenticated human who declared it. Canon events are meant to be rare — the paper hypothesizes a healthy system produces roughly 2–6 per domain per year; that target is a hypothesis to validate, not a law.

**Severity ladder (normative enum).**

| Level | Name | Effect |
|---|---|---|
| L1 | Factual correction | Fixes a record; no epoch transition. |
| L2 | Tactical shift | Priority, tool, or process; may touch one domain epoch. |
| L3 | Operating-model shift | Capacity, team, pricing, delivery; typically opens a domain epoch. |
| L4 | Strategic paradigm shift | Thesis, market position, identity of the operation; may open epochs across domains. |
| L5 | Doctrine shift | Changes what the system considers good judgment; modifies invariants; rare and deliberately high-friction. |

**Definition 4 (Epoch).** For domain d, let C_d = {c ∈ C : d ∈ S(c)} ordered by t_effective. The epochs of d are the derived intervals E_d = {[t(c_i), t(c_{i+1}))}, with the current epoch open-ended. Epochs are never created or edited directly; they *emerge* from the canon sequence — the single most important overhead-reduction decision in the framework. Each epoch carries its **regime** R(d, t) = V ⊕ δ(c₁) ⊕ … ⊕ δ(c_j) for all c_j ∈ C_d with t_effective(c_j) ≤ t.

**Regime fold ⊕ (normative).** ⊕ applies diffs in order: later diffs override, and assumptions persist until explicitly retired (inheritance unless revoked).

**Definition 5 (Understanding).** An understanding u ∈ U is a proposition derived from source facts under a regime: u = (content, F_u ⊆ F, ε(u), t_u, D_u, volatility, status, version), produced by interpretation function I as u = I(F_u, R(d, t_u)) and stamped with epoch of origin ε(u). In practice, I is an LLM under a regime-conditioned prompt. **Provenance is mandatory:** F_u MUST be non-empty and mechanically resolvable to immutable records; an understanding without verifiable source pointers is not decision-grade and MUST NOT be returned as guidance. **Understandings are never overwritten:** re-derivation creates a new version stamped with the new epoch, linked to its predecessor; the full version chain is preserved. status ∈ {active, stale, proposed, superseded, archived}; volatility ∈ {stable, strategic, operational, live} sets review expectations orthogonal to canon (a coarse prior on how fast a class of understandings decays *within* an epoch).

**Domains.** 𝔻 partitions the knowledge space. Epochs run per domain, unaligned; a canon in d₁ does not transition d₂ unless d₂ ∈ S(c). A global epoch exists as the intersection of domain epochs and SHOULD change rarely (L4–L5 only).

## 3. Canon distance (κ) and the validity classification

**Definition 6 (Canon distance).** For understanding u at time t:

κ(u, t) = |{ c ∈ C : t_u < t_effective(c) ≤ t, S(c) ∩ D_u ≠ ∅, (A⁻(c) ∪ A⁺(c)) ∩ deps(u) ≠ ∅ }|

where deps(u) are the assumptions u's derivation relied on (approximated, in the minimal implementation, by domain-plus-category tags). An understanding with κ = 0 has crossed no declared in-scope regime change; an understanding with κ ≥ 1 is suspect regardless of how recently it was created. This replaces clock-based staleness with mark-based staleness only for regime-induced interpretive staleness under adequate declaration coverage and dependency tagging. It does not replace age or volatility priors for within-epoch decay, exogenous drift, or domains whose relevant shifts are not observable in the review corpus.

**What κ measures — and what it does not (normative non-claim; MUST accompany every use of κ).** κ is a distance to *declared* marks, not a validity certificate. κ = 0 means "no declared canon intersects this understanding," which is evidence of freshness only to the extent that declaration coverage is adequate. A system whose operator has stopped declaring reports κ = 0 everywhere while drifting arbitrarily far from the world. Validity requires two conditions: κ = 0 *and* an alive declaration process, which is what the Canon Review's self-instrumentation (§5) makes auditable. Any deployment that reports κ without reporting declaration-process health is misusing the metric, and a conforming implementation MUST NOT surface κ as a freshness guarantee without declaration-process health alongside it.

**The four validity states.** With that caveat stated, validity states are computable relative to the declared canon set:

1. *Eligible for current use relative to declared canons* ⇔ κ = 0 and declaration-process health remains live.
2. *Needs reinterpretation* ⇔ κ ≥ 1 with source facts intact.
3. *Invalid as guidance* ⇔ κ ≥ 1 with dependencies on explicitly retired assumptions.
4. *Valid as history* — every superseded version, permanently.

**Canon promotion test (normative parsimony guardrail).** A fact c merits promotion to canon iff there exist queries q that do not reference c whose correct answer differs under R ⊕ δ(c) versus R. Informally: **a canon event changes the answers to questions that do not mention it.** Facts failing this test — however dramatic — are just facts.

## 4. Core operations

A conforming implementation MUST provide the four operations below. Reference pseudocode reproduced from the paper (§4.4). Notation: κ as in Def. 6; e_now(d) the current epoch of domain d. Note the fourth operation is **SCAN** — it scans and proposes; it does not detect or declare.

```
DECLARE(c):                            # register a canon event (human act)
  1. authenticate declarer; validate c.level against the severity
     ladder; require out-of-band human confirmation for L3+
     (automation may only PROPOSE, never declare)
  2. resolve S(c) from c.diff and the domain taxonomy; propose
     secondary scope for adjacent domains (lower priority)
  3. for each d in S(c):
       close e_now(d); derive new epoch with regime R ⊕ δ(c)
  4. for each u with κ(u, now) ≥ 1: u.status ← stale   # mark, don't rewrite
  5. regenerate CURRENT_CONTEXT (regime summaries per domain)
  6. append signed c to CANON_LOG                       # audit trail
```

```
RETRIEVE(q, t):                        # epoch-aware retrieval
  1. S ← semantic retrieval for q
  2. for each s in S:
       fact       → return as-is, annotated with ε
       invariant  → return as-is (trans-epochal)
       understanding u:
         no provenance → do not return as guidance; flag
         κ = 0    → return as-is (fresh w.r.t. declared canons)
         κ ≥ 1    → REPROCESS(u, t) per policy, or return with banner:
                    [STALE: derived under ε(u); current epoch differs
                     by canons c_i…c_j; diffs attached]
  3. inject R(d, t) summary into the system prompt      # always-on, H8
```

```
REPROCESS(u, t):                       # re-derive under current regime
  1. u' ← I(F_u, R(d, t))              # from the SOURCE FACTS, not from u
  2. stamp u' with ε = e_now(d); attach provenance F_u; link u' ↔ u
  3. if domain(u) marked critical:
       u'.status ← proposed            # activation requires human gate
     else:
       u'.status ← active; u.status ← superseded
  4. u is preserved forever, never deleted              # versioned chain
```

```
SCAN(d, window):                       # continuous scan feeding the Canon Review
  1. AGENDA ORDER IS ASYMMETRIC:
     (a) falsification pass: search recent facts and understandings
         for evidence that ACTIVE canons/assumptions are supplanted
     (b) emergence pass: search for coherent patterns no canon describes
  2. attach provenance to every finding (source, author, date)
  3. if contradiction rate exceeds threshold:
       queue a PROPOSED canon event, with suggested retroactive
       t_effective at the onset of the pattern
  4. findings are presented at the next Canon Review; nothing
     is declared by this process
```

Three details are normative. REPROCESS re-derives from *source facts*, never by editing the old understanding — translation across regimes carries contamination. Reprocessing is **machine-proposed and policy-activated**: automatic activation is a per-domain policy choice, and critical domains require human adjudication before a re-derived understanding becomes active. DECLARE only *marks* stale; actual re-derivation is deferred (H9).

## 5. Operational heuristics H1–H9 (normative guidance; SHOULD)

- **H1 — Write path.** Every new understanding is automatically stamped (epoch, domains, source facts). Stamping must cost the human nothing; if metadata requires discipline, the system dies.
- **H2 — Read path (epistemic synchronicity).** Before use, compute κ. Fresh → use. Stale → check intervening scopes: untouched → re-stamp; touched → REPROCESS or read under an explicit diff banner. (κ is a distance to declared marks, not a validity certificate — §3.)
- **H3 — Staleness by marks, not clock.** Retire fixed-age rules. Age is a proxy; canon distance is the measurement — subject to the declaration-coverage caveat of §3.
- **H4 — Asymmetric decay.** Facts do not decay. Intentions, plans, and postures decay completely upon crossing a disruptive canon. The fact/understanding split makes this asymmetry mechanical rather than judgmental.
- **H5 — Conflict resolution.** Between contradicting understandings, the later epoch prevails *prima facie*; the earlier is retained. Contradictions are flagged, never silently resolved.
- **H6 — Machine proposes, human declares.** SCAN proposes; the Canon Review disposes. Full automation of canon declaration is excluded by design: an autonomous declarer that misfires does not just corrupt data — it corrupts the lens.
- **H7 — Paradigm delta reading.** To brief an agent on history, provide invariants + the canon chain + the current regime, not the archive.
- **H8 — Regime in the system prompt.** Because retrieval-visible updates are frequently ignored, the current regime summary belongs in always-on instructions (system prompt / CLAUDE.md), not in retrievable storage. Foreground, don't file.
- **H9 — Lazy by default, gated for the critical.** Reprocessing at retrieval scales with use, not archive size, and limits contamination if a canon was declared prematurely. Understandings marked critical may be eagerly reprocessed at DECLARE time, but their activation is human-gated. The honest trade-off: gating is additional human load; the framework chooses bounded, scheduled load over unbounded contamination.

## 6. The Canon Review (normative for conforming deployments)

The Canon Review is a first-class component of the framework, not tooling advice. A conforming deployment MUST run it at a fixed cadence (monthly by default; weekly for volatile operations; one to two hours), with the six protocol points and constitutional roles specified in [docs/canon-review-protocol.md](../docs/canon-review-protocol.md).

The honest claim, stated as in the paper: *Canonics does not detect regime shifts by itself; it structures the recurring encounter between machine scanning and human judgment, and measures the lag.*

**Self-instrumentation (MUST support).** A conforming deployment MUST record and report:

- **Proposal rejection rate** — the vital sign. A sustained near-zero rejection rate is an alarm, not a success indicator. Rejection rate is not a non-gameable proof of life: a scan can preserve a healthy-looking rate by offering weak sacrificial findings while consequential proposals pass under-examined.
- **Signal→declaration lag** — t_declared − t_effective, aggregated over the canon log.
- **Ratification outcomes** — canons ratified versus abandoned at the thirty-day gate.
- **Vacancy death rule** — two consecutive reviews with no real adjudication trigger a mandatory question: does this domain need a different cadence — or has the system died? An honest death is recorded, not papered over.

Deployments SHOULD additionally implement the adversarial audit sample and outcome backtesting described in the protocol document.

## 7. Canon integrity (normative)

Canon declaration is a production change. A conforming implementation MUST enforce:

- **Signed, tamper-evident canon history — not a cryptographic append-only ledger.** Every canon event carries an authenticated declarer identity. In the file-based substrate, canon events are recorded through signed Git commits or tags over Markdown records. Git provides tamper evidence relative to a trusted reference; it does not, by itself, provide a globally enforced append-only log. Append-only behavior is a repository policy enforced by protected branches, no-force-push rules, periodic external mirrors or published commit hashes, and audit of any history rewrite. Deployments that cannot provide those controls MUST describe the canon log as tamper-evident, not append-only.
- **Out-of-band human approval.** Declaration at L3+ requires confirmation through a channel outside the agent flow.
- **Automation proposes; only humans declare.** No automated process, including the SCAN pass, may write to the canon log. This is a security boundary, not only an epistemological preference.

The full threat model — including evidence-planting on the review, provenance spoofing, and slow-canon attacks — is normative and specified in [docs/canon-integrity.md](../docs/canon-integrity.md). Two-sided accounting, stated plainly: canon concentration is simultaneously the largest single target in the architecture and the smallest auditable surface in the system. A Canonics deployment that implements the propagation machinery without the integrity controls is more dangerous than no Canonics at all.

## 8. Properties

Design invariants an implementation MUST maintain (not theorems about LLM behavior; the interpretation function I is stochastic, so re-derivations are reproducible only up to model determinism — temperature, seed, and model version SHOULD be logged):

- **P1 (Fact monotonicity).** F is append-only; history is never rewritten.
- **P2 (Re-derivability).** Every understanding is recomputable from its preserved sources under any regime.
- **P3 (Freshness soundness, relative to declared canons).** If κ(u, t) = 0, no assumption u's derivation relied on has been retired by any *declared* canon event in u's domains up to t. P3 says nothing about undeclared shifts (see §3 for what κ does not measure).
- **P4 (Surgical invalidation).** A canon event perturbs only understandings whose domains and dependencies intersect its declared scope.
- **P5 (Audit reconstructibility).** For any past t, R(d, t) is reconstructible from V and CANON_LOG, and any understanding's historical reading is recoverable via its preserved version chain.
- **P6 (Regime reversibility).** Revoking a canon is itself a canon event; the prior regime is restored by the fold without data loss.

## 9. Schemas

Machine-readable schemas (normative) in [schemas/](schemas/):

- [canon_event.schema.yaml](schemas/canon_event.schema.yaml)
- [epoch_state.schema.yaml](schemas/epoch_state.schema.yaml)
- [understanding_frontmatter.schema.yaml](schemas/understanding_frontmatter.schema.yaml)
- [invariant.schema.yaml](schemas/invariant.schema.yaml)
- [reprocess_queue.schema.yaml](schemas/reprocess_queue.schema.yaml)

---

*This specification carries the paper's non-claims as normative constraints (§0). Reproducing Canonics capabilities without the corresponding non-claims is a conformance violation (see [conformance.md](conformance.md)).*