canon CLI reference

Generated from the clap definition of the canon command line in crates/canon-cli/src/lib.rs. It lists only commands that exist; commands the design proposes are on the status page.

canon: Evidence-governed protocol toolchain. canon --version prints its version, and --help after any command prints the text shown below.

Commands

Command	What it does
canon validate	Parse and validate a protocol/1 document
canon compile	Compile a valid protocol/1 document into canon-ir/1 and print it
canon evaluate	Evaluate a case under a compiled protocol from an evidence set: every claim, and each declared obligation, action and outcome. Print the canon-decision/1 document
canon check	Check a protocol/1 document over its whole finite state space: report outcomes no state reaches, actions whose precondition holds in no state, claims, obligations, preconditions and outcome requirements that read evidence no action produces, outcomes that rest on evidence an authority-requiring action may produce yet hold without any authority decision, and each declared property that fails, with a counterexample. A state is a set of evidence records, authority decisions and explicit decisions; a record an invalidation rule can keep from a claim is there in any combination of observed before and after each upstream artifact moved, one record each. Evidence an order form reads (first, before, after, since) is also there with earlier records at a superseded revision, or with no known instant, in every order of first observations; evidence an after or a since compares with its result also with a later record of that result, placed anywhere in that order or at no known instant; and evidence a since reads as its last kind also with a last record at a superseded revision, placed in that order on its own, with or just after its own first observations or a later record it is compared with. Evidence an evidence match demanding independence reads (independent_on) is there from a producer independent on exactly each demand, in every combination of demands met, and without a producer when something that demands nothing reads it. Evidence a children form reads (case_outcome) is also there with earlier records at a superseded revision, each record the outcome of a child case of its own, and with no place in the order, which the form does not read; an action that opens a child case (case_open) counts as producing case_outcome; and a protocol that reads case_outcome with both a children form and an order form is refused (ordered-child-outcomes). A state space of more than 65536 states is refused
canon generate	Generate canon-conformance/1 scenarios into an empty directory: one minimal witness per declared outcome and per action blocked in some state, over the state space canon check enumerates. Each names the protocol path, as given, as its fixture, so canon conform run runs them from the working directory canon generate ran in. Refused, writing nothing: a protocol path that resolves outside the working directory, an outcome no state reaches, a protocol that yields no scenario, an outcome or action identifier holding a character a file name cannot hold (/ \ : * ? " < > | or a control character), two scenario file names equal up to letter case or Unicode normalisation, and a non-empty --out. On failure, nothing this run created is left
canon diff	The semantic difference between two compiled revisions of one protocol: every change, each classified as TIGHTENING, RELAXATION, BREAKING, EXPANSION or NO SEMANTIC CHANGE and naming the identifiers it touches. Two revisions of different protocols are refused
canon conform	Conformance scenarios
canon conform run	Run every canon-conformance/1 scenario of a registry directory and report each

canon validate

Parse and validate a protocol/1 document

Option	Required	Default	Meaning
--path <PATH>	yes	none	The protocol document to validate

Parse and validate a `protocol/1` document

Usage: canon validate --path <PATH>

Options:
      --path <PATH>
          The protocol document to validate

  -h, --help
          Print help

canon compile

Compile a valid protocol/1 document into canon-ir/1 and print it

Option	Required	Default	Meaning
--path <PATH>	yes	none	The protocol document to compile

Compile a valid `protocol/1` document into `canon-ir/1` and print it

Usage: canon compile --path <PATH>

Options:
      --path <PATH>
          The protocol document to compile

  -h, --help
          Print help

canon evaluate

Evaluate a case under a compiled protocol from an evidence set: every claim, and each declared obligation, action and outcome. Print the canon-decision/1 document

Option	Required	Default	Meaning
--ir <IR>	yes	none	The compiled protocol: canon-ir/1 exactly as canon compile prints it
--case <CASE>	yes	none	The canon-case/1 case snapshot
--evidence <EVIDENCE>	yes	none	A directory holding only canon-evidence/1 records, one per *.yaml or *.json file
--authority <AUTHORITY>	no	none	A canon-authority/1 document: which capabilities are granted or denied. An action is admissible only when every capability it requires is granted; without it, none is granted
--decisions <DECISIONS>	no	none	A canon-decisions/1 document: the explicit decisions taken, each naming the decision, the outcome, the principal and the case revision it was taken at. An outcome that requires a decision is legitimate only with one taken at the case snapshot's revision
--at <AT>	no	none	The evaluation instant, in UTC as YYYY-MM-DDTHH:MM:SSZ, or YYYY-MM-DDTHH:MM:SS.fffZ with one to nine fraction digits. Evidence older than its kind's max_age at this instant, counted in whole seconds, does not apply; without it, no evidence expires

Evaluate a case under a compiled protocol from an evidence set: every claim, and each declared obligation, action and outcome. Print the `canon-decision/1` document

Usage: canon evaluate [OPTIONS] --ir <IR> --case <CASE> --evidence <EVIDENCE>

Options:
      --ir <IR>
          The compiled protocol: `canon-ir/1` exactly as `canon compile` prints it

      --case <CASE>
          The `canon-case/1` case snapshot

      --evidence <EVIDENCE>
          A directory holding only `canon-evidence/1` records, one per `*.yaml` or `*.json` file

      --authority <AUTHORITY>
          A `canon-authority/1` document: which capabilities are granted or denied. An action is admissible only when every capability it requires is granted; without it, none is granted

      --decisions <DECISIONS>
          A `canon-decisions/1` document: the explicit decisions taken, each naming the decision, the outcome, the principal and the case revision it was taken at. An outcome that requires a decision is legitimate only with one taken at the case snapshot's revision

      --at <AT>
          The evaluation instant, in UTC as `YYYY-MM-DDTHH:MM:SSZ`, or `YYYY-MM-DDTHH:MM:SS.fffZ` with one to nine fraction digits. Evidence older than its kind's `max_age` at this instant, counted in whole seconds, does not apply; without it, no evidence expires

  -h, --help
          Print help

canon check

Check a protocol/1 document over its whole finite state space: report outcomes no state reaches, actions whose precondition holds in no state, claims, obligations, preconditions and outcome requirements that read evidence no action produces, outcomes that rest on evidence an authority-requiring action may produce yet hold without any authority decision, and each declared property that fails, with a counterexample. A state is a set of evidence records, authority decisions and explicit decisions; a record an invalidation rule can keep from a claim is there in any combination of observed before and after each upstream artifact moved, one record each. Evidence an order form reads (first, before, after, since) is also there with earlier records at a superseded revision, or with no known instant, in every order of first observations; evidence an after or a since compares with its result also with a later record of that result, placed anywhere in that order or at no known instant; and evidence a since reads as its last kind also with a last record at a superseded revision, placed in that order on its own, with or just after its own first observations or a later record it is compared with. Evidence an evidence match demanding independence reads (independent_on) is there from a producer independent on exactly each demand, in every combination of demands met, and without a producer when something that demands nothing reads it. Evidence a children form reads (case_outcome) is also there with earlier records at a superseded revision, each record the outcome of a child case of its own, and with no place in the order, which the form does not read; an action that opens a child case (case_open) counts as producing case_outcome; and a protocol that reads case_outcome with both a children form and an order form is refused (ordered-child-outcomes). A state space of more than 65536 states is refused

Option	Required	Default	Meaning
--path <PATH>	yes	none	The protocol document to check
--properties <PROPERTIES>	no	none	A canon-properties/1 document: properties declared beside the protocol, each saying an action's or outcome's status is independent of a claim. Each is checked in every state

Check a `protocol/1` document over its whole finite state space: report outcomes no state reaches, actions whose precondition holds in no state, claims, obligations, preconditions and outcome requirements that read evidence no action produces, outcomes that rest on evidence an authority-requiring action may produce yet hold without any authority decision, and each declared property that fails, with a counterexample. A state is a set of evidence records, authority decisions and explicit decisions; a record an invalidation rule can keep from a claim is there in any combination of observed before and after each upstream artifact moved, one record each. Evidence an order form reads (`first`, `before`, `after`, `since`) is also there with earlier records at a superseded revision, or with no known instant, in every order of first observations; evidence an `after` or a `since` compares with its result also with a later record of that result, placed anywhere in that order or at no known instant; and evidence a `since` reads as its last kind also with a last record at a superseded revision, placed in that order on its own, with or just after its own first observations or a later record it is compared with. Evidence an evidence match demanding independence reads (`independent_on`) is there from a producer independent on exactly each demand, in every combination of demands met, and without a producer when something that demands nothing reads it. Evidence a `children` form reads (`case_outcome`) is also there with earlier records at a superseded revision, each record the outcome of a child case of its own, and with no place in the order, which the form does not read; an action that opens a child case (`case_open`) counts as producing `case_outcome`; and a protocol that reads `case_outcome` with both a `children` form and an order form is refused (`ordered-child-outcomes`). A state space of more than 65536 states is refused

Usage: canon check [OPTIONS] --path <PATH>

Options:
      --path <PATH>
          The protocol document to check

      --properties <PROPERTIES>
          A `canon-properties/1` document: properties declared beside the protocol, each saying an action's or outcome's status is independent of a claim. Each is checked in every state

  -h, --help
          Print help

canon generate

Generate canon-conformance/1 scenarios into an empty directory: one minimal witness per declared outcome and per action blocked in some state, over the state space canon check enumerates. Each names the protocol path, as given, as its fixture, so canon conform run runs them from the working directory canon generate ran in. Refused, writing nothing: a protocol path that resolves outside the working directory, an outcome no state reaches, a protocol that yields no scenario, an outcome or action identifier holding a character a file name cannot hold (/ \ : * ? " < > \| or a control character), two scenario file names equal up to letter case or Unicode normalisation, and a non-empty --out. On failure, nothing this run created is left

Option	Required	Default	Meaning
--path <PATH>	yes	none	The protocol document, as a relative path without .. components
--out <OUT>	yes	none	The directory to write the scenarios to: absent or empty. When absent it is created, with any missing parents; an existing one, or a symbolic link to one, is written into as it is

Generate `canon-conformance/1` scenarios into an empty directory: one minimal witness per declared outcome and per action blocked in some state, over the state space `canon check` enumerates. Each names the protocol path, as given, as its fixture, so `canon conform run` runs them from the working directory `canon generate` ran in. Refused, writing nothing: a protocol path that resolves outside the working directory, an outcome no state reaches, a protocol that yields no scenario, an outcome or action identifier holding a character a file name cannot hold (`/ \ : * ? " < > |` or a control character), two scenario file names equal up to letter case or Unicode normalisation, and a non-empty `--out`. On failure, nothing this run created is left

Usage: canon generate --path <PATH> --out <OUT>

Options:
      --path <PATH>
          The protocol document, as a relative path without `..` components

      --out <OUT>
          The directory to write the scenarios to: absent or empty. When absent it is created, with any missing parents; an existing one, or a symbolic link to one, is written into as it is

  -h, --help
          Print help

canon diff

The semantic difference between two compiled revisions of one protocol: every change, each classified as TIGHTENING, RELAXATION, BREAKING, EXPANSION or NO SEMANTIC CHANGE and naming the identifiers it touches. Two revisions of different protocols are refused

Option	Required	Default	Meaning
--from <FROM>	yes	none	The earlier revision, as canon compile prints it
--to <TO>	yes	none	The later revision, as canon compile prints it

The semantic difference between two compiled revisions of one protocol: every change, each classified as `TIGHTENING`, `RELAXATION`, `BREAKING`, `EXPANSION` or `NO SEMANTIC CHANGE` and naming the identifiers it touches. Two revisions of different protocols are refused

Usage: canon diff --from <FROM> --to <TO>

Options:
      --from <FROM>
          The earlier revision, as `canon compile` prints it

      --to <TO>
          The later revision, as `canon compile` prints it

  -h, --help
          Print help

canon conform

Conformance scenarios

Subcommands: run.

Conformance scenarios

Usage: canon conform <COMMAND>

Commands:
  run   Run every `canon-conformance/1` scenario of a registry directory and report each
  help  Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help

canon conform run

Run every canon-conformance/1 scenario of a registry directory and report each

Option	Required	Default	Meaning
--scenarios <SCENARIOS>	no	conformance/scenarios	The registry directory; every *.yaml file in it is one scenario
--requirements <REQUIREMENTS>	no	none	A canon-requirements/1 catalogue of the normative requirements the registry answers for. After the run, every implemented requirement must be covered by a passing scenario, no scenario may cover one the catalogue does not list, no planned one may be covered, and every evaluate step must give byte-identical output when run again and with its evidence, authority and decisions lists reversed. Adds a requirements: summary line

Run every `canon-conformance/1` scenario of a registry directory and report each

Usage: canon conform run [OPTIONS]

Options:
      --scenarios <SCENARIOS>
          The registry directory; every `*.yaml` file in it is one scenario

          [default: conformance/scenarios]

      --requirements <REQUIREMENTS>
          A `canon-requirements/1` catalogue of the normative requirements the registry answers for. After the run, every implemented requirement must be covered by a passing scenario, no scenario may cover one the catalogue does not list, no planned one may be covered, and every evaluate step must give byte-identical output when run again and with its `evidence`, `authority` and `decisions` lists reversed. Adds a `requirements:` summary line

  -h, --help
          Print help

Exit status

Status	Meaning
0	Success: the document is valid or compiled, the case was evaluated, every conformance scenario ran and passed, a check found nothing, or the scenarios were generated.
1	Rejected: a document was read and rejected, an evaluation or a check was refused, a conformance scenario failed or was unreadable, no scenario ran, a requirement check failed, a check found something, or generation was refused.
2	Unreadable: an input file or directory could not be read, or an output file could not be written.
64	Usage error: the command line was not understood (an unknown command or option, a missing required option, or a value that cannot be parsed); nothing was read.