aontu 0.52.1 → 0.54.0

package/src/val/ConstraintVal.ts

@@ -57,6 +57,7 @@ import { empty } from './Val'
 import { cmpCodePoint } from '../keyorder'
 
 import { ConjunctVal } from './ConjunctVal'
+import { sizingResidue } from './BagVal'
 
 import { top } from './top'
 
@@ -115,6 +116,8 @@ type ConstraintState = {
                            // over the integer domain -- the count atom reuses
                            // this same algebra recursively
   uniq: boolean   // members must be pairwise distinct (unique())
+  uniqBy: string[]  // ... and distinct ON EACH OF THESE KEYS
+                    // (unique(k)), sorted and deduplicated
   musts: MustAtom[]  // Band B checks, kept in written order, never simplified
   clash?: boolean // a kind disagreement inside a length() argument, recorded
                   // rather than raised: the argument's own meet has no
@@ -180,6 +183,18 @@ type ConstraintState = {
 // 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'
@@ -196,6 +211,67 @@ const RE_ESCAPE_PUNCT = '\\.+*?()[]{}|^$/'
 // 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: string, at: number): [string, number] {
+  const bad = (what: string): [string, number] => [
+    'a ' + what + ', which the two engines do not read the same way', -1]
+
+  let i = at + 1
+  let digits = ''
+  const bounds: number[] = []
+  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: string | undefined): boolean {
   return null != c && (
     ('0' <= c && c <= '9') || ('a' <= c && c <= 'f') || ('A' <= c && c <= 'F'))
@@ -302,8 +378,16 @@ function normaliseRe(src: string): [string, string] {
     }
   }
 
+  // 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)
@@ -311,6 +395,17 @@ function normaliseRe(src: string): [string, string] {
         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
     }
@@ -387,12 +482,43 @@ function normaliseRe(src: string): [string, string] {
     }
 
     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) {
@@ -418,6 +544,16 @@ function stringLeaf(v: any): boolean {
   return true === v?.isScalar && 'string' === typeof v.peg && v.isString
 }
 
+// The VALUE-admission widening of stringLeaf: a path value is a string
+// with more structure (path <: string, ADR-016), so the string-domain
+// constraints admit one -- `refer() & re("auth$")` must still check a
+// link whose value is now a path. The ARGUMENT sites keep the strict
+// test: a pattern, a bound or an exclusion is spelled with a plain
+// string, never a path.
+function stringishLeaf(v: any): boolean {
+  return stringLeaf(v) || (true === v?.isScalar && true === v.isPath)
+}
+
 
 // Scalar identity: leaf AND value, the lattice's own rule (1 and 1.0
 // are different scalars). Exact numeric comparison decides the value
@@ -426,6 +562,12 @@ function sameScalar(a: any, b: any): boolean {
   if (numericLeaf(a) && numericLeaf(b)) {
     return towerRank(a) === towerRank(b) && 0 === cmpNumeric(a, b)
   }
+  if (true === a?.isPath || true === b?.isPath) {
+    // Path identity is kind AND spelling (ADR-016): `neq(path($.x))`
+    // excludes exactly that address, and never a plain string that
+    // happens to spell it.
+    return true === a?.isPath && true === b?.isPath && a.peg === b.peg
+  }
   if (stringLeaf(a) && stringLeaf(b)) {
     return a.peg === b.peg
   }
@@ -480,6 +622,7 @@ class ConstraintVal extends FeatureVal {
   res: ReAtom[] = []
   count?: ConstraintState
   uniq = false
+  uniqBy: string[] = []
   musts: MustAtom[] = []
   // An atom whose arguments have not settled yet (G1 phase 4). Held
   // until unify has a ctx to resolve them through; never present on a
@@ -506,6 +649,7 @@ class ConstraintVal extends 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
     }
@@ -517,7 +661,14 @@ class ConstraintVal extends 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: any) => 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: any) => holdsMove(a))) {
+        this.invalid = 'invalid-arg'
+      }
+      else if (args.some((a: any) => true !== a?.done)) {
         this.pending = { atom: spec.atom, args }
       }
       else {
@@ -525,7 +676,8 @@ class ConstraintVal extends FeatureVal {
       }
     }
 
-    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
     }
@@ -546,19 +698,32 @@ class ConstraintVal extends FeatureVal {
   // SETTLED — the constructor routes an unsettled one to `pending` —
   // so a shape this cannot use is a genuine `invalid-arg`, not a
   // not-yet.
-  private fromAtom(atom: string, args: any[]) {
-    // Mark the residual invalid and report so (a plain boolean, so no
-    // void value is consumed by the callers' `return` statements).
-    const bad = (why: string): boolean => {
+  private fromAtom(atom: string, args: any[]): void {
+    // 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: string): void => {
       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
     }
 
@@ -583,6 +748,9 @@ class ConstraintVal extends 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
     }
@@ -593,7 +761,7 @@ class ConstraintVal extends FeatureVal {
       }
       let domain: 'number' | 'string' | undefined = undefined
       for (const a of args) {
-        const d = numericLeaf(a) ? 'number' : stringLeaf(a) ? 'string' : undefined
+        const d = numericLeaf(a) ? 'number' : stringishLeaf(a) ? 'string' : undefined
         if (null == d || (null != domain && d !== domain)) {
           return bad('invalid-arg')
         }
@@ -676,7 +844,7 @@ class ConstraintVal extends FeatureVal {
       return
     }
 
-    const domain = numericLeaf(a) ? 'number' : stringLeaf(a) ? 'string' : undefined
+    const domain = numericLeaf(a) ? 'number' : stringishLeaf(a) ? 'string' : undefined
     if (null == domain) {
       return bad('invalid-arg')
     }
@@ -700,7 +868,20 @@ class ConstraintVal extends FeatureVal {
     // residual is stable and the ladder is total.
     let out: Val
 
-    if (null != this.pending) {
+    // A rel residual or a graph atom HOLDS constraints for the value
+    // they stand for (RELATIONS P1/P2): hand the drive over before
+    // any settling, exactly as a container does, so `rel(t) & re(x)`
+    // reads the same in either order. Reached through the INCLUDE
+    // flow (a loaded schema's conjunct re-drives with the constraint
+    // on the left) -- inline documents route rel/atom peers through
+    // unite's b-drives first, which is why use-cases/12-relations
+    // refused without this arm while every inline row stayed green;
+    // pinned by constraint-hands-drive-to-rel-and-atom.
+    if (true === (peer as any)?.isRel
+      || true === (peer as any)?.isGraphAtom) {
+      out = (peer as any).unify(this, ctx)
+    }
+    else if (null != this.pending) {
       out = this.settle(peer, ctx)
     }
     else if (null != this.invalid) {
@@ -801,9 +982,9 @@ class ConstraintVal extends FeatureVal {
     if (null == peer || (peer as any).isTop) {
       return again
     }
-    if ((peer as any).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({ peg: [again, peer] }, ctx)
   }
 
@@ -811,8 +992,9 @@ class ConstraintVal extends FeatureVal {
   // Membership: the peer scalar passes every part of the residual, or
   // the whole meet is a located conflict.
   private admit(peer: any, ctx: AontuContext): Val {
-    // 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)) {
@@ -822,14 +1004,17 @@ class ConstraintVal extends FeatureVal {
       // Only a string among the scalars has a length, and it is counted
       // in CODE POINTS -- not UTF-16 units (this host's native count)
       // and not bytes (Go's). Iterating a string yields code points.
-      if (!stringLeaf(peer)) {
+      if (!stringishLeaf(peer)) {
         return this.fail(ctx, peer)
       }
       if (!stateAdmits(this.count, countVal([...peer.peg].length))) {
         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
     }
@@ -845,10 +1030,30 @@ class ConstraintVal extends 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.
-  private checkMusts(peer: any, ctx: AontuContext): Val | undefined {
+  // `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).
+  private checkMusts(
+    peer: any, ctx: AontuContext, final?: boolean): Val | undefined {
     for (const m of this.musts) {
       const trial = ctx.clone({ err: [], collect: true })
-      const got = unite(trial, m.v.clone(trial), peer.clone(trial), 'must')
+      let got: any = 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 = sizingResidue(got)
+      if (undefined !== residue) {
+        if (true !== final) {
+          continue
+        }
+        got = residue.con.settleContainer(residue.bag, trial)
+      }
       if (true === (got as any)?.isNil || 0 < trial.err.length) {
         return makeNilErr(ctx, 'must', this, peer, undefined, {
           message: m.msg.peg,
@@ -861,6 +1066,16 @@ class ConstraintVal extends FeatureVal {
   }
 
 
+  // 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: any, ctx: AontuContext): Val {
+    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.
@@ -872,7 +1087,8 @@ class ConstraintVal extends 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.
-  private admitContainer(peer: any, ctx: AontuContext): Val {
+  private admitContainer(
+    peer: any, ctx: AontuContext, final?: boolean): Val {
     // A scalar-domain residual has no reading over a container.
     if (null != this.domain) {
       return this.fail(ctx, peer)
@@ -885,24 +1101,81 @@ class ConstraintVal extends FeatureVal {
       return new 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) {
@@ -921,7 +1194,68 @@ class ConstraintVal extends FeatureVal {
       }
     }
 
-    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<string>()
+      for (const m of members) {
+        const at: any = true === (m as any).isMap ?
+          (m as any).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.
+  private hold(peer: any, ctx: AontuContext): Val {
+    this.dc = DONE
+    const held: any = new ConjunctVal({ peg: [this, peer] }, ctx)
+    held.dc = DONE
+    return held
   }
 
 
@@ -994,6 +1328,11 @@ class ConstraintVal extends 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.
@@ -1042,6 +1381,7 @@ class ConstraintVal extends FeatureVal {
       res: [...this.res],
       count: this.count,
       uniq: this.uniq,
+      uniqBy: [...this.uniqBy],
       musts: [...this.musts],
       invalid: this.invalid,
     }
@@ -1061,6 +1401,7 @@ class ConstraintVal extends 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
@@ -1137,10 +1478,11 @@ function dedupSorted(domain: 'number' | 'string', neqs: any[]): any[] {
 // 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: any): boolean {
-  if (null == v || true !== v.isVal) {
-    return false
-  }
   if (true === v.isNil) {
     return true
   }
@@ -1159,6 +1501,31 @@ function holdsNil(v: any): boolean {
 }
 
 
+// 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: any): boolean {
+  if (true === v.isFunc && 'move' === v.funcname?.()) {
+    return true
+  }
+  const peg = v.peg
+  if (Array.isArray(peg)) {
+    return peg.some((c: any) => 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
@@ -1217,6 +1584,12 @@ function canonState(s: ConstraintState): string {
   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 + ')')
   }
@@ -1228,13 +1601,145 @@ function canonState(s: ConstraintState): string {
 }
 
 
+// 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: {
+    domain?: 'number' | 'string', kind?: any, lo?: Bound, hi?: Bound,
+    neqs: any[], res: ReAtom[], count?: ConstraintState, uniq: boolean,
+    uniqBy: string[],
+    musts: MustAtom[],
+  },
+  s: {
+    domain?: 'number' | 'string', kind?: any, lo?: Bound, hi?: Bound,
+    neqs: any[], res: ReAtom[], count?: ConstraintState, uniq: boolean,
+    uniqBy: string[],
+    musts: MustAtom[],
+  },
+): boolean | 'undecided' {
+  // 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: any) => 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: ReAtom) => 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: string) => !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: ConstraintVal, s: ConstraintVal): boolean | 'undecided' {
+  return constraintStateSubsumes(g as any, s as any)
+}
+
+function constraintAdmitsScalar(
+  g: ConstraintVal, scalar: any): boolean | 'undecided' {
+  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 as any).count) {
+    return false
+  }
+  return stateAdmits(g as any, 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
 // the count.
 function stateAdmits(s: ConstraintState, peer: any): boolean {
   const domainOf = numericLeaf(peer) ? 'number' :
-    stringLeaf(peer) ? 'string' : undefined
+    stringishLeaf(peer) ? 'string' : undefined
 
   if (null == s.domain) {
     // A sizing residual has no domain, and admits any scalar the sizing
@@ -1345,7 +1850,8 @@ function stateEmpty(s: ConstraintState): boolean {
   // 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) {
@@ -1374,7 +1880,9 @@ function countBase(): ConstraintState {
     neqs: [],
     res: [],
     musts: [],
+    // A COUNT is a number, and a number has no members to be distinct.
     uniq: false,
+    uniqBy: [],
   }
 }
 
@@ -1395,13 +1903,16 @@ function countVal(n: number): any {
 function meetCount(a: ConstraintState, b: ConstraintState): ConstraintState {
   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),
   }
@@ -1426,7 +1937,7 @@ function countArgState(arg: any): ConstraintState | undefined {
       domain: 'number',
       lo: { v: arg, open: false },
       hi: { v: arg, open: false },
-      neqs: [], res: [], musts: [], uniq: false,
+      neqs: [], res: [], musts: [], uniq: false, uniqBy: [],
     }
   }
 
@@ -1434,7 +1945,8 @@ function countArgState(arg: any): ConstraintState | undefined {
     const c = arg as ConstraintVal
     // 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
     }
@@ -1444,18 +1956,24 @@ function countArgState(arg: any): ConstraintState | undefined {
       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 (Integer === marker || Float === marker ||
       BigInteger === marker || 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
   }
@@ -1487,7 +2005,12 @@ function genable(child: any): boolean {
   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 !== sizingResidue(child)
 }
 
 
@@ -1624,7 +2147,7 @@ class UniqueConstraintVal extends ConstraintVal {
   constructor(spec: ValSpec, ctx?: AontuContext) {
     super({ ...spec, atom: 'unique' }, ctx)
   }
-} /* node:coverage ignore next 19 */
+} /* node:coverage ignore next 23 */
 
 
 export {
@@ -1632,6 +2155,11 @@ export {
   // normalisers must produce byte-identical output, and that can only be
   // checked by calling them.
   normaliseRe,
+  // Exported for the subsumption query (G3, ts/src/subsume.ts): the
+  // residual-vs-residual and residual-vs-scalar rules live here beside
+  // the compare machinery they reuse.
+  constraintSubsumesConstraint,
+  constraintAdmitsScalar,
   ConstraintVal,
   MinConstraintVal,
   MaxConstraintVal,