@hviana/sema 0.1.5 → 0.1.7

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

@@ -3,16 +3,10 @@ import { type PipelineMechanism } from "./pipeline-mechanism.js";
 export { resolveConcepts, resolveConnectors } from "./mechanisms/cover.js";
 export { aluToMechanism } from "./mechanisms/alu.js";
 export declare const defaultMechanisms: PipelineMechanism[];
-export type Provenance =
-  | "cast"
-  | "join"
-  | "cover"
-  | "extract"
-  | "recall"
-  | "recall-echo";
+export type Provenance = "cast" | "join" | "cover" | "extract" | "recall" | "recall-echo";
 export interface Thought {
-  bytes: Uint8Array;
-  provenance: Provenance;
+    bytes: Uint8Array;
+    provenance: Provenance;
 }
 /** Think: a single lightest-derivation exploration of the Sema graph.
  *
@@ -23,8 +17,4 @@ export interface Thought {
  *       cost ladder; the lightest grounding derivation wins.
  *    3. Post-grounding — diagnostics (narrowDecision, thinGrounding),
  *       reasoning (multi-hop), fusion (multi-topic). */
-export declare function think(
-  ctx: MindContext,
-  query: Uint8Array,
-  mechs?: readonly PipelineMechanism[],
-): Promise<Thought | null>;
+export declare function think(ctx: MindContext, query: Uint8Array, mechs?: readonly PipelineMechanism[]): Promise<Thought | null>;

package/dist/src/mind/pipeline.js

@@ -26,13 +26,12 @@ export { resolveConcepts, resolveConnectors } from "./mechanisms/cover.js";
 export { aluToMechanism } from "./mechanisms/alu.js";
 // ── Extension dispatch (pre-loop parse) ─────────────────────────────────────
 async function collectComputed(mechanisms, query) {
-  const out = [];
-  for (const m of mechanisms) {
-    if (m.parse) {
-      out.push(...await m.parse(query));
+    const out = [];
+    for (const m of mechanisms) {
+        if (m.parse)
+            out.push(...await m.parse(query));
     }
-  }
-  return out;
+    return out;
 }
 // ── Built-in mechanisms ─────────────────────────────────────────────────────
 // ORDER MATTERS, but only through the uniform floor/worthRunning pruning —
@@ -46,11 +45,11 @@ async function collectComputed(mechanisms, query) {
 // order is also the tie-break priority: cover, cast, confluence, extraction,
 // recall.
 export const defaultMechanisms = [
-  coverMechanism,
-  castMechanism,
-  confluenceMechanism,
-  extractionMechanism,
-  recallMechanism,
+    coverMechanism,
+    castMechanism,
+    confluenceMechanism,
+    extractionMechanism,
+    recallMechanism,
 ];
 /** Think: a single lightest-derivation exploration of the Sema graph.
  *
@@ -62,188 +61,125 @@ export const defaultMechanisms = [
  *    3. Post-grounding — diagnostics (narrowDecision, thinGrounding),
  *       reasoning (multi-hop), fusion (multi-topic). */
 export async function think(ctx, query, mechs) {
-  if (query.length === 0) {
-    return null;
-  }
-  ctx._edgeGuide = gistOf(ctx, query);
-  ctx._edgeChoice.clear();
-  const t = ctx.trace?.enter("think", [rItem(query, "query")]);
-  const done = (answer, note) => {
-    t?.done(
-      answer
-        ? [rItem(answer, "answer", resolve(ctx, answer) ?? undefined)]
-        : [],
-      note,
-    );
-    return answer;
-  };
-  // ── Pre-computation ──────────────────────────────────────────────────
-  const mechanisms = mechs ?? defaultMechanisms;
-  const rec = recognise(ctx, query);
-  // Phase 1: collect computed spans from mechanisms that implement parse()
-  const computed = await collectComputed(mechanisms, query);
-  if (computed.length > 0) {
-    ctx.trace?.step(
-      "computeExtensions",
-      [rItem(query, "query")],
-      computed.map((u) =>
-        rItem(query.subarray(u.i, u.j), "operand", undefined, [u.i, u.j])
-      ),
-      `extensions recognised and evaluated ${computed.length} computation(s)`,
-    );
-    for (const u of computed) {
-      ctx.trace?.step(
-        "evalComputation",
-        [rItem(query.subarray(u.i, u.j), "expression", undefined, [u.i, u.j])],
-        [rItem(u.bytes, "result", resolve(ctx, u.bytes) ?? undefined)],
-        "evaluate the recognised operation to its authoritative result",
-      );
-    }
-  }
-  // Phase 2: the shared pre-computation container.  Eager fields only
-  // (recognition, computed spans, guide) — every expensive analysis
-  // (consensus climb, weave, span-shape classification) is a lazily-cached
-  // method on Precomputed, first-touched by whichever mechanism's floor
-  // survives its cheap gates and the worthRunning check.  A query no
-  // mechanism climbs for (e.g. one an extension decided) never climbs.
-  const pre = new Precomputed(ctx, query, rec, computed, ctx._edgeGuide);
-  const grade = (w) => Math.floor(w / STEP);
-  const unaccounted = (spans) =>
-    unexplainedSpans(query.length, spans)
-      .reduce((sum, [s, e]) => sum + (e - s), 0);
-  const weigh = (accounted, moves) => moves + PASS * unaccounted(accounted);
-  const candidates = [];
-  let best = null;
-  const consider = (c) => {
-    if (c.bytes.length === 0) {
-      return;
-    }
-    candidates.push(c);
-    if (best === null || grade(c.weight) < grade(best.weight)) {
-      best = c;
-    }
-  };
-  const worthRunning = (floor) =>
-    best === null || grade(floor) < grade(best.weight);
-  // Phase 3: grounding loop
-  for (const mech of mechanisms) {
-    const floor = await mech.floor(ctx, query, pre, worthRunning);
-    if (floor === null) {
-      ctx.trace?.step(
-        "skipMechanism",
-        [],
-        [],
-        `${mech.name} skipped — structural precondition failed`,
-      );
-      continue;
-    }
-    if (!worthRunning(floor)) {
-      ctx.trace?.step(
-        "skipMechanism",
-        [],
-        [],
-        `${mech.name} skipped — floor ${floor} cannot beat incumbent (grade ${
-          grade(best.weight)
-        })`,
-      );
-      continue;
-    }
-    const results = await mech.run(ctx, query, pre);
-    for (const r of results) {
-      const weight = r.weight ?? weigh(r.accounted, r.moves);
-      consider({
-        bytes: r.bytes,
-        provenance: r.provenance ?? mech.provenance,
-        weight,
-        used: r.used,
-        accounted: r.accounted,
-        unexplained: r.unexplained,
-      });
+    if (query.length === 0)
+        return null;
+    ctx._edgeGuide = gistOf(ctx, query);
+    ctx._edgeChoice.clear();
+    const t = ctx.trace?.enter("think", [rItem(query, "query")]);
+    const done = (answer, note) => {
+        t?.done(answer
+            ? [rItem(answer, "answer", resolve(ctx, answer) ?? undefined)]
+            : [], note);
+        return answer;
+    };
+    // ── Pre-computation ──────────────────────────────────────────────────
+    const mechanisms = mechs ?? defaultMechanisms;
+    const rec = recognise(ctx, query);
+    // Phase 1: collect computed spans from mechanisms that implement parse()
+    const computed = await collectComputed(mechanisms, query);
+    if (computed.length > 0) {
+        ctx.trace?.step("computeExtensions", [rItem(query, "query")], computed.map((u) => rItem(query.subarray(u.i, u.j), "operand", undefined, [u.i, u.j])), `extensions recognised and evaluated ${computed.length} computation(s)`);
+        for (const u of computed) {
+            ctx.trace?.step("evalComputation", [rItem(query.subarray(u.i, u.j), "expression", undefined, [u.i, u.j])], [rItem(u.bytes, "result", resolve(ctx, u.bytes) ?? undefined)], "evaluate the recognised operation to its authoritative result");
+        }
     }
-  }
-  // (TS cannot see the closure assignments into `best` and narrows it to its
-  // initial null, so the read-back needs the assertion.)
-  const decided = best;
-  if (candidates.length > 1) {
-    ctx.trace?.step(
-      "decideGrounding",
-      candidates.map((c) =>
-        rItem(
-          c.bytes,
-          `${c.provenance} (weight ${c.weight.toFixed(3)}${
-            c.unexplained ? `, unexplained: "${c.unexplained}"` : ""
-          })`,
-        )
-      ),
-      decided ? [rItem(decided.bytes, decided.provenance)] : [],
-      "the lightest grounding derivation wins — every mechanism weighed in the one cost ladder",
-    );
-    if (decided !== null) {
-      let runnerUp = null;
-      for (const c of candidates) {
-        if (c === decided) {
-          continue;
+    // Phase 2: the shared pre-computation container.  Eager fields only
+    // (recognition, computed spans, guide) — every expensive analysis
+    // (consensus climb, weave, span-shape classification) is a lazily-cached
+    // method on Precomputed, first-touched by whichever mechanism's floor
+    // survives its cheap gates and the worthRunning check.  A query no
+    // mechanism climbs for (e.g. one an extension decided) never climbs.
+    const pre = new Precomputed(ctx, query, rec, computed, ctx._edgeGuide);
+    const grade = (w) => Math.floor(w / STEP);
+    const unaccounted = (spans) => unexplainedSpans(query.length, spans)
+        .reduce((sum, [s, e]) => sum + (e - s), 0);
+    const weigh = (accounted, moves) => moves + PASS * unaccounted(accounted);
+    const candidates = [];
+    let best = null;
+    const consider = (c) => {
+        if (c.bytes.length === 0)
+            return;
+        candidates.push(c);
+        if (best === null || grade(c.weight) < grade(best.weight))
+            best = c;
+    };
+    const worthRunning = (floor) => best === null || grade(floor) < grade(best.weight);
+    // Phase 3: grounding loop
+    for (const mech of mechanisms) {
+        const floor = await mech.floor(ctx, query, pre, worthRunning);
+        if (floor === null) {
+            ctx.trace?.step("skipMechanism", [], [], `${mech.name} skipped — structural precondition failed`);
+            continue;
+        }
+        if (!worthRunning(floor)) {
+            ctx.trace?.step("skipMechanism", [], [], `${mech.name} skipped — floor ${floor} cannot beat incumbent (grade ${grade(best.weight)})`);
+            continue;
         }
-        if (runnerUp === null || grade(c.weight) < grade(runnerUp.weight)) {
-          runnerUp = c;
+        const results = await mech.run(ctx, query, pre);
+        for (const r of results) {
+            const weight = r.weight ?? weigh(r.accounted, r.moves);
+            consider({
+                bytes: r.bytes,
+                provenance: r.provenance ?? mech.provenance,
+                weight,
+                used: r.used,
+                accounted: r.accounted,
+                unexplained: r.unexplained,
+            });
         }
-      }
-      if (runnerUp !== null) {
-        const margin = grade(runnerUp.weight) - grade(decided.weight);
-        if (margin <= 1) {
-          ctx.trace?.step(
-            "narrowDecision",
-            [
-              rItem(
-                decided.bytes,
-                `${decided.provenance} (weight ${decided.weight.toFixed(3)})`,
-              ),
-            ],
-            [
-              rItem(
-                runnerUp.bytes,
-                `${runnerUp.provenance} (weight ${runnerUp.weight.toFixed(3)})`,
-              ),
-            ],
-            `margin ${margin} grade-unit(s) — the decision could change with one more training fact`,
-          );
+    }
+    // (TS cannot see the closure assignments into `best` and narrows it to its
+    // initial null, so the read-back needs the assertion.)
+    const decided = best;
+    if (candidates.length > 1) {
+        ctx.trace?.step("decideGrounding", candidates.map((c) => rItem(c.bytes, `${c.provenance} (weight ${c.weight.toFixed(3)}${c.unexplained ? `, unexplained: "${c.unexplained}"` : ""})`)), decided ? [rItem(decided.bytes, decided.provenance)] : [], "the lightest grounding derivation wins — every mechanism weighed in the one cost ladder");
+        if (decided !== null) {
+            let runnerUp = null;
+            for (const c of candidates) {
+                if (c === decided)
+                    continue;
+                if (runnerUp === null || grade(c.weight) < grade(runnerUp.weight)) {
+                    runnerUp = c;
+                }
+            }
+            if (runnerUp !== null) {
+                const margin = grade(runnerUp.weight) - grade(decided.weight);
+                if (margin <= 1) {
+                    ctx.trace?.step("narrowDecision", [
+                        rItem(decided.bytes, `${decided.provenance} (weight ${decided.weight.toFixed(3)})`),
+                    ], [
+                        rItem(runnerUp.bytes, `${runnerUp.provenance} (weight ${runnerUp.weight.toFixed(3)})`),
+                    ], `margin ${margin} grade-unit(s) — the decision could change with one more training fact`);
+                }
+            }
         }
-      }
     }
-  }
-  if (decided === null) {
-    done(null, "no mechanism grounded an answer");
-    return null;
-  }
-  // Honesty density
-  {
-    const covered = query.length - unaccounted(decided.accounted);
-    const density = query.length > 0 ? covered / query.length : 1;
-    const thinBar = 1 / ctx.space.maxGroup;
-    if (density < thinBar) {
-      ctx.trace?.step(
-        "thinGrounding",
-        [rItem(decided.bytes, decided.provenance)],
-        [],
-        `grounded but thin — density ${density.toFixed(3)} is below 1/W (${
-          thinBar.toFixed(3)
-        })`,
-      );
+    if (decided === null) {
+        done(null, "no mechanism grounded an answer");
+        return null;
+    }
+    // Honesty density
+    {
+        const covered = query.length - unaccounted(decided.accounted);
+        const density = query.length > 0 ? covered / query.length : 1;
+        const thinBar = 1 / ctx.space.maxGroup;
+        if (density < thinBar) {
+            ctx.trace?.step("thinGrounding", [rItem(decided.bytes, decided.provenance)], [], `grounded but thin — density ${density.toFixed(3)} is below 1/W (${thinBar.toFixed(3)})`);
+        }
     }
-  }
-  const answer = decided.bytes;
-  const provenance = decided.provenance;
-  const castUsed = decided.used ?? new Set();
-  // ── Post-grounding, gated by provenance ──────────────────────────────
-  const preConsumed = provenance === "cast" || provenance === "join"
-    ? castUsed
-    : provenance === "recall" || provenance === "recall-echo"
-    ? new Set()
-    : new Set(recognise(ctx, answer).sites.map((s) => s.payload));
-  const reasoned = await reason(ctx, query, answer, preConsumed, pre);
-  const fused = provenance === "recall" || provenance === "recall-echo"
-    ? await fuseAttention(ctx, query, reasoned, pre)
-    : reasoned;
-  done(fused, "grounded, reasoned forward, fused across points of attention");
-  return { bytes: fused, provenance };
+    const answer = decided.bytes;
+    const provenance = decided.provenance;
+    const castUsed = decided.used ?? new Set();
+    // ── Post-grounding, gated by provenance ──────────────────────────────
+    const preConsumed = provenance === "cast" || provenance === "join"
+        ? castUsed
+        : provenance === "recall" || provenance === "recall-echo"
+            ? new Set()
+            : new Set(recognise(ctx, answer).sites.map((s) => s.payload));
+    const reasoned = await reason(ctx, query, answer, preConsumed, pre);
+    const fused = provenance === "recall" || provenance === "recall-echo"
+        ? await fuseAttention(ctx, query, reasoned, pre)
+        : reasoned;
+    done(fused, "grounded, reasoned forward, fused across points of attention");
+    return { bytes: fused, provenance };
 }

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

@@ -1,14 +1,20 @@
 import { Vec } from "../vec.js";
 import { Sema } from "../sema.js";
 import type { Input, MindContext } from "./types.js";
+/** 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. */
+export declare function latin1Key(bytes: Uint8Array): string;
 /** Perceive input into a content-defined tree (the river fold).
- *  Deterministic — identical bytes always produce an identical tree. */
-export declare function perceive(
-  ctx: MindContext,
-  input: Input,
-  leafAt?: (i: number) => number | null,
-  lookup?: (ids: number[]) => number | null,
-): Sema;
+ *  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 declare function perceive(ctx: MindContext, input: Input, leafAt?: (i: number) => number | null, lookup?: (ids: number[]) => number | null, boundaries?: readonly number[]): Sema;
 /** The DEPOSIT-shaped perceive: the PLAIN fold (bit-identical to inference
  *  perception — that structural train/inference agreement is load-bearing
  *  for exact recall), computed INCREMENTALLY via the fold's level pyramid
@@ -17,10 +23,7 @@ export declare function perceive(
  *  (ctx._depositTrees), and this deposit refolds only the right edge of
  *  each level — O(turn) instead of O(context) per turn.  Purely a cache:
  *  the produced tree never depends on cache state. */
-export declare function perceiveDeposit(
-  ctx: MindContext,
-  bytes: Uint8Array,
-): Sema;
+export declare function perceiveDeposit(ctx: MindContext, bytes: Uint8Array): Sema;
 /** The raw bytes of an input — modality-neutral conversion. */
 export declare function inputBytes(ctx: MindContext, input: Input): Uint8Array;
 /** Convenience: the gist vector of a byte span. */
@@ -30,22 +33,14 @@ export declare function gistOf(ctx: MindContext, bytes: Uint8Array): Vec;
  *  ids (null the moment any child is unknown).  `visit`, when given, sees each
  *  node with its byte span and resolved id.  Returns the node's byte end and
  *  resolved id. */
-export declare function foldTree(
-  ctx: MindContext,
-  n: Sema,
-  start: number,
-  visit?: (n: Sema, start: number, end: number, node: number | null) => void,
-): {
-  end: number;
-  node: number | null;
+export declare function foldTree(ctx: MindContext, n: Sema, start: number, visit?: (n: Sema, start: number, end: number, node: number | null) => void): {
+    end: number;
+    node: number | null;
 };
 /** 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 declare function resolve(
-  ctx: MindContext,
-  bytes: Uint8Array,
-): number | null;
+export declare function resolve(ctx: MindContext, bytes: Uint8Array): number | null;
 /** Walk a perceived tree in POST-ORDER with byte offsets — children before
  *  their parent, `visit(node, start, end)` for every node including leaves.
  *  Returns the byte end.  The one shared traversal the offset-carrying tree
@@ -54,14 +49,6 @@ export declare function resolve(
  *  re-derive the offset bookkeeping.  (recognition.segment keeps its own
  *  walk: its flush semantics need PRE-order decisions at leaf-parents, which
  *  a post-order visitor cannot express.) */
-export declare function walkTree(
-  n: Sema,
-  start: number,
-  visit: (node: Sema, start: number, end: number) => void,
-): number;
+export declare function walkTree(n: Sema, start: number, visit: (node: Sema, start: number, end: number) => void): number;
 /** Reconstruct a node's byte content from the DAG, up to `maxLen` bytes. */
-export declare function read(
-  ctx: MindContext,
-  id: number,
-  maxLen?: number,
-): Uint8Array;
+export declare function read(ctx: MindContext, id: number, maxLen?: number): Uint8Array;