@remnic/core 9.69.42 → 9.69.44

package/src/access-service.ts

@@ -173,6 +173,9 @@ import {
 } from "./admin/admin-surfaces.js";
 import { FileCalendarSource, buildBriefing, parseBriefingFocus, parseBriefingWindow } from "./briefing.js";
 import { type DeepRecallResult, runBudgetedDeepRecall } from "./deep-recall.js";
+import { resolveEffectiveDeepRecallConfig } from "./deep-recall-config.js";
+import { type RecallNavigationRequest, type RecallNavigationResult, runRecallNavigation } from "./recall-navigation.js";
+import { RECALL_NAVIGATION_CONFIG_DEFAULTS } from "./recall-navigation-config.js";
 import { callDeepRecallPolicyLlm } from "./deep-recall-policy-llm.js";
 import { createDeepRecallSeedSearch } from "./deep-recall-seeds.js";
 import { renderDeepRecallResult } from "./deep-recall-renderer.js";
@@ -1278,6 +1281,7 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
   private readonly replicaDivergenceMonitor: ReplicaDivergenceMonitor;
   private readonly injectedSupportPassportGatewayRoute: SupportPassportModelRoute | null;
   readonly reviewDeckEnabled: boolean;
+  readonly recallNavigationEnabled: boolean;
 
   /** AccessObserveWriteSurface (access-service decomposition). Lazy; selfDeps live wiring. */
   private _accessObserveWriteSurface: AccessObserveWriteSurface | undefined;
@@ -1366,6 +1370,9 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
     this.replicaDivergenceMonitor = new ReplicaDivergenceMonitor({ resolveSecretRef: options.resolveSecretRef });
     this.injectedSupportPassportGatewayRoute = options.supportPassportGatewayRoute ?? null;
     this.reviewDeckEnabled = options.reviewDeckEnabled === true;
+    // Configs built without parseConfig (test stubs, older host shapes) may
+    // omit the block; the parsed default (enabled: true) is the contract.
+    this.recallNavigationEnabled = (orchestrator.config.recallNavigation ?? RECALL_NAVIGATION_CONFIG_DEFAULTS).enabled;
     const accessCaps = resolveAccessSetupCapabilities(orchestrator.config); // #1566 Cluster B
     this.budget = new CrossNamespaceBudget({
       enabled: accessCaps.recallCrossNamespaceBudget,
@@ -2743,29 +2750,7 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
     if (query.length === 0) {
       throw new EngramAccessInputError("deepRecall: query is required");
     }
-    let effective = cfg;
-    const requestedSteps = request.maxSteps;
-    if (requestedSteps !== undefined) {
-      if (typeof requestedSteps !== "number" || !Number.isInteger(requestedSteps) || requestedSteps < 0) {
-        throw new EngramAccessInputError("deepRecall: maxSteps must be a non-negative integer");
-      }
-      // `deepRecall.maxSteps: 0` is a documented disable value (§33): the
-      // policy loop is off, so ANY positive override is a refusal rather than
-      // a ceiling comparison. The zero case resolves first, so the ceiling
-      // threshold below only runs while the loop is enabled.
-      if (cfg.maxSteps <= 0) {
-        if (requestedSteps > 0) {
-          throw new EngramAccessInputError(
-            "deepRecall: the policy loop is disabled (deepRecall.maxSteps=0); maxSteps must be 0"
-          );
-        }
-      } else if (requestedSteps > cfg.maxSteps) {
-        throw new EngramAccessInputError(
-          `deepRecall: maxSteps ${requestedSteps} exceeds the configured ceiling ${cfg.maxSteps}`
-        );
-      }
-      effective = { ...cfg, maxSteps: requestedSteps };
-    }
+    const effective = resolveEffectiveDeepRecallConfig(cfg, request.maxSteps);
     const principal =
       request.authenticatedPrincipal?.trim() || resolvePrincipal(request.sessionKey, this.orchestrator.config);
     // Read path resolves through the SAME namespace layer as memoryGet (§30):
@@ -2844,6 +2829,11 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
     return { ...result, rendered: renderDeepRecallResult(result) };
   }
 
+  async recallNavigate(request: RecallNavigationRequest): Promise<RecallNavigationResult> {
+    const principal = request.authenticatedPrincipal?.trim() || resolvePrincipal(request.sessionKey, this.orchestrator.config);
+    return runRecallNavigation({ config: this.orchestrator.config.recallNavigation ?? RECALL_NAVIGATION_CONFIG_DEFAULTS, recallBudgetChars: this.orchestrator.config.recallBudgetChars, recentServedIds: (sessionKey, depth) => this.orchestrator.handleHistory.recent(sessionKey, depth), resolveReadableNamespace: (ns, p) => this.resolveReadableNamespace(ns, p || undefined), getStorage: (namespace) => this.orchestrator.getStorage(namespace) }, { ...request, authenticatedPrincipal: (principal ?? "").length > 0 ? principal : undefined });
+  }
+
   async recallXray(request: {
     query: string;
     sessionKey?: string;

package/src/access-surface-catalog.test.ts

@@ -271,8 +271,17 @@ function extractHttpRouteDispatchMap(): Map<string, Set<string>> {
       // must not be keyed — validateDispatchCoverage will flag any catalog
       // entry claiming migration through it (no pathname-only fallback).
       currentKey = method ? `${method} ${pathname}` : null;
-      if (currentKey && !routeOps.has(currentKey)) {
-        routeOps.set(currentKey, new Set<string>());
+      if (currentKey) {
+        if (!routeOps.has(currentKey)) {
+          routeOps.set(currentKey, new Set<string>());
+        }
+        // One-line route branches (compact style, e.g. the deep-recall
+        // route) carry their dispatch marker on the SAME line as the route
+        // match — collect it before the loop advances or it is lost.
+        const sameLineOp = line.match(/(?:getOperation|enforceTokenOp)\("(\w+)"\)/);
+        if (sameLineOp) {
+          routeOps.get(currentKey)!.add(sameLineOp[1]!);
+        }
       }
       continue;
     }
@@ -350,6 +359,25 @@ function extractHttpRouteDispatchMap(): Map<string, Set<string>> {
       }
     }
   }
+
+  // Recall-navigation routes (issue #1956): the compact catch-all in
+  // access-http.ts delegates to maybeRespondRecallNavigation; the boundary
+  // dispatch markers live per-route in recall-navigation-http-glue.ts.
+  if (/\bawait\s+maybeRespondRecallNavigation\(/.test(source)) {
+    const navigationSource = readFileSync(
+      new URL("./recall-navigation-http-glue.ts", import.meta.url),
+      "utf-8",
+    );
+    const navigationRoutes = [
+      ["POST", "/engram/v1/memory/expand", "memory_expand"],
+      ["POST", "/engram/v1/memory/traverse", "memory_traverse"],
+    ] as const;
+    for (const [method, pathname, operation] of navigationRoutes) {
+      if (navigationSource.includes(`"${pathname}"`) && navigationSource.includes(`enforceTokenOp("${operation}")`)) {
+        routeOps.set(`${method} ${pathname}`, new Set([operation]));
+      }
+    }
+  }
   for (const [sourcePath, routes] of [
     ["./support-passport/access-http.ts", SUPPORT_PASSPORT_OWNER_HTTP_ROUTES],
     ["./support-passport/public-http.ts", SUPPORT_PASSPORT_PUBLIC_HTTP_ROUTES],

package/src/access-surface-catalog.ts

@@ -72,6 +72,8 @@ export const MCP_TOOLS: readonly McpToolEntry[] = [
   { tool: "meetings_get", operation: "meetings_get" },
   { tool: "meetings_build", operation: "meetings_build" },
   { tool: "deep_recall", operation: "deep_recall" },
+  { tool: "memory_expand", operation: "memory_expand" },
+  { tool: "memory_traverse", operation: "memory_traverse" },
   { tool: "standup", operation: "standup" },
   { tool: "action_confidence", operation: "action_confidence" },
   { tool: "chatgpt_memory_inspector", operation: "chatgpt_memory_inspector" },
@@ -237,6 +239,8 @@ export const HTTP_ROUTES: readonly HttpRouteEntry[] = [
   { method: "POST", pathname: "/engram/v1/meetings/build", operation: "meetings_build" },
   { method: "GET", pathname: "/engram/v1/meetings/:id", operation: "meetings_get" },
   { method: "POST", pathname: "/engram/v1/recall/deep", operation: "deep_recall" },
+  { method: "POST", pathname: "/engram/v1/memory/expand", operation: "memory_expand" },
+  { method: "POST", pathname: "/engram/v1/memory/traverse", operation: "memory_traverse" },
   { method: "GET", pathname: "/engram/v1/standup", operation: "standup" },
   { method: "POST", pathname: "/engram/v1/observe", operation: "observe" },
   { method: "POST", pathname: "/engram/v1/lcm/search", operation: "lcm_search" },

package/src/cli/recall-navigation-commands.ts

@@ -0,0 +1,85 @@
+/**
+ * Recall-navigation command group (issue #1956) — extracted from cli.ts so
+ * the surface file stays at its structural ceiling (same seam as
+ * deep-recall-commands.ts). `remnic navigate expand|traverse <memoryId>`
+ * runs through EngramAccessService.recallNavigate — the same single
+ * implementation MCP and HTTP call, sharing one renderer.
+ */
+
+import type { Orchestrator } from "../orchestrator.js";
+import type { CliCommand } from "../cli.js";
+import { EngramAccessService } from "../access-service.js";
+
+function parseLimit(raw: unknown): number | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  const value = typeof raw === "string" ? Number(raw) : raw;
+  if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < 1) {
+    throw new Error(`--limit must be a positive integer; got ${JSON.stringify(raw)}`);
+  }
+  return value;
+}
+
+export function registerRecallNavigationCommands(cmd: CliCommand, orchestrator: Orchestrator): void {
+  const run = async (args: unknown[], action: "expand" | "traverse") => {
+    const memoryId = String(args[0] ?? "");
+    const options = (args[args.length - 1] ?? {}) as Record<string, unknown>;
+    const sessionKey = typeof options.sessionKey === "string" ? options.sessionKey : "";
+    if (memoryId.length === 0 || sessionKey.length === 0) {
+      console.error("usage: navigate <expand|traverse> <memoryId> --session-key <key> [--namespace <ns>]");
+      process.exitCode = 1;
+      return;
+    }
+    let limit: number | undefined;
+    try {
+      limit = action === "traverse" ? parseLimit(options.limit) : undefined;
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exitCode = 1;
+      return;
+    }
+    const service = new EngramAccessService(orchestrator);
+    try {
+      const result = await service.recallNavigate({
+        action,
+        memoryId,
+        sessionKey,
+        ...(action === "expand" && typeof options.disclosure === "string"
+          ? { disclosure: options.disclosure as "chunk" | "section" | "raw" }
+          : {}),
+        ...(action === "traverse" && typeof options.relation === "string" ? { relation: options.relation } : {}),
+        ...(limit !== undefined ? { limit } : {}),
+        ...(typeof options.namespace === "string" && options.namespace.length > 0
+          ? { namespace: options.namespace }
+          : {}),
+      });
+      if (options.json === true) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(result.rendered);
+      }
+      if (!result.ok) process.exitCode = 1;
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exitCode = 1;
+    }
+  };
+
+  cmd
+    .command("navigate expand <memoryId>")
+    .description("Re-render a served memory at deeper disclosure (issue #1956)")
+    .option("--session-key <key>", "Session key whose recent recalls authorize the id (required)")
+    .option("--disclosure <level>", "Target depth: section or raw (default raw)")
+    .option("--namespace <ns>", "Namespace to scope the read to")
+    .option("--json", "JSON output (items + budget + disclosure spend)")
+    .action(async (...args: unknown[]) => run(args, "expand"));
+
+  cmd
+    .command("navigate traverse <memoryId>")
+    .description("Follow typed links from a served memory; neighbors as chunk summaries (issue #1956)")
+    .option("--session-key <key>", "Session key whose recent recalls authorize the id (required)")
+    .option("--relation <type>", "Optional relation filter (supports, contradicts, elaborates, ...)")
+    .option("--limit <n>", "Optional cap on returned neighbors")
+    .option("--namespace <ns>", "Namespace to scope the read to")
+    .option("--json", "JSON output (items + budget + disclosure spend)")
+    .action(async (...args: unknown[]) => run(args, "traverse"));
+}

package/src/cli.ts

@@ -14,7 +14,7 @@ import { bumpMemoryCorpusVersionForDir } from "./memory-corpus-version.js";
 import { utcDayRange } from "./transcript.js";
 import { padEndDisplay, truncateGraphemeSafe } from "./whitespace.js";
 import { runWearablesCliCommand } from "./wearables/cli.js";
-import { registerMeetingsCommands } from "./cli/meetings-commands.js"; import { registerDeepRecallCommands } from "./cli/deep-recall-commands.js";
+import { registerMeetingsCommands } from "./cli/meetings-commands.js"; import { registerDeepRecallCommands } from "./cli/deep-recall-commands.js"; import { registerRecallNavigationCommands } from "./cli/recall-navigation-commands.js";
 import { registerExportOkfCommand, registerOkfCommands } from "./cli/okf-commands.js";
 import { registerSkillsCommands } from "./cli/skills-commands.js";
 import { registerResearchStatusCommands } from "./cli/research-status-commands.js";
@@ -6230,7 +6230,7 @@ export function registerCli(
 
       registerResearchStatusCommands(cmd, orchestrator);
 
-      registerCreationLedgerCommands(cmd, orchestrator); registerMeetingsCommands(cmd, orchestrator); registerOkfCommands(cmd, orchestrator); registerDeepRecallCommands(cmd, orchestrator); registerTimelineCommands(cmd, orchestrator);
+      registerCreationLedgerCommands(cmd, orchestrator); registerMeetingsCommands(cmd, orchestrator); registerOkfCommands(cmd, orchestrator); registerDeepRecallCommands(cmd, orchestrator); registerTimelineCommands(cmd, orchestrator); registerRecallNavigationCommands(cmd, orchestrator);
 
       cmd
         .command("trust-zone-promote")

package/src/config.ts

@@ -50,6 +50,7 @@ import { parseActiveContextFields } from "./active-context-config.js";
 import { parseSkillProjectionConfig } from "./procedural/skill-projection.js";
 import { parseDriftDetectionConfig } from "./preferences/drift-config.js";
 import { parseDeepRecallConfig } from "./deep-recall-config.js";
+import { parseRecallNavigationConfig } from "./recall-navigation-config.js";
 import { parseContradictionLocalizationConfig, parseContradictionScanConfig } from "./contradiction-config.js";
 import { parseGraphPathScoringConfig } from "./graph-path-scoring-config.js";
 import { parseWritePathDedupConfig } from "./dedup/novelty-gate.js";
@@ -630,6 +631,7 @@ const MEMORY_OS_PRESETS: Record<MemoryOsPresetName, Record<string, unknown>> = {
     // memory on a conservative preset must set `procedural.enabled: true`
     // explicitly.
     procedural: { enabled: false },
+    recallNavigation: { enabled: false },
   },
   balanced: {
     maxMemoryTokens: 2000,
@@ -1820,6 +1822,8 @@ export function parseConfig(
     driftDetection: parseDriftDetectionConfig(cfg.driftDetection),
     // Budgeted deep-recall surface (issue #2332)
     deepRecall: parseDeepRecallConfig(cfg.deepRecall),
+    // Session-scoped recall navigation (issue #1956)
+    recallNavigation: parseRecallNavigationConfig(cfg.recallNavigation),
     dependencyPropagation: parseDependencyPropagationConfig(cfg),
     // Temporal Supersession (issue #375)
     temporalSupersessionEnabled: cfg.temporalSupersessionEnabled !== false, // On by default

package/src/deep-recall-config.ts

@@ -11,6 +11,7 @@
  */
 
 import { coerceBool, coerceNumber } from "./connectors/coerce.js";
+import { EngramAccessInputError } from "./access-errors.js";
 
 export interface DeepRecallConfig {
   /** Master switch for the deep-recall surface. Default false. */
@@ -113,3 +114,34 @@ export function parseDeepRecallMaxSteps(raw: unknown): number | undefined {
   }
   throw new Error(`maxSteps must be a non-negative integer; got ${JSON.stringify(raw)}`);
 }
+
+/**
+ * Resolve the effective per-invocation config from a caller-requested
+ * `maxSteps` override (§33 semantics, extracted from the access service so
+ * the god file stays under its ratchet cap):
+ * - undefined request keeps the parsed config untouched;
+ * - `deepRecall.maxSteps: 0` is a documented disable value — any positive
+ *   override is a refusal, not a ceiling comparison;
+ * - otherwise the override must not exceed the configured ceiling.
+ */
+export function resolveEffectiveDeepRecallConfig(
+  cfg: DeepRecallConfig,
+  requestedSteps: number | undefined,
+): DeepRecallConfig {
+  if (requestedSteps === undefined) return cfg;
+  if (typeof requestedSteps !== "number" || !Number.isInteger(requestedSteps) || requestedSteps < 0) {
+    throw new EngramAccessInputError("deepRecall: maxSteps must be a non-negative integer");
+  }
+  if (cfg.maxSteps <= 0) {
+    if (requestedSteps > 0) {
+      throw new EngramAccessInputError(
+        "deepRecall: the policy loop is disabled (deepRecall.maxSteps=0); maxSteps must be 0"
+      );
+    }
+  } else if (requestedSteps > cfg.maxSteps) {
+    throw new EngramAccessInputError(
+      `deepRecall: maxSteps ${requestedSteps} exceeds the configured ceiling ${cfg.maxSteps}`
+    );
+  }
+  return { ...cfg, maxSteps: requestedSteps };
+}

package/src/index.ts

@@ -1451,5 +1451,4 @@ export * from "./maintenance/atomic-file.js";
 // Privacy-safe action-to-outcome trajectory eval (issue #2345)
 export * from "./eval-trajectory.js";
 export { MemoryControllerCoordinator, chooseAction, computeEvidenceReportHash, controllerConfigHash, evaluateActiveGates, hashControllerState, verifyEvidenceReport } from "./memory-controller.js";
-export type { ActiveContextAdapter, ActiveContextMessage, ActiveContextPlan, MemoryControllerActionFamily, MemoryControllerChoice, MemoryControllerConfig, MemoryControllerDeps, MemoryControllerEvent, MemoryControllerEvidence, MemoryControllerEvidenceReport, MemoryControllerExecutors, MemoryControllerMode, MemoryControllerPairedSeedEvidence, MemoryControllerReceipt, MemoryControllerRecorder, MemoryControllerReportReader, MemoryControllerRunResult, MemoryControllerState } from "./memory-controller.js";
-export * from "./recall-navigate.js";
+export type { ActiveContextAdapter, ActiveContextMessage, ActiveContextPlan, MemoryControllerActionFamily, MemoryControllerChoice, MemoryControllerConfig, MemoryControllerDeps, MemoryControllerEvent, MemoryControllerEvidence, MemoryControllerEvidenceReport, MemoryControllerExecutors, MemoryControllerMode, MemoryControllerPairedSeedEvidence, MemoryControllerReceipt, MemoryControllerRecorder, MemoryControllerReportReader, MemoryControllerRunResult, MemoryControllerState } from "./memory-controller.js"; export * from "./recall-navigate.js"; export * from "./recall-navigation.js"; export * from "./recall-navigation-config.js";

package/src/local-llm-config.test.ts

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { parseLocalLlmConfig } from "./local-llm-config.js";
+
+test("#2964: parseLocalLlmConfig round-trips a free-form localLlmHeaders key", () => {
+  const parsed = parseLocalLlmConfig(
+    {
+      localLlmHeaders: {
+        "X-Remnic-Canary": "alpha-9",
+        Authorization: "Bearer x",
+        drop: 1,
+      },
+    },
+    undefined,
+    (value) => value,
+  );
+  assert.deepEqual(parsed.localLlmHeaders, {
+    "X-Remnic-Canary": "alpha-9",
+    Authorization: "Bearer x",
+  });
+});

package/src/local-llm-config.ts

@@ -56,8 +56,7 @@ function parseLocalLlmMaxContext(value: unknown): number | undefined {
 function copyStringRecord(value: unknown): Record<string, string> | undefined {
   if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
   const headers: Record<string, string> = {};
-  for (const key of Object.getOwnPropertyNames(value)) {
-    const headerValue = Reflect.get(value, key);
+  for (const [key, headerValue] of Object.entries(value)) {
     if (typeof headerValue === "string") headers[key] = headerValue;
   }
   return headers;

package/src/mcp-read-only-tools.ts

@@ -28,6 +28,8 @@ export const MCP_READ_ONLY_TOOL_SUFFIXES: Readonly<Record<string, true>> = {
   meetings_list: true,
   meetings_get: true,
   deep_recall: true,
+  memory_expand: true,
+  memory_traverse: true,
   standup: true,
   action_confidence: true,
   capsule_list: true,

package/src/orchestration/recall-internal.ts

@@ -43,6 +43,7 @@ import { buildProcedureRecallSection, mergeProcedureInjections } from "../proced
 import { canRecallToolScopedMemory } from "../tool-scoped-memory.js";
 import { buildQmdRecallCacheKey, getCachedQmdRecall, setCachedQmdRecall } from "../qmd-recall-cache.js";
 import { MEMORY_ID_PATTERN } from "../recall-handles.js";
+import { shouldRecordRecallAuthorityHistory } from "../recall-navigation-config.js";
 import {
   boundRecallContextComposition, composeRecallContext, contextBudgetForFooter,
   formatCuriosityFooter, renderAuthorityBoundContent, selectCuriosityQuestion,
@@ -5256,10 +5257,9 @@ export class RecallInternalCoordinator {
         }),
         "last recall record",
       );
-      // Issue #1582 — record the admitted memory-id set for handle resolution.
-      // Only when handles are enabled: if injection is off, no handle is ever
-      // rendered, so there is nothing to resolve and we skip the write.
-      if (this.deps.config.recallMemoryHandles && recalledMemoryIds.length > 0) {
+      // Record admitted ids when handles render OR navigation needs authority.
+      // Handles-off + navigation-on is the shipped default; skip only when both are off.
+      if (shouldRecordRecallAuthorityHistory(this.deps.config) && recalledMemoryIds.length > 0) {
         // Only handle-eligible ids aid resolution; filter out non-memory .md
         // basenames (entity reconstructions) so the resolver never records a
         // citation target that cannot be loaded.

package/src/recall-navigation-config.test.ts

@@ -0,0 +1,56 @@
+/**
+ * Recall-navigation config parse (issue #1956 / PR #2937).
+ *
+ * Unknown keys fail closed. Default parse keeps navigation on and display
+ * handles off, and that pair still records authority history.
+ */
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { parseConfig } from "./config.js";
+import {
+  parseRecallNavigationConfig,
+  RECALL_NAVIGATION_CONFIG_DEFAULTS,
+  shouldRecordRecallAuthorityHistory,
+} from "./recall-navigation-config.js";
+
+test("parseRecallNavigationConfig rejects unknown keys instead of ignoring them", () => {
+  assert.throws(
+    () => parseRecallNavigationConfig({ windowSnapshot: 5 }),
+    /recallNavigation contains unknown key "windowSnapshot"/,
+  );
+  assert.throws(
+    () => parseConfig({ recallNavigation: { maxNeighbour: 4 } }),
+    /unknown key "maxNeighbour"/,
+  );
+  assert.deepEqual(parseRecallNavigationConfig({}), RECALL_NAVIGATION_CONFIG_DEFAULTS);
+});
+
+test("default config records authority history with handles off and navigation on", async () => {
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-nav-defaults-"));
+  try {
+    const config = parseConfig({ memoryDir });
+    assert.equal(config.recallMemoryHandles, false);
+    assert.equal(config.recallNavigation.enabled, true);
+    assert.equal(shouldRecordRecallAuthorityHistory(config), true);
+    assert.equal(
+      shouldRecordRecallAuthorityHistory({
+        recallMemoryHandles: false,
+        recallNavigation: { enabled: false },
+      }),
+      false,
+    );
+    assert.equal(
+      shouldRecordRecallAuthorityHistory({
+        recallMemoryHandles: true,
+        recallNavigation: { enabled: false },
+      }),
+      true,
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/recall-navigation-config.ts

@@ -0,0 +1,107 @@
+/**
+ * Recall-navigation config (issue #1956) — the `recallNavigation` block.
+ *
+ * Parsed the same way `deepRecall` is: shape-validated, string-coercion
+ * safe (§24), no silent clamping of documented values (§33). Navigation is
+ * a read-only surface over already-served recall results, so it defaults
+ * ON; the `conservative` preset pins `enabled: false`.
+ */
+
+import { coerceBool, coerceNumber } from "./connectors/coerce.js";
+
+export interface RecallNavigationConfig {
+  /** Master switch. Default true (read-only, additive surface). */
+  enabled: boolean;
+  /**
+   * How many of the session's most recent recall snapshots an expandable
+   * or traversable id may come from. Default 3.
+   */
+  windowSnapshots: number;
+  /** Ceiling for a traverse/entity-neighbor limit override. Default 10. */
+  maxNeighbors: number;
+}
+
+export interface RecallNavigationSettings {
+  recallNavigation: RecallNavigationConfig;
+}
+
+export const DEFAULT_NAVIGATION_WINDOW_SNAPSHOTS = 3;
+
+export const RECALL_NAVIGATION_CONFIG_DEFAULTS: RecallNavigationConfig = {
+  enabled: true,
+  windowSnapshots: DEFAULT_NAVIGATION_WINDOW_SNAPSHOTS,
+  maxNeighbors: 10,
+};
+
+/** Record served ids when display handles or navigation authority needs them. */
+export function shouldRecordRecallAuthorityHistory(config: {
+  recallMemoryHandles?: boolean;
+  recallNavigation?: { enabled?: boolean };
+}): boolean {
+  return config.recallMemoryHandles === true || config.recallNavigation?.enabled === true;
+}
+
+function parseFlag(src: Record<string, unknown>, key: string, fallback: boolean): boolean {
+  const value = src[key];
+  if (value === undefined || value === null) return fallback;
+  const coerced = coerceBool(value);
+  if (coerced === undefined) {
+    throw new Error(
+      `recallNavigation.${key} must be a boolean (or "true"/"false"/"1"/"0"); got ${JSON.stringify(value)}`,
+    );
+  }
+  return coerced;
+}
+
+function parseBoundedInt(
+  src: Record<string, unknown>,
+  key: string,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  const value = src[key];
+  if (value === undefined || value === null) return fallback;
+  const coerced = coerceNumber(value);
+  if (coerced === undefined || !Number.isFinite(coerced) || !Number.isInteger(coerced)) {
+    throw new Error(
+      `recallNavigation.${key} must be an integer between ${min} and ${max}; got ${JSON.stringify(value)}`,
+    );
+  }
+  if (coerced < min || coerced > max) {
+    throw new Error(
+      `recallNavigation.${key} must be an integer between ${min} and ${max}; got ${JSON.stringify(value)}`,
+    );
+  }
+  return coerced;
+}
+
+export function parseRecallNavigationConfig(raw: unknown): RecallNavigationConfig {
+  if (raw === undefined || raw === null) return { ...RECALL_NAVIGATION_CONFIG_DEFAULTS };
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`recallNavigation must be an object; got ${JSON.stringify(raw)}`);
+  }
+  const src = raw as Record<string, unknown>;
+  const { enabled: _enabled, windowSnapshots: _windowSnapshots, maxNeighbors: _maxNeighbors, ...unknown } = src;
+  const unknownKey = Object.keys(unknown)[0];
+  if (unknownKey !== undefined) {
+    throw new Error(`recallNavigation contains unknown key ${JSON.stringify(unknownKey)}`);
+  }
+  return {
+    enabled: parseFlag(src, "enabled", RECALL_NAVIGATION_CONFIG_DEFAULTS.enabled),
+    windowSnapshots: parseBoundedInt(
+      src,
+      "windowSnapshots",
+      RECALL_NAVIGATION_CONFIG_DEFAULTS.windowSnapshots,
+      1,
+      50,
+    ),
+    maxNeighbors: parseBoundedInt(
+      src,
+      "maxNeighbors",
+      RECALL_NAVIGATION_CONFIG_DEFAULTS.maxNeighbors,
+      1,
+      50,
+    ),
+  };
+}