@remnic/core 9.7.15 → 9.8.0

package/dist/chunk-E5BK6CGV.js

@@ -1,335 +0,0 @@
-import {
-  writeFileAtomically
-} from "./chunk-SFQ6QNL7.js";
-import {
-  log
-} from "./chunk-37CTGERM.js";
-
-// src/recall-state.ts
-import { appendFile, mkdir, readFile, writeFile } from "fs/promises";
-import path from "path";
-import { createHash, randomUUID } from "crypto";
-function clampGraphRecallExpandedEntries(entries, maxEntries = 64) {
-  const limit = Math.max(1, Math.floor(maxEntries));
-  if (!Array.isArray(entries)) return [];
-  return entries.filter((item) => !!item && typeof item === "object").map((item) => {
-    const graphType = item.graphType === "entity" || item.graphType === "time" || item.graphType === "causal" ? item.graphType : "entity";
-    const out = {
-      path: typeof item.path === "string" ? item.path : "",
-      score: typeof item.score === "number" && Number.isFinite(item.score) ? item.score : 0,
-      namespace: typeof item.namespace === "string" ? item.namespace : "",
-      seed: typeof item.seed === "string" ? item.seed : "",
-      hopDepth: typeof item.hopDepth === "number" && Number.isFinite(item.hopDepth) ? Math.max(0, Math.floor(item.hopDepth)) : 0,
-      decayedWeight: typeof item.decayedWeight === "number" && Number.isFinite(item.decayedWeight) ? Math.max(0, item.decayedWeight) : 0,
-      graphType
-    };
-    if (typeof item.edgeConfidence === "number" && Number.isFinite(item.edgeConfidence)) {
-      out.edgeConfidence = Math.min(1, Math.max(0, item.edgeConfidence));
-    }
-    return out;
-  }).filter((item) => item.path.length > 0 && item.namespace.length > 0).slice(0, limit);
-}
-function snapshotMatchesExpectedIdentity(current, expected) {
-  if (!expected) return true;
-  if (typeof expected.writeNonce === "string" && expected.writeNonce.length > 0) {
-    return current.writeNonce === expected.writeNonce;
-  }
-  const hasExpectedTraceId = typeof expected.traceId === "string" && expected.traceId.length > 0;
-  if (hasExpectedTraceId) {
-    return current.traceId === expected.traceId;
-  }
-  if (expected.recordedAt !== void 0) {
-    return current.recordedAt === expected.recordedAt;
-  }
-  return true;
-}
-function cloneTierExplain(tierExplain) {
-  if (!tierExplain) return void 0;
-  return structuredClone(tierExplain);
-}
-function cloneLastRecallSnapshot(snapshot) {
-  if (!snapshot) return null;
-  return structuredClone(snapshot);
-}
-var DEFAULT_TIER_MIGRATION_STATUS = {
-  updatedAt: (/* @__PURE__ */ new Date(0)).toISOString(),
-  lastCycle: null,
-  totals: {
-    cycles: 0,
-    scanned: 0,
-    migrated: 0,
-    promoted: 0,
-    demoted: 0,
-    errors: 0
-  }
-};
-var LastRecallStore = class {
-  statePath;
-  impressionsPath;
-  writeStateFile;
-  state = {};
-  stateWriteChain = Promise.resolve();
-  constructor(memoryDir, options = {}) {
-    this.statePath = path.join(memoryDir, "state", "last_recall.json");
-    this.impressionsPath = path.join(memoryDir, "state", "recall_impressions.jsonl");
-    this.writeStateFile = options.writeStateFile ?? (async (filePath, content) => {
-      await writeFileAtomically(filePath, content);
-    });
-  }
-  async load() {
-    try {
-      const raw = await readFile(this.statePath, "utf-8");
-      const parsed = JSON.parse(raw);
-      if (parsed && typeof parsed === "object") this.state = parsed;
-    } catch {
-      this.state = {};
-    }
-  }
-  get(sessionKey) {
-    return cloneLastRecallSnapshot(this.state[sessionKey] ?? null);
-  }
-  getMostRecent() {
-    const snapshots = Object.values(this.state);
-    if (snapshots.length === 0) return null;
-    snapshots.sort((a, b) => {
-      const byTime = b.recordedAt.localeCompare(a.recordedAt);
-      if (byTime !== 0) return byTime;
-      return a.sessionKey.localeCompare(b.sessionKey);
-    });
-    return cloneLastRecallSnapshot(snapshots[0] ?? null);
-  }
-  /**
-   * Persist last-recall snapshot and append an impression log entry.
-   * Does not store raw query text; uses a stable hash for correlation.
-   */
-  async record(opts) {
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    const queryHash = createHash("sha256").update(opts.query).digest("hex");
-    const liveSnapshot = {
-      sessionKey: opts.sessionKey,
-      recordedAt: now,
-      queryHash,
-      writeNonce: randomUUID(),
-      queryLen: opts.query.length,
-      memoryIds: opts.memoryIds,
-      namespace: opts.namespace,
-      recallNamespaces: opts.recallNamespaces,
-      traceId: opts.traceId,
-      plannerMode: opts.plannerMode,
-      requestedMode: opts.requestedMode,
-      source: opts.source,
-      fallbackUsed: opts.fallbackUsed,
-      sourcesUsed: opts.sourcesUsed,
-      budgetsApplied: opts.budgetsApplied,
-      latencyMs: opts.latencyMs,
-      resultPaths: opts.resultPaths,
-      policyVersion: opts.policyVersion,
-      identityInjectionMode: opts.identityInjection?.mode,
-      identityInjectedChars: opts.identityInjection?.injectedChars,
-      identityInjectionTruncated: opts.identityInjection?.truncated,
-      tierExplain: opts.tierExplain,
-      backendDegradations: opts.backendDegradations && opts.backendDegradations.length > 0 ? opts.backendDegradations : void 0
-    };
-    const snapshot = cloneLastRecallSnapshot(liveSnapshot);
-    this.state[opts.sessionKey] = snapshot;
-    const keys = Object.keys(this.state);
-    if (keys.length > 50) {
-      const ordered = keys.map((k) => ({ k, at: this.state[k]?.recordedAt ?? "" })).sort((a, b) => b.at.localeCompare(a.at));
-      for (const doomed of ordered.slice(50)) {
-        delete this.state[doomed.k];
-      }
-    }
-    try {
-      await this.flushState();
-    } catch (err) {
-      log.debug(`last recall store write failed: ${err}`);
-    }
-    if (opts.appendImpression !== false) {
-      try {
-        await mkdir(path.dirname(this.impressionsPath), { recursive: true });
-        await appendFile(this.impressionsPath, JSON.stringify(snapshot) + "\n", "utf-8");
-      } catch (err) {
-        log.debug(`recall impressions append failed: ${err}`);
-      }
-    }
-  }
-  /**
-   * Attach a RecallTierExplain block to the existing snapshot for a
-   * session without rewriting the entire snapshot.  Used by the
-   * post-recall direct-answer annotation path (issue #518 slice 3c):
-   * recallInternal records the snapshot first, then the orchestrator
-   * fires the direct-answer tier in observation mode and annotates
-   * the stored snapshot with whichever tier served the query.
-   *
-   * No-op when no snapshot exists for the given session; callers do
-   * not need to guard on existence.
-   */
-  async annotateTierExplain(sessionKey, tierExplain, expected) {
-    const current = this.state[sessionKey];
-    if (!current) return;
-    if (!snapshotMatchesExpectedIdentity(current, expected)) return;
-    this.state[sessionKey] = {
-      ...current,
-      tierExplain: cloneTierExplain(tierExplain)
-    };
-    try {
-      await this.flushState();
-    } catch (err) {
-      log.debug(`last recall tier-explain annotate failed: ${err}`);
-    }
-  }
-  flushState() {
-    const run = this.stateWriteChain.catch(() => void 0).then(async () => {
-      await mkdir(path.dirname(this.statePath), { recursive: true });
-      await this.writeStateFile(this.statePath, JSON.stringify(this.state, null, 2));
-    });
-    this.stateWriteChain = run.then(
-      () => void 0,
-      () => void 0
-    );
-    return run;
-  }
-};
-var TierMigrationStatusStore = class {
-  statePath;
-  state = structuredClone(DEFAULT_TIER_MIGRATION_STATUS);
-  constructor(memoryDir) {
-    this.statePath = path.join(memoryDir, "state", "tier-migration-status.json");
-  }
-  async load() {
-    try {
-      const raw = await readFile(this.statePath, "utf-8");
-      const parsed = JSON.parse(raw);
-      if (!parsed || typeof parsed !== "object") {
-        this.state = structuredClone(DEFAULT_TIER_MIGRATION_STATUS);
-        return;
-      }
-      const totals = parsed.totals && typeof parsed.totals === "object" ? parsed.totals : DEFAULT_TIER_MIGRATION_STATUS.totals;
-      this.state = {
-        updatedAt: typeof parsed.updatedAt === "string" && parsed.updatedAt.length > 0 ? parsed.updatedAt : DEFAULT_TIER_MIGRATION_STATUS.updatedAt,
-        lastCycle: parsed.lastCycle && typeof parsed.lastCycle === "object" ? parsed.lastCycle : null,
-        totals: {
-          cycles: typeof totals.cycles === "number" && Number.isFinite(totals.cycles) ? totals.cycles : 0,
-          scanned: typeof totals.scanned === "number" && Number.isFinite(totals.scanned) ? totals.scanned : 0,
-          migrated: typeof totals.migrated === "number" && Number.isFinite(totals.migrated) ? totals.migrated : 0,
-          promoted: typeof totals.promoted === "number" && Number.isFinite(totals.promoted) ? totals.promoted : 0,
-          demoted: typeof totals.demoted === "number" && Number.isFinite(totals.demoted) ? totals.demoted : 0,
-          errors: typeof totals.errors === "number" && Number.isFinite(totals.errors) ? totals.errors : 0
-        }
-      };
-    } catch {
-      this.state = structuredClone(DEFAULT_TIER_MIGRATION_STATUS);
-    }
-  }
-  get() {
-    return {
-      updatedAt: this.state.updatedAt,
-      lastCycle: this.state.lastCycle ? { ...this.state.lastCycle } : null,
-      totals: { ...this.state.totals }
-    };
-  }
-  async recordCycle(summary) {
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    const migratedDelta = summary.dryRun ? 0 : Math.max(0, summary.migrated);
-    const promotedDelta = summary.dryRun ? 0 : Math.max(0, summary.promoted);
-    const demotedDelta = summary.dryRun ? 0 : Math.max(0, summary.demoted);
-    const next = {
-      updatedAt: now,
-      lastCycle: { ...summary },
-      totals: {
-        cycles: this.state.totals.cycles + 1,
-        scanned: this.state.totals.scanned + Math.max(0, summary.scanned),
-        migrated: this.state.totals.migrated + migratedDelta,
-        promoted: this.state.totals.promoted + promotedDelta,
-        demoted: this.state.totals.demoted + demotedDelta,
-        errors: this.state.totals.errors + Math.max(0, summary.errorCount ?? 0)
-      }
-    };
-    this.state = next;
-    try {
-      await mkdir(path.dirname(this.statePath), { recursive: true });
-      await writeFile(this.statePath, JSON.stringify(next, null, 2), "utf-8");
-    } catch (err) {
-      log.debug(`tier migration status write failed: ${err}`);
-    }
-  }
-};
-var RecallHandleHistoryStore = class {
-  statePath;
-  writeStateFile;
-  state = {};
-  writeChain = Promise.resolve();
-  maxDepth;
-  constructor(memoryDir, options = {}) {
-    this.statePath = path.join(memoryDir, "state", "handle_history.json");
-    this.writeStateFile = options.writeStateFile ?? (async (filePath, content) => {
-      await writeFileAtomically(filePath, content);
-    });
-    this.maxDepth = typeof options.maxDepth === "number" && Number.isFinite(options.maxDepth) ? Math.max(1, Math.min(50, Math.floor(options.maxDepth))) : 5;
-  }
-  async load() {
-    try {
-      const raw = await readFile(this.statePath, "utf-8");
-      const parsed = JSON.parse(raw);
-      if (parsed && typeof parsed === "object") this.state = parsed;
-    } catch {
-      this.state = {};
-    }
-  }
-  /**
-   * Record one recall's admitted memory ids for a session, newest first.
-   * The ring is capped at {@link maxDepth}; older entries drop off the tail.
-   */
-  async record(sessionKey, memoryIds) {
-    if (!sessionKey) return;
-    const ids = memoryIds.filter((id) => typeof id === "string" && id.length > 0);
-    const entry = { at: (/* @__PURE__ */ new Date()).toISOString(), ids };
-    const prior = this.state[sessionKey] ?? [];
-    const next = [entry, ...prior].slice(0, this.maxDepth);
-    this.state[sessionKey] = next;
-    this.capSessions();
-    try {
-      await this.flush();
-    } catch (err) {
-      log.debug(`recall handle history write failed: ${err}`);
-    }
-  }
-  /**
-   * Return the memory-id arrays for a session, newest first, capped at `depth`.
-   * Empty array when the session has no recorded history.
-   */
-  recent(sessionKey, depth = this.maxDepth) {
-    const entries = this.state[sessionKey];
-    if (!entries || entries.length === 0) return [];
-    const limit = Math.max(0, Math.min(depth, entries.length));
-    return entries.slice(0, limit).map((e) => e.ids);
-  }
-  /** Test seam: drop all history (used by the corpus-scan hygiene test). */
-  clearForTest() {
-    this.state = {};
-  }
-  capSessions() {
-    const keys = Object.keys(this.state);
-    if (keys.length <= 50) return;
-    const ordered = keys.map((k) => ({ k, at: this.state[k]?.[0]?.at ?? "" })).sort((a, b) => b.at.localeCompare(a.at));
-    for (const doomed of ordered.slice(50)) {
-      delete this.state[doomed.k];
-    }
-  }
-  flush() {
-    const run = this.writeChain.catch(() => void 0).then(async () => {
-      await mkdir(path.dirname(this.statePath), { recursive: true });
-      await this.writeStateFile(this.statePath, JSON.stringify(this.state, null, 2));
-    });
-    this.writeChain = run.then(() => void 0, () => void 0);
-    return run;
-  }
-};
-
-export {
-  clampGraphRecallExpandedEntries,
-  LastRecallStore,
-  TierMigrationStatusStore,
-  RecallHandleHistoryStore
-};
-//# sourceMappingURL=chunk-E5BK6CGV.js.map

package/dist/chunk-E5BK6CGV.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/recall-state.ts"],"sourcesContent":["import { appendFile, mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { createHash, randomUUID } from \"node:crypto\";\nimport { log } from \"./logger.js\";\nimport { writeFileAtomically } from \"./maintenance/atomic-file.js\";\nimport type { SearchDegradation } from \"./search/port.js\";\nimport type {\n  IdentityInjectionMode,\n  RecallPlanMode,\n  RecallTierExplain,\n} from \"./types.js\";\n\nexport interface LastRecallBudgetSummary {\n  requestedTopK?: number;\n  appliedTopK: number;\n  recallBudgetChars: number;\n  maxMemoryTokens: number;\n  qmdFetchLimit?: number;\n  qmdHybridFetchLimit?: number;\n  finalContextChars?: number;\n  truncated?: boolean;\n  includedSections?: string[];\n  omittedSections?: string[];\n}\n\nexport interface LastRecallSnapshot {\n  sessionKey: string;\n  recordedAt: string;\n  queryHash: string;\n  queryLen: number;\n  memoryIds: string[];\n  namespace?: string;\n  recallNamespaces?: string[];\n  traceId?: string;\n  plannerMode?: RecallPlanMode;\n  requestedMode?: RecallPlanMode;\n  source?: string;\n  fallbackUsed?: boolean;\n  sourcesUsed?: string[];\n  budgetsApplied?: LastRecallBudgetSummary;\n  latencyMs?: number;\n  resultPaths?: string[];\n  policyVersion?: string;\n  identityInjectionMode?: IdentityInjectionMode | \"none\";\n  identityInjectedChars?: number;\n  identityInjectionTruncated?: boolean;\n  /**\n   * Collision-safe write nonce.  Random UUID set on every `record()`\n   * call so the observation-mode direct-answer hook can detect stale\n   * snapshots and avoid annotating a snapshot that a subsequent recall\n   * already replaced (issue #518).\n   */\n  writeNonce?: string;\n  /**\n   * Optional tier-level explanation of how recall was served\n   * (issue #518).  Populated by orchestrator call sites that can\n   * identify a concrete tier; surfaces expose the block via\n   * `engram query --explain`, the `?explain=1` HTTP flag, and the\n   * `remnic_recall_explain` MCP tool.  Orthogonal to the existing\n   * graph-path `recallExplain` operation.\n   */\n  tierExplain?: RecallTierExplain;\n  /**\n   * Backend degradations observed while serving this recall (issue #1536).\n   * Present only when a search backend reported unavailable/loading/timeout\n   * during the recall — distinguishing \"no matches\" from \"backend could not\n   * answer\" (CLAUDE.md rule 34). Deliberately independent of `tierExplain`,\n   * which is gated behind `recallDirectAnswerEnabled`.\n   */\n  backendDegradations?: SearchDegradation[];\n}\n\nexport interface GraphRecallExpandedEntry {\n  path: string;\n  score: number;\n  namespace: string;\n  seed: string;\n  hopDepth: number;\n  decayedWeight: number;\n  graphType: \"entity\" | \"time\" | \"causal\";\n  /**\n   * Issue #681 PR 3/3 — confidence of the edge that produced this entry's\n   * recorded provenance (strongest edge along the chosen entry path).\n   * Range `[0, 1]`. Optional so persisted snapshots from older builds\n   * round-trip through `clampGraphRecallExpandedEntries` without dropping.\n   */\n  edgeConfidence?: number;\n}\n\nexport function clampGraphRecallExpandedEntries(\n  entries: unknown,\n  maxEntries: number = 64,\n): GraphRecallExpandedEntry[] {\n  const limit = Math.max(1, Math.floor(maxEntries));\n  if (!Array.isArray(entries)) return [];\n  return entries\n    .filter((item): item is Record<string, unknown> => !!item && typeof item === \"object\")\n    .map((item) => {\n      const graphType: \"entity\" | \"time\" | \"causal\" =\n        item.graphType === \"entity\" || item.graphType === \"time\" || item.graphType === \"causal\"\n          ? item.graphType\n          : \"entity\";\n      const out: GraphRecallExpandedEntry = {\n        path: typeof item.path === \"string\" ? item.path : \"\",\n        score: typeof item.score === \"number\" && Number.isFinite(item.score) ? item.score : 0,\n        namespace: typeof item.namespace === \"string\" ? item.namespace : \"\",\n        seed: typeof item.seed === \"string\" ? item.seed : \"\",\n        hopDepth:\n          typeof item.hopDepth === \"number\" && Number.isFinite(item.hopDepth)\n            ? Math.max(0, Math.floor(item.hopDepth))\n            : 0,\n        decayedWeight:\n          typeof item.decayedWeight === \"number\" && Number.isFinite(item.decayedWeight)\n            ? Math.max(0, item.decayedWeight)\n            : 0,\n        graphType,\n      };\n      // Issue #681 PR 3/3: clamp `edgeConfidence` into [0, 1] when present.\n      // Older snapshots without the field round-trip cleanly via the\n      // optional shape; legacy callers always rendered as 1.0.\n      if (\n        typeof item.edgeConfidence === \"number\" &&\n        Number.isFinite(item.edgeConfidence)\n      ) {\n        out.edgeConfidence = Math.min(1, Math.max(0, item.edgeConfidence));\n      }\n      return out;\n    })\n    .filter((item) => item.path.length > 0 && item.namespace.length > 0)\n    .slice(0, limit);\n}\n\ntype LastRecallState = Record<string, LastRecallSnapshot>;\ntype StateFileWriter = (filePath: string, content: string) => Promise<void>;\n\n/**\n * Deep-copy a RecallTierExplain block.  Used by both the write path\n * (so caller mutation after `record()` cannot tear the persisted\n * snapshot) and the read path (so caller mutation after `get()` /\n * `getMostRecent()` cannot tear the in-memory store).\n *\n * Uses structuredClone so future additions to RecallTierExplain do\n * not silently share references through hand-enumerated fields —\n * matching the pattern used elsewhere in the codebase (e.g.,\n * qmd-recall-cache.ts).  The payload is pure JSON-shaped data, so\n * structuredClone is both safe and complete here.\n */\n/**\n * Stale-snapshot identity guard shared by the annotate methods (issue #518):\n * a writeNonce match wins outright; otherwise traceId (when expected) and\n * recordedAt are compared. Extracted so every annotation surface applies\n * identical guards (CLAUDE.md rule 22).\n */\nfunction snapshotMatchesExpectedIdentity(\n  current: LastRecallSnapshot,\n  expected?: { writeNonce?: string; traceId?: string; recordedAt?: string },\n): boolean {\n  if (!expected) return true;\n  if (typeof expected.writeNonce === \"string\" && expected.writeNonce.length > 0) {\n    return current.writeNonce === expected.writeNonce;\n  }\n  const hasExpectedTraceId =\n    typeof expected.traceId === \"string\" && expected.traceId.length > 0;\n  if (hasExpectedTraceId) {\n    return current.traceId === expected.traceId;\n  }\n  if (expected.recordedAt !== undefined) {\n    return current.recordedAt === expected.recordedAt;\n  }\n  return true;\n}\n\nfunction cloneTierExplain(\n  tierExplain: RecallTierExplain | undefined,\n): RecallTierExplain | undefined {\n  if (!tierExplain) return undefined;\n  return structuredClone(tierExplain);\n}\n\n/**\n * Deep-copy a LastRecallSnapshot so callers that receive it cannot\n * mutate the store's internal state through mutable array/object\n * fields.  Same structuredClone rationale as cloneTierExplain above.\n */\nfunction cloneLastRecallSnapshot(\n  snapshot: LastRecallSnapshot | null,\n): LastRecallSnapshot | null {\n  if (!snapshot) return null;\n  return structuredClone(snapshot);\n}\n\nexport interface TierMigrationCycleSummary {\n  trigger: \"extraction\" | \"maintenance\" | \"manual\";\n  scanned: number;\n  migrated: number;\n  promoted: number;\n  demoted: number;\n  limit: number;\n  dryRun: boolean;\n  skipped?: string;\n  errorCount?: number;\n}\n\nexport interface TierMigrationStatusSnapshot {\n  updatedAt: string;\n  lastCycle: TierMigrationCycleSummary | null;\n  totals: {\n    cycles: number;\n    scanned: number;\n    migrated: number;\n    promoted: number;\n    demoted: number;\n    errors: number;\n  };\n}\n\nconst DEFAULT_TIER_MIGRATION_STATUS: TierMigrationStatusSnapshot = {\n  updatedAt: new Date(0).toISOString(),\n  lastCycle: null,\n  totals: {\n    cycles: 0,\n    scanned: 0,\n    migrated: 0,\n    promoted: 0,\n    demoted: 0,\n    errors: 0,\n  },\n};\n\nexport class LastRecallStore {\n  private readonly statePath: string;\n  private readonly impressionsPath: string;\n  private readonly writeStateFile: StateFileWriter;\n  private state: LastRecallState = {};\n  private stateWriteChain: Promise<void> = Promise.resolve();\n\n  constructor(memoryDir: string, options: { writeStateFile?: StateFileWriter } = {}) {\n    this.statePath = path.join(memoryDir, \"state\", \"last_recall.json\");\n    this.impressionsPath = path.join(memoryDir, \"state\", \"recall_impressions.jsonl\");\n    this.writeStateFile =\n      options.writeStateFile ??\n      (async (filePath, content) => {\n        await writeFileAtomically(filePath, content);\n      });\n  }\n\n  async load(): Promise<void> {\n    try {\n      const raw = await readFile(this.statePath, \"utf-8\");\n      const parsed = JSON.parse(raw) as LastRecallState;\n      if (parsed && typeof parsed === \"object\") this.state = parsed;\n    } catch {\n      this.state = {};\n    }\n  }\n\n  get(sessionKey: string): LastRecallSnapshot | null {\n    // Defensive copy: callers must not be able to mutate internal state\n    // by reaching into array/object fields on the returned snapshot.\n    return cloneLastRecallSnapshot(this.state[sessionKey] ?? null);\n  }\n\n  getMostRecent(): LastRecallSnapshot | null {\n    const snapshots = Object.values(this.state);\n    if (snapshots.length === 0) return null;\n    // Secondary key on sessionKey keeps the sort stable when two\n    // snapshots share a recordedAt timestamp (CLAUDE.md rule 19).\n    snapshots.sort((a, b) => {\n      const byTime = b.recordedAt.localeCompare(a.recordedAt);\n      if (byTime !== 0) return byTime;\n      return a.sessionKey.localeCompare(b.sessionKey);\n    });\n    return cloneLastRecallSnapshot(snapshots[0] ?? null);\n  }\n\n  /**\n   * Persist last-recall snapshot and append an impression log entry.\n   * Does not store raw query text; uses a stable hash for correlation.\n   */\n  async record(opts: {\n    sessionKey: string;\n    query: string;\n    memoryIds: string[];\n    namespace?: string;\n    recallNamespaces?: string[];\n    traceId?: string;\n    plannerMode?: RecallPlanMode;\n    requestedMode?: RecallPlanMode;\n    source?: string;\n    fallbackUsed?: boolean;\n    sourcesUsed?: string[];\n    budgetsApplied?: LastRecallBudgetSummary;\n    latencyMs?: number;\n    resultPaths?: string[];\n    policyVersion?: string;\n    appendImpression?: boolean;\n    identityInjection?: {\n      mode: IdentityInjectionMode | \"none\";\n      injectedChars: number;\n      truncated: boolean;\n    };\n    /**\n     * Per-tier explain annotation (issue #518).  When supplied, the\n     * snapshot carries it so downstream surfaces (CLI / HTTP / MCP)\n     * can render which retrieval tier served the query.\n     */\n    tierExplain?: RecallTierExplain;\n    /**\n     * Backend degradations observed while serving this recall (issue #1536).\n     * Passed at record time so the published snapshot is born annotated —\n     * a post-record annotation would leave a window where readers see the\n     * snapshot without them (codex review on #1544).\n     */\n    backendDegradations?: SearchDegradation[];\n  }): Promise<void> {\n    const now = new Date().toISOString();\n    const queryHash = createHash(\"sha256\").update(opts.query).digest(\"hex\");\n\n    // Build the snapshot from opts, then deep-copy it via\n    // cloneLastRecallSnapshot so caller arrays/objects passed in\n    // `opts` cannot retain a live reference to the persisted state\n    // and tear it after record() returns.\n    const liveSnapshot: LastRecallSnapshot = {\n      sessionKey: opts.sessionKey,\n      recordedAt: now,\n      queryHash,\n      writeNonce: randomUUID(),\n      queryLen: opts.query.length,\n      memoryIds: opts.memoryIds,\n      namespace: opts.namespace,\n      recallNamespaces: opts.recallNamespaces,\n      traceId: opts.traceId,\n      plannerMode: opts.plannerMode,\n      requestedMode: opts.requestedMode,\n      source: opts.source,\n      fallbackUsed: opts.fallbackUsed,\n      sourcesUsed: opts.sourcesUsed,\n      budgetsApplied: opts.budgetsApplied,\n      latencyMs: opts.latencyMs,\n      resultPaths: opts.resultPaths,\n      policyVersion: opts.policyVersion,\n      identityInjectionMode: opts.identityInjection?.mode,\n      identityInjectedChars: opts.identityInjection?.injectedChars,\n      identityInjectionTruncated: opts.identityInjection?.truncated,\n      tierExplain: opts.tierExplain,\n      backendDegradations:\n        opts.backendDegradations && opts.backendDegradations.length > 0\n          ? opts.backendDegradations\n          : undefined,\n    };\n    // `cloneLastRecallSnapshot` handles `null` but that never applies\n    // at this call site — the non-null assertion keeps the type\n    // checker honest.\n    const snapshot = cloneLastRecallSnapshot(liveSnapshot)!;\n\n    this.state[opts.sessionKey] = snapshot;\n\n    // Keep the state bounded; the impression log is append-only.\n    const keys = Object.keys(this.state);\n    if (keys.length > 50) {\n      const ordered = keys\n        .map((k) => ({ k, at: this.state[k]?.recordedAt ?? \"\" }))\n        .sort((a, b) => b.at.localeCompare(a.at));\n      for (const doomed of ordered.slice(50)) {\n        delete this.state[doomed.k];\n      }\n    }\n\n    try {\n      await this.flushState();\n    } catch (err) {\n      log.debug(`last recall store write failed: ${err}`);\n    }\n\n    if (opts.appendImpression !== false) {\n      try {\n        await mkdir(path.dirname(this.impressionsPath), { recursive: true });\n        await appendFile(this.impressionsPath, JSON.stringify(snapshot) + \"\\n\", \"utf-8\");\n      } catch (err) {\n        log.debug(`recall impressions append failed: ${err}`);\n      }\n    }\n  }\n\n  /**\n   * Attach a RecallTierExplain block to the existing snapshot for a\n   * session without rewriting the entire snapshot.  Used by the\n   * post-recall direct-answer annotation path (issue #518 slice 3c):\n   * recallInternal records the snapshot first, then the orchestrator\n   * fires the direct-answer tier in observation mode and annotates\n   * the stored snapshot with whichever tier served the query.\n   *\n   * No-op when no snapshot exists for the given session; callers do\n   * not need to guard on existence.\n   */\n  async annotateTierExplain(\n    sessionKey: string,\n    tierExplain: RecallTierExplain,\n    expected?: { writeNonce?: string; traceId?: string; recordedAt?: string },\n  ): Promise<void> {\n    const current = this.state[sessionKey];\n    if (!current) return;\n    if (!snapshotMatchesExpectedIdentity(current, expected)) return;\n    this.state[sessionKey] = {\n      ...current,\n      tierExplain: cloneTierExplain(tierExplain),\n    };\n    try {\n      await this.flushState();\n    } catch (err) {\n      log.debug(`last recall tier-explain annotate failed: ${err}`);\n    }\n  }\n\n\n  private flushState(): Promise<void> {\n    const run = this.stateWriteChain.catch(() => undefined).then(async () => {\n      await mkdir(path.dirname(this.statePath), { recursive: true });\n      await this.writeStateFile(this.statePath, JSON.stringify(this.state, null, 2));\n    });\n    this.stateWriteChain = run.then(\n      () => undefined,\n      () => undefined,\n    );\n    return run;\n  }\n}\n\nexport class TierMigrationStatusStore {\n  private readonly statePath: string;\n  private state: TierMigrationStatusSnapshot = structuredClone(DEFAULT_TIER_MIGRATION_STATUS);\n\n  constructor(memoryDir: string) {\n    this.statePath = path.join(memoryDir, \"state\", \"tier-migration-status.json\");\n  }\n\n  async load(): Promise<void> {\n    try {\n      const raw = await readFile(this.statePath, \"utf-8\");\n      const parsed = JSON.parse(raw) as Partial<TierMigrationStatusSnapshot> | null;\n      if (!parsed || typeof parsed !== \"object\") {\n        this.state = structuredClone(DEFAULT_TIER_MIGRATION_STATUS);\n        return;\n      }\n      const totals = parsed.totals && typeof parsed.totals === \"object\"\n        ? parsed.totals\n        : DEFAULT_TIER_MIGRATION_STATUS.totals;\n      this.state = {\n        updatedAt:\n          typeof parsed.updatedAt === \"string\" && parsed.updatedAt.length > 0\n            ? parsed.updatedAt\n            : DEFAULT_TIER_MIGRATION_STATUS.updatedAt,\n        lastCycle:\n          parsed.lastCycle && typeof parsed.lastCycle === \"object\"\n            ? (parsed.lastCycle as TierMigrationCycleSummary)\n            : null,\n        totals: {\n          cycles: typeof totals.cycles === \"number\" && Number.isFinite(totals.cycles) ? totals.cycles : 0,\n          scanned: typeof totals.scanned === \"number\" && Number.isFinite(totals.scanned) ? totals.scanned : 0,\n          migrated: typeof totals.migrated === \"number\" && Number.isFinite(totals.migrated) ? totals.migrated : 0,\n          promoted: typeof totals.promoted === \"number\" && Number.isFinite(totals.promoted) ? totals.promoted : 0,\n          demoted: typeof totals.demoted === \"number\" && Number.isFinite(totals.demoted) ? totals.demoted : 0,\n          errors: typeof totals.errors === \"number\" && Number.isFinite(totals.errors) ? totals.errors : 0,\n        },\n      };\n    } catch {\n      this.state = structuredClone(DEFAULT_TIER_MIGRATION_STATUS);\n    }\n  }\n\n  get(): TierMigrationStatusSnapshot {\n    return {\n      updatedAt: this.state.updatedAt,\n      lastCycle: this.state.lastCycle ? { ...this.state.lastCycle } : null,\n      totals: { ...this.state.totals },\n    };\n  }\n\n  async recordCycle(summary: TierMigrationCycleSummary): Promise<void> {\n    const now = new Date().toISOString();\n    const migratedDelta = summary.dryRun ? 0 : Math.max(0, summary.migrated);\n    const promotedDelta = summary.dryRun ? 0 : Math.max(0, summary.promoted);\n    const demotedDelta = summary.dryRun ? 0 : Math.max(0, summary.demoted);\n    const next: TierMigrationStatusSnapshot = {\n      updatedAt: now,\n      lastCycle: { ...summary },\n      totals: {\n        cycles: this.state.totals.cycles + 1,\n        scanned: this.state.totals.scanned + Math.max(0, summary.scanned),\n        migrated: this.state.totals.migrated + migratedDelta,\n        promoted: this.state.totals.promoted + promotedDelta,\n        demoted: this.state.totals.demoted + demotedDelta,\n        errors: this.state.totals.errors + Math.max(0, summary.errorCount ?? 0),\n      },\n    };\n    this.state = next;\n    try {\n      await mkdir(path.dirname(this.statePath), { recursive: true });\n      await writeFile(this.statePath, JSON.stringify(next, null, 2), \"utf-8\");\n    } catch (err) {\n      log.debug(`tier migration status write failed: ${err}`);\n    }\n  }\n}\n\n\n/**\n * Per-session bounded history of recent recall memory-id sets, used ONLY by\n * handle resolution (issue #1582). Distinct from {@link LastRecallStore} —\n * that keeps ONE last snapshot per session; this keeps a small ring (depth N)\n * of the memory-id arrays a session has recalled, newest first, so a handle\n * cited in a later turn still resolves even after a newer recall displaced the\n * \"last\" snapshot.\n *\n * Deliberately lightweight: stores only `string[]` per entry (no full\n * snapshot), capped at `depth` per session and 50 sessions total (rule 27\n * slice/cap guards). Misses are acceptable and tagged at resolution time.\n */\nexport class RecallHandleHistoryStore {\n  private readonly statePath: string;\n  private readonly writeStateFile: StateFileWriter;\n  private state: Record<string, Array<{ at: string; ids: string[] }>> = {};\n  private writeChain: Promise<void> = Promise.resolve();\n  private readonly maxDepth: number;\n\n  constructor(memoryDir: string, options: { writeStateFile?: StateFileWriter; maxDepth?: number } = {}) {\n    this.statePath = path.join(memoryDir, \"state\", \"handle_history.json\");\n    this.writeStateFile =\n      options.writeStateFile ??\n      (async (filePath, content) => {\n        await writeFileAtomically(filePath, content);\n      });\n    this.maxDepth =\n      typeof options.maxDepth === \"number\" && Number.isFinite(options.maxDepth)\n        ? Math.max(1, Math.min(50, Math.floor(options.maxDepth)))\n        : 5;\n  }\n\n  async load(): Promise<void> {\n    try {\n      const raw = await readFile(this.statePath, \"utf-8\");\n      const parsed = JSON.parse(raw);\n      if (parsed && typeof parsed === \"object\") this.state = parsed as typeof this.state;\n    } catch {\n      this.state = {};\n    }\n  }\n\n  /**\n   * Record one recall's admitted memory ids for a session, newest first.\n   * The ring is capped at {@link maxDepth}; older entries drop off the tail.\n   */\n  async record(sessionKey: string, memoryIds: readonly string[]): Promise<void> {\n    if (!sessionKey) return;\n    const ids = memoryIds.filter((id): id is string => typeof id === \"string\" && id.length > 0);\n    const entry = { at: new Date().toISOString(), ids };\n    const prior = this.state[sessionKey] ?? [];\n    const next = [entry, ...prior].slice(0, this.maxDepth);\n    this.state[sessionKey] = next;\n    this.capSessions();\n    try {\n      await this.flush();\n    } catch (err) {\n      log.debug(`recall handle history write failed: ${err}`);\n    }\n  }\n\n  /**\n   * Return the memory-id arrays for a session, newest first, capped at `depth`.\n   * Empty array when the session has no recorded history.\n   */\n  recent(sessionKey: string, depth: number = this.maxDepth): Array<readonly string[]> {\n    const entries = this.state[sessionKey];\n    if (!entries || entries.length === 0) return [];\n    const limit = Math.max(0, Math.min(depth, entries.length));\n    return entries.slice(0, limit).map((e) => e.ids);\n  }\n\n  /** Test seam: drop all history (used by the corpus-scan hygiene test). */\n  clearForTest(): void {\n    this.state = {};\n  }\n\n  private capSessions(): void {\n    const keys = Object.keys(this.state);\n    if (keys.length <= 50) return;\n    const ordered = keys\n      .map((k) => ({ k, at: this.state[k]?.[0]?.at ?? \"\" }))\n      .sort((a, b) => b.at.localeCompare(a.at));\n    for (const doomed of ordered.slice(50)) {\n      delete this.state[doomed.k];\n    }\n  }\n\n  private flush(): Promise<void> {\n    const run = this.writeChain.catch(() => undefined).then(async () => {\n      await mkdir(path.dirname(this.statePath), { recursive: true });\n      await this.writeStateFile(this.statePath, JSON.stringify(this.state, null, 2));\n    });\n    this.writeChain = run.then(() => undefined, () => undefined);\n    return run;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-FTYDWKO6.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/recall-timings.ts"],"sourcesContent":["import type { PluginConfig } from \"./types.js\";\n\nexport interface RecallTimingRecord {\n  readonly timestamp: string;\n  readonly namespace: string;\n  readonly recallPlan: string;\n  readonly queryPolicy: string;\n  readonly timingsMs: Readonly<Record<string, number>>;\n}\n\nexport interface RecallTimingStatus {\n  readonly generatedAt: string;\n  readonly processStartedAt: string;\n  readonly capacity: number;\n  readonly count: number;\n  readonly order: \"newest-first\";\n  readonly records: RecallTimingRecord[];\n}\n\nconst RECALL_TIMING_HISTORY_LIMIT = 50;\nconst TIMING_FIELD_ALLOWLIST = [\n  \"total\",\n  \"sharedCtx\",\n  \"profile\",\n  \"peerProfile\",\n  \"identityContinuity\",\n  \"entityRetrieval\",\n  \"ki\",\n  \"artifacts\",\n  \"objectiveState\",\n  \"causalTrajectories\",\n  \"cmcCausalChains\",\n  \"calibrationRules\",\n  \"trustZones\",\n  \"harmonicRetrieval\",\n  \"verifiedRecall\",\n  \"verifiedRules\",\n  \"workProducts\",\n  \"qmd\",\n  \"transcript\",\n  \"summaries\",\n  \"nativeKnowledge\",\n  \"convRecall\",\n  \"compounding\",\n  \"graphShadow\",\n  \"qmdPost\",\n] as const;\n// The ring buffer is process-local: a daemon restart or haproxy failover to\n// the other backend starts an empty history. processStartedAt lets consumers\n// detect that discontinuity. Derived from the process time origin, not module\n// initialization, so lazy imports cannot skew it.\nconst PROCESS_STARTED_AT = new Date(Date.now() - process.uptime() * 1000).toISOString();\nconst histories = new WeakMap<PluginConfig, RecallTimingRecord[]>();\n\nfunction numericMilliseconds(value: unknown): number | undefined {\n  if (typeof value === \"number\" && Number.isFinite(value) && value >= 0) {\n    return value;\n  }\n  if (typeof value !== \"string\") return undefined;\n  const match = /^(\\d+)ms/.exec(value);\n  return match ? Number(match[1]) : undefined;\n}\n\nfunction sanitizeRecallTiming(\n  input: Record<string, unknown>,\n): RecallTimingRecord {\n  // Serialization boundary: ONLY allowlisted numeric phases reach timingsMs,\n  // and the four dimension strings are copied field-by-field. Never spread\n  // the internal record into the public shape.\n  const timingsMs: Record<string, number> = {\n    total: numericMilliseconds(input.total) ?? 0,\n  };\n  for (const field of TIMING_FIELD_ALLOWLIST) {\n    if (field === \"total\") continue;\n    const value = numericMilliseconds(input[field]);\n    // Phases that did not run are omitted; 0 means \"ran, measured zero\".\n    if (value !== undefined) timingsMs[field] = value;\n  }\n  return {\n    timestamp: typeof input.timestamp === \"string\" ? input.timestamp : \"\",\n    namespace: typeof input.namespace === \"string\" ? input.namespace : \"\",\n    recallPlan: typeof input.recallPlan === \"string\" ? input.recallPlan : \"\",\n    queryPolicy: typeof input.queryPolicy === \"string\" ? input.queryPolicy : \"\",\n    timingsMs,\n  };\n}\n\nexport function recordRecallTiming(\n  config: PluginConfig,\n  input: Record<string, unknown>,\n): void {\n  const history = histories.get(config) ?? [];\n  history.push(sanitizeRecallTiming(input));\n  if (history.length > RECALL_TIMING_HISTORY_LIMIT) history.shift();\n  histories.set(config, history);\n}\n\nexport function resolveRecallTimingsOperatorPrincipal(\n  config: PluginConfig,\n  transportPrincipal?: string,\n): string | undefined {\n  return config.agentAccessHttp.principal?.trim()\n    || transportPrincipal?.trim()\n    || undefined;\n}\n\nexport function isRecallTimingsOperator(\n  config: PluginConfig,\n  authenticatedPrincipal?: string,\n  transportPrincipal?: string,\n): boolean {\n  const operatorPrincipal = resolveRecallTimingsOperatorPrincipal(\n    config,\n    transportPrincipal,\n  );\n  return Boolean(\n    operatorPrincipal\n    && authenticatedPrincipal\n    && authenticatedPrincipal === operatorPrincipal,\n  );\n}\n\nexport function getRecallTimings(config: PluginConfig): RecallTimingRecord[] {\n  const history = histories.get(config) ?? [];\n  return history.slice().reverse().map((record) => ({\n    ...record,\n    timingsMs: { ...record.timingsMs },\n  }));\n}\n\nexport function getRecallTimingStatus(config: PluginConfig): RecallTimingStatus {\n  const records = getRecallTimings(config);\n  return {\n    generatedAt: new Date().toISOString(),\n    processStartedAt: PROCESS_STARTED_AT,\n    capacity: RECALL_TIMING_HISTORY_LIMIT,\n    count: records.length,\n    order: \"newest-first\",\n    records,\n  };\n}\n"],"mappings":";AAmBA,IAAM,8BAA8B;AACpC,IAAM,yBAAyB;AAAA,EAC7B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAKA,IAAM,qBAAqB,IAAI,KAAK,KAAK,IAAI,IAAI,QAAQ,OAAO,IAAI,GAAI,EAAE,YAAY;AACtF,IAAM,YAAY,oBAAI,QAA4C;AAElE,SAAS,oBAAoB,OAAoC;AAC/D,MAAI,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK,KAAK,SAAS,GAAG;AACrE,WAAO;AAAA,EACT;AACA,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,QAAM,QAAQ,WAAW,KAAK,KAAK;AACnC,SAAO,QAAQ,OAAO,MAAM,CAAC,CAAC,IAAI;AACpC;AAEA,SAAS,qBACP,OACoB;AAIpB,QAAM,YAAoC;AAAA,IACxC,OAAO,oBAAoB,MAAM,KAAK,KAAK;AAAA,EAC7C;AACA,aAAW,SAAS,wBAAwB;AAC1C,QAAI,UAAU,QAAS;AACvB,UAAM,QAAQ,oBAAoB,MAAM,KAAK,CAAC;AAE9C,QAAI,UAAU,OAAW,WAAU,KAAK,IAAI;AAAA,EAC9C;AACA,SAAO;AAAA,IACL,WAAW,OAAO,MAAM,cAAc,WAAW,MAAM,YAAY;AAAA,IACnE,WAAW,OAAO,MAAM,cAAc,WAAW,MAAM,YAAY;AAAA,IACnE,YAAY,OAAO,MAAM,eAAe,WAAW,MAAM,aAAa;AAAA,IACtE,aAAa,OAAO,MAAM,gBAAgB,WAAW,MAAM,cAAc;AAAA,IACzE;AAAA,EACF;AACF;AAEO,SAAS,mBACd,QACA,OACM;AACN,QAAM,UAAU,UAAU,IAAI,MAAM,KAAK,CAAC;AAC1C,UAAQ,KAAK,qBAAqB,KAAK,CAAC;AACxC,MAAI,QAAQ,SAAS,4BAA6B,SAAQ,MAAM;AAChE,YAAU,IAAI,QAAQ,OAAO;AAC/B;AAEO,SAAS,sCACd,QACA,oBACoB;AACpB,SAAO,OAAO,gBAAgB,WAAW,KAAK,KACzC,oBAAoB,KAAK,KACzB;AACP;AAEO,SAAS,wBACd,QACA,wBACA,oBACS;AACT,QAAM,oBAAoB;AAAA,IACxB;AAAA,IACA;AAAA,EACF;AACA,SAAO;AAAA,IACL,qBACG,0BACA,2BAA2B;AAAA,EAChC;AACF;AAEO,SAAS,iBAAiB,QAA4C;AAC3E,QAAM,UAAU,UAAU,IAAI,MAAM,KAAK,CAAC;AAC1C,SAAO,QAAQ,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,YAAY;AAAA,IAChD,GAAG;AAAA,IACH,WAAW,EAAE,GAAG,OAAO,UAAU;AAAA,EACnC,EAAE;AACJ;AAEO,SAAS,sBAAsB,QAA0C;AAC9E,QAAM,UAAU,iBAAiB,MAAM;AACvC,SAAO;AAAA,IACL,cAAa,oBAAI,KAAK,GAAE,YAAY;AAAA,IACpC,kBAAkB;AAAA,IAClB,UAAU;AAAA,IACV,OAAO,QAAQ;AAAA,IACf,OAAO;AAAA,IACP;AAAA,EACF;AACF;","names":[]}

package/dist/chunk-GWTFLF2P.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/secure-store/keyring.ts","../src/secure-store/header.ts"],"sourcesContent":["/**\n * In-memory keyring for the secure-store module (issue #690 PR 2/4).\n *\n * Holds derived AES-256-GCM master keys for unlocked stores. The\n * keyring is process-local: keys are NEVER persisted to disk, never\n * logged, and never serialized. A daemon restart re-locks every\n * registered store.\n *\n * Scoping\n * -------\n * Entries are keyed by a stable string id (typically the absolute\n * path to the secure-store directory, after `~` expansion). This\n * lets multiple memory roots share a single daemon process without\n * one store's key bleeding into another (matches the per-`serviceId`\n * scoping discipline called out in CLAUDE.md gotcha #11).\n *\n * Lifecycle\n * ---------\n *   - `unlock(id, key)` — register a derived key.\n *   - `getKey(id)` — read a registered key (or `null`).\n *   - `lock(id)` — clear a single entry, zeroing the key bytes.\n *   - `lockAll()` — clear every entry, zeroing every key.\n *   - `status(id)` — non-secret status snapshot for `secure-store\n *     status`.\n *\n * Zeroization\n * -----------\n * `lock` and `lockAll` overwrite the key buffer with zeros before\n * dropping the reference. The JS engine may keep additional copies\n * outside our control; this is best-effort hygiene, not a defense\n * against memory-dump attacks.\n */\n\nconst ENTRIES = new Map<string, KeyringEntry>();\n\n/** A single unlocked store. The key buffer is never copied out. */\ninterface KeyringEntry {\n  key: Buffer;\n  unlockedAt: string;\n}\n\n/** Status snapshot — no secret material. */\nexport interface KeyringStatus {\n  /** True iff a key is currently registered for this id. */\n  unlocked: boolean;\n  /** ISO-8601 timestamp the key was registered, or null when locked. */\n  unlockedAt: string | null;\n}\n\n/**\n * Register a derived key for the given id. If an entry already\n * exists, its old key is zeroed before being replaced.\n *\n * The caller MUST pass an exclusive 32-byte buffer; the keyring\n * takes ownership and will zero it on lock.\n */\nexport function unlock(id: string, key: Buffer, now: () => Date = () => new Date()): void {\n  if (typeof id !== \"string\" || id.length === 0) {\n    throw new Error(\"keyring id must be a non-empty string\");\n  }\n  if (!Buffer.isBuffer(key) || key.length !== 32) {\n    throw new Error(`keyring key must be a 32-byte Buffer, got length=${key?.length ?? \"non-buffer\"}`);\n  }\n  const existing = ENTRIES.get(id);\n  if (existing) {\n    existing.key.fill(0);\n  }\n  ENTRIES.set(id, { key, unlockedAt: now().toISOString() });\n}\n\n/** Read the registered key for `id`, or `null` if locked. */\nexport function getKey(id: string): Buffer | null {\n  const entry = ENTRIES.get(id);\n  return entry ? entry.key : null;\n}\n\n/** Clear a single entry. Zeros the underlying buffer. Returns true if cleared. */\nexport function lock(id: string): boolean {\n  const entry = ENTRIES.get(id);\n  if (!entry) return false;\n  entry.key.fill(0);\n  ENTRIES.delete(id);\n  return true;\n}\n\n/** Clear every registered key. Used on shutdown or for tests. */\nexport function lockAll(): void {\n  for (const entry of ENTRIES.values()) {\n    entry.key.fill(0);\n  }\n  ENTRIES.clear();\n}\n\n/** Non-secret status snapshot. */\nexport function status(id: string): KeyringStatus {\n  const entry = ENTRIES.get(id);\n  if (!entry) {\n    return { unlocked: false, unlockedAt: null };\n  }\n  return { unlocked: true, unlockedAt: entry.unlockedAt };\n}\n\n/** Test-only helper: how many entries are currently registered. */\nexport function size(): number {\n  return ENTRIES.size;\n}\n","/**\n * On-disk header for an initialized secure-store (issue #690 PR 2/4).\n *\n * The header file is the persistent record that a memory directory\n * has had `remnic secure-store init` run against it. It is a JSON\n * file at `<memoryDir>/.secure-store/header.json` with two parts:\n *\n *   1. The KDF metadata from PR 1/4 (`SecureStoreMetadata`) —\n *      algorithm, params, and salt. Public; safe to read/copy.\n *   2. A \"verifier\" — a tiny AES-GCM-encrypted envelope sealed under\n *      the derived key at init time. Unlock re-derives the key from\n *      the entered passphrase and tries to `open()` the verifier; if\n *      the auth tag validates, the passphrase is correct.\n *\n * Why a verifier?\n * ---------------\n * Without one, \"wrong passphrase\" can only be detected when the\n * daemon tries to decrypt actual memory data — too late for a\n * useful CLI error. The verifier gives the unlock command a fast,\n * data-independent passphrase check.\n *\n * The verifier plaintext is a fixed magic string (no secret content).\n * Its only role is to be sealable + openable; the auth-tag check is\n * what proves the key.\n *\n * Naming\n * ------\n * Directory: `.secure-store/` (leading dot — hidden, hints at\n * sensitivity). File: `header.json`. Avoids collision with\n * `.secure-store-metadata.json` from PR 1/4 docs since the header\n * is a strict superset.\n */\n\nimport { mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport path from \"node:path\";\n\nimport { open, seal } from \"./cipher.js\";\nimport {\n  KDF_KEY_LENGTH,\n  KDF_SALT_LENGTH,\n  deriveKey,\n  type Argon2idParams,\n  type ScryptParams,\n} from \"./kdf.js\";\nimport {\n  buildMetadata,\n  decodeMetadataSalt,\n  parseMetadata,\n  serializeMetadata,\n  type SecureStoreMetadata,\n} from \"./metadata.js\";\n\n/** Subdirectory under `memoryDir` that holds the header + future state. */\nexport const SECURE_STORE_DIR_NAME = \".secure-store\";\n\n/** Header filename. Stable name so operators can locate it. */\nexport const HEADER_FILENAME = \"header.json\";\n\n/** Stable identifier so the file shape is sniffable without parsing JSON. */\nexport const HEADER_FORMAT = \"remnic.secure-store.header\" as const;\n\n/** Current header format version. Bump on breaking schema changes. */\nexport const HEADER_FORMAT_VERSION = 1 as const;\n\n/**\n * Magic bytes sealed under the master key at init time. Constant\n * across stores — there's no value in randomizing it because the\n * salt + IV + auth tag already make every verifier envelope unique.\n *\n * The string never appears in plaintext on disk; it only exists\n * inside an AES-GCM-sealed envelope. Its job is purely to give the\n * cipher something to authenticate.\n */\nexport const VERIFIER_PLAINTEXT = Buffer.from(\"remnic-secure-store-v1\", \"utf8\");\n\n/** AAD bound into the verifier envelope. */\nconst VERIFIER_AAD = Buffer.from(\"remnic-secure-store/verifier\", \"utf8\");\n\nexport interface SecureStoreHeader {\n  format: typeof HEADER_FORMAT;\n  formatVersion: number;\n  /** KDF metadata (algorithm + params + salt). */\n  metadata: SecureStoreMetadata;\n  /** Hex-encoded sealed envelope. */\n  verifier: string;\n  /** ISO-8601 timestamp recorded at init time. */\n  createdAt: string;\n}\n\n/** Resolve the canonical secure-store directory for a memory root. */\nexport function secureStoreDir(memoryDir: string): string {\n  return path.join(memoryDir, SECURE_STORE_DIR_NAME);\n}\n\n/** Resolve the canonical header path for a memory root. */\nexport function headerPath(memoryDir: string): string {\n  return path.join(secureStoreDir(memoryDir), HEADER_FILENAME);\n}\n\n/**\n * Build a `SecureStoreHeader` in memory from an already-derived key\n * and metadata. Pure: does not touch the filesystem. The clock is\n * read once if `createdAt` is omitted.\n */\nexport function buildHeader(options: {\n  metadata: SecureStoreMetadata;\n  derivedKey: Buffer;\n  createdAt?: string;\n}): SecureStoreHeader {\n  const { metadata, derivedKey } = options;\n  if (!Buffer.isBuffer(derivedKey) || derivedKey.length !== KDF_KEY_LENGTH) {\n    throw new Error(\n      `derivedKey must be a ${KDF_KEY_LENGTH}-byte Buffer, got length=${derivedKey?.length ?? \"non-buffer\"}`,\n    );\n  }\n  const salt = decodeMetadataSalt(metadata);\n  if (salt.length !== KDF_SALT_LENGTH) {\n    throw new Error(`metadata salt is ${salt.length} bytes, expected ${KDF_SALT_LENGTH}`);\n  }\n  const envelope = seal(derivedKey, salt, VERIFIER_PLAINTEXT, { aad: VERIFIER_AAD });\n  return {\n    format: HEADER_FORMAT,\n    formatVersion: HEADER_FORMAT_VERSION,\n    metadata,\n    verifier: envelope.toString(\"hex\"),\n    createdAt: options.createdAt ?? new Date().toISOString(),\n  };\n}\n\n/** Stable JSON serialization with locked top-level key order. */\nexport function serializeHeader(header: SecureStoreHeader): string {\n  validateHeader(header);\n  // Inline metadata as a parsed object so it shares the same\n  // canonical key ordering as the standalone metadata file.\n  const metadataString = serializeMetadata(header.metadata);\n  const metadataObject = JSON.parse(metadataString) as Record<string, unknown>;\n  const ordered = {\n    format: header.format,\n    formatVersion: header.formatVersion,\n    metadata: metadataObject,\n    verifier: header.verifier,\n    createdAt: header.createdAt,\n  };\n  return JSON.stringify(ordered, null, 2);\n}\n\n/** Parse a header JSON string. Throws on any structural problem. */\nexport function parseHeader(json: string): SecureStoreHeader {\n  if (typeof json !== \"string\") {\n    throw new Error(\"header input must be a string\");\n  }\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(json);\n  } catch (e) {\n    const msg = e instanceof Error ? e.message : String(e);\n    throw new Error(`header is not valid JSON: ${msg}`);\n  }\n  if (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) {\n    throw new Error(\"header must be a JSON object\");\n  }\n  const obj = parsed as Record<string, unknown>;\n  if (obj.format !== HEADER_FORMAT) {\n    throw new Error(\n      `unexpected header format: ${String(obj.format)} (expected ${HEADER_FORMAT})`,\n    );\n  }\n  if (obj.formatVersion !== HEADER_FORMAT_VERSION) {\n    throw new Error(\n      `unsupported header formatVersion: ${String(obj.formatVersion)} (this build supports ${HEADER_FORMAT_VERSION})`,\n    );\n  }\n  if (typeof obj.verifier !== \"string\" || obj.verifier.length === 0) {\n    throw new Error(\"header.verifier must be a non-empty hex string\");\n  }\n  if (!/^[0-9a-fA-F]+$/.test(obj.verifier)) {\n    throw new Error(\"header.verifier must be a hex-encoded string\");\n  }\n  // Codex P2 on PR #737: odd-length hex strings produce a malformed\n  // Buffer via `Buffer.from(hex, \"hex\")` — Node silently truncates the\n  // trailing nibble, yielding a buffer that is one byte shorter than\n  // expected. Reject odd-length strings before they reach the cipher.\n  if (obj.verifier.length % 2 !== 0) {\n    throw new Error(\n      \"header.verifier hex string must have even length (each byte encodes as two hex digits)\",\n    );\n  }\n  if (typeof obj.createdAt !== \"string\" || obj.createdAt.length === 0) {\n    throw new Error(\"header.createdAt must be a non-empty string\");\n  }\n  if (typeof obj.metadata !== \"object\" || obj.metadata === null) {\n    throw new Error(\"header.metadata must be an object\");\n  }\n  // Reuse the metadata parser for nested validation. We re-stringify\n  // the nested object and feed it through `parseMetadata` so any\n  // schema drift is caught in one place.\n  const metadata = parseMetadata(JSON.stringify(obj.metadata));\n  const header: SecureStoreHeader = {\n    format: HEADER_FORMAT,\n    formatVersion: HEADER_FORMAT_VERSION,\n    metadata,\n    verifier: obj.verifier,\n    createdAt: obj.createdAt,\n  };\n  validateHeader(header);\n  return header;\n}\n\n/** Validate a header object's invariants. Throws on the first problem. */\nexport function validateHeader(header: SecureStoreHeader): void {\n  if (header.format !== HEADER_FORMAT) {\n    throw new Error(`header.format must be ${HEADER_FORMAT}`);\n  }\n  if (header.formatVersion !== HEADER_FORMAT_VERSION) {\n    throw new Error(`header.formatVersion must be ${HEADER_FORMAT_VERSION}`);\n  }\n  if (typeof header.createdAt !== \"string\" || header.createdAt.length === 0) {\n    throw new Error(\"header.createdAt must be a non-empty ISO-8601 string\");\n  }\n  if (typeof header.verifier !== \"string\" || header.verifier.length === 0) {\n    throw new Error(\"header.verifier must be a non-empty hex string\");\n  }\n  if (!/^[0-9a-fA-F]+$/.test(header.verifier)) {\n    throw new Error(\"header.verifier must be a hex-encoded string\");\n  }\n  // Enforce even length: odd-length hex is silently truncated by\n  // `Buffer.from(hex, \"hex\")` which yields a malformed envelope.\n  if (header.verifier.length % 2 !== 0) {\n    throw new Error(\n      \"header.verifier hex string must have even length (each byte encodes as two hex digits)\",\n    );\n  }\n  // The nested metadata object is already validated by `parseMetadata`\n  // when read from disk; on the build path, `buildHeader` constructs\n  // it via `buildMetadata`. We still re-run shape validation here as\n  // a belt-and-braces guard for callers that hand-construct headers.\n  if (header.metadata.format !== \"remnic.secure-store.metadata\") {\n    throw new Error(\"header.metadata.format must be remnic.secure-store.metadata\");\n  }\n}\n\n/**\n * Verify a candidate key against the header's verifier envelope.\n *\n * Returns true iff the AES-GCM auth tag validates. Wrong passphrase,\n * tampered envelope, and tampered AAD all return false.\n */\nexport function verifyKey(header: SecureStoreHeader, candidateKey: Buffer): boolean {\n  if (!Buffer.isBuffer(candidateKey) || candidateKey.length !== KDF_KEY_LENGTH) {\n    return false;\n  }\n  const envelope = Buffer.from(header.verifier, \"hex\");\n  try {\n    const plaintext = open(candidateKey, envelope, { aad: VERIFIER_AAD });\n    return plaintext.equals(VERIFIER_PLAINTEXT);\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Derive a key from the passphrase using the algorithm + params +\n * salt recorded in the header. Pure: no I/O.\n */\nexport function deriveKeyFromHeader(header: SecureStoreHeader, passphrase: string): Buffer {\n  const salt = decodeMetadataSalt(header.metadata);\n  // Cursor low on PR #737: a previous version branched on the\n  // algorithm and returned `header.metadata.kdf.params` from both\n  // arms — a no-op conditional. Pass the discriminated union member\n  // through directly; `deriveKey` performs the algorithm dispatch.\n  const params: ScryptParams | Argon2idParams = header.metadata.kdf.params;\n  return deriveKey(header.metadata.kdf.algorithm, passphrase, salt, params);\n}\n\n/**\n * Read and parse the header at `<memoryDir>/.secure-store/header.json`.\n * Returns `null` if the file does not exist; throws on malformed\n * content.\n */\nexport async function readHeader(memoryDir: string): Promise<SecureStoreHeader | null> {\n  const target = headerPath(memoryDir);\n  let raw: string;\n  try {\n    raw = await readFile(target, \"utf8\");\n  } catch (e) {\n    if ((e as NodeJS.ErrnoException).code === \"ENOENT\") {\n      return null;\n    }\n    throw e;\n  }\n  return parseHeader(raw);\n}\n\n/**\n * Write the header with atomic exclusive-create semantics.\n *\n * Uses the `wx` flag (`O_CREAT | O_EXCL`) so the OS rejects the call\n * atomically when the file already exists. Two concurrent\n * `secure-store init` invocations cannot both observe \"missing\" and\n * race to overwrite each other — the second writer reliably gets\n * `EEXIST` and surfaces \"Refusing to overwrite\".\n *\n * Codex P1 on PR #737: a previous version pre-checked existence with\n * `readFile` then `writeFile`+`rename`, which is a check-then-act\n * race. The `wx` flag closes that window at the kernel layer.\n *\n * Crash safety: if the write is interrupted mid-flight, a partial\n * `header.json` may remain on disk. `parseHeader` rejects partial\n * files cleanly and the operator can delete the stub and retry. We\n * don't use temp+rename here because (a) headers are tiny (≤ 1 KiB),\n * (b) there is no prior valid file to destroy, and (c) `wx` already\n * gives us atomic exclusivity — the rename trick (CLAUDE.md gotcha\n * #54) is for replacing an existing valid file, which is exactly the\n * scenario this function refuses.\n */\nexport async function writeHeader(memoryDir: string, header: SecureStoreHeader): Promise<string> {\n  validateHeader(header);\n  const dir = secureStoreDir(memoryDir);\n  await mkdir(dir, { recursive: true });\n  const target = headerPath(memoryDir);\n  try {\n    await writeFile(target, serializeHeader(header), {\n      encoding: \"utf8\",\n      mode: 0o600,\n      flag: \"wx\",\n    });\n  } catch (e) {\n    if ((e as NodeJS.ErrnoException).code === \"EEXIST\") {\n      throw new Error(\n        `secure-store header already exists at ${target}. Refusing to overwrite — initialize a fresh store or remove the existing header explicitly.`,\n      );\n    }\n    throw e;\n  }\n  return target;\n}\n\n/** Convenience: build metadata + header in one call from a passphrase. */\nexport function buildHeaderFromPassphrase(options: {\n  passphrase: string;\n  salt: Buffer;\n  /** Optional override; defaults to Argon2id with `DEFAULT_ARGON2ID_PARAMS`. */\n  algorithm?: \"scrypt\" | \"argon2id\";\n  params?: ScryptParams | Argon2idParams;\n  createdAt?: string;\n  note?: string;\n}): { header: SecureStoreHeader; derivedKey: Buffer } {\n  const { passphrase, salt } = options;\n  const algorithm = options.algorithm ?? \"argon2id\";\n  const metadataOpts: {\n    algorithm: \"scrypt\" | \"argon2id\";\n    salt: Buffer;\n    params?: ScryptParams | Argon2idParams;\n    createdAt?: string;\n    note?: string;\n  } = { algorithm, salt };\n  if (options.params !== undefined) metadataOpts.params = options.params;\n  if (options.createdAt !== undefined) metadataOpts.createdAt = options.createdAt;\n  if (options.note !== undefined) metadataOpts.note = options.note;\n  const metadata = buildMetadata(metadataOpts);\n  // Cursor low on PR #737: same identical-branches ternary as in\n  // `deriveKeyFromHeader`. The discriminated union already carries\n  // the right shape; `deriveKey` dispatches on `algorithm`.\n  const params: ScryptParams | Argon2idParams = metadata.kdf.params;\n  const derivedKey = deriveKey(algorithm, passphrase, salt, params);\n  const headerOpts: { metadata: SecureStoreMetadata; derivedKey: Buffer; createdAt?: string } = {\n    metadata,\n    derivedKey,\n  };\n  if (options.createdAt !== undefined) headerOpts.createdAt = options.createdAt;\n  const header = buildHeader(headerOpts);\n  return { header, derivedKey };\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-IKQTFQMI.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/namespaces/principal.ts"],"sourcesContent":["import { resolveNamespaceCapabilities } from \"../capabilities.js\";\nimport type { PluginConfig } from \"../types.js\";\nimport { isLikelyUnsafeRegex } from \"../routing/engine.js\";\n\nconst MAX_REGEX_SESSION_KEY_LENGTH = 512;\n\nfunction compileSafePrincipalRegex(pattern: string): RegExp | null {\n  if (isLikelyUnsafeRegex(pattern)) return null;\n  try {\n    return new RegExp(pattern);\n  } catch {\n    return null;\n  }\n}\n\nexport function resolvePrincipal(sessionKey: string | undefined, config: PluginConfig): string | undefined {\n  if (!resolveNamespaceCapabilities(config).namespaces) return \"default\";\n  const sk = typeof sessionKey === \"string\" && sessionKey.trim().length > 0\n    ? sessionKey\n    : \"\";\n  const mode = config.principalFromSessionKeyMode;\n  const rules = config.principalFromSessionKeyRules ?? [];\n\n  if (!sk) return undefined;\n\n  if (mode === \"prefix\") {\n    for (const r of rules) {\n      if (sk.startsWith(r.match)) return r.principal;\n    }\n  } else if (mode === \"map\") {\n    for (const r of rules) {\n      if (sk === r.match) return r.principal;\n    }\n  } else if (mode === \"regex\") {\n    if (sk.length <= MAX_REGEX_SESSION_KEY_LENGTH) {\n      for (const r of rules) {\n        const re = compileSafePrincipalRegex(r.match);\n        if (re?.test(sk)) {\n          return r.principal;\n        }\n      }\n    }\n  }\n\n  // Fallback heuristic: \"agent:<agentId>:<channelType>:...\"\n  const parts = sk.split(\":\");\n  if (parts.length >= 2 && parts[0] === \"agent\") {\n    const agentId = parts[1];\n    if (agentId && agentId.length > 0) return agentId;\n  }\n  return \"default\";\n}\n\nexport function canReadNamespace(principal: string | undefined, namespace: string, config: PluginConfig): boolean {\n  if (!resolveNamespaceCapabilities(config).namespaces) return true;\n  if (!principal) return false;\n  const policy = config.namespacePolicies.find((p) => p.name === namespace);\n  if (!policy) return namespace === config.defaultNamespace || namespace === config.sharedNamespace;\n  return policy.readPrincipals.includes(principal) || policy.readPrincipals.includes(\"*\");\n}\n\nexport function canWriteNamespace(principal: string | undefined, namespace: string, config: PluginConfig): boolean {\n  if (!resolveNamespaceCapabilities(config).namespaces) return true;\n  if (!principal) return false;\n  const policy = config.namespacePolicies.find((p) => p.name === namespace);\n  if (!policy) return namespace === config.defaultNamespace;\n  return policy.writePrincipals.includes(principal) || policy.writePrincipals.includes(\"*\");\n}\n\n/**\n * Default \"self\" namespace for a principal.\n *\n * Heuristic:\n * - If there's a namespace policy with the same name as the principal, use it.\n * - Otherwise use config.defaultNamespace.\n */\nexport function defaultNamespaceForPrincipal(principal: string | undefined, config: PluginConfig): string {\n  if (!resolveNamespaceCapabilities(config).namespaces) return config.defaultNamespace;\n  if (!principal) return config.defaultNamespace;\n  const exists = config.namespacePolicies.some((p) => p.name === principal);\n  return exists ? principal : config.defaultNamespace;\n}\n\nexport function recallNamespacesForPrincipal(principal: string | undefined, config: PluginConfig): string[] {\n  const out: string[] = [];\n  if (!resolveNamespaceCapabilities(config).namespaces) return [config.defaultNamespace];\n  if (!principal) return out;\n\n  const selfNs = defaultNamespaceForPrincipal(principal, config);\n  if (config.defaultRecallNamespaces.includes(\"self\") && canReadNamespace(principal, selfNs, config)) {\n    out.push(selfNs);\n  }\n  if (config.defaultRecallNamespaces.includes(\"shared\") && canReadNamespace(principal, config.sharedNamespace, config)) {\n    out.push(config.sharedNamespace);\n  }\n\n  for (const p of config.namespacePolicies) {\n    if (p.includeInRecallByDefault && canReadNamespace(principal, p.name, config)) {\n      if (!out.includes(p.name)) out.push(p.name);\n    }\n  }\n\n  return out;\n}\n"],"mappings":"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","names":[]}