@hviana/sema 0.1.4 → 0.1.5

package/dist/src/mind/primitives.js

@@ -2,7 +2,13 @@
 //
 //   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,
@@ -10,45 +16,46 @@ import { ALL } from "./types.js";
  *  (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;
+  // 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;
-                const tree = bytesToTree(ctx.space, ctx.alphabet, bytes);
-                memo.set(key, tree);
-                return tree;
-            }
-            return bytesToTree(ctx.space, ctx.alphabet, bytes);
+  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;
         }
-        return bytesToTree(ctx.space, ctx.alphabet, bytes, leafAt, lookup);
+        const tree = bytesToTree(ctx.space, ctx.alphabet, bytes);
+        memo.set(key, tree);
+        return tree;
+      }
+      return bytesToTree(ctx.space, ctx.alphabet, bytes);
     }
-    if (Array.isArray(input)) {
-        return gridToTree(ctx.space, ctx.alphabet, stackGrids(input));
-    }
-    return gridToTree(ctx.space, ctx.alphabet, 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);
 }
 /** The DEPOSIT-shaped perceive: the PLAIN fold (bit-identical to inference
  *  perception — that structural train/inference agreement is load-bearing
@@ -59,45 +66,53 @@ 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();
-        }
-        ctx._depositTrees.set(latin1Key(bytes), pyramid);
-        ctx._depositLens.add(bytes.length);
+  }
+  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();
     }
-    return tree;
+    ctx._depositTrees.set(latin1Key(bytes), pyramid);
+    ctx._depositLens.add(bytes.length);
+  }
+  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'
@@ -105,35 +120,37 @@ 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 };
+  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);
     }
-    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);
-    return { end: pos, node };
+    pos = r.end;
+  }
+  const node = known ? ctx.store.findBranch(kids) : null;
+  visit?.(n, start, pos, node);
+  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.
@@ -144,19 +161,20 @@ 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,23 +70,29 @@ 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}.
  *
@@ -97,38 +103,44 @@ 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;
 }