@remnic/core 9.69.5 → 9.69.7

package/src/extraction-span-source-hash.ts

@@ -0,0 +1,100 @@
+/**
+ * Span source stamp/verify (issue #2333).
+ *
+ * Offsets index the exact normalized string sent to the model. If that string
+ * drifts before materialization, the offsets point at different characters and
+ * a wrong quote is persisted as verbatim source. The stamp lets materialization
+ * detect the drift without carrying the source text alongside it.
+ *
+ * Pure apart from hashing: no I/O, no clock, no randomness. The input text is
+ * never mutated and never appears in a result or error message.
+ */
+
+import { createHash } from "node:crypto";
+
+export interface SpanSourceStamp {
+  /** Hex digest of the exact string the model was shown. */
+  hash: string;
+  /** Length of that string, so a mismatch reports which dimension drifted. */
+  length: number;
+}
+
+export type SpanSourceCheck =
+  | { ok: true }
+  | {
+      ok: false;
+      error: "length_mismatch" | "hash_mismatch";
+      expected: SpanSourceStamp;
+      actual: SpanSourceStamp;
+    };
+
+const HASH_PATTERN = /^[0-9a-f]{64}$/;
+
+function requireText(text: string): void {
+  if (typeof text !== "string") {
+    throw new TypeError(`text must be a string, got ${typeof text}`);
+  }
+}
+
+function requireStamp(expected: SpanSourceStamp): void {
+  if (!Object.hasOwn(expected, "hash")) {
+    throw new RangeError("expected stamp is missing field hash");
+  }
+  if (!Object.hasOwn(expected, "length")) {
+    throw new RangeError("expected stamp is missing field length");
+  }
+  const { hash, length } = expected;
+  if (typeof hash !== "string" || !HASH_PATTERN.test(hash)) {
+    throw new RangeError(
+      "expected stamp field hash must be 64 lowercase hex characters",
+    );
+  }
+  if (!Number.isInteger(length) || length < 0) {
+    throw new RangeError(
+      "expected stamp field length must be a non-negative integer",
+    );
+  }
+}
+
+/**
+ * Hash the exact string. No trimming, no newline normalization.
+ *
+ * The digest covers UTF-16LE code units, not UTF-8 bytes: Node's UTF-8
+ * encoder replaces an unpaired surrogate with U+FFFD before hashing, so
+ * "\ud800", "\ud801", and "\ufffd" all produce ONE digest under utf8 and
+ * drift between them would verify as unchanged. Unpaired surrogates reach
+ * real memory text through JSON escapes, and this stamp exists to catch
+ * exactly that class of silent substitution, so it hashes a lossless
+ * representation of the string instead.
+ */
+export function stampSpanSource(text: string): SpanSourceStamp {
+  requireText(text);
+  const hash = createHash("sha256").update(Buffer.from(text, "utf16le")).digest("hex");
+  return { hash, length: text.length };
+}
+
+/**
+ * Verify the materialized string against its stamp. Length is compared first:
+ * it is the cheaper, more diagnostic dimension. Mismatch results carry both
+ * stamps and never the text itself.
+ */
+export function verifySpanSource(
+  text: string,
+  expected: SpanSourceStamp,
+): SpanSourceCheck {
+  requireText(text);
+  requireStamp(expected);
+  const actual = stampSpanSource(text);
+  // Project the caller's stamp down to exactly the two stamp fields. Echoing
+  // the original object would re-export any extra property it carries — a
+  // `source` field holding the text defeats the whole point of a stamp, which
+  // exists so the content does not have to travel.
+  const safeExpected: SpanSourceStamp = { hash: expected.hash, length: expected.length };
+  if (actual.length !== safeExpected.length) {
+    return { ok: false, error: "length_mismatch", expected: safeExpected, actual };
+  }
+  if (actual.hash !== safeExpected.hash) {
+    return { ok: false, error: "hash_mismatch", expected: safeExpected, actual };
+  }
+  return { ok: true };
+}

package/src/recall-state-view-zero-diff.test.ts

@@ -0,0 +1,282 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseConfig } from "./config.js";
+import { RecallResultFormatter } from "./orchestration/recall-result-formatter.js";
+import { applyRecallStateViews } from "./recall-state-view-wire.js";
+import { checkStateViewZeroDiff, type StateViewLine } from "./recall-state-view-zero-diff.js";
+
+function line(memoryId: string, text: string, stateLabel = "current"): StateViewLine {
+  return { memoryId, text, stateLabel };
+}
+
+test("identical current-only lists pass", () => {
+  const baseline = [line("a", "Works at Acme"), line("b", "Prefers dark mode")];
+  const annotated = baseline.map((l) => ({ ...l }));
+  assert.deepEqual(checkStateViewZeroDiff({ baseline, annotated }), {
+    ok: true,
+    reason: "verified",
+  });
+  assert.deepEqual(checkStateViewZeroDiff({ baseline: [], annotated: [] }), {
+    ok: true,
+    reason: "verified",
+  });
+});
+
+test("changed current line reports current_line_changed with the id", () => {
+  const baseline = [line("a", "Was a baker"), line("b", "Runs daily")];
+  const annotated = [line("a", "Was a baker at a shop"), line("b", "Runs daily")];
+  assert.deepEqual(checkStateViewZeroDiff({ baseline, annotated }), {
+    ok: false,
+    error: "current_line_changed",
+    memoryId: "a",
+  });
+});
+
+test("trailing space on a current line is a diff", () => {
+  const baseline = [line("a", "Was a baker")];
+  const annotated = [line("a", "Was a baker ")];
+  assert.deepEqual(checkStateViewZeroDiff({ baseline, annotated }), {
+    ok: false,
+    error: "current_line_changed",
+    memoryId: "a",
+  });
+});
+
+test("reordered lines report order_changed", () => {
+  const baseline = [line("a", "A"), line("b", "B")];
+  const reordered = [line("b", "B"), line("a", "A")];
+  assert.deepEqual(checkStateViewZeroDiff({ baseline, annotated: reordered }), {
+    ok: false,
+    error: "order_changed",
+  });
+});
+
+test("dropped or added current lines report order_changed", () => {
+  const baseline = [line("a", "A"), line("b", "B")];
+  const dropped = [line("a", "A")];
+  assert.deepEqual(checkStateViewZeroDiff({ baseline, annotated: dropped }), {
+    ok: false,
+    error: "order_changed",
+  });
+  const added = [line("a", "A"), line("b", "B"), line("c", "C")];
+  assert.deepEqual(checkStateViewZeroDiff({ baseline, annotated: added }), {
+    ok: false,
+    error: "order_changed",
+  });
+});
+
+test("text mismatch wins over order mismatch", () => {
+  const baseline = [line("a", "A"), line("b", "B")];
+  const annotated = [line("b", "B"), line("a", "Changed")];
+  assert.deepEqual(checkStateViewZeroDiff({ baseline, annotated }), {
+    ok: false,
+    error: "current_line_changed",
+    memoryId: "a",
+  });
+});
+
+test("historical or transition item means the guarantee does not apply", () => {
+  const baseline = [line("new", "Current job")];
+  const withHistorical = [line("old", "Was a baker", "historical"), line("new", "Current job")];
+  assert.deepEqual(checkStateViewZeroDiff({ baseline, annotated: withHistorical }), {
+    ok: true,
+    reason: "not_applicable",
+  });
+  const withTransition = [line("mid", "Bridge job", "transition"), line("new", "Current job")];
+  assert.deepEqual(checkStateViewZeroDiff({ baseline, annotated: withTransition }), {
+    ok: true,
+    reason: "not_applicable",
+  });
+});
+
+test("non-current label in baseline throws RangeError", () => {
+  const baseline = [line("old", "Was a baker", "historical")];
+  assert.throws(
+    () => checkStateViewZeroDiff({ baseline, annotated: [] }),
+    (err: unknown) => err instanceof RangeError && /baseline/.test(String(err.message)),
+  );
+});
+
+test("unknown state label throws TypeError listing allowed values", () => {
+  const annotated = [line("a", "Text", "bogus")];
+  assert.throws(
+    () => checkStateViewZeroDiff({ baseline: [], annotated }),
+    (err: unknown) =>
+      err instanceof TypeError &&
+      /state label/.test(String(err.message)) &&
+      /current, historical, transition/.test(String(err.message)),
+  );
+});
+
+test("duplicate memoryId throws RangeError in either list", () => {
+  assert.throws(
+    () =>
+      checkStateViewZeroDiff({
+        baseline: [line("a", "A"), line("a", "A")],
+        annotated: [],
+      }),
+    (err: unknown) => err instanceof RangeError && /duplicate/.test(String(err.message)),
+  );
+  assert.throws(
+    () =>
+      checkStateViewZeroDiff({
+        baseline: [line("a", "A")],
+        annotated: [line("b", "B"), line("b", "B again")],
+      }),
+    (err: unknown) => err instanceof RangeError && /duplicate/.test(String(err.message)),
+  );
+});
+
+test("inputs are not mutated", () => {
+  const baseline = [line("a", "A"), line("b", "B")];
+  const annotated = [line("old", "Old", "historical"), line("a", "A"), line("b", "B")];
+  const baselineCopy = structuredClone(baseline);
+  const annotatedCopy = structuredClone(annotated);
+  checkStateViewZeroDiff({ baseline, annotated });
+  assert.deepEqual(baseline, baselineCopy);
+  assert.deepEqual(annotated, annotatedCopy);
+});
+
+/** A fixture row: the guard's line shape plus the fields the live route reads. */
+type LiveFixtureRow = StateViewLine & {
+  score: number;
+  supersededAt?: string;
+  supersededBy?: string;
+};
+
+// Review round 2: the earlier follow-up ran `injectStateViewLines`, which has
+// no production caller. The live route in orchestration/recall-entry.ts is
+// applyRecallStateViews -> RecallResultFormatter.formatQmdResultEntries, so
+// these cases drive those two real stages. A regression that reorders, drops,
+// or perturbs current-only entries in widening OR in live formatting now
+// fails here.
+function liveEntries(
+  results: readonly LiveFixtureRow[],
+  query: string,
+  stateViewsEnabled: boolean,
+): { entries: string[]; widened: { id?: string; stateLabel?: string }[] } {
+  // parseConfig intentionally does not carry `recallStateViews` (see
+  // recall-state-view-wire.ts: "parseConfig cannot grow"), so operators set it
+  // on the live config object. Setting it INSIDE parseConfig silently yields a
+  // disabled render, which makes a zero-diff assertion vacuous.
+  const parsed = parseConfig({ memoryDir: "/tmp/remnic-zero-diff-test" });
+  const config = stateViewsEnabled
+    ? ({ ...parsed, recallStateViews: true } as typeof parsed)
+    : parsed;
+  const qmdResults = results.map((result) => ({
+    path: `/tmp/remnic-zero-diff-test/facts/${result.memoryId}.md`,
+    score: result.score,
+    snippet: result.text,
+    // `resultStateViewId` reads `id ?? docid` — NOT memoryId. A fixture keyed
+    // only on memoryId gives every row the empty id, so widening drops any
+    // superseded row and the test silently measures nothing.
+    id: result.memoryId,
+    memoryId: result.memoryId,
+    stateLabel: result.stateLabel,
+    ...(result.supersededAt ? { supersededAt: result.supersededAt } : {}),
+    ...(result.supersededBy ? { supersededBy: result.supersededBy } : {}),
+  }));
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- test fixture
+  const widened = applyRecallStateViews(qmdResults as any[], query, config);
+  const formatter = new RecallResultFormatter(config);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- test fixture
+  const entries = formatter.formatQmdResultEntries("Relevant Memories", widened as any[]).entries;
+  return { entries, widened: widened as unknown as { id?: string; stateLabel?: string }[] };
+}
+
+function linesFrom(
+  entries: readonly string[],
+  results: readonly LiveFixtureRow[],
+): StateViewLine[] {
+  return entries.map((text, index) => ({
+    memoryId: results[index]!.memoryId,
+    text,
+    stateLabel: results[index]!.stateLabel,
+  }));
+}
+
+test("the enabled route labels an admitted superseded row; disabled leaves labels alone", () => {
+  const results = [
+    { memoryId: "m-1", text: "we use PostgreSQL", stateLabel: "current" as const, score: 0.9 },
+    {
+      memoryId: "m-0",
+      text: "we use SQLite",
+      stateLabel: "current" as const,
+      supersededAt: "2026-08-01",
+      supersededBy: "m-1",
+      score: 0.7,
+    },
+  ];
+  const query = "what changed about the database?";
+  const enabled = liveEntries(results, query, true);
+  const disabled = liveEntries(results, query, false);
+
+  // Observable effect #1: widening relabels the superseded row, and only when
+  // the live config carries the flag. This fails if recallStateViews is ignored.
+  assert.equal(
+    enabled.widened.find((row) => row.id === "m-0")?.stateLabel,
+    "historical",
+    "the enabled route must relabel the superseded row",
+  );
+  assert.equal(
+    disabled.widened.find((row) => row.id === "m-0")?.stateLabel,
+    "current",
+    "the disabled route must not touch labels",
+  );
+  // NOTE: the live formatter renders no superseded prefix — formatSupersededPrefix
+  // is reachable only from renderStateViewLine, which has no production caller.
+  // So the rendered entries are identical here, and asserting a rendered
+  // annotation through this route would be asserting a feature that is not
+  // wired. That gap belongs to the rendering slice, not to this guard.
+  assert.deepEqual(enabled.entries, disabled.entries);
+});
+
+test("the enabled route drops a superseded row whose successor is absent", () => {
+  // Observable effect #2, and the sharper one: an orphaned superseded row is
+  // admitted when state views are off and dropped when they are on, so the
+  // entry count itself depends on the live config reaching widening.
+  const results = [
+    { memoryId: "m-9", text: "unrelated current fact", stateLabel: "current" as const, score: 0.9 },
+    {
+      memoryId: "m-0",
+      text: "we use SQLite",
+      stateLabel: "current" as const,
+      supersededAt: "2026-08-01",
+      supersededBy: "m-absent",
+      score: 0.7,
+    },
+  ];
+  const query = "what changed about the database?";
+  assert.equal(liveEntries(results, query, false).entries.length, 2, "disabled admits both rows");
+  assert.equal(liveEntries(results, query, true).entries.length, 1, "enabled drops the orphan");
+});
+test("the live recall route is zero-diff for a current-only result set", () => {
+  const results = [
+    { memoryId: "m-1", text: "the API limit is 100/min", stateLabel: "current" as const, score: 0.9 },
+    { memoryId: "m-2", text: "we chose SQLite", stateLabel: "current" as const, score: 0.8 },
+  ];
+  const query = "what changed about the database?";
+  const baseline = liveEntries(results, query, false).entries;
+  const annotated = liveEntries(results, query, true).entries;
+
+  assert.deepEqual(annotated, baseline, "state views must not touch a current-only render");
+  const check = checkStateViewZeroDiff({
+    baseline: linesFrom(baseline, results),
+    annotated: linesFrom(annotated, results),
+  });
+  assert.deepEqual(check, { ok: true, reason: "verified" });
+});
+
+test("the live route still renders every current entry it was given", () => {
+  // Guards the inverse failure: an empty or dropped render would satisfy a
+  // naive zero-diff comparison, so assert the payload actually survives.
+  const results = [
+    { memoryId: "m-1", text: "the API limit is 100/min", stateLabel: "current" as const, score: 0.9 },
+    { memoryId: "m-2", text: "we chose SQLite", stateLabel: "current" as const, score: 0.8 },
+  ];
+  const entries = liveEntries(results, "what changed about the database?", true).entries;
+  assert.equal(entries.length, 2);
+  assert.match(entries[0]!, /the API limit is 100\/min/);
+  assert.match(entries[1]!, /we chose SQLite/);
+});

package/src/recall-state-view-zero-diff.ts

@@ -0,0 +1,125 @@
+/**
+ * Zero-diff guard for recall state views (issue #1952).
+ *
+ * The issue promises: current items are unchanged — zero diff for existing
+ * users when no historical item qualifies. This module makes that promise
+ * checkable. It compares the lines the pipeline would inject WITHOUT state
+ * views (baseline) against the lines it would inject WITH them (annotated).
+ *
+ * Ok reasons are named for what a reader will assume they mean:
+ * - `verified`: no historical or transition item is present, so the promise
+ *   applies, and the byte-exact comparison ran and held.
+ * - `not_applicable`: at least one historical or transition item is present,
+ *   so the "when no historical item qualifies" precondition is false and
+ *   nothing was compared.
+ *
+ * Text comparison is byte-exact; a trailing space added by a renderer is a
+ * diff. Current-line text mismatches are reported before order mismatches,
+ * so `order_changed` means every line matched by memoryId had identical
+ * text and only the memoryId sequence moved.
+ *
+ * Pure: no I/O, inputs are never mutated. Tests drive it through the live
+ * recall route (`applyRecallStateViews` then
+ * `RecallResultFormatter.formatQmdResultEntries`); wiring the guard into a
+ * runtime caller is a later slice.
+ */
+import type { StateLabel } from "./recall-state-view.js";
+
+export interface StateViewLine {
+  memoryId: string;
+  /** The line as it would be injected. */
+  text: string;
+  stateLabel: string;
+}
+
+export type ZeroDiffCheck =
+  | { ok: true; reason: "verified" | "not_applicable" }
+  | { ok: false; error: "current_line_changed"; memoryId: string }
+  | { ok: false; error: "order_changed" };
+
+const STATE_LABELS = Object.freeze(
+  ["current", "historical", "transition"] as const satisfies readonly StateLabel[],
+);
+
+function isStateLabel(value: string): value is StateLabel {
+  return (STATE_LABELS as readonly string[]).includes(value);
+}
+
+function validateLines(lines: readonly StateViewLine[], name: string): void {
+  for (const line of lines) {
+    if (line === null || typeof line !== "object") {
+      throw new TypeError(`${name} line must be an object`);
+    }
+    if (typeof line.memoryId !== "string") {
+      throw new TypeError(`${name} line memoryId must be a string`);
+    }
+    if (typeof line.text !== "string") {
+      throw new TypeError(`${name} line text must be a string`);
+    }
+    if (typeof line.stateLabel !== "string" || !isStateLabel(line.stateLabel)) {
+      throw new TypeError(
+        `unknown state label: ${JSON.stringify(line.stateLabel)} (allowed: ${STATE_LABELS.join(", ")})`,
+      );
+    }
+  }
+  const seen = new Set<string>();
+  for (const line of lines) {
+    if (seen.has(line.memoryId)) {
+      throw new RangeError(`duplicate memoryId in ${name}: ${line.memoryId}`);
+    }
+    seen.add(line.memoryId);
+  }
+}
+
+export function checkStateViewZeroDiff(input: {
+  baseline: readonly StateViewLine[];
+  annotated: readonly StateViewLine[];
+}): ZeroDiffCheck {
+  if (input === null || typeof input !== "object") {
+    throw new TypeError("input must be an object");
+  }
+  if (!Array.isArray(input.baseline)) {
+    throw new TypeError("baseline must be an array");
+  }
+  if (!Array.isArray(input.annotated)) {
+    throw new TypeError("annotated must be an array");
+  }
+  const baseline = input.baseline;
+  const annotated = input.annotated;
+  validateLines(baseline, "baseline");
+  validateLines(annotated, "annotated");
+  for (const line of baseline) {
+    if (line.stateLabel !== "current") {
+      throw new RangeError(
+        `baseline may only contain current lines, got ${JSON.stringify(line.stateLabel)}`,
+      );
+    }
+  }
+
+  const hasHistorical = annotated.some(
+    (line) => line.stateLabel === "historical" || line.stateLabel === "transition",
+  );
+  if (hasHistorical) {
+    return { ok: true, reason: "not_applicable" };
+  }
+
+  const baselineText = new Map<string, string>();
+  for (const line of baseline) {
+    baselineText.set(line.memoryId, line.text);
+  }
+  for (const line of annotated) {
+    if (baselineText.has(line.memoryId) && baselineText.get(line.memoryId) !== line.text) {
+      return { ok: false, error: "current_line_changed", memoryId: line.memoryId };
+    }
+  }
+
+  if (baseline.length !== annotated.length) {
+    return { ok: false, error: "order_changed" };
+  }
+  for (let i = 0; i < baseline.length; i++) {
+    if (baseline[i].memoryId !== annotated[i].memoryId) {
+      return { ok: false, error: "order_changed" };
+    }
+  }
+  return { ok: true, reason: "verified" };
+}

package/src/shared-context/authority-precedence.test.ts

@@ -0,0 +1,127 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { SHARED_AUTHORITIES } from "./governance.js";
+import {
+  compareSharedAuthority,
+  resolveSharedAuthority,
+  SHARED_AUTHORITY_CLASSES,
+} from "./authority-precedence.js";
+
+test("SHARED_AUTHORITY_CLASSES is the canonical governance list, not a copy", () => {
+  assert.equal(SHARED_AUTHORITY_CLASSES, SHARED_AUTHORITIES);
+});
+
+test("resolveSharedAuthority defaults absent authority to informational", () => {
+  assert.equal(resolveSharedAuthority({}), "informational");
+  assert.equal(resolveSharedAuthority({ authority: undefined }), "informational");
+  assert.equal(resolveSharedAuthority({ authority: null }), "informational");
+});
+
+test("resolveSharedAuthority honors binding only with the explicit boolean flag", () => {
+  assert.equal(resolveSharedAuthority({ authority: "binding", allowBinding: true }), "binding");
+  assert.equal(resolveSharedAuthority({ authority: "binding" }), "advisory");
+  assert.equal(resolveSharedAuthority({ authority: "binding", allowBinding: undefined }), "advisory");
+  assert.equal(resolveSharedAuthority({ authority: "binding", allowBinding: false }), "advisory");
+});
+
+test("resolveSharedAuthority keeps advisory and informational regardless of the flag", () => {
+  assert.equal(resolveSharedAuthority({ authority: "advisory" }), "advisory");
+  assert.equal(resolveSharedAuthority({ authority: "advisory", allowBinding: true }), "advisory");
+  assert.equal(resolveSharedAuthority({ authority: "informational" }), "informational");
+  assert.equal(resolveSharedAuthority({ authority: "informational", allowBinding: true }), "informational");
+});
+
+test("resolveSharedAuthority maps unrecognized strings to informational without normalizing", () => {
+  // Flag on proves these stay informational because of the exact-value
+  // check, not because binding was denied.
+  for (const authority of ["BINDING", "mandatory", " binding", "binding ", ""]) {
+    assert.equal(resolveSharedAuthority({ authority, allowBinding: true }), "informational");
+  }
+});
+
+test("resolveSharedAuthority maps non-string authority values to informational", () => {
+  for (const authority of [3, 0, true, false, { authority: "binding" }, ["binding"], Number.NaN]) {
+    assert.equal(resolveSharedAuthority({ authority }), "informational");
+  }
+});
+
+test("resolveSharedAuthority rejects a non-boolean allowBinding", () => {
+  for (const allowBinding of ["true", 1, null, "yes"] as unknown[]) {
+    assert.throws(
+      () => resolveSharedAuthority({ authority: "binding", allowBinding: allowBinding as never }),
+      { name: "TypeError", message: /allowBinding/ },
+    );
+  }
+});
+test("compareSharedAuthority orders every class pair by ascending privilege", () => {
+  const expected: Record<string, number> = { informational: 0, advisory: 1, binding: 2 };
+  for (const a of SHARED_AUTHORITY_CLASSES) {
+    for (const b of SHARED_AUTHORITY_CLASSES) {
+      const forward = compareSharedAuthority(a, b);
+      const backward = compareSharedAuthority(b, a);
+      assert.equal(Math.sign(forward), Math.sign(expected[a] - expected[b]));
+      assert.equal(Math.sign(backward) || 0, (-Math.sign(forward)) || 0);
+    }
+  }
+  assert.equal(compareSharedAuthority("informational", "informational"), 0);
+  assert.equal(compareSharedAuthority("advisory", "advisory"), 0);
+  assert.equal(compareSharedAuthority("binding", "binding"), 0);
+});
+
+test("compareSharedAuthority sorts unknown classes as informational", () => {
+  assert.equal(compareSharedAuthority("mandatory", "informational"), 0);
+  assert.equal(compareSharedAuthority("informational", "mandatory"), 0);
+  assert.equal(compareSharedAuthority("mandatory", "mandatory"), 0);
+  assert.equal(compareSharedAuthority("mandatory", "advisory") < 0, true);
+  assert.equal(compareSharedAuthority("advisory", "mandatory") > 0, true);
+  assert.equal(compareSharedAuthority("mandatory", "binding") < 0, true);
+  assert.equal(compareSharedAuthority("BINDING", "advisory") < 0, true);
+});
+
+test("sorting a shuffled mixed list is deterministic", () => {
+  const shuffled = [
+    "binding",
+    "informational",
+    "advisory",
+    "mandatory",
+    "advisory",
+    "informational",
+    "binding",
+    "informational",
+  ];
+  const first = [...shuffled].sort(compareSharedAuthority);
+  const second = [...shuffled].sort(compareSharedAuthority);
+  assert.deepEqual(first, [
+    "informational",
+    "mandatory",
+    "informational",
+    "informational",
+    "advisory",
+    "advisory",
+    "binding",
+    "binding",
+  ]);
+  assert.deepEqual(first, second);
+});
+
+// Review round 2: the flag was read twice — once to validate, once to decide.
+// A getter that changes between those reads is the whole attack.
+test("a changing allowBinding getter cannot smuggle binding through", () => {
+  let reads = 0;
+  const input = {
+    authority: "binding",
+    get allowBinding() {
+      reads += 1;
+      // undefined for the validation read, true for the decision read.
+      return reads === 1 ? undefined : true;
+    },
+  };
+  assert.equal(resolveSharedAuthority(input), "advisory");
+  assert.equal(reads, 1, "the switch must be read exactly once");
+});
+
+test("an explicit boolean opt-in still honors binding", () => {
+  assert.equal(resolveSharedAuthority({ authority: "binding", allowBinding: true }), "binding");
+  assert.equal(resolveSharedAuthority({ authority: "binding", allowBinding: false }), "advisory");
+});