@unbrained/pm-cli 2026.5.31 → 2026.6.6

package/dist/core/history/history-diff.d.ts

@@ -0,0 +1,47 @@
+import type { HistoryEntry } from "../../types/index.js";
+export interface HistoryFieldChange {
+    field: string;
+    before: unknown;
+    after: unknown;
+}
+export interface HistoryDiffValueEntry {
+    /** 1-based position in the FULL stream (fullEntries index + 1). */
+    index: number;
+    ts: string;
+    op: string;
+    author: string;
+    /** Number of JSON-patch operations in this entry (entry.patch.length). */
+    patch_ops: number;
+    /** Unique field names touched by this entry, sorted by localeCompare. */
+    changed_fields: string[];
+    /** Per-field before/after values, sorted by field name (localeCompare). */
+    changes: HistoryFieldChange[];
+}
+/**
+ * Map a JSON-Patch path string to a human-readable changed-field name.
+ *
+ * Rules (in priority order):
+ *  - "/body" or "/body/…"                      → "body"
+ *  - "/metadata/…" or "/front_matter/…"
+ *      with a first segment                     → that decoded segment (e.g. "status")
+ *      without a first segment (bare prefix)    → "metadata"
+ *  - "/" (root pointer, empty segment after strip) → "root"
+ *  - anything else                               → decoded first path segment
+ */
+export declare function patchPathToChangedField(path: string): string;
+/**
+ * Replay a full history entry stream and produce enriched diff entries with
+ * per-field before/after values.
+ *
+ * @param fullEntries   The complete ordered history chain to replay.
+ * @param options.windowStartIndex  0-based index into fullEntries at which the
+ *   DISPLAYED window begins. Entries before this index are still replayed (so
+ *   state is accurate) but are not emitted. Defaults to 0.
+ * @param options.field  When supplied, only entries that changed this field are
+ *   emitted, and each emitted entry's `changes` and `changed_fields` are
+ *   restricted to that single field.
+ */
+export declare function computeHistoryDiff(fullEntries: HistoryEntry[], options?: {
+    windowStartIndex?: number;
+    field?: string;
+}): HistoryDiffValueEntry[];

package/dist/core/history/history-diff.js

@@ -0,0 +1,152 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="2b77be38-f27c-5a56-86de-9625777f7211")}catch(e){}}();
+import { cloneEmptyReplayDocument, tryApplyReplayPatch } from "./replay.js";
+// ---------------------------------------------------------------------------
+// JSON-Pointer helpers (ported from src/cli/commands/history.ts so the
+// orchestrator can replace the private copy there with an import from here).
+// ---------------------------------------------------------------------------
+function decodeJsonPointerSegment(segment) {
+    return segment.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+/**
+ * Map a JSON-Patch path string to a human-readable changed-field name.
+ *
+ * Rules (in priority order):
+ *  - "/body" or "/body/…"                      → "body"
+ *  - "/metadata/…" or "/front_matter/…"
+ *      with a first segment                     → that decoded segment (e.g. "status")
+ *      without a first segment (bare prefix)    → "metadata"
+ *  - "/" (root pointer, empty segment after strip) → "root"
+ *  - anything else                               → decoded first path segment
+ */
+export function patchPathToChangedField(path) {
+    if (path === "/body" || path.startsWith("/body/"))
+        return "body";
+    if (path === "/metadata" ||
+        path.startsWith("/metadata/") ||
+        path === "/front_matter" ||
+        path.startsWith("/front_matter/")) {
+        const segment = path.replace(/^\/(?:metadata|front_matter)\/?/, "").split("/")[0];
+        if (!segment)
+            return "metadata";
+        return decodeJsonPointerSegment(segment);
+    }
+    const segment = path.replace(/^\//, "").split("/")[0];
+    return segment ? decodeJsonPointerSegment(segment) : "root";
+}
+// ---------------------------------------------------------------------------
+// Field-value reader
+// ---------------------------------------------------------------------------
+/**
+ * Extract the before/after value for a logical field from a replay document.
+ *
+ * - "body"     → doc.body
+ * - "metadata" → doc.metadata (the whole object, for a bare /metadata replace)
+ * - "root"     → the whole document (for a bare "/" patch op)
+ * - other      → doc.metadata[field] (may be undefined when the field was absent)
+ */
+function readFieldValue(doc, field) {
+    if (field === "body")
+        return doc.body;
+    if (field === "metadata")
+        return doc.metadata;
+    if (field === "root")
+        return doc;
+    return doc.metadata[field];
+}
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+/**
+ * Replay a full history entry stream and produce enriched diff entries with
+ * per-field before/after values.
+ *
+ * @param fullEntries   The complete ordered history chain to replay.
+ * @param options.windowStartIndex  0-based index into fullEntries at which the
+ *   DISPLAYED window begins. Entries before this index are still replayed (so
+ *   state is accurate) but are not emitted. Defaults to 0.
+ * @param options.field  When supplied, only entries that changed this field are
+ *   emitted, and each emitted entry's `changes` and `changed_fields` are
+ *   restricted to that single field.
+ */
+export function computeHistoryDiff(fullEntries, options) {
+    const windowStartIndex = options?.windowStartIndex ?? 0;
+    const fieldFilter = options?.field;
+    if (fullEntries.length === 0 || windowStartIndex >= fullEntries.length) {
+        return [];
+    }
+    let current = cloneEmptyReplayDocument();
+    const result = [];
+    for (let p = 0; p < fullEntries.length; p += 1) {
+        const entry = fullEntries[p];
+        // Capture before state.
+        const beforeDoc = current;
+        // Attempt to apply patch.
+        const applied = tryApplyReplayPatch(current, entry.patch);
+        let afterDoc;
+        if (applied.ok) {
+            afterDoc = applied.document;
+            current = afterDoc;
+        }
+        else {
+            // Patch failed — use before state as after (cannot trust partial result).
+            // Do NOT advance current; keep prior replay state.
+            afterDoc = beforeDoc;
+        }
+        // Collect changed field names from patch paths (and from: paths for move/copy).
+        const changedFieldSet = new Set();
+        for (const patchOp of entry.patch) {
+            changedFieldSet.add(patchPathToChangedField(patchOp.path));
+            if (patchOp.from !== undefined) {
+                changedFieldSet.add(patchPathToChangedField(patchOp.from));
+            }
+        }
+        const sortedFields = [...changedFieldSet].sort((a, b) => a.localeCompare(b));
+        // Only emit entries in the display window.
+        if (p >= windowStartIndex) {
+            // Apply field filter: skip this entry entirely if it doesn't touch the
+            // requested field; otherwise narrow down to only that field.
+            if (fieldFilter !== undefined) {
+                if (!changedFieldSet.has(fieldFilter)) {
+                    // This entry does not touch the requested field — skip it.
+                    continue;
+                }
+                // Emit only the filtered field.
+                const change = {
+                    field: fieldFilter,
+                    before: readFieldValue(beforeDoc, fieldFilter),
+                    after: readFieldValue(afterDoc, fieldFilter),
+                };
+                result.push({
+                    index: p + 1,
+                    ts: entry.ts,
+                    op: entry.op,
+                    author: entry.author,
+                    patch_ops: entry.patch.length,
+                    changed_fields: [fieldFilter],
+                    changes: [change],
+                });
+            }
+            else {
+                // Emit all changed fields.
+                const changes = sortedFields.map((field) => ({
+                    field,
+                    before: readFieldValue(beforeDoc, field),
+                    after: readFieldValue(afterDoc, field),
+                }));
+                result.push({
+                    index: p + 1,
+                    ts: entry.ts,
+                    op: entry.op,
+                    author: entry.author,
+                    patch_ops: entry.patch.length,
+                    changed_fields: sortedFields,
+                    changes,
+                });
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=history-diff.js.map
+//# debugId=2b77be38-f27c-5a56-86de-9625777f7211

package/dist/core/history/history-diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-diff.js","sources":["core/history/history-diff.ts"],"sourceRoot":"/","sourcesContent":["import { cloneEmptyReplayDocument, tryApplyReplayPatch, type ReplayDocument } from \"./replay.js\";\nimport type { HistoryEntry } from \"../../types/index.js\";\n\nexport interface HistoryFieldChange {\n  field: string;\n  // before and after are the raw field values captured by replaying the history chain.\n  // `undefined` is intentional: it signals that the field was absent in the document at\n  // that point (e.g. after a JSON-Patch `remove` op). JSON serialization will omit\n  // undefined values, which correctly communicates \"field did not exist\".\n  before: unknown;\n  after: unknown;\n}\n\nexport interface HistoryDiffValueEntry {\n  /** 1-based position in the FULL stream (fullEntries index + 1). */\n  index: number;\n  ts: string;\n  op: string;\n  author: string;\n  /** Number of JSON-patch operations in this entry (entry.patch.length). */\n  patch_ops: number;\n  /** Unique field names touched by this entry, sorted by localeCompare. */\n  changed_fields: string[];\n  /** Per-field before/after values, sorted by field name (localeCompare). */\n  changes: HistoryFieldChange[];\n}\n\n// ---------------------------------------------------------------------------\n// JSON-Pointer helpers (ported from src/cli/commands/history.ts so the\n// orchestrator can replace the private copy there with an import from here).\n// ---------------------------------------------------------------------------\n\nfunction decodeJsonPointerSegment(segment: string): string {\n  return segment.replaceAll(\"~1\", \"/\").replaceAll(\"~0\", \"~\");\n}\n\n/**\n * Map a JSON-Patch path string to a human-readable changed-field name.\n *\n * Rules (in priority order):\n *  - \"/body\" or \"/body/…\"                      → \"body\"\n *  - \"/metadata/…\" or \"/front_matter/…\"\n *      with a first segment                     → that decoded segment (e.g. \"status\")\n *      without a first segment (bare prefix)    → \"metadata\"\n *  - \"/\" (root pointer, empty segment after strip) → \"root\"\n *  - anything else                               → decoded first path segment\n */\nexport function patchPathToChangedField(path: string): string {\n  if (path === \"/body\" || path.startsWith(\"/body/\")) return \"body\";\n  if (\n    path === \"/metadata\" ||\n    path.startsWith(\"/metadata/\") ||\n    path === \"/front_matter\" ||\n    path.startsWith(\"/front_matter/\")\n  ) {\n    const segment = path.replace(/^\\/(?:metadata|front_matter)\\/?/, \"\").split(\"/\")[0];\n    if (!segment) return \"metadata\";\n    return decodeJsonPointerSegment(segment);\n  }\n  const segment = path.replace(/^\\//, \"\").split(\"/\")[0];\n  return segment ? decodeJsonPointerSegment(segment) : \"root\";\n}\n\n// ---------------------------------------------------------------------------\n// Field-value reader\n// ---------------------------------------------------------------------------\n\n/**\n * Extract the before/after value for a logical field from a replay document.\n *\n * - \"body\"     → doc.body\n * - \"metadata\" → doc.metadata (the whole object, for a bare /metadata replace)\n * - \"root\"     → the whole document (for a bare \"/\" patch op)\n * - other      → doc.metadata[field] (may be undefined when the field was absent)\n */\nfunction readFieldValue(doc: ReplayDocument, field: string): unknown {\n  if (field === \"body\") return doc.body;\n  if (field === \"metadata\") return doc.metadata;\n  if (field === \"root\") return doc;\n  return doc.metadata[field];\n}\n\n// ---------------------------------------------------------------------------\n// Main export\n// ---------------------------------------------------------------------------\n\n/**\n * Replay a full history entry stream and produce enriched diff entries with\n * per-field before/after values.\n *\n * @param fullEntries   The complete ordered history chain to replay.\n * @param options.windowStartIndex  0-based index into fullEntries at which the\n *   DISPLAYED window begins. Entries before this index are still replayed (so\n *   state is accurate) but are not emitted. Defaults to 0.\n * @param options.field  When supplied, only entries that changed this field are\n *   emitted, and each emitted entry's `changes` and `changed_fields` are\n *   restricted to that single field.\n */\nexport function computeHistoryDiff(\n  fullEntries: HistoryEntry[],\n  options?: { windowStartIndex?: number; field?: string },\n): HistoryDiffValueEntry[] {\n  const windowStartIndex = options?.windowStartIndex ?? 0;\n  const fieldFilter = options?.field;\n\n  if (fullEntries.length === 0 || windowStartIndex >= fullEntries.length) {\n    return [];\n  }\n\n  let current = cloneEmptyReplayDocument();\n  const result: HistoryDiffValueEntry[] = [];\n\n  for (let p = 0; p < fullEntries.length; p += 1) {\n    const entry = fullEntries[p];\n\n    // Capture before state.\n    const beforeDoc = current;\n\n    // Attempt to apply patch.\n    const applied = tryApplyReplayPatch(current, entry.patch);\n    let afterDoc: ReplayDocument;\n    if (applied.ok) {\n      afterDoc = applied.document;\n      current = afterDoc;\n    } else {\n      // Patch failed — use before state as after (cannot trust partial result).\n      // Do NOT advance current; keep prior replay state.\n      afterDoc = beforeDoc;\n    }\n\n    // Collect changed field names from patch paths (and from: paths for move/copy).\n    const changedFieldSet = new Set<string>();\n    for (const patchOp of entry.patch) {\n      changedFieldSet.add(patchPathToChangedField(patchOp.path));\n      if (patchOp.from !== undefined) {\n        changedFieldSet.add(patchPathToChangedField(patchOp.from));\n      }\n    }\n    const sortedFields = [...changedFieldSet].sort((a, b) => a.localeCompare(b));\n\n    // Only emit entries in the display window.\n    if (p >= windowStartIndex) {\n      // Apply field filter: skip this entry entirely if it doesn't touch the\n      // requested field; otherwise narrow down to only that field.\n      if (fieldFilter !== undefined) {\n        if (!changedFieldSet.has(fieldFilter)) {\n          // This entry does not touch the requested field — skip it.\n          continue;\n        }\n        // Emit only the filtered field.\n        const change: HistoryFieldChange = {\n          field: fieldFilter,\n          before: readFieldValue(beforeDoc, fieldFilter),\n          after: readFieldValue(afterDoc, fieldFilter),\n        };\n        result.push({\n          index: p + 1,\n          ts: entry.ts,\n          op: entry.op,\n          author: entry.author,\n          patch_ops: entry.patch.length,\n          changed_fields: [fieldFilter],\n          changes: [change],\n        });\n      } else {\n        // Emit all changed fields.\n        const changes: HistoryFieldChange[] = sortedFields.map((field) => ({\n          field,\n          before: readFieldValue(beforeDoc, field),\n          after: readFieldValue(afterDoc, field),\n        }));\n        result.push({\n          index: p + 1,\n          ts: entry.ts,\n          op: entry.op,\n          author: entry.author,\n          patch_ops: entry.patch.length,\n          changed_fields: sortedFields,\n          changes,\n        });\n      }\n    }\n  }\n\n  return result;\n}\n"],"names":[],"mappings":"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","debugId":"2b77be38-f27c-5a56-86de-9625777f7211"}

package/dist/core/history/history-storage-stats.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pure aggregate metrics for history streams (JSONL files).
+ * No filesystem access — callers read raw stream contents and pass them in.
+ * This module has no Node imports; Buffer is available as a global.
+ */
+export interface HistoryStreamStat {
+    id: string;
+    bytes: number;
+    lines: number;
+    oldest_ts: string | null;
+    newest_ts: string | null;
+}
+export interface HistoryStorageEntryRef {
+    id: string;
+    ts: string;
+}
+export interface HistoryStorageStats {
+    total_streams: number;
+    total_lines: number;
+    total_bytes: number;
+    largest_by_bytes: HistoryStreamStat[];
+    deepest_by_lines: HistoryStreamStat[];
+    oldest_entry: HistoryStorageEntryRef | null;
+    newest_entry: HistoryStorageEntryRef | null;
+}
+export declare function computeHistoryStorageStats(streams: Array<{
+    id: string;
+    raw: string;
+}>, options?: {
+    topN?: number;
+}): HistoryStorageStats;

package/dist/core/history/history-storage-stats.js

@@ -0,0 +1,101 @@
+/**
+ * Pure aggregate metrics for history streams (JSONL files).
+ * No filesystem access — callers read raw stream contents and pass them in.
+ * This module has no Node imports; Buffer is available as a global.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="006b5d42-0ff6-57af-a598-4ca069ec316e")}catch(e){}}();
+function parseStreamStat(id, raw) {
+    const bytes = Buffer.byteLength(raw, "utf8");
+    let lines = 0;
+    let oldestTs = null;
+    let newestTs = null;
+    let oldestMs = Number.POSITIVE_INFINITY;
+    let newestMs = Number.NEGATIVE_INFINITY;
+    for (const rawLine of raw.split(/\r?\n/)) {
+        const trimmed = rawLine.trim();
+        if (trimmed === "") {
+            continue;
+        }
+        lines += 1;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (parsed === null ||
+            typeof parsed !== "object" ||
+            !("ts" in parsed) ||
+            typeof parsed["ts"] !== "string") {
+            continue;
+        }
+        const ts = parsed["ts"];
+        const ms = Date.parse(ts);
+        if (Number.isNaN(ms)) {
+            continue;
+        }
+        if (ms < oldestMs || (ms === oldestMs && oldestTs !== null && ts < oldestTs)) {
+            oldestMs = ms;
+            oldestTs = ts;
+        }
+        if (ms > newestMs || (ms === newestMs && newestTs !== null && ts > newestTs)) {
+            newestMs = ms;
+            newestTs = ts;
+        }
+    }
+    return { id, bytes, lines, oldest_ts: oldestTs, newest_ts: newestTs };
+}
+export function computeHistoryStorageStats(streams, options) {
+    const rawTopN = options?.topN ?? 5;
+    const topN = Math.max(0, Math.floor(rawTopN));
+    const stats = streams.map(({ id, raw }) => parseStreamStat(id, raw));
+    let totalLines = 0;
+    let totalBytes = 0;
+    let oldestEntry = null;
+    let newestEntry = null;
+    let globalOldestMs = Number.POSITIVE_INFINITY;
+    let globalNewestMs = Number.NEGATIVE_INFINITY;
+    for (const stat of stats) {
+        totalLines += stat.lines;
+        totalBytes += stat.bytes;
+        if (stat.oldest_ts !== null) {
+            const ms = Date.parse(stat.oldest_ts);
+            if (ms < globalOldestMs ||
+                (ms === globalOldestMs && oldestEntry !== null && stat.id < oldestEntry.id)) {
+                globalOldestMs = ms;
+                oldestEntry = { id: stat.id, ts: stat.oldest_ts };
+            }
+        }
+        if (stat.newest_ts !== null) {
+            const ms = Date.parse(stat.newest_ts);
+            if (ms > globalNewestMs ||
+                (ms === globalNewestMs && newestEntry !== null && stat.id < newestEntry.id)) {
+                globalNewestMs = ms;
+                newestEntry = { id: stat.id, ts: stat.newest_ts };
+            }
+        }
+    }
+    const largestByBytes = topN === 0
+        ? []
+        : [...stats]
+            .sort((a, b) => b.bytes - a.bytes || a.id.localeCompare(b.id))
+            .slice(0, topN);
+    const deepestByLines = topN === 0
+        ? []
+        : [...stats]
+            .sort((a, b) => b.lines - a.lines || a.id.localeCompare(b.id))
+            .slice(0, topN);
+    return {
+        total_streams: streams.length,
+        total_lines: totalLines,
+        total_bytes: totalBytes,
+        largest_by_bytes: largestByBytes,
+        deepest_by_lines: deepestByLines,
+        oldest_entry: oldestEntry,
+        newest_entry: newestEntry,
+    };
+}
+//# sourceMappingURL=history-storage-stats.js.map
+//# debugId=006b5d42-0ff6-57af-a598-4ca069ec316e

package/dist/core/history/history-storage-stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-storage-stats.js","sources":["core/history/history-storage-stats.ts"],"sourceRoot":"/","sourcesContent":["/**\n * Pure aggregate metrics for history streams (JSONL files).\n * No filesystem access — callers read raw stream contents and pass them in.\n * This module has no Node imports; Buffer is available as a global.\n */\n\nexport interface HistoryStreamStat {\n  id: string;\n  bytes: number;\n  lines: number; // non-empty JSONL entry count\n  oldest_ts: string | null; // min parseable ts in this stream, else null\n  newest_ts: string | null; // max parseable ts in this stream, else null\n}\n\nexport interface HistoryStorageEntryRef {\n  id: string;\n  ts: string;\n}\n\nexport interface HistoryStorageStats {\n  total_streams: number;\n  total_lines: number;\n  total_bytes: number;\n  largest_by_bytes: HistoryStreamStat[]; // top-N desc by bytes, tie-break id asc\n  deepest_by_lines: HistoryStreamStat[]; // top-N desc by lines, tie-break id asc\n  oldest_entry: HistoryStorageEntryRef | null; // global min ts across all streams\n  newest_entry: HistoryStorageEntryRef | null; // global max ts across all streams\n}\n\nfunction parseStreamStat(id: string, raw: string): HistoryStreamStat {\n  const bytes = Buffer.byteLength(raw, \"utf8\");\n\n  let lines = 0;\n  let oldestTs: string | null = null;\n  let newestTs: string | null = null;\n  let oldestMs = Number.POSITIVE_INFINITY;\n  let newestMs = Number.NEGATIVE_INFINITY;\n\n  for (const rawLine of raw.split(/\\r?\\n/)) {\n    const trimmed = rawLine.trim();\n    if (trimmed === \"\") {\n      continue;\n    }\n    lines += 1;\n\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(trimmed);\n    } catch {\n      continue;\n    }\n\n    if (\n      parsed === null ||\n      typeof parsed !== \"object\" ||\n      !(\"ts\" in (parsed as object)) ||\n      typeof (parsed as Record<string, unknown>)[\"ts\"] !== \"string\"\n    ) {\n      continue;\n    }\n\n    const ts = (parsed as Record<string, unknown>)[\"ts\"] as string;\n    const ms = Date.parse(ts);\n    if (Number.isNaN(ms)) {\n      continue;\n    }\n\n    if (ms < oldestMs || (ms === oldestMs && oldestTs !== null && ts < oldestTs)) {\n      oldestMs = ms;\n      oldestTs = ts;\n    }\n    if (ms > newestMs || (ms === newestMs && newestTs !== null && ts > newestTs)) {\n      newestMs = ms;\n      newestTs = ts;\n    }\n  }\n\n  return { id, bytes, lines, oldest_ts: oldestTs, newest_ts: newestTs };\n}\n\nexport function computeHistoryStorageStats(\n  streams: Array<{ id: string; raw: string }>,\n  options?: { topN?: number },\n): HistoryStorageStats {\n  const rawTopN = options?.topN ?? 5;\n  const topN = Math.max(0, Math.floor(rawTopN));\n\n  const stats: HistoryStreamStat[] = streams.map(({ id, raw }) => parseStreamStat(id, raw));\n\n  let totalLines = 0;\n  let totalBytes = 0;\n  let oldestEntry: HistoryStorageEntryRef | null = null;\n  let newestEntry: HistoryStorageEntryRef | null = null;\n  let globalOldestMs = Number.POSITIVE_INFINITY;\n  let globalNewestMs = Number.NEGATIVE_INFINITY;\n\n  for (const stat of stats) {\n    totalLines += stat.lines;\n    totalBytes += stat.bytes;\n\n    if (stat.oldest_ts !== null) {\n      const ms = Date.parse(stat.oldest_ts);\n      if (\n        ms < globalOldestMs ||\n        (ms === globalOldestMs && oldestEntry !== null && stat.id < oldestEntry.id)\n      ) {\n        globalOldestMs = ms;\n        oldestEntry = { id: stat.id, ts: stat.oldest_ts };\n      }\n    }\n\n    if (stat.newest_ts !== null) {\n      const ms = Date.parse(stat.newest_ts);\n      if (\n        ms > globalNewestMs ||\n        (ms === globalNewestMs && newestEntry !== null && stat.id < newestEntry.id)\n      ) {\n        globalNewestMs = ms;\n        newestEntry = { id: stat.id, ts: stat.newest_ts };\n      }\n    }\n  }\n\n  const largestByBytes =\n    topN === 0\n      ? []\n      : [...stats]\n          .sort((a, b) => b.bytes - a.bytes || a.id.localeCompare(b.id))\n          .slice(0, topN);\n\n  const deepestByLines =\n    topN === 0\n      ? []\n      : [...stats]\n          .sort((a, b) => b.lines - a.lines || a.id.localeCompare(b.id))\n          .slice(0, topN);\n\n  return {\n    total_streams: streams.length,\n    total_lines: totalLines,\n    total_bytes: totalBytes,\n    largest_by_bytes: largestByBytes,\n    deepest_by_lines: deepestByLines,\n    oldest_entry: oldestEntry,\n    newest_entry: newestEntry,\n  };\n}\n"],"names":[],"mappings":"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","debugId":"006b5d42-0ff6-57af-a598-4ca069ec316e"}

package/dist/core/item/item-format.d.ts

@@ -3,13 +3,14 @@ import type { ItemFormat } from "../../types/index.js";
 export interface ItemDocumentFormatOptions {
     format?: ItemFormat;
     schema?: RuntimeSchemaSettings;
+    extensionFieldNames?: readonly string[];
     onWarning?: (warning: string) => void;
 }
-export declare function normalizeFrontMatter(frontMatter: ItemMetadata, options?: Pick<ItemDocumentFormatOptions, "schema" | "onWarning">): ItemMetadata;
+export declare function normalizeFrontMatter(frontMatter: ItemMetadata, options?: Pick<ItemDocumentFormatOptions, "schema" | "extensionFieldNames" | "onWarning">): ItemMetadata;
 export declare function splitFrontMatter(content: string): {
     frontMatter: string;
     body: string;
 };
 export declare function parseItemDocument(content: string, options?: ItemDocumentFormatOptions): ItemDocument;
 export declare function serializeItemDocument(document: ItemDocument, options?: ItemDocumentFormatOptions): string;
-export declare function canonicalDocument(document: ItemDocument, options?: Pick<ItemDocumentFormatOptions, "schema" | "onWarning">): ItemDocument;
+export declare function canonicalDocument(document: ItemDocument, options?: Pick<ItemDocumentFormatOptions, "schema" | "extensionFieldNames" | "onWarning">): ItemDocument;

package/dist/core/item/item-format.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7ce34b61-0ca0-51e3-8969-50ee0dbe020b")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="375a5879-64b1-55a4-a83e-90ee50031713")}catch(e){}}();
 import { encode as encodeToon } from "@toon-format/toon";
 import { CONFIDENCE_TEXT_VALUES, ISSUE_SEVERITY_VALUES, RECURRENCE_FREQUENCY_VALUES, RECURRENCE_WEEKDAY_VALUES, STATUS_VALUES, weekdayOrderIndex, } from "../../types/index.js";
 import { coerceRuntimeFieldValue } from "../schema/runtime-field-values.js";
@@ -31,6 +31,7 @@ function resolveRuntimeSchemaValidationContext(options) {
         statusRegistry: resolveRuntimeStatusRegistry(options.schema),
         fieldRegistry: resolveRuntimeFieldRegistry(options.schema),
         unknownFieldPolicy: options.schema.unknown_field_policy ?? "allow",
+        extensionFieldNames: new Set(options.extensionFieldNames ?? []),
         onWarning: options.onWarning,
     };
 }
@@ -46,6 +47,16 @@ function runtimeFieldRequiredForType(definition, typeName) {
 function validationError(message) {
     throw new PmCliError(`Invalid item front matter: ${message}`, EXIT_CODE.GENERIC_FAILURE);
 }
+function buildKnownFrontMatterKeys(runtimeContext) {
+    const knownKeys = new Set(STATIC_FRONT_MATTER_FIELD_SET);
+    for (const definition of runtimeContext.fieldRegistry?.definitions ?? []) {
+        knownKeys.add(definition.metadata_key);
+    }
+    for (const fieldName of runtimeContext.extensionFieldNames) {
+        knownKeys.add(fieldName);
+    }
+    return knownKeys;
+}
 function assertFrontMatterCondition(condition, message) {
     if (!condition) {
         validationError(message);
@@ -235,10 +246,7 @@ function assertValidFrontMatter(frontMatter, runtimeContext) {
         }
     }
     if (runtimeContext && runtimeContext.unknownFieldPolicy !== "allow") {
-        const knownKeys = new Set(STATIC_FRONT_MATTER_FIELD_SET);
-        for (const definition of runtimeContext.fieldRegistry?.definitions ?? []) {
-            knownKeys.add(definition.metadata_key);
-        }
+        const knownKeys = buildKnownFrontMatterKeys(runtimeContext);
         const unknownKeys = Object.keys(record).filter((key) => !knownKeys.has(key)).sort((left, right) => left.localeCompare(right));
         if (unknownKeys.length > 0) {
             if (runtimeContext.unknownFieldPolicy === "reject") {
@@ -937,10 +945,7 @@ export function normalizeFrontMatter(frontMatter, options = {}) {
         }
     }
     if (runtimeContext && runtimeContext.unknownFieldPolicy !== "allow") {
-        const knownKeys = new Set(STATIC_FRONT_MATTER_FIELD_SET);
-        for (const definition of runtimeContext.fieldRegistry?.definitions ?? []) {
-            knownKeys.add(definition.metadata_key);
-        }
+        const knownKeys = buildKnownFrontMatterKeys(runtimeContext);
         const unknownKeys = Object.keys(normalized)
             .filter((key) => !knownKeys.has(key))
             .sort((left, right) => left.localeCompare(right));
@@ -1129,4 +1134,4 @@ export function canonicalDocument(document, options = {}) {
     };
 }
 //# sourceMappingURL=item-format.js.map
-//# debugId=7ce34b61-0ca0-51e3-8969-50ee0dbe020b
+//# debugId=375a5879-64b1-55a4-a83e-90ee50031713