@remnic/core 9.65.8 → 9.66.1

package/src/okf/index-files.ts

@@ -0,0 +1,114 @@
+import { readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import path from "node:path";
+
+import { writeFileAtomically } from "../maintenance/atomic-file.js";
+import { normalizeProjectionPreview } from "../memory-projection-format.js";
+import { OKF_RESERVED_BASENAMES } from "./type-mapping.js";
+
+export const OKF_INDEX_MARKER = "<!-- remnic-okf-index -->";
+
+const INDEXED_ROOTS = ["entities", "facts", "corrections", "summaries"] as const;
+
+export interface OkfIndexReport {
+  written: string[];
+  removed: string[];
+}
+
+export async function runOkfIndexMaintenance(
+  memoryDir: string,
+  enabled: boolean,
+): Promise<OkfIndexReport> {
+  const written: string[] = [];
+  const removed: string[] = [];
+  const dirs = collectIndexDirs(memoryDir);
+  for (const dir of dirs) {
+    const indexPath = path.join(dir, "index.md");
+    if (!enabled) {
+      if (isGeneratedIndex(indexPath)) {
+        unlinkSync(indexPath);
+        removed.push(indexPath);
+      }
+      continue;
+    }
+    const next = renderIndex(dir);
+    if (next === null) continue;
+    if (isUnchangedGenerated(indexPath, next)) continue;
+    await writeFileAtomically(indexPath, next);
+    written.push(indexPath);
+  }
+  return { written, removed };
+}
+
+function collectIndexDirs(memoryDir: string): string[] {
+  const dirs = [memoryDir];
+  for (const root of INDEXED_ROOTS) {
+    const full = path.join(memoryDir, root);
+    if (!isDir(full)) continue;
+    dirs.push(full);
+    if (root === "facts") {
+      for (const entry of safeList(full)) {
+        const child = path.join(full, entry);
+        if (isDir(child) && /^\d{4}-\d{2}-\d{2}$/.test(entry)) dirs.push(child);
+      }
+    }
+  }
+  return dirs;
+}
+
+function renderIndex(dir: string): string | null {
+  const entries = safeList(dir)
+    .filter((name) => name.endsWith(".md") && OKF_RESERVED_BASENAMES[name] !== true)
+    .sort((a, b) => a.localeCompare(b));
+  if (entries.length === 0) return null;
+  const lines = [OKF_INDEX_MARKER, "", `# ${path.basename(dir)}`, ""];
+  for (const name of entries) {
+    const preview = previewFile(path.join(dir, name));
+    lines.push(`* [${titleFrom(name, preview)}](${name}) - ${preview}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+function previewFile(filePath: string): string {
+  try {
+    return normalizeProjectionPreview(readFileSync(filePath, "utf8"), 120);
+  } catch {
+    return "";
+  }
+}
+
+function titleFrom(name: string, preview: string): string {
+  return preview.split(" ").slice(0, 8).join(" ") || name.replace(/\.md$/, "");
+}
+
+function isGeneratedIndex(filePath: string): boolean {
+  try {
+    return readFileSync(filePath, "utf8").includes(OKF_INDEX_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+function isUnchangedGenerated(filePath: string, next: string): boolean {
+  try {
+    return readFileSync(filePath, "utf8") === next;
+  } catch {
+    return false;
+  }
+}
+
+function isDir(dir: string): boolean {
+  try {
+    return statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function safeList(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}

package/src/okf/render.ts

@@ -0,0 +1,133 @@
+/**
+ * Shared OKF bundle-rendering helpers (issues #1948 + #1950).
+ *
+ * One source of truth for the mechanics every OKF bundle exporter uses:
+ * deterministic frontmatter rendering, staging-directory file writes, the
+ * symlink-guarded atomic publish, and the bundle version stamp. The memory
+ * exporter (transfer/export-okf.ts) and the codegraph exporter
+ * (coding/export-okf-codegraph.ts) both consume this module so their
+ * bundles are byte-compatible in convention (rule 38 — deterministic
+ * rendering discipline; rule 9 — stable seam over shared mechanics).
+ */
+import { lstatSync, mkdirSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+/** OKF spec version emitted in every bundle root index. */
+export const OKF_EXPORT_VERSION = "0.1";
+
+/**
+ * Render a YAML frontmatter block from a flat field map.
+ *
+ * Key order: the canonical OKF keys first (`type`, `title`, `description`,
+ * `tags`, `timestamp`), everything else alphabetical — one deterministic
+ * layout so identical inputs always render byte-identical files. A key set
+ * to `undefined` is omitted; callers must not pass a key twice.
+ */
+export function renderFrontmatter(fields: Record<string, unknown>): string {
+  const keys = Object.keys(fields).sort((a, b) => {
+    const order = ["type", "title", "description", "tags", "timestamp"];
+    const ai = order.indexOf(a);
+    const bi = order.indexOf(b);
+    if (ai >= 0 || bi >= 0) return (ai < 0 ? 99 : ai) - (bi < 0 ? 99 : bi);
+    return a.localeCompare(b);
+  });
+  const lines = keys.flatMap((key) => yamlLine(key, fields[key]));
+  return `---\n${lines.join("\n")}\n---\n\n`;
+}
+
+function yamlLine(key: string, value: unknown): string[] {
+  if (value === undefined) return [];
+  if (Array.isArray(value)) {
+    if (value.length === 0) return [`${key}: []`];
+    if (value.every((item) => typeof item !== "object" || item === null)) {
+      return [`${key}:`, ...value.map((item) => `  - ${yamlScalar(item)}`)];
+    }
+    return [`${key}: ${JSON.stringify(value)}`];
+  }
+  if (typeof value === "object" && value !== null) return [`${key}: ${JSON.stringify(value)}`];
+  return [`${key}: ${yamlScalar(value)}`];
+}
+
+function yamlScalar(value: unknown): string {
+  if (typeof value === "string") {
+    if (value === "" || /[:#\n]/.test(value) || value !== value.trim()) return JSON.stringify(value);
+    return value;
+  }
+  return String(value);
+}
+
+/**
+ * Write one file into a bundle staging tree. `rel` is a POSIX-style
+ * bundle-relative path; parent directories are created as needed.
+ */
+export function writeBundleFile(root: string, rel: string, content: string): void {
+  const dest = path.join(root, ...rel.split("/"));
+  mkdirSync(path.dirname(dest), { recursive: true });
+  writeFileSync(dest, content, "utf8");
+}
+
+/**
+ * Publish a staged bundle: refuse a non-empty target without `--force`,
+ * swap via rename so the target is never observed half-written, and keep a
+ * restorable backup when replacing an existing tree.
+ */
+export function publishBundle(staging: string, outDir: string, force: boolean): void {
+  let exists = false;
+  try {
+    const stat = lstatSync(outDir);
+    if (stat.isSymbolicLink()) throw new Error(`--out must not be a symlink: ${outDir}`);
+    exists = true;
+    const entries = readdirSync(outDir).filter((name) => name !== "." && name !== "..");
+    if (entries.length > 0 && !force) {
+      rmSync(staging, { recursive: true, force: true });
+      throw new Error(`--out ${outDir} is not empty; pass --force to replace it`);
+    }
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+  }
+  mkdirSync(path.dirname(outDir), { recursive: true });
+  if (exists && force) {
+    const backup = `${outDir}.okf-prev`;
+    try {
+      renameSync(outDir, backup);
+    } catch {
+      rmSync(staging, { recursive: true, force: true });
+      throw new Error(`cannot replace --out ${outDir}`);
+    }
+    try {
+      renameSync(staging, outDir);
+      rmSync(backup, { recursive: true, force: true });
+    } catch (err) {
+      try {
+        renameSync(backup, outDir);
+      } catch {
+        // Keep backup if restore fails.
+      }
+      throw err;
+    }
+    return;
+  }
+  renameSync(staging, outDir);
+}
+
+/**
+ * Reject a --out path with a symlink anywhere in its component chain
+ * (pattern 42 + hermes-shim precedent): a symlinked component could aim
+ * the atomic rename outside the operator's chosen directory.
+ */
+export function rejectSymlinkPath(target: string): void {
+  let current = path.resolve(target);
+  while (true) {
+    try {
+      if (lstatSync(current).isSymbolicLink()) {
+        throw new Error(`--out path component is a symlink: ${current}`);
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+}
+

package/src/okf/type-mapping.test.ts

@@ -49,6 +49,7 @@ test("parseOkfConfig treats false as a real disable", () => {
   assert.deepEqual(parseOkfConfig({ conformanceEnabled: false, sweepEnabled: "false" }), {
     conformanceEnabled: false,
     sweepEnabled: false,
+    indexFilesEnabled: false,
   });
   assert.throws(() => parseOkfConfig("nope"), /okf must be an object/);
 });
@@ -164,6 +165,7 @@ test("runOkfCliCommand handles help and rejects unexpected tokens", async () =>
       memoryDir: "/tmp",
       conformanceEnabled: true,
       sweepEnabled: false,
+      indexFilesEnabled: false,
     });
     assert.equal(code, 0);
     assert.match(chunks.join(""), /usage: remnic okf/);
@@ -176,6 +178,7 @@ test("runOkfCliCommand handles help and rejects unexpected tokens", async () =>
       memoryDir: "/tmp",
       conformanceEnabled: true,
       sweepEnabled: false,
+      indexFilesEnabled: false,
     });
     assert.equal(code, 1);
     assert.match(errChunks.join(""), new RegExp(`unexpected argument '${token}'`));

package/src/okf/type-mapping.ts

@@ -57,6 +57,8 @@ export function okfTypeForEntityKind(kind: string | undefined): string {
 export const OKF_PROFILE_TYPE = "Profile";
 export const OKF_QUESTION_TYPE = "Question";
 export const OKF_DECISION_RECORD_TYPE = "Decision Record";
+export const OKF_ARCHITECTURE_CARD_TYPE = "Architecture Card";
+export const OKF_CODE_MODULE_TYPE = "Code Module";
 
 /**
  * OKF §6/§7 reserve `index.md` and `log.md` for bundle-level files with a

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/extraction-run.ts

@@ -40,6 +40,7 @@ import {
   type MemoryLifecycleCapabilitySet,
 } from "../capabilities.js";
 import { parseFlexibleIsoTimestamp } from "../utils/iso-timestamp.js";
+import { tagPersistedMemories } from "../location/tagging.js";
 import { log } from "../logger.js";
 import type { PluginConfig, BufferTurn, ExtractionResult, MetaState, ExtractionFailureClass } from "../types.js";
 import type { TierMigrationCycleSummary } from "../recall-state.js";
@@ -62,7 +63,6 @@ export class ExtractionDeadlineError extends Error {
   }
 }
 
-
 /** Dependencies injected by the orchestrator. All stable references or
  *  live accessors — lazy getters for anything tests reassign
  *  post-construction (buffer, extraction, storageRouter, threading). */
@@ -1090,6 +1090,7 @@ export class ExtractionRunCoordinator {
       log.warn("runExtraction: durable-commit callback failed", error);
     }
     const runPostPersistBestEffort = runExtractionPostPersistBestEffort.bind(null, runDeadlineAware);
+    await tagPersistedMemories(storage, persistedIds, this.config);
     const postPersist = await runExtractionPostPersist({
       result,
       storage,

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

@@ -9,6 +9,9 @@ import {
   isLocationDayPath,
   isMeetingRecordPath,
 } from "./orchestrator-helpers.js";
+import { isJournalDayPath } from "../activity/journal.js";
+import { OKF_RESERVED_BASENAMES } from "../okf/type-mapping.js";
+
 
 export interface GenericRecallPathPolicy {
   readonly memoryDir?: string;
@@ -135,6 +138,7 @@ export function isSearchExcludedPath(
       isArtifactMemoryPath(candidate) ||
       isNamespacedActivityDigestPath(candidate, policy.memoryDir) ||
       isNamespacedLocationDayPath(candidate, policy.memoryDir) ||
+      isNamespacedJournalDayPath(candidate, policy.memoryDir) ||
       isMeetingRecordPath(candidate)
     ) {
       return true;
@@ -177,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,
@@ -230,9 +243,8 @@ export function isGenericRecallExcludedPath(
 ): boolean {
   return (
     isSearchExcludedPath(filePath, policy, source) ||
-    // Recall-only: archived memories are cold, but an explicit search is one
-    // of the surfaces they remain reachable through.
-    isTopLevelArchivePath(filePath, policy, source)
+    isTopLevelArchivePath(filePath, policy, source) ||
+    OKF_RESERVED_BASENAMES[path.basename(filePath)] === true
   );
 }
 

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

package/src/recall-deep.ts

@@ -0,0 +1,113 @@
+/**
+ * Budgeted REFINE/EXPAND/STOP loop (issue #2332 first slice).
+ *
+ * Pure state stepper. Policy is injected. No LLM, no orchestrator recall,
+ * no IO. Surfaces and parseConfig wait for a later PR — config.ts is at
+ * its fileSizeGrandfather ceiling.
+ *
+ * Budget 0 stops without calling the policy. Unknown actions throw.
+ */
+export const DEEP_RECALL_ACTIONS = ["refine", "expand", "stop"] as const;
+
+export type DeepRecallAction = (typeof DEEP_RECALL_ACTIONS)[number];
+
+export interface DeepRecallState {
+  query: string;
+  workingSet: readonly string[];
+  frontier: readonly string[];
+  budget: number;
+}
+
+export interface DeepRecallTraceStep {
+  action: DeepRecallAction;
+  budget: number;
+  workingSet: readonly string[];
+  frontier: readonly string[];
+}
+
+export interface DeepRecallStepResult {
+  state: DeepRecallState;
+  step: DeepRecallTraceStep;
+}
+
+export interface DeepRecallResult {
+  state: DeepRecallState;
+  trace: readonly DeepRecallTraceStep[];
+}
+
+export type DeepRecallPolicy = (state: DeepRecallState) => string;
+
+export function isDeepRecallAction(value: unknown): value is DeepRecallAction {
+  return typeof value === "string" && (DEEP_RECALL_ACTIONS as readonly string[]).includes(value);
+}
+
+function snapshot(state: DeepRecallState): DeepRecallState {
+  return {
+    query: state.query,
+    workingSet: [...state.workingSet],
+    frontier: [...state.frontier],
+    budget: state.budget,
+  };
+}
+
+export function runDeepRecallStep(state: DeepRecallState, action: string): DeepRecallStepResult {
+  if (!isDeepRecallAction(action)) {
+    throw new Error(
+      `unknown deep recall action: ${JSON.stringify(action)}. Valid: ${DEEP_RECALL_ACTIONS.join(", ")}`,
+    );
+  }
+  if (!Number.isFinite(state.budget) || state.budget <= 0 || action === "stop") {
+    const stopped = snapshot(state);
+    return {
+      state: stopped,
+      step: {
+        action: "stop",
+        budget: stopped.budget,
+        workingSet: stopped.workingSet,
+        frontier: stopped.frontier,
+      },
+    };
+  }
+
+  const next = snapshot(state);
+  next.budget = state.budget - 1;
+  if (action === "expand") {
+    const [head, ...rest] = next.frontier;
+    if (head !== undefined && !next.workingSet.includes(head)) {
+      next.workingSet = [...next.workingSet, head];
+    }
+    next.frontier = rest;
+  }
+  return {
+    state: next,
+    step: {
+      action,
+      budget: next.budget,
+      workingSet: next.workingSet,
+      frontier: next.frontier,
+    },
+  };
+}
+
+export function runDeepRecall(state: DeepRecallState, policy: DeepRecallPolicy): DeepRecallResult {
+  const trace: DeepRecallTraceStep[] = [];
+  let current = snapshot(state);
+  while (true) {
+    if (!Number.isFinite(current.budget) || current.budget <= 0) {
+      const stopped = snapshot(current);
+      trace.push({
+        action: "stop",
+        budget: stopped.budget,
+        workingSet: stopped.workingSet,
+        frontier: stopped.frontier,
+      });
+      return { state: stopped, trace };
+    }
+    const stepped = runDeepRecallStep(current, policy(current));
+    trace.push(stepped.step);
+    current = stepped.state;
+    if (stepped.step.action === "stop") {
+      return { state: current, trace };
+    }
+  }
+}