@hviana/sema 0.8.9 → 0.9.1

package/docs/failures/tempting-but-wrong.md

@@ -12,6 +12,15 @@ discovering bugs:**
   leads to accidental bugs, and real-world corpus must not be compromised.
 - Something that happens due to deduplication, a tie-breaking rule, etc., isn't
   a bug—and that’s a subtle point.
+- A change in behavior is not a behavioral regression: A change that shifts a
+  response from correct to incorrect is not necessarily a regression. Sometimes,
+  there may be many other responses that were incorrect but have become correct.
+  Overall, there must be a net gain. Budget adjustments or computational
+  optimizations often require this.
+- Often, a pathological search is not necessarily resolved by a constant
+  derivative. A constant derivative is typically a type of short-circuit
+  breaker; it can cause truncation and is not necessarily a budget-related
+  measure. Therefore, it must be used wisely.
 
 ### 1. `score >= threshold` decides identity
 
@@ -174,8 +183,10 @@ discovering bugs:**
   the quantities the machine already has (`leadsSomewhere`, the
   exact-then-canonical identity, `accounted` bytes, the ladder, `hubBound`),
   from which the reach of a gap, the offer of a hop, the depth of a join and the
-  scope of a substitution are CONSEQUENCES, not four separate decisions. Nothing
-  in this repository is that today.
+  scope of a substitution are CONSEQUENCES, not four separate decisions. Where
+  the repository stands against it — the engine (`closeOver`), which of the four
+  follow from the law, and the one that does not, with the reason — is stated in
+  `docs/architecture/closure.md`, and nowhere else.
 - **THE STANDARD A CHANGE MUST MEET:** state which consequence it is, and show
   it following from the law. A change that cannot be stated that way is not
   ready.

package/docs/harness/gates.md

@@ -13,22 +13,24 @@ Guards honest silence, determinism, and every pinned contract. Silence:
 unrelated queries ground to nothing (`test/28`, `50`, `56`, `67`, `76`, `84`).
 Determinism: same seed + deposit order + query gives byte-identical answer
 (`test/20`). Every invariant is pinned, the closure law included
-(`test/133`–`147`). §14–25 (pipeline), §64 (derived thresholds), AGENTS.md §2
+(`test/133`–`151`). §14–25 (pipeline), §64 (derived thresholds), AGENTS.md §2
 invariants 1–5.
 
 ## 2 — Work accounting (profiler)
 
-```bash
-node bench/profile-inference.mjs        # add [n] to limit probes
-node bench/profile-inference.mjs --trace # trace is a debugging aid, not product
+```js
+const mind = new Mind({ profile: true }); // meter attached per response
+await mind.respondText(q); //              then read mind.lastCost
+console.log(formatReport(mind.lastCost)); // sumReports() over several
 ```
 
-Guards without trace: counters exact and diffable between COLD runs; phases nest
-(not disjoint — each phase is charged by its own layer); shared analyses charged
-to themselves, not to the first toucher; millisecond fields are
-non-deterministic hints only. With `--trace`, recognition idempotence still
-holds (`test/42`). `src/meter.ts`, `docs/architecture/meter.md`, §55,
-`AGENTS.md` §6.
+The public path is the harness (`AGENTS.md` §6); there is no separate bench
+script. Guards without trace: counters exact and diffable between COLD runs;
+phases nest (not disjoint — each phase is charged by its own layer); shared
+analyses charged to themselves, not to the first toucher; millisecond fields are
+non-deterministic hints only. With an `inspectRationale` callback attached,
+recognition idempotence still holds (`test/42`). `src/meter.ts`,
+`docs/architecture/meter.md`, §55, `AGENTS.md` §6.
 
 ## 3 — Dependency footprint
 

package/docs/mechanisms/cover.md

@@ -15,8 +15,15 @@ consumes them directly; any site whose bytes overlap a computed span is masked
 - `formRules` follow continuation edges (`GraphSearch.formRules`): each hop
   costs `STEP` (1). Forks across all continuations up to the hub bound;
   disambiguation is distributional, not heuristic.
-- Edge-less forms may hop via a halo sibling (`conceptHop` / `resolveConcepts`)
-  at `CONCEPT` (10), borrowing a synonym's continuation.
+- Edge-less forms may hop via a halo sibling (`conceptHop` / `offerConcepts`) at
+  `CONCEPT` (10), borrowing a synonym's continuation.
+- A span's cheapest completion DOMINATES the rest (`buildSearch`): a form or
+  completion of `[i, j)` whose cost has reached that of a completion of `[i, j)`
+  already yielded fires no rule (`searchDominated`). Coverage is positional, so
+  only the cheapest matters to the goal; the byte rules (fuse, splice, join)
+  fire from the completion the search would stand on, never from every
+  alternative it reached. It also makes the first hop's stop-here
+  (`STEP + CONCEPT`) a real horizon for the chain.
 
 ## Gate — `leadsSomewhere` (`src/mind/traverse.ts`)
 
@@ -36,11 +43,18 @@ and are filtered during recognition.
 The cover reports `moves` (its derivation's discrete work) and `accounted`; the
 ladder prices both.
 
-## Pre-resolution (`src/mind/mechanisms/cover.ts`)
+## Licensed premises (`src/mind/mechanisms/cover.ts`, `Licence` in `graph-search.ts`)
 
-`resolveConcepts` and `resolveConnectors` pre-resolve the async maps the
-synchronous search cannot gather: concept targets and learnt connectors, keyed
-by node pair. Bridges (`bridge`) splice connectors between rewrites.
+The synchronous search cannot run the async reads two of its rules need — a
+concept target (a halo lookup) and a learnt connector between two answers (a
+`bridge`). `offerConcepts` and `offerConnectors` OFFER the keys up front (cheap:
+`hasNext`, the touching-site pairs and the N-ary allowances); the search ASKS
+for an offered key only where it reaches it — a connector when its splice's two
+premises meet, a concept target when the hop's asking form (held at the hop's
+own cost) is popped. A cover that asked is provisional: `cover.run` grants the
+asked keys and covers again, until a cover asks nothing — which is then the
+cover every key resolved in advance would have made. The joins licensed by
+ask-free rounds are kept across the re-covers.
 
 ## Provenance
 
@@ -54,3 +68,6 @@ independent evidence streams meet at one anchor — see
 
 - `test/09-edges.test.mjs` — edge following and hop semantics
 - `test/19-nd.test.mjs` — form rules and multi-hop chains
+- `test/151` — connectors and concept hops resolved where the search reaches
+  them; a span's cheapest completion dominates (a hub's degree generates no
+  work)

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://jsr.io/schema/config-file.v1.json",
   "name": "@hviana/sema",
-  "version": "0.8.9",
+  "version": "0.9.1",
   "exports": "./src/index.ts"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hviana/sema",
-  "version": "0.8.9",
+  "version": "0.9.1",
   "description": "Sema: a non-parametric, instance-based reasoning system.",
   "repository": {
     "type": "git",

package/src/alu/README.md

@@ -238,8 +238,16 @@ const sync = await prefetchResonance(resonance, spans);
 ```
 
 The synchronous op callbacks never await — they read from the pre-resolved
-snapshots. The public `Mind.compute(name, operands)` path pre-resolves every
-symbol span before the synchronous kernel runs, using the same discipline.
+snapshots. A named operation applied to the query's operand stream resolves
+opposites ON DEMAND (`withOppositesOnDemand`). The kernel runs against a
+snapshot of the opposites resolved so far. When it asked for one of its symbol
+operands that is not resolved yet, that one is resolved through the host and the
+pure kernel runs again. The result is the eager prefetch's, but only the
+polymorphic inverse reads opposites. Before this, every symbol operand of ANY
+operation paid one host call, and on Sema each is a halo-index query (30–200 ms
+of a plain dialogue turn's parse that computed nothing). The public
+`Mind.compute(name, operands)` path pre-resolves every symbol span before the
+synchronous kernel runs, using the same discipline.
 
 ### The mind loop
 

package/src/alu/src/index.ts

@@ -51,6 +51,7 @@ export {
   prefetchOpposites,
   prefetchRecognisedOps,
   prefetchResonance,
+  withOppositesOnDemand,
 } from "./resonance.js";
 
 export {

package/src/alu/src/parser.ts

@@ -45,10 +45,9 @@ import type { Alu } from "./alu.js";
 import {
   type AluResonance,
   type ConceptAnchor,
-  prefetchOpposites,
   prefetchResonance,
+  withOppositesOnDemand,
 } from "./resonance.js";
-import { NO_RESONANCE } from "./operation.js";
 import { int, real, symbol, symbolSpans, type Value } from "./value.js";
 import { nonSpaceRuns } from "./text.js";
 import { bytesEqual, latin1 } from "../../bytes.js";
@@ -573,10 +572,11 @@ export class QueryParser {
     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/src/alu/src/resonance.ts

@@ -104,6 +104,48 @@ export async function prefetchOpposites(
   };
 }
 
+/** {@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<R>(
+  resonance: AluResonance,
+  symbols: Iterable<Uint8Array>,
+  apply: (sync: ResonanceSync) => R,
+): Promise<R> {
+  const allowed = new Set<string>();
+  for (const bytes of symbols) allowed.add(latin1(bytes));
+  const table = new Map<string, Uint8Array | null>();
+  const asked = new Map<string, Uint8Array>();
+  const sync: ResonanceSync = {
+    opposite: (bytes: Uint8Array) => {
+      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/src/alu/test/alu.test.ts

@@ -9,6 +9,7 @@ import assert from "node:assert/strict";
 import {
   addBits,
   Alu,
+  type AluHost,
   type AluResonance,
   asReal,
   compareBits,
@@ -579,6 +580,45 @@ test("conceptAnchors exposes the operation vocabulary for resonant recognition",
   }
 });
 
+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: string[] = [];
+  const host: AluHost = {
+    meaningOf: async () => null,
+    continuation: async (b) => {
+      asked.push(dec(b));
+      return dec(b) === "large" ? enc("small") : null;
+    },
+    segment: (bytes) => {
+      const runs: Array<{ i: number; j: number }> = [];
+      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: AluResonance = {

package/src/bytes.ts

@@ -35,11 +35,21 @@ export function concat2(a: Uint8Array, b: Uint8Array): Uint8Array {
   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: Uint8Array): string {
+  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)) as unknown as number[],
+    );
+  }
   return s;
 }
 

package/src/canon.ts

@@ -44,6 +44,12 @@ const enc = new TextEncoder();
  *  deliberately conservative: punctuation, digits and word order are content
  *  and pass through untouched. */
 export function textCanon(bytes: Uint8Array): Uint8Array {
+  if (isAscii(bytes)) return asciiCanon(bytes);
+  return unicodeCanon(bytes);
+}
+
+/** The general reading — the DEFINITION of {@link textCanon}. */
+function unicodeCanon(bytes: Uint8Array): Uint8Array {
   const s = dec
     .decode(bytes)
     .normalize("NFKC")
@@ -52,6 +58,40 @@ export function textCanon(bytes: Uint8Array): Uint8Array {
   return enc.encode(s);
 }
 
+function isAscii(bytes: Uint8Array): boolean {
+  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: Uint8Array): Uint8Array {
+  const n = bytes.length;
+  const out = new Uint8Array(n);
+  let o = 0;
+  const ws = (b: number) => 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. */