@hviana/sema 0.2.4 → 0.2.5

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

@@ -3,3 +3,5 @@ export type { Input, Response } from "./mind.js";
 export type { ComputedSpan, ExtensionHost } from "./mind.js";
 export type { MechanismResult, PipelineMechanism, Precomputed, } from "./pipeline-mechanism.js";
 export type { InspectRationale, RationaleItem, RationaleStep, } from "./rationale.js";
+export type { AnchorRejectionReason, ClimbConsensusData, ConsensusAnchorTrace, ConsensusReachTrace, ConsensusRegionTrace, CrossRegionTier, JunctionVoteTrace, RegionOutcome, } from "./attention.js";
+export type { AncestorReach, AttentionRead, SaturationReason, SaturationStop, } from "./types.js";

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

@@ -1,3 +1,4 @@
+import type { Hit } from "../store.js";
 import type { MindContext } from "./types.js";
 export interface Junction {
     /** The node whose learnt bytes evidence this junction (a container form,
@@ -6,6 +7,34 @@ export interface Junction {
     /** The bytes that belong between left and right. */
     interior: Uint8Array;
 }
+/** Which relaxation produced a {@link SynonymJunction}: one side replaced by
+ *  a distributional halo sibling (`single-synonym`), or both (`double-
+ *  synonym`) — the two remaining rungs of the graded ladder below exact DAG
+ *  containment (see the module doc atop {@link junctionSynonyms}). */
+export type SynonymJunctionTier = "single-synonym" | "double-synonym";
+export interface SynonymJunction extends Junction {
+    tier: SynonymJunctionTier;
+    /** Sibling score for a single-synonym junction; min(left, right) sibling
+     *  score for a double-synonym junction. */
+    confidence: number;
+}
+/** The exact node ids and halo siblings resolved for one junction call's two
+ *  sides — computed ONCE and reused by every ladder rung that needs them
+ *  (junctionSynonyms' two tiers, and the structural-resonance tier beyond
+ *  it).  A failed synonym junction means only "no common DAG container was
+ *  proven" — it does NOT mean the loaded siblings stop being useful. */
+export interface JunctionSynonymSides {
+    leftId: number | null;
+    rightId: number | null;
+    leftSiblings: Hit[];
+    rightSiblings: Hit[];
+}
+/** Resolve `left`/`right` to their exact node ids (when known) and load each
+ *  resolved side's halo siblings once — deterministic (haloSiblings already
+ *  ranks nearest-first) and shared by every ladder rung that consults
+ *  siblings, so no ladder rung repeats a halo ANN query the previous one
+ *  already paid for. */
+export declare function loadJunctionSynonymSides(ctx: MindContext, left: Uint8Array, right: Uint8Array): Promise<JunctionSynonymSides>;
 /** Seed node ids to ascend from for one side of a junction: the side's own
  *  node when it is a stored form, plus — when the node has no structural
  *  parents — its canonical window ids.  A non-W-aligned node may have no
@@ -92,4 +121,4 @@ export declare function junctionContainers(ctx: MindContext, left: Uint8Array, r
  *  cost is bounded at √N·W pops total regardless of how many siblings are
  *  tried.  A sibling whose bytes exceed `maxInterior` is skipped (it
  *  cannot be junction-sized). */
-export declare function junctionSynonyms(ctx: MindContext, left: Uint8Array, right: Uint8Array, maxInterior: number, unordered?: boolean): Promise<Junction[]>;
+export declare function junctionSynonyms(ctx: MindContext, left: Uint8Array, right: Uint8Array, maxInterior: number, unordered?: boolean, sides?: JunctionSynonymSides): Promise<SynonymJunction[]>;

package/dist/src/mind/junction.js

@@ -16,6 +16,20 @@ import { windowIds } from "./canonical.js";
 import { hubBound } from "./traverse.js";
 import { haloSiblings } from "./match.js";
 import { indexOf } from "../bytes.js";
+/** Resolve `left`/`right` to their exact node ids (when known) and load each
+ *  resolved side's halo siblings once — deterministic (haloSiblings already
+ *  ranks nearest-first) and shared by every ladder rung that consults
+ *  siblings, so no ladder rung repeats a halo ANN query the previous one
+ *  already paid for. */
+export async function loadJunctionSynonymSides(ctx, left, right) {
+    const leftId = resolve(ctx, left);
+    const rightId = resolve(ctx, right);
+    const leftSiblings = leftId !== null ? await haloSiblings(ctx, leftId) : [];
+    const rightSiblings = rightId !== null
+        ? await haloSiblings(ctx, rightId)
+        : [];
+    return { leftId, rightId, leftSiblings, rightSiblings };
+}
 /** Seed node ids to ascend from for one side of a junction: the side's own
  *  node when it is a stored form, plus — when the node has no structural
  *  parents — its canonical window ids.  A non-W-aligned node may have no
@@ -225,38 +239,79 @@ export function junctionContainers(ctx, left, right, maxContainer, unordered = f
  *  cost is bounded at √N·W pops total regardless of how many siblings are
  *  tried.  A sibling whose bytes exceed `maxInterior` is skipped (it
  *  cannot be junction-sized). */
-export async function junctionSynonyms(ctx, left, right, maxInterior, unordered = false) {
-    const out = [];
-    const lId = resolve(ctx, left);
-    const rId = resolve(ctx, right);
-    if (lId === null && rId === null)
-        return out;
-    const budget = { n: hubBound(ctx) * ctx.space.maxGroup };
+export async function junctionSynonyms(ctx, left, right, maxInterior, unordered = false, sides) {
+    const s = sides ?? await loadJunctionSynonymSides(ctx, left, right);
+    if (s.leftId === null && s.rightId === null)
+        return [];
+    // ── Tier 2.5a: single-synonym — one side replaced by a halo sibling ──────
+    // ONE shared expansion budget across BOTH directions of this tier.
+    const singleBudget = { n: hubBound(ctx) * ctx.space.maxGroup };
+    const singleOut = new Map();
+    const keepBest = (map, j, tier, confidence) => {
+        const prev = map.get(j.id);
+        if (prev === undefined || confidence > prev.confidence) {
+            map.set(j.id, { ...j, tier, confidence });
+        }
+    };
     // Left-side synonyms: containers of sibling+right.  `right`'s seeds are
     // FIXED across every sibling this loop tries.
-    if (lId !== null) {
+    if (s.leftId !== null) {
         const rightSeeds = junctionSeeds(ctx, right);
-        for (const sib of await haloSiblings(ctx, lId)) {
+        for (const sib of s.leftSiblings) {
             const sibBytes = read(ctx, sib.id, maxInterior + 1);
             if (sibBytes.length === 0 || sibBytes.length > maxInterior)
                 continue;
-            const containers = junctionContainersFrom(ctx, sibBytes, right, sibBytes.length + right.length + maxInterior, junctionSeeds(ctx, sibBytes), rightSeeds, budget, unordered);
-            for (const c of containers)
-                out.push(c);
+            const containers = junctionContainersFrom(ctx, sibBytes, right, sibBytes.length + right.length + maxInterior, junctionSeeds(ctx, sibBytes), rightSeeds, singleBudget, unordered);
+            for (const c of containers) {
+                keepBest(singleOut, c, "single-synonym", sib.score);
+            }
         }
     }
     // Right-side synonyms: containers of left+sibling.  `left`'s seeds are
     // likewise fixed across this loop.
-    if (rId !== null) {
+    if (s.rightId !== null) {
         const leftSeeds = junctionSeeds(ctx, left);
-        for (const sib of await haloSiblings(ctx, rId)) {
+        for (const sib of s.rightSiblings) {
             const sibBytes = read(ctx, sib.id, maxInterior + 1);
             if (sibBytes.length === 0 || sibBytes.length > maxInterior)
                 continue;
-            const containers = junctionContainersFrom(ctx, left, sibBytes, left.length + sibBytes.length + maxInterior, leftSeeds, junctionSeeds(ctx, sibBytes), budget, unordered);
-            for (const c of containers)
-                out.push(c);
+            const containers = junctionContainersFrom(ctx, left, sibBytes, left.length + sibBytes.length + maxInterior, leftSeeds, junctionSeeds(ctx, sibBytes), singleBudget, unordered);
+            for (const c of containers) {
+                keepBest(singleOut, c, "single-synonym", sib.score);
+            }
         }
     }
-    return out;
+    if (singleOut.size > 0)
+        return [...singleOut.values()];
+    // ── Tier 2.5b: double-synonym — BOTH sides replaced, tried only when
+    // single-synonym found NOTHING.  Every (leftSibling, rightSibling) pair,
+    // sorted deterministically, bounded to haloQueryK pairs total, ONE fresh
+    // shared budget for the whole tier. ─────────────────────────────────────
+    if (s.leftSiblings.length === 0 || s.rightSiblings.length === 0)
+        return [];
+    const pairs = [];
+    for (const l of s.leftSiblings) {
+        for (const r of s.rightSiblings) {
+            pairs.push({ l, r, confidence: Math.min(l.score, r.score) });
+        }
+    }
+    pairs.sort((a, b) => b.confidence - a.confidence ||
+        a.l.id - b.l.id ||
+        a.r.id - b.r.id);
+    const doubleOut = new Map();
+    const budget = { n: hubBound(ctx) * ctx.space.maxGroup };
+    const tries = Math.min(pairs.length, ctx.cfg.haloQueryK);
+    for (let i = 0; i < tries; i++) {
+        const { l, r, confidence } = pairs[i];
+        const lBytes = read(ctx, l.id, maxInterior + 1);
+        const rBytes = read(ctx, r.id, maxInterior + 1);
+        if (lBytes.length === 0 || lBytes.length > maxInterior ||
+            rBytes.length === 0 || rBytes.length > maxInterior)
+            continue;
+        const containers = junctionContainersFrom(ctx, lBytes, rBytes, lBytes.length + rBytes.length + maxInterior, junctionSeeds(ctx, lBytes), junctionSeeds(ctx, rBytes), budget, unordered);
+        for (const c of containers) {
+            keepBest(doubleOut, c, "double-synonym", confidence);
+        }
+    }
+    return [...doubleOut.values()];
 }

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

@@ -42,6 +42,8 @@ export interface Conversation {
     readonly id: number;
 }
 import type { AttentionRead, MindContext, Recognition } from "./types.js";
+export type { AnchorRejectionReason, ClimbConsensusData, ConsensusAnchorTrace, ConsensusReachTrace, ConsensusRegionTrace, CrossRegionTier, JunctionVoteTrace, RegionOutcome, } from "./attention.js";
+export type { AncestorReach, SaturationReason, SaturationStop, } from "./types.js";
 export interface MindOptions {
     seed?: number;
     recallQueryK?: number;

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

@@ -59,6 +59,11 @@ export interface RationaleStep {
     /** A one-line, human account of what the mechanism did and why — the sentence
      *  that turns the data into an explanation. */
     note?: string;
+    /** Optional structured payload — a mechanism-specific, plain-serialisable
+     *  shape (no Map/Set/vectors/mutable internals) that carries more than the
+     *  human-readable `note` can, for a debugger or downstream tool to consume
+     *  programmatically.  Never read by inference; purely additive. */
+    data?: unknown;
 }
 /** The callback {@link Mind.respond} / {@link Mind.respondText} accept.  It is
  *  invoked once per completed step, AS the inference unfolds — never batched at
@@ -86,7 +91,7 @@ export interface Scope {
     /** 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;
+    done(outputs: RationaleItem[], note?: string, data?: unknown): void;
 }
 /** The live tracer: a stack of open mechanisms over one {@link Mind.respond}.
  *
@@ -130,5 +135,5 @@ export declare class Rationale {
     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;
+    step(name: string, inputs: RationaleItem[], outputs: RationaleItem[], note?: string, deps?: number[], data?: unknown): number;
 }

package/dist/src/mind/rationale.js

@@ -109,7 +109,7 @@ export class Rationale {
         this.lastByName.set(name, index);
         return index;
     }
-    emit(index, mechanism, inputs, outputs, deps, note) {
+    emit(index, mechanism, inputs, outputs, deps, note, data) {
         this.sink({
             index,
             mechanism,
@@ -120,6 +120,7 @@ export class Rationale {
             inputs,
             outputs,
             note,
+            data,
         });
     }
     /** Enter a mechanism that has sub-steps.  Captures its inputs and the nesting
@@ -141,22 +142,22 @@ export class Rationale {
         };
         return {
             index,
-            done: (outputs, note) => {
+            done: (outputs, note, data) => {
                 if (closed)
                     return;
                 closed = true;
                 pop();
-                emit(index, mechanism, inputs, outputs, resolvedDeps, note);
+                emit(index, mechanism, inputs, outputs, resolvedDeps, note, data);
             },
         };
     }
     /** 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, inputs, outputs, note, deps) {
+    step(name, inputs, outputs, note, deps, data) {
         const mechanism = this.path(name);
         const resolvedDeps = deps ?? this.defaultDeps();
         const index = this.reserve(name);
-        this.emit(index, mechanism, inputs, outputs, resolvedDeps, note);
+        this.emit(index, mechanism, inputs, outputs, resolvedDeps, note, data);
         return index;
     }
 }

package/dist/src/mind/traverse.js

@@ -89,7 +89,22 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
     // is withdrawn.  On a small store the floor stays ≤ √N and the atom
     // climbs exactly as before, so single-letter facts keep working.
     if (id < 0 && atomIsHub(ctx, contextCount)) {
-        const reach = { roots: [], contextsReached: 0, saturated: true };
+        const bound0 = Math.ceil(Math.sqrt(Math.max(2, contextCount)));
+        const reach = {
+            roots: [],
+            contextsReached: 0,
+            saturated: true,
+            ...(ctx.trace
+                ? {
+                    saturation: {
+                        reason: "byte-atom-commonality",
+                        node: id,
+                        observed: atomReach(ctx, contextCount),
+                        limit: bound0,
+                    },
+                }
+                : {}),
+        };
         memo?.set(id, reach);
         return reach;
     }
@@ -98,6 +113,10 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
     const seen = new Set([id]);
     const ctxSeen = new Set();
     let saturated = false;
+    // Provenance of the FIRST decision that saturated this climb — allocated
+    // only when a trace is requested (see AncestorReach.saturation's doc); the
+    // climb itself never reads it back.
+    let satStop;
     // EXPAND-UNTIL-DECIDED: a reach is consumed either as a VOTE (which needs
     // contextsReached exactly, and only while ≤ √N — beyond that the region is
     // non-discriminative) or as an ABSTENTION (saturated — whose roots and
@@ -139,16 +158,46 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
             roots.push(x);
             if (hasNx)
                 ctxSeen.add(x);
-            if (pc > bound)
-                return false; // decided: ≥ pc > √N distinct contexts
+            if (pc > bound) {
+                // decided: ≥ pc > √N distinct contexts
+                if (ctx.trace) {
+                    satStop = {
+                        reason: "predecessor-fan-in",
+                        node: x,
+                        observed: pc,
+                        limit: bound,
+                    };
+                }
+                return false;
+            }
             for (const p of ctx.store.prevFirst(x, bound))
                 ctxSeen.add(p);
-            if (ctxSeen.size > bound)
-                return false; // decided
+            if (ctxSeen.size > bound) {
+                // decided
+                if (ctx.trace) {
+                    satStop = {
+                        reason: "distinct-context-limit",
+                        node: x,
+                        observed: ctxSeen.size,
+                        limit: bound,
+                    };
+                }
+                return false;
+            }
         }
         const parents = ctx.store.parentsFirst(x, bound + 1);
-        if (parents.length > bound)
-            return false; // decided: hub
+        if (parents.length > bound) {
+            // decided: hub
+            if (ctx.trace) {
+                satStop = {
+                    reason: "parent-fan-out",
+                    node: x,
+                    observed: parents.length,
+                    limit: bound,
+                };
+            }
+            return false;
+        }
         let fresh = 0;
         for (const p of parents) {
             if (!seen.has(p)) {
@@ -159,8 +208,18 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
         }
         if (fresh > 1) {
             lateral += fresh - 1;
-            if (lateral > bound)
-                return false; // decided: cone-wide hub
+            if (lateral > bound) {
+                // decided: cone-wide hub
+                if (ctx.trace) {
+                    satStop = {
+                        reason: "lateral-cone-limit",
+                        node: x,
+                        observed: lateral,
+                        limit: bound,
+                    };
+                }
+                return false;
+            }
         }
         return true;
     };
@@ -225,7 +284,12 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
             }
         }
     }
-    const reach = { roots, contextsReached: ctxSeen.size, saturated };
+    const reach = {
+        roots,
+        contextsReached: ctxSeen.size,
+        saturated,
+        ...(saturated && satStop ? { saturation: satStop } : {}),
+    };
     memo?.set(id, reach);
     return reach;
 }

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

@@ -133,11 +133,29 @@ export interface RegionVote {
      *  Defaults to 1 when absent. */
     absorbed?: number;
 }
+/** The structural gate that first decided an {@link edgeAncestors} climb was
+ *  saturated (an abstention, not a discriminative conclusion) — pure
+ *  instrumentation for {@link ClimbConsensusData}'s reach trace; it never
+ *  feeds back into the climb itself. */
+export type SaturationReason = "byte-atom-commonality" | "predecessor-fan-in" | "distinct-context-limit" | "parent-fan-out" | "lateral-cone-limit";
+/** One saturation stop's provenance: which reason fired, at which node, the
+ *  observed count against the bound that decided it. */
+export interface SaturationStop {
+    reason: SaturationReason;
+    node: number;
+    observed: number;
+    limit: number;
+}
 /** The edge-bearing contexts reached by climbing from a node, plus saturation info. */
 export interface AncestorReach {
     roots: number[];
     contextsReached: number;
     saturated: boolean;
+    /** The saturation gate that stopped this climb, when {@link saturated} is
+     *  true and a trace was requested — see {@link edgeAncestors}.  Absent for
+     *  a non-saturated reach, and absent (even when saturated) when no trace
+     *  was requested — instrumentation must not allocate when tracing is off. */
+    saturation?: SaturationStop;
 }
 /** Saturated-interval information for the noise-drop gate. */
 export interface SaturationInfo {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hviana/sema",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Sema: a non-parametric, instance-based reasoning system.",
   "type": "module",
   "main": "dist/src/index.js",

package/src/geometry.ts

@@ -7,7 +7,7 @@
 //      identically regardless of what follows — pure structural stability.
 //   3. The same rule recurses level after level until one root remains.
 
-import { normalize, Vec } from "./vec.js";
+import { addInto, copy, normalize, Vec, zeros } from "./vec.js";
 import { Sema, sema, Space } from "./sema.js";
 import { Alphabet } from "./alphabet.js";
 
@@ -461,8 +461,10 @@ function fold2(space: Space, a: Folded, b: Folded): Folded {
 /** Plain river fold WITHOUT the final root normalize — the segment-level
  *  building block of {@link stablePrefixFold} (interiors must keep their
  *  byte-proportional magnitude; only the whole perception's root is ever
- *  normalized). */
-function riverFoldRaw(space: Space, row: Folded[]): Folded {
+ *  normalized).  Exported so callers that COMPOSE already-existing structural
+ *  parts into a hypothetical synthetic root (see {@link composeStructuralGist})
+ *  can feed the same raw primitive instead of duplicating its mathematics. */
+export function riverFoldRaw(space: Space, row: Folded[]): Folded {
   if (row.length === 0) {
     const z = new Float32Array(space.D);
     return { tree: sema(z, new Uint8Array(0), null), len: 0 };
@@ -477,6 +479,53 @@ function riverFoldRaw(space: Space, row: Folded[]): Folded {
   return level[0];
 }
 
+// ---- structural composition (synthesize from EXISTING structural parts) ----
+
+/** One already-existing structural vector to compose, paired with the byte
+ *  span (query-slot) length it stands in for.  `len`, not the vector's own
+ *  magnitude, is what {@link composeStructuralGist} restores — the composed
+ *  slot's NATURAL span, exactly as the linear river fold would carry it. */
+export interface StructuralPart {
+  v: Vec;
+  len: number;
+}
+
+/** Synthesize a hypothetical internal structure from already-existing
+ *  structural vectors — NOT from bytes.  This is the raw positional
+ *  composition the linear river fold already uses (see the folding header
+ *  above): each part is positionally bound into its own seat, its natural
+ *  span magnitude is preserved, the parts are linearly superposed, and only
+ *  the final synthetic root is normalized.  It never calls {@link gistOf}
+ *  (there is no `gistOf` here — geometry.ts has no store), never perceives a
+ *  concatenated byte string, and never interns or stores a new node: the
+ *  result is an opaque, ungrounded Vec for an ANN probe only. */
+export function composeStructuralGist(
+  space: Space,
+  parts: readonly StructuralPart[],
+): Vec {
+  const foldedParts: Folded[] = [];
+
+  for (const part of parts) {
+    if (part.len <= 0) continue;
+
+    const direction = copy(part.v);
+    normalize(direction);
+
+    const scaled = zeros(space.D);
+    addInto(scaled, direction, Math.sqrt(part.len));
+
+    foldedParts.push({ tree: sema(scaled), len: part.len });
+  }
+
+  if (foldedParts.length === 0) return zeros(space.D);
+
+  const rawRoot = riverFoldRaw(space, foldedParts);
+
+  const result = copy(rawRoot.tree.v);
+  normalize(result);
+  return result;
+}
+
 // ---- pyramid fold (incremental plain perception) ----
 
 /** The PLAIN fold's full level pyramid — every level's item list, bottom