@remnic/core 9.69.41 → 9.69.43

package/src/recall-navigation.ts

@@ -0,0 +1,429 @@
+/**
+ * Recall navigation (issue #1956) — session-scoped follow-up tools over
+ * already-served recall results.
+ *
+ * Composes existing primitives; owns no new storage and no new link types:
+ *   - authority: the session's last `windowSnapshots` recall id sets
+ *     (`RecallHandleHistoryStore`, the same ring `resolveMemoryHandle` reads)
+ *   - isolation: every read resolves through the caller's resolved readable
+ *     namespace and ONE storage instance (pattern 30 — no arbitrary-id
+ *     fishing across namespaces)
+ *   - disclosure: `planDisclosureStep` enforces strictly-deeper expansion;
+ *     rendering reuses `shapeMemorySummary` (single formatter, rule 22)
+ *   - links: frontmatter `links` via `selectTraverseNeighbors`
+ *   - budget: per-call character cap drawn from the recall character budget,
+ *     with per-item disclosure/token spend reported through the SAME
+ *     disclosure accounting X-ray aggregates (`estimateRecallTokens` +
+ *     `summarizeDisclosureTokens`).
+ *
+ * Unknown, expired (outside the window), or foreign ids are rejected with a
+ * typed error naming the constraint (pattern 39) — never reinterpreted.
+ */
+
+import { EngramAccessInputError, shapeMemorySummary, type EngramAccessMemorySummary } from "./access-service.js";
+import { parseIdOrHandle, resolveHandle } from "./recall-handles.js";
+import { takeNavigateBudget } from "./recall-navigate-budget.js";
+import { estimateRecallTokens, summarizeDisclosureTokens, type RecallXrayDisclosureSummary } from "./recall-xray.js";
+import { assertIdInNavigationWindow } from "./recall-navigate-window.js";
+import { parseNavigateLinkType } from "./recall-navigate-link.js";
+import { planDisclosureStep } from "./recall-navigate-disclosure.js";
+import { selectTraverseNeighbors, DEFAULT_TRAVERSE_LIMIT, type TraverseNeighbor } from "./recall-navigate-traverse.js";
+import { renderNavigationResult } from "./recall-navigation-renderer.js";
+import type { RecallNavigationConfig } from "./recall-navigation-config.js";
+import type { MemoryFile, RecallDisclosure } from "./types.js";
+
+/** Navigation reads touch only these storage members. */
+export type NavigationStorage = Pick<StorageManagerLike, "dir" | "getMemoryById" | "readMemoriesWindow">;
+
+/** Structural stand-in so this module does not import StorageManager directly. */
+interface StorageManagerLike {
+  dir: string;
+  getMemoryById(id: string): Promise<MemoryFile | null>;
+  readMemoriesWindow(options?: { maxMemories?: number }): Promise<{ memories: MemoryFile[] }>;
+}
+
+/** Injected seams; the service supplies live wiring, tests supply doubles. */
+export interface RecallNavigationDeps {
+  readonly config: RecallNavigationConfig;
+  /** Per-call character cap for the assembled response payload. */
+  readonly recallBudgetChars: number;
+  /** Served-id sets for a session, newest snapshot first. */
+  readonly recentServedIds: (sessionKey: string, depth: number) => ReadonlyArray<readonly string[]>;
+  readonly resolveReadableNamespace: (namespace: string | undefined, principal?: string) => string;
+  readonly getStorage: (namespace: string) => Promise<NavigationStorage>;
+}
+
+export type NavigationAction = "expand" | "traverse" | "entity_neighbors";
+
+export interface RecallNavigationRequest {
+  readonly action: NavigationAction;
+  /** Memory id (or `[m:xxxx]` handle) served to this session's recent recalls. */
+  readonly memoryId: string;
+  /** Session whose recall window authorizes the id. Required. */
+  readonly sessionKey: string;
+  readonly namespace?: string;
+  readonly authenticatedPrincipal?: string;
+  /** expand: target depth. Must be strictly deeper than the chunk default. */
+  readonly disclosure?: RecallDisclosure;
+  /** traverse: optional relation filter. */
+  readonly relation?: string;
+  /** traverse / entity_neighbors: optional result cap. */
+  readonly limit?: number;
+}
+
+export interface NavigationItem {
+  readonly memoryId: string;
+  readonly path: string;
+  readonly disclosure: RecallDisclosure;
+  readonly estimatedTokens: number;
+  readonly preview: string;
+  /** Present when the disclosure level carries full content (expand). */
+  readonly content?: string;
+  /** Relation edge that produced this neighbor (traverse only). */
+  readonly linkType?: string;
+}
+
+export type RecallNavigationError =
+  | "disabled"
+  | "not_served"
+  | "not_found"
+  | "not_deeper"
+  | "unknown_level"
+  | "unknown_relation"
+  | "invalid_limit";
+
+export type RecallNavigationResult =
+  | {
+      ok: true;
+      action: NavigationAction;
+      memoryId: string;
+      namespace: string;
+      items: NavigationItem[];
+      truncated: boolean;
+      budget: { chars: number; used: number };
+      disclosureSpend: RecallXrayDisclosureSummary;
+      rendered: string;
+    }
+  | {
+      ok: false;
+      action: NavigationAction;
+      error: RecallNavigationError;
+      message: string;
+      rendered: string;
+    };
+
+function toNavigationItem(
+  summary: EngramAccessMemorySummary,
+  extras: { linkType?: string } = {},
+): NavigationItem {
+  const item: {
+    memoryId: string;
+    path: string;
+    disclosure: RecallDisclosure;
+    estimatedTokens: number;
+    preview: string;
+    content?: string;
+    linkType?: string;
+  } = {
+    memoryId: summary.id,
+    path: summary.path,
+    disclosure: summary.disclosure ?? "chunk",
+    estimatedTokens: estimateRecallTokens(summary.content ?? summary.preview),
+    preview: summary.preview,
+    };
+  if (summary.content !== undefined) item.content = summary.content;
+  if (extras.linkType !== undefined) item.linkType = extras.linkType;
+  return item;
+}
+
+/** Greedy fill against JSON.stringify of the structured result (no rendered). */
+function applyBudget(
+  request: RecallNavigationRequest,
+  extras: { memoryId: string; namespace: string; items: NavigationItem[]; truncated: boolean; budgetChars: number },
+): { items: NavigationItem[]; truncated: boolean; used: number } {
+  const kept: NavigationItem[] = [];
+  let truncated = extras.truncated;
+  for (const item of extras.items) {
+    const candidate = [...kept, item];
+    const cost = structuredCost(request, extras, candidate, truncated);
+    if (!takeNavigateBudget(extras.budgetChars, cost).ok) {
+      if (kept.length === 0) {
+        const shrunk = shrinkItemToBudget(request, extras, item);
+        if (shrunk !== undefined) {
+          return finalizeBudget(request, extras, [shrunk], true);
+        }
+      }
+      truncated = true;
+      break;
+    }
+    kept.push(item);
+  }
+  return finalizeBudget(request, extras, kept, truncated);
+}
+
+function finalizeBudget(
+  request: RecallNavigationRequest,
+  extras: { memoryId: string; namespace: string; budgetChars: number },
+  items: NavigationItem[],
+  truncated: boolean,
+): { items: NavigationItem[]; truncated: boolean; used: number } {
+  let kept = items;
+  let flag = truncated;
+  let used = measuredUsed(request, extras, kept, flag);
+  while (used > extras.budgetChars && kept.length > 0) {
+    kept = kept.slice(0, -1);
+    flag = true;
+    used = measuredUsed(request, extras, kept, flag);
+  }
+  return { items: kept, truncated: flag, used };
+}
+
+function structuredBody(
+  request: RecallNavigationRequest,
+  extras: { memoryId: string; namespace: string; budgetChars: number },
+  items: NavigationItem[],
+  truncated: boolean,
+  used: number,
+) {
+  return {
+    ok: true as const,
+    action: request.action,
+    memoryId: extras.memoryId,
+    namespace: extras.namespace,
+    items,
+    truncated,
+    budget: { chars: extras.budgetChars, used },
+    disclosureSpend: summarizeDisclosureTokens(
+      items.map((item) => ({ disclosure: item.disclosure, estimatedTokens: item.estimatedTokens })),
+    ),
+  };
+}
+
+function structuredCost(
+  request: RecallNavigationRequest,
+  extras: { memoryId: string; namespace: string; budgetChars: number },
+  items: NavigationItem[],
+  truncated: boolean,
+  used = 0,
+): number {
+  return JSON.stringify(structuredBody(request, extras, items, truncated, used)).length;
+}
+
+function measuredUsed(
+  request: RecallNavigationRequest,
+  extras: { memoryId: string; namespace: string; budgetChars: number },
+  items: NavigationItem[],
+  truncated: boolean,
+): number {
+  return structuredCost(request, extras, items, truncated, structuredCost(request, extras, items, truncated));
+}
+
+function shrinkItemToBudget(
+  request: RecallNavigationRequest,
+  extras: { memoryId: string; namespace: string; budgetChars: number },
+  item: NavigationItem,
+): NavigationItem | undefined {
+  let preview = item.preview;
+  let content = item.content ?? "";
+  const hasContent = item.content !== undefined;
+  while (preview.length > 0 || content.length > 0) {
+    const candidate: NavigationItem = hasContent
+      ? { ...item, preview, content }
+      : { ...item, preview };
+    if (takeNavigateBudget(extras.budgetChars, structuredCost(request, extras, [candidate], true)).ok) {
+      return candidate;
+    }
+    if (content.length > 0) content = content.slice(0, Math.max(0, content.length - 16));
+    else preview = preview.slice(0, Math.max(0, preview.length - 16));
+  }
+  return undefined;
+}
+
+function errorResult(
+  request: RecallNavigationRequest,
+  error: RecallNavigationError,
+  message: string,
+): RecallNavigationResult {
+  return { ok: false, action: request.action, error, message, rendered: renderNavigationResult({ ok: false, action: request.action, error, message }) };
+}
+
+function successResult(
+  request: RecallNavigationRequest,
+  extras: { memoryId: string; namespace: string; items: NavigationItem[]; truncated: boolean; budgetChars: number },
+): RecallNavigationResult {
+  const budgeted = applyBudget(request, extras);
+  const result = structuredBody(request, extras, budgeted.items, budgeted.truncated, budgeted.used);
+  return { ...result, rendered: renderNavigationResult(result) };
+}
+
+function resolveRequestedMemoryId(
+  request: RecallNavigationRequest,
+  snapshots: ReadonlyArray<readonly string[]>,
+  windowSnapshots: number,
+): { ok: true; memoryId: string } | { ok: false } {
+  const parsed = parseIdOrHandle(request.memoryId);
+  if (!parsed.isHandle) return { ok: true, memoryId: parsed.value };
+  const resolved = resolveHandle(
+    request.memoryId,
+    snapshots.map((memoryIds) => ({ memoryIds })),
+    windowSnapshots,
+  );
+  if (resolved.ok) return { ok: true, memoryId: resolved.memoryId };
+  if (resolved.reason === "ambiguous") {
+    throw new EngramAccessInputError(
+      `Memory handle ${request.memoryId} is ambiguous in session ${request.sessionKey}: ${resolved.candidates.join(", ")}. Cite a unique memory id instead.`,
+    );
+  }
+  return { ok: false };
+}
+
+function clampLimit(requested: number | undefined, ceiling: number): number {
+  if (requested === undefined) return Math.min(DEFAULT_TRAVERSE_LIMIT, ceiling);
+  if (!Number.isInteger(requested) || requested < 1) {
+    throw new EngramAccessInputError(
+      `memory navigation: limit must be a positive integer; got ${JSON.stringify(requested)}`,
+    );
+  }
+  return Math.min(requested, ceiling);
+}
+
+/**
+ * Run one navigation step. Throws {@link EngramAccessInputError} for caller
+ * faults (missing sessionKey, malformed limit); returns typed errors for
+ * domain refusals so MCP/HTTP/CLI render the constraint instead of a stack.
+ */
+export async function runRecallNavigation(
+  deps: RecallNavigationDeps,
+  request: RecallNavigationRequest,
+): Promise<RecallNavigationResult> {
+  if (!deps.config.enabled) {
+    return errorResult(request, "disabled", "memory navigation is disabled; set recallNavigation.enabled");
+  }
+  const sessionKey = request.sessionKey?.trim() ?? "";
+  if (sessionKey.length === 0) {
+    throw new EngramAccessInputError(
+      "memory navigation requires a sessionKey: navigation authority is scoped to the session's recent recalls",
+    );
+  }
+  if (request.limit !== undefined) {
+    // Validate at the seam so every surface reports the same fault.
+    clampLimit(request.limit, deps.config.maxNeighbors);
+  }
+  const windowSnapshots = deps.config.windowSnapshots;
+  const servedIds = deps.recentServedIds(sessionKey, windowSnapshots);
+  const resolved = resolveRequestedMemoryId(request, servedIds, windowSnapshots);
+  if (!resolved.ok) {
+    return errorResult(
+      request,
+      "not_served",
+      `memory ${request.memoryId} was not served to session ${sessionKey} within the last ${windowSnapshots} recall snapshots; run recall first`,
+    );
+  }
+  const authority = assertIdInNavigationWindow({
+    snapshots: servedIds.map((ids) => ({ servedIds: ids })),
+    memoryId: resolved.memoryId,
+    windowSnapshots,
+  });
+  if (!authority.ok) {
+    return errorResult(
+      request,
+      "not_served",
+      `memory ${request.memoryId} was not served to session ${sessionKey} within the last ${windowSnapshots} recall snapshots; run recall first`,
+    );
+  }
+  const memoryId = authority.memoryId;
+  const namespace = deps.resolveReadableNamespace(request.namespace, request.authenticatedPrincipal);
+  const storage = await deps.getStorage(namespace);
+  const memory = await storage.getMemoryById(memoryId);
+  if (!memory) {
+    return errorResult(
+      request,
+      "not_found",
+      `memory ${memoryId} was not found in namespace ${namespace}; navigation never crosses the resolved namespace`,
+    );
+  }
+
+  if (request.action === "expand") {
+    const target = request.disclosure ?? "raw";
+    const step = planDisclosureStep({ from: "chunk", to: target });
+    if (!step.ok) {
+      const message =
+        step.error === "unknown_level"
+          ? `unknown disclosure level ${JSON.stringify(target)}; valid: chunk, section, raw`
+          : `disclosure ${JSON.stringify(target)} is not deeper than the chunk level already served; expansion must go deeper (chunk → section → raw)`;
+      return errorResult(request, step.error, message);
+    }
+    const summary = shapeMemorySummary(memory, storage.dir, target);
+    return successResult(request, {
+      memoryId,
+      namespace,
+      items: [toNavigationItem(summary)],
+      truncated: false,
+      budgetChars: deps.recallBudgetChars,
+    });
+  }
+
+  if (request.action === "traverse") {
+    if (request.relation !== undefined) {
+      const parsedRelation = parseNavigateLinkType(request.relation);
+      if (!parsedRelation.ok) {
+        return errorResult(
+          request,
+          "unknown_relation",
+          `unknown relation ${JSON.stringify(request.relation)}; valid: supports, contradicts, elaborates, causes, caused_by, supersedes, follows, references, related`,
+        );
+      }
+    }
+    const links: TraverseNeighbor[] = (memory.frontmatter.links ?? []).map((link) => ({
+      targetId: link.targetId,
+      linkType: link.linkType,
+    }));
+    const selection = selectTraverseNeighbors({
+      links,
+      relation: request.relation,
+      limit: clampLimit(request.limit, deps.config.maxNeighbors),
+    });
+    if (!selection.ok) {
+      return errorResult(request, selection.error, `traverse refused: ${selection.error}`);
+    }
+    const items: NavigationItem[] = [];
+    for (const neighbor of selection.neighbors) {
+      // Neighbors resolve through the SAME namespace storage: a link pointing
+      // at a memory in another namespace simply is not found here, so a stale
+      // or foreign edge can never leak content across namespaces.
+      const neighborMemory = await storage.getMemoryById(neighbor.targetId);
+      if (!neighborMemory) continue;
+      items.push(toNavigationItem(shapeMemorySummary(neighborMemory, storage.dir, "chunk"), { linkType: neighbor.linkType }));
+    }
+    return successResult(request, {
+      memoryId,
+      namespace,
+      items,
+      truncated: selection.truncated,
+      budgetChars: deps.recallBudgetChars,
+    });
+  }
+
+  // entity_neighbors: memories sharing the source memory's entityRef, capped
+  // by limit, rendered at chunk depth. No entityRef → no neighbors (empty is
+  // an honest answer, not an error).
+  const entityRef = memory.frontmatter.entityRef?.trim();
+  if (!entityRef) {
+    return successResult(request, { memoryId, namespace, items: [], truncated: false, budgetChars: deps.recallBudgetChars });
+  }
+  const window = await storage.readMemoriesWindow();
+  const candidates: NavigationItem[] = [];
+  for (const candidate of window.memories) {
+    if (candidate.frontmatter.id === memoryId) continue;
+    if (candidate.frontmatter.entityRef?.trim() !== entityRef) continue;
+    candidates.push(toNavigationItem(shapeMemorySummary(candidate, storage.dir, "chunk")));
+    if (candidates.length >= clampLimit(request.limit, deps.config.maxNeighbors)) break;
+  }
+  return successResult(request, {
+    memoryId,
+    namespace,
+    items: candidates,
+    truncated: false,
+    budgetChars: deps.recallBudgetChars,
+  });
+}

package/src/recall-xray.ts

@@ -631,7 +631,7 @@ function cloneResult(result: RecallXrayResult): RecallXrayResult {
  * "per-disclosure token spend" line and exposed for tests / surfaces.
  */
 export function summarizeDisclosureTokens(
-  results: ReadonlyArray<RecallXrayResult>,
+  results: ReadonlyArray<Pick<RecallXrayResult, "disclosure" | "estimatedTokens">>,
 ): RecallXrayDisclosureSummary {
   const summary: RecallXrayDisclosureSummary = {
     chunk: { count: 0, estimatedTokens: 0 },

package/src/types.ts

@@ -21,6 +21,7 @@ import type {
   RecallDriftAnnotation,
 } from "./preferences/drift-types.js";
 import type { DeepRecallSettings } from "./deep-recall-config.js";
+import type { RecallNavigationSettings } from "./recall-navigation-config.js";
 import type { ProceduralMaintenanceConfig } from "./procedural/maintenance-config.js";
 import type { SkillProjectionConfig } from "./procedural/skill-projection.js";
 import type { ActionGateConfig } from "./coding/action-gate.js";
@@ -693,6 +694,7 @@ export interface PluginConfig
     DriftDetectionSettings,
     ActiveContextConfigFields,
     DeepRecallSettings,
+    RecallNavigationSettings,
     LocalLlmConfig {
   openaiApiKey: string | undefined;
   openaiBaseUrl: string | undefined;

package/src/wearables/pipeline.ts

@@ -15,6 +15,7 @@
  * write for the run has succeeded.
  */
 
+import { fillWearableConversationLocations } from "../location/tagging.js";
 import { cleanConversation } from "./cleanup.js";
 import { describeErrorForOperator, WearablesInputError } from "./errors.js";
 import {
@@ -50,6 +51,7 @@ import {
   saveSyncState,
   updateSourceSyncState,
 } from "./sync-state.js";
+import type { LocationConfig } from "../location/types.js";
 import type {
   WearableConversation,
   WearableSourceConnector,
@@ -122,6 +124,11 @@ export interface WearableSyncDeps {
   listSupportMemories?(): Promise<Array<{ id: string; content: string }>>;
   /** Clock injection for tests. */
   now?: () => Date;
+  /**
+   * Location config for the missing-only conversation location fill
+   * (issue #2925). Absent, or location tagging disabled, changes nothing.
+   */
+  locationConfig?: LocationConfig;
 }
 
 /** Format a Date as YYYY-MM-DD in the given IANA timezone. */
@@ -382,6 +389,18 @@ export async function syncWearableSource(
     summary.redactions += cleaned.redactions;
     summary.correctionsApplied += cleaned.correctionsApplied;
 
+    // Missing-only location fill (issue #2925): run before the body is
+    // composed so a qualifying dominant-overlap place reaches the day
+    // transcript and memory headers exactly like a provider-supplied
+    // location would. Source-provided values are never overwritten, and
+    // the helper no-ops unless both location gates are on.
+    if (deps.locationConfig) {
+      await fillWearableConversationLocations(cleaned.conversations, {
+        memoryDir: deps.memoryDir,
+        config: deps.locationConfig,
+      });
+    }
+
     if (fetched.conversations.length === 0) {
       // No provider data at all. A transient provider hiccup can
       // legitimately produce an empty result, so an existing stored

package/src/wearables/service.ts

@@ -13,6 +13,7 @@ import {
 } from "./corrections.js";
 import { describeErrorForOperator, WearablesInputError } from "./errors.js";
 import { inferMemoryStatus } from "../memory-lifecycle-ledger-utils.js";
+import type { LocationConfig } from "../location/types.js";
 import { isSupportPassportPrivateMemory } from "../support-passport/card-projection.js";
 import {
   bodyIsEscaped,
@@ -143,6 +144,12 @@ export interface WearablesServiceDeps {
    * fails the sync.
    */
   onDaysSynced?: (days: readonly string[]) => void | Promise<void>;
+  /**
+   * Location config for the missing-only conversation location fill
+   * (issue #2925). Absent changes nothing; the fill itself stays gated
+   * on the location tagging flags.
+   */
+  locationConfig?: LocationConfig;
 }
 
 export interface WearableTranscriptSearchResult {
@@ -351,6 +358,7 @@ export class WearablesService {
         options,
         {
           memoryDir: storage.dir,
+          locationConfig: this.deps.locationConfig,
           readDayContentHash: async (source, date) => {
             const raw = await storage.readWearableDayTranscript(source, date);
             if (raw === null) return null;