@hviana/sema 0.2.6 → 0.2.8

package/dist/src/alu/src/operation.d.ts

@@ -0,0 +1,168 @@
+import { type Value } from "./value.js";
+/** Arity: a fixed operand count, or "variadic" for a fold (and/or of many,
+ *  dot, min/max, polynomial evaluation). */
+export type Arity = number | "variadic";
+/** Synchronous resonance an op callback may consult, pre-resolved by the host.
+ *  This is the only path by which a computation reads MEANING from a symbol's
+ *  opaque bytes; numbers never touch it. */
+export interface ResonanceSync {
+    /** The resonant opposite of a symbol's bytes — its antonym / inverse in the
+     *  resonance space, of whatever modality — or null if none is known.  Found
+     *  by the host's halo resonance and handed in pre-resolved (see
+     *  resonance.ts). */
+    opposite(bytes: Uint8Array): Uint8Array | null;
+    /** The canonical operation a symbol's bytes MEAN, found by resonance over the
+     *  operation concepts — the GENERIC, modality-agnostic recognition path, the
+     *  same one the host uses to recognise an operator a query does not literally
+     *  spell.  Pre-resolved by the host; null when nothing resonates.  This is how
+     *  the FUNCTION ARGUMENT of a higher-order nd op (the "+" of a reduce, the
+     *  predicate of a filter) is resolved when it is not a literal surface form —
+     *  see {@link OpContext.resolveOp}. */
+    recogniseOp(bytes: Uint8Array): string | null;
+}
+/** Runtime knobs the numerical kernel reads (the limit layer's tolerance and
+ *  iteration ceiling).  Carried on the context so a derived op never closes
+ *  over global state. */
+export interface OpRuntime {
+    /** Convergence tolerance ε: a refinement stops when successive results agree
+     *  within this. */
+    tol: number;
+    /** Hard iteration ceiling, so a non-converging step still terminates. */
+    maxIter: number;
+}
+/** Evaluate a symbolic EXPRESSION at a binding of its free variable, returning a
+ *  plain number, or null when the expression cannot be evaluated (unparseable,
+ *  or no evaluator wired in).  This is the bridge that lets a NUMERICAL op act
+ *  on a function: an integral, a derivative, a limit (or any refinement) needs
+ *  to sample its integrand/argument at many points, and the integrand is itself
+ *  a sub-expression with a free variable — evaluating it is a RECURSIVE
+ *  application of the same ALU.  Injected by the host (the {@link
+ *  "./alu.js".Alu} facade); absent in a bare registry, where expression-ops
+ *  simply decline. */
+export type EvalExpr = (bytes: Uint8Array, variable: string, at: number) => number | null;
+/** The context a callback runs in: the means to call sibling ops by name, the
+ *  runtime knobs, pre-resolved resonance, and (when wired) an expression
+ *  evaluator.  This is what makes derivations compose without import cycles
+ *  between kernel files. */
+export interface OpContext {
+    /** Apply another registered op by canonical name. */
+    apply(name: string, args: Value[]): Value;
+    /** Whether an op is registered (lets a derivation pick a fast path when an
+     *  optional sibling exists). */
+    has(name: string): boolean;
+    /** Resolve an operation-denoting VALUE to a canonical op name — the
+     *  intelligent callback resolution the higher-order nd ops (map/reduce/filter/
+     *  find) use for their FUNCTION ARGUMENT.  An operation is named the SAME way
+     *  any operation is recognised anywhere in the kernel, reusing the existing
+     *  machinery rather than a bespoke table:
+     *
+     *   1. a literal SURFACE FORM — the op-value's bytes are a registered spelling
+     *      ("+", "plus", "add", "*", "max", …) → the registry's own form index;
+     *   2. else its MEANING — {@link ResonanceSync.recogniseOp} over the same
+     *      operation concepts, so a synonym or a multimodal gesture the bytes do
+     *      not literally spell still resolves (pre-resolved by the host);
+     *   3. else a bare canonical NAME already (a symbol whose bytes equal an op
+     *      name), or an int/bit treated as its decimal name — last resort.
+     *
+     *  `arity` (when given) disambiguates a surface a unary and a binary op share
+     *  (e.g. "-" is both negate and subtract): the claimant of that arity wins.
+     *  Returns null when nothing resolves, so a higher-order op declines. */
+    resolveOp(op: Value, arity?: number): string | null;
+    /** The numerical runtime knobs. */
+    rt: OpRuntime;
+    /** Pre-resolved resonance for the polymorphic inverse and op recognition. */
+    resonance: ResonanceSync;
+    /** Evaluate a symbolic expression at a variable binding (see {@link
+     *  EvalExpr}); undefined in a bare registry with no host evaluator. */
+    evalExpr?: EvalExpr;
+}
+/** The callback that executes an operation on resolved operands. */
+export type OpFn = (args: Value[], ctx: OpContext) => Value;
+/** How tightly an INFIX operation binds, and to which side — declared at
+ *  registration, next to the op it describes, so the expression grammar is
+ *  read off the registry rather than hardcoded in any parser.  Higher
+ *  `precedence` binds tighter. */
+export interface InfixSyntax {
+    precedence: number;
+    rightAssoc?: boolean;
+}
+/** Optional syntactic/structure traits of an operation, declared where the op
+ *  is registered.  Every parser-facing distinction the ALU makes is one of
+ *  these traits — there is no side table of names anywhere. */
+export interface OpTraits {
+    /** Consumes an n-dimensional value WHOLE (exempt from broadcast). */
+    structural?: boolean;
+    /** Usable as an infix operator, with the given binding. */
+    infix?: InfixSyntax;
+    /** The FIRST operand is an EXPRESSION (a function's bytes) rather than a
+     *  value; the remaining `arity − 1` operands are its points/bounds.  The
+     *  numerical layer's diff/integrate/solve/limit/optimize declare this. */
+    expression?: boolean;
+}
+/** An operation — primitive or derived, indistinguishable by type. */
+export interface Operation extends OpTraits {
+    /** Canonical id, e.g. "add", "nand", "converge", "sin". */
+    name: string;
+    /** Operand count (fixed) or "variadic". */
+    arity: Arity;
+    /** True only for the kernel's irreducible roots. */
+    primitive: boolean;
+    /** Surface forms this op answers to — the spellings resonance maps to it,
+     *  e.g. add ← ["+", "plus", "sum", "add"].  May be empty for an internal op
+     *  that has no user-facing surface. */
+    forms: string[];
+    /** The callback. */
+    fn: OpFn;
+}
+/** A resonance that knows nothing — the default when no host is wired in, so
+ *  the pure kernel and its tests run with zero coupling.  Op recognition then
+ *  falls back to literal surface forms / canonical names only. */
+export declare const NO_RESONANCE: ResonanceSync;
+/** The collection of operations, indexed by canonical name and by surface form.
+ *  Building a kernel is a sequence of {@link prim}/{@link derive} calls; the
+ *  registry then resolves names at apply time, so registration order need only
+ *  respect the dependency DAG loosely (a derived op may reference an op
+ *  registered later, since resolution is lazy). */
+export declare class OperationRegistry {
+    private readonly ops;
+    /** Surface form → the canonical names that claim it.  A form may be shared
+     *  (e.g. "-" is both subtract and negate); the caller disambiguates by arity
+     *  and position, so the index keeps every claimant. */
+    private readonly formIndex;
+    /** Register an operation record directly. */
+    register(op: Operation): void;
+    /** Register a PRIMITIVE op (hand-written callback), with optional {@link
+     *  OpTraits} — structural (consumes an nd whole, exempt from broadcast),
+     *  infix binding, expression-operand — declared here, next to the op. */
+    prim(name: string, arity: Arity, forms: string[], fn: OpFn, traits?: OpTraits): void;
+    /** Register a DERIVED op (callback composes other ops via ctx).  `traits`
+     *  as in {@link prim}. */
+    derive(name: string, arity: Arity, forms: string[], fn: OpFn, traits?: OpTraits): void;
+    /** The op with this canonical name, or undefined. */
+    get(name: string): Operation | undefined;
+    has(name: string): boolean;
+    /** The canonical names a surface form maps to (empty if none).  Several ops
+     *  can share one surface (unary vs binary "-"), so this returns all. */
+    lookupForm(form: string): readonly string[];
+    /** Every (surface form → canonical name) pair — the host enumerates these to
+     *  seed its operator recogniser. */
+    formEntries(): Iterable<{
+        form: string;
+        name: string;
+    }>;
+    /** Every registered canonical name. */
+    names(): Iterable<string>;
+    /** Build a context bound to a resonance and runtime — the object derived
+     *  callbacks call back into.  `apply` validates arity-vs-presence and surfaces
+     *  a clear error rather than letting an undefined op silently produce NaN.
+     *  An optional expression evaluator lets the numerical layer act on functions
+     *  (see {@link EvalExpr}). */
+    context(resonance: ResonanceSync, rt: OpRuntime, evalExpr?: EvalExpr): OpContext;
+    /** Resolve an operation-denoting value to a canonical op name — the shared
+     *  machinery behind {@link OpContext.resolveOp}.  Tries, in order: a literal
+     *  surface form (the registry's own index, arity-disambiguated), the meaning
+     *  via `resonance.recogniseOp`, then a bare canonical name / decimal reading.
+     *  Returns null when nothing resolves.  Static-shaped (takes the resonance
+     *  explicitly) so both the context closure and callers can use it. */
+    resolveOp(op: Value, resonance: ResonanceSync, arity?: number): string | null;
+}

package/dist/src/alu/src/operation.js

@@ -0,0 +1,189 @@
+// operation.ts — the Operation record and the registry it lives in.
+//
+// An Operation is the irreducible unit of the ALU.  A PRIMITIVE op has a
+// hand-written callback (the kernel's irreducible roots: nand, the real
+// arithmetic primitives, converge); a DERIVED op's callback only calls OTHER ops
+// by canonical name through the {@link OpContext}.  The two are the SAME type —
+// a caller cannot tell a primitive from a derivation — which is the whole point:
+// "subtract = add ∘ negate" is registered exactly like a primitive and competes
+// in the search exactly like one.  Because a derived callback's body is a
+// sequence of `ctx.apply("…", …)` calls, the derivation DAG is literal,
+// inspectable source: you can read off, from nand, how every gate is built, and
+// from add/multiply/converge how every number-theoretic and numerical op is.
+//
+// The module is pure.  The one window onto meaning a callback may need — the
+// resonant opposite of a symbol, for the polymorphic inverse — arrives through
+// {@link ResonanceSync}, which the host pre-resolves (SEMA's async resonance is
+// hoisted out of the synchronous search, exactly as concept hops and connectors
+// are).  ALU never queries resonance itself.
+import { isNd, nd } from "./value.js";
+/** A resonance that knows nothing — the default when no host is wired in, so
+ *  the pure kernel and its tests run with zero coupling.  Op recognition then
+ *  falls back to literal surface forms / canonical names only. */
+export const NO_RESONANCE = {
+    opposite: () => null,
+    recogniseOp: () => null,
+};
+/** The collection of operations, indexed by canonical name and by surface form.
+ *  Building a kernel is a sequence of {@link prim}/{@link derive} calls; the
+ *  registry then resolves names at apply time, so registration order need only
+ *  respect the dependency DAG loosely (a derived op may reference an op
+ *  registered later, since resolution is lazy). */
+export class OperationRegistry {
+    ops = new Map();
+    /** Surface form → the canonical names that claim it.  A form may be shared
+     *  (e.g. "-" is both subtract and negate); the caller disambiguates by arity
+     *  and position, so the index keeps every claimant. */
+    formIndex = new Map();
+    /** Register an operation record directly. */
+    register(op) {
+        this.ops.set(op.name, op);
+        for (const f of op.forms) {
+            const a = this.formIndex.get(f);
+            if (a) {
+                if (!a.includes(op.name))
+                    a.push(op.name);
+            }
+            else
+                this.formIndex.set(f, [op.name]);
+        }
+    }
+    /** Register a PRIMITIVE op (hand-written callback), with optional {@link
+     *  OpTraits} — structural (consumes an nd whole, exempt from broadcast),
+     *  infix binding, expression-operand — declared here, next to the op. */
+    prim(name, arity, forms, fn, traits = {}) {
+        this.register({ name, arity, primitive: true, forms, fn, ...traits });
+    }
+    /** Register a DERIVED op (callback composes other ops via ctx).  `traits`
+     *  as in {@link prim}. */
+    derive(name, arity, forms, fn, traits = {}) {
+        this.register({ name, arity, primitive: false, forms, fn, ...traits });
+    }
+    /** The op with this canonical name, or undefined. */
+    get(name) {
+        return this.ops.get(name);
+    }
+    has(name) {
+        return this.ops.has(name);
+    }
+    /** The canonical names a surface form maps to (empty if none).  Several ops
+     *  can share one surface (unary vs binary "-"), so this returns all. */
+    lookupForm(form) {
+        return this.formIndex.get(form) ?? [];
+    }
+    /** Every (surface form → canonical name) pair — the host enumerates these to
+     *  seed its operator recogniser. */
+    *formEntries() {
+        for (const [form, names] of this.formIndex) {
+            for (const name of names)
+                yield { form, name };
+        }
+    }
+    /** Every registered canonical name. */
+    names() {
+        return this.ops.keys();
+    }
+    /** Build a context bound to a resonance and runtime — the object derived
+     *  callbacks call back into.  `apply` validates arity-vs-presence and surfaces
+     *  a clear error rather than letting an undefined op silently produce NaN.
+     *  An optional expression evaluator lets the numerical layer act on functions
+     *  (see {@link EvalExpr}). */
+    context(resonance, rt, evalExpr) {
+        const self = this;
+        const ctx = {
+            rt,
+            resonance,
+            evalExpr,
+            has: (name) => self.ops.has(name),
+            resolveOp: (op, arity) => self.resolveOp(op, resonance, arity),
+            apply(name, args) {
+                const op = self.ops.get(name);
+                if (!op)
+                    throw new Error(`ALU: unknown operation "${name}"`);
+                // ── ELEMENT-WISE BROADCAST ────────────────────────────────────────
+                // A SCALAR op (non-structural) applied to an n-dimensional argument
+                // lifts over it: the op runs on each element and the results re-pack
+                // into an nd of the same shape.  This is the ONE place "every operation
+                // supports nd" is implemented — add, sin, nand, the polymorphic inverse
+                // all broadcast for free, and because each element re-enters `apply`,
+                // NESTING recurses (an nd of nd lifts twice) with no extra code.
+                //
+                //   • several nd args ZIP position-wise (their top-level lengths must
+                //     agree); a scalar arg is held constant against the list — so
+                //     add([1,2,3],[4,5,6]) = [5,7,9] and add([1,2,3], 10) = [11,12,13].
+                //   • a structural op is exempt: it wants the whole list (a reduce
+                //     cannot be lifted across the very elements it folds).
+                if (!op.structural && args.some(isNd)) {
+                    let len = -1;
+                    for (const a of args) {
+                        if (!isNd(a))
+                            continue;
+                        if (len === -1)
+                            len = a.items.length;
+                        else if (a.items.length !== len) {
+                            throw new Error(`ALU: cannot broadcast "${name}" over lists of unequal length ` +
+                                `(${len} vs ${a.items.length})`);
+                        }
+                    }
+                    const out = [];
+                    for (let i = 0; i < len; i++) {
+                        out.push(ctx.apply(name, args.map((a) => isNd(a) ? a.items[i] : a)));
+                    }
+                    return nd(out);
+                }
+                if (op.arity !== "variadic" && args.length !== op.arity) {
+                    throw new Error(`ALU: "${name}" expects ${op.arity} operand(s), got ${args.length}`);
+                }
+                return op.fn(args, ctx);
+            },
+        };
+        return ctx;
+    }
+    /** Resolve an operation-denoting value to a canonical op name — the shared
+     *  machinery behind {@link OpContext.resolveOp}.  Tries, in order: a literal
+     *  surface form (the registry's own index, arity-disambiguated), the meaning
+     *  via `resonance.recogniseOp`, then a bare canonical name / decimal reading.
+     *  Returns null when nothing resolves.  Static-shaped (takes the resonance
+     *  explicitly) so both the context closure and callers can use it. */
+    resolveOp(op, resonance, arity) {
+        // The op-value's surface text, if it has a byte reading.
+        let text = null;
+        if (op.domain === "symbol") {
+            let s = "";
+            for (let i = 0; i < op.bytes.length; i++) {
+                s += String.fromCharCode(op.bytes[i]);
+            }
+            text = s.trim();
+        }
+        else if (op.domain === "int")
+            text = op.n.toString();
+        else if (op.domain === "bit")
+            text = String(op.b);
+        if (text === null || text.length === 0)
+            return null;
+        // (1) a literal SURFACE FORM, arity-disambiguated when asked.
+        const claimants = this.formIndex.get(text);
+        if (claimants && claimants.length > 0) {
+            if (arity !== undefined) {
+                for (const n of claimants) {
+                    const o = this.ops.get(n);
+                    const a = o && (o.arity === "variadic" ? 2 : o.arity);
+                    if (a === arity)
+                        return n;
+                }
+            }
+            return claimants[0];
+        }
+        // (2) the MEANING, via pre-resolved resonance (synonym / multimodal gesture
+        //     the bytes do not literally spell) — only a symbol carries meaning.
+        if (op.domain === "symbol") {
+            const byMeaning = resonance.recogniseOp(op.bytes);
+            if (byMeaning && this.ops.has(byMeaning))
+                return byMeaning;
+        }
+        // (3) a bare canonical NAME already registered.
+        if (this.ops.has(text))
+            return text;
+        return null;
+    }
+}

package/dist/src/alu/src/parser.d.ts

@@ -0,0 +1,221 @@
+import type { Alu } from "./alu.js";
+import { type ConceptAnchor } from "./resonance.js";
+/** A half-open byte range. */
+export interface Span {
+    i: number;
+    j: number;
+}
+/** A computation the parser recognised and evaluated: the query span [i, j) it
+ *  is authoritative for, and the canonical result bytes. */
+export interface ComputedSpan extends Span {
+    bytes: Uint8Array;
+}
+/** The port through which the parser reaches its host.  This interface is the
+ *  ENTIRE coupling surface between the ALU and any host: the ALU imports
+ *  nothing from a mind or store, and every member is a GENERIC capability the
+ *  host already has — nothing here mentions operations, vocabularies, or any
+ *  ALU notion, so the host holds no ALU-specific logic either.
+ *
+ *  MEANING (resonance):
+ *   • meaningOf — which of the given labelled forms does a span MEAN?  The ALU
+ *     supplies the anchors (its own concept vocabulary); the host only answers
+ *     nearness in its meaning space, above its own threshold, or null.  This
+ *     is what recognises an operation the bytes do not literally spell — an
+ *     "∫" drawn, a "plus" spoken — in any modality.
+ *   • continuation — the grounded form the host's corpus continues a form to
+ *     (the same grounding its recall uses), or null.  The ALU is the one that
+ *     READS this as the resonant opposite: it asks for the continuation of an
+ *     operand under an inverse, and a corpus that learnt "opposite of large →
+ *     small" grounds exactly that.  The host stays neutral — it only ever
+ *     answers "where does this form lead?".
+ *
+ *  GEOMETRY (perception):
+ *   • segment — coherent runs by the host's own geometric perception.  The
+ *     parser uses this to ask "is this gap pure separator?" (one segment or
+ *     none) — never a character class of its own.
+ *   • reach — how far (in bytes) an operator may look for its operand: the
+ *     host's own grouping capacity, so adjacency is judged by the same
+ *     geometry that groups the host's perception. */
+export interface AluHost {
+    meaningOf(bytes: Uint8Array, anchors: ReadonlyArray<ConceptAnchor>): Promise<string | null>;
+    continuation(bytes: Uint8Array): Promise<Uint8Array | null>;
+    segment(bytes: Uint8Array): Span[];
+    reach: number;
+}
+/** A host that knows nothing beyond structure: no resonance, whitespace-run
+ *  segmentation, unbounded reach.  This is what "the ALU runs fully decoupled"
+ *  means — the parser still reads literal notation, and only the meaning-based
+ *  paths stay silent. */
+export declare const STRUCTURAL_HOST: AluHost;
+export declare class QueryParser {
+    private readonly alu;
+    private readonly host;
+    /** The host's generic capabilities, specialised once into the {@link
+     *  AluResonance} the prefetch bridges consume — the ONE place the ALU gives
+     *  the host's neutral answers their computational reading: op recognition is
+     *  meaningOf over the ALU's own concept anchors, and the polymorphic INVERSE
+     *  of a symbol is the corpus's grounded continuation of it (a learnt
+     *  opposition relation leads from a form to its opposite; the host never
+     *  needs to know that is what it grounded). */
+    private readonly resonance;
+    /** Session memo of a term's meaning-based op reading, keyed by its bytes.
+     *  `meaningOf` is a full river fold of the span — measured at ~a third of
+     *  a plain-English respond's latency, paid per WORD per query — and it is
+     *  a pure function of the bytes (perception is pure; the concept anchors
+     *  are fixed for the Alu's lifetime), so the reading never changes.
+     *  Bounded: cleared wholesale when full (words recur; a rare clear only
+     *  re-pays folds, never changes a reading). */
+    private readonly meaningMemo;
+    private static readonly MEANING_MEMO_MAX;
+    constructor(alu: Alu, host?: AluHost);
+    /** Recognise and evaluate every computation `query` invokes.  All async
+     *  resonance is resolved in here, so the caller receives finished spans it
+     *  can fold synchronously into its search.  Results are deduplicated; a span
+     *  that fails to compute is simply absent (the "rule does not fire"
+     *  contract).
+     *
+     *  The pipeline is one composition ladder, iterated to a FIXPOINT:
+     *
+     *   1. infix arithmetic RUNS are found and evaluated through the
+     *      registry-derived grammar;
+     *   2. every computed span — a run, or a fired operation — is COLLAPSED
+     *      into a single virtual operand, so the next round consumes it as one
+     *      finished value: "sum 1*3 4" is add(3, 4), and "sqrt sum 9 16" is
+     *      sqrt(25) — nesting by iteration, exactly as the grammar nests
+     *      expressions, with no recursion machinery of its own;
+     *   3. rounds repeat while operations still fire (each round consumes at
+     *      least one term, so the ladder is bounded by the term count).
+     *
+     *  One AUTHORITY law then reconciles the readings: a span strictly
+     *  contained in a larger computed span is that computation's MATERIAL (the
+     *  "2-4" inside a solve's "x^2-4", the inner sum under a sqrt), not a rival
+     *  result — the same rule by which the host's search lets a computed span
+     *  override colliding learned facts. */
+    parse(query: Uint8Array): Promise<ComputedSpan[]>;
+    /** Apply an ALU operation to operand byte spans, with the host's resonance
+     *  wired in — the entry point for computation over n-dimensional values.
+     *
+     *  Unlike the in-query arithmetic rule (which hands the facade scalar operand
+     *  bytes), this recognises each operand's STRUCTURE into a Value first and
+     *  runs the kernel on the finished Values, with the full resonance snapshot
+     *  pre-resolved — because an nd computation needs meaning in two places the
+     *  bare facade cannot reach on its own:
+     *
+     *   • the polymorphic INVERSE inside a broadcast — `inverse [large, 3, tall]`
+     *     lifts element-wise (operation.ts), and each symbol element's opposite
+     *     is a resonant lookup, grounded in the host's corpus exactly as a scalar
+     *     inverse is;
+     *   • the FUNCTION ARGUMENT of a higher-order op — `reduce(xs, ‹+›)`,
+     *     `map(xs, ‹negate›)`: the operator value is resolved by
+     *     {@link "./operation.js".OpContext.resolveOp}, which falls through to
+     *     resonance when the bytes are not a literal surface form.
+     *
+     *  Both are async, so every SYMBOL span reachable in the operands (recursing
+     *  through nd nesting, see {@link "./value.js".symbolSpans}) is resolved ONCE
+     *  up front into a synchronous snapshot, and the synchronous kernel computes
+     *  against it.  Returns null when the op is unknown or the computation
+     *  declines — the "this rule does not fire" contract.
+     *
+     *  `asSymbol(idx)` keeps an operand opaque (not read as structure or a
+     *  number) — the numerical-layer convention where operand 0 is an
+     *  expression's bytes; it defaults to "recognise everything", which is what
+     *  an nd computation wants. */
+    compute(name: string, operandBytes: Uint8Array[], asSymbol?: (idx: number) => boolean): Promise<Uint8Array | null>;
+    /** Lex the query ONCE into a single ascending token stream: the facade's
+     *  scanner claims numeric OPERANDS and symbolic OPERATORS, and every maximal
+     *  unclaimed run between spacing bytes is a TERM — a word, glyph, or opaque
+     *  fragment that may name an operation.  Terms are deliberately bounded by
+     *  the spacing floor, not the host's geometric segmentation: perception may
+     *  cut mid-word (its segments are grouping capacity, not word boundaries),
+     *  while an operation NAME is a notation-level token.  Geometry still
+     *  governs what happens BETWEEN tokens (gap bridging, operand reach).
+     *
+     *  Tokens are disjoint, ascending, and cover every non-spacing byte — so
+     *  the gap between consecutive tokens is pure spacing BY CONSTRUCTION, a
+     *  structural fact the run recogniser leans on. */
+    private lex;
+    /** The maximal infix-arithmetic runs in the query: an alternation of numeric
+     *  operands and SYMBOLIC operators (e.g. "2+3*4"), returned as [start, end)
+     *  ranges that begin and end on an operand.
+     *
+     *  Consecutive tokens may be SEPARATED — "3 + 3" is the same run as "3+3".
+     *  The gap between two tokens is a bridgeable separator exactly when the
+     *  host's geometric segmenter reads it as at most one coherent run — the
+     *  same judgement the perception tree makes about spacing — so no character
+     *  is privileged as "the" separator. */
+    private arithmeticRuns;
+    /** The maximal BRACKETED arithmetic runs: like {@link arithmeticRuns} but
+     *  grouping brackets participate — an all-'(' term opens depth where an
+     *  operand is expected, a term beginning with ')' closes it where an
+     *  operator could follow (only its bracket prefix joins the run; anything
+     *  after — a trailing "?" — ends it).  A run is recorded only when it is
+     *  BALANCED, actually crossed a bracket, and contains an operator — the
+     *  bracket-free case is {@link arithmeticRuns}' own.  Evaluation is the
+     *  same registry-derived grammar, whose lexer already reads the brackets. */
+    private bracketedRuns;
+    /** Evaluate an infix-arithmetic run to its canonical result bytes, through
+     *  the kernel's recursive expression evaluator, or null if it does not
+     *  evaluate.  A whole result stays an exact int; otherwise the canonical
+     *  rounded real — deterministic, so the search's chart memoises identical
+     *  results identically. */
+    private evalRun;
+    /** Recognise and apply the operations the query's TERMS name — the generic,
+     *  multimodal path.  A term may name an operation literally (its bytes are a
+     *  registered surface form — no resonance cost) or by RESONANCE (its gist
+     *  lands on an operation's concept, any modality).
+     *
+     *  Recognition PROPOSES, application DISPOSES: a surface form may be shared
+     *  by several operations ("zero" is both the constant and solve's
+     *  root-finding), so every literal claimant is kept, in registration order,
+     *  and the first whose application actually fires wins — disambiguation by
+     *  what the query supplies, not by a precedence table.  Recognition runs
+     *  CONCURRENTLY — each term's reading is independent — and is memoised in
+     *  `readings` across fixpoint rounds (a surviving term is the same token
+     *  object), so each term resonates at most once per parse.  Application is
+     *  then ordered and deterministic: an EXPRESSION op takes the function that
+     *  follows it ({@link applyToExpression}), any other op takes its arity's
+     *  worth of operands from the stream ({@link applyToStream}).  Both read
+     *  the same composed stream — an expression's TEXT comes from the raw query
+     *  bytes by position, so composition never disturbs it, while a composed
+     *  operand serves as a finished point/bound or argument. */
+    private operations;
+    /** Apply a NUMERICAL-LAYER op — one whose first operand is an EXPRESSION (a
+     *  function), declared by the op's own `expression` trait.  The registry's
+     *  arity says how many trailing numeric operands are its points/bounds
+     *  (arity − 1); the bytes between the operator and those points — with
+     *  non-math filler stripped by {@link cleanExprText} — are the expression,
+     *  evaluated by a recursive application of the kernel. */
+    private applyToExpression;
+    /** Apply any other op to the OPERAND STREAM after the operator: the numeric
+     *  operands and symbol terms that follow it, merged nearest-first, each
+     *  within the host's reach of the token before it — so "sqrt 144",
+     *  "gcd 12 18", and "opposite large" are one rule, and the NEAREST token is
+     *  the operand ("opposite large 5" inverts "large", not the 5).
+     *
+     *  Two structural refinements make this read like notation rather than a
+     *  special case:
+     *
+     *   • WORD-INFIX — an under-supplied operator borrows the numeric operand
+     *     immediately BEFORE it (within reach), so "7 minus 2" applies
+     *     subtract(7, 2) exactly as "7 - 2" would: a synonym is notation too.
+     *   • GROUNDED-ONLY SYMBOLS — when every operand is a symbol, a result that
+     *     merely echoes an operand means resonance grounded nothing (an inverse
+     *     with no learnt opposition), and the rule stays silent rather than
+     *     invent meaning.  Numeric identities ("max 3 7" → "7") are real
+     *     results and pass.
+     *
+     *  A NULLARY op never fires from a bare term: a computation must consume
+     *  something, or any prose word that happens to name a constant would be
+     *  rewritten.  Symbol operands get their resonance (the opposite each may
+     *  need) pre-resolved in one prefetch. */
+    private applyToStream;
+    /** Strip non-math filler tokens from a raw expression string — keep numbers,
+     *  operators, parens, names the GRAMMAR resolves (unary functions,
+     *  registered constants), and single-RUNE identifiers.  The rune rule is the
+     *  mirror of {@link "./alu.js".Alu.conceptAnchors}' compound rule: a compound
+     *  name carries distributional meaning (it is either a resolvable operation
+     *  or filler — "of", "at", "the"), while a bare atom carries none and can
+     *  only be the expression's free variable.  Dropping the filler leaves the
+     *  evaluator clean notation. */
+    private cleanExprText;
+}