@hviana/sema 0.8.9 → 0.9.1

package/AGENTS.md

@@ -57,13 +57,13 @@ Five invariants. Violate one and the system degrades silently — tests pin them
 
 Cross-cutting contracts (single-definition, imported everywhere):
 `contentLevels` in `src/geometry.ts` is the one boundary rule;
-`src/mind/derivation.ts` is the closure law; `src/mind/canonical.ts` is the
-canonical segmentation contract; `src/mind/junction.ts` is the shared
-content-addressed ascent; `Precomputed` in `src/mind/pipeline-mechanism.ts` is
-the per-response memo; `src/meter.ts` is the write-only work accounting surface.
-See `docs/INDEX.md` and `factored-machinery.md` for the contract table and
-ownership. Tie-breaks are corpus-determined, not interchangeable
-(`determinism.md`).
+`src/mind/derivation.ts` is the closure law and its engine (`closeOver`);
+`src/mind/canonical.ts` is the canonical segmentation contract;
+`src/mind/junction.ts` is the shared content-addressed ascent; `Precomputed` in
+`src/mind/pipeline-mechanism.ts` is the per-response memo; `src/meter.ts` is the
+write-only work accounting surface. See `docs/INDEX.md` and
+`factored-machinery.md` for the contract table and ownership. Tie-breaks are
+corpus-determined, not interchangeable (`determinism.md`).
 
 ## 3. Where things live
 

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

@@ -1,6 +1,6 @@
 export { asBit, asInt, asReal, bit, coerce, decimalCodec, type Domain, formatReal, int, isNd, isNumeric, joinDomain, nd, parseValue, real, symbol, symbolSpans, tagOf, type Value, type ValueCodec, } from "./value.js";
 export { type Arity, type EvalExpr, type InfixSyntax, NO_RESONANCE, type OpContext, type Operation, OperationRegistry, type OpFn, type OpRuntime, type OpTraits, type ResonanceSync, } from "./operation.js";
-export { type AluResonance, type ConceptAnchor, NO_ALU_RESONANCE, prefetchOpposites, prefetchRecognisedOps, prefetchResonance, } from "./resonance.js";
+export { type AluResonance, type ConceptAnchor, NO_ALU_RESONANCE, prefetchOpposites, prefetchRecognisedOps, prefetchResonance, withOppositesOnDemand, } from "./resonance.js";
 export { type ApplyScalar, ExprGrammar, freeVariables, type IsUnaryFn, type Token, tokenize, } from "./expr.js";
 export { type AluHost, type ComputedSpan, QueryParser, type Span, STRUCTURAL_HOST, } from "./parser.js";
 export { registerNd } from "./kernel-nd.js";

package/dist/src/alu/src/index.js

@@ -8,7 +8,7 @@
 // See ./../README.md for the kernel and its derivation DAG.
 export { asBit, asInt, asReal, bit, coerce, decimalCodec, formatReal, int, isNd, isNumeric, joinDomain, nd, parseValue, real, symbol, symbolSpans, tagOf, } from "./value.js";
 export { NO_RESONANCE, OperationRegistry, } from "./operation.js";
-export { NO_ALU_RESONANCE, prefetchOpposites, prefetchRecognisedOps, prefetchResonance, } from "./resonance.js";
+export { NO_ALU_RESONANCE, prefetchOpposites, prefetchRecognisedOps, prefetchResonance, withOppositesOnDemand, } from "./resonance.js";
 export { ExprGrammar, freeVariables, tokenize, } from "./expr.js";
 export { QueryParser, STRUCTURAL_HOST, } from "./parser.js";
 export { registerNd } from "./kernel-nd.js";

package/dist/src/alu/src/parser.js

@@ -40,8 +40,7 @@
 //      that names an operation literally or by resonance, applied to a
 //      following operand ("opposite large" → "small"), or, for the numerical
 //      layer, to a following EXPRESSION ("derivative of x^2 at 3").
-import { prefetchOpposites, prefetchResonance, } from "./resonance.js";
-import { NO_RESONANCE } from "./operation.js";
+import { prefetchResonance, withOppositesOnDemand, } from "./resonance.js";
 import { int, real, symbol, symbolSpans } from "./value.js";
 import { nonSpaceRuns } from "./text.js";
 import { bytesEqual, latin1 } from "../../bytes.js";
@@ -494,10 +493,7 @@ export class QueryParser {
             return null; // under-supplied → decline
         const args = picked.map((t) => t.value ?? query.subarray(t.i, t.j));
         const symbols = picked.flatMap((t, k) => t.kind === "term" ? [args[k]] : []);
-        const resonance = symbols.length > 0
-            ? await prefetchOpposites(this.resonance, symbols)
-            : NO_RESONANCE;
-        const bytes = this.alu.applyBytes(name, args, resonance);
+        const bytes = await withOppositesOnDemand(this.resonance, symbols, (resonance) => this.alu.applyBytes(name, args, resonance));
         if (bytes === null)
             return null;
         if (symbols.length === args.length && args.some((a) => bytesEqual(bytes, a))) {

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

@@ -35,6 +35,19 @@ export declare const NO_ALU_RESONANCE: AluResonance;
  *  chart uses).  This is the async→sync bridge for the polymorphic inverse,
  *  mirroring how a concept hop's target is pre-resolved and read synchronously. */
 export declare function prefetchOpposites(resonance: AluResonance, symbols: Iterable<Uint8Array>): Promise<ResonanceSync>;
+/** {@link prefetchOpposites} resolved ON DEMAND: run `apply` against a
+ *  synchronous snapshot that answers only the opposites already resolved, and
+ *  when the computation ASKED for one of `symbols` that is not yet resolved,
+ *  resolve it through the host and run `apply` again — until a run asks for
+ *  nothing new.  The result is `apply(prefetchOpposites(resonance, symbols))`
+ *  exactly: an opposite outside `symbols` reads null in both, every one inside
+ *  that the computation reads is the host's answer in both, and `apply` is
+ *  pure, so a run that read the same answers returns the same bytes.  What it
+ *  saves is every host call no computation reads: only the polymorphic
+ *  inverse reads opposites, yet the eager prefetch paid one per symbol operand
+ *  for ANY operation — on SEMA a halo-index query each, measured at 30-200 ms
+ *  of a plain dialogue turn's parse that computed nothing. */
+export declare function withOppositesOnDemand<R>(resonance: AluResonance, symbols: Iterable<Uint8Array>, apply: (sync: ResonanceSync) => R): Promise<R>;
 /** Pre-resolve BOTH capabilities a computation may need synchronously — the
  *  resonant opposite of a symbol (for the polymorphic inverse) AND the operation
  *  a symbol's MEANING names (for a higher-order nd op's function argument) — over

package/dist/src/alu/src/resonance.js

@@ -71,6 +71,47 @@ export async function prefetchOpposites(resonance, symbols) {
         recogniseOp: () => null,
     };
 }
+/** {@link prefetchOpposites} resolved ON DEMAND: run `apply` against a
+ *  synchronous snapshot that answers only the opposites already resolved, and
+ *  when the computation ASKED for one of `symbols` that is not yet resolved,
+ *  resolve it through the host and run `apply` again — until a run asks for
+ *  nothing new.  The result is `apply(prefetchOpposites(resonance, symbols))`
+ *  exactly: an opposite outside `symbols` reads null in both, every one inside
+ *  that the computation reads is the host's answer in both, and `apply` is
+ *  pure, so a run that read the same answers returns the same bytes.  What it
+ *  saves is every host call no computation reads: only the polymorphic
+ *  inverse reads opposites, yet the eager prefetch paid one per symbol operand
+ *  for ANY operation — on SEMA a halo-index query each, measured at 30-200 ms
+ *  of a plain dialogue turn's parse that computed nothing. */
+export async function withOppositesOnDemand(resonance, symbols, apply) {
+    const allowed = new Set();
+    for (const bytes of symbols)
+        allowed.add(latin1(bytes));
+    const table = new Map();
+    const asked = new Map();
+    const sync = {
+        opposite: (bytes) => {
+            const key = latin1(bytes);
+            if (!allowed.has(key))
+                return null;
+            const known = table.get(key);
+            if (known !== undefined)
+                return known;
+            asked.set(key, bytes);
+            return null;
+        },
+        recogniseOp: () => null,
+    };
+    for (;;) {
+        const out = apply(sync);
+        if (asked.size === 0)
+            return out;
+        for (const [key, bytes] of asked) {
+            table.set(key, (await resonance.opposite(bytes)) ?? null);
+        }
+        asked.clear();
+    }
+}
 /** Pre-resolve BOTH capabilities a computation may need synchronously — the
  *  resonant opposite of a symbol (for the polymorphic inverse) AND the operation
  *  a symbol's MEANING names (for a higher-order nd op's function argument) — over

package/dist/src/alu/test/alu.test.js

@@ -432,6 +432,45 @@ test("conceptAnchors exposes the operation vocabulary for resonant recognition",
         assert.ok(!forms.includes("0"));
     }
 });
+test("a symbol's opposite is asked of the host only when the operation reads it", async () => {
+    // Only the polymorphic inverse reads an opposite.  Resolving every symbol
+    // operand's opposite up front paid one host call per operand for ANY
+    // operation — on SEMA a halo-index query each, 30-200 ms of a plain
+    // dialogue turn's parse that computed nothing.
+    const asked = [];
+    const host = {
+        meaningOf: async () => null,
+        continuation: async (b) => {
+            asked.push(dec(b));
+            return dec(b) === "large" ? enc("small") : null;
+        },
+        segment: (bytes) => {
+            const runs = [];
+            for (let i = 0; i < bytes.length;) {
+                if (bytes[i] === 32) {
+                    i++;
+                    continue;
+                }
+                let j = i;
+                while (j < bytes.length && bytes[j] !== 32)
+                    j++;
+                runs.push({ i, j });
+                i = j;
+            }
+            return runs;
+        },
+        reach: Number.POSITIVE_INFINITY,
+    };
+    const u = new Alu({}, host);
+    // An operation that does not read opposites: nothing computed, nothing asked.
+    assert.deepEqual(await u.parse(enc("sqrt large")), []);
+    assert.deepEqual(asked, []);
+    // The inverse reads it: asked once, and grounded exactly as before.
+    const out = await u.parse(enc("opposite large"));
+    assert.equal(out.length, 1);
+    assert.equal(dec(out[0].bytes), "small");
+    assert.deepEqual(asked, ["large"]);
+});
 test("prefetchRecognisedOps bridges async recognition to a sync map", async () => {
     // A stub host resonance: "the rate of change of" means a derivative.
     const stub = {

package/dist/src/bytes.d.ts

@@ -6,8 +6,12 @@ export declare function concatBytes(parts: Uint8Array[]): Uint8Array;
 /** Join two byte spans — the hot two-operand case of {@link concatBytes},
  *  fused without the array wrapper for the search's inner fuse loop. */
 export declare function concat2(a: Uint8Array, b: Uint8Array): Uint8Array;
-/** Latin-1 view of a byte span — a stable, lossless string key for chart
- *  memoization (every byte 0–255 maps to one code unit). */
+/** Latin-1 view of a byte span — ONE code unit per byte, so it is injective
+ *  and safe as an exact cache key (every byte 0–255 maps to one code unit).
+ *  Batched `String.fromCharCode`, chunked to stay within the engine's argument
+ *  limit on long spans; the one definition every content-keyed memo uses.
+ *  `apply` takes the typed array as its argument list directly — a spread
+ *  walks it through the iterator protocol first, ~2.7× slower per short key. */
 export declare function latin1(b: Uint8Array): string;
 /** First index ≥ `from` at which `needle` occurs in `hay`, or -1.  A short naive
  *  scan — used only to locate a result span inside a learnt framing form. */

package/dist/src/bytes.js

@@ -35,12 +35,18 @@ export function concat2(a, b) {
     out.set(b, a.length);
     return out;
 }
-/** Latin-1 view of a byte span — a stable, lossless string key for chart
- *  memoization (every byte 0–255 maps to one code unit). */
+/** Latin-1 view of a byte span — ONE code unit per byte, so it is injective
+ *  and safe as an exact cache key (every byte 0–255 maps to one code unit).
+ *  Batched `String.fromCharCode`, chunked to stay within the engine's argument
+ *  limit on long spans; the one definition every content-keyed memo uses.
+ *  `apply` takes the typed array as its argument list directly — a spread
+ *  walks it through the iterator protocol first, ~2.7× slower per short key. */
 export function latin1(b) {
+    const n = b.length;
     let s = "";
-    for (let k = 0; k < b.length; k++)
-        s += String.fromCharCode(b[k]);
+    for (let i = 0; i < n; i += 4096) {
+        s += String.fromCharCode.apply(null, b.subarray(i, Math.min(i + 4096, n)));
+    }
     return s;
 }
 /** First index ≥ `from` at which `needle` occurs in `hay`, or -1.  A short naive

package/dist/src/canon.js

@@ -37,6 +37,12 @@ const enc = new TextEncoder();
  *  deliberately conservative: punctuation, digits and word order are content
  *  and pass through untouched. */
 export function textCanon(bytes) {
+    if (isAscii(bytes))
+        return asciiCanon(bytes);
+    return unicodeCanon(bytes);
+}
+/** The general reading — the DEFINITION of {@link textCanon}. */
+function unicodeCanon(bytes) {
     const s = dec
         .decode(bytes)
         .normalize("NFKC")
@@ -44,6 +50,44 @@ export function textCanon(bytes) {
         .replace(/(\S)\s+(?=\S)/g, "$1 ");
     return enc.encode(s);
 }
+function isAscii(bytes) {
+    for (let i = 0; i < bytes.length; i++)
+        if (bytes[i] >= 0x80)
+            return false;
+    return true;
+}
+/** {@link unicodeCanon} on ASCII input, byte for byte, without the string
+ *  round trip.  Exact, not approximate: NFKC is the identity on ASCII, the
+ *  lowercase of ASCII is A–Z → a–z, and the ASCII members of the regex's `\s`
+ *  are TAB, LF, VT, FF, CR and SPACE — so an interior run of them becomes one
+ *  space and an edge run stays verbatim, exactly as the regex rewrites it.
+ *  The canonicalizer runs once per probed span on the recognition and join
+ *  paths, so its constant is paid thousands of times per response; test/148
+ *  pins the agreement over random ASCII and over the edge cases. */
+function asciiCanon(bytes) {
+    const n = bytes.length;
+    const out = new Uint8Array(n);
+    let o = 0;
+    const ws = (b) => b === 0x20 || (b >= 0x09 && b <= 0x0d);
+    for (let i = 0; i < n;) {
+        const b = bytes[i];
+        if (!ws(b)) {
+            out[o++] = b >= 0x41 && b <= 0x5a ? b + 0x20 : b;
+            i++;
+            continue;
+        }
+        let j = i;
+        while (j < n && ws(bytes[j]))
+            j++;
+        if (i > 0 && j < n)
+            out[o++] = 0x20;
+        else
+            for (let k = i; k < j; k++)
+                out[o++] = bytes[k];
+        i = j;
+    }
+    return o === n ? out : out.slice(0, o);
+}
 /** 32-bit FNV-1a over a canonical key — the integer the store's canon index
  *  is keyed on.  Same construction as the node table's content hash; a
  *  collision is resolved by verifying canon(stored) === key, never trusted. */

package/dist/src/geometry.d.ts

@@ -204,7 +204,7 @@ export interface ContentFold {
  *  streams.  Verifying the bytes here would cost O(prefix) and defeat the
  *  whole point, so the obligation sits with the caller, and every caller
  *  discharges it structurally rather than by care: `perceiveDeposit` looks the
- *  entry up under `latin1Key(bytes.subarray(0, L))` — the prefix's own bytes
+ *  entry up under `latin1(bytes.subarray(0, L))` — the prefix's own bytes
  *  ARE the cache key — and a conversation's fold state advances only by
  *  append.  A new caller that cannot make the same structural argument must
  *  pass no `prev` at all; the cold path is always correct.
@@ -214,6 +214,24 @@ export declare function contentFoldIncremental(space: Space, alphabet: Alphabet,
     tree: Sema;
     fold: ContentFold;
 };
+/** The node a byte stream's content fold NAMES — `foldTree` over
+ *  {@link contentFoldSpan}'s tree, without building a single vector.
+ *
+ *  A fold names a node only when every child is named, so identity needs the
+ *  tree's SHAPE and the store's answer for each node — and the shape is a
+ *  function of the bytes (cuts and levels) plus, inside an over-long row, each
+ *  item's {@link itemKey}: eight coordinates of its raw gist.  Those are read
+ *  lazily through {@link boundCoord}, bit-identical to the coordinates the
+ *  vector fold computes, so the grouping (the SAME {@link groupByLevel}) cannot
+ *  differ.  `segment(from, to)` names a level-0 segment (one flat node over
+ *  single-byte atoms, or the atom itself); `branch(kids, from, to)` names the
+ *  group covering [from, to) — `kids` holds null for an unnamed child, because
+ *  the store names a branch by its BYTES when its children do not name it
+ *  (the write side's step 1b, store.ts `intern`), so an unnamed child does not
+ *  settle its ancestors.  Every item's grouping key is read from its content,
+ *  named or not, for the same reason.  An empty stream is the caller's: its
+ *  fold is the alphabet's zero-byte leaf, not a segment. */
+export declare function contentIdentity(space: Space, alphabet: Alphabet, bytes: Uint8Array, segment: (from: number, to: number) => number | null, branch: (kids: ReadonlyArray<number | null>, from: number, to: number) => number | null): number | null;
 /** A stable-prefix fold's reusable state: the segment edge offsets and each
  *  segment's independently-folded root ({@link riverFoldRaw} output).  A
  *  grown stream whose boundary set EXTENDS a previous fold's reuses every