@githonllc/avouch 0.1.6 → 0.1.7

package/SPEC.md

@@ -203,7 +203,7 @@ Host language comparisons (`null != "A"` is true in JavaScript) are not used. `i
 
 Quantifiers are two-valued. `exists` is T when some element gives T; `all` is T when every element gives T (an element with F or U makes it F); `none = not exists`. An empty collection gives `exists` F, `all` T, `none` T: navigation results are a closed world, not U. Their bodies should be provably two-valued (R12 quantifier_absorbs_unknown; see Static UNKNOWN analysis).
 
-Navigation: a foreign-key link (no `table`, or `table` is an object's `datasource`) follows `via`; a pure link (`table` is no object's `datasource`) reads `snapshot.links[link.id]` rows `{from, to}`. A null `via`, a dangling foreign key (missing or out of scope) and a null optional ref give the empty set; orphan data is a data-integrity question, not U.
+Navigation: a foreign-key link (no `table`, or `table` is an object's `datasource`) follows `via`; a pure link (`table` is no object's `datasource`) reads `snapshot.links[link.id]` rows `{from, to}`. A pure link that is navigated from a row and is not a key of `snapshot.links` is an incomplete snapshot: `decide` throws `snapshot lacks link <id>`. An empty link table is passed as `[]`. A null `via`, a dangling foreign key (missing or out of scope) and a null optional ref give the empty set (navigation from a null optional ref does not read the link); orphan data is a data-integrity question, not U.
 
 Known risk (vacuous truth): from an optional ref that is null, `all` and `none` are always T. This is not an UNKNOWN risk and is not reported. Guard first: `and(isNotNull({ref: x}), all(...))`.
 
@@ -296,8 +296,9 @@ Types:
 
 - `Reported = {result, reason?}`: a result as the runtime or a scenario states it. `reason` is set only for `INVALID_BINDING`. There is no `param`: runtimes do not report it.
 - `RuntimeCase = {id, action, snapshot, inputs: {bindings, actor, scope, now}, reported, expected}`: `id` is generated by the harness; `snapshot` is the typed snapshot taken before the invocation, or `null`; `reported` is what the runtime reported, or `null` (not reported); `expected` is the scenario expectation, or `null` (none).
-- `ReconcileRow`: `{id, action, status: match, result}`, `{id, action, status: mismatch, evaluator, reported, expected}`, or `{id, action, status: cannot_reconcile, reason, detail?}`.
+- `ReconcileRow`: `{id, action, status: match, result, row?}`, `{id, action, status: mismatch, evaluator, reported, expected, row?}`, or `{id, action, status: cannot_reconcile, reason, detail?}`. `row` is set only when the evaluator result is a domain result (step 9).
 - `Decode = (raw, type) => Value | undefined` and `TypeDefect = {object, prop, row, value}`.
+- `LinkColumns = {<link id>: {from, to}}`: for each pure link, the columns of its table that hold the `from` and `to` ids.
 
 `reconcile(ont, cases)` gives exactly one row per case, in input order. For each case the first step that applies gives the row:
 
@@ -309,8 +310,9 @@ Types:
 | 4 | `snapshot` is `null` | `cannot_reconcile`, `snapshot_missing` |
 | 5 | `decide(ont, action, snapshot, scope, bindings, actor, now)` throws | `cannot_reconcile`, `evaluator_error`; `detail` is the error message |
 | 6 | `reported.result` is `SCOPE_DENIED`, or is neither an invocation result (`INVOCATION_RESULTS`) nor the `result` of a decision row or of `otherwise` of this action | `cannot_reconcile`, `runtime_unmapped`; `detail` is `reported.result` |
-| 7 | the result is INDETERMINATE | `cannot_reconcile`, `indeterminate`; `detail` is its reason |
-| 8 | otherwise: `evaluator` is `externalResult` of the result without `param` (a domain result is `{result}`; `INVALID_BINDING` keeps `reason`) | `match` with `result = evaluator` when the three results are pairwise equal; else `mismatch` |
+| 7 | `expected.result` is `SCOPE_DENIED`, or is neither an invocation result (`INVOCATION_RESULTS`) nor the `result` of a decision row or of `otherwise` of this action | `cannot_reconcile`, `expectation_unmapped`; `detail` is `expected.result` |
+| 8 | the result is INDETERMINATE | `cannot_reconcile`, `indeterminate`; `detail` is its reason |
+| 9 | otherwise: `evaluator` is `externalResult` of the result without `param` (a domain result is `{result}`; `INVALID_BINDING` keeps `reason`) | `match` with `result = evaluator` when the three results are pairwise equal; else `mismatch`. When the result is a domain result, the row also has `row`: the `row` that `decide` gave (the index of the decision row, from 0, or `otherwise`). The runtime does not report a row, so `row` is always the row that `decide` chose |
 
 Two `Reported` values are equal when `result` is equal and `reason` is equal (both absent counts as equal).
 
@@ -318,11 +320,13 @@ A missing runtime result is never filled in from the decision table; neither is
 
 Once an invocation is inside the domain path of an action with a decision table, the runtime must report the domain result explicitly. A coarse signal, such as the status of a receipt, must not stand in for it: a coarse value can share a name with the expected result and give a false match. `runtime_missing` (nothing reported) and `runtime_unmapped` (a value the action cannot give) record the two ways this evidence fails.
 
-`projectSnapshot(ont, stores, decode)` turns stored rows (keyed by datasource) into a typed `Snapshot` (keyed by object type) and returns `{snapshot, defects}`:
+`expectation_unmapped` (an expected result the action cannot give) is a defect of the scenario, not of the runtime or the ontology. Defects of the input (steps 6 and 7) come before the evaluator's own gap (INDETERMINATE, step 8).
 
-1. A link type with a `table` that is not the `datasource` of any object type (a pure link) is not projected: the function throws `pure link <id> is not projected`.
+`projectSnapshot(ont, stores, decode, linkColumns?)` turns stored rows (keyed by table name) into a typed `Snapshot` (objects keyed by object type, pure links keyed by link id) and returns `{snapshot, defects}`:
+
+1. For each link type with a `table` that is not the `datasource` of any object type (a pure link), in array order: when `linkColumns` has no entry for its id, the function throws `pure link <id> is not projected`; a missing store throws `snapshot lacks store <table>`. Otherwise each row is copied with all its columns except `from` and `to`; then `from` gets the value of the column `linkColumns[id].from` and `to` gets the value of the column `linkColumns[id].to`. A mapped column absent from the row is not projected (`decide` throws when it reads it). Link columns are not decoded and give no defects. An entry of `linkColumns` that is not a pure link id is ignored.
 2. For each object type, in key order: a missing store throws `snapshot lacks store <datasource>`. Otherwise each row is copied with all its columns, and then each property `p` with a declared `type` is projected: a column absent from the row is not projected and is not a defect (`decide` throws when it reads it, as for any incomplete snapshot); a null value stays null and is never passed to `decode`; any other value goes through `decode(raw, type)`, and a result that is `undefined` or does not fit the type (`fitsType`) is a defect `{object, prop: p, row: String(row.id), value: raw}`, and the column keeps its raw value; else the column gets the decoded value. Columns without a declared type are kept as they are.
-3. The result is `{snapshot: {objects}, defects}`; `snapshot.links` is not set. When `defects` is not empty the snapshot holds raw values for those columns; do not reconcile with it.
+3. The result is `{snapshot: {objects, links}, defects}`, with one `links` entry per pure link; when the ontology has no pure link, `snapshot.links` is not set. When `defects` is not empty the snapshot holds raw values for those columns; do not reconcile with it.
 
 The physical type mapping is checked here: the profile supplies `decode`, which turns a stored value (for example the integers 0 and 1 of SQLite for a boolean) into a value of the declared type, and `fitsType` checks the result.
 
@@ -330,7 +334,7 @@ The physical type mapping is checked here: the profile supplies `decode`, which
 
 ### 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.
+`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).
 
 ### Known limit
 

package/dist/src/evaluate.js

@@ -77,7 +77,9 @@ class Session {
     linkRows(link) {
         let rows = this.links.get(link.id);
         if (rows === undefined) {
-            const all = own(this.env.snapshot.links, link.id) ?? [];
+            const all = own(this.env.snapshot.links, link.id);
+            if (all === undefined)
+                throw new Error(`snapshot lacks link ${link.id}`);
             const by = this.ont.scope?.by;
             const tenantEnd = this.mode(link.from) === "tenant" || this.mode(link.to) === "tenant";
             rows = by !== undefined && tenantEnd ? all.filter((r) => field(r, by, `${link.id} link row`) === this.env.scope) : all;

package/dist/src/reconcile.d.ts

@@ -18,12 +18,13 @@ export interface RuntimeCase {
     reported: Reported | null;
     expected: Reported | null;
 }
-export type CannotReconcile = "envelope" | "runtime_missing" | "expectation_missing" | "snapshot_missing" | "evaluator_error" | "runtime_unmapped" | "indeterminate";
+export type CannotReconcile = "envelope" | "runtime_missing" | "expectation_missing" | "snapshot_missing" | "evaluator_error" | "runtime_unmapped" | "indeterminate" | "expectation_unmapped";
 export type ReconcileRow = {
     id: string;
     action: string;
     status: "match";
     result: Reported;
+    row?: number | "otherwise";
 } | {
     id: string;
     action: string;
@@ -31,6 +32,7 @@ export type ReconcileRow = {
     evaluator: Reported;
     reported: Reported;
     expected: Reported;
+    row?: number | "otherwise";
 } | {
     id: string;
     action: string;
@@ -46,7 +48,12 @@ export type TypeDefect = {
     row: string;
     value: unknown;
 };
-export declare function projectSnapshot(ont: Stage1Ontology, stores: Readonly<Record<string, readonly Readonly<Record<string, unknown>>[]>>, decode: Decode): {
+/** For each pure link id: the columns of its table that hold the `from` and `to` ids. */
+export type LinkColumns = Readonly<Record<string, {
+    readonly from: string;
+    readonly to: string;
+}>>;
+export declare function projectSnapshot(ont: Stage1Ontology, stores: Readonly<Record<string, readonly Readonly<Record<string, unknown>>[]>>, decode: Decode, linkColumns?: LinkColumns): {
     snapshot: Snapshot;
     defects: TypeDefect[];
 };

package/dist/src/reconcile.js

@@ -3,12 +3,27 @@ import { decide, externalResult } from "./evaluate.js";
 import { fitsType, INVOCATION_RESULTS, own } from "./expr.js";
 // Stored rows (physical values) -> a typed snapshot. Each property with a declared type is decoded and then checked with
 // fitsType; a value that cannot be decoded or does not fit is a defect and keeps its raw value. Null is never decoded.
-// An absent column is not projected (decide throws when it reads it: an incomplete snapshot). Pure link tables fail closed.
-export function projectSnapshot(ont, stores, decode) {
+// An absent column is not projected (decide throws when it reads it: an incomplete snapshot). A pure link is projected only with a linkColumns entry; without one it fails closed.
+export function projectSnapshot(ont, stores, decode, linkColumns) {
     const datasources = new Set(Object.values(ont.objectTypes).map((o) => o.datasource));
-    for (const l of ont.linkTypes)
-        if (l.table !== undefined && !datasources.has(l.table))
+    const links = {};
+    for (const l of ont.linkTypes) {
+        if (l.table === undefined || datasources.has(l.table))
+            continue;
+        const cols = own(linkColumns, l.id);
+        if (cols === undefined)
             throw new Error(`pure link ${l.id} is not projected`);
+        if (!Object.hasOwn(stores, l.table))
+            throw new Error(`snapshot lacks store ${l.table}`);
+        links[l.id] = stores[l.table].map((stored) => {
+            const { from: _from, to: _to, ...row } = stored;
+            if (Object.hasOwn(stored, cols.from) && stored[cols.from] !== undefined)
+                row.from = stored[cols.from];
+            if (Object.hasOwn(stored, cols.to) && stored[cols.to] !== undefined)
+                row.to = stored[cols.to];
+            return row;
+        });
+    }
     const objects = {};
     const defects = [];
     for (const [object, o] of Object.entries(ont.objectTypes)) {
@@ -29,7 +44,7 @@ export function projectSnapshot(ont, stores, decode) {
             return row;
         });
     }
-    return { snapshot: { objects }, defects };
+    return { snapshot: Object.keys(links).length > 0 ? { objects, links } : { objects }, defects };
 }
 // Strict on reason: both absent is equal; INVALID_BINDING with different reasons is not.
 const same = (a, b) => a.result === b.result && a.reason === b.reason;
@@ -55,6 +70,7 @@ export function domainResults(ont, actionId) {
 // expectation is reported as such, never filled in from the decision table. Envelope results are not decisions (the
 // evaluator does not implement the envelope; a replay does not recompute domain conditions), so decide is not called.
 // A reported result that the action cannot give (runtime_unmapped) means the runtime did not report its domain result.
+// An expected result that the action cannot give (expectation_unmapped) is a defect of the scenario.
 export function reconcile(ont, cases) {
     return cases.map((c) => {
         const head = { id: c.id, action: c.action };
@@ -76,14 +92,19 @@ export function reconcile(ont, cases) {
         catch (e) {
             return cannot("evaluator_error", e instanceof Error ? e.message : String(e));
         }
-        // SCOPE_DENIED is internal (SPEC section 9, Existence is not revealed): never a reportable result.
-        const reportable = reported.result !== "SCOPE_DENIED" && (INVOCATION.includes(reported.result) || domainResults(ont, c.action).includes(reported.result));
-        if (!reportable)
+        // A result this action can give: not SCOPE_DENIED (internal: SPEC section 9, Existence is not revealed), and an
+        // invocation result or one of its domain results. Defects of the input (runtime, then scenario) come before INDETERMINATE.
+        const results = domainResults(ont, c.action);
+        const mapped = (r) => r !== "SCOPE_DENIED" && (INVOCATION.includes(r) || results.includes(r));
+        if (!mapped(reported.result))
             return cannot("runtime_unmapped", reported.result);
+        if (!mapped(expected.result))
+            return cannot("expectation_unmapped", expected.result);
         if (d.layer === "indeterminate")
             return cannot("indeterminate", d.reason);
         const { result, reason } = externalResult(d);
         const evaluator = reason !== undefined ? { result, reason } : { result };
-        return same(evaluator, reported) && same(evaluator, expected) ? { ...head, status: "match", result: evaluator } : { ...head, status: "mismatch", evaluator, reported, expected };
+        const row = d.layer === "domain" ? { row: d.row } : {};
+        return same(evaluator, reported) && same(evaluator, expected) ? { ...head, status: "match", result: evaluator, ...row } : { ...head, status: "mismatch", evaluator, reported, expected, ...row };
     });
 }

package/package.json

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