@remnic/core 9.66.0 → 9.66.1

package/src/dedup/merge-on-write.ts

@@ -0,0 +1,75 @@
+/**
+ * Isolated merge-on-write judge (issue #2330 first slice).
+ *
+ * Default off. Persist wiring comes later. Failures create.
+ */
+
+export const DEFAULT_MERGE_MIN = 0.8;
+export const DEFAULT_SKIP_THRESHOLD = 0.92;
+
+export const REFUSED_MERGE_CATEGORIES = [
+  "procedure",
+  "reasoning_trace",
+  "moment",
+  "correction",
+] as const;
+
+export type MergeOnWriteDecision = "merge" | "create";
+export type MergeJudgeVerdict = MergeOnWriteDecision | "uncertain";
+
+export interface MergeOnWritePair {
+  category: string;
+  score: number;
+  incomingContent?: string;
+  existingContent?: string;
+  existingId?: string;
+}
+
+export type MergeJudge = (
+  pair: MergeOnWritePair,
+) => Promise<MergeJudgeVerdict> | MergeJudgeVerdict;
+
+export function shouldConsiderMerge(opts: {
+  score: number;
+  skipThreshold?: number;
+  mergeMin?: number;
+}): boolean {
+  const mergeMin = opts.mergeMin ?? DEFAULT_MERGE_MIN;
+  const skipThreshold = opts.skipThreshold ?? DEFAULT_SKIP_THRESHOLD;
+  if (!(mergeMin > 0)) return false;
+  if (!Number.isFinite(opts.score) || !Number.isFinite(skipThreshold)) return false;
+  return mergeMin <= opts.score && opts.score < skipThreshold;
+}
+
+export async function judgeMergeDecision(
+  pair: MergeOnWritePair,
+  judge: MergeJudge,
+): Promise<MergeOnWriteDecision> {
+  try {
+    const verdict = await judge(pair);
+    return verdict === "merge" ? "merge" : "create";
+  } catch {
+    return "create";
+  }
+}
+
+export async function applyMergeOnWrite(opts: {
+  pair: MergeOnWritePair;
+  judge: MergeJudge;
+  enabled?: boolean;
+  mergeMin?: number;
+  skipThreshold?: number;
+}): Promise<MergeOnWriteDecision> {
+  if (opts.enabled !== true) return "create";
+  if ((REFUSED_MERGE_CATEGORIES as readonly string[]).includes(opts.pair.category)) return "create";
+  if (
+    !shouldConsiderMerge({
+      score: opts.pair.score,
+      mergeMin: opts.mergeMin,
+      skipThreshold: opts.skipThreshold,
+    })
+  ) {
+    return "create";
+  }
+  return judgeMergeDecision(opts.pair, opts.judge);
+}

package/src/dedup/novelty-gate.test.ts

@@ -0,0 +1,143 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseConfig } from "../config.js";
+import {
+  applyNoveltyGate,
+  DEFAULT_NOVELTY_ADD_THRESHOLD,
+  DEFAULT_NOVELTY_NOOP_THRESHOLD,
+  embeddingsFromCosineHits,
+  scoreNovelty,
+  type NoveltyNeighbor,
+} from "./novelty-gate.js";
+
+function neighborAtCosine(id: string, cosine: number): NoveltyNeighbor {
+  const s = Math.min(1, Math.max(-1, cosine));
+  return { id, embedding: [s, Math.sqrt(Math.max(0, 1 - s * s))] };
+}
+
+const CANDIDATE = [1, 0];
+
+test("novelty gate: parseConfig defaults keep the gate off with a wide uncertain band", () => {
+  const config = parseConfig({});
+  assert.equal(config.noveltyGateEnabled, false);
+  assert.equal(config.noveltyAddThreshold, DEFAULT_NOVELTY_ADD_THRESHOLD);
+  assert.equal(config.noveltyNoopThreshold, DEFAULT_NOVELTY_NOOP_THRESHOLD);
+  assert.ok(config.noveltyAddThreshold - config.noveltyNoopThreshold > 0.3);
+});
+
+test("novelty gate: conservative preset stays off", () => {
+  const config = parseConfig({ memoryOsPreset: "conservative" });
+  assert.equal(config.noveltyGateEnabled, false);
+});
+
+test("novelty gate: gate off does not call lookup", async () => {
+  let called = 0;
+  const decision = await applyNoveltyGate({
+    enabled: false,
+    addThreshold: DEFAULT_NOVELTY_ADD_THRESHOLD,
+    noopThreshold: DEFAULT_NOVELTY_NOOP_THRESHOLD,
+    lookup: async () => {
+      called += 1;
+      throw new Error("lookup must not run when the gate is off");
+    },
+  });
+  assert.equal(called, 0);
+  assert.equal(decision.decision, "uncertain");
+});
+
+test("novelty gate: paraphrase routes noop", () => {
+  const decision = scoreNovelty(CANDIDATE, [neighborAtCosine("paraphrase", 0.98)]);
+  assert.equal(decision.decision, "noop");
+  assert.equal(decision.neighborId, "paraphrase");
+  assert.ok(decision.score <= DEFAULT_NOVELTY_NOOP_THRESHOLD);
+});
+
+test("novelty gate: unrelated routes add", () => {
+  const decision = scoreNovelty(CANDIDATE, [neighborAtCosine("other", 0.05)]);
+  assert.equal(decision.decision, "add");
+  assert.equal(decision.neighborId, "other");
+  assert.ok(decision.score >= DEFAULT_NOVELTY_ADD_THRESHOLD);
+});
+
+test("novelty gate: exactly at addThreshold is add", () => {
+  const neighbor = neighborAtCosine("edge-add", 1 - DEFAULT_NOVELTY_ADD_THRESHOLD);
+  const measured = scoreNovelty(CANDIDATE, [neighbor], { addThreshold: 1, noopThreshold: -1 });
+  const decision = scoreNovelty(CANDIDATE, [neighbor], {
+    addThreshold: measured.score,
+    noopThreshold: DEFAULT_NOVELTY_NOOP_THRESHOLD,
+  });
+  assert.equal(decision.decision, "add");
+});
+
+test("novelty gate: exactly at noopThreshold is noop", () => {
+  const neighbor = neighborAtCosine("edge-noop", 1 - DEFAULT_NOVELTY_NOOP_THRESHOLD);
+  const measured = scoreNovelty(CANDIDATE, [neighbor], { addThreshold: 1, noopThreshold: -1 });
+  const decision = scoreNovelty(CANDIDATE, [neighbor], {
+    addThreshold: DEFAULT_NOVELTY_ADD_THRESHOLD,
+    noopThreshold: measured.score,
+  });
+  assert.equal(decision.decision, "noop");
+});
+
+test("novelty gate: mid-band routes uncertain", () => {
+  const mid = (DEFAULT_NOVELTY_ADD_THRESHOLD + DEFAULT_NOVELTY_NOOP_THRESHOLD) / 2;
+  const decision = scoreNovelty(CANDIDATE, [neighborAtCosine("mid", 1 - mid)]);
+  assert.equal(decision.decision, "uncertain");
+});
+
+test("novelty gate: empty neighborhood is add", () => {
+  const decision = scoreNovelty(CANDIDATE, []);
+  assert.equal(decision.decision, "add");
+  assert.equal(decision.score, 1);
+  assert.equal(decision.neighborId, undefined);
+});
+
+test("novelty gate: thrown lookup is uncertain", async () => {
+  const decision = await applyNoveltyGate({
+    enabled: true,
+    addThreshold: DEFAULT_NOVELTY_ADD_THRESHOLD,
+    noopThreshold: DEFAULT_NOVELTY_NOOP_THRESHOLD,
+    lookup: async () => {
+      throw new Error("backend down");
+    },
+  });
+  assert.equal(decision.decision, "uncertain");
+});
+
+test("novelty gate: cross-connector neighbor cannot noop (PR #2564 review)", () => {
+  // Identical content already stored by connector A (cosine ~1) must not
+  // suppress connector B's candidate: neighborhood scoped to same-connector
+  // neighbors only (mirrors the PR #1852 semantic skip gate).
+  const identicalFromA = { id: "a-dup", score: 1, sourceConnector: "connector-a" };
+  const { neighborhood } = embeddingsFromCosineHits([identicalFromA], {
+    candidateConnector: "connector-b",
+  });
+  assert.deepEqual(neighborhood, []);
+  const decision = scoreNovelty(CANDIDATE, neighborhood);
+  assert.equal(decision.decision, "add");
+});
+
+test("novelty gate: unattributed neighbor is scoped out when candidate has a connector", () => {
+  const unattributed = { id: "anon-dup", score: 1 };
+  const { neighborhood } = embeddingsFromCosineHits([unattributed], {
+    candidateConnector: "connector-b",
+  });
+  assert.deepEqual(neighborhood, []);
+});
+
+test("novelty gate: same-connector paraphrase still noops", () => {
+  const sameConnector = { id: "b-dup", score: 0.98, sourceConnector: "connector-b" };
+  const { neighborhood } = embeddingsFromCosineHits([sameConnector], {
+    candidateConnector: "connector-b",
+  });
+  assert.equal(neighborhood.length, 1);
+  assert.equal(scoreNovelty(CANDIDATE, neighborhood).decision, "noop");
+});
+
+test("novelty gate: candidate without connector keeps unscoped neighborhood", () => {
+  const foreign = { id: "a-dup", score: 0.98, sourceConnector: "connector-a" };
+  const { neighborhood } = embeddingsFromCosineHits([foreign]);
+  assert.equal(neighborhood.length, 1);
+  assert.equal(scoreNovelty(CANDIDATE, neighborhood).decision, "noop");
+});

package/src/dedup/novelty-gate.ts

@@ -0,0 +1,163 @@
+import { coerceBooleanLike, coerceNumber } from "../connectors/coerce.js";
+
+/**
+ * Embedding-density novelty gate (issue #1953, SAGE).
+ *
+ * score = 1 - mean(cosine of k nearest). Higher score = more novel.
+ *   score >= noveltyAddThreshold  → add (skip semantic/LLM dedup)
+ *   score <= noveltyNoopThreshold → noop (drop; do not touch contentHashIndex)
+ *   else                          → uncertain (fall through to semantic dedup)
+ *
+ * Defaults keep a wide UNCERTAIN band. noveltyGateEnabled defaults false.
+ * Backend failure is not handled here — callers treat a thrown lookup as uncertain.
+ */
+export const DEFAULT_NOVELTY_ADD_THRESHOLD = 0.55;
+export const DEFAULT_NOVELTY_NOOP_THRESHOLD = 0.15;
+export const DEFAULT_NOVELTY_K = 5;
+
+export interface NoveltyNeighbor {
+  id: string;
+  embedding: number[];
+}
+
+export interface NoveltyDecision {
+  score: number;
+  decision: "add" | "noop" | "uncertain";
+  neighborId?: string;
+}
+
+export interface NoveltyThresholds {
+  addThreshold?: number;
+  noopThreshold?: number;
+  k?: number;
+}
+
+export interface WritePathDedupConfig {
+  semanticDedupEnabled: boolean;
+  semanticDedupThreshold: number;
+  semanticDedupCandidates: number;
+  noveltyGateEnabled: boolean;
+  noveltyAddThreshold: number;
+  noveltyNoopThreshold: number;
+}
+
+function clamp01(value: number | undefined, fallback: number): number {
+  return value !== undefined && Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : fallback;
+}
+
+function cosine(a: number[], b: number[]): number {
+  if (a.length === 0 || a.length !== b.length) return 0;
+  let dot = 0;
+  let magA = 0;
+  let magB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    magA += a[i] * a[i];
+    magB += b[i] * b[i];
+  }
+  const denom = Math.sqrt(magA) * Math.sqrt(magB);
+  if (denom === 0) return 0;
+  const raw = dot / denom;
+  if (!Number.isFinite(raw)) return 0;
+  if (raw < 0) return 0;
+  if (raw > 1) return 1;
+  return raw;
+}
+
+export function parseWritePathDedupConfig(cfg: Record<string, unknown>): WritePathDedupConfig {
+  const rawCandidates = coerceNumber(cfg.semanticDedupCandidates, "semanticDedupCandidates");
+  let semanticDedupCandidates = 5;
+  if (rawCandidates !== undefined && rawCandidates >= 0) {
+    const n = Math.floor(rawCandidates);
+    semanticDedupCandidates = rawCandidates > 0 && n === 0 ? 1 : n;
+  }
+  return {
+    semanticDedupEnabled: coerceBooleanLike(cfg.semanticDedupEnabled, "semanticDedupEnabled") !== false,
+    semanticDedupThreshold: clamp01(
+      coerceNumber(cfg.semanticDedupThreshold, "semanticDedupThreshold"),
+      0.92,
+    ),
+    semanticDedupCandidates,
+    noveltyGateEnabled: coerceBooleanLike(cfg.noveltyGateEnabled, "noveltyGateEnabled") === true,
+    noveltyAddThreshold: clamp01(
+      coerceNumber(cfg.noveltyAddThreshold, "noveltyAddThreshold"),
+      DEFAULT_NOVELTY_ADD_THRESHOLD,
+    ),
+    noveltyNoopThreshold: clamp01(
+      coerceNumber(cfg.noveltyNoopThreshold, "noveltyNoopThreshold"),
+      DEFAULT_NOVELTY_NOOP_THRESHOLD,
+    ),
+  };
+}
+
+export function embeddingsFromCosineHits(
+  hits: ReadonlyArray<{ id: string; score: number; sourceConnector?: string }>,
+  opts: { candidateConnector?: string } = {},
+): { embedding: number[]; neighborhood: NoveltyNeighbor[] } {
+  // Connector-aware scoping (PR #2564 review finding on 54d865cb9): a
+  // neighbor from a different (or unattributed) connector must not drive a
+  // noop — same contract as the semantic skip gate (PR #1852). Candidates
+  // without a connector keep the unscoped neighborhood.
+  const candidateConnector = opts.candidateConnector?.trim() || undefined;
+  const scoped = candidateConnector
+    ? hits.filter((hit) => (hit.sourceConnector?.trim() || undefined) === candidateConnector)
+    : hits;
+  return {
+    embedding: [1, 0],
+    neighborhood: scoped.map((hit) => {
+      const s = Number.isFinite(hit.score) ? Math.min(1, Math.max(-1, hit.score)) : 0;
+      return { id: hit.id, embedding: [s, Math.sqrt(Math.max(0, 1 - s * s))] };
+    }),
+  };
+}
+
+export function scoreNovelty(
+  embedding: number[],
+  neighborhood: NoveltyNeighbor[],
+  thresholds: NoveltyThresholds = {},
+): NoveltyDecision {
+  const addThreshold = clamp01(thresholds.addThreshold ?? DEFAULT_NOVELTY_ADD_THRESHOLD, DEFAULT_NOVELTY_ADD_THRESHOLD);
+  const noopThreshold = clamp01(thresholds.noopThreshold ?? DEFAULT_NOVELTY_NOOP_THRESHOLD, DEFAULT_NOVELTY_NOOP_THRESHOLD);
+  const k = thresholds.k !== undefined && Number.isFinite(thresholds.k) && thresholds.k > 0
+    ? Math.floor(thresholds.k)
+    : DEFAULT_NOVELTY_K;
+
+  if (neighborhood.length === 0) {
+    return { score: 1, decision: "add" };
+  }
+
+  const ranked = neighborhood
+    .map((neighbor) => ({
+      id: neighbor.id,
+      cosine: cosine(embedding, neighbor.embedding),
+    }))
+    .sort((a, b) => b.cosine - a.cosine);
+  const nearest = ranked.slice(0, Math.max(1, k));
+  const density = nearest.reduce((sum, row) => sum + row.cosine, 0) / nearest.length;
+  const score = 1 - density;
+  const neighborId = ranked[0]?.id;
+
+  if (score >= addThreshold) return { score, decision: "add", neighborId };
+  if (score <= noopThreshold) return { score, decision: "noop", neighborId };
+  return { score, decision: "uncertain", neighborId };
+}
+
+export async function applyNoveltyGate(opts: {
+  enabled: boolean;
+  addThreshold: number;
+  noopThreshold: number;
+  lookup: () => Promise<{ embedding: number[]; neighborhood: NoveltyNeighbor[] }>;
+}): Promise<NoveltyDecision> {
+  if (!opts.enabled) {
+    return { score: 0, decision: "uncertain" };
+  }
+  try {
+    const { embedding, neighborhood } = await opts.lookup();
+    return scoreNovelty(embedding, neighborhood, {
+      addThreshold: opts.addThreshold,
+      noopThreshold: opts.noopThreshold,
+    });
+  } catch {
+    return { score: 0, decision: "uncertain" };
+  }
+}

package/src/location/recall-exclusion.test.ts

@@ -17,6 +17,7 @@ test("isLocationDayPath matches only the top-level day-file shape", () => {
 
 test("isSearchExcludedPath keeps location day documents out of generic search and recall", () => {
   assert.equal(isSearchExcludedPath("locations/2026-08-17.md"), true);
+  assert.equal(isSearchExcludedPath("journal/2026-08-17.md"), true);
   assert.equal(
     isSearchExcludedPath("qmd://collection/locations/2026-08-17.md", {}, "qmd"),
     true,

package/src/orchestration/extraction-persist.ts

@@ -83,6 +83,7 @@ import {
 } from "../fallback-llm.js";
 import { EmbeddingFallback } from "../embedding-fallback.js";
 import { decideSemanticDedup, type SemanticDedupDecision, type SemanticDedupHit } from "../dedup/semantic.js";
+import { applyNoveltyGate, embeddingsFromCosineHits } from "../dedup/novelty-gate.js";
 import { selectRouteRule, type RouteRule, type RoutingEngineOptions } from "../routing/engine.js";
 import { ThreadingManager } from "../threading.js";
 import { NamespaceStorageRouter } from "../namespaces/storage.js";
@@ -1919,26 +1920,24 @@ export class ExtractionPersistCoordinator {
           : undefined;
       const faithfulnessEnforceStatus = faithfulnessGateStatus ?? requireSpansPendingStatus ?? injectionScreenStatus;
 
-      // Issue #373 — write-time semantic similarity guard. Hook runs after
-      // the exact content-hash miss and the importance gate so that:
-      //   (a) paraphrased near-duplicates never reach writeMemory(), and
-      //   (b) low-importance facts that will be dropped never trigger an
-      //       embedding lookup (avoids unnecessary API latency/cost).
-      // Fails open when the embedding backend is unavailable.
-      //
-      // Defense in depth (PR #399 review): decideSemanticDedup already
-      // catches lookup errors internally, and the embedding fetch is
-      // bounded by a timeout in embedding-fallback.ts. We still wrap the
-      // whole call in its own try/catch here so that any unexpected
-      // rejection (future refactors, misbehaving custom backends, etc.)
-      // can never block the persist loop — a failure in the dedup path
-      // must always default to "not a duplicate".
-      // Track a pending semantic-skip decision (populated inside the block
-      // below). The actual drop happens AFTER contradiction detection so that
-      // a high-similarity update/correction is linked as a superseding
-      // contradiction rather than silently dropped.
+      const novelty = await applyNoveltyGate({
+        enabled: this.deps.config["noveltyGateEnabled"] === true,
+        addThreshold: this.deps.config.noveltyAddThreshold,
+        noopThreshold: this.deps.config.noveltyNoopThreshold,
+        lookup: async () =>
+          embeddingsFromCosineHits(
+            await this.deps.semanticDedupLookup(
+              fact.content,
+              this.deps.config.semanticDedupCandidates,
+              targetStorage,
+            ),
+            // Same connector scoping as decideSemanticDedup below: a
+            // cross-connector neighbor must not noop this candidate.
+            { candidateConnector: sourceContext?.sourceConnector },
+          ),
+      });
       let pendingSemanticSkip: (SemanticDedupDecision & { action: "skip" }) | null = null;
-      if (resolvePipelineProcessingCapabilities(this.deps.config).semanticDedup && injectionScreenStatus !== "pending_review") {
+      if (novelty.decision !== "add" && resolvePipelineProcessingCapabilities(this.deps.config).semanticDedup && injectionScreenStatus !== "pending_review") {
         let semanticDecision: SemanticDedupDecision;
         // UUI2: skip embedding lookup for the rest of this batch once we know
         // the backend is unavailable. The flag is reset per-batch (set to false
@@ -2100,17 +2099,17 @@ export class ExtractionPersistCoordinator {
       // gate's contract is "persists with status: pending_review, never
       // silently dropped" (issue #1576).
       if (
-        pendingSemanticSkip &&
+        (pendingSemanticSkip || novelty.decision === "noop") &&
         !contradictionDetected &&
         !isCorrection &&
         faithfulnessEnforceStatus !== "pending_review"
       ) {
         log.debug(
-          `dedup: skipping semantic near-duplicate fact "${fact.content
+          `dedup: skipping ${pendingSemanticSkip ? "semantic near-duplicate" : "novelty-noop"} fact "${fact.content
             .slice(0, 60)
-            .replace(/\s+/g, " ")}…" score=${pendingSemanticSkip.topScore.toFixed(
+            .replace(/\s+/g, " ")}…" score=${(pendingSemanticSkip?.topScore ?? novelty.score).toFixed(
             3,
-          )} neighbor=${pendingSemanticSkip.topId}`,
+          )} neighbor=${pendingSemanticSkip?.topId ?? novelty.neighborId}`,
         );
         dedupedCount++;
         // Do NOT add fact.content to contentHashIndex here. No memory was

package/src/orchestration/generic-recall-paths.ts

@@ -9,6 +9,7 @@ import {
   isLocationDayPath,
   isMeetingRecordPath,
 } from "./orchestrator-helpers.js";
+import { isJournalDayPath } from "../activity/journal.js";
 import { OKF_RESERVED_BASENAMES } from "../okf/type-mapping.js";
 
 
@@ -137,6 +138,7 @@ export function isSearchExcludedPath(
       isArtifactMemoryPath(candidate) ||
       isNamespacedActivityDigestPath(candidate, policy.memoryDir) ||
       isNamespacedLocationDayPath(candidate, policy.memoryDir) ||
+      isNamespacedJournalDayPath(candidate, policy.memoryDir) ||
       isMeetingRecordPath(candidate)
     ) {
       return true;
@@ -179,6 +181,15 @@ function isNamespacedLocationDayPath(candidate: string, memoryDir?: string): boo
   return isLocationDayPath(namespaced[2] ?? "", memoryDir);
 }
 
+function isNamespacedJournalDayPath(candidate: string, memoryDir?: string): boolean {
+  if (isJournalDayPath(candidate, memoryDir)) return true;
+  if (memoryDir === undefined || memoryDir.length === 0) return false;
+  const relative = path.relative(memoryDir, path.resolve(memoryDir, candidate));
+  const namespaced = /^namespaces[\\/]([^\\/]+)[\\/](.*)$/.exec(relative);
+  if (namespaced === null) return false;
+  return isJournalDayPath(namespaced[2] ?? "", memoryDir);
+}
+
 /** A path as given, plus its form with a leading COLLECTION segment removed. */
 function collectionSpellings(
   filePath: string,

package/src/orchestration/recall-entry.ts

@@ -20,6 +20,7 @@ import { ProfilingCollector } from "../profiling.js";
 import { trustResultFor, type TrustStageResultItem } from "../trust-score-stage.js";
 import type { RecallResultFormatter } from "./recall-result-formatter.js";
 import type { IdentityInjectionMode, PluginConfig, QmdSearchResult } from "../types.js";
+import { applyRecallStateViews } from "../recall-state-view-wire.js";
 
 export interface RecallEntryDeps {
   appendRecallSection(
@@ -274,9 +275,13 @@ export class RecallEntryCoordinator {
   }): void {
     const sectionId = "memories";
     const trustByPath = options.trustByPath ?? null;
-    const injectable = trustByPath
-      ? options.results.filter((r) => !trustResultFor(trustByPath, r)?.quarantined)
-      : options.results;
+    const injectable = applyRecallStateViews(
+      trustByPath
+        ? options.results.filter((r) => !trustResultFor(trustByPath, r)?.quarantined)
+        : options.results,
+      options.retrievalQuery,
+      this.deps.config,
+    );
     if (injectable.length === 0) return;
 
     const formatted = this.deps.recallResultFormatter.formatQmdResultEntries(

package/src/recall-deep.test.ts

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  runDeepRecall,
+  runDeepRecallStep,
+  type DeepRecallState,
+} from "./recall-deep.js";
+
+function seed(extra: Partial<DeepRecallState> = {}): DeepRecallState {
+  return {
+    query: "who met at the cafe",
+    workingSet: ["m-seed"],
+    frontier: ["m-b", "m-c"],
+    budget: 2,
+    ...extra,
+  };
+}
+
+test("budget 0 stops without calling the policy", () => {
+  const result = runDeepRecall(seed({ budget: 0 }), () => {
+    throw new Error("policy must not run when budget is 0");
+  });
+  assert.equal(result.trace.length, 1);
+  assert.equal(result.trace[0]?.action, "stop");
+  assert.equal(result.state.budget, 0);
+  assert.deepEqual(result.state.workingSet, ["m-seed"]);
+  assert.deepEqual(result.state.frontier, ["m-b", "m-c"]);
+});
+
+test("expand consumes budget and pulls the next frontier item", () => {
+  const result = runDeepRecallStep(seed({ budget: 2 }), "expand");
+  assert.equal(result.step.action, "expand");
+  assert.equal(result.state.budget, 1);
+  assert.deepEqual(result.state.workingSet, ["m-seed", "m-b"]);
+  assert.deepEqual(result.state.frontier, ["m-c"]);
+});
+
+test("stop ends while budget remains", () => {
+  let calls = 0;
+  const result = runDeepRecall(seed({ budget: 4 }), () => {
+    calls += 1;
+    return "stop";
+  });
+  assert.equal(calls, 1);
+  assert.equal(result.trace.length, 1);
+  assert.equal(result.trace[0]?.action, "stop");
+  assert.equal(result.state.budget, 4);
+  assert.deepEqual(result.state.workingSet, ["m-seed"]);
+});
+
+test("unknown action throws", () => {
+  assert.throws(() => runDeepRecallStep(seed(), "rewrite"), /unknown deep recall action/);
+  assert.throws(
+    () => runDeepRecall(seed(), () => "rewrite"),
+    /unknown deep recall action/,
+  );
+});
+
+test("same state and policy produce the same trace", () => {
+  const policy = (state: DeepRecallState) => (state.budget > 1 ? "expand" : "refine");
+  const start = seed({ budget: 3, frontier: ["m-z", "m-a"] });
+  const first = runDeepRecall(start, policy);
+  const second = runDeepRecall(start, policy);
+  assert.deepEqual(first, second);
+  assert.deepEqual(
+    first.trace.map((step) => step.action),
+    ["expand", "expand", "refine", "stop"],
+  );
+  assert.equal(start.budget, 3);
+  assert.deepEqual(start.frontier, ["m-z", "m-a"]);
+});