@remnic/core 9.69.6 → 9.69.8

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/reconcile/cursor.test.ts

@@ -199,3 +199,21 @@ test("converge refresh obligations survive restart and clear independently", asy
     await fs.rm(tmpDir, { recursive: true, force: true });
   }
 });
+
+test("normalizeConvergePeerUrl: non-URL peers trim trailing slashes", () => {
+  assert.equal(normalizeConvergePeerUrl("local///"), "local");
+  assert.equal(normalizeConvergePeerUrl("peer-a/"), "peer-a");
+  assert.equal(normalizeConvergePeerUrl("peer-a"), "peer-a");
+});
+
+test("normalizeConvergePeerUrl: stays linear on long unparseable slash runs", () => {
+  // No scheme, so the URL constructor throws and the fallback branch runs;
+  // the trailing "a" means no suffix of slashes can match, which is the
+  // backtracking worst case for the old /\/+$/ trim.
+  const peerUrl = "/".repeat(50_000) + "a";
+  const startedAt = Date.now();
+  const normalized = normalizeConvergePeerUrl(peerUrl);
+  const elapsedMs = Date.now() - startedAt;
+  assert.ok(elapsedMs < 1000, `normalizeConvergePeerUrl took ${elapsedMs}ms on a ${peerUrl.length}-char slash run`);
+  assert.equal(normalized, peerUrl);
+});

package/src/reconcile/cursor.ts

@@ -27,6 +27,17 @@ export interface ConvergeCursorState {
   pendingRefreshes?: ConvergeRefreshTarget[];
 }
 
+/**
+ * Linear trailing-slash trim. `/\/+$/` backtracks quadratically on long
+ * slash runs that do not end in a slash (CodeQL js/polynomial-redos); a
+ * bounded character loop cannot.
+ */
+function stripTrailingSlashes(value: string): string {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "/") end -= 1;
+  return end === value.length ? value : value.slice(0, end);
+}
+
 export function normalizeConvergePeerUrl(peerUrl: string): string {
   const trimmed = peerUrl.trim();
   try {
@@ -35,10 +46,10 @@ export function normalizeConvergePeerUrl(peerUrl: string): string {
     url.password = "";
     url.search = "";
     url.hash = "";
-    url.pathname = url.pathname.replace(/\/+$/, "");
+    url.pathname = stripTrailingSlashes(url.pathname);
     return url.toString().replace(/\/$/, "");
   } catch {
-    return trimmed.replace(/\/+$/, "");
+    return stripTrailingSlashes(trimmed);
   }
 }
 

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");
+});

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

@@ -0,0 +1,68 @@
+/**
+ * Shared-item authority precedence (issue #1957).
+ *
+ * Pure helpers over the authority classes owned by `governance.ts`
+ * (`SHARED_AUTHORITIES`). Resolution is least-privilege: an absent,
+ * malformed, or unrecognized authority never resolves above
+ * `informational`, and `binding` additionally requires the explicit
+ * `allowBinding` flag. The helpers are exported for callers; wiring them
+ * into the shared-context read and write paths is a later slice.
+ */
+
+import { SHARED_AUTHORITIES, type SharedAuthority } from "./governance.js";
+
+export { SHARED_AUTHORITIES as SHARED_AUTHORITY_CLASSES };
+export type { SharedAuthority as SharedAuthorityClass };
+
+export interface ResolveSharedAuthorityInput {
+  /** Raw authority value from an item's envelope, if any. */
+  authority?: unknown;
+  /** Explicit opt-in required before "binding" is honored. */
+  allowBinding?: boolean;
+}
+
+const AUTHORITY_RANK: Readonly<Record<SharedAuthority, number>> = {
+  informational: 0,
+  advisory: 1,
+  binding: 2,
+};
+
+function isKnownAuthority(value: string): value is SharedAuthority {
+  return (SHARED_AUTHORITIES as readonly string[]).includes(value);
+}
+
+
+export function resolveSharedAuthority(input: ResolveSharedAuthorityInput): SharedAuthority {
+  // Read the security switch ONCE. A getter (or a Proxy) can return undefined
+  // during validation and true at the decision, which would let binding
+  // through without a validated opt-in.
+  const allowBinding = input.allowBinding;
+  if (allowBinding !== undefined && typeof allowBinding !== "boolean") {
+    // The flag is the security switch, so a truthy string or number must
+    // not enable binding: reject it instead of coercing.
+    throw new TypeError(
+      `resolveSharedAuthority: allowBinding must be a boolean when supplied, got ${typeof allowBinding}`,
+    );
+  }
+  const authority = input.authority;
+  // Absent (missing key, undefined, null) and present-but-invalid both land
+  // on informational — the least-privileged class — so an unmarked or
+  // malformed legacy item can never be treated as binding. Validate the
+  // exact value: no trim, no case-fold, because " binding" and "BINDING"
+  // are unrecognized data, not normalized matches for a known class.
+  if (typeof authority !== "string") return "informational";
+  if (!isKnownAuthority(authority)) return "informational";
+  if (authority === "binding" && allowBinding !== true) {
+    // Downgrade rather than throw: a legacy item already carrying "binding"
+    // is stored data, not a caller bug, so it resolves to the highest class
+    // that does not require the explicit opt-in.
+    return "advisory";
+  }
+  return authority;
+}
+
+export function compareSharedAuthority(a: string, b: string): number {
+  const rankA = isKnownAuthority(a) ? AUTHORITY_RANK[a] : AUTHORITY_RANK.informational;
+  const rankB = isKnownAuthority(b) ? AUTHORITY_RANK[b] : AUTHORITY_RANK.informational;
+  return Math.sign(rankA - rankB);
+}