aontu 0.53.0 → 0.55.0

package/dist/sig.js

@@ -0,0 +1,277 @@
+"use strict";
+/* Copyright (c) 2021-2026 Richard Rodger, MIT License */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.funcSig = void 0;
+exports.parseSigLine = parseSigLine;
+exports.parseSigText = parseSigText;
+exports.renderSig = renderSig;
+exports.renderSigArg = renderSigArg;
+// THE SIGNATURE REGISTRY (docs/design/SIGNATURES.0.md). The call
+// surface of the built-in functions is DECLARED, in the signature
+// syntax itself, in test/spec/signature.tsv; this module is the
+// TypeScript half of the pair that reads it. The declaration text is
+// inlined at build time (ts/src/sigdecl.ts, `make sig`) and parsed at
+// initialisation by the signature grammar -- a custom tabnas grammar,
+// the same engine the aontu grammar itself is built on -- into the
+// registry the runtime signature checker, the error-message builder,
+// the docs table and the LSP all consume. Neither port authors a
+// table: go/sig.go parses the same text with the same grammar, and
+// the shared suite round-trips every line (render(parse(line)) is the
+// line) so the two parsers cannot drift.
+//
+//   line = name '(' [ arg {',' arg} ] ')' ':' type
+//   arg  = [mode] name ['?'] ':' type
+//        | '...' name ':' ( type | '(' [mode] type {',' [mode] type} ')' )
+//   type = word {'|' word}
+//   mode = 'capture' | 'template' | 'trial' | 'projector' | 'text'
+//
+// `value` mode is unmarked; the five marked modes are the vocabulary
+// plain pseudo-TypeScript cannot say (a captured spelling is not a
+// string value). The grammar is line-oriented: the loader strips
+// comment and blank lines and parses each declaration line alone, so
+// the grammar never sees line structure.
+const parser_1 = require("@tabnas/parser");
+const sigdecl_1 = require("./sigdecl");
+const ARG_MODES = {
+    capture: true, template: true, trial: true, projector: true, text: true,
+};
+// The signature grammar, as a tabnas grammar plugin. Rules: sig (the
+// line) -> args -> arg -> argtype -> type | group -> gmember. Alts
+// match at most two tokens, the engine's shape; lists loop the
+// json-grammar way (the element rule replaces itself on ',' and
+// backtracks the closer for its parent to consume).
+function sigGrammar(tn) {
+    tn.options({
+        fixed: {
+            token: {
+                '#OP': '(',
+                '#CP': ')',
+                '#QM': '?',
+                '#PI': '|',
+                '#DD': '...',
+            },
+        },
+        rule: { start: 'sig' },
+    });
+    // Parse-level validation errors, collected by the actions: the
+    // engine's own errors cover token shape, these cover word choice (a
+    // mode that is not a mode). Read after parse by parseSigLine.
+    const errs = [];
+    tn.sigErrs = errs;
+    const mode = (word) => {
+        if (true !== ARG_MODES[word]) {
+            errs.push('mode:' + word);
+            return 'value';
+        }
+        return word;
+    };
+    tn.grammar({
+        ref: {
+            '@sig-bo': (r) => {
+                r.node = { name: '', args: [], out: '' };
+                r.u.words = [];
+            },
+            '@signame': (r) => {
+                r.node.name = String(r.o0.val);
+            },
+            '@sigargs': (r) => {
+                r.node.args = r.child.node;
+            },
+            '@sigout': (r) => {
+                r.node.out = r.u.words.join('|');
+            },
+            '@args-bo': (r) => {
+                r.node = [];
+            },
+            '@arg-bo': (r) => {
+                r.u.sig = { name: '', mode: 'value', type: '' };
+            },
+            '@arg-rest': (r) => {
+                r.u.sig.rest = true;
+                r.u.sig.name = String(r.o1.val);
+            },
+            '@arg-modename': (r) => {
+                r.u.sig.mode = mode(String(r.o0.val));
+                r.u.sig.name = String(r.o1.val);
+            },
+            '@arg-name': (r) => {
+                r.u.sig.name = String(r.o0.val);
+            },
+            '@arg-opt': (r) => {
+                r.u.sig.opt = true;
+            },
+            '@arg-done': (r) => {
+                const sig = r.u.sig;
+                const at = r.child.node;
+                if (Array.isArray(at)) {
+                    sig.group = at;
+                    sig.type = '';
+                }
+                else {
+                    sig.type = String(at);
+                }
+                r.node.push(sig);
+            },
+            '@argtype-bo': (r) => {
+                r.u.words = [];
+            },
+            '@argtype-bc': (r) => {
+                r.node = 0 < r.u.words.length ?
+                    r.u.words.join('|') : r.child.node;
+            },
+            '@type-word': (r) => {
+                r.parent.u.words.push(String(r.o0.val));
+            },
+            '@group-bo': (r) => {
+                r.node = [];
+            },
+            '@gm-two': (r) => {
+                r.u.gm = { mode: mode(String(r.o0.val)), type: String(r.o1.val) };
+            },
+            '@gm-one': (r) => {
+                r.u.gm = { mode: 'value', type: String(r.o0.val) };
+            },
+            '@gm-done': (r) => {
+                r.node.push(r.u.gm);
+            },
+        },
+        rule: {
+            sig: {
+                open: [
+                    { s: '#TX #OP', a: '@signame', p: 'args' },
+                ],
+                close: [
+                    { s: '#CL', p: 'type', a: '@sigargs' },
+                    { s: '#ZZ', a: '@sigout' },
+                ],
+            },
+            args: {
+                open: [
+                    { s: '#CP', b: 1 },
+                    { p: 'arg' },
+                ],
+                close: [
+                    { s: '#CP' },
+                ],
+            },
+            arg: {
+                open: [
+                    { s: '#DD #TX', a: '@arg-rest' },
+                    { s: '#TX #TX', a: '@arg-modename' },
+                    { s: '#TX', a: '@arg-name' },
+                ],
+                close: [
+                    { s: '#QM #CL', a: '@arg-opt', p: 'argtype' },
+                    { s: '#CL', p: 'argtype' },
+                    { s: '#CA', a: '@arg-done', r: 'arg' },
+                    { s: '#CP', a: '@arg-done', b: 1 },
+                ],
+            },
+            argtype: {
+                open: [
+                    { s: '#OP', p: 'group' },
+                    { p: 'type' },
+                ],
+                close: [
+                    {},
+                ],
+            },
+            type: {
+                open: [
+                    { s: '#TX', a: '@type-word' },
+                ],
+                close: [
+                    { s: '#PI', r: 'type' },
+                    {},
+                ],
+            },
+            group: {
+                open: [
+                    { p: 'gmember' },
+                ],
+                close: [
+                    { s: '#CP' },
+                ],
+            },
+            gmember: {
+                open: [
+                    { s: '#TX #TX', a: '@gm-two' },
+                    { s: '#TX', a: '@gm-one' },
+                ],
+                close: [
+                    { s: '#CA', a: '@gm-done', r: 'gmember' },
+                    { s: '#CP', a: '@gm-done', b: 1 },
+                ],
+            },
+        },
+    });
+}
+let sigParser = undefined;
+function makeSigParser() {
+    if (undefined === sigParser) {
+        sigParser = new parser_1.Tabnas({ plugins: [sigGrammar] });
+    }
+    return sigParser;
+}
+// Parse ONE declaration line. A malformed line is an Error: the
+// declaration is repository content, read at build and test time, so
+// failing loudly is the right shape (the round-trip suite holds the
+// gate).
+function parseSigLine(line) {
+    const tn = makeSigParser();
+    tn.sigErrs.length = 0;
+    const out = tn.parse(line);
+    if (0 < tn.sigErrs.length) {
+        throw new Error('signature: bad declaration ' +
+            tn.sigErrs.join(',') + ': ' + line);
+    }
+    if (null == out || '' === out.name || '' === out.out) {
+        throw new Error('signature: incomplete declaration: ' + line);
+    }
+    return out;
+}
+// Render one argument of a signature -- the piece the LSP's
+// signatureHelp parameters share with the whole-line renderer.
+function renderSigArg(a) {
+    const type = undefined === a.group ? a.type :
+        '(' + a.group.map((g) => ('value' === g.mode ? '' : g.mode + ' ') + g.type).join(', ') + ')';
+    return (true === a.rest ? '...' : '') +
+        ('value' === a.mode || true === a.rest ? '' : a.mode + ' ') +
+        a.name +
+        (true === a.opt ? '?' : '') +
+        ': ' + type;
+}
+// Render the canonical line for a parsed signature -- the round-trip
+// twin of parseSigLine, and the one renderer every consumer (hints,
+// docs, LSP) uses.
+function renderSig(sig) {
+    return sig.name + '(' +
+        sig.args.map(renderSigArg).join(', ') + ') : ' + sig.out;
+}
+// Parse the whole declaration text: comment (#) and blank lines are
+// the loader's to skip, one FuncSig per remaining line, name-keyed.
+// A duplicate name is an error for the same reason a bad line is.
+function parseSigText(text) {
+    const reg = {};
+    for (const rawline of text.split('\n')) {
+        const line = rawline.trim();
+        if ('' === line || line.startsWith('#')) {
+            continue;
+        }
+        const sig = parseSigLine(line);
+        if (undefined !== reg[sig.name]) {
+            throw new Error('signature: duplicate declaration: ' + sig.name);
+        }
+        reg[sig.name] = sig;
+    }
+    return reg;
+}
+// The parsed registry, built once from the inlined declaration -- the
+// one source every consumer (the arity tables, the runtime gate, the
+// hints, the docs table, the LSP) reads. A parse failure here throws
+// at module load: the inlined text is repository content whose parse
+// the round-trip suite gates, so a failure is a build defect, not a
+// runtime condition. Twin: funcSig in go/sig.go.
+const funcSig = parseSigText(sigdecl_1.SIGDECL); /* node:coverage ignore next 9 */
+exports.funcSig = funcSig;
+//# sourceMappingURL=sig.js.map

package/dist/sig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sig.js","sourceRoot":"","sources":["../src/sig.ts"],"names":[],"mappings":"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"}

package/dist/sigdecl.d.ts

@@ -0,0 +1,2 @@
+declare const SIGDECL: string;
+export { SIGDECL };

package/dist/sigdecl.js

@@ -0,0 +1,11 @@
+"use strict";
+/* Copyright (c) 2021-2026 Richard Rodger, MIT License */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SIGDECL = void 0;
+// GENERATED by ts/scripts/sigdecl.cjs (`make sig`) from
+// test/spec/signature.tsv — DO NOT EDIT. The declaration is the
+// source (docs/design/SIGNATURES.0.md); ts/test/sig.test.ts asserts
+// this copy is identical with the shared file.
+const SIGDECL = "# The call surface: one declaration line per built-in function\n# (docs/design/SIGNATURES.0.md). THIS FILE IS THE SOURCE — both ports\n# carry a build-time-inlined copy (ts/src/sigdecl.ts, go/sigdecl.txt;\n# `make sig` regenerates both, and each port's suite asserts its copy\n# is byte-identical with this file) and parse it at initialisation\n# with the signature grammar, a tabnas grammar (ts/src/sig.ts,\n# go/sig.go). The suites also round-trip every line:\n# render(parse(line)) must be the line exactly, in both ports.\n#\n# The syntax (rendered TypeScript-ish, honest about argument MODES):\n#   line = name '(' [ arg {',' arg} ] ')' ':' type\n#   arg  = [mode] name ['?'] ':' type\n#        | '...' name ':' '(' [mode] type {',' [mode] type} ')'\n#   type = word {'|' word}\n#   mode = 'capture' | 'template' | 'trial' | 'projector' | 'text'\n# `value` mode is unmarked. `constraint` is the result word for\n# residuals whose meet depends on the peer; `any` is the honest type\n# where a function is a wrapper.\nupper(s: string|number) : string\nlower(s: string|number) : string\ncopy(v: any) : any\npref(v: any) : any\nsuper(t: any) : any\ntype(t: any) : any\nhide(v: any) : any\nclose(m: any) : any\nopen(m: any) : any\nmove(v: any) : any\npath(capture p?: path) : path\nmap() : map\nlist() : list\nmin(n: number|string) : constraint\nmax(n: number|string) : constraint\nabove(n: number|string) : constraint\nbelow(n: number|string) : constraint\nre(text p: string) : constraint\nlength(n: number|constraint) : constraint\nkey(up?: integer|biginteger) : string\nunique(projector k?: string) : constraint\nneq(...vals: number|string) : constraint\nmust(trial c: any, text msg: string) : constraint\ndeprecate(v: any, r?: map) : any\nacyclic() : constraint\ninverse(projector k: string) : constraint\nrefer(template t?: any) : constraint\nrel(template t?: any) : constraint\npack(d: map|list, template t: any) : map\neach(d: map|list, template t?: any) : list\nfilter(d: map|list, trial c: any) : map|list\nmatch(s: any, ...pr: (trial any, any), dflt?: any) : any\nadd(a: number, b: number) : number\nsub(a: number, b: number) : number\nmul(a: number, b: number) : number\ndiv(a: number, b: number) : number\nmod(a: number, b: number) : number\nrem(a: number, b: number) : number\nsum(d: map|list) : number\nleast(d: map|list) : number\ngreatest(d: map|list) : number\npick(d: map|list, projector k: string|integer) : any\njoin(d: map|list, sep?: string) : string\n";
+exports.SIGDECL = SIGDECL;
+//# sourceMappingURL=sigdecl.js.map

package/dist/sigdecl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sigdecl.js","sourceRoot":"","sources":["../src/sigdecl.ts"],"names":[],"mappings":";AAAA,yDAAyD;;;AAEzD,wDAAwD;AACxD,gEAAgE;AAChE,oEAAoE;AACpE,+CAA+C;AAE/C,MAAM,OAAO,GACb,46EAA46E,CAAA;QAEn6E,OAAO"}

package/dist/siggate.d.ts

@@ -0,0 +1,4 @@
+import type { Val } from './type';
+import { AontuContext } from './ctx';
+declare function sigRefuse(ctx: AontuContext, fn: any, args: Val[]): Val | undefined;
+export { sigRefuse, };

package/dist/siggate.js

@@ -0,0 +1,90 @@
+"use strict";
+/* Copyright (c) 2021-2026 Richard Rodger, MIT License */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sigRefuse = sigRefuse;
+const err_1 = require("./err");
+const sig_1 = require("./sig");
+const ScalarKindVal_1 = require("./val/ScalarKindVal");
+// The scalar-kind words the gate enforces, each to its lattice
+// marker. A declared type is gate-checkable only when EVERY union
+// word is here: `any`, `constraint`, and the container words leave
+// the argument to the builtin.
+const SIG_KIND = new Map([
+    ['string', String],
+    ['number', Number],
+    ['integer', ScalarKindVal_1.Integer],
+    ['float', ScalarKindVal_1.Float],
+    ['biginteger', ScalarKindVal_1.BigInteger],
+    ['bigdecimal', ScalarKindVal_1.BigDecimal],
+    ['boolean', Boolean],
+    ['path', ScalarKindVal_1.Path],
+]);
+function gateWords(type) {
+    const out = [];
+    for (const word of type.split('|')) {
+        const marker = SIG_KIND.get(word);
+        if (undefined === marker) {
+            return undefined;
+        }
+        out.push(marker);
+    }
+    return out;
+}
+// The declared type admits a driven Val when the Val is a concrete
+// scalar whose leaf kind is, or sits below, one of the declared
+// words -- the same walk subsumption makes, so `number` admits every
+// numeric leaf and `string` admits a path value.
+function admits(markers, arg) {
+    const leaf = arg.superior?.();
+    if (true !== arg.isScalar || true !== leaf?.isScalarKind) {
+        return false;
+    }
+    for (const marker of markers) {
+        if (marker === leaf.peg || (0, ScalarKindVal_1.kindSubsumes)(marker, leaf.peg)) {
+            return true;
+        }
+    }
+    return false;
+}
+// The gate. Answers the func_arg refusal, or undefined to let the
+// call resolve.
+function sigRefuse(ctx, fn, args) {
+    const sig = sig_1.funcSig[fn.funcname()];
+    // key() reads its level off the written peg and `key_level` names
+    // what is wrong with a bad one; the gate leaves the meaning where
+    // it lives.
+    if (undefined === sig || 'key' === sig.name) {
+        return undefined;
+    }
+    for (let i = 0; i < sig.args.length; i++) {
+        const a = sig.args[i];
+        if (true === a.rest) {
+            break;
+        }
+        if ('value' !== a.mode) {
+            continue;
+        }
+        const markers = gateWords(a.type);
+        if (undefined === markers) {
+            continue;
+        }
+        const arg = args[i];
+        if (undefined === arg || true === arg.isNil || true !== arg.done) {
+            continue;
+        }
+        const shaped = (true === arg.isScalar) ||
+            (true === arg.isMap) || (true === arg.isList) ||
+            (true === arg.isScalarKind);
+        if (shaped && !admits(markers, arg)) {
+            return (0, err_1.makeNilErr)(ctx, 'func_arg', fn, arg, undefined, {
+                func: sig.name,
+                sig: (0, sig_1.renderSig)(sig),
+                arg: a.name,
+                argn: '' + (i + 1),
+                got: arg.canon,
+            });
+        }
+    }
+    return undefined;
+} /* node:coverage ignore next 5 */
+//# sourceMappingURL=siggate.js.map

package/dist/siggate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"siggate.js","sourceRoot":"","sources":["../src/siggate.ts"],"names":[],"mappings":"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"}

package/dist/std.js

@@ -33,9 +33,9 @@ std: {
     protocol?: string
   })
 
-  # A node with ports. A Component that is not itself an entity is a
-  # component OF its nearest identified ancestor, which is the
-  # entity/component distinction and needs no mark of its own.
+  # A node with ports. Where a Component sits in the tree is what it
+  # is a component OF -- containment is the document's own structure
+  # and needs no mark of its own.
   Component: type({
     ports?: {&: $.std.Port}
   })
@@ -50,24 +50,83 @@ std: {
     ports?: {&: $.std.Port}
   })
 
-  # A DECLARED RELATION. "target" is what the far end must satisfy,
-  # "inverse" names the relation that must mirror it, and "acyclic"
-  # asks that the edge set have no cycle. The last two are checked
-  # AFTER unification, not by it: they are global and non-monotone ---
-  # an acyclic graph becomes cyclic when one more edge unifies in ---
-  # and no lattice citizen may be falsified by more information.
-  Relation: type({
-    target?: top
-    inverse?: string
-    acyclic?: *false | boolean
+  # (The Relation schema that used to sit here is retired with the
+  # relations: magic key, RELATIONS.0.md P2: a relation is declared
+  # by the graph atoms at its field -- rel(t) & acyclic() &
+  # inverse(name) -- and the target half is rel(t)'s flow.)
+}
+`;
+const STD_VIEW = `# std/view --- the FIGURE VOCABULARY (VIEWS.0.md, "6. The view
+# document"). A view document declares its figures as data, and a
+# declaration is just a map: this is the schema for one, so a typo is
+# refused where every other mistake in an Aontu document is refused --
+# at evaluation, by unification -- rather than by the verb that reads
+# it afterwards.
+#
+#   @"std/view"
+#   @"./system.aon"
+#
+#   views: {&: $.view.Figure} & {
+#     arch: {kind: matrix, order: partition, out: "docs/arch.dsm.txt"}
+#   }
+#
+# The keys ARE the view options: the command-line flags without the
+# dashes, one vocabulary for the CLI, the library and the file. The
+# poset is not among the kinds, because a view document declares
+# figures of the ONE document it includes and the poset compares
+# several.
+#
+# EXPERIMENTAL until the distribution layer can version it by
+# canon-hash. This file carries no backtick: it is one string literal
+# per port, and Go raw strings have no escape.
+
+view: {
+
+  # One declared figure. The kind says what to draw and out says where
+  # it belongs; everything else narrows the drawing, and each option
+  # belongs to the kinds that read it.
+  Figure: type({
+    kind: doc | tree | matrix | graph | layer | sets | layers | ladder
+    out: string
+
+    # Every kind.
+    as?: text | mermaid | dot | er | svg
+    at?: string
+    maxRows?: integer & min(0)
+
+    # doc: how many levels of key to draw.
+    depth?: integer & min(0)
+
+    # tree, matrix, layer: the relation drawn. graph: the predicates
+    # kept. tree: the subtrees drawn.
+    relation?: string
+    relations?: [&: string]
+    roots?: [&: string]
+
+    # matrix.
+    order?: canon | partition
+    closure?: boolean
+
+    # graph, layer.
+    groupBy?: string
+    label?: string
+    layers?: [&: string]
+    edges?: upward | all | none
+
+    # sets, layers.
+    sets?: string
+    member?: string
+    universe?: string
+    minDegree?: integer & min(0)
+    maxCols?: integer & min(0)
+    minSize?: integer & min(0)
   })
 }
 `;
-// The bundled sources, by the name a document writes. Both the bare
-// name and the `.aon` spelling resolve, because both are what an
-// author reaches for.
 exports.STD_SOURCES = {
     'std/system': STD_SYSTEM,
     'std/system.aon': STD_SYSTEM,
+    'std/view': STD_VIEW,
+    'std/view.aon': STD_VIEW,
 };
 //# sourceMappingURL=std.js.map

package/dist/std.js.map

@@ -1 +1 @@
-{"version":3,"file":"std.js","sourceRoot":"","sources":["../src/std.ts"],"names":[],"mappings":";AAAA,oDAAoD;;;AAEpD,sCAAsC;AACtC,uEAAuE;AACvE,uEAAuE;AACvE,mEAAmE;AACnE,sEAAsE;AACtE,4BAA4B;AAC5B,EAAE;AACF,qEAAqE;AACrE,oEAAoE;AACpE,oEAAoE;AACpE,uEAAuE;AACvE,qCAAqC;AAErC,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDlB,CAAA;AAGD,oEAAoE;AACpE,iEAAiE;AACjE,sBAAsB;AACT,QAAA,WAAW,GAA2B;IACjD,YAAY,EAAE,UAAU;IACxB,gBAAgB,EAAE,UAAU;CAC7B,CAAA"}
+{"version":3,"file":"std.js","sourceRoot":"","sources":["../src/std.ts"],"names":[],"mappings":";AAAA,oDAAoD;;;AAEpD,sCAAsC;AACtC,uEAAuE;AACvE,uEAAuE;AACvE,mEAAmE;AACnE,sEAAsE;AACtE,4BAA4B;AAC5B,EAAE;AACF,qEAAqE;AACrE,oEAAoE;AACpE,oEAAoE;AACpE,uEAAuE;AACvE,qCAAqC;AAErC,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyClB,CAAA;AAGD,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkEhB,CAAA;AAGY,QAAA,WAAW,GAA2B;IACjD,YAAY,EAAE,UAAU;IACxB,gBAAgB,EAAE,UAAU;IAC5B,UAAU,EAAE,QAAQ;IACpB,cAAc,EAAE,QAAQ;CACzB,CAAA"}

package/dist/subsume.js

@@ -9,6 +9,7 @@ const vet_1 = require("./vet");
 const hcanon_1 = require("./hcanon");
 const ConstraintVal_1 = require("./val/ConstraintVal");
 const ScalarKindVal_1 = require("./val/ScalarKindVal");
+const PathVal_1 = require("./val/PathVal");
 const PrefVal_1 = require("./val/PrefVal");
 const DEFAULT_GENERAL_URL = 'general';
 const DEFAULT_SPECIFIC_URL = 'specific';
@@ -253,6 +254,20 @@ function subsumeNode(state, path, g0, s0) {
         record(state, 'compat_narrowed', path, g, s, 'the general kind admits no such value');
         return 'no';
     }
+    // Container kinds (docs/design/PATHS.0.md): `map()` subsumes every
+    // map and itself, `list()` every list. The unit literals (`{}`,
+    // `[]`) already subsume through the container rules; only the kind
+    // former needs an arm.
+    if (true === g?.isContainerKind) {
+        const ga = g;
+        const sa = s;
+        if ((true === ga.isMapKind && (true === sa?.isMap || true === sa?.isMapKind))
+            || (true === ga.isListKind && (true === sa?.isList || true === sa?.isListKind))) {
+            return 'yes';
+        }
+        record(state, 'compat_narrowed', path, g, s, 'the general container kind admits no such value');
+        return 'no';
+    }
     // Constraint residuals.
     if (true === g?.isConstraint) {
         if (true === s?.isConstraint) {
@@ -283,8 +298,14 @@ function subsumeNode(state, path, g0, s0) {
         return 'no';
     }
     // Concrete scalars subsume only themselves (identity compares kind
-    // as well as value).
+    // as well as value) -- except paths, whose meet is the prefix rule
+    // (ADR-016): a prefix admits every extension of itself, so it
+    // subsumes one, exactly as the meet answers the longer.
     if (true === g?.isScalar) {
+        if (true === g.isPath && true === s?.isPath &&
+            (0, PathVal_1.prefixMeet)(g.peg, s.peg) === s.peg) {
+            return 'yes';
+        }
         if (true === s?.isScalar && true === g.same?.(s)) {
             return 'yes';
         }
@@ -310,13 +331,29 @@ function subsumeNode(state, path, g0, s0) {
         const sk = s.peg.map((_, i) => '' + i);
         return subsumeBag(state, path, g, s, gk, sk, (v, k) => v.peg[Number(k)]);
     }
-    // The ladder above is total in practice: every evaluated former is a
-    // scalar, kind, constraint, map, list, disjunct, or top, or is caught
-    // by admission (pref) or unresolved (ref, var, conjunct, expect,
-    // func). The arm is kept because "in practice" is evaluation's
-    // property, not this walk's, and a future value class (or a nil, see
-    // the top rule) must land on an honest `undecided`, not fall out of
-    // the walk with no answer.
+    // THE LADDER IS NOT TOTAL, and the formers that fall past it are the
+    // ones the evaluator MEANS to leave standing: a recursion, a
+    // relation and its graph atom, a `refer()` target constraint. None
+    // of them describes a set of values a structural walk can compare,
+    // so `undecided` is the honest answer for two DIFFERENT ones.
+    //
+    // For two IDENTICAL ones it is not. REFLEXIVITY IS A LAW -- every
+    // value admits itself -- and identity is the HASH FORM, the same
+    // rule the unresolved branch above applies and for the same reason:
+    // it costs nothing, because it runs only where the answer would
+    // otherwise be `undecided`. Without it a document that declares a
+    // relation, shares a template by reference or alias, or recurses did
+    // not subsume ITSELF, so `breaking` on the idiom the language exists
+    // for hard-failed and had to run --allow-undecided, which masks the
+    // genuine undecideds it exists to surface (use-cases/BUGS.md 64,
+    // and 28 before it).
+    //
+    // A NIL is the exception, and the reason the law is spelled here
+    // rather than in `unresolved`: a nil is not a value, so it admits
+    // nothing, itself included.
+    if (true !== g?.isNil && true !== s?.isNil && (0, hcanon_1.hcanon)(g) === (0, hcanon_1.hcanon)(s)) {
+        return 'yes';
+    }
     record(state, 'sub_unresolved', path, g, s, 'no subsumption rule covers this pair of value formers');
     return 'undecided';
 }
@@ -373,11 +410,21 @@ function subsumeBag(state, path, g, s, gKeys, sKeys, child) {
         }
     }
     // Spread templates: a path-dependent template's meaning depends on
-    // where it lands, which no structural comparison can decide.
+    // where it lands, which no structural comparison can decide -- UNLESS
+    // the two templates are the same template. REFLEXIVITY IS A LAW and
+    // identity is the HASH FORM (the same rule the unresolved branch of
+    // subsumeNode applies): two byte-identical templates admit the same
+    // set wherever they land, so a document with a reference- or
+    // alias-valued template subsumes itself, and the comparison either
+    // side of the template is decided on its own merits rather than
+    // dragged to `undecided` (use-cases/BUGS.md 64). Where they are NOT
+    // identical, nothing structural can decide them and the fold stands.
     const gcj = g.spread?.cj;
     const scj = s.spread?.cj;
     if (null != gcj || null != scj) {
-        if (true === gcj?.isPathDependent || true === scj?.isPathDependent) {
+        const sameTemplate = null != gcj && null != scj && (0, hcanon_1.hcanon)(gcj) === (0, hcanon_1.hcanon)(scj);
+        if (!sameTemplate &&
+            (true === gcj?.isPathDependent || true === scj?.isPathDependent)) {
             record(state, 'sub_path_dependent_spread', path, gcj ?? g, scj ?? s, 'a path-dependent spread template cannot be compared structurally');
             worse('undecided');
         }