@hviana/sema 0.2.6 → 0.2.8

package/dist/src/vec.d.ts

@@ -0,0 +1,31 @@
+export type Vec = Float32Array;
+/** Deterministic PRNG (32-bit mixer). */
+export declare function rng(seed: number): () => number;
+export declare const zeros: (D: number) => Vec;
+export declare const copy: (v: Vec) => Vec;
+/** Random point on the unit sphere. */
+export declare function randomUnit(D: number, rand: () => number): Vec;
+/** target += src * scale (in place). */
+export declare function addInto(target: Vec, src: Vec, scale?: number): Vec;
+export declare function dot(a: Vec, b: Vec): number;
+/** In-place normalization. */
+export declare function normalize(v: Vec): Vec;
+/** Resonance: 1 = same, 0 = unrelated. */
+export declare function cosine(a: Vec, b: Vec): number;
+/** Set vector epsilon thresholds. Called once by Mind at construction. */
+export declare function setVecConfig(cfg: {
+    normalizeEpsilon?: number;
+    cosineEpsilon?: number;
+}): void;
+export interface Permutation {
+    fwd: Uint32Array;
+    inv: Uint32Array;
+}
+/** The keyring: one independent permutation per seat.
+ *  Independent keys do not commute, so an address in a tree is the
+ *  path itself — "seat 2 inside seat 1" ≠ "seat 1 inside seat 2". */
+export declare function makeKeyring(D: number, seats: number, rand: () => number): Permutation[];
+/** Apply permutation: out[i] = v[table[i]]. */
+export declare function permute(v: Vec, table: Uint32Array): Vec;
+/** Permute into existing buffer — zero allocation. */
+export declare function permuteInto(out: Vec, v: Vec, table: Uint32Array): Vec;

package/dist/src/vec.js

@@ -0,0 +1,109 @@
+// vec.ts — vector primitives.
+// Superposition (add), normalization (stay on the sphere),
+// resonance (cosine), and seat binding (a keyring of fixed permutations).
+// No weights. No gradients.
+/** Deterministic PRNG (32-bit mixer). */
+export function rng(seed) {
+    let s = seed >>> 0;
+    return () => {
+        s = (s + 0x6d2b79f5) >>> 0;
+        let t = s;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** Standard normal sample (Box–Muller). */
+function gaussian(rand) {
+    let u = 0, v = 0;
+    while (u === 0)
+        u = rand();
+    while (v === 0)
+        v = rand();
+    return Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v);
+}
+export const zeros = (D) => new Float32Array(D);
+export const copy = (v) => new Float32Array(v);
+/** Random point on the unit sphere. */
+export function randomUnit(D, rand) {
+    const v = zeros(D);
+    for (let i = 0; i < D; i++)
+        v[i] = gaussian(rand);
+    return normalize(v);
+}
+/** target += src * scale (in place). */
+export function addInto(target, src, scale = 1) {
+    for (let i = 0; i < target.length; i++)
+        target[i] += src[i] * scale;
+    return target;
+}
+export function dot(a, b) {
+    let s = 0;
+    for (let i = 0; i < a.length; i++)
+        s += a[i] * b[i];
+    return s;
+}
+const norm = (v) => Math.sqrt(dot(v, v));
+// Epsilon thresholds (settable once via setVecConfig).
+let _normalizeEpsilon = 1e-12;
+let _cosineEpsilon = 1e-12;
+/** In-place normalization. */
+export function normalize(v) {
+    const n = norm(v);
+    if (n > _normalizeEpsilon) {
+        for (let i = 0; i < v.length; i++)
+            v[i] /= n;
+    }
+    return v;
+}
+/** Resonance: 1 = same, 0 = unrelated. */
+export function cosine(a, b) {
+    const na = norm(a), nb = norm(b);
+    return na > _cosineEpsilon && nb > _cosineEpsilon ? dot(a, b) / (na * nb) : 0;
+}
+/** Set vector epsilon thresholds. Called once by Mind at construction. */
+export function setVecConfig(cfg) {
+    if (cfg.normalizeEpsilon !== undefined) {
+        _normalizeEpsilon = cfg.normalizeEpsilon;
+    }
+    if (cfg.cosineEpsilon !== undefined)
+        _cosineEpsilon = cfg.cosineEpsilon;
+}
+/** One fixed random permutation (Fisher–Yates). */
+function makePermutation(D, rand) {
+    const fwd = new Uint32Array(D);
+    for (let i = 0; i < D; i++)
+        fwd[i] = i;
+    for (let i = D - 1; i > 0; i--) {
+        const j = Math.floor(rand() * (i + 1));
+        const t = fwd[i];
+        fwd[i] = fwd[j];
+        fwd[j] = t;
+    }
+    const inv = new Uint32Array(D);
+    for (let i = 0; i < D; i++)
+        inv[fwd[i]] = i;
+    return { fwd, inv };
+}
+/** The keyring: one independent permutation per seat.
+ *  Independent keys do not commute, so an address in a tree is the
+ *  path itself — "seat 2 inside seat 1" ≠ "seat 1 inside seat 2". */
+export function makeKeyring(D, seats, rand) {
+    const ring = [];
+    for (let s = 0; s < seats; s++)
+        ring.push(makePermutation(D, rand));
+    return ring;
+}
+/** Apply permutation: out[i] = v[table[i]]. */
+export function permute(v, table) {
+    const out = new Float32Array(v.length);
+    for (let i = 0; i < v.length; i++)
+        out[i] = v[table[i]];
+    return out;
+}
+/** Permute into existing buffer — zero allocation. */
+export function permuteInto(out, v, table) {
+    for (let i = 0; i < v.length; i++)
+        out[i] = v[table[i]];
+    return out;
+}

package/package.json

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

package/src/mind/attention.ts

@@ -1549,86 +1549,137 @@ const VARIANT_KIND_ORDER: Record<StructuralVariant["kind"], number> = {
   "double-synonym": 2,
 };
 
-/** A node's structural gist, read directly from its own stored bytes — the
- *  repository's node → gist accessor: content is immutable and perception is
- *  a pure function of bytes, so re-perceiving a node's full stored bytes
- *  reproduces exactly the gist it was interned with.  Never concatenates
- *  the sibling's bytes with anything else. */
-function storedNodeGist(ctx: MindContext, id: number): Vec {
-  return gistOf(ctx, read(ctx, id));
+/** A lightweight, cost-free descriptor of one candidate structural variant —
+ *  enough to rank it, but with no bytes read and no vector materialized. */
+interface StructuralVariantSpec {
+  kind: "left-synonym" | "right-synonym" | "double-synonym";
+  semanticConfidence: number;
+  leftSiblingId?: number;
+  rightSiblingId?: number;
 }
 
-/** A halo sibling's structural part, occupying the ORIGINAL query-region
- *  slot length — the sibling replaces only the DIRECTION, never the query's
- *  own bytes, position, or gap (see §6 of the spec this implements). */
-function siblingPart(
+/** Same deterministic ordering the old implementation applied to already-
+ *  materialized variants (§8): semantic confidence desc, then kind
+ *  (left-synonym, right-synonym, double-synonym), then sibling ids asc. */
+function compareStructuralVariantSpecs(
+  a: StructuralVariantSpec,
+  b: StructuralVariantSpec,
+): number {
+  return b.semanticConfidence - a.semanticConfidence ||
+    VARIANT_KIND_ORDER[a.kind] - VARIANT_KIND_ORDER[b.kind] ||
+    (a.leftSiblingId ?? -1) - (b.leftSiblingId ?? -1) ||
+    (a.rightSiblingId ?? -1) - (b.rightSiblingId ?? -1);
+}
+
+/** Every single- and double-synonym combination, as cost-free descriptors —
+ *  no `read`, `gistOf`, `perceive` or `StructuralPart` allocation.  Both
+ *  sibling lists are already bounded by `haloQueryK`, so the O(haloQueryK²)
+ *  cross-product here is cheap; only the SELECTED specs go on to pay for
+ *  sibling reconstruction. */
+function buildStructuralVariantSpecs(
+  sides: JunctionSynonymSides,
+): StructuralVariantSpec[] {
+  const specs: StructuralVariantSpec[] = [];
+
+  for (const left of sides.leftSiblings) {
+    specs.push({
+      kind: "left-synonym",
+      semanticConfidence: left.score,
+      leftSiblingId: left.id,
+    });
+  }
+
+  for (const right of sides.rightSiblings) {
+    specs.push({
+      kind: "right-synonym",
+      semanticConfidence: right.score,
+      rightSiblingId: right.id,
+    });
+  }
+
+  for (const left of sides.leftSiblings) {
+    for (const right of sides.rightSiblings) {
+      specs.push({
+        kind: "double-synonym",
+        semanticConfidence: Math.min(left.score, right.score),
+        leftSiblingId: left.id,
+        rightSiblingId: right.id,
+      });
+    }
+  }
+
+  specs.sort(compareStructuralVariantSpecs);
+
+  return specs;
+}
+
+/** A halo sibling's structural gist, bounded to `maxBytes` of stored content
+ *  and reused across the whole climb.  `positiveMemo` (shared across every
+ *  probe in the climb, passed in by the caller) remembers only successfully
+ *  reconstructed complete gists — a sibling rejected here for being too
+ *  large for THIS pair's phrase-scale bound may still be admissible for a
+ *  larger-spanning pair later, so a rejection is never memoized globally.
+ *  `localMemo` is scoped to one `buildStructuralVariants` call, where every
+ *  variant shares the same bound, so a `null` there is safe to reuse. */
+function loadBoundedSiblingGist(
   ctx: MindContext,
-  sibling: Hit,
-  originalRegion: { start: number; end: number },
-): StructuralPart {
-  return {
-    v: storedNodeGist(ctx, sibling.id),
-    len: originalRegion.end - originalRegion.start,
-  };
+  id: number,
+  maxBytes: number,
+  positiveMemo: Map<number, Vec>,
+  localMemo: Map<number, Vec | null>,
+): Vec | null {
+  if (localMemo.has(id)) {
+    return localMemo.get(id) ?? null;
+  }
+
+  const cached = positiveMemo.get(id);
+  if (cached !== undefined) {
+    localMemo.set(id, cached);
+    return cached;
+  }
+
+  const length = ctx.store.contentLen(id, maxBytes + 1);
+  if (length <= 0 || length > maxBytes) {
+    localMemo.set(id, null);
+    return null;
+  }
+
+  const bytes = read(ctx, id, maxBytes + 1);
+  if (bytes.length === 0 || bytes.length > maxBytes) {
+    localMemo.set(id, null);
+    return null;
+  }
+
+  const gist = gistOf(ctx, bytes);
+  positiveMemo.set(id, gist);
+  localMemo.set(id, gist);
+  return gist;
 }
 
 /** Build, bound and order every mandatory structural variant (§7-8): the
  *  exact/exact composition is always kept; up to `ctx.cfg.haloQueryK`
  *  synonym variants (single- and double-synonym combined, one shared
- *  budget) are appended, ordered by confidence, then kind, then sibling id. */
+ *  budget) are appended, ordered by confidence, then kind, then sibling id.
+ *  Variant selection is entirely lightweight (see {@link
+ *  buildStructuralVariantSpecs}); a sibling's bytes are read and perceived
+ *  only for specs actually retained, and at most once per sibling id per
+ *  climb via `siblingGistMemo`. */
 export function buildStructuralVariants(
   ctx: MindContext,
   ra: Region,
   rb: Region,
   sides: JunctionSynonymSides,
+  siblingGistMemo: Map<number, Vec>,
 ): {
   variants: StructuralVariant[];
   exactLeft: StructuralPart;
   exactRight: StructuralPart;
 } {
-  const exactLeft: StructuralPart = { v: ra.v, len: ra.end - ra.start };
-  const exactRight: StructuralPart = { v: rb.v, len: rb.end - rb.start };
-
-  const synonymVariants: StructuralVariant[] = [];
-  for (const ls of sides.leftSiblings) {
-    synonymVariants.push({
-      left: siblingPart(ctx, ls, ra),
-      right: exactRight,
-      kind: "left-synonym",
-      semanticConfidence: ls.score,
-      leftSiblingId: ls.id,
-    });
-  }
-  for (const rs of sides.rightSiblings) {
-    synonymVariants.push({
-      left: exactLeft,
-      right: siblingPart(ctx, rs, rb),
-      kind: "right-synonym",
-      semanticConfidence: rs.score,
-      rightSiblingId: rs.id,
-    });
-  }
-  for (const ls of sides.leftSiblings) {
-    for (const rs of sides.rightSiblings) {
-      synonymVariants.push({
-        left: siblingPart(ctx, ls, ra),
-        right: siblingPart(ctx, rs, rb),
-        kind: "double-synonym",
-        semanticConfidence: Math.min(ls.score, rs.score),
-        leftSiblingId: ls.id,
-        rightSiblingId: rs.id,
-      });
-    }
-  }
+  const leftLen = ra.end - ra.start;
+  const rightLen = rb.end - rb.start;
 
-  // §8: semantic confidence desc, then kind (left-synonym, right-synonym,
-  // double-synonym), then left sibling id asc, then right sibling id asc.
-  synonymVariants.sort((a, b) =>
-    b.semanticConfidence - a.semanticConfidence ||
-    VARIANT_KIND_ORDER[a.kind] - VARIANT_KIND_ORDER[b.kind] ||
-    (a.leftSiblingId ?? -1) - (b.leftSiblingId ?? -1) ||
-    (a.rightSiblingId ?? -1) - (b.rightSiblingId ?? -1)
-  );
+  const exactLeft: StructuralPart = { v: ra.v, len: leftLen };
+  const exactRight: StructuralPart = { v: rb.v, len: rightLen };
 
   const variants: StructuralVariant[] = [
     {
@@ -1637,8 +1688,60 @@ export function buildStructuralVariants(
       kind: "exact-exact",
       semanticConfidence: 1,
     },
-    ...synonymVariants.slice(0, ctx.cfg.haloQueryK),
   ];
+
+  // Same phrase-scale bound the cross-region junction ladder uses
+  // (`maxInterior`): a sibling whose complete stored content exceeds it is
+  // not materialized as a structural-resonance endpoint, keeping sibling
+  // reconstruction phrase-scale even for a large deposit or conversation
+  // root that merely appeared in a halo result.
+  const maxSiblingBytes = (leftLen + rightLen) * ctx.space.maxGroup;
+
+  const specs = buildStructuralVariantSpecs(sides);
+  const localGistMemo = new Map<number, Vec | null>();
+  let retainedSynonyms = 0;
+
+  for (const spec of specs) {
+    if (retainedSynonyms >= ctx.cfg.haloQueryK) break;
+
+    let left = exactLeft;
+    let right = exactRight;
+
+    if (spec.leftSiblingId !== undefined) {
+      const gist = loadBoundedSiblingGist(
+        ctx,
+        spec.leftSiblingId,
+        maxSiblingBytes,
+        siblingGistMemo,
+        localGistMemo,
+      );
+      if (gist === null) continue;
+      left = { v: gist, len: leftLen };
+    }
+
+    if (spec.rightSiblingId !== undefined) {
+      const gist = loadBoundedSiblingGist(
+        ctx,
+        spec.rightSiblingId,
+        maxSiblingBytes,
+        siblingGistMemo,
+        localGistMemo,
+      );
+      if (gist === null) continue;
+      right = { v: gist, len: rightLen };
+    }
+
+    variants.push({
+      left,
+      right,
+      kind: spec.kind,
+      semanticConfidence: spec.semanticConfidence,
+      leftSiblingId: spec.leftSiblingId,
+      rightSiblingId: spec.rightSiblingId,
+    });
+    retainedSynonyms++;
+  }
+
   return { variants, exactLeft, exactRight };
 }
 
@@ -1675,6 +1778,7 @@ export async function structuralResonance(
   ra: Region,
   rb: Region,
   sides: JunctionSynonymSides,
+  siblingGistMemo: Map<number, Vec>,
   k: number,
   N: number,
   reachMemo: Map<number, AncestorReach>,
@@ -1692,7 +1796,13 @@ export async function structuralResonance(
   | { proposal: StructuralResonanceProposal; reach: AncestorReach; idf: number }
   | null
 > {
-  const { variants } = buildStructuralVariants(ctx, ra, rb, sides);
+  const { variants } = buildStructuralVariants(
+    ctx,
+    ra,
+    rb,
+    sides,
+    siblingGistMemo,
+  );
   if (trace) trace.variantBudget = ctx.cfg.haloQueryK;
 
   const middleBytes = query.subarray(ra.end, rb.start);
@@ -1864,6 +1974,10 @@ async function crossRegionVotes(
   //
   // Only MAXIMAL spans compose: a span contained in another candidate is a
   // fragment of that candidate's evidence, never independent of it.
+  // Shared across every cross-region probe in this climb: a sibling
+  // successfully reconstructed while probing one pair must not be read and
+  // perceived again while probing another pair in the same climb.
+  const siblingGistMemo = new Map<number, Vec>();
   const votedSpans = new Set<string>();
   for (const rv of rvs.votes) votedSpans.add(`${rv.start},${rv.end}`);
   const seen = new Set<string>();
@@ -2155,6 +2269,7 @@ async function crossRegionVotes(
             ra,
             rb,
             sides,
+            siblingGistMemo,
             k,
             N,
             reachMemo,

package/test/51-structural-resonance-ladder.test.mjs

@@ -381,6 +381,7 @@ test("7/8/9. buildStructuralVariants always includes exact-exact, left-synonym,
     ra,
     rb,
     sides,
+    new Map(),
   );
   assert.equal(variants[0].kind, "exact-exact");
   assert.equal(variants[0].semanticConfidence, 1);
@@ -410,7 +411,7 @@ test("11. synonym variants are bounded to haloQueryK, in addition to the always-
     enc("crimson"),
     enc("square"),
   );
-  const { variants } = buildStructuralVariants(m, ra, rb, sides);
+  const { variants } = buildStructuralVariants(m, ra, rb, sides, new Map());
   assert.ok(variants.length <= 1 + m.cfg.haloQueryK);
   await m.store.close();
 });
@@ -428,7 +429,7 @@ test("12. a sibling's structural part keeps the ORIGINAL query-region slot lengt
     enc("crimson"),
     enc("square"),
   );
-  const { variants } = buildStructuralVariants(m, ra, rb, sides);
+  const { variants } = buildStructuralVariants(m, ra, rb, sides, new Map());
   for (const v of variants) {
     assert.equal(
       v.left.len,
@@ -483,6 +484,7 @@ test("13/18. structuralResonance composes the real middle query bytes and applie
     ra,
     rb,
     sides,
+    new Map(),
     12,
     N,
     new Map(),
@@ -520,7 +522,7 @@ test("15. two variants proposing the SAME candidate keep only the higher-effecti
     enc("crimson"),
     enc("square"),
   );
-  const { variants } = buildStructuralVariants(m, ra, rb, sides);
+  const { variants } = buildStructuralVariants(m, ra, rb, sides, new Map());
   // Directly exercise the merge logic's contract: build two synthetic
   // proposals for the SAME id with different effectiveScore and confirm the
   // higher one is what a caller keeps (mirrors betterProposal's tie-break,
@@ -533,6 +535,7 @@ test("15. two variants proposing the SAME candidate keep only the higher-effecti
     ra,
     rb,
     sides,
+    new Map(),
     12,
     N,
     new Map(),