@hviana/sema 0.2.4 → 0.2.6

package/test/52-climb-consensus-instrumentation.test.mjs

@@ -0,0 +1,324 @@
+// 52-climb-consensus-instrumentation.test.mjs — structured instrumentation
+// for the climbConsensus / inspectRationale step (spec §10).
+//
+// Purely additive: every assertion here checks the STRUCTURE of the `data`
+// payload a traced "climbConsensus" RationaleStep now carries, alongside the
+// existing human-readable `note` — never that inference itself changed
+// (item 6 pins that explicitly: roots/ranked must be bit-identical whether
+// or not a trace was requested).
+
+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";
+import { climbAttentionAll } from "../dist/src/mind/attention.js";
+import { Rationale } from "../dist/src/mind/rationale.js";
+
+const enc = (s) => new TextEncoder().encode(s);
+const mk = (seed = 1) =>
+  new Mind({ seed, store: new SQliteStore({ path: ":memory:" }) });
+
+/** Collect the full step stream for one traced query. */
+async function trace(mind, q) {
+  const steps = [];
+  const ans = await mind.respondText(q, (s) => steps.push(s));
+  return { steps, ans };
+}
+
+/** The FIRST "climbConsensus" step — the one whose data reflects the actual
+ *  per-region pipeline (a later same-response call, if any, would hit the
+ *  content-keyed climb memo). */
+function climbStep(steps) {
+  return steps.find((s) => s.mechanism.at(-1) === "climbConsensus");
+}
+
+const SATURATION_REASONS = new Set([
+  "byte-atom-commonality",
+  "predecessor-fan-in",
+  "distinct-context-limit",
+  "parent-fan-out",
+  "lateral-cone-limit",
+]);
+
+const ATTR_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"],
+];
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 1. every saturation stop reports one of the five reasons, with sound
+//    observed/limit provenance — read off the authoritative `reaches` list.
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("1. every reported saturation stop names a valid reason with sound provenance", async () => {
+  const m = mk(1);
+  await m.ingest(ATTR_CORPUS);
+  const { steps } = await trace(m, "red circle blue square");
+  await m.store.close();
+
+  const step = climbStep(steps);
+  assert.ok(step, "expected a climbConsensus step");
+  assert.ok(step.data, "climbConsensus step must carry a data payload");
+  assert.equal(step.data.version, 1);
+  assert.ok(Array.isArray(step.data.reaches), "expected a reaches list");
+
+  for (const r of step.data.reaches) {
+    assert.equal(typeof r.node, "number");
+    assert.ok(Array.isArray(r.roots));
+    assert.equal(typeof r.contextsReached, "number");
+    assert.equal(typeof r.saturated, "boolean");
+    if (r.saturated && r.saturation) {
+      assert.ok(
+        SATURATION_REASONS.has(r.saturation.reason),
+        `unexpected saturation reason "${r.saturation.reason}"`,
+      );
+      assert.equal(typeof r.saturation.node, "number");
+      assert.ok(r.saturation.observed > r.saturation.limit);
+    }
+  }
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 2. canonical vs ANN/fallback regions report correct examined breadth.
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("2. an exact chunk region is selected canonically, without an ANN query", async () => {
+  const m = mk(2);
+  await m.ingest(ATTR_CORPUS);
+  // "red then circle" is not itself a trained fact (only "red circle" is),
+  // so recall cannot resolve it directly and the consensus climb runs.
+  const { steps } = await trace(m, "red then circle");
+  await m.store.close();
+
+  const step = climbStep(steps);
+  assert.ok(step, "expected a climbConsensus step");
+  assert.ok(step.data, "climbConsensus step must carry a data payload");
+  const regions = step.data.regions ?? [];
+  assert.ok(regions.length > 0, "expected per-region traces");
+
+  const votedRegions = regions.filter((r) => r.outcome === "voted");
+  assert.ok(votedRegions.length > 0, "expected at least one voted region");
+  for (const r of votedRegions) {
+    assert.ok(r.selected, "a voted region must report its selection");
+    assert.ok(
+      r.selected.source === "canonical" || r.selected.source === "ann",
+      "selected.source must be canonical or ann",
+    );
+    if (r.selected.source === "canonical") {
+      assert.equal(r.canonicalUsable, true);
+    }
+    if (r.selected.source === "ann" && !r.selected.fallback) {
+      assert.equal(r.annQueried, true);
+      assert.equal(typeof r.selected.rank, "number");
+    }
+    // annHitsExamined counts distinct CONSULTED hits, never more than what
+    // was returned.
+    assert.ok(r.annHitsExamined <= r.annHitsReturned || !r.annQueried);
+  }
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 3/4. candidateBreadth / contributingVotes / contributingEvidence differ
+//      correctly under junction absorption, and superseded / saturation-
+//      masked votes never inflate contributingEvidence.
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("3/4. junction absorption widens contributingEvidence past contributingVotes", async () => {
+  const m = mk(3);
+  await m.ingest(ATTR_CORPUS);
+  const { steps } = await trace(m, "red then circle");
+  await m.store.close();
+
+  const step = climbStep(steps);
+  assert.ok(step.data.crossRegion, "expected a crossRegion summary");
+  assert.ok(
+    step.data.crossRegion.junctionVotes.length > 0,
+    "expected the exact junction to fire ('red circle' is a trained joint fact)",
+  );
+  const jv = step.data.crossRegion.junctionVotes[0];
+  assert.equal(jv.tier, "exact");
+  assert.ok(Array.isArray(jv.sourceRegionIndices));
+  assert.ok(Array.isArray(jv.explainedAwayRegionIndices));
+  assert.ok(jv.absorbed >= 1);
+
+  const anchors = step.data.anchors ?? [];
+  assert.ok(anchors.length > 0, "expected ranked anchor traces");
+  for (const a of anchors) {
+    // contributingEvidence is regionSupport (absorbed-weighted); it must
+    // never be LESS than the raw pooled-axiom count.
+    assert.ok(a.contributingEvidence >= a.contributingVotes);
+    assert.equal(typeof a.candidateBreadth, "number");
+    assert.ok(a.candidateBreadth >= a.contributingVotes);
+  }
+
+  // A region the junction explained away must be marked superseded on the
+  // per-region trace, and superseded regions never produced an ordinary
+  // vote that also counts toward contributingEvidence twice.
+  const regions = step.data.regions ?? [];
+  const supersededRegions = regions.filter((r) => r.superseded);
+  for (const r of supersededRegions) {
+    assert.equal(
+      r.ordinaryVoteProduced,
+      true,
+      "only a voted region can be superseded",
+    );
+  }
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 5. commit reasons match the existing commitVotes loop.
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("5. commit decisions on the anchor trace match the roots actually returned", async () => {
+  const m = mk(4);
+  await m.ingest(ATTR_CORPUS);
+  const { steps } = await trace(m, "red circle blue square");
+  await m.store.close();
+
+  const step = climbStep(steps);
+  const anchors = step.data.anchors ?? [];
+  assert.ok(anchors.length > 0);
+  const roots = step.data.result.roots;
+  const rootAnchors = new Set(roots.map((r) => r.anchor));
+
+  for (const a of anchors) {
+    if (a.commit.status === "root") {
+      assert.ok(
+        rootAnchors.has(a.anchor),
+        `anchor ${a.anchor} marked root but absent from result.roots`,
+      );
+      assert.equal(a.commit.rejectionReasons.length, 0);
+    } else {
+      assert.ok(!rootAnchors.has(a.anchor) || a.commit.status === "overlap");
+    }
+    if (a.commit.status === "rejected") {
+      assert.ok(
+        a.commit.rejectionReasons.length > 0,
+        "a rejected anchor must name at least one reason",
+      );
+      for (const reason of a.commit.rejectionReasons) {
+        assert.ok(
+          ["below-natural-break", "below-consensus-floor", "leading-saturation"]
+            .includes(reason),
+        );
+      }
+    }
+  }
+  // The dominant (first) root never carries the two vote-threshold gates.
+  const dominant = anchors.find((a) => a.commit.dominant);
+  if (dominant) {
+    assert.equal(dominant.commit.status, "root");
+    assert.equal(dominant.commit.passesNaturalBreak, undefined);
+    assert.equal(dominant.commit.passesConsensusFloor, undefined);
+  }
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 6. roots and ranked results are bit-identical with and without tracing.
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("6. inspectRationale never changes the answer or the traced result.roots/ranked", async () => {
+  const queries = [
+    "red circle",
+    "red then circle",
+    "blue square",
+    "red",
+    "circle blue",
+  ];
+  for (const q of queries) {
+    const plainMind = mk(5);
+    await plainMind.ingest(ATTR_CORPUS);
+    const plainAns = await plainMind.respondText(q);
+    await plainMind.store.close();
+
+    const tracedMind = mk(5);
+    await tracedMind.ingest(ATTR_CORPUS);
+    const { ans: tracedAns, steps } = await trace(tracedMind, q);
+    await tracedMind.store.close();
+
+    assert.equal(
+      tracedAns,
+      plainAns,
+      `answer differs for query "${q}" — tracing must be purely additive`,
+    );
+
+    // Cross-check the climb itself: the untraced mind-level climbAttention
+    // convenience (never touches ctx.trace) must agree with the roots the
+    // traced climbConsensus step reported in its `data.result`.
+    const untracedMind = mk(5);
+    await untracedMind.ingest(ATTR_CORPUS);
+    const untracedRoots = await untracedMind.climbAttention(enc(q), 24);
+    await untracedMind.store.close();
+
+    const step = climbStep(steps);
+    if (step?.data) {
+      assert.deepEqual(
+        JSON.parse(JSON.stringify(step.data.result.roots)),
+        JSON.parse(JSON.stringify(untracedRoots)),
+        `traced result.roots differ from the untraced climb for query "${q}"`,
+      );
+    }
+  }
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 7. a repeated query produces the abbreviated cache-hit payload (§9).
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("7. a repeated query within one response emits the abbreviated cache trace", async () => {
+  const m = mk(7);
+  await m.ingest(ATTR_CORPUS);
+  // A top-level respond() gets a FRESH climbMemo every call (by design —
+  // beginResponse()), so a real cache hit is only observable by driving
+  // climbAttentionAll directly against a climbMemo that persists across
+  // two calls — exactly what respondTurn() does for a real conversation
+  // (see AttentionRead cache doc on climbAttentionAll).
+  m.climbMemo = new Map();
+  m.recogniseMemo = new Map();
+  m.perceiveMemo = new Map();
+  m.canon = null;
+  m.canonMemo = null;
+
+  const q = enc("red then circle");
+  const steps1 = [];
+  m.trace = new Rationale((s) => steps1.push(s));
+  await climbAttentionAll(m, q, 12, "inverse");
+
+  const steps2 = [];
+  m.trace = new Rationale((s) => steps2.push(s));
+  await climbAttentionAll(m, q, 12, "inverse");
+  await m.store.close();
+
+  const first = climbStep(steps1);
+  const second = climbStep(steps2);
+  assert.ok(first, "expected a climbConsensus step on the first call");
+  assert.ok(second, "expected a climbConsensus step on the repeated call");
+
+  assert.equal(first.data.cache.hit, false);
+  assert.equal(second.data.cache.hit, true);
+  assert.equal(second.data.cache.detailAvailable, false);
+  assert.equal(second.data.version, 1);
+  assert.deepEqual(second.data.config, {
+    annK: second.data.config.annK,
+    crossRegionProbeLimit: second.data.config.annK,
+    mode: second.data.config.mode,
+  });
+  assert.deepEqual(second.data.candidates, {
+    perceived: 0,
+    recognised: 0,
+    total: 0,
+  });
+  assert.equal(second.data.regions, undefined);
+  assert.equal(second.data.reaches, undefined);
+  assert.equal(second.data.crossRegion, undefined);
+  assert.equal(second.data.saturation, undefined);
+  assert.equal(second.data.pooling, undefined);
+  assert.equal(second.data.anchors, undefined);
+  assert.ok(second.data.result, "abbreviated payload must still carry result");
+});

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

@@ -0,0 +1,356 @@
+// 53-cross-region-probe-instrumentation.test.mjs — extends the climbConsensus
+// instrumentation (test/52) to cover the ordinary-region contrastive rival,
+// the cross-region junction probe ladder, and structural-resonance.  Purely
+// additive: every assertion checks the STRUCTURE of the `data` payload's new
+// fields — never that inference itself changed.
+
+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 mk = (seed = 1) =>
+  new Mind({ seed, store: new SQliteStore({ path: ":memory:" }) });
+
+async function trace(mind, q) {
+  const steps = [];
+  const ans = await mind.respondText(q, (s) => steps.push(s));
+  return { steps, ans };
+}
+
+function climbStep(steps) {
+  return steps.find((s) => s.mechanism.at(-1) === "climbConsensus");
+}
+
+// Reused verbatim from test/51's proven fixtures.
+const ATTR_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"],
+];
+
+const SYN_ATTR_CORPUS = [
+  ["red", "is a color"],
+  ["crimson", "is a color"],
+  ["blue", "is a color"],
+  ["circle", "is a shape"],
+  ["square", "is a shape"],
+  ["red circle", "answer alpha"],
+  ["crimson circle", "answer alpha2"],
+  ["red square", "answer beta"],
+  ["blue circle", "answer gamma"],
+  ["blue square", "answer delta"],
+];
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 1. ordinary-region contrastive rival.
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("1. an approximate region with a genuine rival reports contrastiveRival, and the margin matches score - rival.score", async () => {
+  const m = mk(1);
+  await m.ingest(ATTR_CORPUS);
+  const { steps } = await trace(m, "blue then circle then square");
+  await m.store.close();
+
+  const step = climbStep(steps);
+  assert.ok(step?.data, "expected a traced climbConsensus step");
+  const regions = step.data.regions ?? [];
+  const withRival = regions.filter((r) => r.contrastiveRival);
+  assert.ok(withRival.length > 0, "expected at least one region with a rival");
+  for (const r of withRival) {
+    assert.equal(typeof r.contrastiveRival.node, "number");
+    assert.equal(typeof r.contrastiveRival.rank, "number");
+    assert.equal(typeof r.contrastiveRival.score, "number");
+    assert.ok(
+      Math.abs(
+        r.contrastiveMargin - (r.selected.score - r.contrastiveRival.score),
+      ) < 1e-9,
+      "contrastiveMargin must equal selected.score - contrastiveRival.score",
+    );
+  }
+});
+
+test("1b. a known region never carries a contrastiveRival (the contrast only applies to approximate regions)", async () => {
+  const m = mk(1);
+  await m.ingest(ATTR_CORPUS);
+  const { steps } = await trace(m, "red then circle");
+  await m.store.close();
+
+  const step = climbStep(steps);
+  const regions = step.data.regions ?? [];
+  for (const r of regions) {
+    if (r.known) {
+      assert.equal(r.contrastiveRival, undefined);
+      assert.equal(r.contrastiveMargin, undefined);
+    }
+  }
+  // And when a voted approximate region has NO rival at all, contrastiveMargin
+  // stays exactly selected.score, with no contrastiveRival field.
+  for (const r of regions) {
+    if (r.outcome === "voted" && !r.known && r.contrastiveRival === undefined) {
+      assert.equal(r.contrastiveMargin, r.selected.score);
+    }
+  }
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 2. probe accounting invariant.
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("2. crossRegion.probes.length === crossRegion.probesAttempted", async () => {
+  const m = mk(1);
+  await m.ingest(SYN_ATTR_CORPUS);
+  const { steps } = await trace(m, "the crimson near the square");
+  await m.store.close();
+
+  const step = climbStep(steps);
+  const cr = step.data.crossRegion;
+  assert.ok(cr, "expected a crossRegion summary");
+  assert.equal(cr.probes.length, cr.probesAttempted);
+  assert.ok(
+    ["insufficient-regions", "probe-limit", "pairs-exhausted"].includes(
+      cr.stopReason,
+    ),
+  );
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 3. exact junction: attempt count, accepted structural outcome, vote-probe
+//    link.
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("3. exact junction: probe.exact attempted with candidates, accepted structural outcome, and vote links back to its probe", async () => {
+  const m = mk(3);
+  await m.ingest(ATTR_CORPUS);
+  const { steps } = await trace(m, "red then circle");
+  await m.store.close();
+
+  const step = climbStep(steps);
+  const cr = step.data.crossRegion;
+  assert.ok(cr.junctionVotes.length > 0);
+  const jv = cr.junctionVotes[0];
+  assert.equal(jv.tier, "exact");
+  assert.equal(typeof jv.probe, "number");
+  const probe = cr.probes[jv.probe];
+  assert.ok(probe, "vote's probe index must resolve into crossRegion.probes");
+  assert.equal(probe.exact.attempted, true);
+  assert.ok(probe.exact.candidatesReturned > 0);
+  assert.ok(probe.structural, "expected a structural trace on this probe");
+  assert.equal(probe.structural.outcome, "accepted");
+  assert.equal(probe.outcome, "accepted");
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 4. single-synonym junction.
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("4. single-synonym junction: exact returns zero, single attempted and returns candidates, selected single-synonym tier", async () => {
+  const m = mk(1);
+  await m.ingest(SYN_ATTR_CORPUS);
+  // "square then crimson" — order-free single-sibling substitution recovers
+  // 'red square' via crimson's sibling 'red' (mirrors test/51's synRight).
+  const { steps } = await trace(m, "square then crimson");
+  await m.store.close();
+
+  const step = climbStep(steps);
+  const cr = step.data.crossRegion;
+  assert.ok(cr.junctionVotes.length > 0);
+  const jv = cr.junctionVotes.find((v) => v.tier === "single-synonym");
+  assert.ok(jv, "expected a single-synonym junction vote");
+  const probe = cr.probes[jv.probe];
+  assert.equal(probe.exact.candidatesReturned, 0);
+  assert.equal(probe.singleSynonym.attempted, true);
+  assert.ok(probe.singleSynonym.candidatesReturned > 0);
+  assert.equal(probe.structural.tier, "single-synonym");
+  assert.equal(probe.structural.outcome, "accepted");
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 5. double-synonym junction: verify the ladder position and fields.
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("5. double-synonym tier: probe fields report single returned zero and double attempted when only the double tier can fire", async () => {
+  const m = mk(1);
+  await m.ingest(SYN_ATTR_CORPUS);
+  const { steps } = await trace(m, "crimson then crimson");
+  await m.store.close();
+
+  const step = climbStep(steps);
+  const cr = step.data.crossRegion ?? { probes: [] };
+  // Whether or not a double-synonym container was actually found (fixture-
+  // sensitive per test/51's own test 4), every probe that attempted the
+  // synonym ladder must report single/double consistently: double is only
+  // ever attempted when single returned zero.
+  for (const p of cr.probes) {
+    if (p.doubleSynonym.attempted) {
+      assert.equal(p.singleSynonym.candidatesReturned, 0);
+      assert.equal(p.singleSynonym.attempted, true);
+    }
+    if (p.singleSynonym.candidatesReturned > 0) {
+      assert.equal(p.doubleSynonym.attempted, false);
+    }
+  }
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 6. structural resonance: variants, budget, hits, merged proposals,
+//    examined sequence, margin, noise floor, outcome.
+// ═══════════════════════════════════════════════════════════════════════════
+
+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.store.close();
+
+  const step = climbStep(steps);
+  const cr = step.data.crossRegion;
+  const eligible = cr.probes.filter((p) =>
+    p.resonance && p.resonance.outcome !== "ineligible"
+  );
+  assert.ok(
+    eligible.length > 0,
+    "expected at least one eligible resonance probe",
+  );
+  for (const p of eligible) {
+    const res = p.resonance;
+    assert.equal(res.variantBudget, m.cfg.haloQueryK);
+    assert.ok(Array.isArray(res.variants));
+    assert.ok(res.variants.length > 0);
+    for (const v of res.variants) {
+      assert.equal(typeof v.semanticConfidence, "number");
+      assert.equal(typeof v.annHitsReturned, "number");
+    }
+    assert.equal(typeof res.mergedProposals, "number");
+    assert.ok(Array.isArray(res.examined));
+    for (const c of res.examined) {
+      assert.ok(
+        Math.abs(c.effectiveScore - c.annScore * c.semanticConfidence) < 1e-9,
+      );
+      assert.ok(
+        [
+          "saturated",
+          "no-roots",
+          "nonpositive-idf",
+          "same-as-endpoint",
+          "same-as-selected",
+          "selected",
+          "contrastive-rival",
+        ].includes(c.outcome),
+      );
+    }
+    assert.equal(typeof res.noiseFloor, "number");
+    assert.ok(
+      ["empty", "no-valid-proposal", "margin-rejected", "accepted"].includes(
+        res.outcome,
+      ),
+    );
+    if (res.outcome === "accepted" || res.outcome === "margin-rejected") {
+      assert.equal(typeof res.contrastiveMargin, "number");
+    }
+  }
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 7. resonance rejection outcomes.
+// ═══════════════════════════════════════════════════════════════════════════
+
+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);
+  const { steps: ineligibleSteps } = await trace(
+    mIneligible,
+    "crimson beside square",
+  );
+  await mIneligible.store.close();
+
+  const ineligibleStep = climbStep(ineligibleSteps);
+  const ineligible = (ineligibleStep.data.crossRegion?.probes ?? []).filter(
+    (p) => p.resonance?.outcome === "ineligible",
+  );
+  assert.ok(ineligible.length > 0, "expected at least one ineligible probe");
+  for (const p of ineligible) {
+    assert.ok(Array.isArray(p.resonance.ineligibleReasons));
+    assert.ok(p.resonance.ineligibleReasons.length > 0);
+    for (const r of p.resonance.ineligibleReasons) {
+      assert.ok(
+        ["between-region", "not-both-strong", "not-both-known", "gap-too-large"]
+          .includes(r),
+      );
+    }
+    assert.equal(p.outcome, "resonance-ineligible");
+  }
+
+  const mMargin = mk(1);
+  await mMargin.ingest(SYN_ATTR_CORPUS);
+  const { steps: marginSteps } = await trace(mMargin, "crimson then square");
+  await mMargin.store.close();
+  const marginStep = climbStep(marginSteps);
+  const marginRejected = (marginStep.data.crossRegion?.probes ?? []).filter(
+    (p) => p.resonance?.outcome === "margin-rejected",
+  );
+  assert.ok(marginRejected.length > 0, "expected a margin-rejected probe");
+  for (const p of marginRejected) {
+    assert.ok(p.resonance.contrastiveMargin <= p.resonance.noiseFloor);
+    assert.equal(p.outcome, "resonance-rejected");
+  }
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 8. cross-region vote weight fields.
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("8. a linked cross-region vote reports confidence, evidenceBytes, mutualWeight, voteWeightPerRoot as numbers", async () => {
+  const m = mk(3);
+  await m.ingest(ATTR_CORPUS);
+  const { steps } = await trace(m, "red then circle");
+  await m.store.close();
+
+  const step = climbStep(steps);
+  const jv = step.data.crossRegion.junctionVotes[0];
+  assert.equal(typeof jv.confidence, "number");
+  assert.equal(typeof jv.evidenceBytes, "number");
+  assert.equal(typeof jv.mutualWeight, "number");
+  assert.equal(typeof jv.voteWeightPerRoot, "number");
+  assert.equal(jv.confidence, 1); // exact tier: confidence collapses to 1
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 9. additive behavior — the new fields never change roots/ranked/answer.
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("9. enabling the extended instrumentation never changes roots, ranked, or the answer", async () => {
+  const queries = [
+    "red then circle",
+    "square then crimson",
+    "crimson then square",
+    "crimson then crimson",
+    "the crimson near the square",
+  ];
+  for (const q of queries) {
+    const plain = mk(9);
+    await plain.ingest(SYN_ATTR_CORPUS);
+    const plainAns = await plain.respondText(q);
+    await plain.store.close();
+
+    const traced = mk(9);
+    await traced.ingest(SYN_ATTR_CORPUS);
+    const { ans: tracedAns, steps } = await trace(traced, q);
+    await traced.store.close();
+
+    assert.equal(tracedAns, plainAns, `answer differs for "${q}"`);
+
+    const step = climbStep(steps);
+    if (step?.data?.crossRegion) {
+      // The probe/resonance instrumentation is present but does not affect
+      // the pooled result: roots/ranked come from the SAME vote objects the
+      // probes were recorded from.
+      assert.ok(Array.isArray(step.data.crossRegion.probes));
+    }
+  }
+});

package/dist/example/demo.d.ts

@@ -1 +0,0 @@
-export {};