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 per RFC 2119. Machine-readable schemas for the objects defined here live in 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:

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.
κ is not a validity metric. It is a distance to declared marks. κ = 0 under an inactive declaration process certifies nothing.
Reprocessing is not automatic. It is machine-proposed and policy-activated; in critical domains, human-gated.
Canonics is not enterprise-ready. The scope is a single operator or small high-trust team.
The Markdown+Git substrate is not part of the claim; it is the convenience implementation.
Operational viability is not demonstrated; it is a falsifiable hypothesis (H-G).
Canonics does not eliminate maintenance; it compresses and schedules it.
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:

Eligible for current use relative to declared canons ⇔ κ = 0 and declaration-process health remains live.
Needs reinterpretation ⇔ κ ≥ 1 with source facts intact.
Invalid as guidance ⇔ κ ≥ 1 with dependencies on explicitly retired assumptions.
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.

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. 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/:

canon_event.schema.yaml
epoch_state.schema.yaml
understanding_frontmatter.schema.yaml
invariant.schema.yaml
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).