@remnic/core 9.69.49 → 9.69.51

package/dist/{chunk-EST3J4LX.js → chunk-2SZBCM2S.js}

@@ -1,6 +1,6 @@
 import {
   rebuildMemoryProjection
-} from "./chunk-AOMVOC2E.js";
+} from "./chunk-KBHDV7P3.js";
 
 // src/convergence-refresh.ts
 async function refreshConvergedNamespaces(namespaces, namespaceSearchRouter, getStorage, searchEnabled) {
@@ -32,4 +32,4 @@ async function refreshConvergedNamespaces(namespaces, namespaceSearchRouter, get
 export {
   refreshConvergedNamespaces
 };
-//# sourceMappingURL=chunk-EST3J4LX.js.map
+//# sourceMappingURL=chunk-2SZBCM2S.js.map

package/dist/{chunk-UB4UVALS.js → chunk-33SX6K3N.js}

@@ -4,7 +4,7 @@ import {
 import {
   computeCorpusWatermarks,
   resolveCorpusNamespaceRoots
-} from "./chunk-3MX4GWJO.js";
+} from "./chunk-JGPG5UHM.js";
 
 // src/operator-doctor-corpus.ts
 var DIGEST_PREFIX_LENGTH = 12;
@@ -78,4 +78,4 @@ export {
   corpusWatermarksFromCheck,
   summarizeCorpusAndReplica
 };
-//# sourceMappingURL=chunk-UB4UVALS.js.map
+//# sourceMappingURL=chunk-33SX6K3N.js.map

package/dist/{chunk-P36WML7L.js → chunk-3QZRSEAM.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-B7RWBZXW.js";
 import {
   StorageManager
-} from "./chunk-AJLQH4RO.js";
+} from "./chunk-RIP2AOZW.js";
 import {
   getCachedEpisodeMap,
   setCachedEpisodeMap
@@ -109,4 +109,4 @@ export {
   compareVerifiedEpisodeResults,
   searchVerifiedEpisodes
 };
-//# sourceMappingURL=chunk-P36WML7L.js.map
+//# sourceMappingURL=chunk-3QZRSEAM.js.map

package/dist/chunk-4KQIWY4A.js

@@ -0,0 +1,197 @@
+import {
+  coerceBooleanLike,
+  coerceNumber
+} from "./chunk-PQVCH2AE.js";
+import {
+  log
+} from "./chunk-3WCASNQZ.js";
+
+// src/recall-recognition-tier.ts
+import { promises as fsp } from "fs";
+import path from "path";
+var DEFAULT_RECALL_RECOGNITION_TIER = false;
+var DEFAULT_RECOGNITION_INDEX_MAX_ENTRIES = 500;
+var RECOGNITION_INDEX_VERSION = 1;
+var RECOGNITION_INDEX_FILE = "index_recognition.json";
+var RECOGNITION_PROMPT_HEADER = "Memory index \u2014 one line per memory. Name the ids that bear on the question.";
+var RECOGNITION_PROMPT_FOOTER = "Answer with the relevant ids only, comma-separated. If none bear on the question, answer with nothing.";
+function parseRecallRecognitionTier(raw) {
+  return coerceBooleanLike(raw, "recallRecognitionTier") === true;
+}
+function parseRecognitionIndexMaxEntries(raw) {
+  if (raw === void 0 || raw === null) return DEFAULT_RECOGNITION_INDEX_MAX_ENTRIES;
+  const n = coerceNumber(raw, "recognitionIndexMaxEntries");
+  if (n === void 0 || !Number.isFinite(n) || n < 1) {
+    throw new Error(
+      `Invalid recognitionIndexMaxEntries: expected an integer >= 1, got ${JSON.stringify(raw)}`
+    );
+  }
+  return Math.floor(n);
+}
+function recognitionIndexPath(memoryDir) {
+  return path.join(memoryDir, "state", RECOGNITION_INDEX_FILE);
+}
+function buildRecognitionIndex(records) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const record of records) {
+    const id = typeof record.id === "string" ? record.id.trim() : "";
+    if (id.length === 0 || seen.has(id)) continue;
+    seen.add(id);
+    out.push({
+      id,
+      description: typeof record.description === "string" ? record.description.trim() : ""
+    });
+  }
+  return { version: RECOGNITION_INDEX_VERSION, entries: out };
+}
+async function saveRecognitionIndex(memoryDir, index) {
+  const file = recognitionIndexPath(memoryDir);
+  await fsp.mkdir(path.dirname(file), { recursive: true });
+  await fsp.writeFile(file, `${JSON.stringify(index, null, 2)}
+`, "utf8");
+}
+function isRecognitionIndex(raw) {
+  if (typeof raw !== "object" || raw === null) return false;
+  const candidate = raw;
+  if (candidate.version !== RECOGNITION_INDEX_VERSION) return false;
+  if (!Array.isArray(candidate.entries)) return false;
+  return candidate.entries.every(
+    (entry) => typeof entry === "object" && entry !== null && typeof entry.id === "string" && typeof entry.description === "string"
+  );
+}
+async function loadRecognitionIndex(memoryDir) {
+  try {
+    const raw = await fsp.readFile(recognitionIndexPath(memoryDir), "utf8");
+    const parsed = JSON.parse(raw);
+    if (isRecognitionIndex(parsed)) return parsed;
+    log.warn(
+      `recognition index ignored at ${RECOGNITION_INDEX_FILE}: unexpected shape; falling back to vector search`
+    );
+    return null;
+  } catch {
+    return null;
+  }
+}
+function decideRecognitionTier(index, opts) {
+  const maxEntries = Math.max(1, Math.floor(opts.maxEntries));
+  if (index === null) {
+    return { tier: "vector", reason: "index_absent", entriesConsidered: 0, maxEntries };
+  }
+  if (index.entries.length > maxEntries) {
+    return {
+      tier: "vector",
+      reason: "index_above_threshold",
+      entriesConsidered: index.entries.length,
+      maxEntries
+    };
+  }
+  return {
+    tier: "recognition",
+    reason: "index_within_threshold",
+    entriesConsidered: index.entries.length,
+    maxEntries
+  };
+}
+function renderRecognitionIndex(entries) {
+  return entries.map((entry) => `${entry.id}: ${entry.description}`).join("\n");
+}
+function buildRecognitionPrompt(query, entries) {
+  return [
+    RECOGNITION_PROMPT_HEADER,
+    renderRecognitionIndex(entries),
+    `Question: ${query}`,
+    RECOGNITION_PROMPT_FOOTER
+  ].join("\n\n");
+}
+function dedupeOrdered(tokens) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const token of tokens) {
+    if (token.length > 0 && !seen.has(token)) {
+      seen.add(token);
+      out.push(token);
+    }
+  }
+  return out;
+}
+var TRAILING_PUNCTUATION = { ".": true, ",": true, ";": true, ":": true };
+function stripTrailingPunctuation(value) {
+  let end = value.length;
+  while (end > 0 && TRAILING_PUNCTUATION[value.charAt(end - 1)]) end -= 1;
+  return value.slice(0, end);
+}
+function parseRecognizerIds(output) {
+  if (typeof output !== "string") return [];
+  const text = output.trim();
+  if (text.length === 0) return [];
+  if (text.startsWith("[")) {
+    try {
+      const parsed = JSON.parse(text);
+      if (Array.isArray(parsed)) {
+        return dedupeOrdered(
+          parsed.filter((item) => typeof item === "string").map((item) => stripTrailingPunctuation(item.trim()).trim())
+        );
+      }
+    } catch {
+    }
+  }
+  return dedupeOrdered(
+    text.split(/[\s,]+/).map((token) => stripTrailingPunctuation(token.replace(/^[•\-*\d.)\]]+/, "")).trim())
+  );
+}
+async function runRecognitionTier(query, entries, recognize) {
+  if (entries.length === 0) {
+    return { ids: [], dropped: [], skipped: true };
+  }
+  const raw = parseRecognizerIds(await recognize(buildRecognitionPrompt(query, entries)));
+  const byId = new Map(entries.map((entry) => [entry.id, entry]));
+  const picked = new Set(raw.filter((token) => byId.has(token)));
+  return {
+    ids: entries.filter((entry) => picked.has(entry.id)).map((entry) => entry.id),
+    dropped: dedupeOrdered(raw.filter((token) => !byId.has(token))),
+    skipped: false
+  };
+}
+async function recallViaRecognitionTier(args) {
+  const index = await loadRecognitionIndex(args.memoryDir);
+  const decision = decideRecognitionTier(index, { maxEntries: args.maxEntries });
+  if (index === null || decision.tier === "vector") {
+    return { decision, ids: [], vectorResults: await args.vectorSearch() };
+  }
+  try {
+    const run = await runRecognitionTier(args.query, index.entries, args.recognize);
+    return { decision, ids: run.ids, vectorResults: [] };
+  } catch (err) {
+    log.warn(
+      `recognition tier degraded to vector search: recognizer failed${err instanceof Error ? ` (${err.message})` : ""}`
+    );
+    return {
+      decision,
+      ids: [],
+      vectorResults: await args.vectorSearch(),
+      degraded: "recognizer_unavailable"
+    };
+  }
+}
+
+export {
+  DEFAULT_RECALL_RECOGNITION_TIER,
+  DEFAULT_RECOGNITION_INDEX_MAX_ENTRIES,
+  RECOGNITION_INDEX_VERSION,
+  RECOGNITION_PROMPT_HEADER,
+  RECOGNITION_PROMPT_FOOTER,
+  parseRecallRecognitionTier,
+  parseRecognitionIndexMaxEntries,
+  recognitionIndexPath,
+  buildRecognitionIndex,
+  saveRecognitionIndex,
+  loadRecognitionIndex,
+  decideRecognitionTier,
+  renderRecognitionIndex,
+  buildRecognitionPrompt,
+  parseRecognizerIds,
+  runRecognitionTier,
+  recallViaRecognitionTier
+};
+//# sourceMappingURL=chunk-4KQIWY4A.js.map

package/dist/chunk-4KQIWY4A.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/recall-recognition-tier.ts"],"sourcesContent":["/**\n * Full-index recognition tier (issue #2975, foundation slice).\n *\n * distill-kura's recall does not search — it recognizes: the entire\n * namespace index (one line per memory: id + description) goes into a\n * single prompt and a small model names which entries bear on the\n * question. Keyword/vector search misses same-subject-different-words\n * cases; a recognizer that reads the whole index cannot miss what it\n * can see (~500 entries ≈ 6k tokens, sub-second locally).\n *\n * This slice ships the deterministic tier machinery only — nothing on\n * the live recall path reads it yet, so recall behavior is unchanged:\n *  - a compact per-namespace index persisted at\n *    `<namespace memoryDir>/state/index_recognition.json` with\n *    build/save/load; loading is total: missing, corrupt, wrong-shape,\n *    or future-version indexes all yield `null`, never an error;\n *  - the tier decision, pure on (index, maxEntries): index present and\n *    at or under the entry threshold → recognition; absent or above →\n *    the vector tier, no error thrown;\n *  - the runner: renders the FULL index into one prompt, asks the\n *    recognizer for ids, keeps only ids the index actually carries, and\n *    returns them in index order — never recognizer order;\n *  - loud degradation: a recognizer that fails falls back to vector\n *    search labeled `recognizer_unavailable` (quiet degradation is\n *    worse than degradation).\n *\n * Determinism rules:\n *  - the decision is a pure function of (index, maxEntries) — no clock,\n *    no I/O, no locale;\n *  - an empty index short-circuits: no model call, zero candidates;\n *  - the prompt and the returned ids are byte-identical across runs\n *    with unchanged inputs.\n *\n * Host contract for the wiring slices:\n *  - maintenance slice: build/save the index at memory write time from\n *    each memory's id + description line (a recognition trigger — proper\n *    nouns, numbers, landmines, the conclusion reached — not a summary),\n *    serializing writes the way temporal-index does (op chain + lock);\n *    saveRecognitionIndex here is single-writer and does not lock;\n *  - recall slice: for each recalled namespace call\n *    recallViaRecognitionTier with the recognizer (one small-model call)\n *    and the existing vector search as the fallback; expand picks\n *    through the graph neighborhood, merge through the normal pipeline\n *    (filters → rerank → budget), and record tier = recognition plus any\n *    degraded fallback in xray;\n *  - config keys recallRecognitionTier (default false) and\n *    recognitionIndexMaxEntries (default 500) gate the wiring.\n */\nimport { promises as fsp } from \"node:fs\";\nimport path from \"node:path\";\nimport { coerceBooleanLike, coerceNumber } from \"./connectors/coerce.js\";\nimport { log } from \"./logger.js\";\n\nexport const DEFAULT_RECALL_RECOGNITION_TIER = false;\nexport const DEFAULT_RECOGNITION_INDEX_MAX_ENTRIES = 500;\nexport const RECOGNITION_INDEX_VERSION = 1;\nconst RECOGNITION_INDEX_FILE = \"index_recognition.json\";\n\nexport const RECOGNITION_PROMPT_HEADER =\n  \"Memory index — one line per memory. Name the ids that bear on the question.\";\nexport const RECOGNITION_PROMPT_FOOTER =\n  \"Answer with the relevant ids only, comma-separated. If none bear on the question, answer with nothing.\";\n\nexport interface RecognitionIndexEntry {\n  /** Stable memory id. Candidates always come back in index order. */\n  id: string;\n  /** One-line recognition trigger; not a summary (issue #2975 swap test). */\n  description: string;\n}\n\nexport interface RecognitionIndex {\n  version: number;\n  entries: RecognitionIndexEntry[];\n}\n\n/**\n * Config fields this tier owns, mixed into `PluginConfig` (issue #2975) so\n * the keys live beside their parsers instead of growing `types.ts`.\n */\nexport interface RecognitionTierSettings {\n  /** Small namespaces recall by recognizing against the whole compact index instead of vector search; parsed now, wiring lands in a later slice. Default false. */\n  recallRecognitionTier: boolean;\n  /** Max entries a namespace's recognition index may carry for the tier to engage (inclusive). Default 500. */\n  recognitionIndexMaxEntries: number;\n}\n\nexport function parseRecallRecognitionTier(raw: unknown): boolean {\n  return coerceBooleanLike(raw, \"recallRecognitionTier\") === true;\n}\n\nexport function parseRecognitionIndexMaxEntries(raw: unknown): number {\n  if (raw === undefined || raw === null) return DEFAULT_RECOGNITION_INDEX_MAX_ENTRIES;\n  const n = coerceNumber(raw, \"recognitionIndexMaxEntries\");\n  if (n === undefined || !Number.isFinite(n) || n < 1) {\n    throw new Error(\n      `Invalid recognitionIndexMaxEntries: expected an integer >= 1, got ${JSON.stringify(raw)}`,\n    );\n  }\n  return Math.floor(n);\n}\n\n/** On-disk location of a namespace's recognition index. */\nexport function recognitionIndexPath(memoryDir: string): string {\n  return path.join(memoryDir, \"state\", RECOGNITION_INDEX_FILE);\n}\n\n/**\n * Normalize raw records into a recognition index: blank/whitespace ids\n * are dropped, descriptions are trimmed, and the first record for an id\n * wins. Input order is preserved — it is the recognition order.\n */\nexport function buildRecognitionIndex(\n  records: ReadonlyArray<{ id?: string | null; description?: string | null }>,\n): RecognitionIndex {\n  const seen = new Set<string>();\n  const out: RecognitionIndexEntry[] = [];\n  for (const record of records) {\n    const id = typeof record.id === \"string\" ? record.id.trim() : \"\";\n    if (id.length === 0 || seen.has(id)) continue;\n    seen.add(id);\n    out.push({\n      id,\n      description: typeof record.description === \"string\" ? record.description.trim() : \"\",\n    });\n  }\n  return { version: RECOGNITION_INDEX_VERSION, entries: out };\n}\n\n/**\n * Persist a recognition index. Single-writer: the maintenance slice that\n * owns index writes must serialize calls the way temporal-index does.\n */\nexport async function saveRecognitionIndex(\n  memoryDir: string,\n  index: RecognitionIndex,\n): Promise<void> {\n  const file = recognitionIndexPath(memoryDir);\n  await fsp.mkdir(path.dirname(file), { recursive: true });\n  await fsp.writeFile(file, `${JSON.stringify(index, null, 2)}\\n`, \"utf8\");\n}\n\nfunction isRecognitionIndex(raw: unknown): raw is RecognitionIndex {\n  if (typeof raw !== \"object\" || raw === null) return false;\n  const candidate = raw as { version?: unknown; entries?: unknown };\n  if (candidate.version !== RECOGNITION_INDEX_VERSION) return false;\n  if (!Array.isArray(candidate.entries)) return false;\n  return candidate.entries.every(\n    (entry) =>\n      typeof entry === \"object\" &&\n      entry !== null &&\n      typeof (entry as RecognitionIndexEntry).id === \"string\" &&\n      typeof (entry as RecognitionIndexEntry).description === \"string\",\n  );\n}\n\n/**\n * Load a namespace's recognition index. Total: a missing, corrupt,\n * wrong-shape, or future-version file all return `null` so the caller\n * falls back to vector search without an error.\n */\nexport async function loadRecognitionIndex(memoryDir: string): Promise<RecognitionIndex | null> {\n  try {\n    const raw = await fsp.readFile(recognitionIndexPath(memoryDir), \"utf8\");\n    const parsed: unknown = JSON.parse(raw);\n    if (isRecognitionIndex(parsed)) return parsed;\n    log.warn(\n      `recognition index ignored at ${RECOGNITION_INDEX_FILE}: unexpected shape; falling back to vector search`,\n    );\n    return null;\n  } catch {\n    return null;\n  }\n}\n\nexport type RecognitionRecallTier = \"recognition\" | \"vector\";\nexport type RecognitionTierReason =\n  | \"index_absent\"\n  | \"index_above_threshold\"\n  | \"index_within_threshold\";\n\nexport interface RecognitionTierDecision {\n  tier: RecognitionRecallTier;\n  reason: RecognitionTierReason;\n  /** Entries the decision considered; 0 when the index is absent. */\n  entriesConsidered: number;\n  /** Threshold in force. */\n  maxEntries: number;\n}\n\n/**\n * Deterministic tier choice, pure on (index, maxEntries). The threshold\n * is inclusive: an index of exactly maxEntries entries still recognizes\n * (a threshold-sized index is the designed working set, not an overrun).\n */\nexport function decideRecognitionTier(\n  index: RecognitionIndex | null,\n  opts: { maxEntries: number },\n): RecognitionTierDecision {\n  const maxEntries = Math.max(1, Math.floor(opts.maxEntries));\n  if (index === null) {\n    return { tier: \"vector\", reason: \"index_absent\", entriesConsidered: 0, maxEntries };\n  }\n  if (index.entries.length > maxEntries) {\n    return {\n      tier: \"vector\",\n      reason: \"index_above_threshold\",\n      entriesConsidered: index.entries.length,\n      maxEntries,\n    };\n  }\n  return {\n    tier: \"recognition\",\n    reason: \"index_within_threshold\",\n    entriesConsidered: index.entries.length,\n    maxEntries,\n  };\n}\n\n/** Render the full index, one line per entry, in index order. */\nexport function renderRecognitionIndex(entries: ReadonlyArray<RecognitionIndexEntry>): string {\n  return entries.map((entry) => `${entry.id}: ${entry.description}`).join(\"\\n\");\n}\n\n/** The single recognition prompt: header, the FULL index, the question, the answer shape. */\nexport function buildRecognitionPrompt(\n  query: string,\n  entries: ReadonlyArray<RecognitionIndexEntry>,\n): string {\n  return [\n    RECOGNITION_PROMPT_HEADER,\n    renderRecognitionIndex(entries),\n    `Question: ${query}`,\n    RECOGNITION_PROMPT_FOOTER,\n  ].join(\"\\n\\n\");\n}\n\nfunction dedupeOrdered(tokens: string[]): string[] {\n  const seen = new Set<string>();\n  const out: string[] = [];\n  for (const token of tokens) {\n    if (token.length > 0 && !seen.has(token)) {\n      seen.add(token);\n      out.push(token);\n    }\n  }\n  return out;\n}\n\nconst TRAILING_PUNCTUATION: Record<string, true> = { \".\": true, \",\": true, \";\": true, \":\": true };\n\n/**\n * Strip trailing sentence punctuation in linear time. A quantified anchored\n * regex (`/[.,;:]+$/`) backtracks polynomially on recognizer output made of\n * many separators, and that output is uncontrolled model text.\n */\nfunction stripTrailingPunctuation(value: string): string {\n  let end = value.length;\n  while (end > 0 && TRAILING_PUNCTUATION[value.charAt(end - 1)]) end -= 1;\n  return value.slice(0, end);\n}\n\n/**\n * Parse recognizer output into ordered unique id tokens. Accepts a JSON\n * string array or comma/whitespace-separated ids, and strips sentence\n * punctuation so prose wrappers do not corrupt ids. Tokens that are not\n * real ids are dropped later by validation against the index.\n */\nexport function parseRecognizerIds(output: string | null | undefined): string[] {\n  if (typeof output !== \"string\") return [];\n  const text = output.trim();\n  if (text.length === 0) return [];\n  if (text.startsWith(\"[\")) {\n    try {\n      const parsed: unknown = JSON.parse(text);\n      if (Array.isArray(parsed)) {\n        return dedupeOrdered(\n          parsed\n            .filter((item): item is string => typeof item === \"string\")\n            .map((item) => stripTrailingPunctuation(item.trim()).trim()),\n        );\n      }\n    } catch {\n      // Fall through to separator parsing.\n    }\n  }\n  return dedupeOrdered(\n    text\n      .split(/[\\s,]+/)\n      .map((token) => stripTrailingPunctuation(token.replace(/^[•\\-*\\d.)\\]]+/, \"\")).trim()),\n  );\n}\n\n/** One model call over the full index; supplied by the wiring slice. */\nexport type Recognizer = (prompt: string) => Promise<string | null | undefined>;\n\nexport interface RecognitionRunResult {\n  /** Recognized ids, validated against the index, in index order. */\n  ids: string[];\n  /** Recognizer tokens the index does not carry (hallucinated ids). */\n  dropped: string[];\n  /** True when no model call was made (empty index). */\n  skipped: boolean;\n}\n\n/**\n * Run the recognition pass: the FULL index goes into one prompt, the\n * recognizer names ids, unknown ids are dropped, and the kept ids come\n * back in index order so downstream merging stays deterministic.\n */\nexport async function runRecognitionTier(\n  query: string,\n  entries: ReadonlyArray<RecognitionIndexEntry>,\n  recognize: Recognizer,\n): Promise<RecognitionRunResult> {\n  if (entries.length === 0) {\n    return { ids: [], dropped: [], skipped: true };\n  }\n  const raw = parseRecognizerIds(await recognize(buildRecognitionPrompt(query, entries)));\n  const byId = new Map(entries.map((entry) => [entry.id, entry]));\n  const picked = new Set(raw.filter((token) => byId.has(token)));\n  return {\n    ids: entries.filter((entry) => picked.has(entry.id)).map((entry) => entry.id),\n    dropped: dedupeOrdered(raw.filter((token) => !byId.has(token))),\n    skipped: false,\n  };\n}\n\nexport interface RecognitionTierOutcome<TVector> {\n  decision: RecognitionTierDecision;\n  /** Recognition picks, index order; empty on the vector tier. */\n  ids: string[];\n  /** Vector-tier results from the fallback; empty on the recognition tier. */\n  vectorResults: TVector[];\n  /**\n   * Set when recognition was routed but the recognizer failed and the\n   * vector tier served the recall instead — loud degradation.\n   */\n  degraded?: \"recognizer_unavailable\";\n}\n\n/**\n * The wiring-seam composition for one namespace: load the index, decide\n * the tier, then either recognize against the full index or run the\n * caller's vector search. Never throws for index problems; a failing\n * recognizer degrades to vector search labeled `recognizer_unavailable`.\n */\nexport async function recallViaRecognitionTier<TVector>(args: {\n  memoryDir: string;\n  query: string;\n  maxEntries: number;\n  recognize: Recognizer;\n  vectorSearch: () => Promise<TVector[]>;\n}): Promise<RecognitionTierOutcome<TVector>> {\n  const index = await loadRecognitionIndex(args.memoryDir);\n  const decision = decideRecognitionTier(index, { maxEntries: args.maxEntries });\n  if (index === null || decision.tier === \"vector\") {\n    return { decision, ids: [], vectorResults: await args.vectorSearch() };\n  }\n  try {\n    const run = await runRecognitionTier(args.query, index.entries, args.recognize);\n    return { decision, ids: run.ids, vectorResults: [] };\n  } catch (err) {\n    log.warn(\n      `recognition tier degraded to vector search: recognizer failed${\n        err instanceof Error ? ` (${err.message})` : \"\"\n      }`,\n    );\n    return {\n      decision,\n      ids: [],\n      vectorResults: await args.vectorSearch(),\n      degraded: \"recognizer_unavailable\",\n    };\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-LBLXEFWK.js → chunk-4MN27537.js}

@@ -48,4 +48,4 @@ export {
   appendRecallAuditEntry,
   pruneRecallAuditEntries
 };
-//# sourceMappingURL=chunk-LBLXEFWK.js.map
+//# sourceMappingURL=chunk-4MN27537.js.map

package/dist/chunk-4MN27537.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/recall-audit.ts"],"sourcesContent":["import type { Dirent } from \"node:fs\";\nimport { appendFile, mkdir, readdir, rm } from \"node:fs/promises\";\nimport path from \"node:path\";\n\nimport type { RecallContextDegradation } from \"./recall-context-composition.js\";\n\nexport interface RecallAuditEntry {\n  ts: string;\n  sessionKey: string;\n  agentId: string;\n  trigger: string;\n  queryText: string;\n  candidateMemoryIds: string[];\n  summary: string | null;\n  injectedChars: number;\n  toggleState: \"enabled\" | \"disabled-primary\" | \"disabled-secondary\";\n  latencyMs?: number;\n  plannerMode?: string;\n  requestedMode?: string;\n  fallbackUsed?: boolean;\n  /** Injected-context degradation (#2972). Absent on a healthy recall. */\n  degradation?: RecallContextDegradation;\n}\n\nfunction formatIsoDate(ts: string): string {\n  const normalized = new Date(ts);\n  if (Number.isNaN(normalized.getTime())) {\n    return new Date().toISOString().slice(0, 10);\n  }\n  return normalized.toISOString().slice(0, 10);\n}\n\nexport function buildRecallAuditPath(rootDir: string, ts: string, sessionKey: string): string {\n  const safeSessionKey = encodeURIComponent(sessionKey);\n  return path.join(rootDir, \"transcripts\", formatIsoDate(ts), `${safeSessionKey}.jsonl`);\n}\n\nexport async function appendRecallAuditEntry(\n  rootDir: string,\n  entry: RecallAuditEntry,\n): Promise<string> {\n  const filePath = buildRecallAuditPath(rootDir, entry.ts, entry.sessionKey);\n  await mkdir(path.dirname(filePath), { recursive: true });\n  await appendFile(filePath, `${JSON.stringify(entry)}\\n`, \"utf8\");\n  return filePath;\n}\n\nexport async function pruneRecallAuditEntries(\n  rootDir: string,\n  retentionDays: number,\n  now: Date = new Date(),\n): Promise<string[]> {\n  const transcriptsDir = path.join(rootDir, \"transcripts\");\n  const removed: string[] = [];\n  const cutoff = new Date(now);\n  cutoff.setUTCHours(0, 0, 0, 0);\n  cutoff.setUTCDate(cutoff.getUTCDate() - Math.max(1, Math.floor(retentionDays)));\n  let entries: Dirent[];\n  try {\n    entries = await readdir(transcriptsDir, { withFileTypes: true });\n  } catch {\n    return removed;\n  }\n\n  for (const entry of entries) {\n    if (!entry.isDirectory()) continue;\n    if (!/^\\d{4}-\\d{2}-\\d{2}$/.test(entry.name)) continue;\n    const day = new Date(`${entry.name}T00:00:00.000Z`);\n    if (Number.isNaN(day.getTime()) || day >= cutoff) continue;\n    const dirPath = path.join(transcriptsDir, entry.name);\n    await rm(dirPath, { recursive: true, force: true });\n    removed.push(dirPath);\n  }\n\n  return removed;\n}\n"],"mappings":";AACA,SAAS,YAAY,OAAO,SAAS,UAAU;AAC/C,OAAO,UAAU;AAsBjB,SAAS,cAAc,IAAoB;AACzC,QAAM,aAAa,IAAI,KAAK,EAAE;AAC9B,MAAI,OAAO,MAAM,WAAW,QAAQ,CAAC,GAAG;AACtC,YAAO,oBAAI,KAAK,GAAE,YAAY,EAAE,MAAM,GAAG,EAAE;AAAA,EAC7C;AACA,SAAO,WAAW,YAAY,EAAE,MAAM,GAAG,EAAE;AAC7C;AAEO,SAAS,qBAAqB,SAAiB,IAAY,YAA4B;AAC5F,QAAM,iBAAiB,mBAAmB,UAAU;AACpD,SAAO,KAAK,KAAK,SAAS,eAAe,cAAc,EAAE,GAAG,GAAG,cAAc,QAAQ;AACvF;AAEA,eAAsB,uBACpB,SACA,OACiB;AACjB,QAAM,WAAW,qBAAqB,SAAS,MAAM,IAAI,MAAM,UAAU;AACzE,QAAM,MAAM,KAAK,QAAQ,QAAQ,GAAG,EAAE,WAAW,KAAK,CAAC;AACvD,QAAM,WAAW,UAAU,GAAG,KAAK,UAAU,KAAK,CAAC;AAAA,GAAM,MAAM;AAC/D,SAAO;AACT;AAEA,eAAsB,wBACpB,SACA,eACA,MAAY,oBAAI,KAAK,GACF;AACnB,QAAM,iBAAiB,KAAK,KAAK,SAAS,aAAa;AACvD,QAAM,UAAoB,CAAC;AAC3B,QAAM,SAAS,IAAI,KAAK,GAAG;AAC3B,SAAO,YAAY,GAAG,GAAG,GAAG,CAAC;AAC7B,SAAO,WAAW,OAAO,WAAW,IAAI,KAAK,IAAI,GAAG,KAAK,MAAM,aAAa,CAAC,CAAC;AAC9E,MAAI;AACJ,MAAI;AACF,cAAU,MAAM,QAAQ,gBAAgB,EAAE,eAAe,KAAK,CAAC;AAAA,EACjE,QAAQ;AACN,WAAO;AAAA,EACT;AAEA,aAAW,SAAS,SAAS;AAC3B,QAAI,CAAC,MAAM,YAAY,EAAG;AAC1B,QAAI,CAAC,sBAAsB,KAAK,MAAM,IAAI,EAAG;AAC7C,UAAM,MAAM,oBAAI,KAAK,GAAG,MAAM,IAAI,gBAAgB;AAClD,QAAI,OAAO,MAAM,IAAI,QAAQ,CAAC,KAAK,OAAO,OAAQ;AAClD,UAAM,UAAU,KAAK,KAAK,gBAAgB,MAAM,IAAI;AACpD,UAAM,GAAG,SAAS,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC;AAClD,YAAQ,KAAK,OAAO;AAAA,EACtB;AAEA,SAAO;AACT;","names":[]}

package/dist/{chunk-JI5Q6EOY.js → chunk-6HCJWCA4.js}

@@ -1,6 +1,6 @@
 import {
   startLocationAutoSync
-} from "./chunk-Z2OKRO3E.js";
+} from "./chunk-PYTSGD5M.js";
 import {
   ensureContradictionScanCron,
   ensureDaySummaryCron,
@@ -12,14 +12,14 @@ import {
 } from "./chunk-666A3MOW.js";
 import {
   rebuildMemoryLifecycleLedger
-} from "./chunk-WGCASEEQ.js";
+} from "./chunk-SZ75IB2T.js";
 import {
   planNamespaceMaintenance,
   runNamespaceMaintenanceBatchPlan
-} from "./chunk-UE7L4EDU.js";
+} from "./chunk-HEKWNWNL.js";
 import {
   rebuildMemoryProjection
-} from "./chunk-AOMVOC2E.js";
+} from "./chunk-KBHDV7P3.js";
 import {
   DEFAULT_TIMELINE_CATEGORIES,
   TIMELINE_RESERVED_IDLE,
@@ -2450,4 +2450,4 @@ export {
   ActivitySyncScheduler,
   MaintenanceScheduler
 };
-//# sourceMappingURL=chunk-JI5Q6EOY.js.map
+//# sourceMappingURL=chunk-6HCJWCA4.js.map

package/dist/chunk-6VITOSPL.js

@@ -0,0 +1,69 @@
+import {
+  RECALL_CONTEXT_SEPARATOR,
+  boundRecallContextComposition,
+  composeMissingMemoryContext,
+  composeRecallContext
+} from "./chunk-IHOXK2I6.js";
+import {
+  isAbortError
+} from "./chunk-BTTPKDIL.js";
+
+// src/recall-composition-decision.ts
+function firstLine(content) {
+  const trimmed = content.trim();
+  if (trimmed.length === 0) return "";
+  const newline = trimmed.indexOf("\n");
+  return newline === -1 ? trimmed : trimmed.slice(0, newline).trimEnd();
+}
+function chunkContent(chunk) {
+  return typeof chunk === "string" ? chunk : chunk.content;
+}
+function compactRecallContextFromBuckets(buckets) {
+  const sections = [];
+  for (const [, chunks] of buckets) {
+    const lines = [];
+    for (const chunk of chunks) {
+      const line = firstLine(chunkContent(chunk));
+      if (line.length > 0) lines.push(line);
+    }
+    if (lines.length > 0) sections.push(lines.join("\n"));
+  }
+  return sections.join(RECALL_CONTEXT_SEPARATOR);
+}
+function decideRecallContextComposition(input) {
+  const composition = boundRecallContextComposition({
+    context: input.context,
+    footer: input.footer,
+    maxChars: input.maxChars,
+    compactContext: input.compactContext
+  });
+  return {
+    composition,
+    context: composeRecallContext(composition),
+    truncated: composition.degradation?.reason === "budget-clipped" || composition.degradation?.reason === "budget-compacted"
+  };
+}
+function notifyContextComposition(onContextComposition, composition, onError) {
+  if (!onContextComposition) return;
+  try {
+    const result = onContextComposition(composition);
+    if (result && typeof result.then === "function") {
+      void Promise.resolve(result).catch(onError);
+    }
+  } catch (err) {
+    onError(err);
+  }
+}
+function recallFailureComposition(err) {
+  if (isAbortError(err)) return null;
+  const detail = err instanceof Error && err.message === "recall timeout" ? "timeout" : "recall_failed";
+  return composeMissingMemoryContext({ detail });
+}
+
+export {
+  compactRecallContextFromBuckets,
+  decideRecallContextComposition,
+  notifyContextComposition,
+  recallFailureComposition
+};
+//# sourceMappingURL=chunk-6VITOSPL.js.map

package/dist/chunk-6VITOSPL.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/recall-composition-decision.ts"],"sourcesContent":["/**\n * Recall composition decision (#2972 layer 2).\n *\n * Extracted from recall-internal so that file stays under its ratchet\n * ceiling. Classifies injected memory context as complete / degraded /\n * missing, builds the compact (first-line) form from section buckets,\n * and turns outer-recall failures into the missing-note instead of \"\".\n */\n\nimport { isAbortError } from \"./abort-error.js\";\nimport {\n  boundRecallContextComposition,\n  composeMissingMemoryContext,\n  composeRecallContext,\n  RECALL_CONTEXT_SEPARATOR,\n  type RecallContextComposition,\n} from \"./recall-context-composition.js\";\n\nexport type RecallCompositionChunk = string | { readonly content: string };\n\nexport interface DecideRecallContextCompositionInput {\n  context: string;\n  compactContext?: string;\n  footer?: string;\n  maxChars: number;\n}\n\nexport interface DecidedRecallContextComposition {\n  composition: RecallContextComposition;\n  context: string;\n  truncated: boolean;\n}\n\nfunction firstLine(content: string): string {\n  const trimmed = content.trim();\n  if (trimmed.length === 0) return \"\";\n  const newline = trimmed.indexOf(\"\\n\");\n  return newline === -1 ? trimmed : trimmed.slice(0, newline).trimEnd();\n}\n\nfunction chunkContent(chunk: RecallCompositionChunk): string {\n  return typeof chunk === \"string\" ? chunk : chunk.content;\n}\n\n/**\n * Shallow form of every section chunk: the first line of each entry,\n * so a budget miss prefers breadth-complete-but-shallow over a clipped\n * tail. Empty chunks contribute nothing.\n */\nexport function compactRecallContextFromBuckets(\n  buckets: Iterable<readonly [unknown, readonly RecallCompositionChunk[]]>,\n): string {\n  const sections: string[] = [];\n  for (const [, chunks] of buckets) {\n    const lines: string[] = [];\n    for (const chunk of chunks) {\n      const line = firstLine(chunkContent(chunk));\n      if (line.length > 0) lines.push(line);\n    }\n    if (lines.length > 0) sections.push(lines.join(\"\\n\"));\n  }\n  return sections.join(RECALL_CONTEXT_SEPARATOR);\n}\n\nexport function decideRecallContextComposition(\n  input: DecideRecallContextCompositionInput,\n): DecidedRecallContextComposition {\n  const composition = boundRecallContextComposition({\n    context: input.context,\n    footer: input.footer,\n    maxChars: input.maxChars,\n    compactContext: input.compactContext,\n  });\n  return {\n    composition,\n    context: composeRecallContext(composition),\n    truncated:\n      composition.degradation?.reason === \"budget-clipped\" ||\n      composition.degradation?.reason === \"budget-compacted\",\n  };\n}\n\nexport function notifyContextComposition(\n  onContextComposition:\n    | ((composition: RecallContextComposition) => void | PromiseLike<void>)\n    | undefined,\n  composition: RecallContextComposition,\n  onError: (err: unknown) => void,\n): void {\n  if (!onContextComposition) return;\n  try {\n    const result = onContextComposition(composition);\n    if (result && typeof result.then === \"function\") {\n      void Promise.resolve(result).catch(onError);\n    }\n  } catch (err) {\n    onError(err);\n  }\n}\n\n/**\n * Outer-recall failure: abort stays silent (empty string). Timeout and\n * other errors become the missing-note so a failed query is never\n * indistinguishable from \"no matches\".\n */\nexport function recallFailureComposition(err: unknown): RecallContextComposition | null {\n  if (isAbortError(err)) return null;\n  const detail =\n    err instanceof Error && err.message === \"recall timeout\"\n      ? \"timeout\"\n      : \"recall_failed\";\n  return composeMissingMemoryContext({ detail });\n}\n"],"mappings":";;;;;;;;;;;AAiCA,SAAS,UAAU,SAAyB;AAC1C,QAAM,UAAU,QAAQ,KAAK;AAC7B,MAAI,QAAQ,WAAW,EAAG,QAAO;AACjC,QAAM,UAAU,QAAQ,QAAQ,IAAI;AACpC,SAAO,YAAY,KAAK,UAAU,QAAQ,MAAM,GAAG,OAAO,EAAE,QAAQ;AACtE;AAEA,SAAS,aAAa,OAAuC;AAC3D,SAAO,OAAO,UAAU,WAAW,QAAQ,MAAM;AACnD;AAOO,SAAS,gCACd,SACQ;AACR,QAAM,WAAqB,CAAC;AAC5B,aAAW,CAAC,EAAE,MAAM,KAAK,SAAS;AAChC,UAAM,QAAkB,CAAC;AACzB,eAAW,SAAS,QAAQ;AAC1B,YAAM,OAAO,UAAU,aAAa,KAAK,CAAC;AAC1C,UAAI,KAAK,SAAS,EAAG,OAAM,KAAK,IAAI;AAAA,IACtC;AACA,QAAI,MAAM,SAAS,EAAG,UAAS,KAAK,MAAM,KAAK,IAAI,CAAC;AAAA,EACtD;AACA,SAAO,SAAS,KAAK,wBAAwB;AAC/C;AAEO,SAAS,+BACd,OACiC;AACjC,QAAM,cAAc,8BAA8B;AAAA,IAChD,SAAS,MAAM;AAAA,IACf,QAAQ,MAAM;AAAA,IACd,UAAU,MAAM;AAAA,IAChB,gBAAgB,MAAM;AAAA,EACxB,CAAC;AACD,SAAO;AAAA,IACL;AAAA,IACA,SAAS,qBAAqB,WAAW;AAAA,IACzC,WACE,YAAY,aAAa,WAAW,oBACpC,YAAY,aAAa,WAAW;AAAA,EACxC;AACF;AAEO,SAAS,yBACd,sBAGA,aACA,SACM;AACN,MAAI,CAAC,qBAAsB;AAC3B,MAAI;AACF,UAAM,SAAS,qBAAqB,WAAW;AAC/C,QAAI,UAAU,OAAO,OAAO,SAAS,YAAY;AAC/C,WAAK,QAAQ,QAAQ,MAAM,EAAE,MAAM,OAAO;AAAA,IAC5C;AAAA,EACF,SAAS,KAAK;AACZ,YAAQ,GAAG;AAAA,EACb;AACF;AAOO,SAAS,yBAAyB,KAA+C;AACtF,MAAI,aAAa,GAAG,EAAG,QAAO;AAC9B,QAAM,SACJ,eAAe,SAAS,IAAI,YAAY,mBACpC,YACA;AACN,SAAO,4BAA4B,EAAE,OAAO,CAAC;AAC/C;","names":[]}

package/dist/{chunk-OTGIAJQ2.js → chunk-6Z4OLQUO.js}

@@ -1,6 +1,6 @@
 import {
   isNamespaceKind
-} from "./chunk-DHTOYRDE.js";
+} from "./chunk-6ZMIASYT.js";
 import {
   EngramAccessInputError
 } from "./chunk-2Z24E5W2.js";
@@ -40,4 +40,4 @@ export {
   positiveIntQueryParam,
   optionalNamespaceKindQueryParam
 };
-//# sourceMappingURL=chunk-OTGIAJQ2.js.map
+//# sourceMappingURL=chunk-6Z4OLQUO.js.map

package/dist/{chunk-DHTOYRDE.js → chunk-6ZMIASYT.js}

@@ -1,7 +1,7 @@
 import {
   resolveDefaultNamespaceRoot,
   resolveNamespaceStorageRoot
-} from "./chunk-FLZJMXFV.js";
+} from "./chunk-T73ZC7C5.js";
 import {
   MutationSerializer,
   withHeldFileLock
@@ -1473,4 +1473,4 @@ export {
   isNamespaceKind,
   NamespaceCatalog
 };
-//# sourceMappingURL=chunk-DHTOYRDE.js.map
+//# sourceMappingURL=chunk-6ZMIASYT.js.map

package/dist/{chunk-UD6W67JM.js → chunk-72AV2H3R.js}

@@ -4,6 +4,9 @@ import {
 import {
   normalizeProjectionPreview
 } from "./chunk-SCU65EZI.js";
+import {
+  coerceBooleanLike
+} from "./chunk-PQVCH2AE.js";
 import {
   writeFileAtomically
 } from "./chunk-AW4QUFQF.js";
@@ -20,6 +23,10 @@ var DIRECTORY_SIDECAR_MARKER = "<!-- remnic-directory-sidecar -->";
 var ABSTRACT_MAX_CHARS = 256;
 var OVERVIEW_MAX_CHARS = 4e3;
 var DEFAULT_QUERY_LIMIT = 5;
+var CATEGORY_ROOTS = new Set(RECALL_FALLBACK_DIRS);
+function parseDirectorySidecarsEnabled(raw) {
+  return coerceBooleanLike(raw, "directorySidecarsEnabled") === true;
+}
 var RESERVED_CHILD_BASENAMES = Object.freeze({
   ...OKF_RESERVED_BASENAMES,
   [DIRECTORY_SIDECAR_BASENAME]: true
@@ -149,40 +156,81 @@ function collectSidecarDirs(scopeRoot) {
   }
   return dirs;
 }
+async function syncSidecarDir(dir, enabled, childAbstracts, written, removed) {
+  const target = sidecarPath(dir);
+  const raw = readFileOrNull(target);
+  const existing = raw !== null && raw.startsWith(DIRECTORY_SIDECAR_MARKER) ? raw : null;
+  if (!enabled) {
+    if (existing !== null) {
+      unlinkSync(target);
+      removed.push(target);
+    }
+    return;
+  }
+  const next = renderSidecar(dir, directoryFingerprint(dir), childAbstracts);
+  if (next === null) {
+    if (existing !== null) {
+      unlinkSync(target);
+      removed.push(target);
+    }
+    return;
+  }
+  const parsedNext = parseSidecar(next);
+  if (parsedNext) childAbstracts.set(dir, parsedNext.abstract);
+  if (raw === next) return;
+  if (existing === null && raw !== null) return;
+  await writeFileAtomically(target, next);
+  written.push(target);
+}
+function childAbstractsFromDisk(dir) {
+  const abstracts = /* @__PURE__ */ new Map();
+  for (const name of directoryChildren(dir)) {
+    const childDir = path.join(dir, name);
+    const parsed = parseSidecar(readFileOrNull(sidecarPath(childDir)) ?? "");
+    if (parsed) abstracts.set(childDir, parsed.abstract);
+  }
+  return abstracts;
+}
+function directorySidecarAncestry(memoryDir, changedPath) {
+  const root = path.resolve(memoryDir);
+  const abs = path.isAbsolute(changedPath) ? path.resolve(changedPath) : path.resolve(root, changedPath);
+  const rel = path.relative(root, abs);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) return [];
+  const parts = rel.split(path.sep).filter(Boolean);
+  const dirParts = isRealDirectory(abs) ? parts : parts.slice(0, -1);
+  let categoryAt = -1;
+  if (dirParts[0] === "namespaces" && dirParts.length >= 3 && CATEGORY_ROOTS.has(dirParts[2] ?? "")) {
+    categoryAt = 2;
+  } else if (CATEGORY_ROOTS.has(dirParts[0] ?? "")) {
+    categoryAt = 0;
+  }
+  if (categoryAt === -1) return [];
+  const dirs = [];
+  for (let i = dirParts.length; i > categoryAt; i--) {
+    dirs.push(path.join(root, ...dirParts.slice(0, i)));
+  }
+  return dirs;
+}
 async function runDirectorySidecarMaintenance(memoryDir, enabled) {
   const written = [];
   const removed = [];
   for (const scope of scopeRoots(memoryDir)) {
     const childAbstracts = /* @__PURE__ */ new Map();
     for (const dir of collectSidecarDirs(scope)) {
-      const target = sidecarPath(dir);
-      const raw = readFileOrNull(target);
-      const existing = raw !== null && raw.startsWith(DIRECTORY_SIDECAR_MARKER) ? raw : null;
-      if (!enabled) {
-        if (existing !== null) {
-          unlinkSync(target);
-          removed.push(target);
-        }
-        continue;
-      }
-      const next = renderSidecar(dir, directoryFingerprint(dir), childAbstracts);
-      if (next === null) {
-        if (existing !== null) {
-          unlinkSync(target);
-          removed.push(target);
-        }
-        continue;
-      }
-      const parsedNext = parseSidecar(next);
-      if (parsedNext) childAbstracts.set(dir, parsedNext.abstract);
-      if (raw === next) continue;
-      if (existing === null && raw !== null) continue;
-      await writeFileAtomically(target, next);
-      written.push(target);
+      await syncSidecarDir(dir, enabled, childAbstracts, written, removed);
     }
   }
   return { written, removed };
 }
+async function refreshDirectorySidecarsAfterWrite(memoryDir, changedPath, enabled) {
+  if (!enabled) return { written: [], removed: [] };
+  const written = [];
+  const removed = [];
+  for (const dir of directorySidecarAncestry(memoryDir, changedPath)) {
+    await syncSidecarDir(dir, true, childAbstractsFromDisk(dir), written, removed);
+  }
+  return { written, removed };
+}
 async function loadDirectorySidecar(dir, options = {}) {
   const refresh = options.refresh !== false;
   const target = sidecarPath(dir);
@@ -252,9 +300,12 @@ async function findDirectorySidecarsForQuery(memoryDir, query, options = {}) {
 export {
   DIRECTORY_SIDECAR_BASENAME,
   DIRECTORY_SIDECAR_MARKER,
+  parseDirectorySidecarsEnabled,
   directoryFingerprint,
+  directorySidecarAncestry,
   runDirectorySidecarMaintenance,
+  refreshDirectorySidecarsAfterWrite,
   loadDirectorySidecar,
   findDirectorySidecarsForQuery
 };
-//# sourceMappingURL=chunk-UD6W67JM.js.map
+//# sourceMappingURL=chunk-72AV2H3R.js.map

package/dist/chunk-72AV2H3R.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/directory-sidecars.ts"],"sourcesContent":["/**\n * @remnic/core — per-directory abstract/overview sidecars (issue #2977).\n *\n * One derived `overview.md` per memory directory (category roots and every\n * directory beneath them, including `namespaces/<ns>/` subtrees), rendered\n * bottom-up from existing memory content:\n *\n *   - the ABSTRACT is a single line (<=256 chars) composed from child titles;\n *   - the OVERVIEW body lists one preview line per child memory and embeds\n *     each child DIRECTORY's abstract, so a parent summarizes its subtree\n *     without embedding full child overviews.\n *\n * Determinism: no LLM, no embeddings. Content is assembled with the same\n * preview machinery the OKF index files use (`normalizeProjectionPreview`).\n *\n * Invalidation: each sidecar stores a content-free fingerprint of its subtree\n * (child name|size|mtime for files, recursive fingerprints for child dirs).\n * Any add/edit/delete anywhere below a directory changes its fingerprint, so\n * `loadDirectorySidecar` can detect staleness with `readdir`+`stat` alone and\n * refresh without reading child memory files first. Eager regeneration runs\n * through {@link runDirectorySidecarMaintenance}; lazy refresh on read covers\n * direct-write paths that bypass scheduled maintenance (Gotcha #43).\n *\n * Isolation: sidecars are derived artifacts, excluded from generic recall via\n * `isGenericRecallExcludedPath` (basename match, the same tradeoff OKF makes\n * for `index.md`/`log.md`) while staying full-text searchable. Files at the\n * sidecar path WITHOUT the marker are user content: never overwritten, never\n * removed.\n *\n * Layer 2 (this slice): {@link refreshDirectorySidecarsAfterWrite} refreshes\n * only the changed directory and its category ancestors, so a memory write\n * populates sidecars without walking the rest of the store. `enabled: false`\n * is a proven no-op (no reads, no writes). Config parsing lives here;\n * `parseConfig` wiring, retrieval drill-down, xray, and LLM summarization\n * remain later layers on #2977 (`config.ts` is at its file-size ratchet).\n */\n\nimport { createHash } from \"node:crypto\";\nimport { lstatSync, readFileSync, readdirSync, statSync, unlinkSync } from \"node:fs\";\nimport path from \"node:path\";\n\nimport { coerceBooleanLike } from \"./connectors/coerce.js\";\nimport { writeFileAtomically } from \"./maintenance/atomic-file.js\";\nimport { normalizeProjectionPreview } from \"./memory-projection-format.js\";\nimport { OKF_RESERVED_BASENAMES } from \"./okf/type-mapping.js\";\nimport { RECALL_FALLBACK_DIRS } from \"./utils/category-dir.js\";\n\nexport const DIRECTORY_SIDECAR_BASENAME = \"overview.md\";\nexport const DIRECTORY_SIDECAR_MARKER = \"<!-- remnic-directory-sidecar -->\";\n\nconst ABSTRACT_MAX_CHARS = 256;\nconst OVERVIEW_MAX_CHARS = 4000;\nconst DEFAULT_QUERY_LIMIT = 5;\nconst CATEGORY_ROOTS: ReadonlySet<string> = new Set(RECALL_FALLBACK_DIRS);\n\n/** Config fields this slice owns. Mix into `PluginConfig` in a later layer. */\nexport interface DirectorySidecarSettings {\n  /** Populate sidecars on memory writes. Default false. */\n  directorySidecarsEnabled: boolean;\n}\n\n/** Strict off-default: only an explicit true/\"true\"/1 opts in. */\nexport function parseDirectorySidecarsEnabled(raw: unknown): boolean {\n  return coerceBooleanLike(raw, \"directorySidecarsEnabled\") === true;\n}\n\n/** Basenames never treated as child memories (ours plus OKF's reserved ones). */\nconst RESERVED_CHILD_BASENAMES: Readonly<Record<string, true>> = Object.freeze({\n  ...OKF_RESERVED_BASENAMES,\n  [DIRECTORY_SIDECAR_BASENAME]: true,\n});\n\nexport interface DirectorySidecar {\n  /** Absolute directory the sidecar describes. */\n  readonly dir: string;\n  /** Single-line L0 abstract (<=256 chars). */\n  readonly abstract: string;\n  /** Abstract plus the per-child preview body (<=4000 chars). */\n  readonly overview: string;\n  /** Number of memory `.md` children in this directory. */\n  readonly childCount: number;\n  /** False when the stored fingerprint no longer matches the subtree. */\n  readonly fresh: boolean;\n}\n\nexport interface DirectorySidecarMatch extends DirectorySidecar {\n  readonly score: number;\n}\n\nexport interface DirectorySidecarReport {\n  written: string[];\n  removed: string[];\n}\n\ninterface ParsedSidecar {\n  abstract: string;\n  overview: string;\n  childCount: number;\n  fingerprint: string;\n}\n\nfunction listEntries(dir: string) {\n  try {\n    return readdirSync(dir, { withFileTypes: true });\n  } catch {\n    return [];\n  }\n}\n\n/** Root check that refuses symlinks (fs-boundary rule, PRs #1938/#1999). */\nfunction isRealDirectory(entryPath: string): boolean {\n  try {\n    const stats = lstatSync(entryPath);\n    return !stats.isSymbolicLink() && stats.isDirectory();\n  } catch {\n    return false;\n  }\n}\n\nfunction memoryChildren(dir: string): string[] {\n  // Dirent.isFile() is false for symlinks, so a linked memory never enters the corpus.\n  return listEntries(dir)\n    .filter((entry) => entry.isFile() && !RESERVED_CHILD_BASENAMES[entry.name] && entry.name.endsWith(\".md\"))\n    .map((entry) => entry.name)\n    .sort((a, b) => a.localeCompare(b));\n}\n\nfunction directoryChildren(dir: string): string[] {\n  // Dirent.isDirectory() is false for symlinks (fs-boundary rule, PRs #1938/#1999).\n  return listEntries(dir)\n    .filter((entry) => entry.isDirectory())\n    .map((entry) => entry.name)\n    .sort((a, b) => a.localeCompare(b));\n}\n\n/**\n * Content-free subtree fingerprint: sha256 over sorted child descriptors.\n * Files contribute `name|size|mtimeMs`; directories contribute their own\n * recursive fingerprint, so any change below a directory invalidates every\n * ancestor. Reads no file contents.\n */\nexport function directoryFingerprint(dir: string): string {\n  const hash = createHash(\"sha256\");\n  for (const name of memoryChildren(dir)) {\n    try {\n      const stats = statSync(path.join(dir, name));\n      hash.update(`f|${name}|${stats.size}|${Math.trunc(stats.mtimeMs)}\\n`);\n    } catch {\n      hash.update(`f|${name}|missing\\n`);\n    }\n  }\n  for (const name of directoryChildren(dir)) {\n    hash.update(`d|${name}|${directoryFingerprint(path.join(dir, name))}\\n`);\n  }\n  return hash.digest(\"hex\");\n}\n\nfunction readFileOrNull(target: string): string | null {\n  try {\n    return readFileSync(target, \"utf8\");\n  } catch {\n    return null;\n  }\n}\n\nfunction parseSidecar(content: string): ParsedSidecar | null {\n  if (!content.startsWith(DIRECTORY_SIDECAR_MARKER)) return null;\n  const fingerprint = /^fingerprint: ([0-9a-f]{64})$/m.exec(content)?.[1];\n  if (!fingerprint) return null;\n  const abstract = /^## Abstract\\n([^\\n]+)$/m.exec(content)?.[1] ?? \"\";\n  const overviewStart = content.indexOf(\"## Abstract\");\n  const overview =\n    overviewStart === -1 ? \"\" : content.slice(overviewStart, overviewStart + OVERVIEW_MAX_CHARS).trim();\n  // The `* name — preview` child bullets are the rendered child count.\n  const childCount = (content.match(/^\\* .+$/gm) ?? []).length;\n  return { abstract, overview, childCount, fingerprint };\n}\n\nfunction sidecarPath(dir: string): string {\n  return path.join(dir, DIRECTORY_SIDECAR_BASENAME);\n}\n\nfunction renderSidecar(dir: string, fingerprint: string, childAbstracts: Map<string, string>): string | null {\n  const children = memoryChildren(dir);\n  const childDirs = directoryChildren(dir).filter((name) => childAbstracts.has(path.join(dir, name)));\n  if (children.length === 0 && childDirs.length === 0) return null;\n\n  const previews = children.map((name) => {\n    try {\n      return normalizeProjectionPreview(readFileSync(path.join(dir, name), \"utf8\"), 120);\n    } catch {\n      return \"\";\n    }\n  });\n  const titles = children.map(\n    (name, index) => previews[index].split(\" \").slice(0, 8).join(\" \") || name.replace(/\\.md$/, \"\"),\n  );\n  const abstract = normalizeProjectionPreview(\n    `${path.basename(dir)}/ — ${children.length} memories: ${titles.slice(0, 5).join(\" · \")}`,\n    ABSTRACT_MAX_CHARS,\n  );\n\n  const lines = [\n    DIRECTORY_SIDECAR_MARKER,\n    `fingerprint: ${fingerprint}`,\n    `# ${path.basename(dir)}/ overview`,\n    \"\",\n    \"## Abstract\",\n    abstract,\n    \"\",\n    \"## Children\",\n  ];\n  for (const [index, name] of children.entries()) {\n    lines.push(`* ${name} — ${previews[index]}`);\n  }\n  for (const name of childDirs) {\n    lines.push(`### ${name}/`);\n    lines.push(childAbstracts.get(path.join(dir, name)) ?? \"\");\n  }\n  lines.push(\"\");\n  return lines.join(\"\\n\");\n}\n\n/** Scope roots whose category subtrees carry sidecars: the memory root plus every namespace root. */\nfunction scopeRoots(memoryDir: string): string[] {\n  const roots = [memoryDir];\n  const namespacesRoot = path.join(memoryDir, \"namespaces\");\n  for (const entry of listEntries(namespacesRoot)) {\n    if (entry.isDirectory() && isRealDirectory(path.join(namespacesRoot, entry.name))) {\n      roots.push(path.join(namespacesRoot, entry.name));\n    }\n  }\n  return roots;\n}\n\n/**\n * Every directory that should carry a sidecar, deepest first (post-order) so\n * parents render after their children and can embed child abstracts.\n */\nfunction collectSidecarDirs(scopeRoot: string): string[] {\n  const dirs: string[] = [];\n  const walk = (dir: string, isCategoryRoot: boolean): boolean => {\n    let carries = memoryChildren(dir).length > 0;\n    for (const name of directoryChildren(dir)) {\n      carries = walk(path.join(dir, name), false) || carries;\n    }\n    // A directory that stopped carrying memories must still be visited so its\n    // orphaned sidecar can be pruned or rewritten (cache-invalidation completeness).\n    const hasSidecar = readFileOrNull(sidecarPath(dir))?.startsWith(DIRECTORY_SIDECAR_MARKER) === true;\n    if (isCategoryRoot || carries || hasSidecar) dirs.push(dir);\n    return carries;\n  };\n  for (const category of RECALL_FALLBACK_DIRS) {\n    const categoryDir = path.join(scopeRoot, category);\n    if (!isRealDirectory(categoryDir)) continue;\n    walk(categoryDir, true);\n  }\n  return dirs;\n}\n\nasync function syncSidecarDir(\n  dir: string,\n  enabled: boolean,\n  childAbstracts: Map<string, string>,\n  written: string[],\n  removed: string[],\n): Promise<void> {\n  const target = sidecarPath(dir);\n  const raw = readFileOrNull(target);\n  const existing = raw !== null && raw.startsWith(DIRECTORY_SIDECAR_MARKER) ? raw : null;\n  if (!enabled) {\n    if (existing !== null) {\n      unlinkSync(target);\n      removed.push(target);\n    }\n    return;\n  }\n  const next = renderSidecar(dir, directoryFingerprint(dir), childAbstracts);\n  if (next === null) {\n    if (existing !== null) {\n      unlinkSync(target);\n      removed.push(target);\n    }\n    return;\n  }\n  const parsedNext = parseSidecar(next);\n  if (parsedNext) childAbstracts.set(dir, parsedNext.abstract);\n  if (raw === next) return;\n  if (existing === null && raw !== null) return; // user-authored file: hands off\n  await writeFileAtomically(target, next);\n  written.push(target);\n}\n\nfunction childAbstractsFromDisk(dir: string): Map<string, string> {\n  const abstracts = new Map<string, string>();\n  for (const name of directoryChildren(dir)) {\n    const childDir = path.join(dir, name);\n    const parsed = parseSidecar(readFileOrNull(sidecarPath(childDir)) ?? \"\");\n    if (parsed) abstracts.set(childDir, parsed.abstract);\n  }\n  return abstracts;\n}\n\n/**\n * Category-root ancestry of a changed memory path, deepest first.\n * Paths outside a recall category return `[]` so writes to `state/` or\n * `namespaces/<ns>/` itself never mint a sidecar.\n */\nexport function directorySidecarAncestry(memoryDir: string, changedPath: string): string[] {\n  const root = path.resolve(memoryDir);\n  const abs = path.isAbsolute(changedPath) ? path.resolve(changedPath) : path.resolve(root, changedPath);\n  const rel = path.relative(root, abs);\n  if (rel.startsWith(\"..\") || path.isAbsolute(rel)) return [];\n  const parts = rel.split(path.sep).filter(Boolean);\n  const dirParts = isRealDirectory(abs) ? parts : parts.slice(0, -1);\n  let categoryAt = -1;\n  if (dirParts[0] === \"namespaces\" && dirParts.length >= 3 && CATEGORY_ROOTS.has(dirParts[2] ?? \"\")) {\n    categoryAt = 2;\n  } else if (CATEGORY_ROOTS.has(dirParts[0] ?? \"\")) {\n    categoryAt = 0;\n  }\n  if (categoryAt === -1) return [];\n  const dirs: string[] = [];\n  for (let i = dirParts.length; i > categoryAt; i--) {\n    dirs.push(path.join(root, ...dirParts.slice(0, i)));\n  }\n  return dirs;\n}\n\n/**\n * Regenerates directory sidecars incrementally. Unchanged sidecars are left\n * untouched; emptied directories lose theirs; user files at the sidecar path\n * (no marker) are never written or removed. With `enabled: false` every\n * generated sidecar is removed — the OKF index-maintenance contract.\n */\nexport async function runDirectorySidecarMaintenance(\n  memoryDir: string,\n  enabled: boolean,\n): Promise<DirectorySidecarReport> {\n  const written: string[] = [];\n  const removed: string[] = [];\n  for (const scope of scopeRoots(memoryDir)) {\n    const childAbstracts = new Map<string, string>();\n    for (const dir of collectSidecarDirs(scope)) {\n      await syncSidecarDir(dir, enabled, childAbstracts, written, removed);\n    }\n  }\n  return { written, removed };\n}\n\n/**\n * Incremental write-path refresh: only the changed directory and its\n * category ancestors, using the same fingerprint/render path as maintenance.\n * `enabled: false` returns immediately — no readdir, no writes.\n */\nexport async function refreshDirectorySidecarsAfterWrite(\n  memoryDir: string,\n  changedPath: string,\n  enabled: boolean,\n): Promise<DirectorySidecarReport> {\n  if (!enabled) return { written: [], removed: [] };\n  const written: string[] = [];\n  const removed: string[] = [];\n  for (const dir of directorySidecarAncestry(memoryDir, changedPath)) {\n    await syncSidecarDir(dir, true, childAbstractsFromDisk(dir), written, removed);\n  }\n  return { written, removed };\n}\n\n/**\n * Read a directory's sidecar for retrieval. By default a stale sidecar is\n * refreshed in place (child directories first), which is what makes direct\n * writes that bypass maintenance still converge. With `{ refresh: false }`\n * the stored sidecar is returned as-is with `fresh: false` so callers can\n * observe staleness without writes.\n */\nexport async function loadDirectorySidecar(\n  dir: string,\n  options: { refresh?: boolean } = {},\n): Promise<DirectorySidecar | null> {\n  const refresh = options.refresh !== false;\n  const target = sidecarPath(dir);\n  const stored = readFileOrNull(target);\n  const generated = stored !== null && stored.startsWith(DIRECTORY_SIDECAR_MARKER);\n  const parsed = generated ? parseSidecar(stored) : null;\n  const fingerprint = directoryFingerprint(dir);\n  if (parsed !== null && (parsed.fingerprint === fingerprint || !refresh)) {\n    return {\n      dir,\n      abstract: parsed.abstract,\n      overview: parsed.overview,\n      childCount: parsed.childCount,\n      fresh: parsed.fingerprint === fingerprint,\n    };\n  }\n  if (!refresh) return null;\n\n  // Refresh bottom-up so this directory's body embeds current child abstracts.\n  const childAbstracts = new Map<string, string>();\n  for (const name of directoryChildren(dir)) {\n    const child = await loadDirectorySidecar(path.join(dir, name));\n    if (child) childAbstracts.set(path.join(dir, name), child.abstract);\n  }\n  const next = renderSidecar(dir, directoryFingerprint(dir), childAbstracts);\n  if (next === null) {\n    if (generated) unlinkSync(target);\n    return null;\n  }\n  if (readFileOrNull(target) !== next) {\n    if (stored !== null && !generated) {\n      // User-authored file at the sidecar path: serve nothing rather than clobber it.\n      return null;\n    }\n    await writeFileAtomically(target, next);\n  }\n  const refreshed = parseSidecar(next);\n  return refreshed\n    ? {\n        dir,\n        abstract: refreshed.abstract,\n        overview: refreshed.overview,\n        childCount: refreshed.childCount,\n        fresh: true,\n      }\n    : null;\n}\n\n/**\n * Overview-query primitive for hierarchical retrieval (layer 1 of #2977):\n * score every sidecar's abstract (+3 per query term) and overview (+1 per\n * term) lexically, then return the most specific matches — when both a\n * directory and its descendant match, only the descendant is kept, matching\n * the drill-down semantics the full retrieval mode will build on.\n */\nexport async function findDirectorySidecarsForQuery(\n  memoryDir: string,\n  query: string,\n  options: { namespace?: string; limit?: number } = {},\n): Promise<DirectorySidecarMatch[]> {\n  const scope = options.namespace ? path.join(memoryDir, \"namespaces\", options.namespace) : memoryDir;\n  if (!isRealDirectory(scope)) return [];\n  const terms = query\n    .toLowerCase()\n    .split(/[^a-z0-9]+/)\n    .filter((term) => term.length >= 2);\n\n  const matches: DirectorySidecarMatch[] = [];\n  for (const root of scopeRoots(scope)) {\n    for (const dir of collectSidecarDirs(root)) {\n      const sidecar = await loadDirectorySidecar(dir);\n      if (!sidecar) continue;\n      const abstractLower = sidecar.abstract.toLowerCase();\n      const overviewLower = sidecar.overview.toLowerCase();\n      let score = 0;\n      for (const term of terms) {\n        if (abstractLower.includes(term)) score += 3;\n        else if (overviewLower.includes(term)) score += 1;\n      }\n      if (score > 0) matches.push({ ...sidecar, score });\n    }\n  }\n  matches.sort((a, b) => b.score - a.score || a.dir.localeCompare(b.dir));\n\n  const limit = options.limit ?? DEFAULT_QUERY_LIMIT;\n  return matches\n    .filter((candidate) => !matches.some((other) => other.dir.startsWith(`${candidate.dir}${path.sep}`)))\n    .slice(0, limit);\n}\n"],"mappings":"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","names":[]}