@hviana/sema 0.1.5 → 0.1.7

package/dist/src/mind/primitives.js

@@ -2,60 +2,59 @@
 //
 //   Address  — bytes → node   (perceive, foldTree, resolve)
 //   Read     — node → bytes   (read)
-import {
-  bytesToTree,
-  bytesToTreePyramid,
-  gridToTree,
-  hilbertBytes,
-  stackGrids,
-} from "../geometry.js";
+import { bytesToTree, bytesToTreePyramid, gridToTree, hilbertBytes, stackGrids, } from "../geometry.js";
 import { ALL } from "./types.js";
 // ── Address: bytes → node ──────────────────────────────────────────────
 /** The content key of a byte span — one latin1 char per byte, an exact,
  *  collision-free encoding.  Spans on the perception path are query-scale
  *  (windows, regions, candidate spans), so key construction is far cheaper
  *  than the river fold it deduplicates. */
-function latin1Key(bytes) {
-  // Batched String.fromCharCode — avoids the O(n²) cost of repeated += on
-  // potentially-large query spans, and stays well under the ~65536 arg limit.
-  const n = bytes.length;
-  let s = "";
-  for (let i = 0; i < n; i += 4096) {
-    s += String.fromCharCode(...bytes.subarray(i, Math.min(i + 4096, n)));
-  }
-  return s;
+export function latin1Key(bytes) {
+    // Batched String.fromCharCode — avoids the O(n²) cost of repeated += on
+    // potentially-large query spans, and stays well under the ~65536 arg limit.
+    const n = bytes.length;
+    let s = "";
+    for (let i = 0; i < n; i += 4096) {
+        s += String.fromCharCode(...bytes.subarray(i, Math.min(i + 4096, n)));
+    }
+    return s;
 }
 /** Perceive input into a content-defined tree (the river fold).
- *  Deterministic — identical bytes always produce an identical tree. */
-export function perceive(ctx, input, leafAt, lookup) {
-  if (typeof input === "string" || input instanceof Uint8Array) {
-    const bytes = typeof input === "string"
-      ? new TextEncoder().encode(input)
-      : input;
-    if (leafAt === undefined && lookup === undefined) {
-      // Per-response memo (see MindContext.perceiveMemo): only the plain
-      // inference shape — raw bytes, no store capabilities — is memoised,
-      // keyed by CONTENT so byte-identical spans in fresh arrays still hit.
-      // The tree is shared by reference; Sema nodes are never mutated.
-      const memo = ctx.perceiveMemo;
-      if (memo) {
-        const key = latin1Key(bytes);
-        const hit = memo.get(key);
-        if (hit !== undefined) {
-          return hit;
+ *  Deterministic — identical bytes always produce an identical tree.
+ *
+ *  `boundaries` is an optional sorted list of proper byte offsets where the
+ *  fold must split so that each prefix segment folds identically to how it
+ *  folded when it was learned (§10.3 stable-prefix contract).  Only the
+ *  CALLER — who assembled the multi-turn context — knows where those
+ *  boundaries are; the geometry never guesses them from the bytes. */
+export function perceive(ctx, input, leafAt, lookup, boundaries) {
+    if (typeof input === "string" || input instanceof Uint8Array) {
+        const bytes = typeof input === "string"
+            ? new TextEncoder().encode(input)
+            : input;
+        if (leafAt === undefined && lookup === undefined) {
+            // Per-response memo (see MindContext.perceiveMemo): only the plain
+            // inference shape — raw bytes, no store capabilities — is memoised,
+            // keyed by CONTENT so byte-identical spans in fresh arrays still hit.
+            // The tree is shared by reference; Sema nodes are never mutated.
+            const memo = ctx.perceiveMemo;
+            if (memo) {
+                const key = latin1Key(bytes);
+                const hit = memo.get(key);
+                if (hit !== undefined)
+                    return hit;
+                const tree = bytesToTree(ctx.space, ctx.alphabet, bytes, undefined, undefined, boundaries);
+                memo.set(key, tree);
+                return tree;
+            }
+            return bytesToTree(ctx.space, ctx.alphabet, bytes, undefined, undefined, boundaries);
         }
-        const tree = bytesToTree(ctx.space, ctx.alphabet, bytes);
-        memo.set(key, tree);
-        return tree;
-      }
-      return bytesToTree(ctx.space, ctx.alphabet, bytes);
+        return bytesToTree(ctx.space, ctx.alphabet, bytes, leafAt, lookup);
+    }
+    if (Array.isArray(input)) {
+        return gridToTree(ctx.space, ctx.alphabet, stackGrids(input));
     }
-    return bytesToTree(ctx.space, ctx.alphabet, bytes, leafAt, lookup);
-  }
-  if (Array.isArray(input)) {
-    return gridToTree(ctx.space, ctx.alphabet, stackGrids(input));
-  }
-  return gridToTree(ctx.space, ctx.alphabet, input);
+    return gridToTree(ctx.space, ctx.alphabet, input);
 }
 /** The DEPOSIT-shaped perceive: the PLAIN fold (bit-identical to inference
  *  perception — that structural train/inference agreement is load-bearing
@@ -66,53 +65,45 @@ export function perceive(ctx, input, leafAt, lookup) {
  *  each level — O(turn) instead of O(context) per turn.  Purely a cache:
  *  the produced tree never depends on cache state. */
 export function perceiveDeposit(ctx, bytes) {
-  let prev;
-  // Longest cached PROPER prefix first.
-  const lens = [...ctx._depositLens]
-    .filter((L) => L >= 2 && L < bytes.length)
-    .sort((a, b) => b - a);
-  for (const L of lens) {
-    const hit = ctx._depositTrees.get(latin1Key(bytes.subarray(0, L)));
-    if (hit !== undefined) {
-      prev = hit;
-      break;
+    let prev;
+    // Longest cached PROPER prefix first.
+    const lens = [...ctx._depositLens]
+        .filter((L) => L >= 2 && L < bytes.length)
+        .sort((a, b) => b - a);
+    for (const L of lens) {
+        const hit = ctx._depositTrees.get(latin1Key(bytes.subarray(0, L)));
+        if (hit !== undefined) {
+            prev = hit;
+            break;
+        }
     }
-  }
-  const { tree, pyramid } = bytesToTreePyramid(
-    ctx.space,
-    ctx.alphabet,
-    bytes,
-    prev,
-  );
-  if (bytes.length >= 2) {
-    // The lengths set drifts as the map evicts; past the probe budget the
-    // drift itself becomes the cost (each stale length is an O(len) key
-    // build), so both reset together — losing only warm-up on live chains.
-    if (ctx._depositLens.size > 64) {
-      ctx._depositLens.clear();
-      ctx._depositTrees.clear();
+    const { tree, pyramid } = bytesToTreePyramid(ctx.space, ctx.alphabet, bytes, prev);
+    if (bytes.length >= 2) {
+        // The lengths set drifts as the map evicts; past the probe budget the
+        // drift itself becomes the cost (each stale length is an O(len) key
+        // build), so both reset together — losing only warm-up on live chains.
+        if (ctx._depositLens.size > 64) {
+            ctx._depositLens.clear();
+            ctx._depositTrees.clear();
+        }
+        ctx._depositTrees.set(latin1Key(bytes), pyramid);
+        ctx._depositLens.add(bytes.length);
     }
-    ctx._depositTrees.set(latin1Key(bytes), pyramid);
-    ctx._depositLens.add(bytes.length);
-  }
-  return tree;
+    return tree;
 }
 /** The raw bytes of an input — modality-neutral conversion. */
 export function inputBytes(ctx, input) {
-  if (typeof input === "string") {
-    return new TextEncoder().encode(input);
-  }
-  if (input instanceof Uint8Array) {
-    return input;
-  }
-  if (Array.isArray(input)) {
-    return hilbertBytes(stackGrids(input));
-  }
-  return hilbertBytes(input);
+    if (typeof input === "string")
+        return new TextEncoder().encode(input);
+    if (input instanceof Uint8Array)
+        return input;
+    if (Array.isArray(input))
+        return hilbertBytes(stackGrids(input));
+    return hilbertBytes(input);
 }
 /** Convenience: the gist vector of a byte span. */
 export function gistOf(ctx, bytes) {
-  return perceive(ctx, bytes).v;
+    return perceive(ctx, bytes).v;
 }
 /** Fold a perceived tree bottom-up against the store's content-addressed maps:
  *  every leaf is named by findLeaf, every branch by findBranch over its kids'
@@ -120,37 +111,51 @@ export function gistOf(ctx, bytes) {
  *  node with its byte span and resolved id.  Returns the node's byte end and
  *  resolved id. */
 export function foldTree(ctx, n, start, visit) {
-  if (n.kids === null) {
-    const b = n.leaf ?? new Uint8Array(0);
-    const end = start + b.length;
-    const node = ctx.store.findLeaf(b);
-    visit?.(n, start, end, node);
-    return { end, node };
-  }
-  let pos = start;
-  let known = true;
-  const kids = [];
-  for (const k of n.kids) {
-    const r = foldTree(ctx, k, pos, visit);
-    if (r.node === null) {
-      known = false;
-    } else if (known) {
-      kids.push(r.node);
+    // Fast path: subtree already resolved (from a previous conversation turn
+    // or an earlier recognition pass).  The pyramid reuses prefix subtrees as
+    // identical Sema objects, so this cache turns foldTree into O(suffix)
+    // instead of O(context) for multi-turn recognition.
+    const cached = ctx._resolvedSubtrees?.get(n);
+    if (cached !== undefined) {
+        const end = start + cached.len;
+        visit?.(n, start, end, cached.id);
+        return { end, node: cached.id };
     }
-    pos = r.end;
-  }
-  const node = known ? ctx.store.findBranch(kids) : null;
-  visit?.(n, start, pos, node);
-  return { end: pos, node };
+    if (n.kids === null) {
+        const b = n.leaf ?? new Uint8Array(0);
+        const end = start + b.length;
+        const node = ctx.store.findLeaf(b);
+        visit?.(n, start, end, node);
+        if (node !== null && ctx._resolvedSubtrees) {
+            ctx._resolvedSubtrees.set(n, { id: node, len: b.length });
+        }
+        return { end, node };
+    }
+    let pos = start;
+    let known = true;
+    const kids = [];
+    for (const k of n.kids) {
+        const r = foldTree(ctx, k, pos, visit);
+        if (r.node === null)
+            known = false;
+        else if (known)
+            kids.push(r.node);
+        pos = r.end;
+    }
+    const node = known ? ctx.store.findBranch(kids) : null;
+    visit?.(n, start, pos, node);
+    if (node !== null && ctx._resolvedSubtrees) {
+        ctx._resolvedSubtrees.set(n, { id: node, len: pos - start });
+    }
+    return { end: pos, node };
 }
 /** The canonical node id of a byte span: perceive it in isolation — the way
  *  training did — and recover its root bottom-up.  Returns null if any part is
  *  unknown. */
 export function resolve(ctx, bytes) {
-  if (bytes.length === 0) {
-    return null;
-  }
-  return foldTree(ctx, perceive(ctx, bytes), 0).node;
+    if (bytes.length === 0)
+        return null;
+    return foldTree(ctx, perceive(ctx, bytes), 0).node;
 }
 /** Walk a perceived tree in POST-ORDER with byte offsets — children before
  *  their parent, `visit(node, start, end)` for every node including leaves.
@@ -161,20 +166,19 @@ export function resolve(ctx, bytes) {
  *  walk: its flush semantics need PRE-order decisions at leaf-parents, which
  *  a post-order visitor cannot express.) */
 export function walkTree(n, start, visit) {
-  if (n.kids === null) {
-    const end = start + (n.leaf?.length ?? 0);
-    visit(n, start, end);
-    return end;
-  }
-  let pos = start;
-  for (const k of n.kids) {
-    pos = walkTree(k, pos, visit);
-  }
-  visit(n, start, pos);
-  return pos;
+    if (n.kids === null) {
+        const end = start + (n.leaf?.length ?? 0);
+        visit(n, start, end);
+        return end;
+    }
+    let pos = start;
+    for (const k of n.kids)
+        pos = walkTree(k, pos, visit);
+    visit(n, start, pos);
+    return pos;
 }
 // ── Read: node → bytes ──────────────────────────────────────────────────
 /** Reconstruct a node's byte content from the DAG, up to `maxLen` bytes. */
 export function read(ctx, id, maxLen = ALL) {
-  return ctx.store.bytesPrefix(id, maxLen);
+    return ctx.store.bytesPrefix(id, maxLen);
 }

package/dist/src/mind/rationale.d.ts

@@ -7,25 +7,25 @@ import type { Vec } from "../vec.js";
  *  the ones that carry meaning for what it did.  `text` is always present (the
  *  human-readable rendering); the rest is provenance a debugger can lean on. */
 export interface RationaleItem {
-  /** Human-readable rendering — decoded text for a byte span, else a label like
-   *  "‹none›" or an operator name.  Always set, so a step always reads. */
-  text: string;
-  /** The graph node this element is, or resolved to, when known — the handle to
-   *  point back at the exact stored fact in the content-addressed DAG. */
-  node?: number;
-  /** The `[start, end)` span this element occupies in its step's frame of
-   *  reference (usually the query or the answer being composed). */
-  span?: [number, number];
-  /** The resonance / cosine score that selected this element, when it was chosen
-   *  by similarity rather than by exact structure. */
-  score?: number;
-  /** A short role tag — "query", "leaf", "form", "hit", "connector", "answer",
-   *  … — naming what KIND of element this is within the step. */
-  role?: string;
-  /** The gist vector, only when the element fundamentally IS a vector and a
-   *  caller asked to carry it (off by default — a D-float array per item would
-   *  bury the reasoning it is meant to explain). */
-  v?: Vec;
+    /** Human-readable rendering — decoded text for a byte span, else a label like
+     *  "‹none›" or an operator name.  Always set, so a step always reads. */
+    text: string;
+    /** The graph node this element is, or resolved to, when known — the handle to
+     *  point back at the exact stored fact in the content-addressed DAG. */
+    node?: number;
+    /** The `[start, end)` span this element occupies in its step's frame of
+     *  reference (usually the query or the answer being composed). */
+    span?: [number, number];
+    /** The resonance / cosine score that selected this element, when it was chosen
+     *  by similarity rather than by exact structure. */
+    score?: number;
+    /** A short role tag — "query", "leaf", "form", "hit", "connector", "answer",
+     *  … — naming what KIND of element this is within the step. */
+    role?: string;
+    /** The gist vector, only when the element fundamentally IS a vector and a
+     *  caller asked to carry it (off by default — a D-float array per item would
+     *  bury the reasoning it is meant to explain). */
+    v?: Vec;
 }
 /** A single completed act of inference — one mechanism, run once.
  *
@@ -35,30 +35,30 @@ export interface RationaleItem {
  *  parent's `index` is always lower than its children's, and the two orderings
  *  together give a valid topological reading of the dependency graph. */
 export interface RationaleStep {
-  /** This step's index, assigned when the mechanism was ENTERED — a strict,
-   *  incremental ordering over the whole inference. */
-  index: number;
-  /** The mechanism and its enclosing mechanisms, outermost → innermost, e.g.
-   *  `["respond", "think", "recognise"]`.  The last entry is this step; the
-   *  prefix is the nest of sub-mechanisms it ran inside. */
-  mechanism: string[];
-  /** The enclosing mechanism's step index, or -1 at the root — the NESTING edge
-   *  of the dependency graph (which step this one is a part of). */
-  parent: number;
-  /** The earlier steps whose OUTPUTS became this step's inputs — the DATA-FLOW
-   *  edges of the dependency graph.  Defaults to the previous sibling (the step
-   *  run just before this one inside the same mechanism), or the parent when
-   *  this is the first sub-step; a mechanism that fuses several earlier results
-   *  names them all explicitly. */
-  dependsOn: number[];
-  /** The vector of elements handed to the mechanism (one or more). */
-  inputs: RationaleItem[];
-  /** The vector of elements the mechanism produced (one or more) — longer than
-   *  `inputs` when it decomposed, shorter when it combined. */
-  outputs: RationaleItem[];
-  /** A one-line, human account of what the mechanism did and why — the sentence
-   *  that turns the data into an explanation. */
-  note?: string;
+    /** This step's index, assigned when the mechanism was ENTERED — a strict,
+     *  incremental ordering over the whole inference. */
+    index: number;
+    /** The mechanism and its enclosing mechanisms, outermost → innermost, e.g.
+     *  `["respond", "think", "recognise"]`.  The last entry is this step; the
+     *  prefix is the nest of sub-mechanisms it ran inside. */
+    mechanism: string[];
+    /** The enclosing mechanism's step index, or -1 at the root — the NESTING edge
+     *  of the dependency graph (which step this one is a part of). */
+    parent: number;
+    /** The earlier steps whose OUTPUTS became this step's inputs — the DATA-FLOW
+     *  edges of the dependency graph.  Defaults to the previous sibling (the step
+     *  run just before this one inside the same mechanism), or the parent when
+     *  this is the first sub-step; a mechanism that fuses several earlier results
+     *  names them all explicitly. */
+    dependsOn: number[];
+    /** The vector of elements handed to the mechanism (one or more). */
+    inputs: RationaleItem[];
+    /** The vector of elements the mechanism produced (one or more) — longer than
+     *  `inputs` when it decomposed, shorter when it combined. */
+    outputs: RationaleItem[];
+    /** A one-line, human account of what the mechanism did and why — the sentence
+     *  that turns the data into an explanation. */
+    note?: string;
 }
 /** The callback {@link Mind.respond} / {@link Mind.respondText} accept.  It is
  *  invoked once per completed step, AS the inference unfolds — never batched at
@@ -70,29 +70,23 @@ export declare function decodeText(bytes: Uint8Array): string;
 /** The `[start, end)` gaps of `[0, queryLen)` NOT covered by `accounted` —
  *  the same union-of-spans reading think's grounding decider prices at PASS
  *  per byte, exposed here so a mechanism can turn it into a human label. */
-export declare function unexplainedSpans(
-  queryLen: number,
-  accounted: ReadonlyArray<[number, number]>,
-): Array<[number, number]>;
+export declare function unexplainedSpans(queryLen: number, accounted: ReadonlyArray<[number, number]>): Array<[number, number]>;
 /** A human-readable label for the query bytes a mechanism's `accounted`
  *  spans leave unexplained — purely diagnostic (Task 2's negative evidence):
  *  it never changes a candidate's weight, only what the rationale trace
  *  says the mechanism left on the table. `""` when nothing is unexplained. */
-export declare function unexplainedLabel(
-  query: Uint8Array,
-  accounted: ReadonlyArray<[number, number]>,
-): string;
+export declare function unexplainedLabel(query: Uint8Array, accounted: ReadonlyArray<[number, number]>): string;
 /** An open mechanism — the handle {@link Rationale.enter} returns.  Hold it for
  *  the duration of the mechanism and call {@link Scope.done} with the outputs
  *  when it finishes; that emits the step and pops the nesting. */
 export interface Scope {
-  /** The step index reserved for this mechanism at entry — pass it as an
-   *  explicit dependency of a later step that consumes this one's output. */
-  readonly index: number;
-  /** Close the mechanism: emit its step with these outputs and pop it off the
-   *  nesting stack.  Idempotent — a second call is ignored, so a `finally` that
-   *  closes after an early return is safe. */
-  done(outputs: RationaleItem[], note?: string): void;
+    /** The step index reserved for this mechanism at entry — pass it as an
+     *  explicit dependency of a later step that consumes this one's output. */
+    readonly index: number;
+    /** Close the mechanism: emit its step with these outputs and pop it off the
+     *  nesting stack.  Idempotent — a second call is ignored, so a `finally` that
+     *  closes after an early return is safe. */
+    done(outputs: RationaleItem[], note?: string): void;
 }
 /** The live tracer: a stack of open mechanisms over one {@link Mind.respond}.
  *
@@ -103,44 +97,38 @@ export interface Scope {
  *  sub-steps) is the two fused.  The tracer never branches the control flow; it
  *  only records it. */
 export declare class Rationale {
-  private readonly sink;
-  private next;
-  /** Open mechanisms, outermost first.  Each frame remembers the last child it
-   *  has spawned so the next sibling can default its data-flow edge to it. */
-  private readonly stack;
-  /** The most recent step index emitted under each mechanism name — the handle
-   *  a later step uses to name an EARLIER mechanism as its data-flow producer
-   *  (e.g. cover depends on the latest recognise / computeExtensions).  One tracer is
-   *  built per response and inference is sequential, so "most recent" is exactly
-   *  "the one that produced the inputs I am about to consume". */
-  private readonly lastByName;
-  constructor(sink: InspectRationale);
-  /** The index of the most recent step with this mechanism name, or undefined if
-   *  none has run.  Used to wire an explicit producer edge into {@link
-   *  Scope.done} / {@link step}'s `deps`. */
-  lastIndex(name: string): number | undefined;
-  /** The mechanism names currently open, outermost → innermost. */
-  private path;
-  /** The default data-flow edge for a step entering now: the previous sibling
-   *  inside the current mechanism, else the enclosing mechanism, else nothing
-   *  (the root).  An explicit `deps` overrides this. */
-  private defaultDeps;
-  /** Reserve this step's index and register it as the current mechanism's most
-   *  recent child (so the NEXT sibling chains to it) and as the most recent step
-   *  of its own NAME (so a later mechanism can name it as a producer). */
-  private reserve;
-  private emit;
-  /** Enter a mechanism that has sub-steps.  Captures its inputs and the nesting
-   *  now; the matching {@link Scope.done} supplies the outputs when it finishes.
-   *  `deps` overrides the default data-flow edge (previous sibling / parent). */
-  enter(name: string, inputs: RationaleItem[], deps?: number[]): Scope;
-  /** Record a mechanism that has no sub-steps — its inputs and outputs are both
-   *  known at the call site.  Returns its index, for a later step to depend on. */
-  step(
-    name: string,
-    inputs: RationaleItem[],
-    outputs: RationaleItem[],
-    note?: string,
-    deps?: number[],
-  ): number;
+    private readonly sink;
+    private next;
+    /** Open mechanisms, outermost first.  Each frame remembers the last child it
+     *  has spawned so the next sibling can default its data-flow edge to it. */
+    private readonly stack;
+    /** The most recent step index emitted under each mechanism name — the handle
+     *  a later step uses to name an EARLIER mechanism as its data-flow producer
+     *  (e.g. cover depends on the latest recognise / computeExtensions).  One tracer is
+     *  built per response and inference is sequential, so "most recent" is exactly
+     *  "the one that produced the inputs I am about to consume". */
+    private readonly lastByName;
+    constructor(sink: InspectRationale);
+    /** The index of the most recent step with this mechanism name, or undefined if
+     *  none has run.  Used to wire an explicit producer edge into {@link
+     *  Scope.done} / {@link step}'s `deps`. */
+    lastIndex(name: string): number | undefined;
+    /** The mechanism names currently open, outermost → innermost. */
+    private path;
+    /** The default data-flow edge for a step entering now: the previous sibling
+     *  inside the current mechanism, else the enclosing mechanism, else nothing
+     *  (the root).  An explicit `deps` overrides this. */
+    private defaultDeps;
+    /** Reserve this step's index and register it as the current mechanism's most
+     *  recent child (so the NEXT sibling chains to it) and as the most recent step
+     *  of its own NAME (so a later mechanism can name it as a producer). */
+    private reserve;
+    private emit;
+    /** Enter a mechanism that has sub-steps.  Captures its inputs and the nesting
+     *  now; the matching {@link Scope.done} supplies the outputs when it finishes.
+     *  `deps` overrides the default data-flow edge (previous sibling / parent). */
+    enter(name: string, inputs: RationaleItem[], deps?: number[]): Scope;
+    /** Record a mechanism that has no sub-steps — its inputs and outputs are both
+     *  known at the call site.  Returns its index, for a later step to depend on. */
+    step(name: string, inputs: RationaleItem[], outputs: RationaleItem[], note?: string, deps?: number[]): number;
 }