Protocol calculus · bootstrap
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 answers what is known, what is unknown, which obligations remain open, which actions are admissible, and whether an outcome has been earned.
canon validate --path fixtures/investigation/protocol.yaml
valid: protocol `investigation` revision 1
canon compile --path fixtures/investigation/protocol.yaml | head -n 8
{
"actions": {
"attempt_falsification": {
"description": "Try to refute the explanation.",
"effect": null,
"may_produce": [
{
"evidence": "falsification_attempt"
canon conform run
passed: scenario `CANON-AUTHORITY-001`
passed: scenario `CANON-COMPOSE-001`
passed: scenario `CANON-INPUT-001`
passed: scenario `CANON-OUTCOME-002`
passed: scenario `CANON-EVIDENCE-002`
passed: scenario `CANON-INDEPENDENCE-001`
passed: scenario `CANON-ORDER-002`
passed: scenario `CANON-ORDER-004`
passed: scenario `CANON-ORDER-003`
passed: scenario `CANON-ORDER-001`
passed: scenario `CANON-EVIDENCE-001`
passed: scenario `CANON-EXPLAIN-001`
passed: scenario `CANON-INVALIDATION-001`
passed: scenario `CANON-OBLIGATION-001`
passed: scenario `CANON-OUTCOME-001`
passed: scenario `CANON-REASONS-001`
passed: scenario `CANON-EVIDENCE-003`
passed: scenario `CANON-CLAIM-001`
conform: 18 passed, 0 failed, 0 unreadable
- actions
- 2
- evidence kinds
- 2
- claims
- 1
- shipped, runs today
- 29
- decided, not built
- 0
- planned
- 0
01 / What it does
Legitimacy, not sequencing.
A workflow answers what executes next. Canon answers what is currently legitimate: the claims that can be made, the evidence that can establish them, the actions that are possible and the outcomes a case may conclude under. It does not execute anything.
Declared as data
ShippedA protocol is a YAML document in the protocol/1 format. Canon parses it, checks every reference and compiles it into canon-ir/1, a normalized form stable enough to hash.
Pure and deterministic
ShippedThe library reads no clock, environment, network or filesystem. Callers pass documents in; the same normalized input gives the same normalized output.
02 / How it works
From a document to a decision.
Each step is a command that runs today. The evaluation reads a case snapshot and an evidence set and prints a canon-decision/1 document with a value for every claim.
- Authorprotocol/1
Artifacts, evidence kinds, claims, obligations, actions and outcomes, as YAML.
- Validatecanon validate
Every reference resolves, every identifier is unique, no claim cycles.
- Compilecanon-ir/1
Canonical order, explicit defaults, one serialization.
- Evaluatecanon evaluate
Claims for one case and one evidence set, three-valued.
03 / A protocol
What a protocol declares, as a graph.
The investigation protocol from Canon's own fixtures, drawn from its compiled form. Actions may produce evidence; evidence establishes claims; claims earn outcomes. Hover a node to trace what it rests on.
Protocol · revision 1
investigation/1Decide whether an explanation is supported by observation and survives an attempt to falsify it.
- Actions2
- Evidence kinds2
- Claims1
- Outcomes1
Hover or focus a node to trace what it rests on and what rests on it. Press Enter to pin it, Escape to clear.
Protocol as text
| Name | Description | Rule | Leads to |
|---|---|---|---|
attempt_falsification | Try to refute the explanation. | — | produces falsification_attempt |
inspect | Look for observations bearing on the explanation. | — | produces supporting_observation |
More columns: swipe horizontally, or focus the table and use the arrow keys.
| Name | Description | Rule | Leads to |
|---|---|---|---|
falsification_attempt | An attempt to refute the explanation; its result is survived or refuted. | — | establishes explanation.supported (survived) |
supporting_observation | An observation consistent with the explanation. | — | establishes explanation.supported |
More columns: swipe horizontally, or focus the table and use the arrow keys.
| Name | Description | Rule | Leads to |
|---|---|---|---|
explanation.supported | The explanation is supported by observation and has survived falsification. | all of evidence = survived: falsification_attempt any evidence: supporting_observation | requires supported |
More columns: swipe horizontally, or focus the table and use the arrow keys.
| Name | Description | Rule | Leads to |
|---|---|---|---|
supported | The explanation is supported. | claim explanation.supported | — |
More columns: swipe horizontally, or focus the table and use the arrow keys.
Source: canon compile fixtures/investigation/protocol.yaml
04 / Status
Bootstrap. Here is exactly what exists.
Shipped means a command or library call that runs today. Decided means recorded in an accepted architecture decision, not built. Planned means on the roadmap only.
Shipped · runs today
- ShippedTyped catalog assertionscanon-expr/1 parsing, type checking, recipes, exact numbers, acquisition planning and pure replay over typed observations; available in source release 0.1.0.
- Shippedprotocol/1 source model and parserArtifacts, evidence kinds, claims, obligations, actions, outcomes and invalidation rules, read strictly; unknown keys and explicit nulls are refused.
- ShippedDeterministic validationFormat, identifiers, duplicates, unresolved references and claim cycles, in a stable order.
- Shippedcanon-ir/1 compilationCanonical ordering, explicit defaults, one serialization suitable for hashing.
- ShippedESS specification of the data modelThe model is specified under ess/ and held to a hard gate; a test fails when the two differ.
- ShippedThree-valued claim evaluationcanon evaluate over a case snapshot and an evidence directory, writing a canon-decision/1 document; scenario CANON-CLAIM-001, also covering CANON-CLAIM-002.
- ShippedEvaluation documentscanon-case/1, canon-evidence/1, canon-authority/1, canon-decisions/1 and canon-decision/1, and the canon-properties/1 document canon check reads.
- Shippedcanon conform runRuns canon-conformance/1 scenarios that compile a fixture and evaluate a case, with authority decisions, explicit decisions and an evaluation instant when a step gives them.
- ShippedNormative conformance suiteThe canon-requirements/1 catalogue lists the CANON-* requirements Canon implements; canon conform run --requirements fails when an implemented one has no passing scenario, a scenario covers one the catalogue omits, or an evaluate step gives another decision when rerun or with its evidence, authority and decisions reversed.
- ShippedEvidence bound to revisionsEvidence applies only to the current revision of the artifact it names; a record bound to another revision is listed as excluded under each claim that reaches its kind, and one about an undeclared artifact is refused; scenario CANON-EVIDENCE-001.
- ShippedSubject-bound evidence matchesAn evidence match may name the artifact its record must be about; a record about another artifact does not match it; scenario CANON-EVIDENCE-003.
- ShippedEvidence freshnessEvidence older than its kind's max_age at the --at instant is excluded, so a match it alone decided is UNKNOWN rather than FALSE; scenario CANON-EVIDENCE-002.
- ShippedInvalidation rulesA rule names an upstream artifact and the claims its revision change invalidates; evidence observed against an earlier revision no longer supports them, and claims built on them follow their predicates; scenario CANON-INVALIDATION-001.
- ShippedObligationsEach obligation is open or discharged by its discharge predicate; scenario CANON-OBLIGATION-001.
- ShippedAction admissibilityAdmissible, approval-required or blocked, from preconditions and authority decisions; scenario CANON-AUTHORITY-001.
- ShippedOutcomesLegitimate or blocked; no completion through an undeclared or blocked outcome; scenario CANON-OUTCOME-001.
- ShippedDecision-based outcomesAn outcome may require an explicit decision taken at the current case revision; scenario CANON-OUTCOME-002.
- ShippedStructured explanationEvery decision says what it was computed from and why each value is what it is, down to the evidence records that applied or were excluded; scenario CANON-EXPLAIN-001, also covering CANON-DETERMINISM-001.
- Shippedcanon checkEvery state of a protocol's finite state space; unreachable outcomes, unsatisfiable preconditions, unproduced evidence, authority bypasses with a witness state, and failing properties with a counterexample.
- Shippedcanon generateOne minimal witness scenario per outcome and per blocked action, which canon conform run runs unchanged.
- ShippedSemantic diffClassify a protocol change as tightening, relaxation, breaking, expansion or no semantic change.
- ShippedCase inputs and applicable obligationsA protocol declares case inputs with closed value lists; the input predicate and applicable_when let one compiled protocol serve several profiles; scenario CANON-INPUT-001.
- ShippedEvidence from an independent producerAn evidence match demands that its records' producer be independent on declared dimensions, which the case resolves for each producer; a record that fails the demand leaves the match UNKNOWN, never FALSE; scenario CANON-INDEPENDENCE-001.
- ShippedAction argument schemasAn action declares one argument schema in Canon's JSON Schema 2020-12 dialect, which a runner reads and validates calls against; absent, the action takes only {}. canon validate refuses a schema outside the dialect, canon compile carries it unchanged into canon-ir/1 and canon diff classifies its changes.
- ShippedCases compose at run timeAn action declares the child case it opens, by protocol and subject (case_open); each child's outcome comes back as one case_outcome record, and the children predicate is TRUE when every child ended with an outcome it lists, FALSE once one ended outside them, UNKNOWN while one is open or none is recorded. A case has one commission; a second party works through a child case. canon validate refuses an opening under the protocol's own id, and a check over a set of protocols refuses openings that form a cycle; Atlas ADR 0081, scenario CANON-COMPOSE-001.
- ShippedProtocols express step orderA predicate over evidence order, the first record of a kind and one kind before another; Atlas ADR 0084.
- ShippedA record observed after the first of a kindThe after order form tests whether a record of one kind with a given result was observed strictly after the first record of another kind, or of the same kind, read from the evidence history like first and before; scenario CANON-ORDER-002.
- ShippedOrder within a secondAn observed_at may carry a fraction of one to nine digits, and first, before and after compare every instant of one evaluation at the coarsest precision written among its records, so records within one second are ordered when all are written finer and equal instants are not; expiry keeps whole seconds; scenario CANON-ORDER-003.
- ShippedA record observed since the latest of a kindThe since order form tests whether a record of one kind with a given result, at the subject revision of the latest record of another kind (or of the same kind), was observed after it, read from the evidence history like the other order forms; scenario CANON-ORDER-004.
Generated by canon-docs from website/status.yaml; each status is read from the AEP story it names