@hviana/sema 0.2.9 → 0.4.0

package/test/53-cross-region-probe-instrumentation.test.mjs

@@ -47,6 +47,27 @@ const SYN_ATTR_CORPUS = [
   ["blue square", "answer delta"],
 ];
 
+// Structural-resonance is the LAST rung: it runs only when every DAG tier —
+// exact junction, single- and double-synonym — found no container at all.
+// SYN_ATTR_CORPUS cannot reach it, and no longer pretends to: every attribute
+// there shares a context ("is a color" / "is a shape") with its neighbours, so
+// the single-synonym tier always finds a bridge and accepts before the ladder
+// gets this far.  (It once did reach resonance, when the junction search was
+// phase-dependent and missed containers it should have found; asserting the
+// weaker rung still fires would now be asserting a defect.)
+//
+// This corpus withholds exactly what the synonym tiers need: each attribute's
+// context is unique, so no two attributes are halo siblings, and `red` and
+// `square` never co-occur.  `red then square` therefore exhausts the DAG tiers
+// and reaches resonance for real — one probe margin-rejected, one ineligible.
+const NO_BRIDGE_CORPUS = [
+  ["red", "warm hue"],
+  ["square", "four sides"],
+  ["circle", "round form"],
+  ["red circle", "answer alpha"],
+  ["blue square", "answer delta"],
+];
+
 // ═══════════════════════════════════════════════════════════════════════════
 // 1. ordinary-region contrastive rival.
 // ═══════════════════════════════════════════════════════════════════════════
@@ -204,8 +225,8 @@ test("5. double-synonym tier: probe fields report single returned zero and doubl
 
 test("6. structural-resonance: eligible probes report variants, merged proposals and an examined sequence with effectiveScore = annScore * semanticConfidence", async () => {
   const m = mk(1);
-  await m.ingest(SYN_ATTR_CORPUS);
-  const { steps } = await trace(m, "crimson then square");
+  await m.ingest(NO_BRIDGE_CORPUS);
+  const { steps } = await trace(m, "red then square");
   await m.store.close();
 
   const step = climbStep(steps);
@@ -262,10 +283,10 @@ test("6. structural-resonance: eligible probes report variants, merged proposals
 
 test("7. resonance outcomes: ineligible reasons are named and a margin-rejected probe reports a sub-noise-floor margin", async () => {
   const mIneligible = mk(1);
-  await mIneligible.ingest(SYN_ATTR_CORPUS);
+  await mIneligible.ingest(NO_BRIDGE_CORPUS);
   const { steps: ineligibleSteps } = await trace(
     mIneligible,
-    "crimson beside square",
+    "red then square",
   );
   await mIneligible.store.close();
 
@@ -286,9 +307,18 @@ test("7. resonance outcomes: ineligible reasons are named and a margin-rejected
     assert.equal(p.outcome, "resonance-ineligible");
   }
 
+  // A margin rejection needs resonance to actually PRODUCE a proposal and
+  // then find it indistinguishable from its runner-up.  On the tight
+  // `red then square` the single surviving proposal clears the noise floor and
+  // is accepted; spreading the two attributes apart puts many more pairs in
+  // play, and the pair that reaches resonance proposes an ANN neighbour its
+  // rival matches — which is exactly the case this field exists to report.
   const mMargin = mk(1);
-  await mMargin.ingest(SYN_ATTR_CORPUS);
-  const { steps: marginSteps } = await trace(mMargin, "crimson then square");
+  await mMargin.ingest(NO_BRIDGE_CORPUS);
+  const { steps: marginSteps } = await trace(
+    mMargin,
+    "red and a very long interior gap before square",
+  );
   await mMargin.store.close();
   const marginStep = climbStep(marginSteps);
   const marginRejected = (marginStep.data.crossRegion?.probes ?? []).filter(

package/test/54-evidence-k-instrumentation.test.mjs

@@ -0,0 +1,175 @@
+// 54-evidence-k-instrumentation.test.mjs — the three purely-additive
+// read-outs added for evidence-breadth measurement tooling:
+//   1. AncestorReach.visited / maxDepth (trace-gated, serialised into
+//      ClimbConsensusData.reaches),
+//   2. structured data payloads on "decideGrounding" / "narrowDecision",
+//   3. ingest()'s optional onDeposit provenance callback.
+//
+// Every assertion here checks a READ-OUT; the final test pins that none of
+// them changes the answer (the same invariant tests 52 §6 / 53 §9 pin for
+// the climb instrumentation).
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { decodeText, Mind } from "../dist/src/index.js";
+import { SQliteStore } from "../dist/src/store-sqlite.js";
+
+const mk = (seed = 1) =>
+  new Mind({ seed, store: new SQliteStore({ path: ":memory:" }) });
+
+const CORPUS = [
+  ["red", "is a color"],
+  ["blue", "is a color"],
+  ["circle", "is a shape"],
+  ["square", "is a shape"],
+  ["red circle", "answer alpha"],
+  ["red square", "answer beta"],
+  ["blue circle", "answer gamma"],
+  ["blue square", "answer delta"],
+];
+
+async function trace(mind, q) {
+  const steps = [];
+  const ans = await mind.respondText(q, (s) => steps.push(s));
+  return { steps, ans };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 1. climb read-out: visited / maxDepth
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("1. traced climb reaches carry visited/maxDepth; untraced ones do not", async () => {
+  const m = mk(1);
+  await m.ingest(CORPUS);
+
+  const { steps } = await trace(m, "red then circle");
+  const climb = steps.find((s) => s.mechanism.at(-1) === "climbConsensus");
+  assert.ok(climb?.data?.reaches?.length > 0, "expected reach traces");
+  for (const r of climb.data.reaches) {
+    assert.equal(typeof r.visited, "number");
+    assert.equal(typeof r.maxDepth, "number");
+    assert.ok(r.visited >= 0);
+    assert.ok(r.maxDepth >= 0);
+    // A climb that processed no node cannot have ascended.  (One processed
+    // node can already sit at depth 1: containment seeds start one hop up.)
+    if (r.visited === 0) assert.equal(r.maxDepth, 0);
+    // Depth is bounded by the number of processed nodes plus any
+    // transparent-chain interiors — sanity only: never negative, and zero
+    // whenever nothing was climbed.
+    assert.ok(r.maxDepth >= 0);
+  }
+
+  // Untraced (no respond in flight): the same contract as `saturation` —
+  // instrumentation fields absent when no trace was requested.
+  const someNode = climb.data.reaches[0].node;
+  const reach = m.edgeAncestors(someNode, 8);
+  assert.equal(reach.visited, undefined);
+  assert.equal(reach.maxDepth, undefined);
+  await m.store.close();
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 2. decideGrounding / narrowDecision data payloads
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("2. decideGrounding carries every candidate's weight/grade as data, exactly one decided", async () => {
+  const m = mk(1);
+  await m.ingest(CORPUS);
+  const { steps, ans } = await trace(m, "red then circle");
+  await m.store.close();
+
+  const dg = steps.find((s) => s.mechanism.at(-1) === "decideGrounding");
+  assert.ok(dg, "expected a decideGrounding step (≥2 candidates)");
+  assert.ok(dg.data, "decideGrounding must carry a data payload");
+  assert.equal(dg.data.version, 1);
+  assert.equal(dg.data.candidates.length, dg.inputs.length);
+  for (const c of dg.data.candidates) {
+    assert.equal(typeof c.provenance, "string");
+    assert.equal(typeof c.weight, "number");
+    assert.equal(typeof c.grade, "number");
+    assert.equal(typeof c.unexplainedBytes, "number");
+    assert.ok(c.unexplainedBytes >= 0);
+  }
+  const decided = dg.data.candidates.filter((c) => c.decided);
+  assert.equal(decided.length, 1, "exactly one candidate wins");
+  // The winner's grade is minimal — the data restates the decision rule.
+  const minGrade = Math.min(...dg.data.candidates.map((c) => c.grade));
+  assert.equal(decided[0].grade, minGrade);
+  assert.ok(ans.length > 0);
+
+  if (dg.data.runnerUpMargin !== undefined) {
+    assert.ok(dg.data.runnerUpMargin >= 0);
+    const nd = steps.find((s) => s.mechanism.at(-1) === "narrowDecision");
+    if (dg.data.runnerUpMargin <= 1) {
+      assert.ok(nd, "margin ≤ 1 must emit narrowDecision");
+      assert.equal(nd.data.version, 1);
+      assert.equal(nd.data.margin, dg.data.runnerUpMargin);
+    } else {
+      assert.equal(nd, undefined);
+    }
+  }
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 3. onDeposit provenance callback
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("3. onDeposit reports one item-indexed record per ingested item, ids content-addressed", async () => {
+  const m = mk(1);
+  const reports = [];
+  await m.ingest(CORPUS, undefined, (r) => reports.push(r));
+
+  assert.equal(reports.length, CORPUS.length);
+  reports.forEach((r, i) => {
+    assert.equal(r.index, i);
+    assert.equal(r.kind, "pair");
+    assert.equal(typeof r.contextId, "number");
+    assert.equal(typeof r.continuationId, "number");
+    // The reported ids ARE the items' content-addressed nodes.
+    assert.equal(decodeText(m.store.bytes(r.contextId)), CORPUS[i][0]);
+    assert.equal(decodeText(m.store.bytes(r.continuationId)), CORPUS[i][1]);
+  });
+  // Content addressing: identical continuations share one node id.
+  const colorIds = [reports[0], reports[1]].map((r) => r.continuationId);
+  assert.equal(colorIds[0], colorIds[1]);
+  await m.store.close();
+});
+
+test("3b. onDeposit reports bare items as kind 'one'; omitting it changes nothing", async () => {
+  const m = mk(1);
+  const reports = [];
+  await m.ingest(
+    ["standalone note", ["ctx", "cont"]],
+    undefined,
+    (r) => reports.push(r),
+  );
+  assert.deepEqual(reports.map((r) => [r.index, r.kind]), [[0, "one"], [
+    1,
+    "pair",
+  ]]);
+  assert.equal(reports[1].continuationId !== undefined, true);
+  assert.equal(reports[0].continuationId, undefined);
+  await m.store.close();
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 4. none of the read-outs changes the answer
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("4. answers are identical with and without the new read-outs attached", async () => {
+  const ask = async (withHooks) => {
+    const m = mk(7);
+    await m.ingest(CORPUS, undefined, withHooks ? () => {} : undefined);
+    const out = [];
+    for (
+      const q of ["red then circle", "red circle blue square", "blue square"]
+    ) {
+      out.push(
+        withHooks ? await m.respondText(q, () => {}) : await m.respondText(q),
+      );
+    }
+    await m.store.close();
+    return out;
+  };
+  assert.deepEqual(await ask(true), await ask(false));
+});

package/test/55-cost-meter.test.mjs

@@ -0,0 +1,284 @@
+// 55-cost-meter.test.mjs — the cross-stack computational-usage meter
+// (src/meter.ts).
+//
+// The meter's four contracts, one test each:
+//   1. OFF BY DEFAULT — an unprofiled Mind never attaches one, and the store
+//      is left with no meter after a response either way.
+//   2. NEVER READ BY INFERENCE — profiled and unprofiled answers are
+//      byte-identical, and so is the provenance.
+//   3. COUNTS ARE DETERMINISTIC — the same query on the same store meters
+//      identically (only the millisecond fields may differ).
+//   4. THE WHOLE STACK REPORTS — store reads, perception, recognition,
+//      the mechanism market and the graph search all appear.
+//
+// Plus the two aggregation helpers (sumReports, formatReport) and the
+// multi-turn lifecycle (respondTurn meters through the SAME beginResponse /
+// endResponse pair respond() uses).
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { formatReport, Mind, sumReports } from "../dist/src/index.js";
+import { SQliteStore } from "../dist/src/store-sqlite.js";
+
+const mk = (opts = {}) =>
+  new Mind({ seed: 1, store: new SQliteStore({ path: ":memory:" }), ...opts });
+
+/** A small store with enough structure that every layer does some work. */
+async function trained(opts) {
+  const mind = mk(opts);
+  await mind.ingest([
+    ["the capital of France is", " Paris"],
+    ["the capital of Japan is", " Tokyo"],
+    ["the capital of Italy is", " Rome"],
+    ["Paris is in", " Europe"],
+    ["Tokyo is in", " Asia"],
+  ]);
+  return mind;
+}
+
+const QUERY = "the capital of France is";
+
+test("1. profiling is off by default and leaves no meter on the store", async () => {
+  const mind = await trained();
+  assert.equal(mind.lastCost, null);
+  await mind.respondText(QUERY);
+  assert.equal(mind.lastCost, null, "no report without { profile: true }");
+  assert.equal(mind.store.meter, null, "store meter never attached");
+  assert.equal(mind.meter, null);
+  await mind.store.close();
+});
+
+test("2. profiling never changes the answer", async () => {
+  const plain = await trained();
+  const profiled = await trained({ profile: true });
+
+  for (const q of [QUERY, "Paris is in", "the capital of Japan is", "zzz"]) {
+    const a = await plain.respond(q);
+    const b = await profiled.respond(q);
+    assert.deepEqual(
+      Array.from(b.bytes),
+      Array.from(a.bytes),
+      `answer changed under profiling for "${q}"`,
+    );
+    assert.equal(b.provenance, a.provenance);
+  }
+  await plain.store.close();
+  await profiled.store.close();
+});
+
+test("3. the meter is detached and the report published after each response", async () => {
+  const mind = await trained({ profile: true });
+  await mind.respondText(QUERY);
+
+  assert.equal(mind.meter, null, "meter torn down with the response");
+  assert.equal(mind.store.meter, null, "store detached — no cross-charging");
+
+  const r = mind.lastCost;
+  assert.ok(r, "a report was published");
+  assert.equal(r.version, 1);
+  assert.equal(r.queryBytes, QUERY.length);
+  assert.ok(r.elapsedMs >= 0);
+  await mind.store.close();
+});
+
+test("4. counters are deterministic across identical calls on identical stores", async () => {
+  const a = await trained({ profile: true });
+  const b = await trained({ profile: true });
+  await a.respondText(QUERY);
+  await b.respondText(QUERY);
+  assert.deepEqual(
+    a.lastCost.counters,
+    b.lastCost.counters,
+    "same query + same store ⇒ same work; a diff here is a real regression",
+  );
+  // Phase CALL counts are deterministic too (their millisecond totals are not).
+  const calls = (r) =>
+    Object.fromEntries(
+      Object.entries(r.phases).map(([k, v]) => [k, v.calls]),
+    );
+  assert.deepEqual(calls(a.lastCost), calls(b.lastCost));
+  await a.store.close();
+  await b.store.close();
+});
+
+test("5. every layer of the stack reports", async () => {
+  const mind = await trained({ profile: true });
+  await mind.respondText(QUERY);
+  const c = mind.lastCost.counters;
+
+  // Store layer — identity, content, structure.
+  assert.ok(c.leafLookups > 0, "content-addressed leaf lookups counted");
+  assert.ok(c.branchLookups > 0, "content-addressed branch lookups counted");
+  assert.ok(c.byteReads > 0, "node byte reads counted");
+  assert.ok(c.bytesRead > 0, "read VOLUME counted, not just call count");
+
+  // Mind layer — perception and recognition.
+  assert.ok(c.perceptions > 0, "perceptions counted");
+  assert.ok(c.perceivedBytes >= c.perceptions, "perceived volume counted");
+  assert.ok(c.recognitions > 0, "recognitions counted");
+  assert.ok(c.resolves > 0, "identity resolutions counted");
+
+  // The mechanism market — every mechanism was offered the query.
+  assert.ok(
+    c.mechanismFloors + c.mechanismSkips >= 5,
+    "each built-in mechanism's floor() was accounted",
+  );
+  assert.ok(c.mechanismRuns > 0, "at least one mechanism ran");
+  assert.ok(c.candidates > 0, "candidates weighed");
+
+  // Phases are per-mechanism and named after the mechanism itself.
+  const phases = Object.keys(mind.lastCost.phases);
+  assert.ok(phases.includes("think"));
+  assert.ok(phases.includes("articulate"));
+  assert.ok(
+    phases.some((p) => p.endsWith(".floor")),
+    "per-mechanism floor phases present",
+  );
+  await mind.store.close();
+});
+
+test("6. zero-valued counters are omitted, and no bookkeeping leaks in", async () => {
+  const mind = await trained({ profile: true });
+  await mind.respondText(QUERY);
+  const c = mind.lastCost.counters;
+  for (const [k, v] of Object.entries(c)) {
+    assert.notEqual(v, 0, `${k} is zero and should have been dropped`);
+    assert.ok(!k.startsWith("_"), `${k} is meter bookkeeping, not work`);
+  }
+  await mind.store.close();
+});
+
+test("7. a bigger query costs more than a smaller one", async () => {
+  const mind = await trained({ profile: true });
+  await mind.respondText("Paris");
+  const small = mind.lastCost.counters;
+  await mind.respondText(
+    "the capital of France is and the capital of Japan is and Paris is in",
+  );
+  const big = mind.lastCost.counters;
+  assert.ok(
+    big.perceivedBytes > small.perceivedBytes,
+    "perception cost tracks query length",
+  );
+  await mind.store.close();
+});
+
+test("8. respondTurn meters through the same lifecycle", async () => {
+  const mind = await trained({ profile: true });
+  const conv = mind.beginConversation();
+  await mind.respondTurnText(conv, "the capital of France is");
+  const first = mind.lastCost;
+  assert.ok(first, "a turn publishes a report");
+  assert.ok(first.counters.perceptions > 0);
+  assert.equal(mind.store.meter, null, "detached after the turn too");
+
+  await mind.respondTurnText(conv, "Paris is in");
+  const second = mind.lastCost;
+  assert.notEqual(second, null);
+  assert.ok(
+    second.queryBytes > first.queryBytes,
+    "a turn is metered against the ACCUMULATED context, which grows",
+  );
+  mind.endConversation(conv);
+  await mind.store.close();
+});
+
+test("9. conversation memos survive the shared lifecycle (turn 2 re-uses turn 1)", async () => {
+  const mind = await trained({ profile: true });
+  const conv = mind.beginConversation();
+  await mind.respondTurnText(conv, "the capital of France is");
+  await mind.respondTurnText(conv, "the capital of Japan is");
+  const c = mind.lastCost.counters;
+  // The conversation's perceive/recognise memos are swapped in by
+  // beginResponse; the second turn must therefore HIT them for the prefix it
+  // shares with the first.  A zero here means respondTurn stopped carrying
+  // the conversation's persistent state — the exact drift the shared
+  // lifecycle exists to prevent.
+  assert.ok(
+    (c.perceiveHits ?? 0) > 0 || (c.recogniseHits ?? 0) > 0,
+    "the prefix's earlier results were re-used across turns",
+  );
+  mind.endConversation(conv);
+  await mind.store.close();
+});
+
+test("9b. every phase reports the work done inside it, and phases nest", async () => {
+  const mind = await trained({ profile: true });
+  await mind.respondText(QUERY);
+  const { phases, counters } = mind.lastCost;
+
+  // Each phase carries counter deltas, not just a duration.
+  const withWork = Object.entries(phases).filter(([, p]) =>
+    Object.keys(p.counters).length > 0
+  );
+  assert.ok(withWork.length > 0, "phases attribute work, not only time");
+
+  // `think` is the outermost inference phase, so its counters must DOMINATE
+  // every phase nested inside it — that is what "inclusive" means, and it is
+  // the property that makes the deltas readable as attribution.
+  const think = phases["think"];
+  assert.ok(think, "think is a phase");
+  for (const [name, p] of Object.entries(phases)) {
+    if (name === "think" || name === "articulate") continue;
+    for (const [k, v] of Object.entries(p.counters)) {
+      assert.ok(
+        (think.counters[k] ?? 0) >= v,
+        `${name}.${k}=${v} exceeds think.${k}=${think.counters[k] ?? 0} — ` +
+          `phases must nest`,
+      );
+    }
+  }
+  // And no phase may claim more of a counter than the whole response spent.
+  for (const [name, p] of Object.entries(phases)) {
+    for (const [k, v] of Object.entries(p.counters)) {
+      assert.ok(
+        (counters[k] ?? 0) >= v,
+        `${name}.${k}=${v} exceeds the response total ${counters[k] ?? 0}`,
+      );
+    }
+  }
+  await mind.store.close();
+});
+
+test("9c. a recursive read is one read, not one per node descended", async () => {
+  const mind = await trained({ profile: true });
+  await mind.respondText(QUERY);
+  const c = mind.lastCost.counters;
+  // bytesRead is the byte VOLUME, byteReads the number of read REQUESTS.
+  // Reconstructing a branch used to charge one read per node descended, which
+  // made byteReads track tree size — it read as ~1 byte per read.  Real reads
+  // return whole forms, so the volume must comfortably exceed the count.
+  assert.ok(c.byteReads > 0 && c.bytesRead > 0);
+  assert.ok(
+    c.bytesRead > c.byteReads,
+    `bytesRead ${c.bytesRead} should exceed byteReads ${c.byteReads} — ` +
+      `a per-node charge would invert this`,
+  );
+  await mind.store.close();
+});
+
+test("10. sumReports and formatReport aggregate a battery", async () => {
+  const mind = await trained({ profile: true });
+  const reports = [];
+  for (const q of [QUERY, "Paris is in", "the capital of Italy is"]) {
+    await mind.respondText(q);
+    reports.push(mind.lastCost);
+  }
+  const total = sumReports(reports);
+  assert.equal(total.version, 1);
+  assert.equal(
+    total.queryBytes,
+    reports.reduce((s, r) => s + r.queryBytes, 0),
+  );
+  for (const key of Object.keys(reports[0].counters)) {
+    assert.equal(
+      total.counters[key],
+      reports.reduce((s, r) => s + (r.counters[key] ?? 0), 0),
+      `${key} did not sum`,
+    );
+  }
+  const text = formatReport(total);
+  assert.match(text, /^cost: /);
+  assert.match(text, /perceptions/);
+  await mind.store.close();
+});