Skip to main content

Engineering protocols · bootstrap

Engineering protocols on Canon.
UNKNOWN is not FALSE.

Engineering protocols state what makes engineering work legitimate: which claims must hold, which evidence counts and for which revision, which actions need authority, and which outcomes a case can end in.

What engineering protocols are Protocols One night, replayed

Rust · protocols as Canon protocol/1 data · Apache-2.0

incident.response/1 · protocol graph

ACTIONemergency.leaveACTION · READlogs.searchACTION · READmetrics.inspectACTION · READrelease.inspectACTION · WRITErelease.rollbackACTION · WRITEtraffic.shiftEVIDENCE KINDcause_analysisEVIDENCE KINDimpact_assessmentEVIDENCE KINDoperational_observationEVIDENCE KINDrollback_resultCLAIMcause.identifiedCLAIMimpact.boundedCLAIMrollback.verifiedCLAIMservice.healthyOBLIGATIONinvestigate_causeOBLIGATIONrestore_service
  • Actions6
  • Evidence kinds4
  • Claims4
  • Obligations2

Hover or focus a node to trace what it rests on.

incident.response/1 as Canon compiled it, drawn from the graph canon-engineering-docs generates from protocols/incident-response/1.yaml.
claims in incident.response/1
4
evidence kinds
4
actions
6
obligations
2
shipped, runs today
15

01 / What it does

Engineering method, declared as data.

This project owns the engineering vocabulary and the protocols written in it. What a claim, a piece of evidence or an obligation is, and how one is decided, belongs to Canon.

  1. Protocols are data

    Each protocol is a Canon protocol/1 document at protocols/<name>/<major>.yaml. Canon validates it, compiles it and evaluates it; engineering protocols add no hidden clock, network or model call.

  2. UNKNOWN is not FALSE

    Tests that passed on revision R1 say nothing about R2: tests.pass is UNKNOWN and merge stays blocked until evidence for R2 exists. Missing or stale evidence never makes a claim FALSE.

  3. Delivery and incidents

    Every rule is pressure-tested against software delivery and incident response. An incident can leave emergency mode while its cause is still UNKNOWN.

02 / How it works

From a protocol to a page.

A protocol is written once as data. Canon checks and compiles it, and every page on this site is generated from that compiled form.

  1. Authorprotocol/1

    Artifacts, evidence kinds, claims, obligations, actions and outcomes, named from the engineering vocabulary.

  2. Compilecanon-ir/1

    Canon validates every reference and compiles the document to its normalized form.

  3. EvaluateCanon

    Claims for one case and one evidence set, each TRUE, FALSE or UNKNOWN.

  4. Rendercanon-engineering-docs

    One page and one graph per protocol, checked for drift on every change.

03 / Status

Bootstrap. Here is exactly what exists.

Shipped means it is in the repository and tested today. Planned means it is in the plan only.

Shipped · runs today

  • ShippedTyped assertion gates and replayTyped file, process, report and network checks retain source-bound evidence for offline replay. Recipes and explicitly admitted Rust providers extend the catalog.
  • ShippedEngineering vocabulary181 terms, each with its category, marking and meaning, in protocols/vocabulary.yaml.
  • ShippedFixture harness over Canon evaluationCompiles a protocol with Canon and checks each fixture state's claims against Canon's evaluator.
  • ShippedBuilt-in protocol registryThe b10x-canon-engineering crate embeds every protocol under protocols/; canon-engineering protocols list and canon-engineering protocols show <name>@<major> print them.
  • Shippedeval.gated_change/1Canon protocol/1 data declaring 7 claims, 4 evidence kinds, 6 actions and 4 outcomes, with every evidence match bound to its artifact.
  • Shippedincident.response/1Canon protocol/1 data declaring 4 claims, 4 evidence kinds, 6 actions and 2 obligations.
  • Shippedloop.improvement/1Canon protocol/1 data declaring 4 claims, 4 evidence kinds, 6 actions, 2 obligations and 3 outcomes, with every evidence match bound to its artifact.
  • Shippedml.experiment/1Canon protocol/1 data declaring 5 claims, 5 evidence kinds and 5 outcomes, with every evidence match bound to its artifact.
  • Shippedprotocol.adopt/1Canon protocol/1 data declaring 3 claims, 3 evidence kinds, 3 actions and 1 outcome, with every evidence match bound to its artifact.
  • Shippedself.improvement/1Canon protocol/1 data declaring 6 claims, 5 evidence kinds, 7 actions, 3 obligations and 4 outcomes, with every evidence match bound to its artifact.
  • Shippedsoftware.change/1Canon protocol/1 data declaring 9 claims, 9 evidence kinds, 6 actions, 6 obligations and 5 outcomes, with every evidence match bound to its artifact.
  • Shippedstory.delivery/1Canon protocol/1 data declaring 7 claims, 7 evidence kinds, 10 actions, 4 obligations and 2 outcomes, with every evidence match bound to its artifact.
  • Shippedstory.delivery/2Canon protocol/1 data declaring 9 claims, 9 evidence kinds, 10 actions, 4 obligations and 2 outcomes, with every evidence match bound to its artifact.
  • Shippedsupport.triage/1Canon protocol/1 data declaring 9 claims, 6 evidence kinds, 7 actions, 1 obligation and 3 outcomes, with every evidence match bound to its artifact.
  • ShippedProtocol pages from canon-ir/1Generated by canon-engineering-docs for every protocol in protocols/, with its graph, and checked for drift.

Planned · roadmap only

Generated by canon-engineering-docs from protocols/ and the engineering protocols crates

04 / Related tools