@remnic/core 1.1.2 → 1.1.4

package/dist/tier-stats-62ZVDFKS.js

@@ -0,0 +1,152 @@
+import {
+  applyUtilityPromotionRuntimePolicy,
+  loadUtilityRuntimeValues
+} from "./chunk-FSFEQI74.js";
+import {
+  computeTierValueScore,
+  decideTierTransition
+} from "./chunk-S75M5ZRK.js";
+import "./chunk-PYXS46O7.js";
+import "./chunk-3QKK7QOS.js";
+import {
+  computeLifecycleValueInputs
+} from "./chunk-TBBDFYXW.js";
+import "./chunk-DGXUHMOV.js";
+import "./chunk-LPSF4OQH.js";
+import "./chunk-PZ5AY32C.js";
+
+// src/maintenance/tier-stats.ts
+async function readTierVisibleMemories(storage) {
+  const [hotMemories, coldMemories] = await Promise.all([
+    storage.readAllMemories(),
+    storage.readAllColdMemories()
+  ]);
+  return [
+    ...hotMemories.map((memory) => ({ memory, tier: "hot" })),
+    ...coldMemories.map((memory) => ({ memory, tier: "cold" }))
+  ];
+}
+async function tierRoutingPolicyFromConfig(config) {
+  const basePolicy = {
+    enabled: config.qmdTierMigrationEnabled,
+    demotionMinAgeDays: config.qmdTierDemotionMinAgeDays,
+    demotionValueThreshold: config.qmdTierDemotionValueThreshold,
+    promotionValueThreshold: config.qmdTierPromotionValueThreshold
+  };
+  const runtime = await loadUtilityRuntimeValues({
+    memoryDir: config.memoryDir,
+    memoryUtilityLearningEnabled: config.memoryUtilityLearningEnabled,
+    promotionByOutcomeEnabled: config.promotionByOutcomeEnabled
+  });
+  return applyUtilityPromotionRuntimePolicy(basePolicy, runtime);
+}
+async function summarizeTiers(storage) {
+  const all = await readTierVisibleMemories(storage);
+  const summary = {
+    total: all.length,
+    byTier: { hot: 0, cold: 0 },
+    byStatus: {},
+    forgottenCount: 0,
+    byCategory: {}
+  };
+  for (const { memory: m, tier } of all) {
+    summary.byTier[tier] += 1;
+    const status = m.frontmatter.status ?? "active";
+    summary.byStatus[status] = (summary.byStatus[status] ?? 0) + 1;
+    if (status === "forgotten") summary.forgottenCount += 1;
+    const cat = m.frontmatter.category ?? "(uncategorized)";
+    summary.byCategory[cat] = (summary.byCategory[cat] ?? 0) + 1;
+  }
+  return summary;
+}
+async function explainTierForMemory(storage, id, config) {
+  const trimmed = typeof id === "string" ? id.trim() : "";
+  if (trimmed.length === 0) {
+    throw new Error("tier explain: memory id is required and must be non-empty");
+  }
+  const all = await readTierVisibleMemories(storage);
+  const entry = all.find(({ memory: m }) => m.frontmatter.id === trimmed);
+  if (!entry) {
+    throw new Error(`tier explain: memory not found: ${trimmed}`);
+  }
+  const { memory, tier: currentTier } = entry;
+  const now = /* @__PURE__ */ new Date();
+  const valueInputs = computeLifecycleValueInputs(memory, now);
+  const valueScore = computeTierValueScore(memory, now);
+  const policy = await tierRoutingPolicyFromConfig(config);
+  const decision = decideTierTransition(memory, currentTier, policy, now);
+  const fm = memory.frontmatter;
+  return {
+    id: trimmed,
+    path: memory.path,
+    currentTier,
+    status: typeof fm.status === "string" ? fm.status : "active",
+    category: typeof fm.category === "string" ? fm.category : "",
+    valueScore,
+    decision,
+    signals: {
+      confidence: valueInputs.confidence,
+      accessCount: typeof fm.accessCount === "number" ? fm.accessCount : 0,
+      lastAccessed: typeof fm.lastAccessed === "string" ? fm.lastAccessed : null,
+      created: typeof fm.created === "string" ? fm.created : "",
+      updated: typeof fm.updated === "string" ? fm.updated : "",
+      importance: valueInputs.importance,
+      feedback: valueInputs.feedback
+    }
+  };
+}
+function formatTierSummaryText(summary) {
+  const lines = [];
+  lines.push("=== Memory Tier Distribution ===");
+  lines.push(`Total memories: ${summary.total}`);
+  lines.push("");
+  lines.push("Tier:");
+  lines.push(`  hot:  ${summary.byTier.hot}`);
+  lines.push(`  cold: ${summary.byTier.cold}`);
+  lines.push("");
+  lines.push("Status:");
+  const statusEntries = Object.entries(summary.byStatus).sort(
+    (a, b) => b[1] - a[1] || a[0].localeCompare(b[0])
+  );
+  for (const [status, count] of statusEntries) {
+    lines.push(`  ${status}: ${count}`);
+  }
+  lines.push("");
+  lines.push("Top categories:");
+  const categoryEntries = Object.entries(summary.byCategory).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 8);
+  for (const [cat, count] of categoryEntries) {
+    lines.push(`  ${cat}: ${count}`);
+  }
+  return lines.join("\n");
+}
+function formatTierExplainText(explain) {
+  const lines = [];
+  lines.push(`=== Tier Explain: ${explain.id} ===`);
+  lines.push(`path:          ${explain.path}`);
+  lines.push(`current tier:  ${explain.currentTier}`);
+  lines.push(`status:        ${explain.status}`);
+  lines.push(`category:      ${explain.category}`);
+  lines.push(`value score:   ${explain.valueScore.toFixed(3)}`);
+  lines.push("");
+  lines.push("Tier-transition decision:");
+  lines.push(`  next tier: ${explain.decision.nextTier}`);
+  lines.push(`  changed:   ${explain.decision.changed}`);
+  lines.push(`  reason:    ${explain.decision.reason}`);
+  lines.push("");
+  lines.push("Signals:");
+  lines.push(`  confidence:   ${explain.signals.confidence}`);
+  lines.push(`  accessCount:  ${explain.signals.accessCount}`);
+  lines.push(`  lastAccessed: ${explain.signals.lastAccessed ?? "(never)"}`);
+  lines.push(`  created:      ${explain.signals.created}`);
+  lines.push(`  updated:      ${explain.signals.updated}`);
+  lines.push(`  importance:   ${explain.signals.importance}`);
+  lines.push(`  feedback:     ${explain.signals.feedback}`);
+  return lines.join("\n");
+}
+export {
+  explainTierForMemory,
+  formatTierExplainText,
+  formatTierSummaryText,
+  summarizeTiers
+};
+//# sourceMappingURL=tier-stats-62ZVDFKS.js.map

package/dist/tier-stats-62ZVDFKS.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/maintenance/tier-stats.ts"],"sourcesContent":["/**\n * Operator-facing tier visibility (issue #686 PR 5/6).\n *\n * Two read-only surfaces:\n *\n *   - `summarizeTiers(storage)` — count memories by tier (hot vs cold)\n *     plus per-status breakdown so operators can see at a glance\n *     whether the lifecycle policy has actually demoted anything.\n *   - `explainTierForMemory(storage, id)` — show the value-score\n *     components and tier-transition decision for a single memory\n *     so an operator can reason about why a memory ended up where\n *     it did.\n *\n * Pure inspection — neither surface mutates anything.  The CLI wires\n * them as `remnic tier list` and `remnic tier explain <id>`.\n */\n\nimport type { StorageManager } from \"../storage.js\";\nimport type { MemoryFile, PluginConfig } from \"../types.js\";\nimport { computeLifecycleValueInputs } from \"../lifecycle.js\";\nimport {\n  computeTierValueScore,\n  decideTierTransition,\n  type MemoryTier,\n  type TierRoutingPolicy,\n  type TierTransitionDecision,\n} from \"../tier-routing.js\";\nimport {\n  applyUtilityPromotionRuntimePolicy,\n  loadUtilityRuntimeValues,\n} from \"../utility-runtime.js\";\n\nexport interface TierSummary {\n  /** Total memories scanned (all tiers, all statuses). */\n  total: number;\n  byTier: Record<MemoryTier, number>;\n  byStatus: Record<string, number>;\n  /** Memories with `status === \"forgotten\"` (issue #686 PR 4/6). */\n  forgottenCount: number;\n  /** Top contributors to the forgotten / archived buckets, by category. */\n  byCategory: Record<string, number>;\n}\n\nexport interface TierExplainResult {\n  id: string;\n  path: string;\n  currentTier: MemoryTier;\n  status: string;\n  category: string;\n  valueScore: number;\n  decision: TierTransitionDecision;\n  signals: {\n    confidence: number;\n    accessCount: number;\n    lastAccessed: string | null;\n    created: string;\n    updated: string;\n    importance: number;\n    feedback: number;\n  };\n}\n\ninterface TierVisibleMemory {\n  memory: MemoryFile;\n  tier: MemoryTier;\n}\n\nasync function readTierVisibleMemories(\n  storage: StorageManager,\n): Promise<TierVisibleMemory[]> {\n  const [hotMemories, coldMemories] = await Promise.all([\n    storage.readAllMemories(),\n    storage.readAllColdMemories(),\n  ]);\n  return [\n    ...hotMemories.map((memory) => ({ memory, tier: \"hot\" as const })),\n    ...coldMemories.map((memory) => ({ memory, tier: \"cold\" as const })),\n  ];\n}\n\nasync function tierRoutingPolicyFromConfig(\n  config: PluginConfig,\n): Promise<TierRoutingPolicy> {\n  const basePolicy: TierRoutingPolicy = {\n    enabled: config.qmdTierMigrationEnabled,\n    demotionMinAgeDays: config.qmdTierDemotionMinAgeDays,\n    demotionValueThreshold: config.qmdTierDemotionValueThreshold,\n    promotionValueThreshold: config.qmdTierPromotionValueThreshold,\n  };\n  const runtime = await loadUtilityRuntimeValues({\n    memoryDir: config.memoryDir,\n    memoryUtilityLearningEnabled: config.memoryUtilityLearningEnabled,\n    promotionByOutcomeEnabled: config.promotionByOutcomeEnabled,\n  });\n  return applyUtilityPromotionRuntimePolicy(basePolicy, runtime);\n}\n\nexport async function summarizeTiers(\n  storage: StorageManager,\n): Promise<TierSummary> {\n  const all = await readTierVisibleMemories(storage);\n  const summary: TierSummary = {\n    total: all.length,\n    byTier: { hot: 0, cold: 0 },\n    byStatus: {},\n    forgottenCount: 0,\n    byCategory: {},\n  };\n  for (const { memory: m, tier } of all) {\n    summary.byTier[tier] += 1;\n    const status: string = m.frontmatter.status ?? \"active\";\n    summary.byStatus[status] = (summary.byStatus[status] ?? 0) + 1;\n    // Compare via the widened `string` type so this module compiles\n    // both before and after PR 4/6 lands `\"forgotten\"` in MemoryStatus.\n    if (status === \"forgotten\") summary.forgottenCount += 1;\n    const cat = m.frontmatter.category ?? \"(uncategorized)\";\n    summary.byCategory[cat] = (summary.byCategory[cat] ?? 0) + 1;\n  }\n  return summary;\n}\n\nexport async function explainTierForMemory(\n  storage: StorageManager,\n  id: string,\n  config: PluginConfig,\n): Promise<TierExplainResult> {\n  const trimmed = typeof id === \"string\" ? id.trim() : \"\";\n  if (trimmed.length === 0) {\n    throw new Error(\"tier explain: memory id is required and must be non-empty\");\n  }\n  const all = await readTierVisibleMemories(storage);\n  const entry = all.find(({ memory: m }) => m.frontmatter.id === trimmed);\n  if (!entry) {\n    throw new Error(`tier explain: memory not found: ${trimmed}`);\n  }\n  const { memory, tier: currentTier } = entry;\n  const now = new Date();\n  const valueInputs = computeLifecycleValueInputs(memory, now);\n  const valueScore = computeTierValueScore(memory, now);\n  const policy = await tierRoutingPolicyFromConfig(config);\n  const decision = decideTierTransition(memory, currentTier, policy, now);\n  const fm = memory.frontmatter as unknown as Record<string, unknown>;\n  return {\n    id: trimmed,\n    path: memory.path,\n    currentTier,\n    status: typeof fm.status === \"string\" ? (fm.status as string) : \"active\",\n    category: typeof fm.category === \"string\" ? (fm.category as string) : \"\",\n    valueScore,\n    decision,\n    signals: {\n      confidence: valueInputs.confidence,\n      accessCount:\n        typeof fm.accessCount === \"number\" ? (fm.accessCount as number) : 0,\n      lastAccessed:\n        typeof fm.lastAccessed === \"string\" ? (fm.lastAccessed as string) : null,\n      created: typeof fm.created === \"string\" ? (fm.created as string) : \"\",\n      updated: typeof fm.updated === \"string\" ? (fm.updated as string) : \"\",\n      importance: valueInputs.importance,\n      feedback: valueInputs.feedback,\n    },\n  };\n}\n\n/**\n * Render a TierSummary as plain text for `remnic tier list` text mode.\n * Pure formatter — exposed so future surfaces (HTTP, MCP) can reuse.\n */\nexport function formatTierSummaryText(summary: TierSummary): string {\n  const lines: string[] = [];\n  lines.push(\"=== Memory Tier Distribution ===\");\n  lines.push(`Total memories: ${summary.total}`);\n  lines.push(\"\");\n  lines.push(\"Tier:\");\n  lines.push(`  hot:  ${summary.byTier.hot}`);\n  lines.push(`  cold: ${summary.byTier.cold}`);\n  lines.push(\"\");\n  lines.push(\"Status:\");\n  const statusEntries = Object.entries(summary.byStatus).sort(\n    (a, b) => b[1] - a[1] || a[0].localeCompare(b[0]),\n  );\n  for (const [status, count] of statusEntries) {\n    lines.push(`  ${status}: ${count}`);\n  }\n  lines.push(\"\");\n  lines.push(\"Top categories:\");\n  const categoryEntries = Object.entries(summary.byCategory)\n    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))\n    .slice(0, 8);\n  for (const [cat, count] of categoryEntries) {\n    lines.push(`  ${cat}: ${count}`);\n  }\n  return lines.join(\"\\n\");\n}\n\n/**\n * Render a TierExplainResult as plain text for `remnic tier explain`.\n */\nexport function formatTierExplainText(explain: TierExplainResult): string {\n  const lines: string[] = [];\n  lines.push(`=== Tier Explain: ${explain.id} ===`);\n  lines.push(`path:          ${explain.path}`);\n  lines.push(`current tier:  ${explain.currentTier}`);\n  lines.push(`status:        ${explain.status}`);\n  lines.push(`category:      ${explain.category}`);\n  lines.push(`value score:   ${explain.valueScore.toFixed(3)}`);\n  lines.push(\"\");\n  lines.push(\"Tier-transition decision:\");\n  lines.push(`  next tier: ${explain.decision.nextTier}`);\n  lines.push(`  changed:   ${explain.decision.changed}`);\n  lines.push(`  reason:    ${explain.decision.reason}`);\n  lines.push(\"\");\n  lines.push(\"Signals:\");\n  lines.push(`  confidence:   ${explain.signals.confidence}`);\n  lines.push(`  accessCount:  ${explain.signals.accessCount}`);\n  lines.push(`  lastAccessed: ${explain.signals.lastAccessed ?? \"(never)\"}`);\n  lines.push(`  created:      ${explain.signals.created}`);\n  lines.push(`  updated:      ${explain.signals.updated}`);\n  lines.push(`  importance:   ${explain.signals.importance}`);\n  lines.push(`  feedback:     ${explain.signals.feedback}`);\n  return lines.join(\"\\n\");\n}\n"],"mappings":"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","names":[]}

package/dist/tmt.js

@@ -12,6 +12,7 @@ import {
   tmtDir,
   weekNodePath
 } from "./chunk-TPB3I2AC.js";
+import "./chunk-PZ5AY32C.js";
 export {
   TMT_DIR,
   TmtBuilder,

package/dist/tokens.js

@@ -11,6 +11,7 @@ import {
   saveTokenStore
 } from "./chunk-VTU2B4VF.js";
 import "./chunk-MARWOCVP.js";
+import "./chunk-PZ5AY32C.js";
 export {
   buildTokenEntry,
   commitTokenEntry,

package/dist/topics.js

@@ -2,6 +2,7 @@ import {
   extractTopics,
   findTrendingTopics
 } from "./chunk-UHGBNIOS.js";
+import "./chunk-PZ5AY32C.js";
 export {
   extractTopics,
   findTrendingTopics

package/dist/trace-C5ETWBEF.js

@@ -0,0 +1,290 @@
+import {
+  renderFrame
+} from "./chunk-32KD5IHZ.js";
+import "./chunk-TYEOAFH3.js";
+import "./chunk-PZ5AY32C.js";
+
+// src/console/trace.ts
+import { promises as fs } from "fs";
+import path from "path";
+import readline from "readline";
+import { createReadStream } from "fs";
+var ANSI_CLEAR_HOME = "\x1B[2J\x1B[H";
+var ANSI_HIDE_CURSOR = "\x1B[?25l";
+var ANSI_SHOW_CURSOR = "\x1B[?25h";
+var DEFAULT_REPLAY_DELAY_MS = 2e3;
+var MAX_REPLAY_DELAY_MS = 6e4;
+var MIN_REPLAY_DELAY_MS = 0;
+async function openTraceRecorder(filePath, options = {}) {
+  const ensureParentDir = options.ensureParentDir ?? true;
+  if (ensureParentDir) {
+    const parent = path.dirname(filePath);
+    if (parent && parent !== "." && parent !== "/") {
+      await fs.mkdir(parent, { recursive: true });
+    }
+  }
+  const handle = await fs.open(filePath, "a");
+  let closed = false;
+  let lastError = null;
+  let writeChain = Promise.resolve();
+  const queueWrite = (line) => {
+    const next = writeChain.then(async () => {
+      if (closed) return;
+      try {
+        await handle.write(line);
+      } catch (err) {
+        const msg = describeError(err);
+        lastError = msg;
+        throw err;
+      }
+    });
+    writeChain = next.catch(() => {
+    });
+    return next;
+  };
+  return {
+    append: async (snapshot) => {
+      if (closed) return;
+      let line;
+      try {
+        line = JSON.stringify(snapshot) + "\n";
+      } catch (err) {
+        lastError = `serialize failed: ${describeError(err)}`;
+        return;
+      }
+      try {
+        await queueWrite(line);
+      } catch {
+      }
+    },
+    close: async (signal) => {
+      if (closed) return;
+      try {
+        if (signal) {
+          await Promise.race([
+            writeChain,
+            new Promise((_, reject) => {
+              if (signal.aborted) {
+                reject(makeAbortError());
+                return;
+              }
+              signal.addEventListener("abort", () => reject(makeAbortError()), {
+                once: true
+              });
+            })
+          ]);
+        } else {
+          await writeChain;
+        }
+      } catch {
+      }
+      closed = true;
+      try {
+        await handle.close();
+      } catch (err) {
+        lastError = describeError(err);
+      }
+    },
+    getLastError: () => lastError
+  };
+}
+async function replayTrace(filePath, options = {}) {
+  const output = options.output ?? process.stdout;
+  const speed = normalizeSpeed(options.speed);
+  const sleep = options.sleep ?? ((ms) => sleepAbortable(ms, options.signal));
+  const manageCursor = options.manageCursor ?? true;
+  const nowFn = options.now ?? ((snapshot) => {
+    const ms = Date.parse(snapshot.capturedAt);
+    return Number.isFinite(ms) ? ms : Date.now();
+  });
+  const stream = createReadStream(filePath, { encoding: "utf-8" });
+  const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+  let framesRendered = 0;
+  let framesSkipped = 0;
+  let lastSnapshot = null;
+  let prevCapturedMs = null;
+  if (manageCursor) safeWrite(output, ANSI_HIDE_CURSOR);
+  try {
+    for await (const rawLine of rl) {
+      if (options.signal?.aborted) break;
+      const line = rawLine.trim();
+      if (line.length === 0) continue;
+      const snapshot = parseSnapshotLine(line);
+      if (snapshot === null) {
+        framesSkipped += 1;
+        continue;
+      }
+      const capturedMs = Date.parse(snapshot.capturedAt);
+      let waitMs = 0;
+      if (prevCapturedMs !== null && Number.isFinite(capturedMs)) {
+        const rawDelta = capturedMs - prevCapturedMs;
+        waitMs = computeReplayDelay(rawDelta, speed);
+      } else if (prevCapturedMs !== null) {
+        waitMs = computeReplayDelay(DEFAULT_REPLAY_DELAY_MS, speed);
+      }
+      if (waitMs > 0) {
+        try {
+          await sleep(waitMs);
+        } catch (err) {
+          if (isAbortError(err) || options.signal?.aborted) break;
+          throw err;
+        }
+        if (options.signal?.aborted) break;
+      }
+      let frame;
+      try {
+        frame = renderFrame({
+          snapshot,
+          renderError: null,
+          now: () => nowFn(snapshot, framesRendered)
+        });
+      } catch (err) {
+        frame = `remnic console replay: render failed: ${describeError(err)}
+`;
+      }
+      safeWrite(output, ANSI_CLEAR_HOME);
+      safeWrite(output, frame);
+      framesRendered += 1;
+      lastSnapshot = snapshot;
+      if (Number.isFinite(capturedMs)) prevCapturedMs = capturedMs;
+    }
+  } finally {
+    rl.close();
+    stream.close();
+    if (manageCursor) safeWrite(output, ANSI_SHOW_CURSOR);
+  }
+  return { framesRendered, framesSkipped, lastSnapshot };
+}
+function parseSnapshotLine(line) {
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return null;
+  }
+  return parsed;
+}
+function computeReplayDelay(rawDeltaMs, speed) {
+  if (!Number.isFinite(rawDeltaMs)) return 0;
+  if (rawDeltaMs <= 0) return 0;
+  if (!Number.isFinite(speed)) return 0;
+  const adjusted = rawDeltaMs / speed;
+  if (!Number.isFinite(adjusted)) return 0;
+  if (adjusted <= MIN_REPLAY_DELAY_MS) return MIN_REPLAY_DELAY_MS;
+  if (adjusted > MAX_REPLAY_DELAY_MS) return MAX_REPLAY_DELAY_MS;
+  return adjusted;
+}
+function parseSpeedFlag(raw) {
+  if (raw === void 0 || raw === null) return 1;
+  const num = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isFinite(num) && num !== Infinity) {
+    throw new Error(
+      `invalid --speed value: ${JSON.stringify(raw)} (must be a positive number)`
+    );
+  }
+  if (num <= 0) {
+    throw new Error(
+      `invalid --speed value: ${JSON.stringify(raw)} (must be > 0)`
+    );
+  }
+  return num;
+}
+function normalizeSpeed(speed) {
+  if (speed === void 0) return 1;
+  if (!Number.isFinite(speed) && speed !== Infinity) return 1;
+  if (speed <= 0) return 1;
+  return speed;
+}
+function sleepAbortable(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(makeAbortError());
+      return;
+    }
+    const timer = setTimeout(() => {
+      if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    let onAbort = null;
+    if (signal) {
+      onAbort = () => {
+        clearTimeout(timer);
+        reject(makeAbortError());
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
+function makeAbortError() {
+  if (typeof DOMException !== "undefined") {
+    return new DOMException("aborted", "AbortError");
+  }
+  const err = new Error("aborted");
+  err.name = "AbortError";
+  return err;
+}
+function isAbortError(err) {
+  return typeof err === "object" && err !== null && "name" in err && err.name === "AbortError";
+}
+async function flushWithTimeout(flush, timeoutMs) {
+  const TIMEOUT_SENTINEL = /* @__PURE__ */ Symbol("flush-timeout");
+  let error = null;
+  let timeoutHandle = null;
+  const ac = new AbortController();
+  const flushPromise = flush(ac.signal).then(
+    () => void 0,
+    (err) => {
+      error = err;
+      return void 0;
+    }
+  );
+  const timeoutPromise = new Promise((resolve) => {
+    timeoutHandle = setTimeout(() => resolve(TIMEOUT_SENTINEL), timeoutMs);
+    if (typeof timeoutHandle.unref === "function") {
+      timeoutHandle.unref();
+    }
+  });
+  try {
+    const winner = await Promise.race([
+      flushPromise,
+      timeoutPromise
+    ]);
+    if (winner === TIMEOUT_SENTINEL) {
+      ac.abort();
+      return { flushed: false, timedOut: true, error: null };
+    }
+    return { flushed: true, timedOut: false, error };
+  } finally {
+    if (timeoutHandle !== null) {
+      clearTimeout(timeoutHandle);
+    }
+  }
+}
+function safeWrite(output, chunk) {
+  try {
+    output.write(chunk);
+  } catch {
+  }
+}
+function describeError(err) {
+  if (err instanceof Error) return err.message;
+  try {
+    return String(err);
+  } catch {
+    return "unknown error";
+  }
+}
+export {
+  computeReplayDelay,
+  flushWithTimeout,
+  isAbortError,
+  openTraceRecorder,
+  parseSnapshotLine,
+  parseSpeedFlag,
+  replayTrace,
+  sleepAbortable
+};
+//# sourceMappingURL=trace-C5ETWBEF.js.map

package/dist/trace-C5ETWBEF.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 * intentionally do NOT validate every nested field — the renderer is\n * already defensive about missing fields and the trace file format\n * is best-effort.\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  // Best-effort cast: the renderer is tolerant of missing fields.\n  return parsed as ConsoleStateSnapshot;\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.js

@@ -3,6 +3,7 @@ import {
 } from "./chunk-E6K4NIEU.js";
 import "./chunk-YRMVARQP.js";
 import "./chunk-2ODBA7MQ.js";
+import "./chunk-PZ5AY32C.js";
 export {
   TranscriptManager
 };

package/dist/trust-zones.js

@@ -15,6 +15,7 @@ import {
 import "./chunk-DT5TVLJE.js";
 import "./chunk-DGXUHMOV.js";
 import "./chunk-LPSF4OQH.js";
+import "./chunk-PZ5AY32C.js";
 export {
   getTrustZoneStoreStatus,
   isTrustZoneName,

package/dist/tui-RI7P6PBS.js

@@ -0,0 +1,13 @@
+import {
+  renderFrame,
+  runConsoleTui,
+  stripAnsi
+} from "./chunk-32KD5IHZ.js";
+import "./chunk-TYEOAFH3.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  renderFrame,
+  runConsoleTui,
+  stripAnsi
+};
+//# sourceMappingURL=tui-RI7P6PBS.js.map

package/dist/tui-RI7P6PBS.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types-V3FJ26TF.js

@@ -0,0 +1,30 @@
+import {
+  CAPSULE_ID_PATTERN,
+  CapsuleBlockSchema,
+  CapsuleIncludesSchema,
+  CapsuleParentSchema,
+  CapsuleRetrievalPolicySchema,
+  ExportBundleV1Schema,
+  ExportBundleV2Schema,
+  ExportManifestV1Schema,
+  ExportManifestV2Schema,
+  ExportMemoryRecordV1Schema,
+  parseExportBundle,
+  parseExportManifest
+} from "./chunk-OA3L7BFR.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  CAPSULE_ID_PATTERN,
+  CapsuleBlockSchema,
+  CapsuleIncludesSchema,
+  CapsuleParentSchema,
+  CapsuleRetrievalPolicySchema,
+  ExportBundleV1Schema,
+  ExportBundleV2Schema,
+  ExportManifestV1Schema,
+  ExportManifestV2Schema,
+  ExportMemoryRecordV1Schema,
+  parseExportBundle,
+  parseExportManifest
+};
+//# sourceMappingURL=types-V3FJ26TF.js.map

package/dist/types-V3FJ26TF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}