Skip to main content

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.

Rust · protocol/1 source · canon-ir/1 compiled form · Apache-2.0

canon / repository root
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
Real canon output, recorded by canon-docs and checked for drift on every change.3/3 exit 0 · 19 ✓ · 0 ✕
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.

  1. Declared as data

    Shipped

    A 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.

  2. Pure and deterministic

    Shipped

    The library reads no clock, environment, network or filesystem. Callers pass documents in; the same normalized input gives the same normalized output.

  3. Three-valued claims

    Shipped

    Every claim is TRUE, FALSE or UNKNOWN. Missing evidence leaves a claim UNKNOWN; it never makes it FALSE.

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.

  1. Authorprotocol/1

    Artifacts, evidence kinds, claims, obligations, actions and outcomes, as YAML.

  2. Validatecanon validate

    Every reference resolves, every identifier is unique, no claim cycles.

  3. Compilecanon-ir/1

    Canonical order, explicit defaults, one serialization.

  4. 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/1

Decide whether an explanation is supported by observation and survives an attempt to falsify it.

  • Actions2
  • Evidence kinds2
  • Claims1
  • Outcomes1
ACTIONattempt_falsificationACTIONinspectEVIDENCE KINDfalsification_attemptEVIDENCE KINDsupporting_observationCLAIMexplanation.supportedOUTCOMEsupported

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
Actions
NameDescriptionRuleLeads to
attempt_falsificationTry to refute the explanation.—produces falsification_attempt
inspectLook for observations bearing on the explanation.—produces supporting_observation
Evidence kinds
NameDescriptionRuleLeads to
falsification_attemptAn attempt to refute the explanation; its result is survived or refuted.—establishes explanation.supported (survived)
supporting_observationAn observation consistent with the explanation.—establishes explanation.supported
Claims
NameDescriptionRuleLeads to
explanation.supportedThe explanation is supported by observation and has survived falsification.all of evidence = survived: falsification_attempt any evidence: supporting_observationrequires supported
Outcomes
NameDescriptionRuleLeads to
supportedThe explanation is supported.claim explanation.supported—

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