protocol/1 reference

Generated from the model types in crates/canon/src/model: their doc comments, fields, field types and serde attributes. The JSON Schema is generated from the same types. For what the parts mean together, read the language; for the documents an evaluation reads and writes, see evaluation documents.

Keys written with no value: a key left out takes its default, or is refused when it has none; a key written with no value is an error.

The document

A protocol/1 source document as written.

Key	Value	Required	Meaning
format	text	required	The document format; the validator accepts only protocol/1.
protocol	ProtocolHeader	required	—
artifacts	map from identifier (ArtifactId) to Artifact	optional	—
evidence_kinds	map from identifier (EvidenceKindId) to EvidenceKind	optional	—
claims	map from identifier (ClaimId) to Claim	optional	—
obligations	map from identifier (ObligationId) to Obligation	optional	—
actions	map from identifier (ActionId) to Action	optional	—
outcomes	map from identifier (OutcomeId) to Outcome	optional	—
invalidation	map from identifier (InvalidationRuleId) to InvalidationRule	optional	The invalidation rules, keyed by rule id; a protocol without the section declares none.
case	CaseSection	optional	What a case governed by the protocol gives when it opens: its case inputs. A protocol without the section declares no input.
independence_dimensions	map from identifier (IndependenceDimensionId) to IndependenceDimension	optional	The independence dimensions the protocol's evidence matches may demand, keyed by dimension id; a protocol without the section declares none.

ProtocolHeader

The protocol's identity: id and revision.

Key	Value	Required	Meaning
id	identifier (ProtocolId)	required	—
revision	integer, 0 or more	required	—
description	text	optional	—

Artifact

A thing whose revisions evidence is bound to.

Key	Value	Required	Meaning
description	text	optional	—

EvidenceKind

A kind of evidence the protocol admits.

Key	Value	Required	Meaning
description	text	optional	—
max_age	text (Age)	optional	How old a record of this kind may be and still apply: at an evaluation instant later than its observed_at by more than this, it is excluded as expired (design § 8).

Claim

A proposition whose value is established from evidence by its predicate.

Key	Value	Required	Meaning
description	text	optional	—
true_when	Predicate	required	—

Obligation

Something that must be done before the case can be complete. It is discharged only when its discharge predicate, over claim values, evaluates true (design § 8). One with an applicability predicate applies only when that predicate is not false: false, it is not applicable.

Key	Value	Required	Meaning
description	text	optional	—
discharged_when	Predicate	required	—
applicable_when	Predicate	optional	When the obligation applies, over claim values and case inputs; always, when absent.

Action

A semantically named possibility: what it needs, what authority it requires, what effect it has and what evidence it may produce (design § 10).

Key	Value	Required	Meaning
description	text	optional	—
precondition	Predicate	optional	—
requires	list of CapabilityRequirement	optional	—
effect	identifier (EffectClass)	optional	—
may_produce	list of EvidenceProduction	optional	—
arguments	any JSON value	optional	The JSON Schema, in Canon's argument-schema dialect, that the action's arguments satisfy. Absent: the action takes no arguments; a runner accepts only {}. Canon never validates arguments at run time: the runner that calls the action validates them against the schema, and canon validate holds the schema to the dialect (action-arguments).
case_open	CaseOpening	optional	The child case the action opens (story:case-composition): a case governed by another protocol, about a declared artifact. Absent: the action opens no case. Canon opens nothing itself; whoever takes the action opens the child case. A case has one commission, and a second party works through a child case: this is the one primitive by which a case hands work to another party (D207).

Outcome

A legitimate terminal interpretation of a case and what it requires: a predicate, or an explicit decision (requires: decision: <name>).

Key	Value	Required	Meaning
description	text	optional	—
requires	OutcomeRequirement	required	—

InvalidationRule

An invalidation rule: a change of its upstream artifact's revision invalidates, for the claims it names and every claim built on them, the evidence observed against an earlier revision of that artifact (design § 4.1, CANON-INVALIDATION-001).

Key	Value	Required	Meaning
description	text	optional	—
upstream	identifier (ArtifactId)	required	The artifact whose revision the rule watches.
invalidates	list of identifier (ClaimId)	required	The claims whose support a change of that revision invalidates.

CaseSection

The protocol's case: section.

Key	Value	Required	Meaning
inputs	map from identifier (InputId) to CaseInput	optional	The case inputs, keyed by input id.

IndependenceDimension

One independence dimension: a relation between who produced a record and the case's work, which the trusted context resolves for each producer and Canon reads from the case.

Key	Value	Required	Meaning
description	text	optional	—

Predicate

A predicate over evidence and claim values.

The predicate language: a small, total, deterministic expression language (design § 39.2).

A predicate is one of all, any, not, an evidence match by kind, optional result and optional subject, a test on a claim value, a test on a case input's value, one of the four order forms over the evidence history, or the form over the case's child cases. Written in source as a map with exactly one of the keys all, any, not, evidence, claim, input, first, before, after, since or children; a claim test may add is, which defaults to true, and an input test adds in, the values it is true for ({input: severity, in: [high]}).

The order forms read the evidence history: every record of their kind (about their subject when they name one) that the evidence check accepted, including the records the exclusion stages keep from evidence matches (revision_mismatch, expired, invalidated). A record's place in the order is its observed_at; a record without one has no known place. An evaluation compares every instant at one resolution, the coarsest precision written among the records with an observed_at: each is read with its finer digits dropped, and two records read at one instant are not ordered. Instant below means the instant at the evaluation's resolution. {first: {kind: K, result: R}} asks whether the first record of K has result R: unknown with no record or with a record without observed_at; otherwise, of the records at the earliest instant, true when every one has R, false when none has, unknown when they disagree. {before: {first: K1, then: K2}} asks whether the first record of K1 was observed strictly before the first record of K2: unknown with no record of either, false with a record of K2 and none of K1 (a later K1 record comes after it), unknown with a record of K1 and none of K2, unknown when a record of either has no observed_at, and otherwise true, false or unknown as the earliest instants of K1 and K2 are earlier, later or equal. {after: {first: K1, then: {kind: K2, result: R}}} asks whether some record of K2 with result R was observed strictly after the first record of K1: unknown with no record of K1, false with no record of K2 with R, unknown when a record of K1, or of K2 with R, has no observed_at, and otherwise true when one of K2 with R comes after the earliest instant of K1, unknown when one only shares that instant (other than the first record itself: a record is not later than itself), and false when none comes after it. A record of K2 with another result takes no part. K1 and K2 may be one kind. A known limit: a record bound to any earlier revision counts, whether or not the current revision descends from it, since Canon does not know how revisions descend (story:revision-ordering). {since: {last: K1, then: {kind: K2, result: R}}} asks whether a record of K2 with result R, at the subject and subject revision of the latest record of K1, was observed after that record: unknown with no record of K1, false with no record of K2 with R, unknown when a record of K1, or of K2 with R, has no observed_at; otherwise each latest record of K1 (one no record of K1 is observed after) gives true when a record of K2 with R at its subject and subject revision, other than itself, is observed after it, false when every such record is observed before it or there is none, and unknown otherwise, and the form is true when every latest record gives true, false when every one gives false, and unknown otherwise. A record at a revision descended from the latest record's does not count.

An evidence match may demand independence: {evidence: {kind: K, result: R, independent_on: [D, ...]}} reads a record only when it names a producer and the case's independence map lists that producer on every dimension D (dimensions the protocol declares under independence_dimensions). A record of the match's kind and subject that fails the demand is not of the match, whatever its result: it neither establishes nor contradicts it, and is excluded from it as not_independent (CANON-INDEPENDENCE-001). The order forms do not demand independence.

{children: {in: [O, ...]}} (story:case-composition) asks whether every child case of the case ended with one of the outcomes O. It reads every case_outcome record the evidence check accepted, as the order forms read the history, one record per child case: its child_case names the child, its result the child's outcome, open while the child runs. unknown with no record; false when a record's outcome is neither listed nor open, a child that ended outside the set; otherwise unknown while a child is open, and true when every child ended with a listed outcome. A child's outcome is a fact about the child case, so a record about an earlier revision of its subject, an expired one and an invalidated one still count.

Key	Value	Meaning
all	list of Predicate	True when every member is true; true when empty.
any	list of Predicate	True when some member is true; false when empty.
not	Predicate	—
evidence	EvidenceMatch	—
claim	identifier (ClaimId)	—
is	Truth	Allowed only beside claim.
input	identifier (InputId)	True when the case's value of the input is one of the values listed, false otherwise.
in	list of identifier (InputValue)	Allowed only beside input. The values the test is true for, written in.
first	FirstResult	Whether the first record of a kind, in the evidence history, has a result.
before	EvidenceOrder	Whether the first record of one kind, in the evidence history, was observed strictly before the first record of another.
after	EvidenceAfter	Whether a record of a kind with a result, in the evidence history, was observed strictly after the first record of a kind.
since	EvidenceSince	Whether a record of a kind with a result, at the subject revision of the latest record of a kind in the evidence history, was observed after that record.
children	ChildOutcomes	Whether every child case of the case ended with one of the outcomes listed, over its case_outcome records (story:case-composition).

CapabilityRequirement

One capability an action requires authority for.

Key	Value	Required	Meaning
capability	identifier (CapabilityId)	required	—

EvidenceProduction

One evidence kind an action may produce.

Key	Value	Required	Meaning
evidence	identifier (EvidenceKindId)	required	—

CaseOpening

What an action's case_open names: the protocol the child case is governed by and the artifact it is about, never an existing case. No run-time check keeps a case from opening one under its own protocol (D206): canon validate refuses an opening under the protocol's own id, and the library function b10x_canon::ir::check_openings refuses a set of protocols whose openings form a cycle, naming it in the order its openings go, from its least protocol id.

Key	Value	Required	Meaning
protocol	identifier (ProtocolId)	required	The protocol the child case is governed by.
subject	identifier (ArtifactId)	required	The declared artifact the child case is about.

OutcomeRequirement

What an outcome requires.

Key	Value	Meaning
decision	identifier (DecisionName)	The outcome is legitimate only with an explicit decision of this name, for the outcome, taken at the case snapshot's current revision.
—	Predicate	Written as the Predicate itself, with its keys and no key of its own. The outcome is legitimate when the predicate is true.

CaseInput

A case input: configuration a case fixes when it opens, one of a closed, non-empty list of values. Not evidence, so no evaluation has an unknown input.

Key	Value	Required	Meaning
description	text	optional	—
values	list of identifier (InputValue)	required	The values the input may take.

EvidenceMatch

Matches evidence of one kind, optionally with one result, optionally only evidence about one declared artifact (a match that names a subject reads only the records whose subject it is), and optionally only evidence whose producer the case lists as independent on every dimension independent_on names.

Key	Value	Required	Meaning
kind	identifier (EvidenceKindId)	required	—
result	text	optional	—
subject	identifier (ArtifactId)	optional	—
independent_on	list of identifier (IndependenceDimensionId)	optional	The independence the match demands of a record's producer: declared dimensions, not empty, each once. A match without it reads records whoever produced them.

FirstResult

An order form: whether the first record of kind, about subject when it names one, has result: the records at the earliest instant at the evaluation's resolution. It reads every record of the kind the evidence check accepted, excluded or not.

Key	Value	Required	Meaning
kind	identifier (EvidenceKindId)	required	The evidence kind whose first record is read.
result	text	required	The result that first record is to have.
subject	identifier (ArtifactId)	optional	The declared artifact the records read are about; without it, records about any artifact.

EvidenceOrder

An order form: whether the first record of kind first was observed strictly before the first record of kind then, both about subject when it names one: the earliest instants of the two kinds at the evaluation's resolution, an equal pair not ordered. It reads every record of the two kinds the evidence check accepted, excluded or not.

Key	Value	Required	Meaning
first	identifier (EvidenceKindId)	required	The evidence kind whose first record is to come first.
then	identifier (EvidenceKindId)	required	The evidence kind whose first record is to come after it; another kind than first.
subject	identifier (ArtifactId)	optional	The declared artifact the records of both kinds are about; without it, records about any artifact.

EvidenceAfter

An order form: whether some record of then.kind with result then.result was observed strictly after the first record of kind first, all about subject when it names one: after the earliest instant of first at the evaluation's resolution. It reads every record of the two kinds the evidence check accepted, excluded or not. first and then.kind may be one kind: a record is not later than itself.

Key	Value	Required	Meaning
first	identifier (EvidenceKindId)	required	The evidence kind whose first record the later one is to come after.
then	LaterRecord	required	The record that is to come after it: its kind and its result.
subject	identifier (ArtifactId)	optional	The declared artifact the records of both kinds are about; without it, records about any artifact.

EvidenceSince

An order form: whether a record of then.kind with result then.result, about the subject and subject revision of the latest record of kind last, was observed after that record, all about subject when it names one. It reads every record of the two kinds the evidence check accepted, excluded or not. last and then.kind may be one kind: a record is not later than itself.

Key	Value	Required	Meaning
last	identifier (EvidenceKindId)	required	The evidence kind whose latest record the later one is to come after, at its revision.
then	LaterRecord	required	The record that is to come after it: its kind and its result.
subject	identifier (ArtifactId)	optional	The declared artifact the records of both kinds are about; without it, records about any artifact.

ChildOutcomes

The form over the case's child cases, written {children: {in: [<outcome>, ...]}}: whether every child case ended with one of the outcomes listed. It reads every case_outcome record the evidence check accepted, as the order forms read the history: unknown with no record, false when a record's outcome is neither listed nor open (a child that ended outside the set), otherwise unknown when a child is still open and true when every child ended with a listed outcome.

Key	Value	Required	Meaning
in	list of text	required	The outcomes a child case may have ended with, written in: not empty, each once, never open.

Truth

A three-valued truth value. Unknown is not False.

Written true, false or unknown. A YAML boolean true or false is read as the same value.

Value	Meaning
true	—
false	—
unknown	—

LaterRecord

What an after form reads later than the first record of its first kind, and a since form later than the latest record of its last kind: a record of kind with result.

Key	Value	Required	Meaning
kind	identifier (EvidenceKindId)	required	The evidence kind of the later record.
result	text	required	The result the later record is to have.

Identifiers

An identifier is text. A well-formed identifier is not empty, and without whitespace, control characters or Unicode format characters (general category Cf). Each kind of identifier is its own type, so one cannot stand in for another. These are the kinds a protocol/1 document use:

Type	Identifies
ProtocolId	Identifies a protocol, independently of its revision.
ArtifactId	Identifies an artifact a protocol declares.
ClaimId	Identifies a claim a protocol declares.
EvidenceKindId	Identifies a kind of evidence a protocol declares.
ObligationId	Identifies an obligation a protocol declares.
ActionId	Identifies an action a protocol declares.
OutcomeId	Identifies an outcome a protocol declares.
CapabilityId	Names a capability an action requires authority for.
EffectClass	Names the class of effect an action has.
DecisionName	Names an explicit decision an outcome may require (explicitly_inconclusive).
IndependenceDimensionId	Identifies an independence dimension a protocol declares (different_principal). Canon gives no dimension a meaning; the trusted context that writes the case resolves it.
InvalidationRuleId	Identifies an invalidation rule a protocol declares.
InputId	Identifies a case input a protocol declares.
InputValue	One value a case input may take: an identifier its input declares. Read from any scalar, alike in the protocol and in the case: values: [true, false] declares the values true and false, and a case gives one as flag: true.

Text formats

These values are text in a fixed form, not identifiers. Canon refuses text that does not match its pattern, and also checks what the pattern cannot:

Type	Written as	Pattern
Age	A length of time: a whole number without leading zeros, followed by s, m, h or d (5m, 24h). Canon also refuses an age too long to count in seconds.	^(0|[1-9][0-9]*)[smhd]$