@remnic/core 9.66.1 → 9.66.3

package/src/recall-state-view-kind.ts

@@ -0,0 +1,20 @@
+/**
+ * Recall state-view kind parse (issue #1952 leftover).
+ *
+ * Pure. Surfaces wait. Unknown or empty is unknown_kind.
+ */
+
+const STATE_VIEW_KINDS = ["current", "historical", "transition"] as const;
+
+export type StateViewKind = (typeof STATE_VIEW_KINDS)[number];
+
+export type ParseStateViewKindResult =
+  | { ok: true; kind: StateViewKind }
+  | { ok: false; error: "unknown_kind" };
+
+export function parseStateViewKind(value: string): ParseStateViewKindResult {
+  if ((STATE_VIEW_KINDS as readonly string[]).includes(value)) {
+    return { ok: true, kind: value as StateViewKind };
+  }
+  return { ok: false, error: "unknown_kind" };
+}

package/src/recall-state-view-label.test.ts

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { labelStateView } from "./recall-state-view-label.js";
+
+const DATE = "2026-03-01";
+const SUCCESSOR = "new-job";
+
+test("kind current is current", () => {
+  assert.equal(
+    labelStateView({ kind: "current", supersededAt: DATE, successorId: SUCCESSOR }),
+    "current",
+  );
+});
+
+test("kind historical with both fields is historical", () => {
+  assert.equal(
+    labelStateView({ kind: "historical", supersededAt: DATE, successorId: SUCCESSOR }),
+    "historical",
+  );
+});
+
+test("missing supersededAt or successorId is current", () => {
+  assert.equal(
+    labelStateView({ kind: "historical", successorId: SUCCESSOR }),
+    "current",
+  );
+  assert.equal(
+    labelStateView({ kind: "transition", supersededAt: DATE }),
+    "current",
+  );
+});
+
+test("unknown kind throws", () => {
+  assert.throws(() => labelStateView({ kind: "ghost" }), /unknown state view kind/);
+});

package/src/recall-state-view-label.ts

@@ -0,0 +1,22 @@
+/**
+ * Pure state-view labeler (issue #1952 leftover).
+ *
+ * Surfaces wait. `current` stays current. `historical` and `transition`
+ * keep their kind only when both supersededAt and successorId are set.
+ * Missing either field is current. Unknown kind throws.
+ */
+import type { StateLabel } from "./recall-state-view.js";
+
+export function labelStateView(input: {
+  kind: string;
+  supersededAt?: string;
+  successorId?: string;
+}): StateLabel {
+  const { kind, supersededAt, successorId } = input;
+  if (kind === "current") return "current";
+  if (kind === "historical" || kind === "transition") {
+    if (!supersededAt || !successorId) return "current";
+    return kind;
+  }
+  throw new Error(`unknown state view kind: ${JSON.stringify(kind)}`);
+}

package/src/recall-state-view-render.test.ts

@@ -0,0 +1,94 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { renderStateViewLine } from "./recall-state-view-render.js";
+
+const TEXT = "Was a baker";
+const DATE = "2026-03-01";
+const SUCCESSOR = "new-job";
+
+test("historical line gets the superseded prefix", () => {
+  const line = renderStateViewLine(
+    {
+      id: "old-job",
+      text: TEXT,
+      stateLabel: "historical",
+      supersededAt: DATE,
+      supersededBy: SUCCESSOR,
+    },
+    { enabled: true },
+  );
+  assert.equal(line, `[superseded ${DATE} by ${SUCCESSOR}] ${TEXT}`);
+});
+
+test("transition line gets the superseded prefix", () => {
+  const line = renderStateViewLine(
+    {
+      id: "mid-job",
+      text: TEXT,
+      stateLabel: "transition",
+      supersededAt: DATE,
+      supersededBy: SUCCESSOR,
+    },
+    { enabled: true },
+  );
+  assert.equal(line, `[superseded ${DATE} by ${SUCCESSOR}] ${TEXT}`);
+});
+
+test("current line is identity text", () => {
+  assert.equal(
+    renderStateViewLine(
+      {
+        id: "new-job",
+        text: TEXT,
+        stateLabel: "current",
+        supersededAt: DATE,
+        supersededBy: SUCCESSOR,
+      },
+      { enabled: true },
+    ),
+    TEXT,
+  );
+});
+
+test("missing date is identity text", () => {
+  assert.equal(
+    renderStateViewLine(
+      {
+        id: "old-job",
+        text: TEXT,
+        stateLabel: "historical",
+        supersededBy: SUCCESSOR,
+      },
+      { enabled: true },
+    ),
+    TEXT,
+  );
+});
+
+test("missing successor is identity text", () => {
+  assert.equal(
+    renderStateViewLine(
+      {
+        id: "old-job",
+        text: TEXT,
+        stateLabel: "historical",
+        supersededAt: DATE,
+      },
+      { enabled: true },
+    ),
+    TEXT,
+  );
+});
+
+test("enabled false is identity text", () => {
+  const historical = {
+    id: "old-job",
+    text: TEXT,
+    stateLabel: "historical" as const,
+    supersededAt: DATE,
+    supersededBy: SUCCESSOR,
+  };
+  assert.equal(renderStateViewLine(historical), TEXT);
+  assert.equal(renderStateViewLine(historical, { enabled: false }), TEXT);
+});

package/src/recall-state-view-render.ts

@@ -0,0 +1,24 @@
+/**
+ * Recall inject-line renderer for state views (issue #1952).
+ *
+ * Historical and transition rows get `[superseded <date> by <id>]` when both
+ * supersededAt and supersededBy are present. Current rows and a disabled
+ * flag are identity.
+ */
+import { formatSupersededPrefix, type StateViewResult } from "./recall-state-view.js";
+
+export type StateViewLineResult = StateViewResult & { text?: string };
+
+export function renderStateViewLine(
+  result: StateViewLineResult,
+  options: { enabled?: boolean } = {},
+): string {
+  const text = typeof result.text === "string" ? result.text : "";
+  if (options.enabled !== true) return text;
+  const label = result.stateLabel;
+  if (label !== "historical" && label !== "transition") return text;
+  const date = result.supersededAt;
+  const successor = result.supersededBy;
+  if (!date || !successor) return text;
+  return `${formatSupersededPrefix(date, successor)} ${text}`;
+}

package/src/recall-state-view-successor.test.ts

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseSuccessorId } from "./recall-state-view-successor.js";
+
+test("ok successor id returns trimmed successorId", () => {
+  assert.deepEqual(parseSuccessorId("mem-2"), { ok: true, successorId: "mem-2" });
+});
+
+test("empty successor id is missing_successor", () => {
+  assert.deepEqual(parseSuccessorId(""), { ok: false, error: "missing_successor" });
+  assert.deepEqual(parseSuccessorId("   "), { ok: false, error: "missing_successor" });
+});
+
+test("newline in successor id is invalid_successor", () => {
+  assert.deepEqual(parseSuccessorId("mem-1\nmem-2"), { ok: false, error: "invalid_successor" });
+});
+
+test("trims surrounding whitespace", () => {
+  assert.deepEqual(parseSuccessorId("  mem-2  "), { ok: true, successorId: "mem-2" });
+});

package/src/recall-state-view-successor.ts

@@ -0,0 +1,16 @@
+/**
+ * Recall state-view successor-id parse (issue #1952 leftover).
+ *
+ * Pure. Surfaces wait. Empty is missing_successor. Newline is invalid_successor.
+ */
+
+export type ParseSuccessorIdResult =
+  | { ok: true; successorId: string }
+  | { ok: false; error: "missing_successor" | "invalid_successor" };
+
+export function parseSuccessorId(value: string): ParseSuccessorIdResult {
+  const successorId = value.trim();
+  if (successorId.length === 0) return { ok: false, error: "missing_successor" };
+  if (successorId.includes("\n")) return { ok: false, error: "invalid_successor" };
+  return { ok: true, successorId };
+}

package/src/recall-state-view-superseded.test.ts

@@ -0,0 +1,20 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseSupersededAt } from "./recall-state-view-superseded.js";
+
+test("ok date returns canonical ISO supersededAt", () => {
+  assert.deepEqual(parseSupersededAt("2026-08-19T12:34:56.000Z"), {
+    ok: true,
+    supersededAt: "2026-08-19T12:34:56.000Z",
+  });
+});
+
+test("empty date is missing_date", () => {
+  assert.deepEqual(parseSupersededAt(""), { ok: false, error: "missing_date" });
+  assert.deepEqual(parseSupersededAt("   "), { ok: false, error: "missing_date" });
+});
+
+test("invalid date is invalid_date", () => {
+  assert.deepEqual(parseSupersededAt("not-a-date"), { ok: false, error: "invalid_date" });
+});

package/src/recall-state-view-superseded.ts

@@ -0,0 +1,17 @@
+/**
+ * Recall state-view superseded-at parse (issue #1952 leftover).
+ *
+ * Pure. Surfaces wait. Empty is missing_date. Unparseable is invalid_date.
+ */
+
+export type ParseSupersededAtResult =
+  | { ok: true; supersededAt: string }
+  | { ok: false; error: "missing_date" | "invalid_date" };
+
+export function parseSupersededAt(value: string): ParseSupersededAtResult {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return { ok: false, error: "missing_date" };
+  const parsed = Date.parse(trimmed);
+  if (!Number.isFinite(parsed)) return { ok: false, error: "invalid_date" };
+  return { ok: true, supersededAt: new Date(parsed).toISOString() };
+}

package/src/recall-state-view-transition.test.ts

@@ -0,0 +1,30 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { assertTransitionHasSuccessor } from "./recall-state-view-transition.js";
+
+test("transition plus empty successor id is transition_missing_successor", () => {
+  assert.deepEqual(assertTransitionHasSuccessor({ kind: "transition", successorId: "" }), {
+    ok: false,
+    error: "transition_missing_successor",
+  });
+  assert.deepEqual(assertTransitionHasSuccessor({ kind: "transition", successorId: "   " }), {
+    ok: false,
+    error: "transition_missing_successor",
+  });
+  assert.deepEqual(assertTransitionHasSuccessor({ kind: "transition" }), {
+    ok: false,
+    error: "transition_missing_successor",
+  });
+});
+
+test("transition plus successor id is ok", () => {
+  assert.deepEqual(assertTransitionHasSuccessor({ kind: "transition", successorId: "mem-2" }), {
+    ok: true,
+  });
+});
+
+test("current plus empty successor id is ok", () => {
+  assert.deepEqual(assertTransitionHasSuccessor({ kind: "current", successorId: "" }), { ok: true });
+  assert.deepEqual(assertTransitionHasSuccessor({ kind: "current" }), { ok: true });
+});

package/src/recall-state-view-transition.ts

@@ -0,0 +1,24 @@
+/**
+ * Recall state-view transition-has-successor guard (issue #1952 leftover).
+ *
+ * Pure. Surfaces wait. Transition without a successor is transition_missing_successor.
+ */
+
+export type AssertTransitionHasSuccessorInput = {
+  kind: string;
+  successorId?: string;
+};
+
+export type AssertTransitionHasSuccessorResult =
+  | { ok: true }
+  | { ok: false; error: "transition_missing_successor" };
+
+export function assertTransitionHasSuccessor(
+  input: AssertTransitionHasSuccessorInput,
+): AssertTransitionHasSuccessorResult {
+  const successorId = input.successorId?.trim() ?? "";
+  if (input.kind === "transition" && successorId.length === 0) {
+    return { ok: false, error: "transition_missing_successor" };
+  }
+  return { ok: true };
+}

package/src/recall-state-view-widen.test.ts

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { applyRecallStateViews } from "./recall-state-view-wire.js";
+import { widenRecallStateViews } from "./recall-state-view-widen.js";
+import type { StateViewResult } from "./recall-state-view.js";
+
+function fact(id: string, extra: Partial<StateViewResult> = {}): StateViewResult {
+  return { id, ...extra };
+}
+
+const CURRENT = fact("new-job", { status: "active" });
+const HISTORICAL = fact("old-job", {
+  status: "superseded",
+  supersededBy: "new-job",
+  supersededAt: "2026-03-01",
+});
+const ORPHAN = fact("orphan-job", {
+  status: "superseded",
+  supersededBy: "missing-job",
+});
+const ON = { recallStateViews: true } as const;
+const CHANGE = "when did the job title change";
+const NON_CHANGE = "what is the current job title";
+
+test("change-intent query labels both facts when successor is in the set", () => {
+  const labeled = widenRecallStateViews([CURRENT], CHANGE, ON, [HISTORICAL]);
+  assert.equal(labeled.length, 2);
+  assert.equal(labeled[0]?.id, "new-job");
+  assert.equal(labeled[0]?.stateLabel, "current");
+  assert.equal(labeled[1]?.id, "old-job");
+  assert.equal(labeled[1]?.stateLabel, "historical");
+  assert.deepEqual(
+    applyRecallStateViews([CURRENT, HISTORICAL], CHANGE, ON).map((row) => [
+      row.id,
+      row.stateLabel,
+    ]),
+    [
+      ["new-job", "current"],
+      ["old-job", "historical"],
+    ],
+  );
+});
+
+test("non-change query is identical (same array reference)", () => {
+  const input = [CURRENT, HISTORICAL];
+  assert.equal(widenRecallStateViews(input, NON_CHANGE, ON, [ORPHAN]), input);
+  assert.equal(applyRecallStateViews(input, NON_CHANGE, ON), input);
+  assert.equal(input[0]?.stateLabel, undefined);
+});
+
+test("recallStateViews false is identity (same array reference)", () => {
+  const input = [CURRENT];
+  assert.equal(widenRecallStateViews(input, CHANGE, {}, [HISTORICAL]), input);
+  assert.equal(widenRecallStateViews(input, CHANGE, { recallStateViews: false }, [HISTORICAL]), input);
+  assert.equal(applyRecallStateViews(input, CHANGE, { recallStateViews: false }), input);
+  assert.equal(input[0]?.stateLabel, undefined);
+});
+
+test("superseded without successor is dropped", () => {
+  assert.deepEqual(widenRecallStateViews([ORPHAN], CHANGE, ON), []);
+  assert.deepEqual(widenRecallStateViews([CURRENT], CHANGE, ON, [ORPHAN]), [
+    { ...CURRENT, stateLabel: "current" },
+  ]);
+  assert.deepEqual(applyRecallStateViews([ORPHAN], CHANGE, ON), []);
+});

package/src/recall-state-view-widen.ts

@@ -0,0 +1,49 @@
+/**
+ * Recall state-view widening (issue #1952).
+ *
+ * When recallStateViews is on and the query is change-oriented, admit a
+ * superseded memory only if its successor is already in the candidate set.
+ * Flag off / non-change queries are identity.
+ */
+import {
+  annotateStateView,
+  isChangeOrientedQuery,
+  parseRecallStateViews,
+  resultStateViewId,
+  shouldWidenSuperseded,
+  type StateViewResult,
+} from "./recall-state-view.js";
+
+export function widenRecallStateViews<T extends StateViewResult>(
+  results: T[],
+  query: string,
+  config: unknown,
+  pool: readonly T[] = [],
+): T[] {
+  const raw =
+    typeof config === "object" && config !== null && "recallStateViews" in config
+      ? config.recallStateViews
+      : undefined;
+  const enabled = parseRecallStateViews(raw);
+  if (!enabled || !isChangeOrientedQuery(query)) return results;
+
+  const candidateIds = new Set<string>();
+  for (const result of results) {
+    const id = resultStateViewId(result);
+    if (id) candidateIds.add(id);
+  }
+
+  const seen = new Set(candidateIds);
+  const extra: T[] = [];
+  for (const item of pool) {
+    const id = resultStateViewId(item);
+    if (!id || seen.has(id)) continue;
+    if (!shouldWidenSuperseded(item.supersededBy, candidateIds)) continue;
+    extra.push(item);
+    seen.add(id);
+  }
+
+  return annotateStateView(extra.length > 0 ? results.concat(extra) : results, query, [], {
+    enabled: true,
+  });
+}

package/src/recall-state-view-wire.ts

@@ -1,28 +1,18 @@
 /**
  * Recall inject seam for state views (issue #1952).
  *
- * parseConfig cannot grow (fileSizeGrandfather). Operators set
- * `recallStateViews` on the live PluginConfig extra field. Default false
- * is identity. Use parseRecallStateViews — do not read a scattered
- * config flag property here.
+ * Widening lives in recall-state-view-widen.ts. parseConfig cannot grow.
+ * Operators set `recallStateViews` on the live PluginConfig extra field.
+ * Default false is identity.
  */
 
-import {
-  annotateStateView,
-  parseRecallStateViews,
-  type StateViewResult,
-} from "./recall-state-view.js";
+import { widenRecallStateViews } from "./recall-state-view-widen.js";
+import type { StateViewResult } from "./recall-state-view.js";
 
 export function applyRecallStateViews<T extends StateViewResult>(
   results: T[],
   query: string,
   config: unknown,
 ): T[] {
-  const raw =
-    typeof config === "object" && config !== null && "recallStateViews" in config
-      ? (config as { recallStateViews?: unknown }).recallStateViews
-      : undefined;
-  return annotateStateView(results, query, [], {
-    enabled: parseRecallStateViews(raw),
-  });
+  return widenRecallStateViews(results, query, config);
 }

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

@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { checkAuthority } from "./authority.js";
+
+test("checkAuthority rejects a missing actor", () => {
+  assert.deepEqual(checkAuthority({ actor: "", required: "agent-a" }), {
+    ok: false,
+    error: "missing_actor",
+  });
+  assert.deepEqual(checkAuthority({ required: "agent-a" }), {
+    ok: false,
+    error: "missing_actor",
+  });
+  assert.deepEqual(checkAuthority({ actor: "   ", required: "agent-a" }), {
+    ok: false,
+    error: "missing_actor",
+  });
+});
+
+test("checkAuthority allows an empty required role", () => {
+  assert.deepEqual(checkAuthority({ actor: "agent-a", required: "" }), { ok: true });
+  assert.deepEqual(checkAuthority({ actor: "agent-a" }), { ok: true });
+});
+
+test("checkAuthority allows a matching actor", () => {
+  assert.deepEqual(checkAuthority({ actor: "agent-a", required: "agent-a" }), { ok: true });
+});
+
+test("checkAuthority rejects a mismatched actor", () => {
+  assert.deepEqual(checkAuthority({ actor: "agent-a", required: "agent-b" }), {
+    ok: false,
+    error: "forbidden",
+  });
+});

package/src/shared-context/authority.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared-item actor authority (issue #1957).
+ *
+ * Pure helper. Empty required means no gate. Missing actor always fails.
+ */
+
+export type AuthorityCheckError = "missing_actor" | "forbidden";
+
+export type AuthorityCheck =
+  | { ok: true }
+  | { ok: false; error: AuthorityCheckError };
+
+export interface CheckAuthorityInput {
+  actor?: string;
+  required?: string;
+}
+
+export function checkAuthority(input: CheckAuthorityInput): AuthorityCheck {
+  const actor = input.actor?.trim() ?? "";
+  if (actor.length === 0) return { ok: false, error: "missing_actor" };
+  const required = input.required?.trim() ?? "";
+  if (required.length === 0) return { ok: true };
+  if (actor !== required) return { ok: false, error: "forbidden" };
+  return { ok: true };
+}

package/src/shared-context/claim-key.test.ts

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseClaimKey } from "./claim-key.js";
+
+test("ok key returns trimmed key", () => {
+  assert.deepEqual(parseClaimKey("claim-a"), { ok: true, key: "claim-a" });
+});
+
+test("empty key is missing_key", () => {
+  assert.deepEqual(parseClaimKey(""), { ok: false, error: "missing_key" });
+  assert.deepEqual(parseClaimKey("   "), { ok: false, error: "missing_key" });
+});
+
+test("newline in key is invalid_key", () => {
+  assert.deepEqual(parseClaimKey("claim-a\nclaim-b"), { ok: false, error: "invalid_key" });
+});
+
+test("trims surrounding whitespace", () => {
+  assert.deepEqual(parseClaimKey("  claim-a  "), { ok: true, key: "claim-a" });
+});

package/src/shared-context/claim-key.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared-context claim key parse (issue #1957 leftover).
+ *
+ * Pure. Empty is missing_key. Newline is invalid_key.
+ */
+
+export type ParseClaimKeyResult =
+  | { ok: true; key: string }
+  | { ok: false; error: "missing_key" | "invalid_key" };
+
+export function parseClaimKey(value: string): ParseClaimKeyResult {
+  const key = value.trim();
+  if (key.length === 0) return { ok: false, error: "missing_key" };
+  if (key.includes("\n")) return { ok: false, error: "invalid_key" };
+  return { ok: true, key };
+}

package/src/shared-context/contradictions.test.ts

@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  detectContradictionPair,
+  type SharedClaimItem,
+} from "./contradictions.js";
+
+test("detectContradictionPair returns same for identical ids", () => {
+  const a: SharedClaimItem = { id: "item-1", claims: { host: "alpha" } };
+  const b: SharedClaimItem = { id: "item-1", claims: { host: "beta" } };
+
+  assert.deepEqual(detectContradictionPair(a, b), { kind: "same" });
+});
+
+test("detectContradictionPair returns conflict with the unequal overlapping keys", () => {
+  const a: SharedClaimItem = {
+    id: "item-1",
+    claims: { tier: "high", host: "alpha", region: "us" },
+  };
+  const b: SharedClaimItem = {
+    id: "item-2",
+    claims: { tier: "high", host: "beta", owner: "ops" },
+  };
+
+  assert.deepEqual(detectContradictionPair(a, b), {
+    kind: "conflict",
+    keys: ["host"],
+  });
+});
+
+test("detectContradictionPair returns none when overlap is absent or equal", () => {
+  const disjoint: SharedClaimItem = { id: "item-1", claims: { host: "alpha" } };
+  const other: SharedClaimItem = { id: "item-2", claims: { owner: "ops" } };
+  const agreeing: SharedClaimItem = { id: "item-3", claims: { host: "alpha" } };
+
+  assert.deepEqual(detectContradictionPair(disjoint, other), { kind: "none" });
+  assert.deepEqual(detectContradictionPair(disjoint, agreeing), { kind: "none" });
+});

package/src/shared-context/contradictions.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared-item contradiction detection (issue #1957).
+ *
+ * Pure helper. Same-id items are one item; overlapping claim keys with
+ * unequal values are a conflict. No deletes, no persistence.
+ */
+
+export interface SharedClaimItem {
+  id: string;
+  claims: Record<string, string>;
+}
+
+export type ContradictionPairResult =
+  | { kind: "same" }
+  | { kind: "conflict"; keys: string[] }
+  | { kind: "none" };
+
+export function detectContradictionPair(
+  a: SharedClaimItem,
+  b: SharedClaimItem,
+): ContradictionPairResult {
+  if (a.id === b.id) {
+    return { kind: "same" };
+  }
+  const keys: string[] = [];
+  for (const key of Object.keys(a.claims)) {
+    if (key in b.claims && a.claims[key] !== b.claims[key]) {
+      keys.push(key);
+    }
+  }
+  return keys.length > 0 ? { kind: "conflict", keys: keys.sort() } : { kind: "none" };
+}