@remnic/core 1.0.2 → 1.0.3

package/dist/chunk-6ZH4TU6I.js

@@ -0,0 +1,245 @@
+// src/page-versioning.ts
+import { createHash } from "crypto";
+import path from "path";
+import {
+  access,
+  mkdir,
+  readFile,
+  writeFile,
+  unlink
+} from "fs/promises";
+var NOOP_LOGGER = {
+  debug: () => {
+  },
+  warn: () => {
+  }
+};
+var writeLocks = /* @__PURE__ */ new Map();
+function withPageLock(pageKey, fn) {
+  const prev = writeLocks.get(pageKey) ?? Promise.resolve();
+  const next = prev.then(fn, fn);
+  writeLocks.set(pageKey, next.then(() => {
+  }, () => {
+  }));
+  return next;
+}
+function contentHash(content) {
+  return createHash("sha256").update(content, "utf-8").digest("hex");
+}
+function sidecarKey(pagePath) {
+  const withoutExt = pagePath.replace(/\.md$/i, "");
+  return withoutExt.replace(/[\\/]/g, "__");
+}
+function sidecarDir(memoryDir, sidecar, pagePath) {
+  return path.join(memoryDir, sidecar, sidecarKey(pagePath));
+}
+function manifestPath(memoryDir, sidecar, pagePath) {
+  return path.join(sidecarDir(memoryDir, sidecar, pagePath), "manifest.json");
+}
+async function fileExists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readManifest(memoryDir, sidecar, pagePath) {
+  const mp = manifestPath(memoryDir, sidecar, pagePath);
+  try {
+    const raw = await readFile(mp, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) {
+      return { pagePath, versions: [], currentVersion: "0" };
+    }
+    const obj = parsed;
+    const versions = Array.isArray(obj.versions) ? obj.versions : [];
+    const currentVersion = typeof obj.currentVersion === "string" ? obj.currentVersion : "0";
+    return { pagePath: typeof obj.pagePath === "string" ? obj.pagePath : pagePath, versions, currentVersion };
+  } catch {
+    return { pagePath, versions: [], currentVersion: "0" };
+  }
+}
+async function writeManifest(memoryDir, sidecar, pagePath, history) {
+  const dir = sidecarDir(memoryDir, sidecar, pagePath);
+  await mkdir(dir, { recursive: true });
+  const mp = manifestPath(memoryDir, sidecar, pagePath);
+  await writeFile(mp, JSON.stringify(history, null, 2) + "\n", "utf-8");
+}
+async function createVersion(pagePath, content, trigger, config, log = NOOP_LOGGER, note, memoryDir) {
+  const { sidecarDir: sidecar, maxVersionsPerPage } = config;
+  const resolvedMemoryDir = memoryDir ?? resolveMemoryDir(pagePath);
+  const mPath = manifestPath(resolvedMemoryDir, sidecar, relPath(pagePath, resolvedMemoryDir));
+  return withPageLock(mPath, async () => {
+    const history = await readManifest(resolvedMemoryDir, sidecar, relPath(pagePath, resolvedMemoryDir));
+    const nextId = String(history.versions.length > 0 ? Math.max(...history.versions.map((v) => Number(v.versionId))) + 1 : 1);
+    const hash = contentHash(content);
+    const version = {
+      versionId: nextId,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      contentHash: hash,
+      sizeBytes: Buffer.byteLength(content, "utf-8"),
+      trigger,
+      ...note !== void 0 ? { note } : {}
+    };
+    const dir = sidecarDir(resolvedMemoryDir, sidecar, relPath(pagePath, resolvedMemoryDir));
+    await mkdir(dir, { recursive: true });
+    const ext = path.extname(pagePath) || ".md";
+    const snapshotPath = path.join(dir, `${nextId}${ext}`);
+    await writeFile(snapshotPath, content, "utf-8");
+    history.versions.push(version);
+    history.currentVersion = nextId;
+    if (maxVersionsPerPage > 0 && history.versions.length > maxVersionsPerPage) {
+      const toRemove = history.versions.splice(0, history.versions.length - maxVersionsPerPage);
+      for (const old of toRemove) {
+        const oldPath = path.join(dir, `${old.versionId}${ext}`);
+        try {
+          await unlink(oldPath);
+        } catch {
+          log.debug(`page-versioning: could not remove old snapshot ${oldPath}`);
+        }
+      }
+    }
+    await writeManifest(resolvedMemoryDir, sidecar, relPath(pagePath, resolvedMemoryDir), history);
+    log.debug(`page-versioning: created version ${nextId} for ${pagePath} (trigger=${trigger})`);
+    return version;
+  });
+}
+async function listVersions(pagePath, config, memoryDir) {
+  const resolvedMemoryDir = memoryDir ?? resolveMemoryDir(pagePath);
+  const rel = relPath(pagePath, resolvedMemoryDir);
+  const history = await readManifest(resolvedMemoryDir, config.sidecarDir, rel);
+  history.versions.sort((a, b) => Number(a.versionId) - Number(b.versionId));
+  return history;
+}
+async function getVersion(pagePath, versionId, config, memoryDir) {
+  const resolvedMemoryDir = memoryDir ?? resolveMemoryDir(pagePath);
+  const rel = relPath(pagePath, resolvedMemoryDir);
+  const ext = path.extname(pagePath) || ".md";
+  const dir = sidecarDir(resolvedMemoryDir, config.sidecarDir, rel);
+  const snapshotPath = path.join(dir, `${versionId}${ext}`);
+  if (!await fileExists(snapshotPath)) {
+    throw new Error(`Version ${versionId} not found for ${pagePath}`);
+  }
+  return readFile(snapshotPath, "utf-8");
+}
+async function revertToVersion(pagePath, versionId, config, log = NOOP_LOGGER, memoryDir) {
+  const resolvedMemoryDir = memoryDir ?? resolveMemoryDir(pagePath);
+  const targetContent = await getVersion(pagePath, versionId, config, resolvedMemoryDir);
+  let currentContent = "";
+  try {
+    currentContent = await readFile(pagePath, "utf-8");
+  } catch {
+  }
+  const version = await createVersion(
+    pagePath,
+    currentContent,
+    "revert",
+    config,
+    log,
+    `reverted to version ${versionId}`,
+    resolvedMemoryDir
+  );
+  await writeFile(pagePath, targetContent, "utf-8");
+  log.debug(`page-versioning: reverted ${pagePath} to version ${versionId}`);
+  return version;
+}
+async function diffVersions(pagePath, v1, v2, config, memoryDir) {
+  const resolvedMemoryDir = memoryDir ?? resolveMemoryDir(pagePath);
+  const content1 = await getVersion(pagePath, v1, config, resolvedMemoryDir);
+  const content2 = await getVersion(pagePath, v2, config, resolvedMemoryDir);
+  const lines1 = content1.split("\n");
+  const lines2 = content2.split("\n");
+  const result = [];
+  result.push(`--- version ${v1}`);
+  result.push(`+++ version ${v2}`);
+  const lcs = computeLCS(lines1, lines2);
+  let i = 0;
+  let j = 0;
+  let k = 0;
+  while (k < lcs.length) {
+    while (i < lines1.length && lines1[i] !== lcs[k]) {
+      result.push(`-${lines1[i]}`);
+      i++;
+    }
+    while (j < lines2.length && lines2[j] !== lcs[k]) {
+      result.push(`+${lines2[j]}`);
+      j++;
+    }
+    result.push(` ${lcs[k]}`);
+    i++;
+    j++;
+    k++;
+  }
+  while (i < lines1.length) {
+    result.push(`-${lines1[i]}`);
+    i++;
+  }
+  while (j < lines2.length) {
+    result.push(`+${lines2[j]}`);
+    j++;
+  }
+  return result.join("\n");
+}
+function computeLCS(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+  for (let i2 = 1; i2 <= m; i2++) {
+    for (let j2 = 1; j2 <= n; j2++) {
+      if (a[i2 - 1] === b[j2 - 1]) {
+        dp[i2][j2] = dp[i2 - 1][j2 - 1] + 1;
+      } else {
+        dp[i2][j2] = Math.max(dp[i2 - 1][j2], dp[i2][j2 - 1]);
+      }
+    }
+  }
+  const result = [];
+  let i = m;
+  let j = n;
+  while (i > 0 && j > 0) {
+    if (a[i - 1] === b[j - 1]) {
+      result.unshift(a[i - 1]);
+      i--;
+      j--;
+    } else if (dp[i - 1][j] > dp[i][j - 1]) {
+      i--;
+    } else {
+      j--;
+    }
+  }
+  return result;
+}
+function resolveMemoryDir(pagePath) {
+  const knownSubdirs = /* @__PURE__ */ new Set([
+    "facts",
+    "corrections",
+    "entities",
+    "state",
+    "artifacts",
+    "questions",
+    "profiles"
+  ]);
+  let dir = path.dirname(pagePath);
+  for (let depth = 0; depth < 5; depth++) {
+    const base = path.basename(dir);
+    if (knownSubdirs.has(base) || /^\d{4}-\d{2}-\d{2}$/.test(base)) {
+      dir = path.dirname(dir);
+    } else {
+      break;
+    }
+  }
+  return dir;
+}
+function relPath(pagePath, memoryDir) {
+  return path.relative(memoryDir, pagePath);
+}
+
+export {
+  createVersion,
+  listVersions,
+  getVersion,
+  revertToVersion,
+  diffVersions
+};
+//# sourceMappingURL=chunk-6ZH4TU6I.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/page-versioning.ts"],"sourcesContent":["/**\n * Page-level versioning with history and revert (issue #371).\n *\n * Provides snapshot-based versioning for memory files using a sidecar\n * directory layout.  Each memory page gets a `.versions/<pageName>/`\n * subdirectory containing numbered snapshots and a `manifest.json` that\n * records the version history.\n *\n * Storage layout:\n *   memoryDir/\n *     facts/preferences.md              <- current file\n *     .versions/\n *       facts__preferences/\n *         manifest.json                  <- VersionHistory\n *         1.md                           <- version 1 snapshot\n *         2.md                           <- version 2 snapshot\n */\n\nimport { createHash } from \"node:crypto\";\nimport path from \"node:path\";\nimport {\n  access,\n  mkdir,\n  readFile,\n  writeFile,\n  unlink,\n} from \"node:fs/promises\";\n\n// ---------------------------------------------------------------------------\n// Public interfaces\n// ---------------------------------------------------------------------------\n\nexport interface PageVersion {\n  versionId: string;\n  timestamp: string;\n  contentHash: string;\n  sizeBytes: number;\n  trigger: VersionTrigger;\n  note?: string;\n}\n\nexport type VersionTrigger = \"write\" | \"consolidation\" | \"revert\" | \"manual\";\n\nexport interface VersionHistory {\n  pagePath: string;\n  versions: PageVersion[];\n  currentVersion: string;\n}\n\nexport interface VersioningConfig {\n  enabled: boolean;\n  maxVersionsPerPage: number;\n  sidecarDir: string;\n}\n\n// ---------------------------------------------------------------------------\n// Logger interface (minimal, avoids coupling to the host logger)\n// ---------------------------------------------------------------------------\n\nexport interface VersioningLogger {\n  debug(msg: string): void;\n  warn(msg: string): void;\n}\n\nconst NOOP_LOGGER: VersioningLogger = {\n  debug: () => {},\n  warn: () => {},\n};\n\n// ---------------------------------------------------------------------------\n// Per-page write lock (promise-chain pattern, see gotcha #40)\n// ---------------------------------------------------------------------------\n\nconst writeLocks = new Map<string, Promise<void>>();\n\nfunction withPageLock<T>(pageKey: string, fn: () => Promise<T>): Promise<T> {\n  const prev = writeLocks.get(pageKey) ?? Promise.resolve();\n  const next = prev.then(fn, fn); // run fn after previous completes, even if previous failed\n  writeLocks.set(pageKey, next.then(() => {}, () => {})); // recover chain per gotcha #40\n  return next;\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nfunction contentHash(content: string): string {\n  return createHash(\"sha256\").update(content, \"utf-8\").digest(\"hex\");\n}\n\n/**\n * Derive a filesystem-safe sidecar key from a page path relative to memoryDir.\n *\n * `facts/2026-01-15/pref-001.md` -> `facts__2026-01-15__pref-001`\n */\nfunction sidecarKey(pagePath: string): string {\n  const withoutExt = pagePath.replace(/\\.md$/i, \"\");\n  return withoutExt.replace(/[\\\\/]/g, \"__\");\n}\n\nfunction sidecarDir(memoryDir: string, sidecar: string, pagePath: string): string {\n  return path.join(memoryDir, sidecar, sidecarKey(pagePath));\n}\n\nfunction manifestPath(memoryDir: string, sidecar: string, pagePath: string): string {\n  return path.join(sidecarDir(memoryDir, sidecar, pagePath), \"manifest.json\");\n}\n\nasync function fileExists(p: string): Promise<boolean> {\n  try {\n    await access(p);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nasync function readManifest(\n  memoryDir: string,\n  sidecar: string,\n  pagePath: string,\n): Promise<VersionHistory> {\n  const mp = manifestPath(memoryDir, sidecar, pagePath);\n  try {\n    const raw = await readFile(mp, \"utf-8\");\n    const parsed: unknown = JSON.parse(raw);\n    if (typeof parsed !== \"object\" || parsed === null) {\n      return { pagePath, versions: [], currentVersion: \"0\" };\n    }\n    const obj = parsed as Record<string, unknown>;\n    const versions = Array.isArray(obj.versions) ? (obj.versions as PageVersion[]) : [];\n    const currentVersion = typeof obj.currentVersion === \"string\" ? obj.currentVersion : \"0\";\n    return { pagePath: typeof obj.pagePath === \"string\" ? obj.pagePath : pagePath, versions, currentVersion };\n  } catch {\n    return { pagePath, versions: [], currentVersion: \"0\" };\n  }\n}\n\nasync function writeManifest(\n  memoryDir: string,\n  sidecar: string,\n  pagePath: string,\n  history: VersionHistory,\n): Promise<void> {\n  const dir = sidecarDir(memoryDir, sidecar, pagePath);\n  await mkdir(dir, { recursive: true });\n  const mp = manifestPath(memoryDir, sidecar, pagePath);\n  await writeFile(mp, JSON.stringify(history, null, 2) + \"\\n\", \"utf-8\");\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\n/**\n * Create a new version snapshot for a page.\n *\n * Call this BEFORE overwriting the current file so the previous content is\n * preserved. If the file does not exist yet (first write), the provided\n * `content` is snapshotted as version 1.\n *\n * Pruning: when the number of versions exceeds `config.maxVersionsPerPage`,\n * the oldest snapshots (and their files) are removed.\n */\nexport async function createVersion(\n  pagePath: string,\n  content: string,\n  trigger: VersionTrigger,\n  config: VersioningConfig,\n  log: VersioningLogger = NOOP_LOGGER,\n  note?: string,\n  memoryDir?: string,\n): Promise<PageVersion> {\n  const { sidecarDir: sidecar, maxVersionsPerPage } = config;\n  const resolvedMemoryDir = memoryDir ?? resolveMemoryDir(pagePath);\n  const mPath = manifestPath(resolvedMemoryDir, sidecar, relPath(pagePath, resolvedMemoryDir));\n\n  return withPageLock(mPath, async () => {\n    const history = await readManifest(resolvedMemoryDir, sidecar, relPath(pagePath, resolvedMemoryDir));\n    const nextId = String(history.versions.length > 0\n      ? Math.max(...history.versions.map((v) => Number(v.versionId))) + 1\n      : 1);\n\n    const hash = contentHash(content);\n    const version: PageVersion = {\n      versionId: nextId,\n      timestamp: new Date().toISOString(),\n      contentHash: hash,\n      sizeBytes: Buffer.byteLength(content, \"utf-8\"),\n      trigger,\n      ...(note !== undefined ? { note } : {}),\n    };\n\n    // Write snapshot file\n    const dir = sidecarDir(resolvedMemoryDir, sidecar, relPath(pagePath, resolvedMemoryDir));\n    await mkdir(dir, { recursive: true });\n    const ext = path.extname(pagePath) || \".md\";\n    const snapshotPath = path.join(dir, `${nextId}${ext}`);\n    await writeFile(snapshotPath, content, \"utf-8\");\n\n    history.versions.push(version);\n    history.currentVersion = nextId;\n\n    // Prune old versions if exceeding max\n    if (maxVersionsPerPage > 0 && history.versions.length > maxVersionsPerPage) {\n      const toRemove = history.versions.splice(0, history.versions.length - maxVersionsPerPage);\n      for (const old of toRemove) {\n        const oldPath = path.join(dir, `${old.versionId}${ext}`);\n        try {\n          await unlink(oldPath);\n        } catch {\n          log.debug(`page-versioning: could not remove old snapshot ${oldPath}`);\n        }\n      }\n    }\n\n    await writeManifest(resolvedMemoryDir, sidecar, relPath(pagePath, resolvedMemoryDir), history);\n    log.debug(`page-versioning: created version ${nextId} for ${pagePath} (trigger=${trigger})`);\n\n    return version;\n  });\n}\n\n/**\n * List all versions for a page.\n */\nexport async function listVersions(\n  pagePath: string,\n  config: VersioningConfig,\n  memoryDir?: string,\n): Promise<VersionHistory> {\n  const resolvedMemoryDir = memoryDir ?? resolveMemoryDir(pagePath);\n  const rel = relPath(pagePath, resolvedMemoryDir);\n  const history = await readManifest(resolvedMemoryDir, config.sidecarDir, rel);\n  // Sort ascending by versionId (numeric)\n  history.versions.sort((a, b) => Number(a.versionId) - Number(b.versionId));\n  return history;\n}\n\n/**\n * Read the content of a specific version.\n */\nexport async function getVersion(\n  pagePath: string,\n  versionId: string,\n  config: VersioningConfig,\n  memoryDir?: string,\n): Promise<string> {\n  const resolvedMemoryDir = memoryDir ?? resolveMemoryDir(pagePath);\n  const rel = relPath(pagePath, resolvedMemoryDir);\n  const ext = path.extname(pagePath) || \".md\";\n  const dir = sidecarDir(resolvedMemoryDir, config.sidecarDir, rel);\n  const snapshotPath = path.join(dir, `${versionId}${ext}`);\n\n  if (!(await fileExists(snapshotPath))) {\n    throw new Error(`Version ${versionId} not found for ${pagePath}`);\n  }\n\n  return readFile(snapshotPath, \"utf-8\");\n}\n\n/**\n * Revert a page to a previous version.\n *\n * 1. Reads the target version's content.\n * 2. Snapshots the CURRENT content as a new version (trigger: \"revert\").\n * 3. Writes the reverted content to the page file.\n *\n * Returns the newly created version entry for the revert snapshot.\n */\nexport async function revertToVersion(\n  pagePath: string,\n  versionId: string,\n  config: VersioningConfig,\n  log: VersioningLogger = NOOP_LOGGER,\n  memoryDir?: string,\n): Promise<PageVersion> {\n  const resolvedMemoryDir = memoryDir ?? resolveMemoryDir(pagePath);\n\n  // Read target version content\n  const targetContent = await getVersion(pagePath, versionId, config, resolvedMemoryDir);\n\n  // Snapshot current content before overwriting\n  let currentContent = \"\";\n  try {\n    currentContent = await readFile(pagePath, \"utf-8\");\n  } catch {\n    // File may not exist; that's okay\n  }\n\n  const version = await createVersion(\n    pagePath,\n    currentContent,\n    \"revert\",\n    config,\n    log,\n    `reverted to version ${versionId}`,\n    resolvedMemoryDir,\n  );\n\n  // Write the reverted content to the actual page\n  await writeFile(pagePath, targetContent, \"utf-8\");\n  log.debug(`page-versioning: reverted ${pagePath} to version ${versionId}`);\n\n  return version;\n}\n\n/**\n * Simple line-based diff between two versions.\n *\n * Returns a unified-style diff string showing added (+) and removed (-) lines.\n */\nexport async function diffVersions(\n  pagePath: string,\n  v1: string,\n  v2: string,\n  config: VersioningConfig,\n  memoryDir?: string,\n): Promise<string> {\n  const resolvedMemoryDir = memoryDir ?? resolveMemoryDir(pagePath);\n  const content1 = await getVersion(pagePath, v1, config, resolvedMemoryDir);\n  const content2 = await getVersion(pagePath, v2, config, resolvedMemoryDir);\n\n  const lines1 = content1.split(\"\\n\");\n  const lines2 = content2.split(\"\\n\");\n\n  const result: string[] = [];\n  result.push(`--- version ${v1}`);\n  result.push(`+++ version ${v2}`);\n\n  // Simple LCS-based diff\n  const lcs = computeLCS(lines1, lines2);\n  let i = 0;\n  let j = 0;\n  let k = 0;\n\n  while (k < lcs.length) {\n    // Emit removed lines before the next common line\n    while (i < lines1.length && lines1[i] !== lcs[k]) {\n      result.push(`-${lines1[i]}`);\n      i++;\n    }\n    // Emit added lines before the next common line\n    while (j < lines2.length && lines2[j] !== lcs[k]) {\n      result.push(`+${lines2[j]}`);\n      j++;\n    }\n    // Common line\n    result.push(` ${lcs[k]}`);\n    i++;\n    j++;\n    k++;\n  }\n  // Remaining removed lines\n  while (i < lines1.length) {\n    result.push(`-${lines1[i]}`);\n    i++;\n  }\n  // Remaining added lines\n  while (j < lines2.length) {\n    result.push(`+${lines2[j]}`);\n    j++;\n  }\n\n  return result.join(\"\\n\");\n}\n\n// ---------------------------------------------------------------------------\n// LCS helper for diffVersions\n// ---------------------------------------------------------------------------\n\nfunction computeLCS(a: string[], b: string[]): string[] {\n  const m = a.length;\n  const n = b.length;\n  // Build DP table\n  const dp: number[][] = Array.from({ length: m + 1 }, () => new Array<number>(n + 1).fill(0));\n  for (let i = 1; i <= m; i++) {\n    for (let j = 1; j <= n; j++) {\n      if (a[i - 1] === b[j - 1]) {\n        dp[i][j] = dp[i - 1][j - 1] + 1;\n      } else {\n        dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1]);\n      }\n    }\n  }\n  // Backtrack to build LCS\n  const result: string[] = [];\n  let i = m;\n  let j = n;\n  while (i > 0 && j > 0) {\n    if (a[i - 1] === b[j - 1]) {\n      result.unshift(a[i - 1]);\n      i--;\n      j--;\n    } else if (dp[i - 1][j] > dp[i][j - 1]) {\n      i--;\n    } else {\n      j--;\n    }\n  }\n  return result;\n}\n\n// ---------------------------------------------------------------------------\n// Path helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Legacy fallback: given an absolute page path, heuristically resolve the\n * memory directory by walking up past known subdirectory names.\n *\n * Callers should always pass an explicit `memoryDir` instead of relying on\n * this heuristic.  It is retained only for backward compatibility when the\n * optional `memoryDir` parameter is omitted.\n */\nfunction resolveMemoryDir(pagePath: string): string {\n  const knownSubdirs = new Set([\n    \"facts\",\n    \"corrections\",\n    \"entities\",\n    \"state\",\n    \"artifacts\",\n    \"questions\",\n    \"profiles\",\n  ]);\n\n  let dir = path.dirname(pagePath);\n  // Walk up past date directories (YYYY-MM-DD) and known subdirs\n  for (let depth = 0; depth < 5; depth++) {\n    const base = path.basename(dir);\n    if (knownSubdirs.has(base) || /^\\d{4}-\\d{2}-\\d{2}$/.test(base)) {\n      dir = path.dirname(dir);\n    } else {\n      break;\n    }\n  }\n  return dir;\n}\n\n/**\n * Compute relative path of a page within its memory directory.\n */\nfunction relPath(pagePath: string, memoryDir: string): string {\n  return path.relative(memoryDir, pagePath);\n}\n"],"mappings":";AAkBA,SAAS,kBAAkB;AAC3B,OAAO,UAAU;AACjB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAsCP,IAAM,cAAgC;AAAA,EACpC,OAAO,MAAM;AAAA,EAAC;AAAA,EACd,MAAM,MAAM;AAAA,EAAC;AACf;AAMA,IAAM,aAAa,oBAAI,IAA2B;AAElD,SAAS,aAAgB,SAAiB,IAAkC;AAC1E,QAAM,OAAO,WAAW,IAAI,OAAO,KAAK,QAAQ,QAAQ;AACxD,QAAM,OAAO,KAAK,KAAK,IAAI,EAAE;AAC7B,aAAW,IAAI,SAAS,KAAK,KAAK,MAAM;AAAA,EAAC,GAAG,MAAM;AAAA,EAAC,CAAC,CAAC;AACrD,SAAO;AACT;AAMA,SAAS,YAAY,SAAyB;AAC5C,SAAO,WAAW,QAAQ,EAAE,OAAO,SAAS,OAAO,EAAE,OAAO,KAAK;AACnE;AAOA,SAAS,WAAW,UAA0B;AAC5C,QAAM,aAAa,SAAS,QAAQ,UAAU,EAAE;AAChD,SAAO,WAAW,QAAQ,UAAU,IAAI;AAC1C;AAEA,SAAS,WAAW,WAAmB,SAAiB,UAA0B;AAChF,SAAO,KAAK,KAAK,WAAW,SAAS,WAAW,QAAQ,CAAC;AAC3D;AAEA,SAAS,aAAa,WAAmB,SAAiB,UAA0B;AAClF,SAAO,KAAK,KAAK,WAAW,WAAW,SAAS,QAAQ,GAAG,eAAe;AAC5E;AAEA,eAAe,WAAW,GAA6B;AACrD,MAAI;AACF,UAAM,OAAO,CAAC;AACd,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,eAAe,aACb,WACA,SACA,UACyB;AACzB,QAAM,KAAK,aAAa,WAAW,SAAS,QAAQ;AACpD,MAAI;AACF,UAAM,MAAM,MAAM,SAAS,IAAI,OAAO;AACtC,UAAM,SAAkB,KAAK,MAAM,GAAG;AACtC,QAAI,OAAO,WAAW,YAAY,WAAW,MAAM;AACjD,aAAO,EAAE,UAAU,UAAU,CAAC,GAAG,gBAAgB,IAAI;AAAA,IACvD;AACA,UAAM,MAAM;AACZ,UAAM,WAAW,MAAM,QAAQ,IAAI,QAAQ,IAAK,IAAI,WAA6B,CAAC;AAClF,UAAM,iBAAiB,OAAO,IAAI,mBAAmB,WAAW,IAAI,iBAAiB;AACrF,WAAO,EAAE,UAAU,OAAO,IAAI,aAAa,WAAW,IAAI,WAAW,UAAU,UAAU,eAAe;AAAA,EAC1G,QAAQ;AACN,WAAO,EAAE,UAAU,UAAU,CAAC,GAAG,gBAAgB,IAAI;AAAA,EACvD;AACF;AAEA,eAAe,cACb,WACA,SACA,UACA,SACe;AACf,QAAM,MAAM,WAAW,WAAW,SAAS,QAAQ;AACnD,QAAM,MAAM,KAAK,EAAE,WAAW,KAAK,CAAC;AACpC,QAAM,KAAK,aAAa,WAAW,SAAS,QAAQ;AACpD,QAAM,UAAU,IAAI,KAAK,UAAU,SAAS,MAAM,CAAC,IAAI,MAAM,OAAO;AACtE;AAgBA,eAAsB,cACpB,UACA,SACA,SACA,QACA,MAAwB,aACxB,MACA,WACsB;AACtB,QAAM,EAAE,YAAY,SAAS,mBAAmB,IAAI;AACpD,QAAM,oBAAoB,aAAa,iBAAiB,QAAQ;AAChE,QAAM,QAAQ,aAAa,mBAAmB,SAAS,QAAQ,UAAU,iBAAiB,CAAC;AAE3F,SAAO,aAAa,OAAO,YAAY;AACrC,UAAM,UAAU,MAAM,aAAa,mBAAmB,SAAS,QAAQ,UAAU,iBAAiB,CAAC;AACnG,UAAM,SAAS,OAAO,QAAQ,SAAS,SAAS,IAC5C,KAAK,IAAI,GAAG,QAAQ,SAAS,IAAI,CAAC,MAAM,OAAO,EAAE,SAAS,CAAC,CAAC,IAAI,IAChE,CAAC;AAEL,UAAM,OAAO,YAAY,OAAO;AAChC,UAAM,UAAuB;AAAA,MAC3B,WAAW;AAAA,MACX,YAAW,oBAAI,KAAK,GAAE,YAAY;AAAA,MAClC,aAAa;AAAA,MACb,WAAW,OAAO,WAAW,SAAS,OAAO;AAAA,MAC7C;AAAA,MACA,GAAI,SAAS,SAAY,EAAE,KAAK,IAAI,CAAC;AAAA,IACvC;AAGA,UAAM,MAAM,WAAW,mBAAmB,SAAS,QAAQ,UAAU,iBAAiB,CAAC;AACvF,UAAM,MAAM,KAAK,EAAE,WAAW,KAAK,CAAC;AACpC,UAAM,MAAM,KAAK,QAAQ,QAAQ,KAAK;AACtC,UAAM,eAAe,KAAK,KAAK,KAAK,GAAG,MAAM,GAAG,GAAG,EAAE;AACrD,UAAM,UAAU,cAAc,SAAS,OAAO;AAE9C,YAAQ,SAAS,KAAK,OAAO;AAC7B,YAAQ,iBAAiB;AAGzB,QAAI,qBAAqB,KAAK,QAAQ,SAAS,SAAS,oBAAoB;AAC1E,YAAM,WAAW,QAAQ,SAAS,OAAO,GAAG,QAAQ,SAAS,SAAS,kBAAkB;AACxF,iBAAW,OAAO,UAAU;AAC1B,cAAM,UAAU,KAAK,KAAK,KAAK,GAAG,IAAI,SAAS,GAAG,GAAG,EAAE;AACvD,YAAI;AACF,gBAAM,OAAO,OAAO;AAAA,QACtB,QAAQ;AACN,cAAI,MAAM,kDAAkD,OAAO,EAAE;AAAA,QACvE;AAAA,MACF;AAAA,IACF;AAEA,UAAM,cAAc,mBAAmB,SAAS,QAAQ,UAAU,iBAAiB,GAAG,OAAO;AAC7F,QAAI,MAAM,oCAAoC,MAAM,QAAQ,QAAQ,aAAa,OAAO,GAAG;AAE3F,WAAO;AAAA,EACT,CAAC;AACH;AAKA,eAAsB,aACpB,UACA,QACA,WACyB;AACzB,QAAM,oBAAoB,aAAa,iBAAiB,QAAQ;AAChE,QAAM,MAAM,QAAQ,UAAU,iBAAiB;AAC/C,QAAM,UAAU,MAAM,aAAa,mBAAmB,OAAO,YAAY,GAAG;AAE5E,UAAQ,SAAS,KAAK,CAAC,GAAG,MAAM,OAAO,EAAE,SAAS,IAAI,OAAO,EAAE,SAAS,CAAC;AACzE,SAAO;AACT;AAKA,eAAsB,WACpB,UACA,WACA,QACA,WACiB;AACjB,QAAM,oBAAoB,aAAa,iBAAiB,QAAQ;AAChE,QAAM,MAAM,QAAQ,UAAU,iBAAiB;AAC/C,QAAM,MAAM,KAAK,QAAQ,QAAQ,KAAK;AACtC,QAAM,MAAM,WAAW,mBAAmB,OAAO,YAAY,GAAG;AAChE,QAAM,eAAe,KAAK,KAAK,KAAK,GAAG,SAAS,GAAG,GAAG,EAAE;AAExD,MAAI,CAAE,MAAM,WAAW,YAAY,GAAI;AACrC,UAAM,IAAI,MAAM,WAAW,SAAS,kBAAkB,QAAQ,EAAE;AAAA,EAClE;AAEA,SAAO,SAAS,cAAc,OAAO;AACvC;AAWA,eAAsB,gBACpB,UACA,WACA,QACA,MAAwB,aACxB,WACsB;AACtB,QAAM,oBAAoB,aAAa,iBAAiB,QAAQ;AAGhE,QAAM,gBAAgB,MAAM,WAAW,UAAU,WAAW,QAAQ,iBAAiB;AAGrF,MAAI,iBAAiB;AACrB,MAAI;AACF,qBAAiB,MAAM,SAAS,UAAU,OAAO;AAAA,EACnD,QAAQ;AAAA,EAER;AAEA,QAAM,UAAU,MAAM;AAAA,IACpB;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,uBAAuB,SAAS;AAAA,IAChC;AAAA,EACF;AAGA,QAAM,UAAU,UAAU,eAAe,OAAO;AAChD,MAAI,MAAM,6BAA6B,QAAQ,eAAe,SAAS,EAAE;AAEzE,SAAO;AACT;AAOA,eAAsB,aACpB,UACA,IACA,IACA,QACA,WACiB;AACjB,QAAM,oBAAoB,aAAa,iBAAiB,QAAQ;AAChE,QAAM,WAAW,MAAM,WAAW,UAAU,IAAI,QAAQ,iBAAiB;AACzE,QAAM,WAAW,MAAM,WAAW,UAAU,IAAI,QAAQ,iBAAiB;AAEzE,QAAM,SAAS,SAAS,MAAM,IAAI;AAClC,QAAM,SAAS,SAAS,MAAM,IAAI;AAElC,QAAM,SAAmB,CAAC;AAC1B,SAAO,KAAK,eAAe,EAAE,EAAE;AAC/B,SAAO,KAAK,eAAe,EAAE,EAAE;AAG/B,QAAM,MAAM,WAAW,QAAQ,MAAM;AACrC,MAAI,IAAI;AACR,MAAI,IAAI;AACR,MAAI,IAAI;AAER,SAAO,IAAI,IAAI,QAAQ;AAErB,WAAO,IAAI,OAAO,UAAU,OAAO,CAAC,MAAM,IAAI,CAAC,GAAG;AAChD,aAAO,KAAK,IAAI,OAAO,CAAC,CAAC,EAAE;AAC3B;AAAA,IACF;AAEA,WAAO,IAAI,OAAO,UAAU,OAAO,CAAC,MAAM,IAAI,CAAC,GAAG;AAChD,aAAO,KAAK,IAAI,OAAO,CAAC,CAAC,EAAE;AAC3B;AAAA,IACF;AAEA,WAAO,KAAK,IAAI,IAAI,CAAC,CAAC,EAAE;AACxB;AACA;AACA;AAAA,EACF;AAEA,SAAO,IAAI,OAAO,QAAQ;AACxB,WAAO,KAAK,IAAI,OAAO,CAAC,CAAC,EAAE;AAC3B;AAAA,EACF;AAEA,SAAO,IAAI,OAAO,QAAQ;AACxB,WAAO,KAAK,IAAI,OAAO,CAAC,CAAC,EAAE;AAC3B;AAAA,EACF;AAEA,SAAO,OAAO,KAAK,IAAI;AACzB;AAMA,SAAS,WAAW,GAAa,GAAuB;AACtD,QAAM,IAAI,EAAE;AACZ,QAAM,IAAI,EAAE;AAEZ,QAAM,KAAiB,MAAM,KAAK,EAAE,QAAQ,IAAI,EAAE,GAAG,MAAM,IAAI,MAAc,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;AAC3F,WAASA,KAAI,GAAGA,MAAK,GAAGA,MAAK;AAC3B,aAASC,KAAI,GAAGA,MAAK,GAAGA,MAAK;AAC3B,UAAI,EAAED,KAAI,CAAC,MAAM,EAAEC,KAAI,CAAC,GAAG;AACzB,WAAGD,EAAC,EAAEC,EAAC,IAAI,GAAGD,KAAI,CAAC,EAAEC,KAAI,CAAC,IAAI;AAAA,MAChC,OAAO;AACL,WAAGD,EAAC,EAAEC,EAAC,IAAI,KAAK,IAAI,GAAGD,KAAI,CAAC,EAAEC,EAAC,GAAG,GAAGD,EAAC,EAAEC,KAAI,CAAC,CAAC;AAAA,MAChD;AAAA,IACF;AAAA,EACF;AAEA,QAAM,SAAmB,CAAC;AAC1B,MAAI,IAAI;AACR,MAAI,IAAI;AACR,SAAO,IAAI,KAAK,IAAI,GAAG;AACrB,QAAI,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG;AACzB,aAAO,QAAQ,EAAE,IAAI,CAAC,CAAC;AACvB;AACA;AAAA,IACF,WAAW,GAAG,IAAI,CAAC,EAAE,CAAC,IAAI,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG;AACtC;AAAA,IACF,OAAO;AACL;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;AAcA,SAAS,iBAAiB,UAA0B;AAClD,QAAM,eAAe,oBAAI,IAAI;AAAA,IAC3B;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AAED,MAAI,MAAM,KAAK,QAAQ,QAAQ;AAE/B,WAAS,QAAQ,GAAG,QAAQ,GAAG,SAAS;AACtC,UAAM,OAAO,KAAK,SAAS,GAAG;AAC9B,QAAI,aAAa,IAAI,IAAI,KAAK,sBAAsB,KAAK,IAAI,GAAG;AAC9D,YAAM,KAAK,QAAQ,GAAG;AAAA,IACxB,OAAO;AACL;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;AAKA,SAAS,QAAQ,UAAkB,WAA2B;AAC5D,SAAO,KAAK,SAAS,WAAW,QAAQ;AAC1C;","names":["i","j"]}

package/dist/{chunk-V4YC4LUK.js → chunk-74JR4N5J.js}

@@ -1,27 +1,29 @@
 import {
   collectNativeKnowledgeChunks
-} from "./chunk-Q6FETXJA.js";
+} from "./chunk-7SEAZFFB.js";
 import {
+  compareEntityTimestamps,
   normalizeEntityName
-} from "./chunk-QWUUMMIK.js";
+} from "./chunk-POMSFKTB.js";
 import {
   sanitizeMemoryContent
 } from "./chunk-M62O4P4T.js";
+import {
+  normalizeEntityText,
+  resolveRequestedEntitySectionKeys
+} from "./chunk-4DJQYKMN.js";
 
 // src/entity-retrieval.ts
 import { createHash } from "crypto";
 import { mkdir, readFile, writeFile } from "fs/promises";
 import path from "path";
-var ENTITY_INDEX_VERSION = 1;
+var ENTITY_INDEX_VERSION = 3;
 var RECENT_TRANSCRIPT_LOOKBACK_HOURS = 24;
 var INSTRUCTION_LIKE_RE = /\b(always|never|must|should|remember to|do not|don't|process|workflow|template|checklist|instruction)\b/i;
 var METADATA_WRAPPER_RE = /^(source|context|metadata|notes?):/i;
 var ENTITY_PRONOUN_RE = /\b(he|him|his|she|her|they|them|their|it|its)\b/i;
-function normalizeText(value) {
-  return value.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
-}
 function tokenize(value) {
-  return normalizeText(value).split(/\s+/).filter((token) => token.length >= 2);
+  return normalizeEntityText(value).split(/\s+/).filter((token) => token.length >= 2);
 }
 function uniqueStrings(values) {
   return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))];
@@ -36,18 +38,37 @@ function compactLine(value, maxLength = 220) {
   if (normalized.length <= maxLength) return normalized;
   return `${normalized.slice(0, Math.max(0, maxLength - 1)).trimEnd()}\u2026`;
 }
+function dedupeHintSnippetsByText(snippets) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const snippet of snippets) {
+    const key = normalizeEntityText(snippet.text);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(snippet);
+  }
+  return result;
+}
 function relationLine(entry, relationship) {
   const normalizedLabel = relationship.label.replace(/\s+/g, " ").trim();
   if (normalizedLabel.length === 0) return `${entry.name} is connected to ${relationship.target}`;
   return `${entry.name} ${normalizedLabel} ${relationship.target}`;
 }
 function detectEntityQueryMode(query) {
-  const normalized = normalizeText(query);
+  const normalized = normalizeEntityText(query);
   if (!normalized) return null;
   if (/^(what about|and what about|how about|what happened (with|to) (he|him|his|she|her|they|them|their|it|its)|did (he|she|they|it)|is (he|she|they|it)|was (he|she|they|it))\b/.test(normalized)) {
     return "follow_up";
   }
-  if (/^(who is|who s|what do we know about|tell me about|what can you tell me about|what s new with|what happened with|what happened to|status of|where is|how is)\b/.test(normalized)) {
+  if (/^(who is|who s|what do we know about|what does|tell me about|what can you tell me about|what s new with|what happened with|what happened to|status of|where is|how is)\b/.test(normalized)) {
+    if (/^what does\b/.test(normalized)) {
+      if (/^what does (?:this|that|it|the|a|an|my|our|your|their)\b/.test(normalized)) {
+        return null;
+      }
+      if (/^what does [a-z0-9-]+ (?:error|warning|exception|failure|stack|trace|code|message|log)\b/.test(normalized) && /\b(mean|means|indicate|indicates|imply|implies)\b/.test(normalized)) {
+        return null;
+      }
+    }
     return /what happened|what s new|status of|how is|where is/.test(normalized) ? "timeline" : "direct";
   }
   if (ENTITY_PRONOUN_RE.test(normalized) && normalized.split(/\s+/).length <= 8) {
@@ -56,8 +77,8 @@ function detectEntityQueryMode(query) {
   return null;
 }
 function scoreAliasMatch(query, alias) {
-  const normalizedQuery = normalizeText(query);
-  const normalizedAlias = normalizeText(alias);
+  const normalizedQuery = normalizeEntityText(query);
+  const normalizedAlias = normalizeEntityText(alias);
   if (!normalizedAlias) return 0;
   if (normalizedQuery === normalizedAlias) return 10;
   if (containsPhrase(normalizedQuery, normalizedAlias)) return 8 + Math.min(normalizedAlias.split(/\s+/).length, 3);
@@ -77,6 +98,26 @@ function sanitizeEntityFact(fact) {
   if (INSTRUCTION_LIKE_RE.test(clean) && clean.length > 100) return "";
   return clean;
 }
+function scoreHintSnippet(snippet, queryTokens) {
+  const normalized = normalizeEntityText(snippet.text);
+  if (!normalized) return null;
+  const scored = { ...snippet };
+  if (isLikelyInstructionLike(scored.text) && scored.kind !== "summary") {
+    scored.score -= 3;
+  }
+  const overlap = queryTokens.filter((token) => normalized.includes(token)).length;
+  scored.score += overlap * 2;
+  if (METADATA_WRAPPER_RE.test(scored.text)) scored.score -= 2;
+  if (scored.text.length <= 160) scored.score += 1;
+  return scored.score > 0 ? scored : null;
+}
+function sortTimelineEntriesDesc(left, right) {
+  const timestampOrder = compareEntityTimestamps(right.timestamp, left.timestamp);
+  if (timestampOrder !== 0) {
+    return timestampOrder;
+  }
+  return right.text.localeCompare(left.text);
+}
 function jaccardSimilarity(a, b) {
   const aTokens = new Set(tokenize(a));
   const bTokens = new Set(tokenize(b));
@@ -91,7 +132,7 @@ function jaccardSimilarity(a, b) {
 function buildAliasIndex(entries) {
   const index = /* @__PURE__ */ new Map();
   for (const entry of entries) {
-    const aliases = uniqueStrings([entry.name, ...entry.aliases]).map(normalizeText).filter(Boolean);
+    const aliases = uniqueStrings([entry.name, ...entry.aliases]).map(normalizeEntityText).filter(Boolean);
     for (const alias of aliases) {
       const existing = index.get(alias) ?? [];
       existing.push(entry);
@@ -143,6 +184,9 @@ function createPseudoNativeEntry(chunk) {
     type: chunk.sourceKind,
     aliases: uniqueStrings(chunk.aliases ?? []),
     facts: [],
+    structuredSections: [],
+    timelineFacts: [],
+    timeline: [],
     relationships: [],
     activity: [],
     factCount: 0,
@@ -183,13 +227,21 @@ async function buildEntityMentionIndex(storage, config, recallNamespaces) {
   for (const entity of entityFiles) {
     const canonicalId = normalizeEntityName(entity.name, entity.type);
     const sanitizedFacts = entity.facts.map((fact) => sanitizeEntityFact(fact)).filter(Boolean).map((fact) => compactLine(fact, 180));
+    const sanitizedTimelineFacts = entity.timeline.map((entry) => sanitizeEntityFact(entry.text)).filter(Boolean).map((fact) => compactLine(fact, 180));
     entities.set(canonicalId, {
       canonicalId,
       name: entity.name,
       type: entity.type,
       aliases: uniqueStrings(entity.aliases),
-      summary: entity.summary,
+      summary: entity.synthesis?.trim() || entity.summary?.trim() || void 0,
       facts: sanitizedFacts,
+      timelineFacts: uniqueStrings(sanitizedTimelineFacts),
+      structuredSections: (entity.structuredSections ?? []).map((section) => ({
+        key: section.key,
+        title: section.title,
+        facts: section.facts.map((fact) => sanitizeEntityFact(fact)).filter(Boolean).map((fact) => compactLine(fact, 180))
+      })).filter((section) => section.facts.length > 0),
+      timeline: entity.timeline.map((entry) => ({ ...entry })),
       relationships: entity.relationships.map((relationship) => ({ ...relationship })),
       activity: entity.activity.map((activity) => ({ ...activity })),
       factCount: sanitizedFacts.length,
@@ -214,7 +266,7 @@ async function buildEntityMentionIndex(storage, config, recallNamespaces) {
       mergeNativeChunk(existingPseudo, chunk);
       continue;
     }
-    const candidateAliases = uniqueStrings([chunk.title, ...chunk.aliases ?? []]).map(normalizeText).filter(Boolean);
+    const candidateAliases = uniqueStrings([chunk.title, ...chunk.aliases ?? []]).map(normalizeEntityText).filter(Boolean);
     let matched = false;
     for (const alias of candidateAliases) {
       for (const entry of aliasIndex.get(alias) ?? []) {
@@ -287,60 +339,86 @@ async function readMemorySnippet(memory) {
   const content = memory.content.replace(/\s+/g, " ").trim();
   return compactLine(content, 180);
 }
-async function buildHintSnippets(entry, queryTokens, mode, maxSupportingFacts) {
+async function buildHintSnippets(entry, queryTokens, mode, maxSupportingFacts, requestedSectionKeys) {
   const snippets = [];
+  const aliasTokens = new Set(tokenize(uniqueStrings([entry.name, ...entry.aliases]).join(" ")));
   if (entry.summary) {
     snippets.push({ text: compactLine(entry.summary, 180), score: 10, kind: "summary" });
   }
-  for (const fact of entry.facts) {
-    snippets.push({ text: fact, score: 7, kind: "fact" });
-  }
-  for (const relationship of entry.relationships) {
-    snippets.push({
-      text: compactLine(relationLine(entry, relationship), 180),
-      score: mode === "direct" && entry.type.toLowerCase() === "person" ? 6 : 4,
-      kind: "relationship"
-    });
-  }
-  for (const activity of entry.activity) {
-    snippets.push({
-      text: compactLine(`${activity.date}: ${activity.note}`, 180),
-      score: 4,
-      kind: "activity"
-    });
-  }
-  for (const memorySnippet of entry.memorySnippets.slice(0, Math.min(maxSupportingFacts, 4))) {
-    snippets.push({
-      text: memorySnippet,
-      score: 5,
-      kind: "memory"
-    });
+  if (requestedSectionKeys.size > 0) {
+    for (const section of entry.structuredSections) {
+      if (!requestedSectionKeys.has(normalizeEntityText(section.key).replace(/\s+/g, "_"))) continue;
+      for (const fact of section.facts) {
+        snippets.push({ text: fact, score: mode === "direct" ? 8 : 9, kind: "section" });
+      }
+    }
+  } else {
+    for (const fact of entry.timelineFacts) {
+      snippets.push({ text: fact, score: mode === "direct" ? 6 : 7, kind: "fact" });
+    }
+    for (const section of entry.structuredSections) {
+      for (const fact of section.facts) {
+        const normalizedFact = normalizeEntityText(fact);
+        const hasNonAliasQueryOverlap = queryTokens.some(
+          (token) => !aliasTokens.has(token) && normalizedFact.includes(token)
+        );
+        if (entry.timelineFacts.length > 0 && !hasNonAliasQueryOverlap) {
+          continue;
+        }
+        snippets.push({ text: fact, score: mode === "direct" ? 6 : 7, kind: "fact" });
+      }
+    }
+    if (entry.timelineFacts.length === 0 && entry.structuredSections.length === 0) {
+      for (const fact of entry.facts) {
+        if (!fact.trim()) continue;
+        snippets.push({ text: fact, score: mode === "direct" ? 6 : 7, kind: "fact" });
+      }
+    }
   }
-  for (const chunk of entry.nativeChunks) {
-    snippets.push({
-      text: compactLine(chunk.snippet, 180),
-      score: 3,
-      kind: "native"
-    });
+  if (requestedSectionKeys.size === 0) {
+    for (const relationship of entry.relationships) {
+      snippets.push({
+        text: compactLine(relationLine(entry, relationship), 180),
+        score: mode === "direct" && entry.type.toLowerCase() === "person" ? 6 : 4,
+        kind: "relationship"
+      });
+    }
+    for (const activity of entry.activity) {
+      snippets.push({
+        text: compactLine(`${activity.date}: ${activity.note}`, 180),
+        score: 4,
+        kind: "activity"
+      });
+    }
+    for (const memorySnippet of entry.memorySnippets.slice(0, Math.min(maxSupportingFacts, 4))) {
+      snippets.push({
+        text: memorySnippet,
+        score: 5,
+        kind: "memory"
+      });
+    }
+    for (const chunk of entry.nativeChunks) {
+      snippets.push({
+        text: compactLine(chunk.snippet, 180),
+        score: 3,
+        kind: "native"
+      });
+    }
   }
   const deduped = /* @__PURE__ */ new Map();
   for (const snippet of snippets) {
-    const normalized = normalizeText(snippet.text);
-    if (!normalized) continue;
-    if (isLikelyInstructionLike(snippet.text) && snippet.kind !== "summary") {
-      snippet.score -= 3;
-    }
-    const overlap = queryTokens.filter((token) => normalizeText(snippet.text).includes(token)).length;
-    snippet.score += overlap * 2;
-    if (METADATA_WRAPPER_RE.test(snippet.text)) snippet.score -= 2;
-    if (snippet.text.length <= 160) snippet.score += 1;
+    const scored = scoreHintSnippet(snippet, queryTokens);
+    if (!scored) continue;
+    const normalized = normalizeEntityText(scored.text);
     const existing = deduped.get(normalized);
-    if (!existing || snippet.score > existing.score) deduped.set(normalized, snippet);
+    if (!existing || scored.score > existing.score) deduped.set(normalized, scored);
   }
   return [...deduped.values()].filter((snippet) => snippet.score > 0).sort((left, right) => right.score - left.score).slice(0, maxSupportingFacts);
 }
 function summarizeUncertainty(snippets) {
-  const direct = snippets.filter((snippet) => snippet.kind === "summary" || snippet.kind === "fact" || snippet.kind === "memory");
+  const direct = snippets.filter(
+    (snippet) => snippet.kind === "summary" || snippet.kind === "fact" || snippet.kind === "section" || snippet.kind === "memory"
+  );
   if (direct.length < 2) return null;
   for (let index = 0; index < direct.length; index += 1) {
     for (let compare = index + 1; compare < direct.length; compare += 1) {
@@ -351,12 +429,36 @@ function summarizeUncertainty(snippets) {
   }
   return null;
 }
-function formatEntityHintSection(candidates, mode, maxRelatedEntities, maxChars) {
+function formatEntityHintSection(candidates, queryTokens, mode, maxRelatedEntities, maxChars) {
   if (candidates.length === 0) return null;
   const lines = ["## entity_answer_hints", ""];
   for (const { candidate, snippets, uncertainty } of candidates) {
-    const topSnippets = snippets.slice(0, 3);
-    const topSnippetTexts = new Set(topSnippets.map((snippet) => normalizeText(snippet.text)));
+    const hasSummary = Boolean(candidate.entry.summary?.trim());
+    const preferredTopSnippets = hasSummary ? snippets.filter((snippet) => snippet.kind !== "fact") : snippets;
+    let topSnippets = (preferredTopSnippets.length > 0 ? preferredTopSnippets : snippets).slice(0, 3);
+    const buildTimelineSnippets = (seedExcludedTexts) => {
+      const explicitTimelinePool = dedupeHintSnippetsByText(
+        (candidate.entry.timeline ?? []).slice().sort(sortTimelineEntriesDesc).map((entry) => sanitizeEntityFact(entry.text)).filter(Boolean).map((text) => scoreHintSnippet({
+          text: compactLine(text, 180),
+          score: 7,
+          kind: "activity"
+        }, queryTokens)).filter((snippet) => snippet !== null).filter((snippet) => !seedExcludedTexts.has(normalizeEntityText(snippet.text)))
+      ).slice(0, 2);
+      const activityTimelinePool = dedupeHintSnippetsByText(
+        snippets.filter((snippet) => (snippet.kind === "activity" || snippet.kind === "memory") && !seedExcludedTexts.has(normalizeEntityText(snippet.text)))
+      ).slice(0, 2);
+      return explicitTimelinePool.length > 0 ? explicitTimelinePool : activityTimelinePool.length > 0 ? activityTimelinePool : dedupeHintSnippetsByText(
+        snippets.filter((snippet) => (snippet.kind === "fact" || snippet.kind === "summary") && !seedExcludedTexts.has(normalizeEntityText(snippet.text)))
+      ).slice(0, 2);
+    };
+    const baseTopSnippetTexts = new Set(topSnippets.map((snippet) => normalizeEntityText(snippet.text)));
+    const timelinePool = mode !== "direct" ? buildTimelineSnippets(baseTopSnippetTexts) : [];
+    if (mode !== "direct" && hasSummary && topSnippets.length < 2) {
+      if (timelinePool.length > 0) {
+        topSnippets = [...topSnippets, timelinePool[0]].slice(0, 3);
+      }
+    }
+    const topSnippetTexts = new Set(topSnippets.map((snippet) => normalizeEntityText(snippet.text)));
     lines.push(`- target: ${candidate.entry.name} (${candidate.entry.type})`);
     if (candidate.source === "recent_turn") {
       lines.push(`- resolution: carried forward from recent turns via alias "${candidate.alias}"`);
@@ -371,8 +473,9 @@ function formatEntityHintSection(candidates, mode, maxRelatedEntities, maxChars)
       }
     }
     if (mode !== "direct") {
-      const timeline = snippets.filter((snippet) => (snippet.kind === "activity" || snippet.kind === "memory") && !topSnippetTexts.has(normalizeText(snippet.text))).slice(0, 2);
-      const fallbackTimeline = timeline.length > 0 ? timeline : snippets.filter((snippet) => (snippet.kind === "fact" || snippet.kind === "summary") && !topSnippetTexts.has(normalizeText(snippet.text))).slice(0, 2);
+      const fallbackTimeline = timelinePool.filter(
+        (snippet) => !topSnippetTexts.has(normalizeEntityText(snippet.text))
+      );
       if (fallbackTimeline.length > 0) {
         lines.push("- recent timeline:");
         for (const snippet of fallbackTimeline) {
@@ -409,11 +512,20 @@ async function buildEntityRecallSection(options) {
   const rankedCandidates = candidates.slice(0, candidateLimit);
   const enriched = await Promise.all(
     rankedCandidates.map(async (candidate) => {
+      const requestedSectionKeys = new Set(
+        resolveRequestedEntitySectionKeys(
+          options.query,
+          candidate.entry.type,
+          candidate.entry.structuredSections,
+          options.config.entitySchemas
+        )
+      );
       const snippets = await buildHintSnippets(
         candidate.entry,
         queryTokens,
         mode,
-        options.maxSupportingFacts
+        options.maxSupportingFacts,
+        requestedSectionKeys
       );
       return {
         candidate,
@@ -422,7 +534,7 @@ async function buildEntityRecallSection(options) {
       };
     })
   );
-  const section = formatEntityHintSection(enriched, mode, options.maxRelatedEntities, options.maxChars);
+  const section = formatEntityHintSection(enriched, queryTokens, mode, options.maxRelatedEntities, options.maxChars);
   if (!section) return null;
   return section;
 }
@@ -441,4 +553,4 @@ export {
   entityIndexVersion,
   entityRecentTranscriptLookbackHours
 };
-//# sourceMappingURL=chunk-V4YC4LUK.js.map
+//# sourceMappingURL=chunk-74JR4N5J.js.map