@remnic/core 9.69.41 → 9.69.43

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/orchestration/workspace-ops.ts

@@ -28,6 +28,8 @@ import { LocalLlmClient } from "../local-llm.js";
 import { log } from "../logger.js";
 import type { NamespaceMaintenanceFanoutRunnerContext } from "../maintenance/namespace-maintenance-fanout.js";
 import type { NamespaceMaintenanceSummary } from "../maintenance/namespace-planner.js";
+import { localDayKey } from "../location/intervals.js";
+import { renderDayLocationContext } from "../location/tagging.js";
 import { type PatternReinforcementResult, runPatternReinforcement } from "../maintenance/pattern-reinforcement.js";
 import { evaluateMemoryActionPolicy } from "../memory-action-policy.js";
 import { NamespaceStorageRouter } from "../namespaces/storage.js";
@@ -454,6 +456,17 @@ export class WorkspaceOpsCoordinator {
       }
     }
 
+    if (options.includeLocation === true && this.deps.config.location) {
+      const section = await renderDayLocationContext(
+        storage.dir,
+        localDayKey(now.toISOString(), this.deps.config.location.timezone),
+        this.deps.config.location,
+      );
+      if (section) {
+        formatted += `\n\n${section}`;
+      }
+    }
+
     log.info(
       `gatherTodayFacts: collected ${facts.length} facts, ${hourlySummaries.length} hourly summaries for ${targetLocalDate} (${timeZone}, ${formatted.length} chars)`,
     );
@@ -636,6 +649,7 @@ export class WorkspaceOpsCoordinator {
       service = new WearablesService({
         config: this.deps.config.wearables,
         getStorage: async () => await this.deps.getStorageForNamespace(namespace),
+        locationConfig: this.deps.config.location,
         extract: (turns) => this.deps.extraction.extract(turns),
         // Smart memoryMode runs candidates through the SAME extraction
         // judge (cache + defer counters included) the live extraction

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

package/src/recall-navigation-http-glue.ts

@@ -0,0 +1,141 @@
+/**
+ * Recall-navigation HTTP glue (issue #1956) — route body lives here so
+ * access-http.ts stays at its structural ceiling (same seam as
+ * deep-recall-http-glue.ts).
+ *
+ * Input errors map to 400; everything else rethrows to the global 500
+ * handler. Config gating (`recallNavigation.enabled`) lives in the service
+ * and returns a typed `error: "disabled"` refusal — this module only
+ * translates transport shape. Namespace/sessionKey resolution flows through
+ * the caller-supplied `scopeFor` gate so a body-supplied namespace passes
+ * the SAME effective-namespace allow-list as the query string (issue #1850
+ * finding 2), and `authenticatedPrincipal` reaches the service so
+ * authorization derives from the presenting principal, never the
+ * client-supplied sessionKey.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import { EngramAccessInputError } from "./access-errors.js";
+import type { EngramAccessService } from "./access-service.js";
+import type { NavigationAction } from "./recall-navigation.js";
+
+type RespondJson = (res: ServerResponse, status: number, payload: unknown) => void;
+type ReadJsonBody = (req: IncomingMessage) => Promise<unknown>;
+
+type ScopeFor = (
+  bodyNamespace?: string,
+  bodySessionKey?: string,
+) => { namespace?: string; sessionKey?: string; authenticatedPrincipal?: string };
+
+const VALID_RELATIONS = [
+  "supports",
+  "contradicts",
+  "elaborates",
+  "causes",
+  "caused_by",
+  "supersedes",
+  "follows",
+  "references",
+  "related",
+] as const;
+
+function optStr(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function optInt(value: unknown): number | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  const parsed = typeof value === "string" ? Number(value) : value;
+  if (typeof parsed !== "number" || !Number.isInteger(parsed) || parsed < 1) {
+    throw new EngramAccessInputError("limit must be a positive integer");
+  }
+  return parsed;
+}
+
+async function respondNavigation(
+  req: IncomingMessage,
+  res: ServerResponse,
+  respondJson: RespondJson,
+  readJsonBody: ReadJsonBody,
+  service: EngramAccessService,
+  scopeFor: ScopeFor,
+  action: Extract<NavigationAction, "expand" | "traverse">,
+): Promise<void> {
+  const body = (await readJsonBody(req)) as Record<string, unknown>;
+  const memoryId = optStr(body.memoryId);
+  if (memoryId === undefined || memoryId.trim().length === 0) {
+    respondJson(res, 400, { error: "invalid_request", detail: "memoryId is required" });
+    return;
+  }
+  const sessionKey = optStr(body.sessionKey);
+  if (sessionKey === undefined || sessionKey.trim().length === 0) {
+    respondJson(res, 400, { error: "invalid_request", detail: "sessionKey is required" });
+    return;
+  }
+  let disclosure: "chunk" | "section" | "raw" | undefined;
+  let relation: string | undefined;
+  if (action === "expand") {
+    const raw = optStr(body.disclosure);
+    if (raw !== undefined && raw !== "chunk" && raw !== "section" && raw !== "raw") {
+      respondJson(res, 400, { error: "invalid_request", detail: "disclosure must be one of chunk, section, raw" });
+      return;
+    }
+    disclosure = raw;
+  } else {
+    relation = optStr(body.relation);
+    if (relation !== undefined && !(VALID_RELATIONS as readonly string[]).includes(relation)) {
+      respondJson(
+        res,
+        400,
+        { error: "invalid_request", detail: `relation must be one of ${VALID_RELATIONS.join(", ")}` },
+      );
+      return;
+    }
+  }
+  let limit: number | undefined;
+  try {
+    limit = optInt(body.limit);
+  } catch (err) {
+    respondJson(res, 400, { error: "invalid_request", detail: err instanceof Error ? err.message : String(err) });
+    return;
+  }
+  const scope = scopeFor(optStr(body.namespace), sessionKey);
+  const result = await service.recallNavigate({
+    action,
+    memoryId,
+    sessionKey: scope.sessionKey ?? sessionKey,
+    ...(disclosure !== undefined ? { disclosure } : {}),
+    ...(relation !== undefined ? { relation } : {}),
+    ...(limit !== undefined ? { limit } : {}),
+    namespace: scope.namespace,
+    authenticatedPrincipal: scope.authenticatedPrincipal,
+  });
+  const { rendered: _rendered, ...payload } = result;
+  respondJson(res, 200, payload);
+}
+
+export async function maybeRespondRecallNavigation(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathname: string,
+  method: string | undefined,
+  enforceTokenOp: (op: "memory_expand" | "memory_traverse") => void,
+  respondJson: RespondJson,
+  readJsonBody: ReadJsonBody,
+  service: EngramAccessService,
+  scopeFor: ScopeFor,
+): Promise<boolean> {
+  if (method === "POST" && (pathname === "/engram/v1/memory/expand" || pathname === "/remnic/v1/memory/expand")) {
+    enforceTokenOp("memory_expand");
+    await respondNavigation(req, res, respondJson, readJsonBody, service, scopeFor, "expand");
+    return true;
+  }
+  if (method === "POST" && (pathname === "/engram/v1/memory/traverse" || pathname === "/remnic/v1/memory/traverse")) {
+    enforceTokenOp("memory_traverse");
+    await respondNavigation(req, res, respondJson, readJsonBody, service, scopeFor, "traverse");
+    return true;
+  }
+  return false;
+}
+

package/src/recall-navigation-mcp-tools.ts

@@ -0,0 +1,60 @@
+/**
+ * Recall-navigation MCP tool definitions (issue #1956) — extracted from
+ * access-mcp.ts so the surface file stays at its structural ceiling (same
+ * seam as deep-recall-mcp-tools.ts). Spread back into `this.tools`
+ * (`...RECALL_NAVIGATION_MCP_TOOLS`); the migrated-operation mapping lives
+ * in access-mcp.ts's MCP_MIGRATED_OPERATIONS. The `remnic.` canonical alias
+ * is minted by withToolAliases at tools/list time.
+ *
+ * Gating: spread is conditional on `service.recallNavigationEnabled !== false`
+ * — the flag defaults TRUE, so the check treats an absent property (older
+ * service shape / test stub) as enabled and removes the tools from listing
+ * ONLY on an explicit false. Disabled config therefore yields tools absent
+ * from tools/list, not present-but-erroring.
+ */
+
+import type { McpTool } from "./access-mcp.js";
+
+export const RECALL_NAVIGATION_MCP_TOOLS: McpTool[] = [
+  {
+    name: "engram.memory_expand",
+    description:
+      "Re-render one memory a recall already served to this session at a deeper disclosure level (section or raw). Cheap follow-up — no fresh search. The id must come from this session's recent recall results.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        memoryId: { type: "string", description: "Memory id (or [m:xxxx] handle) served by a recent recall. Required." },
+        sessionKey: { type: "string", description: "Session key whose recent recalls authorize the id. Required." },
+        disclosure: {
+          type: "string",
+          enum: ["section", "raw"],
+          description: "Target depth; must be deeper than the chunk preview already served. Default raw.",
+        },
+        namespace: { type: "string", description: "Caller namespace to scope this operation to." },
+      },
+      required: ["memoryId", "sessionKey"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "engram.memory_traverse",
+    description:
+      "Follow typed links (supports/contradicts/elaborates/causes/caused_by/supersedes/follows/references/related) from a memory a recall already served to this session. Neighbors return as chunk-level summaries, optionally filtered by relation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        memoryId: { type: "string", description: "Memory id (or [m:xxxx] handle) served by a recent recall. Required." },
+        sessionKey: { type: "string", description: "Session key whose recent recalls authorize the id. Required." },
+        relation: {
+          type: "string",
+          enum: ["supports", "contradicts", "elaborates", "causes", "caused_by", "supersedes", "follows", "references", "related"],
+          description: "Optional relation filter; omitted means every known relation.",
+        },
+        limit: { type: "integer", minimum: 1, description: "Optional cap on returned neighbors (ceiling: recallNavigation.maxNeighbors)." },
+        namespace: { type: "string", description: "Caller namespace to scope this operation to." },
+      },
+      required: ["memoryId", "sessionKey"],
+      additionalProperties: false,
+    },
+  },
+];

package/src/recall-navigation-operations.ts

@@ -0,0 +1,111 @@
+/**
+ * Recall-navigation boundary operations (issue #1956).
+ *
+ * `memory_expand` / `memory_traverse` route MCP, HTTP, and CLI dispatch
+ * through the shared validation + error-mapping layer (access-boundary.ts)
+ * to the single `EngramAccessService.recallNavigate` implementation.
+ * Sibling module so access-operations-batch.ts stays at its ceiling seam
+ * (same layout as deep-recall's extraction).
+ */
+
+import { z } from "zod";
+
+import { defineOperation } from "./access-boundary.js";
+import { EngramAccessInputError } from "./access-errors.js";
+
+function stripNulls(data: unknown): unknown {
+  if (data !== null && typeof data === "object" && !Array.isArray(data)) {
+    const obj = data as Record<string, unknown>;
+    const cleaned: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      if (value !== null) cleaned[key] = value;
+    }
+    return cleaned;
+  }
+  return data;
+}
+
+function strictSchema<T extends z.ZodRawShape>(shape: T): z.ZodType<Record<string, unknown>> {
+  return z.preprocess(stripNulls, z.object(shape).passthrough()) as unknown as z.ZodType<Record<string, unknown>>;
+}
+
+const str = z.string().optional();
+
+function optStr(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function optInt(value: unknown): number | undefined {
+  if (typeof value === "number") return value;
+  if (typeof value === "string" && Number.isFinite(Number(value))) return Number(value);
+  return undefined;
+}
+
+function reqStr(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new EngramAccessInputError(`${field} is required`);
+  }
+  return value;
+}
+
+const baseShape = {
+  memoryId: z.string(),
+  sessionKey: z.string(),
+  namespace: str,
+};
+
+defineOperation({
+  name: "memory_expand",
+  description: "Re-render one already-served recall result at a deeper disclosure level (chunk → section → raw).",
+  schema: strictSchema({ ...baseShape, disclosure: z.enum(["chunk", "section", "raw"]).optional() }),
+  handler: async (input, ctx) => {
+    const disclosure = optStr(input.disclosure);
+    return {
+      result: await ctx.service.recallNavigate({
+        action: "expand",
+        memoryId: reqStr(input.memoryId, "memoryId"),
+        sessionKey: reqStr(input.sessionKey, "sessionKey"),
+        ...(disclosure === "chunk" || disclosure === "section" || disclosure === "raw" ? { disclosure } : {}),
+        namespace: optStr(input.namespace),
+        authenticatedPrincipal: ctx.authenticatedPrincipal,
+      }),
+    };
+  },
+});
+
+defineOperation({
+  name: "memory_traverse",
+  description:
+    "Follow typed frontmatter links from an already-served recall result; neighbors return as chunk-level summaries.",
+  schema: strictSchema({
+    ...baseShape,
+    relation: z
+      .enum([
+        "supports",
+        "contradicts",
+        "elaborates",
+        "causes",
+        "caused_by",
+        "supersedes",
+        "follows",
+        "references",
+        "related",
+      ])
+      .optional(),
+    limit: z.union([z.number(), z.string()]).optional(),
+  }),
+  handler: async (input, ctx) => {
+    const relation = optStr(input.relation);
+    return {
+      result: await ctx.service.recallNavigate({
+        action: "traverse",
+        memoryId: reqStr(input.memoryId, "memoryId"),
+        sessionKey: reqStr(input.sessionKey, "sessionKey"),
+        ...(relation !== undefined ? { relation } : {}),
+        limit: optInt(input.limit),
+        namespace: optStr(input.namespace),
+        authenticatedPrincipal: ctx.authenticatedPrincipal,
+      }),
+    };
+  },
+});

package/src/recall-navigation-renderer.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared markdown renderer for recall navigation (issue #1956).
+ *
+ * Rule 22: CLI text output, MCP `rendered`, and HTTP human output all
+ * render through this one module — never forked per surface.
+ * Deterministic: items in result order, budget and disclosure spend last.
+ */
+
+import type { RecallNavigationResult } from "./recall-navigation.js";
+
+type NavigationRenderInput = RecallNavigationResult extends infer Result
+  ? Result extends { rendered: string }
+    ? Omit<Result, "rendered">
+    : never
+  : never;
+
+export function renderNavigationResult(result: NavigationRenderInput): string {
+  if (!result.ok) {
+    return ["# Memory navigation", "", `- error: ${result.error}`, `- ${result.message}`, ""].join("\n");
+  }
+  const lines = ["# Memory navigation", ""];
+  lines.push(`- action: ${result.action}`);
+  lines.push(`- memory: ${result.memoryId}`);
+  lines.push(`- namespace: ${result.namespace}`);
+  if (result.items.length === 0) {
+    lines.push("- neighbors: (none)");
+  } else {
+    lines.push("");
+    for (const [index, item] of result.items.entries()) {
+      const via = item.linkType !== undefined ? ` via ${item.linkType}` : "";
+      lines.push(`${index + 1}. **${item.memoryId}** (${item.disclosure}${via})`);
+      if (item.content !== undefined) {
+        lines.push(item.content);
+      } else {
+        lines.push(`   ${item.preview.replace(/\s+/g, " ").trim()}`);
+      }
+    }
+  }
+  lines.push("");
+  lines.push(
+    `- budget: ${result.budget.used}/${result.budget.chars} chars${result.truncated ? " (truncated)" : ""}`,
+  );
+  const spend = result.disclosureSpend;
+  lines.push(
+    `- disclosure spend: chunk=${spend.chunk.estimatedTokens}t, section=${spend.section.estimatedTokens}t, raw=${spend.raw.estimatedTokens}t`,
+  );
+  lines.push("");
+  return lines.join("\n");
+}