Canon
What is known. What is owed. What has been earned.
Canon is a formal language and a deterministic calculus for evidence-governed protocols. For one case under one protocol it is meant to answer: what is known, what is unknown, which obligations remain open, which actions are admissible, which need authority, and whether an outcome has been earned.
Canon is early. Today it parses, validates and compiles protocols, and runs conformance
scenarios. canon evaluate gives every claim of a case a three-valued value, applying evidence
only to the revision it is bound to and only while it is fresh, and says which obligations are
open, which actions are admissible under the authority decisions given, and which outcomes are
legitimate, including outcomes that require an explicit decision, with a structured explanation of
each. Invalidation rules keep evidence observed against an earlier revision of an upstream artifact
from the claims that depend on it. Case inputs let one protocol serve several profiles: obligations
apply by the inputs a case gives, and canon diff classifies a change between two revisions of a
protocol. Predicates over evidence order read a case's evidence history: the first result of a
kind, and one kind's first record before another's. An evidence match can demand an independent
producer: a record counts only when the case lists its producer as independent on the dimensions
the match names. Each action can declare one argument schema, which a runner reads from the
protocol it loads and validates calls against. Every page says which parts are shipped and
which are planned;
where this stands has the full list.
Legitimacy, not sequencing
A workflow answers "what executes next?". Canon answers "what is currently legitimate?". A protocol declares the claims that can be made, the evidence that can establish them, the actions that are possible and the outcomes under which a case may conclude. Canon evaluates that declaration; it does not do the work.
- Declared as data. A protocol is a YAML document in the
protocol/1format. Canon parses it, checks every reference and compiles it intocanon-ir/1, a normalized form whose bytes are stable enough to hash. - Pure and deterministic. The library reads no clock, environment, network or filesystem. Callers pass documents in. The same normalized input is meant to give the same normalized output, byte for byte.
- Domain-neutral. Canon contains no engineering vocabulary and knows nothing about agents or model providers. Domains are written on top of it; the first is ELS, the engineering domain.
What Canon does not do
Canon does not execute anything. It is not a workflow engine, planner, scheduler, issue tracker, database, agent harness, authorization server or CI runner. Systems that do those things can consume what Canon decides.
Where to go next
- Getting started: build
canon, then validate, compile and evaluate a protocol. - The
protocol/1language: how a protocol is put together. - Three-valued truth and evidence bound to revisions: the two ideas Canon is built around.
- A worked example: one protocol, validated, compiled and evaluated.