@remnic/core 1.1.31 → 9.3.516

package/dist/trace-WM7V4CKI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/console/trace.ts"],"sourcesContent":["/**\n * Trace recording + replay for the operator console (issue #688 PR 3/3).\n *\n * This module is the I/O layer that bridges the live console surface\n * (PR 2/3, `runConsoleTui`) with an offline replay mode. Operators can:\n *\n *   - `remnic console --record-trace <path>`: append every refresh\n *     cycle's `ConsoleStateSnapshot` to a JSONL file at `<path>` (one\n *     snapshot per line), so the engine state can be reviewed later.\n *\n *   - `remnic console --trace <path> [--speed N]`: read the JSONL file\n *     frame-by-frame, recompute the inter-frame delay from the\n *     captured `capturedAt` timestamps (divided by `speed`), and feed\n *     each frame into the same `renderFrame` function the live TUI\n *     uses. EOF exits cleanly.\n *\n * Design contract:\n *   - Replay reuses `renderFrame` (NOT a parallel reimplementation).\n *     Live and replay must look identical for the same snapshot.\n *   - Replay is fully sandboxed: no orchestrator instance is required,\n *     no filesystem reads beyond the trace file itself.\n *   - Recording is cheap: one `JSON.stringify` + a single\n *     `\\n`-delimited append per snapshot. A failed write logs once and\n *     disables further writes; the live loop must NOT crash.\n *   - Speed multiplier `N`: positive finite. `N=2` halves the delay,\n *     `N=0.5` doubles it. `Infinity` is permitted and means \"no\n *     delay\" (back-to-back frames).\n */\n\nimport { promises as fs } from \"node:fs\";\nimport path from \"node:path\";\nimport readline from \"node:readline\";\nimport { createReadStream } from \"node:fs\";\nimport type { Writable } from \"node:stream\";\n\nimport { renderFrame } from \"./tui.js\";\nimport type { ConsoleStateSnapshot } from \"./state.js\";\n\n/** ANSI: clear screen + move cursor to home (top-left). Same constant the TUI uses. */\nconst ANSI_CLEAR_HOME = \"\\x1b[2J\\x1b[H\";\n/** ANSI: hide / show the cursor during replay. */\nconst ANSI_HIDE_CURSOR = \"\\x1b[?25l\";\nconst ANSI_SHOW_CURSOR = \"\\x1b[?25h\";\n\n/**\n * Default delay (ms) used when the trace file has fewer than two\n * frames OR the captured timestamps don't yield a valid delta. Mirrors\n * the live TUI's default refresh interval for visual consistency.\n */\nconst DEFAULT_REPLAY_DELAY_MS = 2000;\n\n/**\n * Maximum allowed delay between replay frames. A pathological trace\n * with hour-long gaps would otherwise stall replay indefinitely; cap\n * at one minute so a tester running `--trace` always sees progress.\n */\nconst MAX_REPLAY_DELAY_MS = 60_000;\n\n/** Minimum delay between replay frames (ms) — prevents starving the loop. */\nconst MIN_REPLAY_DELAY_MS = 0;\n\nexport interface TraceRecorder {\n  /**\n   * Append a snapshot to the trace file. Returns a promise that\n   * resolves once the line is flushed. Errors are surfaced via\n   * `getLastError()` rather than thrown — the live TUI must never\n   * crash because tracing failed.\n   */\n  append: (snapshot: ConsoleStateSnapshot) => Promise<void>;\n  /**\n   * Close the underlying file handle. Idempotent.\n   *\n   * The optional `signal` parameter is forwarded from\n   * `flushWithTimeout` when the deadline wins the race. When the\n   * signal fires, the pending write-chain drain is abandoned and the\n   * file handle is closed immediately, releasing OS resources instead\n   * of leaving the handle open until the orphaned writeChain resolves.\n   */\n  close: (signal?: AbortSignal) => Promise<void>;\n  /** Returns the most recent error (or null) without throwing. */\n  getLastError: () => string | null;\n}\n\nexport interface OpenTraceRecorderOptions {\n  /**\n   * If true (default), `path` is created with `mkdir -p` on its\n   * parent directory before the first append. Set to false in tests\n   * that pre-create the parent.\n   */\n  ensureParentDir?: boolean;\n}\n\n/**\n * Open (create or append to) a JSONL trace recorder at `filePath`.\n * Each call to `recorder.append(snapshot)` writes\n * `JSON.stringify(snapshot) + \"\\n\"`. Concurrent appends are\n * serialized through an internal write chain so partial-line\n * interleaving cannot occur.\n */\nexport async function openTraceRecorder(\n  filePath: string,\n  options: OpenTraceRecorderOptions = {},\n): Promise<TraceRecorder> {\n  const ensureParentDir = options.ensureParentDir ?? true;\n  if (ensureParentDir) {\n    const parent = path.dirname(filePath);\n    if (parent && parent !== \".\" && parent !== \"/\") {\n      await fs.mkdir(parent, { recursive: true });\n    }\n  }\n  const handle = await fs.open(filePath, \"a\");\n  let closed = false;\n  let lastError: string | null = null;\n  // Codex P0 (Common Gotcha #40): a serialized promise chain without\n  // `.catch()` recovery permanently poisons the chain after the first\n  // I/O error. Use `queueWrite` — it surfaces the error to the caller\n  // AND restores the chain to a resolved state for the next caller.\n  let writeChain: Promise<void> = Promise.resolve();\n  const queueWrite = (line: string): Promise<void> => {\n    const next = writeChain.then(async () => {\n      if (closed) return;\n      try {\n        await handle.write(line);\n      } catch (err) {\n        const msg = describeError(err);\n        lastError = msg;\n        // Re-throw so the caller's awaiter sees the failure, but\n        // recover the chain below so the next append can still run.\n        throw err;\n      }\n    });\n    writeChain = next.catch(() => {\n      // Recovery: reset the chain so a single transient failure does\n      // not poison every subsequent append. The original error is\n      // already captured in `lastError` AND was surfaced to the\n      // caller via the awaited `next` promise above.\n    });\n    return next;\n  };\n  return {\n    append: async (snapshot: ConsoleStateSnapshot) => {\n      if (closed) return;\n      let line: string;\n      try {\n        line = JSON.stringify(snapshot) + \"\\n\";\n      } catch (err) {\n        // A non-serializable snapshot is a bug, not a runtime\n        // condition we should crash on. Record + skip.\n        lastError = `serialize failed: ${describeError(err)}`;\n        return;\n      }\n      try {\n        await queueWrite(line);\n      } catch {\n        // already captured in lastError via queueWrite\n      }\n    },\n    close: async (signal?: AbortSignal) => {\n      if (closed) return;\n      // Codex P1: do NOT set `closed = true` before draining. Each\n      // queued write begins with `if (closed) return;`, so flipping the\n      // flag first would silently drop frames that callers already\n      // queued via `append()`. Drain the existing chain first so every\n      // already-queued write executes against the still-open handle,\n      // THEN flip `closed` to reject any further appends, THEN close\n      // the file handle. This honors the documented \"drain pending\n      // writes\" contract of `close()`.\n      //\n      // Codex P1 (PR #732 round 5): when `flushWithTimeout` races the\n      // drain against a deadline and the timeout wins, it fires the\n      // `signal` passed here. We race the writeChain drain against that\n      // signal so the file handle is closed promptly instead of being\n      // held open until the orphaned writeChain eventually resolves.\n      try {\n        if (signal) {\n          await Promise.race([\n            writeChain,\n            new Promise<void>((_, reject) => {\n              if (signal.aborted) {\n                reject(makeAbortError());\n                return;\n              }\n              signal.addEventListener(\"abort\", () => reject(makeAbortError()), {\n                once: true,\n              });\n            }),\n          ]);\n        } else {\n          await writeChain;\n        }\n      } catch {\n        // ignore — abort or I/O error already in lastError\n      }\n      closed = true;\n      try {\n        await handle.close();\n      } catch (err) {\n        lastError = describeError(err);\n      }\n    },\n    getLastError: () => lastError,\n  };\n}\n\nexport interface ReplayTraceOptions {\n  /** Output stream. Defaults to `process.stdout`. */\n  output?: Writable;\n  /**\n   * Speed multiplier. `1` = original cadence, `2` = twice as fast,\n   * `0.5` = half speed. `Infinity` is permitted and means \"no\n   * delay\" (back-to-back frames). Defaults to 1.\n   */\n  speed?: number;\n  /**\n   * Override the inter-frame delay function — primarily for tests so\n   * we can swap `setTimeout` for an instant resolver. The function\n   * receives the *raw* (already-speed-adjusted) delay in ms.\n   */\n  sleep?: (ms: number) => Promise<void>;\n  /**\n   * Hide / show the terminal cursor during replay. Defaults to true.\n   * Tests typically pass false so they don't pollute captured output\n   * with cursor-control escapes.\n   */\n  manageCursor?: boolean;\n  /**\n   * Optional clock injection — feeds `renderFrame`'s \"current time\"\n   * value during replay. By default, replay uses the snapshot's own\n   * `capturedAt` so the rendered timestamp matches the original\n   * frame. Tests override this for determinism.\n   */\n  now?: (snapshot: ConsoleStateSnapshot, frameIndex: number) => number;\n  /**\n   * Abort signal. If aborted mid-replay, the loop exits cleanly at\n   * the next frame boundary.\n   */\n  signal?: AbortSignal;\n}\n\nexport interface ReplayTraceResult {\n  /** Total frames rendered. */\n  framesRendered: number;\n  /** Frames skipped because they could not be parsed. */\n  framesSkipped: number;\n  /** Last snapshot that was rendered, or null if the file was empty. */\n  lastSnapshot: ConsoleStateSnapshot | null;\n}\n\n/**\n * Replay a JSONL trace file frame-by-frame. Each line is parsed,\n * optionally renders via `renderFrame`, then waits the speed-adjusted\n * delay before the next frame. Returns once EOF is reached or the\n * abort signal fires.\n */\nexport async function replayTrace(\n  filePath: string,\n  options: ReplayTraceOptions = {},\n): Promise<ReplayTraceResult> {\n  const output: Writable = options.output ?? process.stdout;\n  const speed = normalizeSpeed(options.speed);\n  // Codex P2 (PR #732 follow-up): the default sleeper now uses\n  // `sleepAbortable` which REJECTS with `AbortError` on signal abort\n  // (rather than resolving silently). The replay loop catches the\n  // AbortError and exits cleanly. Custom `sleep` implementations are\n  // responsible for their own abort wiring; if they reject with an\n  // AbortError-shaped error the loop will treat it as a clean exit.\n  const sleep =\n    options.sleep ?? ((ms: number) => sleepAbortable(ms, options.signal));\n  const manageCursor = options.manageCursor ?? true;\n  const nowFn =\n    options.now ??\n    ((snapshot: ConsoleStateSnapshot) => {\n      const ms = Date.parse(snapshot.capturedAt);\n      return Number.isFinite(ms) ? ms : Date.now();\n    });\n\n  const stream = createReadStream(filePath, { encoding: \"utf-8\" });\n  const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });\n\n  let framesRendered = 0;\n  let framesSkipped = 0;\n  let lastSnapshot: ConsoleStateSnapshot | null = null;\n  let prevCapturedMs: number | null = null;\n\n  if (manageCursor) safeWrite(output, ANSI_HIDE_CURSOR);\n\n  try {\n    for await (const rawLine of rl) {\n      if (options.signal?.aborted) break;\n      const line = rawLine.trim();\n      if (line.length === 0) continue;\n      const snapshot = parseSnapshotLine(line);\n      if (snapshot === null) {\n        framesSkipped += 1;\n        continue;\n      }\n\n      // Compute the inter-frame delay from the captured timestamps.\n      // The first frame paints immediately; subsequent frames wait\n      // `(this.capturedAt - prev.capturedAt) / speed`.\n      const capturedMs = Date.parse(snapshot.capturedAt);\n      let waitMs = 0;\n      if (prevCapturedMs !== null && Number.isFinite(capturedMs)) {\n        const rawDelta = capturedMs - prevCapturedMs;\n        waitMs = computeReplayDelay(rawDelta, speed);\n      } else if (prevCapturedMs !== null) {\n        // No usable timestamp on this frame — fall back to the\n        // default refresh interval (also speed-adjusted).\n        waitMs = computeReplayDelay(DEFAULT_REPLAY_DELAY_MS, speed);\n      }\n      if (waitMs > 0) {\n        try {\n          await sleep(waitMs);\n        } catch (err) {\n          // Codex P2 (PR #732 follow-up): `sleepAbortable` rejects\n          // with AbortError when SIGINT fires mid-sleep. Treat any\n          // AbortError-shaped rejection as a clean early exit so\n          // Ctrl-C does not have to wait for the current `setTimeout`\n          // to elapse. Re-throw any other error so genuine bugs\n          // surface.\n          if (isAbortError(err) || options.signal?.aborted) break;\n          throw err;\n        }\n        if (options.signal?.aborted) break;\n      }\n\n      let frame: string;\n      try {\n        frame = renderFrame({\n          snapshot,\n          renderError: null,\n          now: () => nowFn(snapshot, framesRendered),\n        });\n      } catch (err) {\n        // Mirror the live loop's renderer-failure recovery: emit a\n        // minimal error frame and keep replaying.\n        frame = `remnic console replay: render failed: ${describeError(err)}\\n`;\n      }\n      safeWrite(output, ANSI_CLEAR_HOME);\n      safeWrite(output, frame);\n\n      framesRendered += 1;\n      lastSnapshot = snapshot;\n      if (Number.isFinite(capturedMs)) prevCapturedMs = capturedMs;\n    }\n  } finally {\n    rl.close();\n    stream.close();\n    if (manageCursor) safeWrite(output, ANSI_SHOW_CURSOR);\n  }\n\n  return { framesRendered, framesSkipped, lastSnapshot };\n}\n\n/**\n * Parse a single JSONL line into a `ConsoleStateSnapshot`. Returns\n * null for malformed lines so the replay loop can keep going. We\n * validate the minimum nested shape the renderer dereferences. The trace file\n * format is best-effort, but partial objects are skipped rather than counted as\n * rendered frames that only display renderer failures.\n */\nexport function parseSnapshotLine(line: string): ConsoleStateSnapshot | null {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(line);\n  } catch {\n    return null;\n  }\n  // Common Gotcha #18: JSON.parse('null') succeeds but null is not a\n  // valid snapshot. Always check the result type.\n  if (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) {\n    return null;\n  }\n  if (!isConsoleStateSnapshot(parsed)) {\n    return null;\n  }\n  return parsed;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction isConsoleStateSnapshot(value: unknown): value is ConsoleStateSnapshot {\n  if (!isRecord(value)) return false;\n  if (typeof value.capturedAt !== \"string\") return false;\n\n  const bufferState = value.bufferState;\n  if (!isRecord(bufferState)) return false;\n  if (typeof bufferState.turnsCount !== \"number\") return false;\n  if (typeof bufferState.byteCount !== \"number\") return false;\n\n  const extractionQueue = value.extractionQueue;\n  if (!isRecord(extractionQueue)) return false;\n  if (typeof extractionQueue.depth !== \"number\") return false;\n  if (!Array.isArray(extractionQueue.recentVerdicts)) return false;\n\n  if (!Array.isArray(value.dedupRecent)) return false;\n  if (!Array.isArray(value.maintenanceLedgerTail)) return false;\n\n  const qmdProbe = value.qmdProbe;\n  if (!isRecord(qmdProbe)) return false;\n  if (typeof qmdProbe.available !== \"boolean\") return false;\n  if (typeof qmdProbe.daemonMode !== \"boolean\") return false;\n  if (typeof qmdProbe.debug !== \"string\") return false;\n\n  const daemon = value.daemon;\n  if (!isRecord(daemon)) return false;\n  if (typeof daemon.uptimeMs !== \"number\") return false;\n  if (typeof daemon.version !== \"string\") return false;\n\n  return Array.isArray(value.errors);\n}\n\n/**\n * Compute the speed-adjusted, clamped inter-frame delay. Exposed for\n * tests so we can assert the speed math without a real timer.\n *\n * - `rawDeltaMs` is the captured-time difference between two frames\n *   (may be negative if the trace went back in time — clamped to 0).\n * - `speed` must be a positive finite number OR `Infinity` (treated\n *   as \"no delay\"). Non-positive / NaN values are normalized to 1\n *   upstream so this function never sees them.\n */\nexport function computeReplayDelay(rawDeltaMs: number, speed: number): number {\n  if (!Number.isFinite(rawDeltaMs)) return 0;\n  if (rawDeltaMs <= 0) return 0;\n  if (!Number.isFinite(speed)) return 0; // Infinity → no delay.\n  const adjusted = rawDeltaMs / speed;\n  if (!Number.isFinite(adjusted)) return 0;\n  if (adjusted <= MIN_REPLAY_DELAY_MS) return MIN_REPLAY_DELAY_MS;\n  if (adjusted > MAX_REPLAY_DELAY_MS) return MAX_REPLAY_DELAY_MS;\n  return adjusted;\n}\n\n/**\n * Coerce a user-provided `--speed` value into a valid positive\n * multiplier. Common Gotchas #28 / #36: CLI values arrive as strings,\n * and `\"false\"` / `\"0\"` are truthy. Always convert + validate at the\n * input boundary. Throws on invalid input so the CLI surfaces a\n * helpful error message instead of silently defaulting (Common\n * Gotcha #51).\n */\nexport function parseSpeedFlag(raw: unknown): number {\n  if (raw === undefined || raw === null) return 1;\n  const num = typeof raw === \"number\" ? raw : Number(raw);\n  if (!Number.isFinite(num) && num !== Infinity) {\n    throw new Error(\n      `invalid --speed value: ${JSON.stringify(raw)} (must be a positive number)`,\n    );\n  }\n  if (num <= 0) {\n    throw new Error(\n      `invalid --speed value: ${JSON.stringify(raw)} (must be > 0)`,\n    );\n  }\n  return num;\n}\n\nfunction normalizeSpeed(speed: number | undefined): number {\n  if (speed === undefined) return 1;\n  if (!Number.isFinite(speed) && speed !== Infinity) return 1;\n  if (speed <= 0) return 1;\n  return speed;\n}\n\n/**\n * Abortable sleep used by `replayTrace` between frames.\n *\n * Codex P2 (PR #732): unlike a plain `setTimeout` wrapper, this\n * variant REJECTS with `AbortError` when `signal` fires (or is\n * already aborted on entry). That gives callers a way to\n * *distinguish* timer-expiry from signal-driven early exit, instead\n * of silently resolving on both. The replay loop catches the\n * `AbortError` and exits cleanly so Ctrl-C does not have to wait for\n * the current inter-frame `setTimeout` (capped at 60s) to elapse.\n *\n * Resolves only on timer expiry. Rejects with `AbortError` (DOMException-\n * shaped: `name === \"AbortError\"`) on abort. Exported so callers in\n * tests and adjacent modules can reuse the same primitive.\n */\nexport function sleepAbortable(\n  ms: number,\n  signal?: AbortSignal,\n): Promise<void> {\n  return new Promise((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(makeAbortError());\n      return;\n    }\n    const timer = setTimeout(() => {\n      if (signal && onAbort) signal.removeEventListener(\"abort\", onAbort);\n      resolve();\n    }, ms);\n    let onAbort: (() => void) | null = null;\n    if (signal) {\n      onAbort = () => {\n        clearTimeout(timer);\n        reject(makeAbortError());\n      };\n      signal.addEventListener(\"abort\", onAbort, { once: true });\n    }\n  });\n}\n\n/**\n * Construct an `AbortError`-shaped error. Prefers the standard\n * `DOMException(\"...\", \"AbortError\")` when available (Node 18+);\n * falls back to a plain Error with `name = \"AbortError\"` for\n * environments without `DOMException`.\n */\nfunction makeAbortError(): Error {\n  if (typeof DOMException !== \"undefined\") {\n    return new DOMException(\"aborted\", \"AbortError\");\n  }\n  const err = new Error(\"aborted\");\n  err.name = \"AbortError\";\n  return err;\n}\n\n/**\n * Detect an AbortError-shaped rejection. Matches both\n * `DOMException(\"...\", \"AbortError\")` and plain `Error` with\n * `name === \"AbortError\"`. Exported for tests.\n */\nexport function isAbortError(err: unknown): boolean {\n  return (\n    typeof err === \"object\" &&\n    err !== null &&\n    \"name\" in err &&\n    (err as { name?: unknown }).name === \"AbortError\"\n  );\n}\n\nexport interface FlushWithTimeoutResult {\n  /** True if the flush completed before the deadline. */\n  flushed: boolean;\n  /** True if the deadline won. */\n  timedOut: boolean;\n  /** Error from the flush, if any. */\n  error: unknown;\n}\n\n/**\n * Bound a recorder flush against a wall-clock deadline (Codex P1, PR\n * #732 follow-up).\n *\n * The CLI shutdown path awaits `recorder.close()`. On a wedged\n * network-backed filesystem that drain can block indefinitely. This\n * helper races the drain against `timeoutMs` and returns a structured\n * result so the caller can decide whether to log a warning, retry, or\n * proceed silently. Returning a structured result (rather than\n * throwing) keeps shutdown ordering deterministic — the caller must\n * always reach the next teardown step.\n *\n * Errors raised by the flush are captured in `result.error` rather\n * than re-thrown.\n *\n * The `flush` factory receives an `AbortSignal` that fires when the\n * timeout wins the race. Callers should forward the signal into\n * whatever I/O the flush performs so the underlying operation is\n * actually cancelled rather than just orphaned. The signal is fired\n * exactly once, immediately after the timeout sentinel wins. The flush\n * promise is still awaited in the background; any subsequent error is\n * silently discarded (it was already abandoned by the caller).\n */\nexport async function flushWithTimeout(\n  flush: (signal: AbortSignal) => Promise<void>,\n  timeoutMs: number,\n): Promise<FlushWithTimeoutResult> {\n  const TIMEOUT_SENTINEL = Symbol(\"flush-timeout\");\n  let error: unknown = null;\n  let timeoutHandle: ReturnType<typeof setTimeout> | null = null;\n  // Codex P1 (PR #732 round 5): give the flush an AbortSignal so the\n  // underlying close() can stop holding resources when the timeout\n  // wins. Previously the close kept running silently after the race\n  // resolved — the AbortController lets callers wire cancellation into\n  // their I/O path (e.g., by aborting a stream or write chain) instead\n  // of merely abandoning the orphaned promise.\n  const ac = new AbortController();\n  const flushPromise = flush(ac.signal).then(\n    () => undefined,\n    (err) => {\n      error = err;\n      // Resolve so the race winner is \"flush\" — the caller inspects\n      // `result.error` to decide what to do.\n      return undefined;\n    },\n  );\n  const timeoutPromise = new Promise<symbol>((resolve) => {\n    timeoutHandle = setTimeout(() => resolve(TIMEOUT_SENTINEL), timeoutMs);\n    // Codex P1 (PR #732): unref the fallback timer so it does not\n    // hold the event loop open on its own. Belt-and-suspenders with\n    // the `clearTimeout` in the `finally` below: even if a future\n    // refactor accidentally drops the clear, an unref'd timer will\n    // not prevent process exit once the flush has resolved.\n    if (typeof timeoutHandle.unref === \"function\") {\n      timeoutHandle.unref();\n    }\n  });\n  try {\n    const winner = await Promise.race<symbol | void>([\n      flushPromise,\n      timeoutPromise,\n    ]);\n    if (winner === TIMEOUT_SENTINEL) {\n      // Fire the abort signal so the flush's underlying I/O can\n      // release its resources rather than staying open indefinitely.\n      ac.abort();\n      return { flushed: false, timedOut: true, error: null };\n    }\n    return { flushed: true, timedOut: false, error };\n  } finally {\n    // Codex P1 (PR #732): clear the fallback timer when the flush\n    // wins the race. Without this, Node keeps the ref'd timeout\n    // handle alive for the full `timeoutMs` and delays process exit\n    // by that interval on EVERY normal shutdown — turning a\n    // safety-net into a consistent user-visible hang.\n    if (timeoutHandle !== null) {\n      clearTimeout(timeoutHandle);\n    }\n  }\n}\n\nfunction safeWrite(output: Writable, chunk: string): void {\n  try {\n    output.write(chunk);\n  } catch {\n    // ignore — best effort\n  }\n}\n\nfunction describeError(err: unknown): string {\n  if (err instanceof Error) return err.message;\n  try {\n    return String(err);\n  } catch {\n    return \"unknown error\";\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/transcript.d.ts

@@ -1,5 +1,6 @@
 import { PluginConfig, TranscriptEntry, Checkpoint } from './types.js';
 import { SessionIntegrityReport } from './session-integrity.js';
+import './types-BliCnURB.js';
 import './index-DJ9QWMw-.js';
 
 /**

package/dist/transcript.js

@@ -1,8 +1,8 @@
 import {
   TranscriptManager
-} from "./chunk-5375UYTQ.js";
+} from "./chunk-A6D7A2FW.js";
 import "./chunk-FF4KLI5W.js";
-import "./chunk-YRMVARQP.js";
+import "./chunk-KFY3SGN7.js";
 import "./chunk-2ODBA7MQ.js";
 import "./chunk-PZ5AY32C.js";
 export {

package/dist/transfer/autodetect.js

@@ -1,13 +1,13 @@
 import {
   detectImportFormat
-} from "../chunk-DOM4GKSW.js";
-import "../chunk-W4L6CZKA.js";
-import "../chunk-3JXBXXM2.js";
-import "../chunk-6H2TESSP.js";
-import "../chunk-WEHSQBFR.js";
+} from "../chunk-OZKVVUJB.js";
+import "../chunk-2DL3OFLD.js";
+import "../chunk-G4IAEX6D.js";
+import "../chunk-765K3SAT.js";
 import "../chunk-J4EB7DNW.js";
-import "../chunk-I6K5FBRQ.js";
-import "../chunk-AGZQD76C.js";
+import "../chunk-WEHSQBFR.js";
+import "../chunk-UI3NYK34.js";
+import "../chunk-GCGJW34D.js";
 import "../chunk-PZ5AY32C.js";
 export {
   detectImportFormat

package/dist/transfer/backup.js

@@ -1,14 +1,14 @@
 import {
   backupMemoryDir
-} from "../chunk-7OZ53EXP.js";
-import "../chunk-6H2TESSP.js";
-import "../chunk-KNKUID7G.js";
+} from "../chunk-2NLLXCJG.js";
+import "../chunk-765K3SAT.js";
 import "../chunk-J4EB7DNW.js";
+import "../chunk-X7Y7WX73.js";
 import "../chunk-BJMBJZ2Y.js";
 import "../chunk-UKJAGEXH.js";
 import "../chunk-FP2373TW.js";
-import "../chunk-I6K5FBRQ.js";
-import "../chunk-AGZQD76C.js";
+import "../chunk-UI3NYK34.js";
+import "../chunk-GCGJW34D.js";
 import "../chunk-A6XUJE5D.js";
 import "../chunk-PZ5AY32C.js";
 export {

package/dist/transfer/capsule-export.js

@@ -1,15 +1,15 @@
 import {
   exportCapsule,
   isValidCapsuleSince
-} from "../chunk-QA2ZAPBU.js";
-import "../chunk-WEHSQBFR.js";
-import "../chunk-KNKUID7G.js";
+} from "../chunk-IPLYGWQF.js";
 import "../chunk-J4EB7DNW.js";
+import "../chunk-WEHSQBFR.js";
+import "../chunk-X7Y7WX73.js";
 import "../chunk-BJMBJZ2Y.js";
 import "../chunk-UKJAGEXH.js";
 import "../chunk-FP2373TW.js";
-import "../chunk-I6K5FBRQ.js";
-import "../chunk-AGZQD76C.js";
+import "../chunk-UI3NYK34.js";
+import "../chunk-GCGJW34D.js";
 import "../chunk-A6XUJE5D.js";
 import "../chunk-PZ5AY32C.js";
 export {

package/dist/transfer/capsule-import.d.ts

@@ -64,6 +64,12 @@ interface ImportCapsuleOptions {
      * When provided and the archive is NOT encrypted, the value is ignored.
      */
     memoryDir?: string;
+    /**
+     * Original secure-store passphrase for encrypted format-v2 archives. When
+     * supplied, the importer derives the archive key from the embedded KDF
+     * header, enabling restore without the source machine's unlocked keyring.
+     */
+    passphrase?: string;
 }
 interface ImportCapsuleSkippedRecord {
     /** Original record path (capsule-relative, posix). */

package/dist/transfer/capsule-import.js

@@ -1,13 +1,13 @@
 import {
   importCapsule
-} from "../chunk-ZYVPLJ4T.js";
-import "../chunk-FAAFWE4G.js";
+} from "../chunk-DHGSZ3UD.js";
+import "../chunk-ALEPI75L.js";
 import "../chunk-WEHSQBFR.js";
-import "../chunk-KNKUID7G.js";
+import "../chunk-X7Y7WX73.js";
 import "../chunk-BJMBJZ2Y.js";
 import "../chunk-UKJAGEXH.js";
 import "../chunk-FP2373TW.js";
-import "../chunk-AGZQD76C.js";
+import "../chunk-GCGJW34D.js";
 import "../chunk-A6XUJE5D.js";
 import "../chunk-PZ5AY32C.js";
 export {

package/dist/transfer/export-json.js

@@ -1,9 +1,9 @@
 import {
   exportJsonBundle
-} from "../chunk-GIF42EW3.js";
+} from "../chunk-UP6MOYCB.js";
 import "../chunk-J4EB7DNW.js";
-import "../chunk-I6K5FBRQ.js";
-import "../chunk-AGZQD76C.js";
+import "../chunk-UI3NYK34.js";
+import "../chunk-GCGJW34D.js";
 import "../chunk-PZ5AY32C.js";
 export {
   exportJsonBundle

package/dist/transfer/export-md.js

@@ -1,10 +1,10 @@
 import {
   exportMarkdownBundle,
   looksLikeEngramMdExport
-} from "../chunk-6H2TESSP.js";
+} from "../chunk-765K3SAT.js";
 import "../chunk-J4EB7DNW.js";
-import "../chunk-I6K5FBRQ.js";
-import "../chunk-AGZQD76C.js";
+import "../chunk-UI3NYK34.js";
+import "../chunk-GCGJW34D.js";
 import "../chunk-PZ5AY32C.js";
 export {
   exportMarkdownBundle,

package/dist/transfer/export-sqlite.js

@@ -1,10 +1,10 @@
 import {
   exportSqlite
-} from "../chunk-66DHUKLO.js";
+} from "../chunk-XSWKORGM.js";
 import "../chunk-Z734BLO3.js";
 import "../chunk-3HPAPHUK.js";
-import "../chunk-I6K5FBRQ.js";
-import "../chunk-AGZQD76C.js";
+import "../chunk-UI3NYK34.js";
+import "../chunk-GCGJW34D.js";
 import "../chunk-PZ5AY32C.js";
 export {
   exportSqlite

package/dist/transfer/fs-utils.d.ts

@@ -31,6 +31,7 @@ interface SafeArchiveRoot {
 declare function prepareSafeArchiveRoot(absPath: string, errorPrefix: string, argName: string): Promise<SafeArchiveRoot>;
 declare function validateArchiveRelativePath(relPath: string, errorPrefix: string): string;
 declare function resolveSafeArchiveTarget(root: SafeArchiveRoot, relPath: string): Promise<string>;
+declare function writeSafeArchiveTarget(root: SafeArchiveRoot, relPath: string, content: string | Uint8Array): Promise<void>;
 /**
  * Return true when {@link absPath} is the same as {@link rootReal} or a
  * descendant. {@link rootReal} should be the value returned by
@@ -58,4 +59,4 @@ declare function assertIsDirectoryNotSymlink(absPath: string, errorPrefix: strin
  */
 declare function assertRealpathInsideRoot(rootReal: string, targetAbs: string, sourcePath: string, errorPrefix: string): Promise<void>;
 
-export { type SafeArchiveRoot, assertIsDirectoryNotSymlink, assertRealpathInsideRoot, ensureDirExists, fileExists, fromPosixRelPath, isPathInsideRoot, listFilesRecursive, prepareSafeArchiveRoot, readJsonFile, readUtf8FileStrict, resolveSafeArchiveTarget, sha256Bytes, sha256File, sha256String, toPosixRelPath, validateArchiveRelativePath, writeJsonFile };
+export { type SafeArchiveRoot, assertIsDirectoryNotSymlink, assertRealpathInsideRoot, ensureDirExists, fileExists, fromPosixRelPath, isPathInsideRoot, listFilesRecursive, prepareSafeArchiveRoot, readJsonFile, readUtf8FileStrict, resolveSafeArchiveTarget, sha256Bytes, sha256File, sha256String, toPosixRelPath, validateArchiveRelativePath, writeJsonFile, writeSafeArchiveTarget };

package/dist/transfer/fs-utils.js

@@ -15,8 +15,9 @@ import {
   sha256String,
   toPosixRelPath,
   validateArchiveRelativePath,
-  writeJsonFile
-} from "../chunk-AGZQD76C.js";
+  writeJsonFile,
+  writeSafeArchiveTarget
+} from "../chunk-GCGJW34D.js";
 import "../chunk-PZ5AY32C.js";
 export {
   assertIsDirectoryNotSymlink,
@@ -35,6 +36,7 @@ export {
   sha256String,
   toPosixRelPath,
   validateArchiveRelativePath,
-  writeJsonFile
+  writeJsonFile,
+  writeSafeArchiveTarget
 };
 //# sourceMappingURL=fs-utils.js.map

package/dist/transfer/import-json.js

@@ -1,10 +1,10 @@
 import {
   importJsonBundle,
   looksLikeEngramJsonExport
-} from "../chunk-W4L6CZKA.js";
-import "../chunk-3JXBXXM2.js";
+} from "../chunk-2DL3OFLD.js";
+import "../chunk-G4IAEX6D.js";
 import "../chunk-WEHSQBFR.js";
-import "../chunk-AGZQD76C.js";
+import "../chunk-GCGJW34D.js";
 import "../chunk-PZ5AY32C.js";
 export {
   importJsonBundle,

package/dist/transfer/import-md.js

@@ -1,9 +1,9 @@
 import {
   importMarkdownBundle
-} from "../chunk-TK4UEOSK.js";
-import "../chunk-3JXBXXM2.js";
+} from "../chunk-HDDRVXX4.js";
+import "../chunk-G4IAEX6D.js";
 import "../chunk-WEHSQBFR.js";
-import "../chunk-AGZQD76C.js";
+import "../chunk-GCGJW34D.js";
 import "../chunk-PZ5AY32C.js";
 export {
   importMarkdownBundle

package/dist/transfer/import-sqlite.js

@@ -1,10 +1,10 @@
 import {
   importSqlite
-} from "../chunk-XKLD5OK4.js";
-import "../chunk-3JXBXXM2.js";
+} from "../chunk-4RR6ROTB.js";
 import "../chunk-Z734BLO3.js";
+import "../chunk-G4IAEX6D.js";
 import "../chunk-3HPAPHUK.js";
-import "../chunk-AGZQD76C.js";
+import "../chunk-GCGJW34D.js";
 import "../chunk-PZ5AY32C.js";
 export {
   importSqlite

package/dist/trust-zones.js

@@ -11,9 +11,9 @@ import {
   seedTrustZoneDemoDataset,
   summarizeTrustZonePromotionReadiness,
   validateTrustZoneRecord
-} from "./chunk-QDZ2RLEC.js";
+} from "./chunk-472U7RDF.js";
 import "./chunk-DT5TVLJE.js";
-import "./chunk-DGXUHMOV.js";
+import "./chunk-A2IYSXDQ.js";
 import "./chunk-LPSF4OQH.js";
 import "./chunk-PZ5AY32C.js";
 export {

package/dist/types-B1VHaf2w.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Peer registry types — issue #679 PR 1/5.
+ *
+ * Generalizes the singular identity-anchor model to a multi-peer registry.
+ * Every party Remnic interacts with — humans, agents, integrations, and
+ * "self" — is represented as a `Peer` with an evolving cognitive profile.
+ *
+ * This module defines pure types only. Storage primitives live in
+ * `./storage.ts`. Reasoner integration, recall injection, CLI/HTTP/MCP
+ * surfaces, and migration of existing identity-anchor data ship in later
+ * PRs (2/5 — 5/5).
+ */
+/**
+ * Kind of peer.
+ *
+ * - `self`     — the current Remnic operator (replaces singular identity-anchor).
+ * - `human`    — another human collaborator distinct from self.
+ * - `agent`    — another AI agent (Claude Code, Codex, Hermes, etc.).
+ * - `integration` — non-conversational integration (cron, webhook, importer).
+ */
+type PeerKind = "self" | "human" | "agent" | "integration";
+/**
+ * Stable, slow-changing facts about a peer.
+ *
+ * `id` matches `^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$`, 1-64 chars,
+ * with no leading/trailing/consecutive dots or dashes. Stored on disk under
+ * `peers/{id}/identity.md` as YAML frontmatter + markdown body.
+ */
+interface Peer {
+    /** Stable, opaque identifier. See PEER_ID_PATTERN. */
+    readonly id: string;
+    /** Kind of peer. Drives default profile schema and recall posture. */
+    readonly kind: PeerKind;
+    /** Human-readable display name. Distinct from `id`; mutable. */
+    readonly displayName: string;
+    /** ISO-8601 timestamp of first registration. */
+    readonly createdAt: string;
+    /** ISO-8601 timestamp of most recent update to identity. */
+    readonly updatedAt: string;
+    /** Optional free-form markdown body for the identity kernel. */
+    readonly notes?: string;
+}
+/**
+ * Evolving cognitive profile for a peer.
+ *
+ * Updated by the async profile reasoner (PR 2/5) from observable session
+ * signals. Every field carries provenance back to its originating session
+ * and signal. This PR only defines the shape — population is deferred.
+ */
+interface PeerProfile {
+    /** Peer this profile belongs to. */
+    readonly peerId: string;
+    /** ISO-8601 timestamp of most recent profile mutation. */
+    readonly updatedAt: string;
+    /**
+     * Arbitrary key/value profile fields. Values are markdown strings.
+     * Keys are stable section identifiers (e.g. `communication_style`,
+     * `recurring_concerns`). The reasoner is responsible for choosing
+     * keys; this PR does not constrain them beyond requiring strings.
+     */
+    readonly fields: Record<string, string>;
+    /**
+     * Per-field provenance. Maps field key → list of provenance entries.
+     * A field may have multiple sources (the reasoner accumulates evidence
+     * across sessions before promoting a field).
+     */
+    readonly provenance: Record<string, ReadonlyArray<PeerProfileFieldProvenance>>;
+}
+/**
+ * Provenance for a single profile-field mutation.
+ *
+ * Reasoner output (PR 2/5) attaches one of these every time it touches a
+ * field, so the user can audit exactly why a profile claim exists.
+ */
+interface PeerProfileFieldProvenance {
+    /** ISO-8601 timestamp the field was set/updated by this signal. */
+    readonly observedAt: string;
+    /** Originating session id (or other source identifier). */
+    readonly sourceSessionId?: string;
+    /** Short label for the signal type (e.g. "explicit_preference"). */
+    readonly signal: string;
+    /** Optional free-form note explaining the inference. */
+    readonly note?: string;
+}
+/**
+ * One row of the append-only interaction log for a peer.
+ *
+ * Stored on disk under `peers/{id}/interactions.log.md` as a sequence of
+ * markdown bullet entries with a leading ISO-8601 timestamp. Append-only
+ * by contract — the reasoner reads this log to derive profile updates.
+ */
+interface PeerInteractionLogEntry {
+    /** ISO-8601 timestamp the interaction occurred. */
+    readonly timestamp: string;
+    /** Originating session id, if any. */
+    readonly sessionId?: string;
+    /** Short kind label (e.g. "message", "tool_call", "preference_set"). */
+    readonly kind: string;
+    /** Free-form markdown summary of the interaction. */
+    readonly summary: string;
+}
+/**
+ * Regex enforced on `Peer.id`. Exported so callers can mirror validation
+ * before constructing a `Peer`.
+ *
+ * Rules:
+ *   - 1-64 characters total
+ *   - First and last character must be `[A-Za-z0-9]`
+ *   - Interior may contain `.`, `_`, `-` in addition to alphanumerics
+ *   - No leading or trailing dot/dash/underscore
+ *   - No consecutive separators (`..`, `--`, `__`, `.-`, etc.)
+ *
+ * Cursor Medium: previously the regex allowed `a..b` even though the
+ * docs claimed otherwise — a separate JS-side check enforced the rule
+ * but the standalone PATTERN was wrong for any external consumer
+ * relying on it. Tighten the regex itself so PEER_ID_PATTERN is the
+ * single source of truth: an alphanumeric, optionally followed by
+ * groups of (one separator + one-or-more alphanumerics), with the
+ * final group ending on an alphanumeric. Negative lookahead-free so
+ * it works in any JS engine.
+ */
+declare const PEER_ID_PATTERN: RegExp;
+/** Maximum length for `Peer.id`. */
+declare const PEER_ID_MAX_LENGTH = 64;
+
+export { type PeerInteractionLogEntry as P, type Peer as a, type PeerProfile as b, PEER_ID_MAX_LENGTH as c, PEER_ID_PATTERN as d, type PeerKind as e, type PeerProfileFieldProvenance as f };

package/dist/types-BliCnURB.d.ts

@@ -0,0 +1,83 @@
+import { L as LcmMessagePartInput, M as MessagePartSourceFormat } from './index-DJ9QWMw-.js';
+
+interface BulkImportSource {
+    turns: ImportTurn[];
+    metadata: {
+        source: string;
+        exportDate: string;
+        messageCount: number;
+        dateRange: {
+            from: string;
+            to: string;
+        };
+    };
+}
+interface ImportTurn {
+    role: "user" | "assistant" | "other";
+    content: string;
+    timestamp: string;
+    participantId?: string;
+    participantName?: string;
+    replyToId?: string;
+    parts?: LcmMessagePartInput[];
+    rawContent?: unknown;
+    sourceFormat?: MessagePartSourceFormat;
+    importProvenance?: ImportTurnProvenance;
+}
+interface ImportTurnProvenance {
+    sourceLabel?: string;
+    sourceId?: string;
+    sourceTimestamp?: string;
+    importedFromPath?: string;
+    importedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+interface BulkImportOptions {
+    batchSize?: number;
+    dryRun?: boolean;
+    dedup?: boolean;
+    trustLevel?: "import";
+    namespace?: string;
+}
+type ImportSourceRole = ImportTurn["role"];
+interface BulkImportResult {
+    memoriesCreated: number;
+    duplicatesSkipped: number;
+    entitiesCreated: number;
+    turnsProcessed: number;
+    batchesProcessed: number;
+    errors: BulkImportError[];
+}
+interface BulkImportError {
+    batchIndex: number;
+    message: string;
+}
+interface BulkImportSourceAdapter {
+    name: string;
+    parse(input: unknown, options?: {
+        strict?: boolean;
+        platform?: string;
+    }): Promise<BulkImportSource> | BulkImportSource;
+}
+interface ImportTurnValidationIssue {
+    code: string;
+    message: string;
+    index?: number;
+}
+declare function isImportRole(value: unknown): value is ImportSourceRole;
+/**
+ * Parse an ISO-8601 / RFC 3339 timestamp used by bulk-import adapters.
+ *
+ * Accepts variable-precision fractional seconds and either a `Z` suffix or a
+ * `[+-]HH:MM` timezone offset, so adapters may preserve their source
+ * timestamps verbatim. Returns milliseconds since epoch, or `null` if the
+ * string is not a well-formed timestamp (including overflowed calendar dates
+ * or out-of-range offsets).
+ *
+ * Delegates to the shared parser in `utils/iso-timestamp.ts` — do not
+ * reimplement locally; extend that helper instead.
+ */
+declare function parseIsoTimestamp(value: string): number | null;
+declare function validateImportTurn(turn: ImportTurn, index?: number): ImportTurnValidationIssue[];
+
+export { type BulkImportOptions as B, type ImportTurn as I, type BulkImportSource as a, type BulkImportResult as b, type ImportTurnProvenance as c, type BulkImportError as d, type BulkImportSourceAdapter as e, type ImportSourceRole as f, type ImportTurnValidationIssue as g, isImportRole as i, parseIsoTimestamp as p, validateImportTurn as v };

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import { c as ImportTurnProvenance } from './types-BliCnURB.js';
 import { L as LcmMessagePartInput, M as MessagePartSourceFormat } from './index-DJ9QWMw-.js';
 
 /**
@@ -1168,6 +1169,39 @@ interface PluginConfig {
      */
     localLlmDisableThinking: boolean;
     gatewayConfig?: GatewayConfig;
+    /**
+     * Optional host-supplied resolver for provider API keys. Core never discovers
+     * host runtimes directly; adapters inject their native secret resolver here.
+     */
+    providerApiKeyResolver?: (params: {
+        provider: string;
+        cfg?: unknown;
+        agentDir?: string;
+    }) => Promise<{
+        apiKey?: string;
+        source?: string;
+        mode?: string;
+    } | null>;
+    /**
+     * Optional host-supplied resolver for request-ready model auth, including
+     * provider transforms such as OAuth token exchange or base URL overrides.
+     */
+    runtimeAuthForModelResolver?: (params: {
+        model: {
+            provider: string;
+            id: string;
+            api?: string;
+            baseUrl?: string;
+        };
+        cfg?: unknown;
+        workspaceDir?: string;
+    }) => Promise<{
+        apiKey?: string;
+        baseUrl?: string;
+        source?: string;
+        mode?: string;
+        profileId?: string;
+    } | null>;
     modelSource: "plugin" | "gateway";
     gatewayAgentId: string;
     fastGatewayAgentId: string;
@@ -1895,6 +1929,7 @@ interface BufferTurn {
     parts?: LcmMessagePartInput[];
     rawContent?: unknown;
     sourceFormat?: MessagePartSourceFormat;
+    importProvenance?: ImportTurnProvenance;
 }
 interface BufferEntryState {
     turns: BufferTurn[];

package/dist/types.js

@@ -4,7 +4,7 @@ import {
   SPECULATIVE_TTL_DAYS,
   confidenceTier,
   isRecallDisclosure
-} from "./chunk-Q7P4WJDP.js";
+} from "./chunk-M5T4Q2ZU.js";
 import "./chunk-PZ5AY32C.js";
 export {
   DEFAULT_RECALL_DISCLOSURE,

package/dist/utility-learner.js

@@ -3,10 +3,10 @@ import {
   learnUtilityPromotionWeights,
   readUtilityLearningSnapshot,
   resolveUtilityLearningStatePath
-} from "./chunk-PYXS46O7.js";
-import "./chunk-3QKK7QOS.js";
+} from "./chunk-3BP57I6J.js";
+import "./chunk-TERNBNJB.js";
 import "./chunk-TBBDFYXW.js";
-import "./chunk-DGXUHMOV.js";
+import "./chunk-A2IYSXDQ.js";
 import "./chunk-LPSF4OQH.js";
 import "./chunk-PZ5AY32C.js";
 export {

package/dist/utility-runtime.d.ts

@@ -1,5 +1,6 @@
 import { TierRoutingPolicy } from './tier-routing.js';
 import './types.js';
+import './types-BliCnURB.js';
 import './index-DJ9QWMw-.js';
 import './lifecycle.js';
 

package/dist/utility-runtime.js

@@ -2,11 +2,11 @@ import {
   applyUtilityPromotionRuntimePolicy,
   applyUtilityRankingRuntimeDelta,
   loadUtilityRuntimeValues
-} from "./chunk-FSFEQI74.js";
-import "./chunk-PYXS46O7.js";
-import "./chunk-3QKK7QOS.js";
+} from "./chunk-W7L6HXUC.js";
+import "./chunk-3BP57I6J.js";
+import "./chunk-TERNBNJB.js";
 import "./chunk-TBBDFYXW.js";
-import "./chunk-DGXUHMOV.js";
+import "./chunk-A2IYSXDQ.js";
 import "./chunk-LPSF4OQH.js";
 import "./chunk-PZ5AY32C.js";
 export {