aontu 0.62.0 → 0.63.0

package/src/val/ConstraintVal.ts

@@ -1,36 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-/*
- * The constraint algebra's residual value (G1 phase 1: bounds and neq;
- * docs/reference-language.md, "The constraint algebra"). A
- * ConstraintVal is the normal form of any meet of Band A atoms over
- * one domain: an interval (endpoints with open/closed flags), an
- * exclusion set (from neq), and an optional numeric-leaf kind
- * narrowing (from meeting `integer` etc.). Its rules, decided in
- * phase 0 and mirrored by go/constraint.go:
- *
- *  - Order is a property of the number line: a numeric bound admits
- *    ANY numeric leaf at an admissible position, compared exactly
- *    (numcmp.ts), and never narrows the peer's leaf by itself.
- *  - Endpoints keep their written leaf (canon renders the stored
- *    scalar); two endpoints at the SAME point keep the tower-lowest
- *    leaf. No endpoint rewriting, ever (lazy endpoints).
- *  - neq excludes by scalar identity — leaf AND value.
- *  - Emptiness is decided eagerly where it is exact: empty interval,
- *    integral gap under an integer/biginteger narrowing, point
- *    deletion under a narrowed leaf, domain mixing. Representability
- *    holes of the int64-window integer leaf are deliberately NOT
- *    modelled (sound — no false conflicts; incomplete — those
- *    contradictions surface against data), matching the algebra's
- *    regex-approximation philosophy.
- *  - Canonical atom order: kind, lower bound, upper bound, neq
- *    (arguments sorted); `parse(canon(v)) == v` holds because the
- *    reparse is a conjunct of atoms that normalises back to the
- *    identical residual.
- *
- * A constraint violation raises the registered `constraint` code
- * (class conflict), with the admissible set in NilVal.details.
- */
 
 import type {
   Val,
@@ -92,7 +61,7 @@ type Bound = {
 }
 
 type ReAtom = {
-  v: any          // the stored pattern StringVal (canon renders the literal)
+  v: any
   src: string     // the pattern text AS WRITTEN — canon and dedup use this,
                   // never the normalised form, because canon round-trips
                   // source and G6's hash will be taken over canon
@@ -115,7 +84,7 @@ type ConstraintState = {
   count?: ConstraintState  // the COUNT residual (length()), itself a residual
                            // over the integer domain -- the count atom reuses
                            // this same algebra recursively
-  uniq: boolean   // members must be pairwise distinct (unique())
+  uniq: boolean
   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
@@ -126,73 +95,6 @@ type ConstraintState = {
 }
 
 
-// THE PATTERN SUBSET, AND HOW IT IS ENFORCED (G1 phase 2; ADR-003).
-//
-// `re(p)` must mean the same thing in both engines and cost about the
-// same, and the two host engines guarantee neither: TypeScript compiles
-// with JavaScript's backtracking RegExp, Go with RE2 — a different
-// language in a different complexity class, over a different alphabet.
-//
-// The enforcement is NORMALISATION, not refusal (ADR-003). Every
-// construct whose expansion is engine-defined is rewritten here, by
-// this function, into an explicit form that cannot be read two ways;
-// only the rewritten pattern reaches a host engine. The alternative —
-// refusing everything that might differ — was tried first and leaked
-// three times, because its correctness depended on this comment knowing
-// every difference between two large engines.
-//
-// Aontu therefore DEFINES the abbreviations rather than inheriting
-// either host's. The definitions are deliberately the small ASCII ones,
-// because a config value containing U+00A0 is a mistake to catch, not a
-// space to accept silently:
-//
-//     \d  [0-9]                 \D  [^0-9]
-//     \w  [0-9A-Za-z_]          \W  [^0-9A-Za-z_]
-//     \s  [ \t\n\r\f\v]         \S  [^ \t\n\r\f\v]
-//     .   [^\n]
-//     \A  ^                     \z  $
-//
-// Neither host agreed with all of these before rewriting: JavaScript's
-// \s also matches U+00A0 and other Unicode spaces, RE2's omits \v, and
-// the two `.` sets differ by \r and the Unicode line separators. After
-// rewriting, both engines see one explicit class and cannot disagree.
-//
-// What is still REFUSED, and why refusal is right for these:
-//
-//  1. Constructs one engine simply lacks — backreferences and
-//     lookaround (not in RE2, and not expressible as regular
-//     expressions at all), POSIX classes, `\p{...}`, `\x{...}`, `\u`.
-//     There is nothing to normalise them TO.
-//  2. `(?` other than `(?:` — named groups are spelled differently
-//     (`(?P<n>` in RE2, `(?<n>` in JavaScript) and inline flags change
-//     the meaning of everything after them.
-//  3. A quantifier applied to a group containing a quantifier or an
-//     alternation. This one is about TIME, not meaning: `(a+)+$`
-//     against twenty-nine characters takes 45 SECONDS in JavaScript
-//     and 0.065s under RE2, and a regex match is counted by no
-//     evaluator budget, so an untrusted schema could otherwise stall
-//     the TypeScript evaluator indefinitely (docs/trust.md clause 2).
-//     Normalisation cannot fix a complexity difference; only owning the
-//     matcher could, which ADR-003 records as the future option.
-//
-// The alphabet is fixed separately, by compiling with the `u` flag:
-// JavaScript otherwise matches UTF-16 code units where RE2 matches code
-// points, so `^.$` accepted U+1D11E in Go and refused it in TypeScript.
-//
-// 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
@@ -201,28 +103,12 @@ const RE_CLASS_DIGIT = '0-9'
 const RE_CLASS_WORD = '0-9A-Za-z_'
 const RE_CLASS_SPACE = ' \\t\\n\\r\\f\\v'
 
-// Metacharacters that may be escaped to mean themselves, in both
-// engines. `-` is handled separately: it is legal escaped only INSIDE a
-// character class, because RE2 accepts `a\-b` and JavaScript's unicode
-// mode makes it a syntax error.
 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: string, at: number): [string, number] {
   const bad = (what: string): [string, number] => [
     'a ' + what + ', which the two engines do not read the same way', -1]
@@ -367,10 +253,6 @@ function normaliseRe(src: string): [string, string] {
   let inClass = false
   const out: string[] = []
 
-  // One frame per open group, recording whether it contains a quantifier
-  // or an alternation. A group carrying either may not itself be
-  // quantified; containment is transitive, so a frame hands its flags up
-  // to its parent when it closes.
   const groups: { q: boolean, alt: boolean }[] = []
   const mark = (k: 'q' | 'alt') => {
     if (0 < groups.length) {
@@ -395,14 +277,6 @@ 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
       }
@@ -410,9 +284,6 @@ function normaliseRe(src: string): [string, string] {
       continue
     }
 
-    // A POSIX class opener, anywhere: the form lives inside an ordinary
-    // class (`[[:alpha:]]`), and refusing it everywhere is one rule
-    // rather than two.
     if ('[' === c && ':' === src[i + 1]) {
       return ['', 'a POSIX class ([:...:]), which JavaScript does not have']
     }
@@ -482,12 +353,6 @@ 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']
@@ -504,10 +369,6 @@ function normaliseRe(src: string): [string, string] {
       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 ' +
@@ -544,20 +405,11 @@ 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
-// half for numeric leaves.
 function sameScalar(a: any, b: any): boolean {
   if (numericLeaf(a) && numericLeaf(b)) {
     return towerRank(a) === towerRank(b) && 0 === cmpNumeric(a, b)
@@ -589,20 +441,6 @@ function leafMarker(v: any): any {
 }
 
 
-// Conjunct sort order for an atom that must see the WHOLE value.
-// Every other value sorts below the container default (99999), so such
-// an atom is the LAST term to fold: `a:length(2) a:{x:1} a:{y:2}` must
-// count the MERGED map, and a constraint that folded at 50000 would
-// count `{x:1}` alone and refuse the layering that is the whole point
-// of the language.
-//
-// The order atoms keep the low slot: `min(2) & 1 & 2` may decide as
-// soon as it sees a scalar, because meeting more scalars can only
-// narrow. Meeting more containers GROWS the member set, which is why
-// the two orders differ.
-//
-// Three atoms are late: `length` and `unique` (they count members), and
-// `must` (an evaluate-only check against the finished value).
 const LATE_CJO = 150000
 
 function lateAtom(atom: string): boolean {
@@ -655,16 +493,6 @@ class ConstraintVal extends FeatureVal {
     }
     else if (spec.atom) {
       const args = atomArgs(spec.atom, (spec.peg as any[]) ?? [])
-      // An argument that is not yet concrete — a reference, an
-      // arithmetic expression, a conjunct of atoms — makes the whole
-      // atom PENDING rather than invalid (G1 phase 4). It is resolved
-      // 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`.
-      // 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'
       }
@@ -694,27 +522,11 @@ class ConstraintVal extends FeatureVal {
   }
 
 
-  // Normalise one atom call into state. Every argument here is already
-  // 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[]): 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
     }
 
-    // `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) {
       if (0 === args.length) {
         this.uniq = true
@@ -727,12 +539,6 @@ class ConstraintVal extends FeatureVal {
       return
     }
 
-    // `must(c, msg)` is Band B: an evaluate-only check against the
-    // finished value, carrying the author's own message. It is KEPT,
-    // never simplified and never consulted for emptiness or
-    // subsumption — Band B is opaque by construction, which is exactly
-    // what makes it the honest channel for a rule the algebra cannot
-    // reason about (docs/reference-language.md, "Band B: `must`").
     if ('must' === atom) {
       if (2 !== args.length) {
         return bad('arg')
@@ -740,11 +546,6 @@ class ConstraintVal extends FeatureVal {
       if (!stringLeaf(args[1])) {
         return bad('invalid-arg')
       }
-      // A check carrying a nil can never be satisfied, so it is refused
-      // as an ARGUMENT rather than left to fail against every value with
-      // the author's message attached -- which would blame the data for
-      // a mistake in the check. `must([1-x],m)` is the reachable case: a
-      // degenerate expression leaves a nil inside the written list.
       if (holdsNil(args[0])) {
         return bad('invalid-arg')
       }
@@ -785,8 +586,6 @@ class ConstraintVal extends FeatureVal {
         return bad('invalid-arg')
       }
       const src = a.peg as string
-      // Normalise BEFORE compiling: the host engines only ever see a
-      // pattern that cannot be read two ways (ADR-003).
       const [norm, why] = normaliseRe(src)
       if ('' !== why) {
         this.invalidWhy = why
@@ -794,23 +593,9 @@ class ConstraintVal extends FeatureVal {
       }
       let re: RegExp
       try {
-        // The `u` flag is REQUIRED for parity, not an optimisation.
-        // Without it JavaScript matches UTF-16 code units while RE2
-        // matches code points, so `re("^.$")` accepted U+1D11E in Go
-        // and refused it in TypeScript (and `^..$` did the reverse).
-        // With it, `.` and every quantifier count code points in both.
-        // It also makes JavaScript refuse the identity escapes this
-        // scanner rejects by hand, which is defence in depth rather
-        // than a substitute: RE2 accepts some of them, so the scanner
-        // is what keeps the two ports agreeing.
         re = new RegExp(norm, 'u')
       }
       catch (e: any) {
-        // The host engine refuses what the subset scanner passed — a
-        // malformed quantifier, an unbalanced group. Same refusal under
-        // the same code: the author gets one rule, not two. The message
-        // is the host's, so it is NOT pinned by a shared row; the code
-        // and the located frame are.
         this.invalidWhy = 'not a valid pattern'
         return bad('constraint_pattern')
       }
@@ -819,16 +604,6 @@ class ConstraintVal extends FeatureVal {
       return
     }
 
-    // `length` is the other non-ORDER atom: its argument constrains the
-    // COUNT, not the value, so it is itself a residual over the integer
-    // domain (docs/reference-language.md, "`length` semantics"). It is
-    // resolved HERE, at construction, by walking the written argument
-    // rather than by unifying it: the func-paren handler builds atoms
-    // without an AontuContext, so there is nothing to fold a nested
-    // conjunct through. Walking is enough because a length argument is by
-    // definition a meet of concrete Band A atoms; anything else (a
-    // reference, an expression) is refused rather than deferred, the
-    // same discipline min/max apply to their own arguments.
     if ('length' === atom) {
       const arg = countArgState(a)
       if (null == arg) {
@@ -868,15 +643,6 @@ class ConstraintVal extends FeatureVal {
     // residual is stable and the ladder is total.
     let out: Val
 
-    // 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)
@@ -908,15 +674,6 @@ class ConstraintVal extends FeatureVal {
     }
     /* node:coverage ignore next 12 */
     else {
-      // Every other shape: no order, no membership, nothing to count —
-      // a conflict of the constraint family. The ladder above is total
-      // in practice: every remaining Val kind either sorts BELOW a
-      // constraint in a conjunct (conjunct, disjunct, pref, ref) and so
-      // drives the meet from its own side, or resolves to a
-      // scalar/container before a constraint sees it (func, op, var,
-      // expect). The arm is kept because "in practice" depends on the
-      // cjo table, and a future value class would land here rather than
-      // falling out of unify with no result.
       out = this.fail(ctx, peer)
     }
 
@@ -926,17 +683,6 @@ class ConstraintVal extends FeatureVal {
   }
 
 
-  // Resolve a pending atom's arguments and, once they have all settled,
-  // become the residual they describe (G1 phase 4).
-  //
-  // This is the residuation discipline FuncBaseVal already follows for
-  // its own operands: push each unsettled argument one step by unifying
-  // it with `top`, and if any is still moving, mark not-done and defer
-  // — either as this same pending atom (against a `top` peer) or
-  // wrapped with the peer in a conjunct the next pass will re-enter.
-  // Nothing is decided from a half-resolved argument, which is what
-  // keeps `min($.lo)` from reporting a conflict against a bound that
-  // has not arrived yet.
   private settle(peer: Val, ctx: AontuContext): Val {
     const TOP = top()
     const pend = this.pending as { atom: string, args: any[] }
@@ -946,9 +692,6 @@ class ConstraintVal extends FeatureVal {
     for (const arg of pend.args) {
       let next = arg
       if (true !== arg?.done) {
-        // Charged to the depth budget: this recurses without going
-        // through `unite`, so the counter would otherwise stay flat
-        // while the stack grows (the rule FuncBaseVal follows).
         next = withDepth(ctx, arg, TOP, () => arg.unify(TOP, ctx))
       }
       settled = settled && true === next?.done
@@ -1001,9 +744,6 @@ class ConstraintVal extends FeatureVal {
       return this.fail(ctx, peer)
     }
     if (null != this.count) {
-      // 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 (!stringishLeaf(peer)) {
         return this.fail(ctx, peer)
       }
@@ -1022,31 +762,11 @@ class ConstraintVal extends FeatureVal {
   }
 
 
-  // Band B, applied to a finished value. Each check is a plain
-  // unification against a CLONE of the peer: `must` reports, it never
-  // contributes: whatever the check would have added to the value is
-  // discarded, and `peer` is returned untouched by the callers.
-  //
-  // 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.
-  // `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 })
       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) {
@@ -1066,27 +786,11 @@ 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.
-  //
-  // The members that count are the members that GENERATE
-  // (docs/reference-language.md, "`length` semantics"), and rather than
-  // mirror generation's filter — type/hide marks, optional keys that
-  // drop, empty optional values — this asks generation itself, in an
-  // 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, final?: boolean): Val {
     // A scalar-domain residual has no reading over a container.
@@ -1106,13 +810,6 @@ class ConstraintVal extends FeatureVal {
       return bad
     }
 
-    // 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
@@ -1122,43 +819,12 @@ class ConstraintVal extends FeatureVal {
 
     const members = emittedMembers(peer, ctx)
     if (null == members) {
-      // 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) {
@@ -1179,11 +845,6 @@ class ConstraintVal extends FeatureVal {
     }
 
     if (this.uniq) {
-      // Members compare by CANONICAL FORM, which reduces to scalar
-      // identity for scalars (so [1, 1.0] is distinct) and gives
-      // structural equality for container members without a second
-      // rule. A generated value could not express the first: `1` and
-      // `1.0` generate the same JSON number.
       const seen = new Set<string>()
       for (const m of members) {
         const key = m.canon
@@ -1194,10 +855,6 @@ class ConstraintVal extends FeatureVal {
       }
     }
 
-    // ... 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) {
@@ -1225,32 +882,10 @@ class ConstraintVal extends FeatureVal {
     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)
@@ -1259,16 +894,6 @@ class ConstraintVal extends FeatureVal {
   }
 
 
-  // Meet with a kind: `number` (or `string` on the string domain) is
-  // already implied by an ORDER atom's argument; a numeric LEAF narrows
-  // the residual; anything else has an empty intersection with the
-  // constraint's domain.
-  //
-  // A sizing residual (`length`, `unique`) has no domain of its own -- a
-  // count says nothing about what is counted -- so a kind here SETS one
-  // rather than merely agreeing with it: `string & length(3)` is a
-  // three-character string, and `number & length(3)` is empty because a
-  // number has no length (stateEmpty decides that, not this).
   private meetKind(peer: any, ctx: AontuContext): Val {
     const marker = peer.peg
     const merged = this.cloneState()
@@ -1328,14 +953,7 @@ 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.
     merged.musts = [...this.musts, ...peer.musts]
 
     return this.finish(merged, ctx, peer)
@@ -1353,10 +971,6 @@ class ConstraintVal extends FeatureVal {
     out.site.row = this.site.row
     out.site.col = this.site.col
     out.site.url = this.site.url
-    // Marks ratchet across a meet (the propagateMarks rule): a fresh
-    // residual must carry both operands' type/hide marks, or a
-    // `type(min(0)) & max(10)` merge would silently unmark the field
-    // (the Go fold re-ratchets from its terms; this is the TS twin).
     propagateMarks(this, out)
     propagateMarks(peer, out)
     return out
@@ -1432,9 +1046,6 @@ class ConstraintVal extends FeatureVal {
 }
 
 
-// The tighter of two like-direction bounds: the higher lower bound (or
-// lower upper bound); on the same point the OPEN bound wins, and on a
-// full tie the tower-lowest endpoint spelling survives.
 function tighter(
   domain: 'number' | 'string',
   a: Bound | undefined,
@@ -1475,13 +1086,6 @@ 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 (true === v.isNil) {
     return true
@@ -1501,12 +1105,6 @@ 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
@@ -1526,15 +1124,6 @@ function holdsMove(v: any): boolean {
 }
 
 
-// The written arguments of an atom, flattened.
-//
-// A multi-argument call arrives from the func-paren grammar as ONE
-// entry holding the comma group, and `neq([3,1,2])` means the same as
-// `neq(3,1,2)`. The group is always a ListVal by the time it reaches
-// here -- the func-paren handler rawToVals every argument (issue #49) --
-// so there is no raw-array case to unwrap. Flattening happens before
-// the settled check, because an unsettled member hiding inside the
-// group would otherwise make the atom look ready.
 function atomArgs(atom: string, args: any[]): any[] {
   if (('neq' === atom || 'must' === atom) && 1 === args.length &&
     true === (args[0] as any)?.isList) {
@@ -1544,19 +1133,11 @@ function atomArgs(atom: string, args: any[]): any[] {
 }
 
 
-// The canonical rendering of a residual, in the fixed atom order:
-// kind, lower bound, upper bound, neq, re, length, unique. Taken over the
-// STATE rather than the Val because `length`'s argument is a residual too,
-// and renders by exactly the same rules.
 function canonState(s: ConstraintState): string {
   const parts: string[] = []
   if (null != s.kind) {
     parts.push((s.kind as any).name.toLowerCase())
   }
-  // An ORDER atom's argument implies the domain, so it is not spelled
-  // out. A SIZING residual carries no order, and there `string` is the
-  // only thing saying what is being sized -- drop it and the reparse
-  // would admit lists and maps too.
   else if ('string' === s.domain &&
     null == s.lo && null == s.hi && 0 === s.neqs.length && 0 === s.res.length) {
     parts.push('string')
@@ -1574,19 +1155,11 @@ function canonState(s: ConstraintState): string {
     parts.push('re(' + r.v.canon + ')')
   }
   if (null != s.count) {
-    // Rendered UNABRIDGED, implied parts and all: `length(3)` canonicalises
-    // to `length(integer&min(3)&max(3))` because that IS the residual the
-    // count must satisfy, and canon is a normal form (G6 hashes it),
-    // not a pretty-printer. Abbreviating would mean a second set of
-    // rules for when the implied `integer & min(0)` may be dropped.
     parts.push('length(' + canonState(s.count) + ')')
   }
   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) + ')')
   }
@@ -1601,15 +1174,6 @@ 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,
@@ -1683,11 +1247,6 @@ function constraintStateSubsumes(
     }
   }
 
-  // `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
   }
@@ -1723,9 +1282,6 @@ function constraintAdmitsScalar(
   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
   }
@@ -1733,10 +1289,6 @@ function constraintAdmitsScalar(
 }
 
 
-// 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' :
     stringishLeaf(peer) ? 'string' : undefined
@@ -1774,10 +1326,6 @@ function stateAdmits(s: ConstraintState, peer: any): boolean {
       return false
     }
   }
-  // Every accumulated pattern must match: the meet of two `re` atoms
-  // is conjunction, and matching is UNANCHORED in both engines
-  // (JS RegExp.test, Go regexp.MatchString), so `re("el")` admits
-  // "hello". Anchor with ^ and $ to mean the whole string.
   for (const r of s.res) {
     if (!r.re.test(peer.peg)) {
       return false
@@ -1787,13 +1335,7 @@ function stateAdmits(s: ConstraintState, peer: any): boolean {
 }
 
 
-// The eager emptiness rules. Each is EXACT -- it reports empty only
-// where no value could satisfy the residual -- so the algebra stays
-// sound; the incompleteness it accepts is documented in
-// docs/reference-language.md, "Emptiness".
 function stateEmpty(s: ConstraintState): boolean {
-  // Two disagreeing kind narrowings inside a length argument, recorded by
-  // meetCount because that meet has no ctx to fail through.
   if (s.clash) {
     return true
   }
@@ -1832,10 +1374,6 @@ function stateEmpty(s: ConstraintState): boolean {
     }
   }
 
-  // Point deletion under a narrowed leaf: a closed point interval
-  // whose single value of the narrowed leaf is excluded is empty
-  // (integer & min(3) & max(3) & neq(3)). Without a narrowing the
-  // point survives in the other leaves.
   if (null != s.kind && null != s.lo && null != s.hi &&
     !s.lo.open && !s.hi.open &&
     0 === cmpVal(d, s.lo.v, s.hi.v)) {
@@ -1846,10 +1384,6 @@ function stateEmpty(s: ConstraintState): boolean {
     }
   }
 
-  // Sizing over the number domain: a number has neither a length nor
-  // 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 ||
     0 < s.uniqBy.length)) {
     return true
@@ -1868,10 +1402,6 @@ function stateEmpty(s: ConstraintState): boolean {
 }
 
 
-// The base every `length` argument meets: a count is a non-negative
-// integer, whatever else the argument says (docs/reference-language.md,
-// "`length` semantics" -- `length(c)` is empty iff `c & integer & min(0)`
-// is).
 function countBase(): ConstraintState {
   return {
     domain: 'number',
@@ -1894,12 +1424,6 @@ function countVal(n: number): any {
 }
 
 
-// The pure meet of two count residuals. Both are number-domain and
-// carry no pattern or sizing atom of their own, so the merge is the
-// interval/exclusion part alone. A kind disagreement becomes a `clash`
-// rather than an error: this meet runs at construction, where there is
-// no AontuContext to raise through, and an empty residual carries the
-// same news to `unify`.
 function meetCount(a: ConstraintState, b: ConstraintState): ConstraintState {
   return {
     domain: 'number',
@@ -1919,18 +1443,6 @@ function meetCount(a: ConstraintState, b: ConstraintState): ConstraintState {
 }
 
 
-// Read a WRITTEN `length` argument as a count residual, or undefined when
-// it is not one. Accepted: an integer literal (an exact count), a
-// numeric kind, a Band A residual over the number domain, and any
-// conjunct of those. A conjunct never reaches here any more: an
-// unsettled argument is held as `pending` and folded before the count
-// reads it (G1 phase 4), so `length(min(2)&max(5))` arrives as the
-// single residual it folds to.
-//
-// Anything else is refused rather than deferred. A reference or an
-// expression would have to residuate, and the sizing atoms do not
-// residuate on their ARGUMENT -- only on the peer whose members are
-// still settling.
 function countArgState(arg: any): ConstraintState | undefined {
   if (numericLeaf(arg)) {
     return {
@@ -1982,18 +1494,7 @@ function countArgState(arg: any): ConstraintState | undefined {
 }
 
 
-// A container is SETTLED when it and every child have converged. Until
-// then the member set can still change — an optional key whose value is
-// a still-resolving reference may yet generate — so a sizing atom must
-// defer rather than decide (docs/reference-language.md, "`length`
-// semantics"). Note that an optional holding a settled-but-ungenerable
-// value, `{x:1,y?:number}`, IS settled: the map converges on the first
-// pass and `y` is simply never emitted.
 function containerSettled(bag: any): boolean {
-  // The bag's OWN done-counter is enough: BagVal.unify sets it from the
-  // AND over its children, so an unsettled child already leaves the bag
-  // unsettled. Walking the children again would be a second, drifting
-  // copy of that rule.
   return true === bag.done
 }
 
@@ -2006,35 +1507,15 @@ function genable(child: any): boolean {
     true === child.isList || true === child.isPref ||
     true === child.isRef || true === child.isDisjunct ||
     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)
 }
 
 
-// The children a bag would EMIT, mirroring the selection in
-// `BagVal.gen` — type/hide marks skipped, non-generable residue and
-// values that generate nothing dropped, optional keys dropped when
-// they generate empty.
-//
-// It returns the member VALS rather than their generated values,
-// because uniqueness compares canon and a generated value cannot
-// express that distinction: `1` and `1.0` generate the same JSON number
-// and canon differently. Counting uses the same list, so both sizing
-// atoms see exactly one definition of "member".
-//
-// Returns undefined when a REQUIRED child is residue: the container's
-// own `gen` raises there, and that error is the one worth reporting.
 function emittedMembers(bag: any, ctx: AontuContext): any[] | undefined {
   const out: any[] = []
 
   let entries = items(bag.peg)
   if (bag.isMap) {
-    // Code-point order, because the two ports disagree on raw key order
-    // — JavaScript hoists integer-like keys, Go keeps insertion order —
-    // and a duplicate report must name the same pair in both.
     entries = entries
       .slice()
       .sort((a: any, b: any) => cmpCodePoint(String(a[0]), String(b[0])))
@@ -2057,10 +1538,6 @@ function emittedMembers(bag: any, ctx: AontuContext): any[] | undefined {
       return undefined
     }
 
-    // Generation decides in an isolated collect context, so an
-    // unresolved inner value neither raises here nor pollutes the
-    // caller's errors — the same isolation BagVal.gen uses for an
-    // optional child.
     const cval = child.gen(ctx.clone({ err: [], collect: true }))
 
     if (undefined === cval || (optional && empty(cval))) {
@@ -2074,12 +1551,6 @@ function emittedMembers(bag: any, ctx: AontuContext): any[] | undefined {
 }
 
 
-// Sort accumulated patterns by source in code-point order and drop
-// exact duplicates. Patterns are NEVER simplified or compared for
-// containment: deciding `re("a")` subsumes `re("a|b")` is regex
-// containment, which the algebra deliberately does not do (emptiness
-// stays approximate — sound, incomplete). Two spellings of one language
-// therefore both survive, and both are tested.
 function dedupSortedRes(res: ReAtom[]): ReAtom[] {
   const sorted = [...res].sort((a, b) => cmpCodePoints(a.src, b.src))
   const out: ReAtom[] = []
@@ -2092,9 +1563,6 @@ function dedupSortedRes(res: ReAtom[]): ReAtom[] {
 }
 
 
-// The atom classes registered in the parser's funcMap: each is a
-// ConstraintVal that knows its atom name. Constructed by the
-// func-paren handler as `new funcval({peg: args})`.
 class MinConstraintVal extends ConstraintVal {
   constructor(spec: ValSpec, ctx?: AontuContext) {
     super({ ...spec, atom: 'min' }, ctx)
@@ -2151,9 +1619,6 @@ class UniqueConstraintVal extends ConstraintVal {
 
 
 export {
-  // Exported for the differential corpus test (ADR-003): the two ports'
-  // 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