@hviana/sema 0.1.0

package/src/vec.ts

@@ -0,0 +1,124 @@
+// 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.
+
+export type Vec = Float32Array;
+
+/** Deterministic PRNG (32-bit mixer). */
+export function rng(seed: number): () => number {
+  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: () => number): number {
+  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: number): Vec => new Float32Array(D);
+export const copy = (v: Vec): Vec => new Float32Array(v);
+
+/** Random point on the unit sphere. */
+export function randomUnit(D: number, rand: () => number): Vec {
+  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: Vec, src: Vec, scale = 1): Vec {
+  for (let i = 0; i < target.length; i++) target[i] += src[i] * scale;
+  return target;
+}
+
+export function dot(a: Vec, b: Vec): number {
+  let s = 0;
+  for (let i = 0; i < a.length; i++) s += a[i] * b[i];
+  return s;
+}
+
+const norm = (v: Vec): number => 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: Vec): Vec {
+  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: Vec, b: Vec): number {
+  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: {
+  normalizeEpsilon?: number;
+  cosineEpsilon?: number;
+}): void {
+  if (cfg.normalizeEpsilon !== undefined) {
+    _normalizeEpsilon = cfg.normalizeEpsilon;
+  }
+  if (cfg.cosineEpsilon !== undefined) _cosineEpsilon = cfg.cosineEpsilon;
+}
+
+export interface Permutation {
+  fwd: Uint32Array;
+  inv: Uint32Array;
+}
+
+/** One fixed random permutation (Fisher–Yates). */
+function makePermutation(D: number, rand: () => number): Permutation {
+  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: number,
+  seats: number,
+  rand: () => number,
+): Permutation[] {
+  const ring: Permutation[] = [];
+  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: Vec, table: Uint32Array): Vec {
+  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: Vec, v: Vec, table: Uint32Array): Vec {
+  for (let i = 0; i < v.length; i++) out[i] = v[table[i]];
+  return out;
+}

package/test/00-extract.test.mjs

@@ -0,0 +1,151 @@
+// 00-extract.test.mjs — extract a PIECE from prose by a TAUGHT skill.
+//
+// The requirement: ask about a part of a sentence and get just that part — a
+// value the mind was NEVER told (it appears only in the question's own sentence).
+//
+// This is not blind carving of an isolated sentence (that is impossible — a never-
+// seen value is, by construction, unrelated to anything learned, so nothing can
+// locate it). It is a learned, transferable SKILL, the way a reasoner works:
+//
+//   • You TEACH the skill with a handful of episodes whose answer is a span of
+//     the context — "The dog is named Rex." → "Rex", etc. The episodes share a
+//     shape; the answer is the part that varies.
+//   • You then ask an UNSEEN sentence of the same shape. The mind matches it to
+//     the skill (the consensus climb, `climbAttentionAll`, over the structural DAG), locates the invariant
+//     frame bytes bordering the answer in the exemplar, finds those same bytes
+//     in the query by exact match, and reads whatever sits between them out of
+//     the QUESTION itself — returning a value it was never told.
+//
+// The result is approximate by nature — a reasoner's relational read, not a byte
+// rule — but consistent: the analogous span transfers across unseen values and
+// across entirely different relations (named / capital / born). These assertions
+// are literal equality on the extracted value.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { Mind } from "../dist/src/index.js";
+import { SQliteStore } from "../dist/src/store-sqlite.js";
+
+const taught = async (episodes) => {
+  const mind = new Mind({
+    seed: 7,
+  });
+  await mind.ingest(episodes); // (sentence → answer-span) episodes: the SKILL
+  return mind;
+};
+
+const ask = async (mind, q) => (await mind.respondText(q)).trim();
+
+test("learn to extract a NAME, then extract it from unseen sentences", async () => {
+  const mind = await taught([
+    ["The dog is named Rex.", "Rex"],
+    ["The cat is named Whiskers.", "Whiskers"],
+    ["The horse is named Comet.", "Comet"],
+    ["The parrot is named Echo.", "Echo"],
+    ["The fish is named Bubbles.", "Bubbles"],
+  ]);
+  // Unseen sentences; the names below were NEVER deposited.
+  assert.equal(await ask(mind, "The rabbit is named Clover."), "Clover");
+  assert.equal(await ask(mind, "The owl is named Sage."), "Sage");
+  assert.equal(await ask(mind, "The bear is named Honey."), "Honey");
+  await mind.store.close();
+});
+
+test("the SAME mechanism learns a different relation: the capital", async () => {
+  const mind = await taught([
+    ["The capital of France is Paris.", "Paris"],
+    ["The capital of Japan is Tokyo.", "Tokyo"],
+    ["The capital of Egypt is Cairo.", "Cairo"],
+    ["The capital of Peru is Lima.", "Lima"],
+  ]);
+  assert.equal(
+    await ask(mind, "The capital of Brazil is Brasilia."),
+    "Brasilia",
+  );
+  assert.equal(await ask(mind, "The capital of Italy is Rome."), "Rome");
+  await mind.store.close();
+});
+
+test("and another relation: where someone was born", async () => {
+  const mind = await taught([
+    ["Einstein was born in Germany.", "Germany"],
+    ["Curie was born in Poland.", "Poland"],
+    ["Newton was born in England.", "England"],
+    ["Tesla was born in Serbia.", "Serbia"],
+  ]);
+  assert.equal(await ask(mind, "Darwin was born in England."), "England");
+  assert.equal(await ask(mind, "Mozart was born in Austria."), "Austria");
+  await mind.store.close();
+});
+
+// Extraction and multi-hop are COMPOSABLE, not isolated branches: extracting a
+// value and then reasoning from it is one pipeline. Here the extracted value
+// ("Rome") has its own downstream fact, so the answer chains through it.
+test("extraction COMPOSES with multi-hop reasoning", async () => {
+  const mind = await taught([
+    ["The capital of France is Paris.", "Paris"],
+    ["The capital of Japan is Tokyo.", "Tokyo"],
+    ["The capital of Egypt is Cairo.", "Cairo"],
+    ["The capital of Peru is Lima.", "Lima"],
+  ]);
+  // A fact keyed on a value the skill will extract.
+  await mind.ingest(["Rome", "Rome was the heart of a vast empire"]);
+  // "Italy" is an unseen subject → extraction yields "Rome" → reason hops to its
+  // fact. One pipeline: ground-by-skill, then walk the graph forward.
+  assert.equal(
+    await ask(mind, "The capital of Italy is Rome."),
+    "Rome was the heart of a vast empire",
+  );
+  await mind.store.close();
+});
+
+// A MULTI-WORD answer span, reached from EITHER seat. The discriminative slice of
+// the query ("painted by") is itself part of the answer span, so the consensus
+// climb can land on the CONTINUATION seat (an answer like "Leonardo da Vinci",
+// which bears no forward edge) rather than the context. The skill must still
+// apply — rise through the answer's `prev` edge to the context that taught it —
+// and the multi-word value must come back WHOLE (not truncated to one word, and
+// not collapsed to a neighbour's answer via fallback recall).
+test("extracts a MULTI-WORD span, from whichever seat the climb lands on", async () => {
+  const mind = await taught([
+    ["The Mona Lisa was painted by Leonardo da Vinci.", "Leonardo da Vinci"],
+    ["The Starry Night was painted by Vincent van Gogh.", "Vincent van Gogh"],
+    [
+      "The Night Watch was painted by Rembrandt van Rijn.",
+      "Rembrandt van Rijn",
+    ],
+    ["The Scream was painted by Edvard Munch.", "Edvard Munch"],
+  ]);
+  assert.equal(
+    await ask(mind, "Guernica was painted by Pablo Picasso."),
+    "Pablo Picasso",
+  );
+  assert.equal(
+    await ask(mind, "The Persistence of Memory was painted by Salvador Dali."),
+    "Salvador Dali",
+  );
+  await mind.store.close();
+});
+
+// The multi-word extraction COMPOSES with the forward hop: lift a never-seen
+// painter out of the sentence, then reason onward to a stored fact keyed on that
+// name. The reply contains no word of the question — generalization and a
+// reasoning hop in one query (the README's headline demo).
+test("multi-word extraction COMPOSES with a forward reasoning hop", async () => {
+  const mind = await taught([
+    ["The Mona Lisa was painted by Leonardo da Vinci.", "Leonardo da Vinci"],
+    ["The Starry Night was painted by Vincent van Gogh.", "Vincent van Gogh"],
+    [
+      "The Night Watch was painted by Rembrandt van Rijn.",
+      "Rembrandt van Rijn",
+    ],
+  ]);
+  await mind.ingest([
+    ["Pablo Picasso", "Pablo Picasso co-founded the Cubist movement"],
+  ]);
+  assert.equal(
+    await ask(mind, "The Weeping Woman was painted by Pablo Picasso."),
+    "Pablo Picasso co-founded the Cubist movement",
+  );
+  await mind.store.close();
+});

package/test/01-floor.test.mjs

@@ -0,0 +1,20 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { cosine, Mind } from "../dist/src/index.js";
+
+test("fractal floor: ordinal geometry of the byte line", async () => {
+  const m = new Mind({ seed: 7 });
+  const a = m.alphabet;
+  // same-mid neighbours resonate more than coarse-only, more than far
+  const sameMid = cosine(a.vecs[64], a.vecs[65]);
+  const sameCoarse = cosine(a.vecs[64], a.vecs[76]);
+  const far = Math.abs(cosine(a.vecs[64], a.vecs[200]));
+  assert.ok(
+    sameMid > sameCoarse + 0.1,
+    `mid ${sameMid} vs coarse ${sameCoarse}`,
+  );
+  assert.ok(sameCoarse > far, `coarse ${sameCoarse} vs far ${far}`);
+});
+
+// encodeChunk / decodeChunk were removed — 1-byte leaves have no chunk
+// encoding.  Each byte is its own leaf with an implicit negative id.

package/test/02-roundtrip.test.mjs

@@ -0,0 +1,83 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { hilbertBytes, Mind } from "../dist/src/index.js";
+import { SQliteStore } from "../dist/src/store-sqlite.js";
+
+const txt = (r) => new TextDecoder().decode(r.bytes).replace(/\u0000+/g, "");
+
+test("random byte streams roundtrip exactly", async () => {
+  const m = new Mind({
+    seed: 11,
+  });
+  let s = 42;
+  const rnd = () => ((s = (s * 1103515245 + 12345) & 0x7fffffff), s % 256);
+  for (let t = 0; t < 20; t++) {
+    const len = 1 + (t * 17) % 180;
+    const bytes = new Uint8Array(len);
+    for (let j = 0; j < len; j++) bytes[j] = rnd();
+    const tree = await m.ingest(bytes);
+    const out = await m.express(tree.v);
+    assert.deepEqual([...out], [...bytes], `trial ${t} len ${len}`);
+  }
+});
+
+test("text roundtrips: unicode, emoji, whitespace, the full byte table, runs", async () => {
+  const m = new Mind({
+    seed: 7,
+  });
+  const table = new Uint8Array(256);
+  for (let i = 0; i < 256; i++) table[i] = i;
+  const cases = [
+    "hello world",
+    "naïve café — émigré: ¿señor? Übermensch",
+    "数据是雨水，记忆是河流。",
+    "🌊🧠 memory is the model 🜁",
+    "line one\nline two\ttabbed\r\nwindows line",
+    "a".repeat(300),
+    "ab".repeat(150),
+  ];
+  for (const c of cases) {
+    const bytes = new TextEncoder().encode(c);
+    const t = await m.ingest(bytes);
+    const out = await m.express(t.v);
+    assert.deepEqual([...out], [...bytes], JSON.stringify(c.slice(0, 20)));
+  }
+  const t = await m.ingest(table);
+  const out = await m.express(t.v);
+  assert.deepEqual([...out], [...table], "byte table");
+});
+
+test("images roundtrip through one root vector", async () => {
+  const m = new Mind({
+    seed: 7,
+  });
+  const mk = (w, h, ch) => {
+    const g = {
+      width: w,
+      height: h,
+      channels: ch,
+      data: new Uint8Array(w * h * ch),
+    };
+    for (let i = 0; i < g.data.length; i++) g.data[i] = (i * 7 + 3) & 0xff;
+    return g;
+  };
+  for (const g of [mk(8, 8, 1), mk(16, 16, 1), mk(8, 8, 3)]) {
+    const want = hilbertBytes(g);
+    const t = await m.ingest(g);
+    const out = await m.express(t.v);
+    assert.deepEqual(
+      [...out],
+      [...want],
+      `${g.width}x${g.height}x${g.channels}`,
+    );
+  }
+});
+
+test("empty input is graceful silence", async () => {
+  const m = new Mind({
+    seed: 7,
+  });
+  const r = await m.respond("");
+  assert.equal(r.v, null);
+  assert.equal(r.bytes.length, 0);
+});

package/test/03-recall.test.mjs

@@ -0,0 +1,98 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { Mind } from "../dist/src/index.js";
+import { SQliteStore } from "../dist/src/store-sqlite.js";
+
+const txt = (r) => new TextDecoder().decode(r.bytes).replace(/\u0000+/g, "");
+
+const FACTS = [
+  ["what is ice?", "ice is frozen water"],
+  ["what is fire?", "fire is hot plasma"],
+  ["who are you?", "a forest of resonant memories"],
+];
+
+test("respond before any training is silence", async () => {
+  const m = new Mind({
+    seed: 7,
+  });
+  assert.equal((await m.respond("anything at all")).v, null);
+});
+
+test("duplicate training is idempotent", async () => {
+  const m = new Mind({
+    seed: 7,
+  });
+  await m.ingest([FACTS[0], FACTS[0], FACTS[0]]);
+  assert.equal(await m.respondText(FACTS[0][0]), FACTS[0][1]);
+});
+
+test("conflicting episodes answer one side, deterministically", async () => {
+  const run = async () => {
+    const m = new Mind({
+      seed: 7,
+    });
+    await m.ingest([["the sky", "blue"], ["the sky", "grey"]]);
+    return await m.respondText("the sky");
+  };
+  const a = await run();
+  const b = await run();
+  assert.ok(a === "blue" || a === "grey", `got "${a}"`);
+  assert.equal(a, b, "same seed, same answer");
+});
+
+test("same seed → identical behaviour and identical save blobs", async () => {
+  const mk = async () => {
+    const m = new Mind({
+      seed: 99,
+    });
+    await m.ingest(FACTS);
+    return m;
+  };
+  const m1 = await mk(), m2 = await mk();
+  assert.equal(
+    await m1.respondText(FACTS[1][0]),
+    await m2.respondText(FACTS[1][0]),
+  );
+  const b1 = await m1.save(), b2 = await m2.save();
+  assert.deepEqual([...new Uint8Array(b1)], [...new Uint8Array(b2)]);
+});
+
+test("known query returns an answer, unknown returns null", async () => {
+  const m = new Mind({
+    seed: 7,
+  });
+  await m.ingest(FACTS);
+  const known = await m.respond(FACTS[0][0]);
+  assert.ok(known.v !== null, "known query must return an answer");
+  assert.ok(known.bytes.length > 0, "known query must return bytes");
+  // Unknown query: may return null or a closest-approximation answer.
+  // Either is correct — the system always gives its best.
+});
+
+test("seat symmetry: an episode completes from either seat (whole-level)", async () => {
+  for (const seed of [1, 7, 42]) {
+    const m = new Mind({
+      seed,
+    });
+    await m.ingest([
+      ["what is ice?", "ice is frozen water"],
+      ["what is fire?", "fire is hot plasma"],
+    ]);
+    // reverse: a known CONTINUATION recalls its context
+    assert.equal(
+      await m.respondText("ice is frozen water"),
+      "what is ice?",
+      `seed ${seed}`,
+    );
+    // forward priority untouched
+    assert.equal(
+      await m.respondText("what is fire?"),
+      "fire is hot plasma",
+      `seed ${seed}`,
+    );
+    // a stranger continuation: may be null (no close match) or a
+    // deterministic approximation — either is correct behaviour.
+    const r = await m.respond("lava is molten rock");
+    assert.ok(r.v !== undefined, "respond returns a valid response");
+  }
+});