aontu 0.52.1 → 0.53.0

package/dist/val/ConstraintVal.js

@@ -3,11 +3,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MustConstraintVal = exports.UniqueConstraintVal = exports.LengthConstraintVal = exports.ReConstraintVal = exports.NeqConstraintVal = exports.BelowConstraintVal = exports.AboveConstraintVal = exports.MaxConstraintVal = exports.MinConstraintVal = exports.ConstraintVal = void 0;
 exports.normaliseRe = normaliseRe;
+exports.constraintSubsumesConstraint = constraintSubsumesConstraint;
+exports.constraintAdmitsScalar = constraintAdmitsScalar;
 const type_1 = require("../type");
 const utility_1 = require("../utility");
 const Val_1 = require("./Val");
 const keyorder_1 = require("../keyorder");
 const ConjunctVal_1 = require("./ConjunctVal");
+const BagVal_1 = require("./BagVal");
 const top_1 = require("./top");
 const unify_1 = require("../unify");
 const IntegerVal_1 = require("./IntegerVal");
@@ -71,6 +74,17 @@ const numcmp_1 = require("./numcmp");
 // This function is mirrored statement for statement in go/constraint.go,
 // and `test/spec/files/regex-corpus.txt` pins that the two produce
 // byte-identical output for every pattern in a generated corpus.
+// The largest repeat count Aontu's pattern language admits. RE2 caps a
+// repeat at 1000 and refuses to compile past it, where JavaScript's
+// backtracking engine accepts any count -- so `re("^a{1001}$")` was
+// VALID in TypeScript and an `error` verdict in Go, a cross-port
+// verdict flip on a schema an agent could be handed
+// (status-2026-08-21.md section 4). Under ADR-003 the host's own
+// compile failure must never be what a user sees, so the bound is
+// Aontu's: at most RE_REPEAT_MAX, refused identically in both ports
+// before either engine compiles. Nested products beyond the cap were
+// already refused, by the quantified-group rule below.
+const RE_REPEAT_MAX = 1000;
 // The normative expansions. These are Aontu's definitions, not either
 // host's; both hosts are rewritten to them.
 const RE_CLASS_DIGIT = '0-9';
@@ -84,6 +98,65 @@ const RE_ESCAPE_PUNCT = '\\.+*?()[]{}|^$/';
 // Escapes passed through unchanged: the control characters, the ASCII
 // word boundary, and `\xHH`. Each was probed in both engines.
 const RE_ESCAPE_PASS = 'tnrfv';
+// A counted quantifier `{n}`, `{n,}` or `{n,m}` starting at `src[at]`.
+// Two rules, both about what the hosts do NOT share:
+//
+//  - A bound above RE_REPEAT_MAX: RE2 refuses to compile it, JavaScript
+//    accepts it.
+//  - A brace that does not open a well-formed counted quantifier at
+//    all (`x{y}`, `a{`, `{,5}`): JavaScript compiled with the `u` flag
+//    makes it a SYNTAX ERROR, while RE2 reads it as a literal brace, so
+//    `re("^x{y}$")` was `constraint_pattern` in TypeScript and a plain
+//    unresolved value in Go -- the same class of verdict flip as the
+//    repeat cap, found by sweeping around it. A literal brace is
+//    written escaped (`a\\{1001\\}`), which both engines share.
+function repeatWhy(src, at) {
+    const bad = (what) => [
+        'a ' + what + ', which the two engines do not read the same way', -1
+    ];
+    let i = at + 1;
+    let digits = '';
+    const bounds = [];
+    let commas = 0;
+    for (; i < src.length; i++) {
+        const c = src[i];
+        if ('0' <= c && c <= '9') {
+            digits += c;
+            continue;
+        }
+        if (',' === c) {
+            if ('' === digits || 0 < commas) {
+                return bad('{ that does not open a counted quantifier');
+            }
+            bounds.push(parseInt(digits, 10));
+            digits = '';
+            commas++;
+            continue;
+        }
+        if ('}' === c) {
+            if ('' !== digits) {
+                bounds.push(parseInt(digits, 10));
+            }
+            else if (0 === commas) {
+                return bad('{ that does not open a counted quantifier');
+            }
+            break;
+        }
+        return bad('{ that does not open a counted quantifier');
+    }
+    if (i >= src.length) {
+        return bad('{ that does not open a counted quantifier');
+    }
+    for (const b of bounds) {
+        if (RE_REPEAT_MAX < b) {
+            return ['a repeat count above ' + RE_REPEAT_MAX +
+                    ', which RE2 refuses to compile', -1];
+        }
+    }
+    // A descending range (`{5,2}`) is refused by both engines' own
+    // compilers, so it needs no rule here.
+    return ['', i];
+}
 function isHexDigit(c) {
     return null != c && (('0' <= c && c <= '9') || ('a' <= c && c <= 'f') || ('A' <= c && c <= 'F'));
 }
@@ -178,14 +251,32 @@ function normaliseRe(src) {
             groups[groups.length - 1][k] = true;
         }
     };
+    // Where the counted quantifier validated below closes, so its own
+    // `}` is told apart from a stray one; and whether the atom just
+    // emitted was `^` or `$`, which cannot be quantified.
+    let repeatEnd = -1;
+    let anchorPrev = false;
     for (let i = 0; i < src.length; i++) {
         const c = src[i];
+        const afterAnchor = anchorPrev;
+        anchorPrev = false;
         if ('\\' === c) {
             const [emit, why, extra] = normaliseEscape(src[i + 1], src, i, inClass);
             if ('' !== why) {
                 return ['', why];
             }
             out.push(emit);
+            // `\b` AND `\B` ARE ASSERTIONS TOO, and quantifying one is the
+            // same disagreement `^{1}` is: JavaScript under `u` calls it a
+            // syntax error, RE2 quantifies the assertion happily. The rule
+            // said "`\b` and `\B` quantify identically in both and are left
+            // alone" and that was measured wrong -- `re("\\b{1}x")` is
+            // `constraint_pattern` in TypeScript and an accepted schema in
+            // Go. Only OUTSIDE a class: inside one, `\b` is a backspace in
+            // both engines and repeats like any other character.
+            if (!inClass && ('b' === src[i + 1] || 'B' === src[i + 1])) {
+                anchorPrev = true;
+            }
             i += 1 + extra;
             continue;
         }
@@ -256,11 +347,41 @@ function normaliseRe(src) {
             continue;
         }
         if ('*' === c || '+' === c || '?' === c || '{' === c) {
+            // Nothing to repeat. JavaScript under the `u` flag makes this a
+            // SYNTAX ERROR, where RE2 quantifies the assertion happily and
+            // matches, so `re("^{1}")` was `constraint_pattern` in
+            // TypeScript and an accepted schema in Go. The four assertions
+            // behave alike here -- `^`, `$`, `\b` and `\B` -- so the rule
+            // names all four.
+            if (afterAnchor) {
+                return ['', 'a quantifier applied to `^`, `$`, `\\b` or ' +
+                        '`\\B`, which has nothing to repeat'];
+            }
+            if ('{' === c) {
+                const [why, end] = repeatWhy(src, i);
+                if ('' !== why) {
+                    return ['', why];
+                }
+                repeatEnd = end;
+            }
             mark('q');
             out.push(c);
             continue;
         }
+        // A `}` that closes no counted quantifier: JavaScript under `u`
+        // refuses it as a lone quantifier bracket, RE2 reads it as a
+        // literal. Written escaped inside a class (`[}]`) it is a literal
+        // in both, which is the spelling that survives.
+        if ('}' === c) {
+            if (i !== repeatEnd) {
+                return ['', 'a `}` that closes no counted quantifier, which ' +
+                        'the two engines do not read the same way'];
+            }
+            out.push(c);
+            continue;
+        }
         out.push(c);
+        anchorPrev = ('^' === c || '$' === c);
     }
     if (inClass) {
         return ['', 'an unterminated character class'];
@@ -328,6 +449,7 @@ class ConstraintVal extends FeatureVal_1.FeatureVal {
         this.neqs = [];
         this.res = [];
         this.uniq = false;
+        this.uniqBy = [];
         this.musts = [];
         if (spec.state) {
             this.domain = spec.state.domain;
@@ -340,6 +462,7 @@ class ConstraintVal extends FeatureVal_1.FeatureVal {
             this.res = spec.state.res ?? [];
             this.count = spec.state.count;
             this.uniq = spec.state.uniq ?? false;
+            this.uniqBy = spec.state.uniqBy ?? [];
             this.musts = spec.state.musts ?? [];
             this.invalid = spec.state.invalid;
         }
@@ -351,14 +474,22 @@ class ConstraintVal extends FeatureVal_1.FeatureVal {
             // in unify, where there is a ctx to resolve through, and the
             // residual is built from the settled arguments. Only a settled
             // argument of the wrong shape is an `invalid-arg`.
-            if (args.some((a) => true !== a?.done)) {
+            // The effectful-argument refusal happens HERE, on the written
+            // form, and not in fromAtom: settling is what runs the effect, so
+            // by the time fromAtom sees a settled `move($.b)` the move has
+            // already happened and the argument is just its result.
+            if ('must' === spec.atom && args.some((a) => holdsMove(a))) {
+                this.invalid = 'invalid-arg';
+            }
+            else if (args.some((a) => true !== a?.done)) {
                 this.pending = { atom: spec.atom, args };
             }
             else {
                 this.fromAtom(spec.atom, args);
             }
         }
-        if (null != this.count || this.uniq || 0 < this.musts.length ||
+        if (null != this.count || this.uniq || 0 < this.uniqBy.length ||
+            0 < this.musts.length ||
             (null != this.pending && lateAtom(this.pending.atom))) {
             this.cjo = LATE_CJO;
         }
@@ -377,17 +508,30 @@ class ConstraintVal extends FeatureVal_1.FeatureVal {
     // so a shape this cannot use is a genuine `invalid-arg`, not a
     // not-yet.
     fromAtom(atom, args) {
-        // Mark the residual invalid and report so (a plain boolean, so no
-        // void value is consumed by the callers' `return` statements).
+        // Mark the residual invalid. It answers NOTHING: every caller
+        // spells its exit `return bad(...)` and none reads a value, so a
+        // return type would be a value nobody consumes -- and a routine
+        // that answers on some paths and not others is the shape a reader
+        // (and a static analyser) has to stop and check.
         const bad = (why) => {
             this.invalid = why;
-            return true;
         };
-        // `unique()` takes no argument: it is a property of the container,
-        // not a comparison against a value. Arity is checked at parse, so a
-        // written argument never reaches here.
+        // `unique()` is a property of the container -- not a comparison
+        // against a value -- so with no argument it says the members are
+        // pairwise DISTINCT. THE ONE ARGUMENT IS A PROJECTOR (the review's
+        // finding I: "unique()-by-field is reserved but absent", and the
+        // arity was reserved for exactly this): `unique(port)` says no two
+        // members share a `port`, which is how "no two services share a
+        // port" and "event ids are unique" are said.
         if ('unique' === atom) {
-            this.uniq = true;
+            if (0 === args.length) {
+                this.uniq = true;
+                return;
+            }
+            if (1 !== args.length || !stringLeaf(args[0])) {
+                return bad('invalid-arg');
+            }
+            this.uniqBy = [args[0].peg];
             return;
         }
         // `must(c, msg)` is Band B: an evaluate-only check against the
@@ -411,6 +555,9 @@ class ConstraintVal extends FeatureVal_1.FeatureVal {
             if (holdsNil(args[0])) {
                 return bad('invalid-arg');
             }
+            // (An effectful argument is refused at construction, in the
+            // constructor: by the time this arm sees a settled `move($.b)`
+            // the move has already run.)
             this.musts = [{ v: args[0], msg: args[1] }];
             return;
         }
@@ -609,16 +756,17 @@ class ConstraintVal extends FeatureVal_1.FeatureVal {
         if (null == peer || peer.isTop) {
             return again;
         }
-        if (peer.isNil) {
-            return peer;
-        }
+        // No nil-peer arm: `unite` returns a nil operand before dispatching
+        // to any Val's unify (ts/src/unify.ts), so a nil never reaches here
+        // — and were one to, the conjunct below folds to it unchanged.
         return new ConjunctVal_1.ConjunctVal({ peg: [again, peer] }, ctx);
     }
     // Membership: the peer scalar passes every part of the residual, or
     // the whole meet is a located conflict.
     admit(peer, ctx) {
-        // No scalar has members, so a `unique()` residual admits none.
-        if (this.uniq) {
+        // No scalar has members, so a `unique()` residual admits none --
+        // and neither does a `unique(k)` one, for the same reason.
+        if (this.uniq || 0 < this.uniqBy.length) {
             return this.fail(ctx, peer);
         }
         if (!stateAdmits(this, peer)) {
@@ -635,7 +783,10 @@ class ConstraintVal extends FeatureVal_1.FeatureVal {
                 return this.fail(ctx, peer);
             }
         }
-        const bad = this.checkMusts(peer, ctx);
+        // A SCALAR HAS NO MEMBERS to accumulate, so its musts are decided
+        // here and never residuate: the final reading is the only reading
+        // a scalar has.
+        const bad = this.checkMusts(peer, ctx, true);
         if (null != bad) {
             return bad;
         }
@@ -649,10 +800,29 @@ class ConstraintVal extends FeatureVal_1.FeatureVal {
     // The trial runs in an isolated collect context so a failing check
     // leaves nothing on the caller's error list — only the located nil
     // this returns, carrying the author's own message.
-    checkMusts(peer, ctx) {
+    // `final` is the generation-time reading (see settleContainer): a
+    // must whose own check is a SIZING atom inherits that atom's
+    // provisionality, because `must(length(2), …)` against a map that may
+    // still gain members has not failed yet -- it has not been answered.
+    // Without this the must would decide against whatever the container
+    // held when it first settled, which is the very defect the sizing
+    // atoms were fixed for (use-cases/BUGS.md §16, §17).
+    checkMusts(peer, ctx, final) {
         for (const m of this.musts) {
             const trial = ctx.clone({ err: [], collect: true });
-            const got = (0, unify_1.unite)(trial, m.v.clone(trial), peer.clone(trial), 'must');
+            let got = (0, unify_1.unite)(trial, m.v.clone(trial), peer.clone(trial), 'must');
+            // A must whose check is a SIZING atom answers a residue rather
+            // than a verdict, because the atom is waiting for members that
+            // may still arrive. Before generation that residue IS the answer
+            // -- the must has not failed, it has not been asked yet -- and at
+            // generation it is settled, because nothing more can arrive.
+            const residue = (0, BagVal_1.sizingResidue)(got);
+            if (undefined !== residue) {
+                if (true !== final) {
+                    continue;
+                }
+                got = residue.con.settleContainer(residue.bag, trial);
+            }
             if (true === got?.isNil || 0 < trial.err.length) {
                 return (0, err_1.makeNilErr)(ctx, 'must', this, peer, undefined, {
                     message: m.msg.peg,
@@ -663,6 +833,14 @@ class ConstraintVal extends FeatureVal_1.FeatureVal {
         }
         return undefined;
     }
+    // THE FINAL READING of a sizing atom over a container: the same
+    // checks admitContainer makes, with the provisional ones taken as
+    // decided. Called from ConjunctVal.gen, which is where no more
+    // members can arrive. Returns the container (to generate) or the
+    // constraint's own nil (to report).
+    settleContainer(peer, ctx) {
+        return this.admitContainer(peer, ctx, true);
+    }
     // Membership for a container peer. Only the SIZING atoms have anything
     // to say about a map or a list; every other atom is scalar-domain and
     // refuses one.
@@ -674,7 +852,7 @@ class ConstraintVal extends FeatureVal_1.FeatureVal {
     // isolated collect context so nothing leaks into the caller's errors.
     // A mirror would be a second copy of a filter that has already grown
     // subtle, free to drift from it; asking is correct by construction.
-    admitContainer(peer, ctx) {
+    admitContainer(peer, ctx, final) {
         // A scalar-domain residual has no reading over a container.
         if (null != this.domain) {
             return this.fail(ctx, peer);
@@ -686,21 +864,76 @@ class ConstraintVal extends FeatureVal_1.FeatureVal {
             this.dc = 0;
             return new ConjunctVal_1.ConjunctVal({ peg: [this, peer] }, ctx);
         }
-        const bad = this.checkMusts(peer, ctx);
+        const bad = this.checkMusts(peer, ctx, final);
         if (null != bad) {
             return bad;
         }
-        if (!this.uniq && null == this.count) {
-            return peer;
+        // A MUST OVER A CONTAINER RESIDUATES with the atoms, for the same
+        // reason (use-cases/BUGS.md §17): `must({t: max(60)}, …)` beside a
+        // `{t: integer}` schema was answered against the schema layer
+        // ALONE, and discharged before the data it was written to judge
+        // ever arrived. It is decided at generation, where the value is
+        // whole -- unless there is nothing else on the constraint AND the
+        // reading is already final.
+        if (!this.uniq && 0 === this.uniqBy.length && null == this.count) {
+            if (true === final || 0 === this.musts.length) {
+                return peer;
+            }
+            return this.hold(peer, ctx);
         }
         const members = emittedMembers(peer, ctx);
         if (null == members) {
-            // The container cannot generate at all; its own error is the one
-            // worth reporting, so pass it through untouched.
-            return peer;
-        }
-        if (null != this.count && !stateAdmits(this.count, countVal(members.length))) {
-            return this.fail(ctx, peer);
+            // NOT COUNTABLE YET IS NOT A PASS. A container that cannot
+            // generate cannot be counted, and a SCHEMA is exactly that: the
+            // members of `{a: integer}` are types, so nothing is emitted and
+            // nothing can be counted. Discharging the atom here was the §16
+            // defect wearing its other face -- `length(min(2)) & {a: integer}`
+            // dropped its bound while still alone, so the data half of a
+            // `vet` meet was never measured at all and short data vetted
+            // clean against a bound the evaluator enforces.
+            //
+            // At generation the reading IS final: a container that still
+            // cannot generate has its own error, and that error is the one
+            // worth reporting, so it passes through untouched.
+            if (true === final) {
+                return peer;
+            }
+            return this.hold(peer, ctx);
+        }
+        // MONOTONE READINGS ONLY (the review's finding C, use-cases/BUGS.md
+        // §16). Members ACCUMULATE under unification -- a meet adds keys and
+        // never removes them -- so a settled container is settled ON ITS
+        // OWN and not against every value that may still contribute. The
+        // schema half of a `vet` meet, a document that is about to receive
+        // an `@` include, a bag a later `pack` will fill: each settles, and
+        // an atom that decided there decided too early.
+        //
+        // So a verdict is taken only when MORE MEMBERS CANNOT CHANGE IT:
+        //   - an upper bound VIOLATED is permanent -> refuse now;
+        //     satisfied is provisional -> keep the atom, re-check later.
+        //   - a lower bound SATISFIED is permanent -> that part may go;
+        //     violated is provisional -> keep the atom (which is why
+        //     `length(min(1))` beside a template no longer kills the schema
+        //     it was written for).
+        //   - a DUPLICATE is permanent -> refuse now; distinctness is
+        //     provisional -> keep the atom.
+        // Anything provisional residuates, exactly as an unsettled
+        // container does above, and the two spellings then agree.
+        const count = null == this.count ? undefined : this.count;
+        const n = members.length;
+        if (null != count) {
+            if (null != count.hi && !stateAdmits({ ...count, lo: undefined }, countVal(n))) {
+                return this.fail(ctx, peer);
+            }
+            if (0 < count.neqs.length && !stateAdmits({ ...count, lo: undefined, hi: undefined }, countVal(n))) {
+                return this.fail(ctx, peer);
+            }
+            // The provisional half, decided only when nothing more can
+            // arrive: a lower bound still short is a refusal at generation
+            // and a residue before it.
+            if (true === final && !stateAdmits(count, countVal(n))) {
+                return this.fail(ctx, peer);
+            }
         }
         if (this.uniq) {
             // Members compare by CANONICAL FORM, which reduces to scalar
@@ -717,7 +950,65 @@ class ConstraintVal extends FeatureVal_1.FeatureVal {
                 seen.add(key);
             }
         }
-        return peer;
+        // ... and the same test per PROJECTED key. A member that has no such
+        // key FAILS the constraint rather than being skipped: distinctness
+        // it cannot be shown to have is distinctness it does not have, and
+        // skipping would let one keyless record hide a duplicate.
+        for (const field of this.uniqBy) {
+            const seen = new Set();
+            for (const m of members) {
+                const at = true === m.isMap ?
+                    m.peg[field] : undefined;
+                if (null == at) {
+                    return this.fail(ctx, peer);
+                }
+                const key = at.canon;
+                if (seen.has(key)) {
+                    return this.fail(ctx, peer);
+                }
+                seen.add(key);
+            }
+        }
+        // WHAT IS LEFT IS PROVISIONAL, so the atom stays on the value. A
+        // lower bound already met is the one reading that cannot be undone,
+        // and an atom holding nothing else is spent: that is when it goes.
+        const spent = true === final || (0 === this.musts.length &&
+            !this.uniq && 0 === this.uniqBy.length &&
+            (null == count ||
+                (null == count.hi && 0 === count.neqs.length &&
+                    stateAdmits(count, countVal(n)))));
+        if (spent) {
+            return peer;
+        }
+        // DONE, unlike the unsettled case above. The container HAS settled;
+        // the atom is kept only because a LATER value could still add
+        // members, and a residue that reported itself unresolved would
+        // leave every enclosing value unresolved with it -- a `type()`
+        // waiting on its argument for ever, and use case 09's whole
+        // registry with it.
+        // The ATOM is done too, not just the conjunct. An earlier pass may
+        // have set `dc = 0` on the unsettled branch above, and a conjunct
+        // recomputes its own doneness from its terms on every later meet --
+        // so a stale 0 here would drag the residue, and every value holding
+        // it, back to unresolved for ever.
+        return this.hold(peer, ctx);
+    }
+    // The atom kept on a value whose reading is still provisional.
+    // DONE, unlike the unsettled container above: the value HAS settled;
+    // the atom is kept only because a LATER value could still add
+    // members, and a residue that reported itself unresolved would leave
+    // every enclosing value unresolved with it -- a `type()` waiting on
+    // its argument for ever, and use case 09's whole registry with it.
+    // The ATOM is done too, not just the conjunct. An earlier pass may
+    // have set `dc = 0` on the unsettled branch, and a conjunct
+    // recomputes its own doneness from its terms on every later meet --
+    // so a stale 0 here would drag the residue, and every value holding
+    // it, back to unresolved for ever.
+    hold(peer, ctx) {
+        this.dc = type_1.DONE;
+        const held = new ConjunctVal_1.ConjunctVal({ peg: [this, peer] }, ctx);
+        held.dc = type_1.DONE;
+        return held;
     }
     // Meet with a kind: `number` (or `string` on the string domain) is
     // already implied by an ORDER atom's argument; a numeric LEAF narrows
@@ -782,6 +1073,11 @@ class ConstraintVal extends FeatureVal_1.FeatureVal {
             null == peer.count ? this.count : meetCount(this.count, peer.count);
         // `unique()` is idempotent: two of them are one.
         merged.uniq = this.uniq || peer.uniq;
+        // `unique(a) & unique(b)` is BOTH, not the later one: each names a
+        // key on which the members must differ, and dropping either would
+        // silently weaken the constraint. Sorted and deduplicated, so the
+        // meet is commutative and `unique(a) & unique(a)` is one atom.
+        merged.uniqBy = [...new Set([...this.uniqBy, ...peer.uniqBy])].sort();
         // Band B checks accumulate in written order and are never merged,
         // deduplicated or reordered: each carries its own author message,
         // and two checks with the same shape may still say different things.
@@ -822,6 +1118,7 @@ class ConstraintVal extends FeatureVal_1.FeatureVal {
             res: [...this.res],
             count: this.count,
             uniq: this.uniq,
+            uniqBy: [...this.uniqBy],
             musts: [...this.musts],
             invalid: this.invalid,
         };
@@ -839,6 +1136,7 @@ class ConstraintVal extends FeatureVal_1.FeatureVal {
         out.res = [...this.res];
         out.count = this.count;
         out.uniq = this.uniq;
+        out.uniqBy = [...this.uniqBy];
         out.musts = [...this.musts];
         out.pending = this.pending;
         out.cjo = this.cjo;
@@ -903,10 +1201,11 @@ function dedupSorted(domain, neqs) {
 // Is this value, or anything inside it, a nil? A written argument that
 // holds one can never be satisfied, so the atom refuses it as an
 // argument rather than reporting a mystery failure against every peer.
+// Every caller passes a Val: `args[0]` comes from atomArgs, and the
+// walk below descends only into container pegs, which hold Vals. The
+// null/non-Val guard this function used to open with was therefore
+// unreachable, and the coverage gate said so.
 function holdsNil(v) {
-    if (null == v || true !== v.isVal) {
-        return false;
-    }
     if (true === v.isNil) {
         return true;
     }
@@ -923,6 +1222,29 @@ function holdsNil(v) {
     }
     return false;
 }
+// Whether a value, or anything inside it, is an effectful call — one
+// whose evaluation changes a node OTHER than the one being computed.
+// `move()` is the only builtin that does: it hides its resolution
+// target in place. Band B refuses one as an argument, because settling
+// it runs the effect against the live root before `must`'s trial clone
+// is taken, and a check that mutates cannot be report-only.
+function holdsMove(v) {
+    if (true === v.isFunc && 'move' === v.funcname?.()) {
+        return true;
+    }
+    const peg = v.peg;
+    if (Array.isArray(peg)) {
+        return peg.some((c) => holdsMove(c));
+    }
+    if (null != peg && 'object' === typeof peg) {
+        for (const k in peg) {
+            if (holdsMove(peg[k])) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
 // The written arguments of an atom, flattened.
 //
 // A multi-argument call arrives from the func-paren grammar as ONE
@@ -979,6 +1301,12 @@ function canonState(s) {
     if (s.uniq) {
         parts.push('unique()');
     }
+    // After the bare atom, and sorted: canon is a normal form, so two
+    // documents writing the same keys in different orders must render
+    // the same string.
+    for (const key of s.uniqBy) {
+        parts.push('unique(' + JSON.stringify(key) + ')');
+    }
     for (const m of s.musts) {
         parts.push('must(' + m.v.canon + ',' + m.msg.canon + ')');
     }
@@ -988,6 +1316,110 @@ function canonState(s) {
     }
     return parts.join('&');
 }
+// SUBSUMPTION over two residuals (G3, the query built on the table in
+// docs/reference-language.md "Subsumption"): does every value `s`
+// admits pass `g` too? Implemented here because the compare machinery
+// (cmpVal, sameScalar, the recursive count state) is this module's.
+//
+// Three-valued: true / false / 'undecided'. `must` on the GENERAL side
+// is undecided by construction (a Band B predicate is opaque — G3 maps
+// the table's "never" to the query's honest sub_evaluate_only); every
+// other approximation folds toward false, the safe direction.
+function constraintStateSubsumes(g, s) {
+    // A Band B predicate on the general side makes its admitted set
+    // unknowable; an extra `must` on the SPECIFIC side only narrows it
+    // and is ignored.
+    if (0 < g.musts.length) {
+        return 'undecided';
+    }
+    // Domains must agree where both constrain one; a sizing-only residual
+    // has no domain and passes this gate.
+    if (null != g.domain && g.domain !== s.domain) {
+        return false;
+    }
+    // A general leaf restriction requires the same leaf on the specific
+    // side (leaves are disjoint; an unrestricted specific admits other
+    // leaves the general refuses).
+    if (null != g.kind && g.kind !== s.kind) {
+        return false;
+    }
+    // Interval containment: the general's endpoints at or beyond the
+    // specific's, and where they coincide the general's may not be the
+    // open one.
+    const d = g.domain ?? s.domain;
+    if (null != g.lo) {
+        if (null == s.lo || null == d) {
+            return false;
+        }
+        const c = cmpVal(d, g.lo.v, s.lo.v);
+        if (0 < c || (0 === c && g.lo.open && !s.lo.open)) {
+            return false;
+        }
+    }
+    if (null != g.hi) {
+        if (null == s.hi || null == d) {
+            return false;
+        }
+        const c = cmpVal(d, g.hi.v, s.hi.v);
+        if (c < 0 || (0 === c && g.hi.open && !s.hi.open)) {
+            return false;
+        }
+    }
+    // Excluding FEWER values is more general: every general exclusion
+    // must be excluded by the specific too.
+    for (const n of g.neqs) {
+        if (!s.neqs.some((m) => sameScalar(n, m))) {
+            return false;
+        }
+    }
+    // Patterns compare as TEXT sets (the sanctioned approximation:
+    // deciding regex containment is what this algebra refuses to do).
+    for (const r of g.res) {
+        if (!s.res.some((q) => q.src === r.src)) {
+            return false;
+        }
+    }
+    // `unique()` subsumes only itself on that axis: a general uniqueness
+    // demand admits no container the unconstrained specific also admits.
+    // ... and a general `unique(k)` needs the same key on the specific
+    // side: distinctness on `port` says nothing about distinctness on
+    // `name`.
+    if (g.uniqBy.some((k) => !s.uniqBy.includes(k))) {
+        return false;
+    }
+    if (g.uniq && !s.uniq) {
+        return false;
+    }
+    // The count atom reuses this same table over the integer domain.
+    if (null != g.count) {
+        if (null == s.count) {
+            return false;
+        }
+        return constraintStateSubsumes(g.count, s.count);
+    }
+    return true;
+}
+// The query surface for ts/src/subsume.ts: residual-vs-residual, and
+// residual-vs-scalar membership (with `must` and `unique` making the
+// scalar case undecided/false exactly as the meet would).
+function constraintSubsumesConstraint(g, s) {
+    return constraintStateSubsumes(g, s);
+}
+function constraintAdmitsScalar(g, scalar) {
+    if (0 < g.musts.length) {
+        return 'undecided';
+    }
+    if (g.uniq || 0 < g.uniqBy.length) {
+        return false;
+    }
+    // A count residual admits by LENGTH, which is the meet's business;
+    // the query answers false (the safe direction) rather than
+    // reimplementing the sizing walk here.
+    if (null != g.count) {
+        return false;
+    }
+    return stateAdmits(g, scalar);
+}
 // Does this residual's ORDER and MEMBERSHIP part admit the scalar? The
 // sizing atoms are deliberately not consulted: `admit` applies them to
 // the peer's length, and the count check applies this same function to
@@ -1096,7 +1528,8 @@ function stateEmpty(s) {
     // members, so `integer & length(3)` and `min(2) & unique()` admit
     // nothing. Uniqueness over the string domain is empty for the same
     // reason -- a string's members are not values the algebra compares.
-    if ('number' === d && (null != s.count || s.uniq)) {
+    if ('number' === d && (null != s.count || s.uniq ||
+        0 < s.uniqBy.length)) {
         return true;
     }
     if ('string' === d && s.uniq) {
@@ -1121,7 +1554,9 @@ function countBase() {
         neqs: [],
         res: [],
         musts: [],
+        // A COUNT is a number, and a number has no members to be distinct.
         uniq: false,
+        uniqBy: [],
     };
 }
 // A count as a Val, so the count residual can be applied by exactly the
@@ -1138,13 +1573,16 @@ function countVal(n) {
 function meetCount(a, b) {
     return {
         domain: 'number',
-        kind: a.kind ?? b.kind,
+        // `a` is always a countBase()-seeded residual, so its kind is
+        // always Integer — there is no kindless side to fall back from.
+        kind: a.kind,
         lo: tighter('number', a.lo, b.lo, true),
         hi: tighter('number', a.hi, b.hi, false),
         neqs: dedupSorted('number', [...a.neqs, ...b.neqs]),
         res: [],
         musts: [],
         uniq: false,
+        uniqBy: [],
         clash: true === a.clash || true === b.clash ||
             (null != a.kind && null != b.kind && a.kind !== b.kind),
     };
@@ -1167,14 +1605,15 @@ function countArgState(arg) {
             domain: 'number',
             lo: { v: arg, open: false },
             hi: { v: arg, open: false },
-            neqs: [], res: [], musts: [], uniq: false,
+            neqs: [], res: [], musts: [], uniq: false, uniqBy: [],
         };
     }
     if (true === arg?.isConstraint) {
         const c = arg;
         // A pattern, a sizing atom or a string bound inside a count is not
         // a count constraint at all, and neither is a broken one.
-        if (null != c.invalid || 0 < c.res.length || c.uniq || null != c.count ||
+        if (null != c.invalid || 0 < c.res.length || c.uniq ||
+            0 < c.uniqBy.length || null != c.count ||
             'number' !== c.domain) {
             return undefined;
         }
@@ -1184,17 +1623,23 @@ function countArgState(arg) {
             lo: c.lo,
             hi: c.hi,
             neqs: [...c.neqs],
-            res: [], musts: [], uniq: false,
+            res: [], musts: [], uniq: false, uniqBy: [],
         };
     }
     if (true === arg?.isScalarKind) {
         const marker = arg.peg;
         if (Number === marker) {
-            return { domain: 'number', neqs: [], res: [], musts: [], uniq: false };
+            return {
+                domain: 'number', neqs: [], res: [], musts: [],
+                uniq: false, uniqBy: [],
+            };
         }
         if (ScalarKindVal_1.Integer === marker || ScalarKindVal_1.Float === marker ||
             ScalarKindVal_1.BigInteger === marker || ScalarKindVal_1.BigDecimal === marker) {
-            return { domain: 'number', kind: marker, neqs: [], res: [], musts: [], uniq: false };
+            return {
+                domain: 'number', kind: marker, neqs: [], res: [], musts: [],
+                uniq: false, uniqBy: [],
+            };
         }
         return undefined;
     }
@@ -1221,7 +1666,12 @@ function genable(child) {
     return true === child.isScalar || true === child.isMap ||
         true === child.isList || true === child.isPref ||
         true === child.isRef || true === child.isDisjunct ||
-        true === child.isNil;
+        true === child.isNil ||
+        // A settled sizing residue generates through ConjunctVal.gen, so it
+        // is a member like any other -- and a `length` that did not count
+        // its sibling's `unique` would be the early-fold defect again, one
+        // level up.
+        undefined !== (0, BagVal_1.sizingResidue)(child);
 }
 // The children a bag would EMIT, mirroring the selection in
 // `BagVal.gen` — type/hide marks skipped, non-generable residue and
@@ -1343,6 +1793,6 @@ class UniqueConstraintVal extends ConstraintVal {
     constructor(spec, ctx) {
         super({ ...spec, atom: 'unique' }, ctx);
     }
-} /* node:coverage ignore next 19 */
+} /* node:coverage ignore next 23 */
 exports.UniqueConstraintVal = UniqueConstraintVal;
 //# sourceMappingURL=ConstraintVal.js.map