avouch 0.1.22

package/dist/src/unknown.js

@@ -0,0 +1,173 @@
+import { navType, objectBinding, own, resolvesInDomain } from "./expr.js";
+export const MAX_NULLABLE_REFS = 8;
+class NoExpression extends Error {
+}
+// One domain for values and predicates: a null value is {U}, a non-null value is {T, F}.
+const U = new Set(["U"]);
+const TF = new Set(["T", "F"]);
+const QUANTIFIERS = new Set(["exists", "none", "all"]);
+const nodeKey = (e) => Object.keys(e)[0];
+const operands = (e) => e[nodeKey(e)];
+// `x.prop` -> ["x", "prop"]; `x` -> ["x", undefined]
+function split(path) {
+    const dot = path.indexOf(".");
+    return dot < 0 ? [path, undefined] : [path.slice(0, dot), path.slice(dot + 1)];
+}
+// A path with the head `self` replaced by the current self (an object binding name, or "self" at the root).
+function norm(path, self) {
+    const [head, prop] = split(path);
+    return head !== "self" ? path : prop === undefined ? self : `${self}.${prop}`;
+}
+const and3 = (a, b) => (a === "F" || b === "F" ? "F" : a === "U" || b === "U" ? "U" : "T");
+const or3 = (a, b) => (a === "T" || b === "T" ? "T" : a === "U" || b === "U" ? "U" : "F");
+const not3 = (a) => (a === "T" ? "F" : a === "F" ? "T" : "U");
+// a Kleene connective lifted to sets: the product of the operand sets
+function lift(xs, ys, f) {
+    const out = new Set();
+    for (const a of xs)
+        for (const b of ys)
+            out.add(f(a, b));
+    return out;
+}
+// The abstract result of e for one combination: isNull says which normalized paths are null. Every operand of every node
+// is evaluated (no short-circuit), and only isNull(of) of a derived property prunes: freeNullableRefs relies on both.
+function ev(ont, e, self, isNull) {
+    const k = nodeKey(e);
+    switch (k) {
+        case "lit":
+            return TF;
+        case "ref":
+            return isNull(norm(e.ref, self)) ? U : TF;
+        case "derived": {
+            // the only place a derived property is inlined: null without reading the expression when its `of` is null
+            const d = e.derived;
+            const of = norm(d.of.ref, self);
+            if (isNull(of))
+                return U;
+            const x = own(ont.derivedProperties, d.id)?.expr;
+            if (x === undefined)
+                throw new NoExpression(d.id);
+            return ev(ont, x, of, isNull);
+        }
+        case "exists":
+        case "none":
+        case "all":
+            return TF; // two-valued; the body is analysed on its own
+        case "and":
+        case "or": {
+            const [first, ...rest] = operands(e).map((x) => ev(ont, x, self, isNull));
+            return rest.reduce((acc, p) => lift(acc, p, k === "and" ? and3 : or3), first);
+        }
+        case "not":
+            return new Set([...ev(ont, operands(e)[0], self, isNull)].map(not3));
+        case "isNull":
+        case "isNotNull": {
+            const a = ev(ont, operands(e)[0], self, isNull);
+            const out = new Set();
+            if (a.has("U"))
+                out.add(k === "isNull" ? "T" : "F");
+            if (a.has("T") || a.has("F"))
+                out.add(k === "isNull" ? "F" : "T");
+            return out;
+        }
+        default: {
+            // strict nodes (comparisons, in, subsetOf, plus, dateIn): a null operand gives null; non-null operands give T or F
+            // (no narrowing by constants)
+            const xs = operands(e).map((x) => ev(ont, x, self, isNull));
+            const out = new Set();
+            if (xs.some((x) => x.has("U")))
+                out.add("U");
+            if (xs.every((x) => x.has("T") || x.has("F")))
+                (out.add("T"), out.add("F"));
+            return out;
+        }
+    }
+}
+// The distinct normalized paths that may be null and that the outer evaluation reads, sorted. One run of ev with no path
+// null reaches every read (ev evaluates every operand; only a null `of` prunes); quantifiers are not entered, and a
+// `nav.from` is never a read.
+export function freeNullableRefs(ont, e, mayNull) {
+    const seen = new Set();
+    ev(ont, e, "self", (p) => (seen.add(p), false));
+    return [...seen].filter(mayNull).sort();
+}
+// The predicate results of e for one combination: isNull says which paths are null.
+export function abstractEval(ont, e, isNull) {
+    return ev(ont, e, "self", isNull);
+}
+// Whether some combination of nulls over the free nullable reads of e may give U.
+export function mayUnknown(ont, e, mayNull) {
+    const refs = freeNullableRefs(ont, e, mayNull);
+    if (refs.length > MAX_NULLABLE_REFS)
+        return true;
+    for (let mask = 0; mask < 2 ** refs.length; mask++) {
+        const nulls = new Set(refs.filter((_, i) => (mask >> i) & 1));
+        if (abstractEval(ont, e, (p) => nulls.has(p)).has("U"))
+            return true;
+    }
+    return false;
+}
+// Nullability for any context of one ontology and its facts; the field lists are read once per object type.
+function nullability(ont, facts) {
+    const lists = new Map();
+    const fields = (objectType) => {
+        if (!lists.has(objectType)) {
+            const doc = own(ont.objectTypes, objectType)?.doc;
+            lists.set(objectType, typeof doc === "string" ? (facts.fieldList(doc, objectType)?.value ?? null) : null);
+        }
+        return lists.get(objectType);
+    };
+    return (ctx) => (path) => {
+        const [head, prop] = split(path);
+        if (head === "now" || head === "actor")
+            return false;
+        const local = head === "self" || Object.hasOwn(ctx.locals, head);
+        const param = local || ctx.action === undefined ? undefined : own(ont.actionTypes[ctx.action]?.parameters, head);
+        if (!local && param === undefined)
+            return true; // not reachable after the type check; conservative
+        if (param !== undefined && (param.optional === true || resolvesInDomain(param)))
+            return true; // an optional parameter or a ref with unresolved: domain, and every property read through it
+        if (prop === undefined)
+            return false; // an object binding, or a required parameter
+        const o = objectBinding(ont, head, ctx);
+        // non-null only when the field list says so; a projected property (from) may always be null (its key may be absent)
+        return o === undefined || own(own(ont.objectTypes, o)?.properties, prop)?.from !== undefined || fields(o)?.get(prop)?.nullable !== false;
+    };
+}
+// Nullability of the paths in ctx. A field is non-null only when its field list says so; a field that is not listed,
+// or an object without a field list, has unknown nullability and may be null. An optional parameter may be null; so
+// may every property read through it. A ref parameter with `unresolved: domain` is the same.
+export function mayNullIn(ont, facts, ctx) {
+    return nullability(ont, facts)(ctx);
+}
+// The quantifiers of e (preorder, through and / or / not and quantifier bodies) whose body may be UNKNOWN. Paths use
+// the type-error notation: `$.none`, `$.and[1].none`, `$.all.where.and[0].exists`. Derived property nodes are not
+// entered: a quantifier inside a derived property is reported once, for the derived property itself. A body that
+// reaches a derived property without an expression is not analysed (its nested quantifiers still are).
+export function absorbingQuantifiers(ont, facts, e, ctx) {
+    const out = [];
+    const mayNullFor = nullability(ont, facts);
+    const walk = (x, at, c) => {
+        const k = nodeKey(x);
+        const p = `${at}.${k}`;
+        if (k === "and" || k === "or" || k === "not")
+            operands(x).forEach((y, i) => walk(y, `${p}[${i}]`, c));
+        else if (QUANTIFIERS.has(k)) {
+            const q = x[k];
+            if (q.where === undefined)
+                return;
+            const c2 = { ...c, locals: { ...c.locals, [q.as]: navType(ont, q.in, c, `${p}.in`) } };
+            try {
+                if (mayUnknown(ont, q.where, mayNullFor(c2)))
+                    out.push(p);
+            }
+            catch (err) {
+                if (!(err instanceof NoExpression))
+                    throw err;
+            }
+            walk(q.where, `${p}.where`, c2);
+        }
+    };
+    walk(e, "$", ctx);
+    return out;
+}

package/docs/adapter-guide.md

@@ -0,0 +1,187 @@
+# Writing an Avouch adapter
+
+This guide is for engineers who want to use Avouch for their own project. It tells you which facts the checker needs, how the toy library adapter supplies them, and how to write the profile.
+
+## For AI agents
+
+Read this when `avouch check` or `avouch facts` reports `no adapter`, or when `/avouch:scan` stops because no adapter can read the documents. An adapter reads the design documents and gives the checker the facts that the ontology must agree with.
+
+1. The documents are Markdown: you do not need code. Use the built-in Markdown adapter. Add this key to `avouch.config.json` at the git top level, with the paths of the design documents (relative to the file):
+
+   ```json
+   { "adapter": { "markdown": { "docs": ["docs/design.md"] } } }
+   ```
+
+   Then run `npx -y avouch facts`. Exit code 0 means the adapter reads the documents. Rules that need a structured fact (a state machine, a permission table, a catalog) need sections in the grammar of `docs/markdown-convention.md`, and a `facts` anchor for each (section 7). Without them, those rules report `fact_missing`: disable each one with a reason (`"rules": {"R8": {"disabled": "<reason>"}}` in `profile`), or rewrite the section to the convention.
+
+2. The documents are in another form, or you need structured facts from Markdown that does not follow the convention: write an adapter module. Do this in a new session, not in the session that writes or edits the ontology. Give the new session this prompt:
+
+   ```text
+   Write an Avouch adapter module for this repository.
+   Read first: https://github.com/githonllc/avouch/blob/main/docs/adapter-guide.md (sections 2, 3 and "Writing your own adapter"),
+   src/contract.ts (the SourceFacts interface) and examples/library/adapter.ts of the avouch package.
+   Inputs: the design documents only. Do not read the ontology (*.ontology.yaml) and do not run avouch query.
+   Output: avouch/adapter.mjs, which exports facts(ontologyPath) and returns SourceFacts. Parse the documents at run time.
+   Put no expected value (state, edge, trigger, key, event, scenario or catalog name) in the code.
+   Set "adapter": "avouch/adapter.mjs" in avouch.config.json. Add a test that runs facts() on the real documents.
+   Done when the test passes and `npx -y avouch check` no longer reports "no adapter".
+   Report each document form that the adapter does not read.
+   ```
+
+   The reason for a new session: the adapter gives the expected facts, and the ontology declares them. When one agent writes both, `avouch check` compares the agent with itself, and a PASS proves nothing. Not guaranteed: the checker cannot see which session wrote the adapter. Review the adapter in the pull request.
+
+## 1. The three layers
+
+Avouch has three layers: the format layer (this package), the project profile and adapter (your code), and the ontology instance (your `<project>.ontology.yaml`). SPEC section 1 defines them. The format layer never reads a source document. Your adapter reads your sources and returns `SourceFacts`. The checker compares your ontology with those facts.
+
+## 2. The fact contract
+
+The contract is the `SourceFacts` interface in `src/contract.ts`. Your adapter returns one object of this type.
+
+| Field | Required | Used by |
+|---|---|---|
+| `config` | yes | all rules: the profile (section 5) |
+| `diagnostics` | yes | your adapter's findings (parse errors, duplicate rows); reported and waived like violations |
+| `info` | yes | lines that the checker prints |
+| `section(anchor)` | yes | R2: finds a section by its anchor; returns the section, `"missing"` or `"ambiguous"` |
+| `containsTerm(term)` | yes | R2: is the term in the source |
+| `fieldList(anchor, objectType)` | yes | R2 (R6 and R12 also read it): the fields of an object in a section, each with `nullable`, or `null` |
+| `storeCatalog` | no | R2 |
+| `stateMachines` | no | R3: object type to the state machine at its authoritative anchor |
+| `transitionTriggers` | no | R3: object type to `"FROM->TO"` to action ids |
+| `contextMembers` | no | R5: context to member names |
+| `eventCatalog` | no | R8 |
+| `scenarios` | no | R9: scenario id to the cited action ids |
+| `permissions` | no | R10 |
+| `evidence` | no | R1 (id validity), R6 (`none_but_written`), R7 |
+
+`permissions.quoteNamesKey(quote, key)` is the fourth function that you must supply when you supply `permissions`. R10 uses it to ask: does this quote name this key in the key syntax of your source?
+
+Each optional field can be absent. When a rule that needs an absent field is enabled, the checker reports one `fact_missing` violation and skips the checks that depend on the fact. The table in SPEC section 6 lists the checks that are skipped for each fact.
+
+## 3. Walkthrough: the toy library adapter
+
+`examples/library/adapter.ts` builds `SourceFacts` for `examples/library/library.md`.
+
+- It parses the `## L<n> <title>` headings into sections. A heading anchor that occurs two times gives `"ambiguous"`.
+- `fieldList` finds the one `text` code block in the section whose first line is the object name, and reads its `- <field>` lines. A trailing `?` marks the field nullable and is not part of its name. A field that is not listed, or an object without a field list, has unknown nullability.
+- `containsTerm` searches the document for the term.
+- Before it extracts any fact, it removes every generated block (`<!-- BEGIN GENERATED: <name> -->` to `<!-- END GENERATED: <name> -->`, marker lines included); markers that do not pair throw. No fact may come from text generated from the ontology (SPEC section 4). This stripper is simplified: it does not skip fenced code blocks and does not accept annotated markers. A real adapter must handle the marker syntax of its own generator.
+- All other facts are literals with an anchor: the store catalog (`L8`), the state machines (`L4`, `L5`), the transition triggers (`L6`), the context members (`L7`), the event catalog (`L9`) and the permissions (`L10`). The scenarios are a literal without an anchor.
+
+The toy adapter writes these facts as literals to keep the example small. A real adapter must parse them from its sources, so that a change in a source document shows as a violation.
+
+`examples/library/evidence.ts` supplies the execution evidence: for each evidence id, a list of invocation records (SPEC section 4). Each record has a harness-generated id, the outcome, a snapshot reference, the evaluation inputs and, when committed, the net change per store row by row (keyed by a stable row identity) and the events written. The checker derives the changed stores and the committed count from the records. Always set the record id: a record without one is keyed by its list position, and that key is not stable for waivers. Do not reuse a row identity within one invocation (SPEC section 4).
+
+### Writing your own adapter
+
+A project that does not write its documents to the Markdown convention (`docs/markdown-convention.md`) writes its own adapter. Follow these rules:
+
+- Derive every fact from the source text. Parse it at run time, so that a change in a source document shows as a violation.
+- Put no expected value in the adapter code: no state, edge, trigger, key, event, scenario or catalog name. A value in code is a value that the check cannot compare with the documents. The toy adapter uses literals only to keep the example small (see above).
+- Take no fact from text generated from the ontology (SPEC section 4). Remove generated text before you extract any fact.
+
+Not guaranteed: the checker cannot check these rules. It sees the facts that the adapter returns, not how the adapter made them. Review the adapter in the pull request, as you review the ledger.
+
+## 4. Rules that need no project facts
+
+R1, R4 and R11 never report `fact_missing` (SPEC section 6). R4 and R11 read only the ontology. R1 reads the ontology and the profile; when an action names `evidence`, R1 also needs the `evidence` fact to resolve it.
+
+Parameters and parameter and actor reads (`parameters`, `{param}`, `{actor}`) need no new fact. For these reads, R1 and R4 use only the ontology. R2 checks parameter quotes with the same `section` function as all other quotes.
+
+## 5. The profile
+
+`examples/library/profile.ts` is the toy profile. It is a `FormatConfig`:
+
+- `rules`: one switch for each rule R1–R12, `true` or `{ disabled: "<reason>" }`. Write all of them. A missing entry gives `rule_not_configured`.
+- `requiredSource`: the anchor that each permission cite must name (R10).
+- `scenarioCoverage`: `"printed"` (default) or `"enforced"` (R9). The toy profile uses the default.
+- `crossContextMechanisms`: the legal `via` values of `crossContext` (R5).
+- `actionIdPattern`: the pattern of an action id (R1).
+- `linkFieldPattern`: the pattern of a field that holds a link (R6).
+- `stateProperty`: the default name of the state property (R1, R3). An ontology machine names another property of its object with `stateMachines.<Object>.property`.
+
+A harness that builds its own snapshot, and not through `projectSnapshot` (for example the input of the `reconcile` CLI, which is taken as given), must set each projected property (`properties.<p>.from`) the same way: from the top-level key of the JSON object in its column, null when the column is null or the key is absent or null, never decoded, and not set when the column is absent (SPEC section 9, `projectSnapshot` step 2).
+
+## 6. Run the example
+
+In the package directory, run:
+
+```
+npm install
+npm test
+```
+
+## 7. The built-in Markdown adapter
+
+A project whose specification is plain Markdown can run `avouch check` without writing an adapter. `src/markdown.ts` is a generic adapter: `parseMarkdownConfig(text, file)` reads a JSON configuration (`validateMarkdownConfig(value, where)` checks an object that is already parsed), and `markdownFacts(docs, config)` turns document texts into `SourceFacts`. It reads no file; the command line reads the configuration and the documents.
+
+### Configuration
+
+The configuration is either the `adapter.markdown` object of the project configuration `avouch.config.json` (README, "Configuration"), and `docs` is then relative to that file, or a stand-alone `.json` file. A stand-alone file is named by `--adapter <file>.json`, or by the string `"adapter": "<file>.json"` in `avouch.config.json` (a path relative to that file); its `docs` are relative to the stand-alone file. `avouch check` without `--adapter` uses the `adapter` of `avouch.config.json`. Any other `--adapter` value, or any other string in `adapter`, is loaded as a module. The configuration for the toy library (in the directory of `library.md`; as a stand-alone file, or as the value of `adapter.markdown`) is:
+
+```json
+{
+  "docs": ["library.md"],
+  "facts": { "storeCatalog": "L8", "eventCatalog": "L9", "contextMembers": "L7", "permissions": "L10", "scenarios": "L11", "stateMachines": { "Book": "L4", "Loan": "L5" }, "transitionTriggers": "L6" },
+  "profile": { "crossContextMechanisms": ["same_transaction"] }
+}
+```
+
+- `docs` (required): the source documents, a non-empty list of distinct paths. A relative path resolves from the directory of the configuration file. Two entries that resolve to the same file, or a file that cannot be read, stop the command with exit code 2.
+- `facts` (optional): the anchor of the section that holds each optional fact: `storeCatalog` (R2), `eventCatalog` (R8), `contextMembers` (R5), `permissions` (R10), `scenarios` (R9), `stateMachines` and `transitionTriggers` (R3). A fact without an anchor is not supplied. `stateMachines` is an object, not a string: each key is an object type and each value is the anchor of the section that holds the state diagram of that object (`"stateMachines": {"Book": "L4"}`). `stateMachines` and `transitionTriggers` are set together or not at all; one without the other is an error.
+- `profile` (optional): `actionIdPattern` and `linkFieldPattern` (regular expression strings), `stateProperty`, `crossContextMechanisms`, `scenarioCoverage`, `idempotencyDeclarationRequired`, `evidenceRequired` and `rules`. A `rules` entry is `true` or `{"disabled": "<reason>"}` and replaces the default for that rule.
+
+An unknown key, a wrong type or an invalid regular expression is an error `<file>: <json path>: <problem>` (exit code 2).
+
+Defaults: `actionIdPattern` `^[A-Z][A-Z_]*$`, `linkFieldPattern` `_id$`, `stateProperty` `state`, `crossContextMechanisms` empty. `requiredSource` is `{R10: <permissions anchor>}` when `facts.permissions` is set, else empty; it cannot be set separately. `scenarioCoverage`, `idempotencyDeclarationRequired` and `evidenceRequired` are set only when given. Rules R1, R2, R4, R5, R6, R8, R10, R11 and R12 are on. R9 is on when `facts.scenarios` is set. R3 is on when `facts.stateMachines` and `facts.transitionTriggers` are set. Without its facts, R9 or R3 is off, like R7, because the adapter supplies no facts for the rule; the checker prints the reason:
+
+| Rule | Reason |
+|---|---|
+| R3 | facts.stateMachines and facts.transitionTriggers are not set: the Markdown adapter reads state machines only from those sections |
+| R7 | the Markdown adapter reads no execution evidence |
+| R9 | facts.scenarios is not set: the Markdown adapter reads scenarios only from that section |
+
+### Parse conventions
+
+The grammar of the documents is in `docs/markdown-convention.md`: the general rules, and one section for each fact with its template, example and diagnostics.
+
+### Evidence and R6
+
+The Markdown adapter reads no evidence, so `evidence` is absent. R6 stays on, because its static checks (missing, unspecified and stray link effects, link catalog completeness, stray non-link fields) need only the field lists. The cost is one violation `R6 fact_missing facts.evidence`. Waive it in the ontology:
+
+```yaml
+knownSourceGaps:
+  - id: NO-EVIDENCE
+    rule: R6
+    kind: fact_missing
+    keys: [facts.evidence]
+    doc_line: the sources are plain Markdown; there is no execution evidence
+    conflict: R6 none_but_written needs evidence
+    proposed: add an evidence adapter
+```
+
+Or switch R6 off with `"rules": {"R6": {"disabled": "<reason>"}}`; this also turns off the link checks.
+
+An action that names `evidence` fails R1 when no evidence is supplied. To use the Markdown facts with your own evidence, write a small adapter module that combines them:
+
+```ts
+export const facts = () => ({ ...markdownFacts(docs, cfg), evidence });
+```
+
+### Query
+
+Without `--check` and without `--adapter`, the check stamp of `avouch query` stays `not_run`. `avouch query ... --check` runs the same check as `avouch check` with the adapter of the project configuration, and `--adapter <file>.json` with that file.
+
+### Check documents without an ontology
+
+`avouch facts` runs this adapter over the documents of a configuration and prints the facts, the fields of each `text` block and the diagnostics, without reading an ontology file. See "facts" in `README.md`.
+
+### The toy library with the generic adapter
+
+`test/markdown.test.ts` runs the clean toy ontology and its 28 mutations through both adapters, with every `evidence` id removed. The findings are the same, except:
+
+- the toy adapter also reports R7 and R6 `none_but_written` (the generic adapter has no evidence);
+- the generic adapter also reports R6 `fact_missing facts.evidence`.
+
+The R3 and R9 findings are the same, because the configuration sets `facts.stateMachines`, `facts.transitionTriggers` and `facts.scenarios`. So the generic adapter does not catch three mutations: `lib-r6-none-but-written`, `lib-r7-effect-unwitnessed` and `lib-r7-undeclared-store`. It catches the other 25, `lib-r3-transition-binding`, `lib-r6-link-sweep-missing` and `lib-r9-unknown-scenario` included. With the evidence ids kept, the clean toy fails with three violations: R1 for each of the two evidence ids, and R6 `fact_missing`.