@githonllc/avouch 0.1.7 → 0.1.9

package/README.md

@@ -39,8 +39,10 @@ Read in this order:
 | `src/checker.ts` | `check(ontology, facts)` returns the violations |
 | `src/patch.ts` | JSON-pointer patch that the mutation tests use |
 | `src/query.ts` | read-only queries over an ontology (`avouch query`) |
+| `src/reconcile.ts` | runtime consistency: `reconcile`, `projectSnapshot` (SPEC section 9) |
+| `src/coverage.ts` | decision-row coverage of reconcile rows, with a baseline (`verifyCoverage`, `avouch gate verify`) |
 | `src/markdown.ts` | built-in adapter for plain Markdown sources (`avouch.json`); see `docs/adapter-guide.md` section 7 |
-| `cli/` | command line: `avouch check` (`check.ts`) and `avouch query` (`query.ts`) |
+| `cli/` | command line: `avouch check` (`check.ts`), `avouch query` (`query.ts`), `avouch reconcile` (`reconcile.ts`) and `avouch gate verify` (`gate.ts`) |
 | `tsconfig.build.json` | configuration for the JavaScript and type declaration build |
 | `dist/` | build output; not tracked in version control |
 | `examples/library/` | toy project: source document, ontology, mutations, adapter, profile, evidence |
@@ -60,6 +62,9 @@ A project supplies an adapter and a profile. The adapter reads the project's sou
 - `test/cli.test.ts`: command line results, schema errors, checker violations and adapter errors.
 - `test/query.test.ts`: the query functions on the toy ontology and on patched variants of it.
 - `test/query-cli.test.ts`: `avouch query`: the JSON envelope, the stamp (git and check), exit codes, text output, and that a query writes no file.
+- `test/coverage.test.ts`: `verifyCoverage` on the toy ontology and on patched variants of it: units, gaps, stale baseline entries, failing reconcile rows, and the shape checks.
+- `test/reconcile-cli.test.ts`: `avouch reconcile`: JSON lines in and out, exit codes, and the line number in each input error.
+- `test/gate-cli.test.ts`: `avouch gate verify`: the pipeline from cases to the gate, text and JSON output, the check with `--adapter`, and exit codes.
 - `test/markdown.test.ts`: the built-in Markdown adapter: the toy library gives the same findings as with its own adapter (outside the rules the generic adapter cannot check), and each parse convention.
 - `test/boundary.test.ts`: the runtime (`src/` and `examples/`) imports only relative paths inside this package. It imports no npm package and no file outside the package.
 
@@ -118,6 +123,71 @@ The stamp tells which specification answered:
 
 Exit code 0 means there is a result. 1 means there is no result: the id is not declared, or the list is empty (the envelope is still printed). 2 means invalid arguments, or a file, parsing or adapter error.
 
+## Runtime consistency on the command line
+
+`avouch reconcile` compares the result that the runtime reported with the result of the evaluator and with the scenario expectation (SPEC section 9, Runtime consistency). `avouch gate verify` checks that the reconciled cases cover each decision row. Both commands read files and write no file. They do not run project code: the project's test harness writes the cases.
+
+```sh
+avouch reconcile <ontology.yaml> --cases <cases.jsonl>
+avouch gate verify <ontology.yaml> --rows <rows.jsonl> [--baseline <baseline.json>] [--json] [--adapter <module|config.json>]
+```
+
+### reconcile
+
+The cases file has one `RuntimeCase` (SPEC section 9) per line, as JSON. Empty lines are skipped. A case can have more keys than `RuntimeCase`; they are ignored. The command prints one `ReconcileRow` per case, as one JSON line, in input order. For example, `avouch reconcile library.ontology.yaml --cases cases.jsonl > rows.jsonl` writes the input of `gate verify`.
+
+Exit code 0 means that each case gave a row, also a `mismatch` or a `cannot_reconcile` row: the command does not judge the rows. 2 means invalid arguments, a file or parse error, or a line that is not a `RuntimeCase`; the message gives the file and the line number. The command does not use exit code 1.
+
+### gate verify
+
+The unit of coverage is the decision row. Each row of a decision table and its `otherwise` is one unit. A unit has the name `<action>:rows.<i>` (`i` from 0) or `<action>:otherwise`, as in the R12 keys. A unit is verified when a `match` row has its action, its `row` and the result of that row. A `mismatch` row does not verify its unit. An action without a decision table has no units; it is printed as `no_table` and does not change the result. The command checks every action of the ontology.
+
+Verified means: for one case, `decide` reached this row, and the runtime result and the expected result are the same as the result of `decide`. The runtime does not report which row it ran. A case without an expected result never verifies a unit: `reconcile` gives `expectation_missing` for it, and the gate prints it as `unasserted`. An action with `permission: unknown` never reaches its decision table in `decide`, so all its units stay as `uncovered` entries until the permission is written.
+
+A gap is a condition that a decision row names and that is declared without an expression (`unspecified`). `decide` stops at the first row that names a gap, so the units from that row to `otherwise` are blocked: they are printed as `blocked` and are not reported as uncovered. Each gap needs an exemption with a reason in the baseline. When a gap gets an expression, the units it blocked become ordinary units. The change that adds the expression must also add cases or `uncovered` entries for them.
+
+The baseline is a JSON file. In this example, the condition `loan_active` has no expression:
+
+```json
+{
+  "avouchCoverage": 1,
+  "uncovered": [
+    { "action": "BORROW", "row": 3, "when": { "fails": "returns_in_good_condition" }, "result": "REFERRED" },
+    { "action": "BORROW", "row": "otherwise", "when": null, "result": "BORROWED" }
+  ],
+  "exempt": [
+    { "action": "RETURN", "condition": "loan_active", "kind": "unspecified", "reason": "the source does not state when a loan is active" }
+  ]
+}
+```
+
+- `uncovered` lists units that have no `match` yet, each with the `when` and `result` of its row. An entry for a unit that is now verified fails the gate. The tool does not stop new entries; review the baseline diff for that.
+- `exempt` lists gaps, each with a non-empty `reason`.
+- Both keys are required. A key that is not shown above is an error (exit code 2).
+- Without `--baseline`, both lists are empty.
+- Units are named by position. When rows are added, removed or moved, the positions change; an `uncovered` entry whose `when` or `result` is not the same as in the ontology is stale (`moved`).
+
+The canonical form of the file is `JSON.stringify(baseline, null, 2)` with a final line break, the keys in the order shown above, `uncovered` in unit order (actions in code-unit order, then rows from 0, then `otherwise`) and `exempt` in action order, then condition order. The gate does not check the form. `--json` prints `uncovered` and `unexempted` in the shape and order of the baseline entries; to make a first baseline, copy them and add a reason to each `unexempted` entry.
+
+The gate fails (exit code 1) when:
+
+| Output | Cause |
+|---|---|
+| `uncovered` | a unit has no `match`, is not blocked, and is not in `uncovered` of the baseline |
+| `unexempted` | a gap has no entry in `exempt` |
+| `unreasoned` | an `exempt` entry has no reason, or only white space |
+| `stale` | an `uncovered` entry names a unit that does not exist, that has another `when` or `result` (`moved`), that is verified or that is blocked, or repeats an entry; an `exempt` entry names a condition that is not a gap, or repeats an entry |
+| `failed` | a reconcile row names an action that the ontology does not have (`action_unknown`); a reconcile row is a `mismatch`; a `cannot_reconcile` row has the reason `runtime_missing`, `runtime_unmapped`, `expectation_unmapped`, `snapshot_missing` or `evaluator_error`, or the reason `indeterminate` with the detail `no_row_matched`; a `match` row names a row that the action does not have, or a result that is not the result of that row (`row_unknown`) |
+| `check` | with `--adapter`, the same check as `avouch check` fails |
+
+The reasons `envelope`, `expectation_missing` and `indeterminate` with another detail do not fail the gate. A replay is not a decision; a case without an expectation states nothing to compare. An `indeterminate` result does not fail the gate, except `no_row_matched`; the units that it leaves unverified stay `uncovered` or `blocked`, so the gate still sees them. `no_row_matched` means that no row applies and the table has no `otherwise`.
+
+Known limit: when a case has no expected result, `reconcile` gives `expectation_missing` before it checks the runtime result. So the gate does not see a runtime result that the action cannot give (`runtime_unmapped`) in such a case.
+
+Exit code 0 means the gate passes. 1 means it fails. 2 means invalid arguments (also a repeated option), a file or parse error, an ontology without an `actionTypes` mapping, or a rows or baseline file with a wrong shape. Without `--json`, the command prints one `FAIL` line for each failure, `INFO` lines (`check`, `blocked`, `no_table`, `unasserted`), and a summary line that starts with `PASS` or `FAIL`. `--json` prints `{avouchGate: 1, gate: "verify", check, result}`.
+
+The same gate is a function in the package root, for tests that run without a file system or child processes: `verifyCoverage(ontology, rows, baseline)` returns the `result` object (`src/coverage.ts`). The command is a thin wrapper around it. The function does not run the check.
+
 ## Claude Code plugin
 
 This repository is also a Claude Code plugin marketplace. Install the plugin:

package/SPEC.md

@@ -28,6 +28,17 @@ Only generic needs go into the format. A special-case need stays in the project
 
 Example: objects shared by several contexts (a shared kernel) are a cross-project pattern. The format already expresses them: the shared objects get their own context, and actions that write them declare `crossContext`. An exemption such as "writes to shared objects need no declaration" fails criteria 2 and 3, so it is not in the format.
 
+### Limit of the expression language
+
+The expression language (section 9) is a restricted predicate language that can be checked statically. It reads domain facts and decides the conditions of decision tables. It is not a language in which a project implements its rules, for two reasons: the ontology states the rules independently of the runtime, so that agreement in `reconcile` means something; and the static checks of section 9 (types, the UNKNOWN analysis) must stay decidable.
+
+So a new expression node must meet the three criteria above and do one of these two things:
+
+- read a fact that no node reads now: of the snapshot, the invocation or the caller, including a field of a parameter or of a stored value;
+- decide a bounded claim over facts: a comparison, a quantifier over a finite collection, or a count or sum over a finite collection inside a comparison.
+
+Value nodes such as `{lit}`, `plus` and `dateIn` only give a comparison its operands. Not admitted: user-defined functions, recursion, unbounded iteration, nodes that build new collections, records or strings, and other arithmetic than `plus`, `dateIn` and the count or sum above.
+
 ## 2. Concepts
 
 A key is foundation when Palantir Foundry has the same concept (names follow https://www.palantir.com/docs/foundry/ontology/overview/ and the pages for each type). A key is extension when Palantir has no analog; the rule that uses it is named.
@@ -46,7 +57,7 @@ The definitions quoted in the "Palantir analog" column are short quotations from
 | `derivedProperties.<d>.expr` / `cite` / `type` | foundation | derived property definition | the definition as an expression over `self` (instead of `reads`), its source text and its declared type; a predicate expression has type `boolean`; without `expr` the derived property is undefined for evaluation; R1, R2, R4, R12 |
 | `linkTypes` | foundation | link type: "the schema definition of a relationship between two object types" | `via` / `table` map to a foreign key or a many-to-many datasource; `create_rule` is an extension (R5) |
 | `actionTypes` | foundation | action type: "the schema definition of a set of changes or edits to objects, property values, and links that a user can take at once" | |
-| `actionTypes.<A>.parameters` | foundation | action parameter: "Parameters are the inputs of an action type." | name → `{cite, type?, optional?, values?}`; read by a condition as `{param}` or, in an expression, `{ref}`; `type` is needed when an expression reads it; `optional: true` lets the caller omit it; `values` (only with `type: enum`) is the value domain of the parameter; R1, R2 |
+| `actionTypes.<A>.parameters` | foundation | action parameter: "Parameters are the inputs of an action type." | name → `{cite, type?, optional?, values?, projectedFrom?}`; read by a condition as `{param}` or, in an expression, `{ref}`; `type` is needed when an expression reads it; `optional: true` lets the caller omit it; `values` (only with `type: enum`) is the value domain of the parameter; `projectedFrom` lists the request fields that the project resolves to this ref; it takes effect only on a `type: {ref: <Object>}` parameter with at least one field, and such a projected parameter is always given, also when optional (section 9); on any other parameter R1 reports it and `decide` ignores it; R1, R2 |
 | `conditions` | foundation + constraint | submission criteria: "the conditions that determine whether an action can be submitted"; Palantir submission criteria ≈ the rows whose disposition class is `rejected` | named Boolean claims `{id, expr \| unspecified, reads?, reads_unspecified?, cites[{cite}], scenarios?}`: `expr` is the claim as an expression (section 9); `unspecified` says it is not written as one, and `reads` may then list what it reads (properties, parameters `{param, values?}`, the caller `{actor: id}` / `{actor: keys}`); R1, R4, R12 |
 | `decision` | extension | none | decision table `{hitPolicy: first, order?: {cite}, rows: [{when: {passes \| fails: <condition>}, result, cites, next?}], otherwise?: {result, cites, next?}}`; `next` is `{actions}`, `{external, cite}` or `{unspecified}`; R1, R12 |
 | `edits` / `creates` / `deletes` | foundation | action rules: modify / create / delete object | `deletes` is a hard delete of datasource rows; a soft delete is an `edits` |
@@ -104,8 +115,8 @@ The adapter may read the ontology instance (for example to list action ids in a
 
 | Rule | Checks | Facts used | Guarantee | Not guaranteed |
 |---|---|---|---|---|
-| R1 | shape, references resolve (a `{param}` read names a parameter of its action; `actor` is `id` or `keys`), ids unique, `formatVersion`, evidence ids exist; expressions type-check (section 9; the properties, parameters and derived properties they read declare `type`; `self` only in derived expressions; quantifier variables do not reuse reserved or bound names; set literals are non-empty with one element type), derived properties have exactly one of `expr` / `reads` and form no cycle, a derived `expr` has `type` and `cite`; a condition has exactly one of `expr` / `unspecified`, `reads` only with `unspecified`; duplicate condition ids are R1 (implementation decision: each entry with an `expr` is type-checked, but every entry with that id takes its type error, R4 reads and literals, and the R12 derived-property part from the last entry with that id that has an `expr`; the static UNKNOWN analysis also uses that last entry, while `decide` evaluates the first entry with that id); `scope` types are declared object types, each listed once; disposition ids are not invocation results; decision rows name a condition of the action and a disposition, only `pending` results have `next` (and must), `next.actions` are declared actions; `principals` is `{kinds: [distinct], cite}`; `idempotencyKey` is `{required: boolean, cite}`; a parameter with `values` has `type: enum` and a non-empty list of distinct non-empty strings, and a string literal compared with that parameter (`eq` / `neq` with `{ref: <name>}` on the other side, or every element of the set literal in `in [{ref: <name>}, {lit: [..]}]`) must be one of its `values` (else a type error); with `config.idempotencyDeclarationRequired: true` (default `false`) an action without `idempotencyKey` fails `idempotency_undeclared` (key `<ID>`) | `config.actionIdPattern`, `config.stateProperty`, `evidence` keys, `config.idempotencyDeclarationRequired` | structure is well-formed | that an expression means what its cite says |
-| R2 | anchors unique, quotes verbatim (also under `derivedProperties`, `scope` and `dispositions`), properties are fields, names in the store catalog, parameter names appear in their quote (`parameter_not_in_quote`), and so does each of a parameter's `values` (`parameter_value_not_in_quote`, key `<ID>:<name>:<value>`); with `scope`: each tenant type's field list has `<by>` (`scope_field_missing`, key `<Object>.<by>`), no global type's field list has it (`scope_field_present`), `<by>` is in the scope quote (`scope_by_not_in_quote`, key `scope`); each disposition id is in its own quote (`disposition_not_in_quote`, key `dispositions.<ID>`); a declared `type` has a cite (`type_without_provenance`, key `<Object>.<prop>` or `derivedProperties.<id>`; a derived property with `expr` and no cite is R1 only) | `section`, `containsTerm`, `fieldList`, `storeCatalog` | quotes exist in the source | that a quote supports the claim |
+| R1 | shape, references resolve (a `{param}` read names a parameter of its action; `actor` is `id` or `keys`), ids unique, `formatVersion`, evidence ids exist; expressions type-check (section 9; the properties, parameters and derived properties they read declare `type`; `self` only in derived expressions; quantifier variables do not reuse reserved or bound names; set literals are non-empty with one element type), derived properties have exactly one of `expr` / `reads` and form no cycle, a derived `expr` has `type` and `cite`; a condition has exactly one of `expr` / `unspecified`, `reads` only with `unspecified`; duplicate condition ids are R1 (implementation decision: each entry with an `expr` is type-checked, but every entry with that id takes its type error, R4 reads and literals, and the R12 derived-property part from the last entry with that id that has an `expr`; the static UNKNOWN analysis also uses that last entry, while `decide` evaluates the first entry with that id); `scope` types are declared object types, each listed once; disposition ids are not invocation results; decision rows name a condition of the action and a disposition, only `pending` results have `next` (and must), `next.actions` are declared actions; `principals` is `{kinds: [distinct], cite}`; `idempotencyKey` is `{required: boolean, cite}`; a parameter with `values` has `type: enum` and a non-empty list of distinct non-empty strings, and a string literal compared with that parameter (`eq` / `neq` with `{ref: <name>}` on the other side, or every element of the set literal in `in [{ref: <name>}, {lit: [..]}]`) must be one of its `values` (else a type error); a parameter with `projectedFrom` has `type: {ref: <Object>}` and a non-empty list of distinct non-empty field names; with `config.idempotencyDeclarationRequired: true` (default `false`) an action without `idempotencyKey` fails `idempotency_undeclared` (key `<ID>`) | `config.actionIdPattern`, `config.stateProperty`, `evidence` keys, `config.idempotencyDeclarationRequired` | structure is well-formed | that an expression means what its cite says |
+| R2 | anchors unique, quotes verbatim (also under `derivedProperties`, `scope` and `dispositions`), properties are fields, names in the store catalog, parameter names appear in their quote (`parameter_not_in_quote`), or, for a projected parameter, each of its fields (`projection_field_not_in_quote`, key `<ID>:<name>:<field>`), and so does each of a parameter's `values` (`parameter_value_not_in_quote`, key `<ID>:<name>:<value>`); with `scope`: each tenant type's field list has `<by>` (`scope_field_missing`, key `<Object>.<by>`), no global type's field list has it (`scope_field_present`), `<by>` is in the scope quote (`scope_by_not_in_quote`, key `scope`); each disposition id is in its own quote (`disposition_not_in_quote`, key `dispositions.<ID>`); a declared `type` has a cite (`type_without_provenance`, key `<Object>.<prop>` or `derivedProperties.<id>`; a derived property with `expr` and no cite is R1 only) | `section`, `containsTerm`, `fieldList`, `storeCatalog` | quotes exist in the source | that a quote supports the claim |
 | R3 | graph equality, terminal states, reachability, `by` = triggers, `by` iff the action edits the state property | `stateMachines`, `transitionTriggers`, `config.stateProperty` | ontology matches the source machine | trigger-cell conditions; objects without a machine in the source |
 | R4 | conditions read only canonical and policy properties, for an expression also through the derived properties it reaches (parameter and actor reads are request inputs, not state, and are not classified; a derived property without `expr` is not expanded; a hand-written `reads` entry that names a derived property is expanded through its `reads`, or, when it has an `expr`, through the properties that expression reads, as for an expression condition); a non-canonical property passes when every read compares it by `eq` / `neq` with a literal in its `canonical_values`; canonical values and the values of a parameter read appear in their quote (`parameter_value_unsupported`); each literal of an expression appears in one of its condition's quotes, or in the derived property's quote (`literal_unsupported`, key `<ID>:<condition id>:<value>` or `derivedProperties.<id>:<value>`) | none | the property reads of conditions are canonical or policy facts; literals are not invented | that `reads` is complete; that an expression's logic matches its cite |
 | R5 | object membership, cross-context declaration (`via` or `unspecified`), `create_rule`, entity coverage | `contextMembers`, `config.crossContextMechanisms` | object ownership matches the source | the content of the mechanism |
@@ -146,7 +157,7 @@ The table lists only the optional facts. Every rule may also read the required f
 
 ## 8. Versions
 
-The version is in two places: `v1` in the schema `$id`, and `formatVersion: 1` in the ontology file (R1 fails on any other value). A change that breaks existing ontologies raises both. A change that rejects only files without meaning (for example an empty name) is not a break. Adding the `permission.any_of` form is additive: existing files stay valid, so `formatVersion` stays 1. Adding `parameters` and the parameter and actor reads of the submission criteria (since renamed `conditions`) is additive: existing files stay valid, so `formatVersion` stays 1. Adding `values` on enum parameters is additive; `formatVersion` stays 1. Adding `deletes` is additive; `formatVersion` stays 1.
+The version is in two places: `v1` in the schema `$id`, and `formatVersion: 1` in the ontology file (R1 fails on any other value). A change that breaks existing ontologies raises both. A change that rejects only files without meaning (for example an empty name) is not a break. Adding the `permission.any_of` form is additive: existing files stay valid, so `formatVersion` stays 1. Adding `parameters` and the parameter and actor reads of the submission criteria (since renamed `conditions`) is additive: existing files stay valid, so `formatVersion` stays 1. Adding `values` on enum parameters is additive; `formatVersion` stays 1. Adding `deletes` is additive; `formatVersion` stays 1. Adding `projectedFrom` on ref parameters is additive; `formatVersion` stays 1.
 During 0.x the v1 draft changes in place (`formatVersion` 1, `$id` v1); the rule above applies from the 1.0 semantic freeze.
 
 ## 9. Decision semantics
@@ -155,7 +166,7 @@ Stage 1A; runtime consistency is Stage 1B. Code: `src/expr.ts` (AST, types, stat
 
 ### Expressions and two-level evaluation
 
-Every node is a single-key map. The reserved names `now`, `actor` and `self` are exported as `RESERVED_NAMES`. The node set is fixed (`EXPR_NODES`):
+Every node is a single-key map. The reserved names `now`, `actor` and `self` are exported as `RESERVED_NAMES`. The node set is fixed (`EXPR_NODES`); section 1, "Limit of the expression language", says which new nodes can be admitted:
 
 | Level | Nodes | Result |
 |---|---|---|
@@ -220,7 +231,7 @@ Nullability comes from the facts and the parameters; only this analysis treats u
 
 - `fieldList` gives each field with `nullable` (a trailing `?` in the source). A field is non-null only when its object's field list says `nullable: false`. Unknown nullability is analysed as may-be-null: a field that is not listed, or an object without a field list (R2 reports both).
 - `now` and `actor.id` / `actor.keys` are never null. A quantifier variable or `self` is not null; its property `x.prop` may be null unless the field is non-null.
-- An optional parameter may be null, and so may every property read through it. A required parameter is not null (a missing one is `INVALID_BINDING`); its property may be null unless the field is non-null.
+- An optional parameter may be null, and so may every property read through it. A required parameter is not null (a missing one, or a null projected one, is `INVALID_BINDING`); its property may be null unless the field is non-null.
 
 Counting: the analysis collects the distinct normalized paths that may be null and that the outer evaluation reads (`self` is replaced by the `of` of the derived property that is inlined). Reads only inside a quantifier are not counted, because a quantifier is T or F outside; a read that also occurs outside a quantifier is counted there. The `from` of a navigation is never counted: a null ref navigates to the empty set, not to U. With k paths, all 2^k combinations are evaluated; for k > 8 (`MAX_NULLABLE_REFS`) the condition is taken as may-be-U without enumeration. A quantifier body is analysed on its own with the same evaluator and the same counting, its variable added to the visible names; a quantifier nested in the body is again T or F there and is analysed on its own.
 
@@ -264,14 +275,24 @@ A request-shape check before `decide` (so before its shape step), permission and
 
 | Step | Result |
 |---|---|
-| shape (no snapshot read): undeclared parameter (first by sorted name), missing required parameter (absent or null, in declaration order), value not fitting its type, or an `enum` value not among the parameter's `values` | `INVALID_BINDING` with `unknown_param`, `missing`, `type` |
+| shape (no snapshot read): undeclared parameter (first by sorted name), missing parameter (in declaration order: a required one that is absent or null, except a null projected parameter; a projected parameter that is absent, also when optional), value not fitting its type, or an `enum` value not among the parameter's `values` | `INVALID_BINDING` with `unknown_param`, `missing`, `type` |
 | permission: each alternative is denied (a key missing, or `principals: {kinds, cite}` whose `kinds` lacks `actor.kind`; the cite is not read), passed (all keys and conditional keys), or undecided (only conditional keys missing); the `{none}` form passes, or is denied when its `principals` `kinds` lacks `actor.kind` (never undecided) | `PERMISSION_DENIED`; INDETERMINATE `permission_condition` / `permission_unknown` |
 | envelope (idempotency) | `REPLAYED`, `IDEMPOTENCY_CONFLICT`; **not implemented by `decide`**, which has no idempotency key |
-| binding and scope: parameters are checked in declaration order, across all parameters (scalar ref and `{set: {ref: T}}`), and the first failing parameter gives the result; each ref parameter is looked up in its own type only; each element of a `{set: {ref: T}}` parameter is bound the same way, in array order, and the first failing element gives the result | `SCOPE_DENIED` (the id exists only outside the scope), `INVALID_BINDING` `not_found` (absent from the type, including ids of other types) |
+| binding and scope: parameters are checked in declaration order, across all parameters (scalar ref and `{set: {ref: T}}`), and the first failing parameter gives the result; each ref parameter is looked up in its own type only; each element of a `{set: {ref: T}}` parameter is bound the same way, in array order, and the first failing element gives the result; a required projected parameter with the value null fails as `not_found` | `SCOPE_DENIED` (the id exists only outside the scope), `INVALID_BINDING` `not_found` (absent from the type, including ids of other types) |
 | decision: first-hit table | a domain result `{result, class, row}` or INDETERMINATE |
 
 The invocation results are a fixed set (`INVOCATION_RESULTS`), not declared by actions. A null optional ref binds; reading its properties gives null. Invalid input (unknown action, scope argument against the declaration, an ill-typed condition, an untyped parameter, a parameter named `now`, `actor` or `self`, a decision row naming an unknown condition, a decision row or `otherwise` whose `result` has no disposition, a type both global and root, a corrupt or incomplete snapshot) throws; it is never a result. A row without a field that evaluation reads (such as the scope field) is incomplete; a field with the value null is not.
 
+Projected parameters. A `{ref: T}` parameter with `projectedFrom: [<field>, …]` (at least one field) is projected: it is not a field of the request. The project's projection reads those request fields (an alternate key, for example `source` and `external_ref`) and looks up the object of the parameter's ref type as the runtime looks it up: with the same scope rules (only in the caller's scope for a tenant or root type; everywhere for a global type) and the same soft delete filter. It never passes the id of an object outside the scope. When a key field is missing from the request, the projection omits the binding; when no object has the key, it passes null; else it passes the id. Null is not the same as an absent binding:
+
+| Binding | Required parameter | Optional parameter |
+|---|---|---|
+| absent | `INVALID_BINDING` `missing` (shape) | `INVALID_BINDING` `missing` (shape) |
+| null | `INVALID_BINDING` `not_found` (binding and scope), as for an id that does not resolve | an ordinary value, for example "no other object has this key", which a condition tests with `isNull` |
+| id | bound as any ref parameter | bound as any ref parameter |
+
+An absent binding is a valid input (the request lacks a key field); when the runtime gives another result, `reconcile` shows the difference as a mismatch. On any other parameter (another type, for example `{set: {ref: T}}`, or no field) R1 reports `projectedFrom` and `decide` ignores it: the parameter behaves as without `projectedFrom`. The format does not read the fields or their values; it has no alternate-key model.
+
 ### Decision table and INDETERMINATE
 
 `passes(c) := eval(c) = T`; `fails(c) := eval(c) != T`. Rows are tried in order; the first hit gives `{layer: domain, result, class, row, next?}`, with `class` from `dispositions`. Only the rows actually reached matter. INDETERMINATE is neither an invocation result nor a domain result, and is never filled in as rejected or applied. Its reasons:
@@ -332,6 +353,8 @@ The physical type mapping is checked here: the profile supplies `decode`, which
 
 `Invocation.disposition` stays the optional Stage 0 field of the fact contract. `reconcile` does not read it.
 
+The command line reads and writes these types as JSON lines, one `RuntimeCase` or one `ReconcileRow` per line (`avouch reconcile`, `avouch gate verify`; README, "Runtime consistency on the command line"). A `Value` is a JSON string, number, boolean, null or array. An optional field that is absent (`reason`, `detail`, `row`, a binding that is not given) is an absent key; a binding with the value null is `null`. The coverage rule of `avouch gate verify` is a rule of the tool, not of this format.
+
 ### Existence is not revealed
 
 `SCOPE_DENIED` is internal. `externalResult` maps it and `INVALID_BINDING` `not_found` to one value, `{result: INVALID_BINDING, param, reason: not_found}`, so a caller cannot learn that an id exists in another tenant. Other reasons, such as `type`, are reported as they are. A runtime must not report `SCOPE_DENIED`; `reconcile` gives `runtime_unmapped` for it. A scenario must not expect it either; `reconcile` gives `expectation_unmapped` for it (step 7).
@@ -339,3 +362,5 @@ The physical type mapping is checked here: the profile supplies `decode`, which
 ### Known limit
 
 `dateIn` uses the time zone data of the runtime. Near a time zone rule change the evaluator and another runtime with a different tzdata version may give different dates.
+
+An optional projected parameter carries a fact that the project computes from the same database as the runtime, for example the object that already holds a unique key. Avouch checks the decision given that fact, not whether the fact is right. When the projection and the runtime are wrong in the same way (for example the projection passes null and the runtime has lost its unique index), they agree and `reconcile` gives `match`.

package/dist/cli/avouch.js

@@ -2,7 +2,9 @@
 import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { CONFIG_FILE, runCheck } from "./check.js";
+import { GATE_USAGE, runGate } from "./gate.js";
 import { QUERY_USAGE, runQuery } from "./query.js";
+import { RECONCILE_USAGE, runReconcile } from "./reconcile.js";
 const CHECK_USAGE = "usage: avouch check <ontology.yaml> [--adapter <module|config.json>]";
 async function check(args) {
     let adapter;
@@ -38,8 +40,14 @@ async function main() {
         return check(args.slice(1));
     if (args[0] === "query")
         return runQuery(args.slice(1));
+    if (args[0] === "reconcile")
+        return runReconcile(args.slice(1));
+    if (args[0] === "gate")
+        return runGate(args.slice(1));
     console.error(CHECK_USAGE);
     console.error(QUERY_USAGE);
+    console.error(RECONCILE_USAGE);
+    console.error(GATE_USAGE);
     return 2;
 }
 try {

package/dist/cli/gate.d.ts

@@ -0,0 +1,2 @@
+export declare const GATE_USAGE = "usage: avouch gate verify <ontology.yaml> --rows <rows.jsonl> [--baseline <baseline.json>] [--json] [--adapter <module|config.json>]";
+export declare function runGate(args: string[]): Promise<number>;

package/dist/cli/gate.js

@@ -0,0 +1,88 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { verifyCoverage } from "../src/coverage.js";
+import { runCheck } from "./check.js";
+import { readJsonLines } from "./jsonl.js";
+import { parseOptions, readOntology } from "./reconcile.js";
+export const GATE_USAGE = "usage: avouch gate verify <ontology.yaml> --rows <rows.jsonl> [--baseline <baseline.json>] [--json] [--adapter <module|config.json>]";
+const unitText = (row) => (row === "otherwise" ? "otherwise" : `rows.${row}`);
+function text(check, r, pass) {
+    const lines = [];
+    if (check.status === "fail")
+        lines.push(`FAIL check: ${check.schemaErrors} schema error(s), ${check.violations} violation(s)`);
+    for (const u of r.uncovered)
+        lines.push(`FAIL uncovered ${u.action}:${unitText(u.row)}`);
+    for (const g of r.unexempted)
+        lines.push(`FAIL unexempted ${g.action}:${g.condition}`);
+    for (const g of r.unreasoned)
+        lines.push(`FAIL unreasoned ${g.action}:${g.condition}`);
+    for (const s of r.stale)
+        lines.push(s.list === "uncovered" ? `FAIL stale uncovered ${s.action}:${unitText(s.row)} ${s.why}` : `FAIL stale exempt ${s.action}:${s.condition} ${s.why}`);
+    for (const f of r.failed)
+        lines.push(`FAIL case ${f.id} ${f.action} ${f.why}`);
+    lines.push(`INFO check ${check.status}`);
+    for (const b of r.blocked)
+        lines.push(`INFO blocked ${b.action}:${unitText(b.row)} by ${b.condition}`);
+    for (const a of r.noTable)
+        lines.push(`INFO no_table ${a}`);
+    for (const c of r.unasserted)
+        lines.push(`INFO unasserted ${c.id} ${c.action}`);
+    lines.push(`${pass ? "PASS" : "FAIL"}: ${r.units} unit(s), ${r.verified.length} verified, ${r.baselined.length} baselined, ${r.blocked.length} blocked, ` +
+        `${r.uncovered.length} uncovered; ${r.unexempted.length} unexempted, ${r.unreasoned.length} unreasoned, ${r.stale.length} stale, ` +
+        `${r.failed.length} failed case(s), ${r.unasserted.length} unasserted`);
+    return lines.join("\n") + "\n";
+}
+async function verify(args) {
+    const { pos, opts } = parseOptions(args, ["--rows", "--baseline", "--adapter"], ["--json"]);
+    if (pos.length !== 1)
+        throw new Error(`expected 1 argument, found ${pos.length}`);
+    const rowsFile = opts.get("--rows");
+    if (typeof rowsFile !== "string")
+        throw new Error("--rows is required");
+    const baselineFile = opts.get("--baseline");
+    const adapter = opts.get("--adapter");
+    const ont = readOntology(pos[0]);
+    const rows = readJsonLines(rowsFile);
+    let baseline = null;
+    if (baselineFile !== undefined) {
+        const raw = readFileSync(resolve(baselineFile), "utf8");
+        try {
+            baseline = JSON.parse(raw);
+        }
+        catch (error) {
+            throw new Error(`${baselineFile}: invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    let result;
+    try {
+        result = verifyCoverage(ont, rows, baseline);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new Error(`${msg.startsWith("baseline:") ? baselineFile : msg.startsWith("ontology:") ? pos[0] : rowsFile}: ${msg}`);
+    }
+    let check = { status: "not_run" };
+    if (adapter !== undefined) {
+        const { schemaErrors, report } = await runCheck(pos[0], adapter);
+        const pass = schemaErrors.length === 0 && report.violations.length === 0;
+        check = { status: pass ? "pass" : "fail", adapter, schemaErrors: schemaErrors.length, violations: report.violations.length, waived: report.waived.length };
+    }
+    const pass = result.ok && check.status !== "fail";
+    process.stdout.write(opts.get("--json") === true ? `${JSON.stringify({ avouchGate: 1, gate: "verify", check, result }, null, 2)}\n` : text(check, result, pass));
+    return pass ? 0 : 1;
+}
+// Exit 0: the gate passes; 1: it fails; 2: a usage, file, parse or shape error, or an adapter error (one stderr line).
+export async function runGate(args) {
+    try {
+        if (args.length === 0)
+            throw new Error("missing gate");
+        if (args[0] !== "verify")
+            throw new Error(`unknown gate ${args[0]}`);
+        return await verify(args.slice(1));
+    }
+    catch (error) {
+        const msg = (error instanceof Error ? error.message : String(error)).replace(/[\r\n]+/g, " ");
+        console.error(`${msg}; ${GATE_USAGE}`);
+        return 2;
+    }
+}

package/dist/cli/jsonl.d.ts

@@ -0,0 +1,5 @@
+export declare function jsonLines(file: string): {
+    line: number;
+    value: unknown;
+}[];
+export declare function readJsonLines(file: string): unknown[];

package/dist/cli/jsonl.js

@@ -0,0 +1,20 @@
+import { readFileSync } from "node:fs";
+// One JSON value per line, with its line number (from 1). Lines that are empty or only white space are skipped; the
+// line numbers count them.
+export function jsonLines(file) {
+    return readFileSync(file, "utf8")
+        .split("\n")
+        .flatMap((text, i) => {
+        if (text.trim() === "")
+            return [];
+        try {
+            return [{ line: i + 1, value: JSON.parse(text) }];
+        }
+        catch (error) {
+            throw new Error(`${file}:${i + 1}: invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+}
+export function readJsonLines(file) {
+    return jsonLines(file).map((x) => x.value);
+}

package/dist/cli/reconcile.d.ts

@@ -0,0 +1,7 @@
+export declare const RECONCILE_USAGE = "usage: avouch reconcile <ontology.yaml> --cases <cases.jsonl>";
+export declare function parseOptions(args: string[], values: readonly string[], flags: readonly string[]): {
+    pos: string[];
+    opts: Map<string, string | true>;
+};
+export declare function readOntology(file: string): Record<string, unknown>;
+export declare function runReconcile(args: string[]): Promise<number>;

package/dist/cli/reconcile.js

@@ -0,0 +1,110 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parse } from "yaml";
+import { isObj } from "../src/expr.js";
+import { reconcile } from "../src/reconcile.js";
+import { jsonLines } from "./jsonl.js";
+export const RECONCILE_USAGE = "usage: avouch reconcile <ontology.yaml> --cases <cases.jsonl>";
+const REASONS = ["missing", "unknown_param", "type", "not_found"];
+// Options in any position. Returns the positional arguments and the value of each option.
+export function parseOptions(args, values, flags) {
+    const pos = [];
+    const opts = new Map();
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (opts.has(a))
+            throw new Error(`repeated option ${a}`);
+        if (flags.includes(a))
+            opts.set(a, true);
+        else if (values.includes(a)) {
+            if (i + 1 >= args.length)
+                throw new Error(`${a} needs a file`);
+            opts.set(a, args[++i]);
+        }
+        else if (a.startsWith("--"))
+            throw new Error(`unknown option ${a}`);
+        else
+            pos.push(a);
+    }
+    return { pos, opts };
+}
+export function readOntology(file) {
+    const ont = parse(readFileSync(resolve(file), "utf8"));
+    if (!isObj(ont))
+        throw new Error(`${file}: the root is not a mapping`);
+    return ont;
+}
+// The shape of a RuntimeCase (SPEC section 9). Extra keys are allowed; the snapshot content is not checked.
+function checkCase(x) {
+    if (!isObj(x))
+        return "case is not an object";
+    const c = x;
+    if (typeof c.id !== "string" || c.id === "")
+        return "id is not a non-empty string";
+    if (typeof c.action !== "string" || c.action === "")
+        return "action is not a non-empty string";
+    if (!Object.hasOwn(c, "snapshot"))
+        return "snapshot is missing";
+    if (c.snapshot !== null && !isObj(c.snapshot))
+        return "snapshot is not null or an object";
+    const i = c.inputs;
+    if (!isObj(i))
+        return "inputs is not an object";
+    if (!isObj(i.bindings))
+        return "inputs.bindings is not an object";
+    if (!isObj(i.actor))
+        return "inputs.actor is not an object";
+    if (typeof i.actor.id !== "string")
+        return "inputs.actor.id is not a string";
+    if (typeof i.actor.kind !== "string")
+        return "inputs.actor.kind is not a string";
+    if (!Array.isArray(i.actor.keys) || !i.actor.keys.every((k) => typeof k === "string"))
+        return "inputs.actor.keys is not a list of strings";
+    if (i.scope !== null && typeof i.scope !== "string")
+        return "inputs.scope is not a string or null";
+    if (typeof i.now !== "number" || !Number.isFinite(i.now))
+        return "inputs.now is not a finite number";
+    for (const k of ["reported", "expected"]) {
+        if (!Object.hasOwn(c, k))
+            return `${k} is missing`;
+        const r = c[k];
+        if (r === null)
+            continue;
+        if (!isObj(r))
+            return `${k} is not null or an object`;
+        if (typeof r.result !== "string" || r.result === "")
+            return `${k}.result is not a non-empty string`;
+        if (r.reason !== undefined && !REASONS.includes(r.reason))
+            return `${k}.reason is not one of ${REASONS.join(", ")}`;
+    }
+    return null;
+}
+async function main(args) {
+    const { pos, opts } = parseOptions(args, ["--cases"], []);
+    if (pos.length !== 1)
+        throw new Error(`expected 1 argument, found ${pos.length}`);
+    const cases = opts.get("--cases");
+    if (typeof cases !== "string")
+        throw new Error("--cases is required");
+    const ont = readOntology(pos[0]);
+    const lines = jsonLines(cases);
+    for (const { line, value } of lines) {
+        const problem = checkCase(value);
+        if (problem !== null)
+            throw new Error(`${cases}:${line}: ${problem}`);
+    }
+    const rows = reconcile(ont, lines.map((x) => x.value));
+    process.stdout.write(rows.map((r) => `${JSON.stringify(r)}\n`).join(""));
+    return 0;
+}
+// Exit 0: one row per case (the command does not judge the rows); 2: a usage, file, parse or shape error (one stderr line).
+export async function runReconcile(args) {
+    try {
+        return await main(args);
+    }
+    catch (error) {
+        const msg = (error instanceof Error ? error.message : String(error)).replace(/[\r\n]+/g, " ");
+        console.error(`${msg}; ${RECONCILE_USAGE}`);
+        return 2;
+    }
+}

package/dist/src/checker.js

@@ -1,7 +1,7 @@
 // Format-level ontology checker (rules R1–R12). Pure functions: no I/O. Project facts arrive through SourceFacts (contract.ts).
 // Fail closed: a missing anchor, a parse failure or a missing field is a violation, never a skip.
 import { IDENT, RULES } from "./contract.js";
-import { derivedPropertyType, isObj, newReads } from "./expr.js";
+import { derivedPropertyType, isObj, newReads, projectedFields } from "./expr.js";
 import { analyzeConditions, asReads, parseScope, quotesOf, stage1Violations } from "./stage1-check.js";
 export { IDENT };
 const CLASSES = ["canonical", "derived", "policy", "unknown"];
@@ -284,6 +284,9 @@ export function check(ontology, facts) {
             const vs = isObj(pv) ? pv.values : undefined;
             if (vs !== undefined && !(pv.type === "enum" && Array.isArray(vs) && vs.length > 0 && vs.every(isStr) && new Set(vs).size === vs.length))
                 v("R1", `${p}.parameters.${n}`, "values needs type enum and a non-empty list of distinct non-empty strings");
+            const pf = isObj(pv) ? pv.projectedFrom : undefined;
+            if (pf !== undefined && !(isObj(pv.type) && isStr(pv.type.ref) && Array.isArray(pf) && pf.length > 0 && pf.every(isStr) && new Set(pf).size === pf.length))
+                v("R1", `${p}.parameters.${n}`, "projectedFrom needs type {ref: <Object>} and a non-empty list of distinct non-empty field names");
         }
         const pids = new Set();
         for (const [i, pc] of arr(c.conditions).entries()) {
@@ -429,7 +432,14 @@ export function check(ontology, facts) {
         for (const [n, pv] of Object.entries(isObj(c.parameters) ? c.parameters : {})) {
             if (!isObj(pv) || !isStr(pv.cite?.quote))
                 continue;
-            if (!IDENT(n).test(pv.cite.quote))
+            // A projected parameter is not a request field: its quote names the fields it is projected from.
+            const fields = projectedFields(pv);
+            if (fields !== null) {
+                for (const f of fields)
+                    if (!IDENT(f).test(pv.cite.quote))
+                        v("R2", `${cid}:${n}:${f}`, `parameter ${n} is projected from ${f}, which does not appear in its cite quote`, "projection_field_not_in_quote");
+            }
+            else if (!IDENT(n).test(pv.cite.quote))
                 v("R2", `${cid}:${n}`, `parameter ${n} does not appear in its cite quote`, "parameter_not_in_quote");
             for (const x of Array.isArray(pv.values) ? pv.values.filter(isStr) : [])
                 if (!IDENT(x).test(pv.cite.quote))

package/dist/src/coverage.d.ts

@@ -0,0 +1,65 @@
+import type { ReconcileRow } from "./reconcile.js";
+/** One coverage unit: a row of a decision table (index from 0) or its otherwise. Key text: `<action>:rows.<i>` / `<action>:otherwise`. */
+export type CoverageUnit = {
+    action: string;
+    row: number | "otherwise";
+};
+/** A unit with the `when` and `result` of its row, so that an entry for a row that moved is stale. */
+export type CoverageDebt = CoverageUnit & {
+    when: {
+        passes: string;
+    } | {
+        fails: string;
+    } | null;
+    result: string;
+};
+/** A condition that a decision row names and that is declared without an expression. */
+export type CoverageGap = {
+    action: string;
+    condition: string;
+    kind: "unspecified";
+};
+export type CoverageExemption = CoverageGap & {
+    reason?: string;
+};
+export type CoverageBaseline = {
+    avouchCoverage: 1;
+    uncovered: CoverageDebt[];
+    exempt: CoverageExemption[];
+};
+export type CoverageStale = {
+    list: "uncovered";
+    action: string;
+    row: number | "otherwise";
+    why: "duplicate" | "no_such_row" | "moved" | "verified" | "blocked";
+} | {
+    list: "exempt";
+    action: string;
+    condition: string;
+    why: "duplicate" | "not_a_gap";
+};
+export type CoverageFailure = {
+    id: string;
+    action: string;
+    why: "mismatch" | "action_unknown" | "row_unknown" | "no_row_matched" | "runtime_missing" | "runtime_unmapped" | "expectation_unmapped" | "snapshot_missing" | "evaluator_error";
+};
+export interface CoverageResult {
+    ok: boolean;
+    units: number;
+    verified: CoverageUnit[];
+    baselined: CoverageUnit[];
+    blocked: (CoverageUnit & {
+        condition: string;
+    })[];
+    noTable: string[];
+    unasserted: {
+        id: string;
+        action: string;
+    }[];
+    uncovered: CoverageDebt[];
+    unexempted: CoverageGap[];
+    unreasoned: CoverageGap[];
+    stale: CoverageStale[];
+    failed: CoverageFailure[];
+}
+export declare function verifyCoverage(ont: unknown, rows: readonly ReconcileRow[], baseline: CoverageBaseline | null): CoverageResult;

package/dist/src/coverage.js

@@ -0,0 +1,229 @@
+// Decision-row coverage of reconcile rows (`avouch gate verify`). A rule of the tool, not of the format. A pure function:
+// it reads only its arguments, and the order of each output list is fixed.
+import { isObj } from "./expr.js";
+import { queryAction } from "./query.js";
+// Which reasons of cannot_reconcile fail the gate. A replay is not a decision; a case without an expectation states
+// nothing to compare; INDETERMINATE does not fail (except no_row_matched: see below), and the units that it leaves
+// unverified stay uncovered or blocked, so the gate still sees them.
+const FAILS = {
+    envelope: false,
+    expectation_missing: false,
+    indeterminate: false,
+    runtime_missing: true,
+    runtime_unmapped: true,
+    expectation_unmapped: true,
+    snapshot_missing: true,
+    evaluator_error: true,
+};
+const sortStr = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const show = (x) => JSON.stringify(x) ?? String(x);
+const isRow = (x) => x === "otherwise" || (typeof x === "number" && Number.isSafeInteger(x) && x >= 0);
+const sameWhen = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+function checkKeys(o, path, required, allowed) {
+    for (const k of required)
+        if (!Object.hasOwn(o, k))
+            throw new Error(`baseline: ${path}${k}: missing`);
+    for (const k of Object.keys(o))
+        if (!allowed.includes(k))
+            throw new Error(`baseline: ${path}${k}: unknown key`);
+}
+function checkRows(rows) {
+    if (!Array.isArray(rows))
+        throw new Error("rows: not an array");
+    rows.forEach((x, i) => {
+        const at = `rows[${i}]:`;
+        if (!isObj(x))
+            throw new Error(`${at} not an object`);
+        if (typeof x.id !== "string")
+            throw new Error(`${at} id is not a string`);
+        if (typeof x.action !== "string")
+            throw new Error(`${at} action is not a string`);
+        if (x.status === "match" || x.status === "mismatch") {
+            if (x.row !== undefined && !isRow(x.row))
+                throw new Error(`${at} row ${show(x.row)} is not a row index or "otherwise"`);
+        }
+        else if (x.status === "cannot_reconcile") {
+            if (typeof x.reason !== "string" || !Object.hasOwn(FAILS, x.reason))
+                throw new Error(`${at} reason ${show(x.reason)} is not a reason of cannot_reconcile`);
+        }
+        else
+            throw new Error(`${at} status ${show(x.status)} is not match, mismatch or cannot_reconcile`);
+    });
+}
+function checkBaseline(b) {
+    if (!isObj(b))
+        throw new Error("baseline: not an object");
+    checkKeys(b, "", ["avouchCoverage", "uncovered", "exempt"], ["avouchCoverage", "uncovered", "exempt"]);
+    if (b.avouchCoverage !== 1)
+        throw new Error(`baseline: avouchCoverage: ${show(b.avouchCoverage)} is not 1`);
+    if (!Array.isArray(b.uncovered))
+        throw new Error("baseline: uncovered: not an array");
+    if (!Array.isArray(b.exempt))
+        throw new Error("baseline: exempt: not an array");
+    b.uncovered.forEach((x, i) => {
+        const at = `uncovered[${i}]`;
+        if (!isObj(x))
+            throw new Error(`baseline: ${at}: not an object`);
+        checkKeys(x, `${at}.`, ["action", "row", "when", "result"], ["action", "row", "when", "result"]);
+        if (typeof x.action !== "string")
+            throw new Error(`baseline: ${at}.action: not a string`);
+        if (!isRow(x.row))
+            throw new Error(`baseline: ${at}.row: ${show(x.row)} is not a row index or "otherwise"`);
+        const w = x.when;
+        const when = w === null || (isObj(w) && Object.keys(w).length === 1 && (typeof w.passes === "string" || typeof w.fails === "string"));
+        if (!when)
+            throw new Error(`baseline: ${at}.when: not null, {passes: <condition>} or {fails: <condition>}`);
+        if (typeof x.result !== "string")
+            throw new Error(`baseline: ${at}.result: not a string`);
+    });
+    b.exempt.forEach((x, i) => {
+        const at = `exempt[${i}]`;
+        if (!isObj(x))
+            throw new Error(`baseline: ${at}: not an object`);
+        checkKeys(x, `${at}.`, ["action", "condition", "kind"], ["action", "condition", "kind", "reason"]);
+        if (typeof x.action !== "string")
+            throw new Error(`baseline: ${at}.action: not a string`);
+        if (typeof x.condition !== "string")
+            throw new Error(`baseline: ${at}.condition: not a string`);
+        if (x.kind !== "unspecified")
+            throw new Error(`baseline: ${at}.kind: ${show(x.kind)} is not supported by this version`);
+        if (x.reason !== undefined && typeof x.reason !== "string")
+            throw new Error(`baseline: ${at}.reason: not a string`);
+    });
+}
+// Coverage of the decision rows of every action of the ontology by the match rows. baseline null = both lists empty.
+// Throws for an ontology without an actionTypes object, or rows or a baseline with a wrong shape (the message starts
+// with "ontology:", "rows" or "baseline:").
+export function verifyCoverage(ont, rows, baseline) {
+    if (!isObj(ont) || !isObj(ont.actionTypes))
+        throw new Error("ontology: actionTypes is not an object");
+    const actionTypes = ont.actionTypes;
+    checkRows(rows);
+    if (baseline !== null)
+        checkBaseline(baseline);
+    const base = baseline ?? { avouchCoverage: 1, uncovered: [], exempt: [] };
+    // 1. Units and gaps. A gap: a condition that a row names (as its own or as an earlier row's) and that has no expression.
+    const units = [];
+    const unitOf = new Map();
+    const gaps = [];
+    const noTable = [];
+    const key = (action, x) => JSON.stringify([action, x]);
+    for (const action of Object.keys(actionTypes).sort(sortStr)) {
+        const q = queryAction(ont, action);
+        if (q === null)
+            continue;
+        if (q.decision === null) {
+            noTable.push(action);
+            continue;
+        }
+        const isGap = (c) => q.conditions.find((x) => x.id === c)?.expr === null;
+        const named = new Set();
+        for (const r of q.decision.rows) {
+            const u = { action, q: r, gap: r.requires.find((x) => isGap(x.condition))?.condition ?? null };
+            units.push(u);
+            unitOf.set(key(action, r.row), u);
+            for (const x of r.requires)
+                if (isGap(x.condition))
+                    named.add(x.condition);
+        }
+        for (const condition of [...named].sort(sortStr))
+            gaps.push({ action, condition, kind: "unspecified" });
+    }
+    const gapKeys = new Set(gaps.map((g) => key(g.action, g.condition)));
+    // 2. Case rows, in input order.
+    const verified = new Set();
+    const failed = [];
+    const unasserted = [];
+    for (const r of rows) {
+        const head = { id: r.id, action: r.action };
+        if (!Object.hasOwn(actionTypes, r.action))
+            failed.push({ ...head, why: "action_unknown" });
+        else if (r.status === "mismatch")
+            failed.push({ ...head, why: "mismatch" });
+        else if (r.status === "cannot_reconcile") {
+            if (r.reason === "indeterminate" && r.detail === "no_row_matched")
+                failed.push({ ...head, why: "no_row_matched" });
+            else if (FAILS[r.reason])
+                failed.push({ ...head, why: r.reason });
+            else if (r.reason === "expectation_missing")
+                unasserted.push(head);
+        }
+        else if (r.row !== undefined) {
+            // a match on a row: the unit must exist and give the same result
+            const u = unitOf.get(key(r.action, r.row));
+            const result = isObj(r.result) ? r.result.result : undefined;
+            if (u === undefined || u.q.result !== result)
+                failed.push({ ...head, why: "row_unknown" });
+            else
+                verified.add(u);
+        }
+    }
+    // 3. Exemptions, in baseline order.
+    const stale = [];
+    const exempted = new Set();
+    const unreasonedKeys = new Set();
+    const seenExempt = new Set();
+    for (const e of base.exempt) {
+        const k = key(e.action, e.condition);
+        const out = { list: "exempt", action: e.action, condition: e.condition };
+        if (seenExempt.has(k))
+            stale.push({ ...out, why: "duplicate" });
+        else if (!gapKeys.has(k))
+            stale.push({ ...out, why: "not_a_gap" });
+        else {
+            exempted.add(k);
+            if (e.reason === undefined || e.reason.trim() === "")
+                unreasonedKeys.add(k);
+        }
+        seenExempt.add(k);
+    }
+    // 4. Uncovered entries, in baseline order. The baseline must have no dead entries.
+    const owed = new Set();
+    const seenDebt = new Set();
+    for (const d of base.uncovered) {
+        const k = key(d.action, d.row);
+        const u = unitOf.get(k);
+        const out = { list: "uncovered", action: d.action, row: d.row };
+        if (seenDebt.has(k))
+            stale.push({ ...out, why: "duplicate" });
+        else if (u === undefined)
+            stale.push({ ...out, why: "no_such_row" });
+        else if (!sameWhen(d.when, u.q.when) || d.result !== u.q.result)
+            stale.push({ ...out, why: "moved" });
+        else if (verified.has(u))
+            stale.push({ ...out, why: "verified" });
+        else if (u.gap !== null)
+            stale.push({ ...out, why: "blocked" });
+        else
+            owed.add(u);
+        seenDebt.add(k);
+    }
+    // 5. Each unit, in unit order.
+    const result = {
+        ok: false,
+        units: units.length,
+        verified: [],
+        baselined: [],
+        blocked: [],
+        noTable,
+        unasserted,
+        uncovered: [],
+        unexempted: gaps.filter((g) => !exempted.has(key(g.action, g.condition))),
+        unreasoned: gaps.filter((g) => unreasonedKeys.has(key(g.action, g.condition))),
+        stale,
+        failed,
+    };
+    for (const u of units) {
+        const id = { action: u.action, row: u.q.row };
+        if (verified.has(u))
+            result.verified.push(id);
+        else if (u.gap !== null)
+            result.blocked.push({ ...id, condition: u.gap });
+        else if (owed.has(u))
+            result.baselined.push(id);
+        else
+            result.uncovered.push({ ...id, when: u.q.when, result: u.q.result });
+    }
+    result.ok = [result.uncovered, result.unexempted, result.unreasoned, result.stale, result.failed].every((x) => x.length === 0);
+    return result;
+}

package/dist/src/evaluate.js

@@ -1,7 +1,7 @@
 // Decision evaluation: evalValue / evalPredicate (two levels, Kleene logic) and decide (invocation layer, then decision table).
 // Deterministic: no wall clock, no randomness, no global mutable state; `now` comes from the caller.
 // Invalid input (ontology, snapshot, scope argument) throws; it is never a result.
-import { checkPredicate, fitsType, own, RESERVED_NAMES, TIMESTAMP_MAX, TIMESTAMP_MIN } from "./expr.js";
+import { checkPredicate, fitsType, own, projectedFields, RESERVED_NAMES, TIMESTAMP_MAX, TIMESTAMP_MIN } from "./expr.js";
 // The fixed invocation result set of the format (defined in ./expr). decide never returns the first two (the idempotency
 // envelope is not implemented here: it has no idempotency key).
 export { INVOCATION_RESULTS } from "./expr.js";
@@ -347,7 +347,9 @@ function admit(ont, actionId, bindings, actor) {
     for (const [name, p] of Object.entries(params)) {
         const v = own(bindings, name);
         if (v === null || v === undefined) {
-            if (p.optional === true)
+            // A projected ref parameter is always given: null means the projection found nothing (not_found at the binding step).
+            const projected = projectedFields(p) !== null;
+            if (v === null ? p.optional === true || projected : p.optional === true && !projected)
                 continue;
             return { layer: "invocation", result: "INVALID_BINDING", param: name, reason: "missing" };
         }
@@ -380,6 +382,8 @@ function resolve(s, actionId) {
         if (typeof elem === "string" || !("ref" in elem))
             continue;
         const v = own(s.env.bindings, name);
+        if (v === null && p.optional !== true && projectedFields(p) !== null)
+            return { layer: "invocation", result: "INVALID_BINDING", param: name, reason: "not_found" };
         if (v === null || v === undefined)
             continue;
         for (const id of isSet ? v : [v]) {

package/dist/src/expr.d.ts

@@ -116,11 +116,16 @@ export type ActionType = {
         type?: Type;
         optional?: true;
         values?: string[];
+        projectedFrom?: string[];
     }>;
     permission: Permission;
     conditions: Condition[];
     decision?: Decision;
 };
+export declare function projectedFields(p: {
+    type?: unknown;
+    projectedFrom?: unknown;
+}): string[] | null;
 export interface Stage1Ontology {
     scope?: {
         by: string;

package/dist/src/expr.js

@@ -11,6 +11,12 @@ export const DISPOSITION_CLASSES = ["rejected", "recorded", "pending", "applied"
 // not be one of these names.
 // Every invocation-layer result, SCOPE_DENIED included. SCOPE_DENIED is internal and never reported (SPEC section 9).
 export const INVOCATION_RESULTS = ["REPLAYED", "IDEMPOTENCY_CONFLICT", "INVALID_BINDING", "SCOPE_DENIED", "PERMISSION_DENIED"];
+// The distinct request fields of a projected parameter, or null: only a scalar {ref: T} parameter with at least one field is
+// projected; on any other parameter projectedFrom has no effect.
+export function projectedFields(p) {
+    const fs = Array.isArray(p.projectedFrom) ? [...new Set(p.projectedFrom.filter((f) => typeof f === "string"))] : [];
+    return isObj(p.type) && typeof p.type.ref === "string" && fs.length > 0 ? fs : null;
+}
 export class ExprError extends Error {
     path;
     constructor(path, msg) {

package/dist/src/index.d.ts

@@ -7,3 +7,4 @@ export * from "./patch.js";
 export * from "./query.js";
 export * from "./markdown.js";
 export * from "./unknown.js";
+export * from "./coverage.js";

package/dist/src/index.js

@@ -7,3 +7,4 @@ export * from "./patch.js";
 export * from "./query.js";
 export * from "./markdown.js";
 export * from "./unknown.js";
+export * from "./coverage.js";

package/dist/src/query.d.ts

@@ -142,6 +142,7 @@ export type QueryAction = {
         type: Type | null;
         optional: boolean;
         values: string[] | null;
+        projectedFrom: string[] | null;
         cite: QueryCite | null;
     }[];
     conditions: {

package/dist/src/query.js

@@ -330,6 +330,7 @@ export function queryAction(ont, id) {
             type: typeOf(map(p).type),
             optional: map(p).optional === true,
             values: Array.isArray(map(p).values) ? map(p).values.filter((x) => typeof x === "string") : null,
+            projectedFrom: Array.isArray(map(p).projectedFrom) ? map(p).projectedFrom.filter((x) => typeof x === "string") : null,
             cite: citeOf(map(p).cite),
         })),
         conditions: conditionsOf(a).map((c) => ({

package/ontology.schema.json

@@ -673,7 +673,7 @@
           "type": "object",
           "propertyNames": { "minLength": 1 },
           "additionalProperties": { "$ref": "#/$defs/parameter" },
-          "description": "Optional action parameters: parameter name → {cite}. Foundation: Palantir action parameters (\"Parameters are the inputs of an action type.\"). A condition reads a parameter as `{param: <name>}` or, in an expression, as `{ref: <name>}`. R1: must be a mapping; each entry carries a cite. R2: the cite quote must occur verbatim, and the parameter name must appear in it (R2 `parameter_not_in_quote`, key `<ID>:<name>`), and so must each of its `values` (R2 `parameter_value_not_in_quote`, key `<ID>:<name>:<value>`). A declared parameter that no condition reads is not a failure."
+          "description": "Optional action parameters: parameter name → {cite}. Foundation: Palantir action parameters (\"Parameters are the inputs of an action type.\"). A condition reads a parameter as `{param: <name>}` or, in an expression, as `{ref: <name>}`. R1: must be a mapping; each entry carries a cite. R2: the cite quote must occur verbatim, and the parameter name must appear in it (R2 `parameter_not_in_quote`, key `<ID>:<name>`), or, for a projected parameter (`type: {ref: <Object>}` with at least one `projectedFrom` field), each of its fields (R2 `projection_field_not_in_quote`, key `<ID>:<name>:<field>`), and so must each of its `values` (R2 `parameter_value_not_in_quote`, key `<ID>:<name>:<value>`). A declared parameter that no condition reads is not a failure."
         },
         "edits": {
           "type": "array",
@@ -1009,17 +1009,22 @@
       "type": "object",
       "additionalProperties": false,
       "required": ["cite"],
-      "description": "One action parameter. Foundation: Palantir action parameter. The name is the map key; the cite is the source text that names it. `type` is required when an expression reads the parameter; `optional: true` lets the caller omit it (it is then null). `values` is the value domain of an `enum` parameter (only with `type: enum`): a value outside it is `INVALID_BINDING` `type`; R1 checks its shape and that literals compared with the parameter are among them, R2 that each value appears in the cite quote.",
+      "description": "One action parameter. Foundation: Palantir action parameter. The name is the map key; the cite is the source text that names it. `type` is required when an expression reads the parameter; `optional: true` lets the caller omit it (it is then null). `values` is the value domain of an `enum` parameter (only with `type: enum`): a value outside it is `INVALID_BINDING` `type`; R1 checks its shape and that literals compared with the parameter are among them, R2 that each value appears in the cite quote. `projectedFrom` (only with `type: {ref: <Object>}`) lists the request fields, an alternate key, that the project's projection resolves to this ref; on any other parameter R1 reports it and `decide` ignores it; the cite quote must name each field instead of the parameter name (R2 `projection_field_not_in_quote`); a null value of a required projected parameter is `INVALID_BINDING` `not_found`, and an absent one is `missing`, also with `optional: true` (SPEC section 9).",
       "properties": {
         "cite": { "$ref": "#/$defs/cite" },
         "type": { "$ref": "#/$defs/valueType" },
         "optional": { "const": true },
-        "values": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+        "values": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+        "projectedFrom": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
       },
       "allOf": [
         {
           "if": { "required": ["values"] },
           "then": { "required": ["type"], "properties": { "type": { "const": "enum" } } }
+        },
+        {
+          "if": { "required": ["projectedFrom"] },
+          "then": { "required": ["type"], "properties": { "type": { "type": "object", "required": ["ref"] } } }
         }
       ]
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githonllc/avouch",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/vocab.ttl

@@ -475,7 +475,12 @@ ofv:set a rdf:Property ;
 
 ofv:optional a rdf:Property ;
   rdfs:label "optional" ;
-  rdfs:comment "The caller may leave the parameter out; it is then null. YAML: actionTypes.<ID>.parameters.<n>.optional" ;
+  rdfs:comment "The caller may leave the parameter out; it is then null. Not for a projected parameter: it is always given, and null is a value. YAML: actionTypes.<ID>.parameters.<n>.optional" ;
+  rdfs:isDefinedBy <https://w3id.org/avouch/v1/vocab> .
+
+ofv:projectedFrom a rdf:Property ;
+  rdfs:label "projectedFrom" ;
+  rdfs:comment "Request fields (an alternate key) that the project's projection resolves to this ref parameter. A projected parameter is always given; null means the projection found nothing. YAML: actionTypes.<ID>.parameters.<n>.projectedFrom[]" ;
   rdfs:isDefinedBy <https://w3id.org/avouch/v1/vocab> .
 
 ofv:principals a rdf:Property ;