@hviana/sema 0.2.4 → 0.2.5

package/src/mind/index.ts

@@ -16,3 +16,19 @@ export type {
   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/src/mind/junction.ts

@@ -12,6 +12,7 @@
 // adjacent ANSWER pieces) and cross-region attention (the joint CONTEXT of two
 // non-adjacent QUERY regions) ascend by the same disciplined, bounded walk.
 
+import type { Hit } from "../store.js";
 import type { MindContext } from "./types.js";
 import { read, resolve } from "./primitives.js";
 import { windowIds } from "./canonical.js";
@@ -27,6 +28,52 @@ export interface Junction {
   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 async function loadJunctionSynonymSides(
+  ctx: MindContext,
+  left: Uint8Array,
+  right: Uint8Array,
+): Promise<JunctionSynonymSides> {
+  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
@@ -292,20 +339,32 @@ export async function junctionSynonyms(
   right: Uint8Array,
   maxInterior: number,
   unordered = false,
-): Promise<Junction[]> {
-  const out: Junction[] = [];
-
-  const lId = resolve(ctx, left);
-  const rId = resolve(ctx, right);
-  if (lId === null && rId === null) return out;
+  sides?: JunctionSynonymSides,
+): Promise<SynonymJunction[]> {
+  const s = sides ?? await loadJunctionSynonymSides(ctx, left, right);
+  if (s.leftId === null && s.rightId === null) return [];
 
-  const budget = { n: hubBound(ctx) * ctx.space.maxGroup };
+  // ── 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<number, SynonymJunction>();
+  const keepBest = (
+    map: Map<number, SynonymJunction>,
+    j: Junction,
+    tier: SynonymJunctionTier,
+    confidence: number,
+  ) => {
+    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(
@@ -315,18 +374,20 @@ export async function junctionSynonyms(
         sibBytes.length + right.length + maxInterior,
         junctionSeeds(ctx, sibBytes),
         rightSeeds,
-        budget,
+        singleBudget,
         unordered,
       );
-      for (const c of containers) out.push(c);
+      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(
@@ -336,12 +397,60 @@ export async function junctionSynonyms(
         left.length + sibBytes.length + maxInterior,
         leftSeeds,
         junctionSeeds(ctx, sibBytes),
-        budget,
+        singleBudget,
         unordered,
       );
-      for (const c of containers) out.push(c);
+      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: Array<{ l: Hit; r: Hit; confidence: number }> = [];
+  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<number, SynonymJunction>();
+  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/src/mind/mind.ts

@@ -136,6 +136,21 @@ import {
   climbAttention as climbAttentionFn,
   naturalBreak as naturalBreakFn,
 } from "./attention.js";
+export type {
+  AnchorRejectionReason,
+  ClimbConsensusData,
+  ConsensusAnchorTrace,
+  ConsensusReachTrace,
+  ConsensusRegionTrace,
+  CrossRegionTier,
+  JunctionVoteTrace,
+  RegionOutcome,
+} from "./attention.js";
+export type {
+  AncestorReach,
+  SaturationReason,
+  SaturationStop,
+} from "./types.js";
 import { aluToMechanism, defaultMechanisms, think } from "./pipeline.js";
 import { articulate } from "./articulation.js";
 import { ingest } from "./learning.js";

package/src/mind/rationale.ts

@@ -83,6 +83,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
@@ -142,7 +147,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}.
@@ -212,6 +217,7 @@ export class Rationale {
     outputs: RationaleItem[],
     deps: number[] | undefined,
     note: string | undefined,
+    data?: unknown,
   ): void {
     this.sink({
       index,
@@ -223,6 +229,7 @@ export class Rationale {
       inputs,
       outputs,
       note,
+      data,
     });
   }
 
@@ -248,11 +255,11 @@ 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);
       },
     };
   }
@@ -265,11 +272,12 @@ export class Rationale {
     outputs: RationaleItem[],
     note?: string,
     deps?: number[],
+    data?: unknown,
   ): number {
     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/src/mind/traverse.ts

@@ -7,7 +7,7 @@
 // project) live in match.ts — the elementary match-and-project operation.
 
 import { cosine, Vec } from "../vec.js";
-import type { AncestorReach, MindContext } from "./types.js";
+import type { AncestorReach, MindContext, SaturationStop } from "./types.js";
 import { gistOf, read } from "./primitives.js";
 
 // ── Per-response structural memo ────────────────────────────────────────
@@ -134,7 +134,22 @@ export function edgeAncestors(
   // 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: AncestorReach = {
+      roots: [],
+      contextsReached: 0,
+      saturated: true,
+      ...(ctx.trace
+        ? {
+          saturation: {
+            reason: "byte-atom-commonality" as const,
+            node: id,
+            observed: atomReach(ctx, contextCount),
+            limit: bound0,
+          },
+        }
+        : {}),
+    };
     memo?.set(id, reach);
     return reach;
   }
@@ -144,6 +159,10 @@ export function edgeAncestors(
   const seen = new Set<number>([id]);
   const ctxSeen = new Set<number>();
   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: SaturationStop | undefined;
 
   // EXPAND-UNTIL-DECIDED: a reach is consumed either as a VOTE (which needs
   // contextsReached exactly, and only while ≤ √N — beyond that the region is
@@ -188,12 +207,45 @@ export function edgeAncestors(
     if (hasNx || pc > 0) {
       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)) {
@@ -204,7 +256,18 @@ export function edgeAncestors(
     }
     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;
   };
@@ -266,7 +329,12 @@ export function edgeAncestors(
     }
   }
 
-  const reach = { roots, contextsReached: ctxSeen.size, saturated };
+  const reach: AncestorReach = {
+    roots,
+    contextsReached: ctxSeen.size,
+    saturated,
+    ...(saturated && satStop ? { saturation: satStop } : {}),
+  };
   memo?.set(id, reach);
   return reach;
 }

package/src/mind/types.ts

@@ -175,11 +175,36 @@ export interface RegionVote {
   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. */