npm - @unbrained/pm-cli - Versions diffs - 2026.6.19 → 2026.6.21 - Mend

@unbrained/pm-cli 2026.6.19 → 2026.6.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (545) hide show

package/dist/core/history/drift-scan.js CHANGED Viewed

@@ -4,7 +4,7 @@
  * Implements append-only history and replay behavior for Drift Scan.
  */
-!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]="8ca839bf-b395-5bbb-a3e4-6c20b5b58f5e")}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]="a928aad0-855f-5c7f-aa00-77d698ddca80")}catch(e){}}();
 import fs from "fs/promises";
 import { createHash } from "node:crypto";
 import path from "node:path";
@@ -12,7 +12,7 @@ import { getHistoryPath } from "../store/paths.js";
 import { writeFileAtomic } from "../fs/fs-utils.js";
 import { hashDocument } from "./history.js";
 import { verifyHistoryChain } from "./replay.js";
-const DRIFT_CACHE_VERSION = 2;
+const DRIFT_CACHE_VERSION = 3;
 const DRIFT_CACHE_FILENAME = "history-drift-cache.json";
 function getDriftCachePath(pmRoot) {
     return path.join(pmRoot, "runtime", DRIFT_CACHE_FILENAME);
@@ -79,13 +79,13 @@ async function verifyHistoryStream(historyPath) {
  * Scan every item's history stream for drift (missing/unreadable streams, broken
  * hash chains, and item/history hash mismatches).
  *
- * Full chain re-verification of a 17MB+ history tree is the dominant cost of
+ * Full chain re-verification of a large history tree is the dominant cost of
  * `pm health`. We cache the per-stream verification keyed by the history file's
- * mtime/ctime/size + content hash: metadata-stable replacements (same stat tuple)
- * can still happen, so each metadata hit recomputes a content hash guard before
- * trusting the cached chain/hash verification.
+ * mtime/ctime/size plus content hash. Strict callers keep recomputing the
+ * content hash on metadata hits; latency-sensitive health checks can opt into
+ * trusting the stat tuple and skip rereading unchanged streams.
  */
-export async function scanHistoryDrift(pmRoot, items) {
+export async function scanHistoryDrift(pmRoot, items, options = {}) {
     const missingStreams = [];
     const unreadableStreams = [];
     const hashMismatches = [];
@@ -94,6 +94,9 @@ export async function scanHistoryDrift(pmRoot, items) {
     const previousEntries = cache?.entries ?? {};
     const nextEntries = {};
     let cacheDirty = false;
+    // Metadata mode does not open a stat-matched stream, so unreadable-after-stat
+    // failures are intentionally deferred to strict validate/history-repair scans.
+    const verifyCacheHitByContent = options.cacheHitVerification !== "metadata";
     for (const item of items) {
         const historyPath = getHistoryPath(pmRoot, item.id);
         let stat;
@@ -139,14 +142,19 @@ export async function scanHistoryDrift(pmRoot, items) {
         const canUseCache = metadataMatchesCache && cachedContentHash !== undefined;
         if (canUseCache && cached) {
             let currentContentHash;
-            try {
-                currentContentHash = await readHistoryContentHash(historyPath);
+            if (verifyCacheHitByContent) {
+                try {
+                    currentContentHash = await readHistoryContentHash(historyPath);
+                }
+                catch {
+                    unreadableStreams.push(item.id);
+                    continue;
+                }
             }
-            catch {
-                unreadableStreams.push(item.id);
-                continue;
+            else {
+                currentContentHash = cachedContentHash;
             }
-            if (currentContentHash === cachedContentHash) {
+            if (!verifyCacheHitByContent || currentContentHash === cachedContentHash) {
                 verification = {
                     latestAfterHash: cached.latest_after_hash,
                     chainOk: cached.chain_ok,
@@ -204,4 +212,4 @@ export async function scanHistoryDrift(pmRoot, items) {
     return { missingStreams, unreadableStreams, hashMismatches, chainMismatches, driftedItems };
 }
 //# sourceMappingURL=drift-scan.js.map
-//# debugId=8ca839bf-b395-5bbb-a3e4-6c20b5b58f5e
+//# debugId=a928aad0-855f-5c7f-aa00-77d698ddca80

package/dist/core/history/drift-scan.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"drift-scan.js","sources":["core/history/drift-scan.ts"],"sourceRoot":"/","sourcesContent":["/*\n @module core/history/drift-scan\n \n Implements append-only history and replay behavior for Drift Scan.\n /\nimport fs from \"fs/promises\";\nimport { createHash } from \"node:crypto\";\nimport path from \"node:path\";\nimport { getHistoryPath } from \"../store/paths.js\";\nimport { writeFileAtomic } from \"../fs/fs-utils.js\";\nimport { hashDocument } from \"./history.js\";\nimport { verifyHistoryChain } from \"./replay.js\";\nimport type { HistoryEntry, ItemMetadata } from \"../../types/index.js\";\n\n/\n Documents the drift scan result payload exchanged by command, SDK, and package integrations.\n /\nexport interface DriftScanResult {\n missingStreams: string[];\n unreadableStreams: string[];\n hashMismatches: string[];\n chainMismatches: string[];\n driftedItems: string[];\n}\n\nconst DRIFT_CACHE_VERSION = 2;\nconst DRIFT_CACHE_FILENAME = \"history-drift-cache.json\";\n\ninterface DriftCacheEntry {\n mtime_ms: number;\n ctime_ms: number;\n size: number;\n content_hash: string;\n latest_after_hash: string;\n chain_ok: boolean;\n}\n\ninterface DriftCacheEnvelope {\n version: number;\n entries: Record<string, DriftCacheEntry>;\n}\n\nfunction getDriftCachePath(pmRoot: string): string {\n return path.join(pmRoot, \"runtime\", DRIFT_CACHE_FILENAME);\n}\n\nasync function loadDriftCache(pmRoot: string): Promise<DriftCacheEnvelope \| null> {\n try {\n const raw = await fs.readFile(getDriftCachePath(pmRoot), \"utf8\");\n const parsed = JSON.parse(raw) as DriftCacheEnvelope;\n if (parsed.version !== DRIFT_CACHE_VERSION \|\| typeof parsed.entries !== \"object\" \|\| parsed.entries === null) {\n return null;\n }\n return parsed;\n } catch {\n return null;\n }\n}\n\nfunction isErrno(error: unknown, code: string): boolean {\n return typeof error === \"object\" && error !== null && \"code\" in error && (error as { code?: string }).code === code;\n}\n\ninterface StreamVerification {\n latestAfterHash: string;\n chainOk: boolean;\n contentHash: string;\n}\n\nfunction hashContent(raw: string): string {\n return createHash(\"sha256\").update(raw).digest(\"hex\");\n}\n\nasync function readHistoryContentHash(historyPath: string): Promise<string> {\n const raw = await fs.readFile(historyPath, \"utf8\");\n return hashContent(raw);\n}\n\n/\n Read and fully verify one history stream's hash chain. Returns null for an\n * empty/missing stream (caller records it as a missing stream).\n /\nasync function verifyHistoryStream(historyPath: string): Promise<StreamVerification \| null> {\n const raw = await fs.readFile(historyPath, \"utf8\");\n const contentHash = hashContent(raw);\n if (raw.trim().length === 0) {\n return null;\n }\n const entries: HistoryEntry[] = [];\n let latestAfterHash: string \| null = null;\n for (const line of raw.split(/\\r?\\n/)) {\n const trimmed = line.trim();\n if (trimmed.length === 0) {\n continue;\n }\n const parsed = JSON.parse(trimmed) as HistoryEntry;\n if (typeof parsed.after_hash !== \"string\" \|\| parsed.after_hash.trim().length === 0) {\n throw new Error(\"missing after_hash\");\n }\n entries.push(parsed);\n latestAfterHash = parsed.after_hash;\n }\n / c8 ignore start -- defensive guard for future history schema changes. /\n if (!latestAfterHash) {\n return null;\n }\n / c8 ignore stop /\n return {\n latestAfterHash,\n chainOk: verifyHistoryChain(entries).ok,\n contentHash,\n };\n}\n\n/\n Scan every item's history stream for drift (missing/unreadable streams, broken\n * hash chains, and item/history hash mismatches).\n \n Full chain re-verification of a 17MB+ history tree is the dominant cost of\n * `pm health`. We cache the per-stream verification keyed by the history file's\n * mtime/ctime/size + content hash: metadata-stable replacements (same stat tuple)\n * can still happen, so each metadata hit recomputes a content hash guard before\n * trusting the cached chain/hash verification.\n */\nexport async function scanHistoryDrift(\n pmRoot: string,\n items: Array<ItemMetadata & { body: string }>,\n): Promise<DriftScanResult> {\n const missingStreams: string[] = [];\n const unreadableStreams: string[] = [];\n const hashMismatches: string[] = [];\n const chainMismatches: string[] = [];\n\n const cache = await loadDriftCache(pmRoot);\n const previousEntries: Record<string, DriftCacheEntry> = cache?.entries ?? {};\n const nextEntries: Record<string, DriftCacheEntry> = {};\n let cacheDirty = false;\n\n for (const item of items) {\n const historyPath = getHistoryPath(pmRoot, item.id);\n\n let stat: Awaited<ReturnType<typeof fs.stat>>;\n try {\n stat = await fs.stat(historyPath);\n } catch (error: unknown) {\n if (isErrno(error, \"ENOENT\")) {\n missingStreams.push(item.id);\n } else {\n unreadableStreams.push(item.id);\n }\n continue;\n }\n\n const loadStreamVerification = async (): Promise<StreamVerification \| null \| \"unreadable\"> => {\n try {\n return await verifyHistoryStream(historyPath);\n } catch {\n return \"unreadable\";\n }\n };\n\n const loadFreshVerification = async (): Promise<StreamVerification \| null> => {\n const loaded = await loadStreamVerification();\n if (loaded === \"unreadable\") {\n unreadableStreams.push(item.id);\n return null;\n }\n if (!loaded) {\n missingStreams.push(item.id);\n return null;\n }\n return loaded;\n };\n\n const cached = previousEntries[item.id];\n let verification: StreamVerification;\n const metadataMatchesCache =\n cached !== undefined &&\n cached.mtime_ms === stat.mtimeMs &&\n cached.ctime_ms === stat.ctimeMs &&\n cached.size === stat.size;\n const cachedContentHash =\n typeof cached?.content_hash === \"string\" && cached.content_hash.length > 0 ? cached.content_hash : undefined;\n const canUseCache = metadataMatchesCache && cachedContentHash !== undefined;\n if (canUseCache && cached) {\n let currentContentHash: string;\n try {\n currentContentHash = await readHistoryContentHash(historyPath);\n } catch {\n unreadableStreams.push(item.id);\n continue;\n }\n if (currentContentHash === cachedContentHash) {\n verification = {\n latestAfterHash: cached.latest_after_hash,\n chainOk: cached.chain_ok,\n contentHash: currentContentHash,\n };\n } else {\n cacheDirty = true;\n const refreshed = await loadFreshVerification();\n if (!refreshed) {\n continue;\n }\n verification = refreshed;\n }\n } else {\n cacheDirty = true;\n const refreshed = await loadFreshVerification();\n if (!refreshed) {\n continue;\n }\n verification = refreshed;\n }\n\n if (!verification.chainOk) {\n chainMismatches.push(item.id);\n }\n nextEntries[item.id] = {\n mtime_ms: stat.mtimeMs,\n ctime_ms: stat.ctimeMs,\n size: stat.size,\n content_hash: verification.contentHash,\n latest_after_hash: verification.latestAfterHash,\n chain_ok: verification.chainOk,\n };\n\n const { body, ...frontMatter } = item;\n const currentHash = hashDocument({\n metadata: frontMatter as ItemMetadata,\n body,\n });\n if (currentHash !== verification.latestAfterHash) {\n hashMismatches.push(item.id);\n }\n }\n\n if (cacheDirty \|\| Object.keys(previousEntries).length !== Object.keys(nextEntries).length) {\n const cachePath = getDriftCachePath(pmRoot);\n try {\n await fs.mkdir(path.dirname(cachePath), { recursive: true });\n await writeFileAtomic(cachePath, JSON.stringify({ version: DRIFT_CACHE_VERSION, entries: nextEntries }));\n } catch {\n // Best-effort cache write: a failed persist must never fail a health scan.\n }\n }\n\n const driftedItems = [...new Set([...missingStreams, ...unreadableStreams, ...hashMismatches, ...chainMismatches])].sort((a, b) =>\n a.localeCompare(b),\n );\n return { missingStreams, unreadableStreams, hashMismatches, chainMismatches, driftedItems };\n}\n"],"names":[],"mappings":"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","debugId":"8ca839bf-b395-5bbb-a3e4-6c20b5b58f5e"}
1	+ {"version":3,"file":"drift-scan.js","sources":["core/history/drift-scan.ts"],"sourceRoot":"/","sourcesContent":["/*\n @module core/history/drift-scan\n \n Implements append-only history and replay behavior for Drift Scan.\n /\nimport fs from \"fs/promises\";\nimport { createHash } from \"node:crypto\";\nimport path from \"node:path\";\nimport { getHistoryPath } from \"../store/paths.js\";\nimport { writeFileAtomic } from \"../fs/fs-utils.js\";\nimport { hashDocument } from \"./history.js\";\nimport { verifyHistoryChain } from \"./replay.js\";\nimport type { HistoryEntry, ItemMetadata } from \"../../types/index.js\";\n\n/\n Documents the drift scan result payload exchanged by command, SDK, and package integrations.\n /\nexport interface DriftScanResult {\n missingStreams: string[];\n unreadableStreams: string[];\n hashMismatches: string[];\n chainMismatches: string[];\n driftedItems: string[];\n}\n\nconst DRIFT_CACHE_VERSION = 3;\nconst DRIFT_CACHE_FILENAME = \"history-drift-cache.json\";\n\n/\n Controls how cached history stream verification is trusted when the file stat\n * tuple still matches a previous scan.\n /\nexport type DriftCacheHitVerification = \"content_hash\" \| \"metadata\";\n\n/\n Documents the history drift scan options shared by health, validate, and\n * repair callers.\n /\nexport interface DriftScanOptions {\n cacheHitVerification?: DriftCacheHitVerification;\n}\n\ninterface DriftCacheEntry {\n mtime_ms: number;\n ctime_ms: number;\n size: number;\n content_hash: string;\n latest_after_hash: string;\n chain_ok: boolean;\n}\n\ninterface DriftCacheEnvelope {\n version: number;\n entries: Record<string, DriftCacheEntry>;\n}\n\nfunction getDriftCachePath(pmRoot: string): string {\n return path.join(pmRoot, \"runtime\", DRIFT_CACHE_FILENAME);\n}\n\nasync function loadDriftCache(pmRoot: string): Promise<DriftCacheEnvelope \| null> {\n try {\n const raw = await fs.readFile(getDriftCachePath(pmRoot), \"utf8\");\n const parsed = JSON.parse(raw) as DriftCacheEnvelope;\n if (parsed.version !== DRIFT_CACHE_VERSION \|\| typeof parsed.entries !== \"object\" \|\| parsed.entries === null) {\n return null;\n }\n return parsed;\n } catch {\n return null;\n }\n}\n\nfunction isErrno(error: unknown, code: string): boolean {\n return typeof error === \"object\" && error !== null && \"code\" in error && (error as { code?: string }).code === code;\n}\n\ninterface StreamVerification {\n latestAfterHash: string;\n chainOk: boolean;\n contentHash: string;\n}\n\nfunction hashContent(raw: string): string {\n return createHash(\"sha256\").update(raw).digest(\"hex\");\n}\n\nasync function readHistoryContentHash(historyPath: string): Promise<string> {\n const raw = await fs.readFile(historyPath, \"utf8\");\n return hashContent(raw);\n}\n\n/\n Read and fully verify one history stream's hash chain. Returns null for an\n * empty/missing stream (caller records it as a missing stream).\n /\nasync function verifyHistoryStream(historyPath: string): Promise<StreamVerification \| null> {\n const raw = await fs.readFile(historyPath, \"utf8\");\n const contentHash = hashContent(raw);\n if (raw.trim().length === 0) {\n return null;\n }\n const entries: HistoryEntry[] = [];\n let latestAfterHash: string \| null = null;\n for (const line of raw.split(/\\r?\\n/)) {\n const trimmed = line.trim();\n if (trimmed.length === 0) {\n continue;\n }\n const parsed = JSON.parse(trimmed) as HistoryEntry;\n if (typeof parsed.after_hash !== \"string\" \|\| parsed.after_hash.trim().length === 0) {\n throw new Error(\"missing after_hash\");\n }\n entries.push(parsed);\n latestAfterHash = parsed.after_hash;\n }\n / c8 ignore start -- defensive guard for future history schema changes. /\n if (!latestAfterHash) {\n return null;\n }\n / c8 ignore stop /\n return {\n latestAfterHash,\n chainOk: verifyHistoryChain(entries).ok,\n contentHash,\n };\n}\n\n/\n Scan every item's history stream for drift (missing/unreadable streams, broken\n * hash chains, and item/history hash mismatches).\n \n Full chain re-verification of a large history tree is the dominant cost of\n * `pm health`. We cache the per-stream verification keyed by the history file's\n * mtime/ctime/size plus content hash. Strict callers keep recomputing the\n * content hash on metadata hits; latency-sensitive health checks can opt into\n * trusting the stat tuple and skip rereading unchanged streams.\n */\nexport async function scanHistoryDrift(\n pmRoot: string,\n items: Array<ItemMetadata & { body: string }>,\n options: DriftScanOptions = {},\n): Promise<DriftScanResult> {\n const missingStreams: string[] = [];\n const unreadableStreams: string[] = [];\n const hashMismatches: string[] = [];\n const chainMismatches: string[] = [];\n\n const cache = await loadDriftCache(pmRoot);\n const previousEntries: Record<string, DriftCacheEntry> = cache?.entries ?? {};\n const nextEntries: Record<string, DriftCacheEntry> = {};\n let cacheDirty = false;\n // Metadata mode does not open a stat-matched stream, so unreadable-after-stat\n // failures are intentionally deferred to strict validate/history-repair scans.\n const verifyCacheHitByContent = options.cacheHitVerification !== \"metadata\";\n\n for (const item of items) {\n const historyPath = getHistoryPath(pmRoot, item.id);\n\n let stat: Awaited<ReturnType<typeof fs.stat>>;\n try {\n stat = await fs.stat(historyPath);\n } catch (error: unknown) {\n if (isErrno(error, \"ENOENT\")) {\n missingStreams.push(item.id);\n } else {\n unreadableStreams.push(item.id);\n }\n continue;\n }\n\n const loadStreamVerification = async (): Promise<StreamVerification \| null \| \"unreadable\"> => {\n try {\n return await verifyHistoryStream(historyPath);\n } catch {\n return \"unreadable\";\n }\n };\n\n const loadFreshVerification = async (): Promise<StreamVerification \| null> => {\n const loaded = await loadStreamVerification();\n if (loaded === \"unreadable\") {\n unreadableStreams.push(item.id);\n return null;\n }\n if (!loaded) {\n missingStreams.push(item.id);\n return null;\n }\n return loaded;\n };\n\n const cached = previousEntries[item.id];\n let verification: StreamVerification;\n const metadataMatchesCache =\n cached !== undefined &&\n cached.mtime_ms === stat.mtimeMs &&\n cached.ctime_ms === stat.ctimeMs &&\n cached.size === stat.size;\n const cachedContentHash =\n typeof cached?.content_hash === \"string\" && cached.content_hash.length > 0 ? cached.content_hash : undefined;\n const canUseCache = metadataMatchesCache && cachedContentHash !== undefined;\n if (canUseCache && cached) {\n let currentContentHash: string;\n if (verifyCacheHitByContent) {\n try {\n currentContentHash = await readHistoryContentHash(historyPath);\n } catch {\n unreadableStreams.push(item.id);\n continue;\n }\n } else {\n currentContentHash = cachedContentHash;\n }\n if (!verifyCacheHitByContent \|\| currentContentHash === cachedContentHash) {\n verification = {\n latestAfterHash: cached.latest_after_hash,\n chainOk: cached.chain_ok,\n contentHash: currentContentHash,\n };\n } else {\n cacheDirty = true;\n const refreshed = await loadFreshVerification();\n if (!refreshed) {\n continue;\n }\n verification = refreshed;\n }\n } else {\n cacheDirty = true;\n const refreshed = await loadFreshVerification();\n if (!refreshed) {\n continue;\n }\n verification = refreshed;\n }\n\n if (!verification.chainOk) {\n chainMismatches.push(item.id);\n }\n nextEntries[item.id] = {\n mtime_ms: stat.mtimeMs,\n ctime_ms: stat.ctimeMs,\n size: stat.size,\n content_hash: verification.contentHash,\n latest_after_hash: verification.latestAfterHash,\n chain_ok: verification.chainOk,\n };\n\n const { body, ...frontMatter } = item;\n const currentHash = hashDocument({\n metadata: frontMatter as ItemMetadata,\n body,\n });\n if (currentHash !== verification.latestAfterHash) {\n hashMismatches.push(item.id);\n }\n }\n\n if (cacheDirty \|\| Object.keys(previousEntries).length !== Object.keys(nextEntries).length) {\n const cachePath = getDriftCachePath(pmRoot);\n try {\n await fs.mkdir(path.dirname(cachePath), { recursive: true });\n await writeFileAtomic(cachePath, JSON.stringify({ version: DRIFT_CACHE_VERSION, entries: nextEntries }));\n } catch {\n // Best-effort cache write: a failed persist must never fail a health scan.\n }\n }\n\n const driftedItems = [...new Set([...missingStreams, ...unreadableStreams, ...hashMismatches, ...chainMismatches])].sort((a, b) =>\n a.localeCompare(b),\n );\n return { missingStreams, unreadableStreams, hashMismatches, chainMismatches, driftedItems };\n}\n"],"names":[],"mappings":"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","debugId":"a928aad0-855f-5c7f-aa00-77d698ddca80"}

package/dist/core/history/replay.d.ts CHANGED Viewed

@@ -1,3 +1,4 @@
+import { canonicalDocument } from "../item/item-format.js";
 import type { HistoryEntry, HistoryPatchOp, ItemDocument } from "../../types/index.js";
 /**
  * Shared history replay/patch mechanics single-sourced for the history, restore,
@@ -24,6 +25,12 @@ export declare function replayHash(document: ReplayDocument): string;
  * Implements replay to item document for the public runtime surface of this module.
  */
 export declare function replayToItemDocument(document: ReplayDocument): ItemDocument;
+/**
+ * Converts a materialized replay document into a canonical item document. Use
+ * this when callers have already rejected the empty/deleted replay state and
+ * need restored metadata validated through the normal front-matter rules.
+ */
+export declare function replayToCanonicalItemDocument(document: ReplayDocument, options?: Parameters<typeof canonicalDocument>[1]): ItemDocument;
 /**
  * Canonicalize an item document into the ordered replay form used when comparing
  * a replayed chain against the on-disk item (restore + history-repair reconciliation).

package/dist/core/history/replay.js CHANGED Viewed

@@ -4,7 +4,7 @@
  * Implements append-only history and replay behavior for Replay.
  */
-!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]="33ca44a2-2bb0-5ce8-8e1f-2c17e0c4e500")}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]="cf6461d3-7d73-5aa9-afa3-65f14d708e4c")}catch(e){}}();
 import jsonPatch from "fast-json-patch";
 import { FRONT_MATTER_KEY_ORDER } from "../shared/constants.js";
 import { canonicalDocument } from "../item/item-format.js";
@@ -26,10 +26,7 @@ export function cloneEmptyReplayDocument() {
  */
 export function replayHash(document) {
     try {
-        return hashDocument({
-            metadata: document.metadata,
-            body: document.body,
-        });
+        return hashDocument(replayToItemDocument(document));
     }
     catch {
         // Legacy/malformed replay states (for example a stream whose first entry never
@@ -50,6 +47,14 @@ export function replayToItemDocument(document) {
         body: document.body,
     };
 }
+/**
+ * Converts a materialized replay document into a canonical item document. Use
+ * this when callers have already rejected the empty/deleted replay state and
+ * need restored metadata validated through the normal front-matter rules.
+ */
+export function replayToCanonicalItemDocument(document, options = {}) {
+    return canonicalDocument(replayToItemDocument(document), options);
+}
 /**
  * Canonicalize an item document into the ordered replay form used when comparing
  * a replayed chain against the on-disk item (restore + history-repair reconciliation).
@@ -279,4 +284,4 @@ export function historyEntriesToRaw(entries) {
     return `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
 }
 //# sourceMappingURL=replay.js.map
-//# debugId=33ca44a2-2bb0-5ce8-8e1f-2c17e0c4e500
+//# debugId=cf6461d3-7d73-5aa9-afa3-65f14d708e4c

package/dist/core/history/replay.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"replay.js","sources":["core/history/replay.ts"],"sourceRoot":"/","sourcesContent":["/*\n @module core/history/replay\n \n Implements append-only history and replay behavior for Replay.\n /\nimport jsonPatch from \"fast-json-patch\";\nimport { FRONT_MATTER_KEY_ORDER } from \"../shared/constants.js\";\nimport { canonicalDocument } from \"../item/item-format.js\";\nimport { toItemRecord } from \"../item/item-record.js\";\nimport { orderObject, sha256Hex, stableStringify } from \"../shared/serialization.js\";\nimport { hashDocument } from \"./history.js\";\nimport type { HistoryEntry, HistoryPatchOp, ItemDocument, ItemMetadata } from \"../../types/index.js\";\n\n/\n Shared history replay/patch mechanics single-sourced for the history, restore,\n * history-redact, and history-repair commands plus the health/validate drift checks.\n \n Each command keeps its own thin error-formatting wrapper so the exact CLI error\n * contracts (restore's rich patch-failure context, redact's op tag, history's\n * generic message) are preserved; only the underlying replay/patch logic is shared.\n /\n\nexport interface ReplayDocument {\n metadata: Record<string, unknown>;\n body: string;\n}\n\nexport const EMPTY_REPLAY_DOCUMENT: ReplayDocument = {\n metadata: {},\n body: \"\",\n};\n\n/\n Implements clone empty replay document for the public runtime surface of this module.\n /\nexport function cloneEmptyReplayDocument(): ReplayDocument {\n return structuredClone(EMPTY_REPLAY_DOCUMENT);\n}\n\n/\n Implements replay hash for the public runtime surface of this module.\n /\nexport function replayHash(document: ReplayDocument): string {\n try {\n return hashDocument({\n metadata: document.metadata as unknown as ItemMetadata,\n body: document.body,\n });\n } catch {\n // Legacy/malformed replay states (for example a stream whose first entry never\n // established a full `create` document, so the canonicalizer cannot normalize it)\n // cannot be canonically hashed. Fall back to a deterministic structural hash so\n // re-anchor and verification stay internally consistent for these streams. Fully\n // formed documents always take the canonical path above, so valid streams are\n // unaffected.\n return sha256Hex(stableStringify({ replay_fallback: true, metadata: document.metadata, body: document.body }));\n }\n}\n\n/\n Implements replay to item document for the public runtime surface of this module.\n /\nexport function replayToItemDocument(document: ReplayDocument): ItemDocument {\n return {\n metadata: document.metadata as unknown as ItemMetadata,\n body: document.body,\n };\n}\n\n/\n Canonicalize an item document into the ordered replay form used when comparing\n * a replayed chain against the on-disk item (restore + history-repair reconciliation).\n /\nexport function toReplayDocument(document: ItemDocument): ReplayDocument {\n if (!document.metadata \|\| Object.keys(document.metadata).length === 0) {\n return {\n metadata: {},\n body: document.body ?? \"\",\n };\n }\n const canonical = canonicalDocument(document);\n return {\n metadata: orderObject(toItemRecord(canonical.metadata), FRONT_MATTER_KEY_ORDER),\n body: canonical.body,\n };\n}\n\n/\n Implements normalize replay patch path for the public runtime surface of this module.\n /\nexport function normalizeReplayPatchPath(path: string): string {\n if (path === \"/front_matter\") {\n return \"/metadata\";\n }\n if (path.startsWith(\"/front_matter/\")) {\n return `/metadata/${path.slice(\"/front_matter/\".length)}`;\n }\n return path;\n}\n\nfunction isHistoryPatchOp(value: unknown): value is HistoryPatchOp {\n return (\n typeof value === \"object\" &&\n value !== null &&\n typeof (value as { op?: unknown }).op === \"string\" &&\n typeof (value as { path?: unknown }).path === \"string\"\n );\n}\n\n/\n Implements normalize replay patch ops for the public runtime surface of this module.\n /\nexport function normalizeReplayPatchOps(patch: HistoryPatchOp[] \| unknown): HistoryPatchOp[] {\n if (!Array.isArray(patch)) {\n return [];\n }\n return patch.filter(isHistoryPatchOp).map((operation) => ({\n ...operation,\n path: normalizeReplayPatchPath(operation.path),\n from: typeof operation.from === \"string\" ? normalizeReplayPatchPath(operation.from) : undefined,\n }));\n}\n\nfunction isReplayDocumentShape(value: unknown): value is { metadata: Record<string, unknown>; body: string } {\n return (\n typeof value === \"object\" &&\n value !== null &&\n \"metadata\" in value &&\n \"body\" in value &&\n typeof (value as { body: unknown }).body === \"string\" &&\n typeof (value as { metadata: unknown }).metadata === \"object\" &&\n (value as { metadata: unknown }).metadata !== null\n );\n}\n\n/\n Restricts replay apply result values accepted by command, SDK, and storage contracts.\n /\nexport type ReplayApplyResult =\n \| { ok: true; document: ReplayDocument }\n \| { ok: false; error: unknown };\n\n/\n Strictly apply a history patch (front_matter->metadata normalized) to a replay\n * document. Returns a result envelope rather than throwing so each caller can\n * format its own error contract.\n /\nexport function tryApplyReplayPatch(current: ReplayDocument, patch: HistoryPatchOp[]): ReplayApplyResult {\n try {\n const normalizedPatch = normalizeReplayPatchOps(patch);\n const applied = jsonPatch.applyPatch(\n structuredClone(current),\n normalizedPatch as jsonPatch.Operation[],\n true,\n false,\n ).newDocument as unknown;\n if (!isReplayDocumentShape(applied)) {\n return { ok: false, error: new Error(\"history_replay_invalid_document_shape\") };\n }\n return { ok: true, document: { metadata: applied.metadata, body: applied.body } };\n } catch (error) {\n return { ok: false, error };\n }\n}\n\n/\n Deterministically verify a history chain: each entry's before_hash must equal\n * the prior replayed after_hash, the patch must strictly apply, and the recorded\n * after_hash must equal the replayed result.\n /\nexport function verifyHistoryChain(entries: HistoryEntry[]): { ok: boolean; errors: string[] } {\n let replay = cloneEmptyReplayDocument();\n for (let index = 0; index < entries.length; index += 1) {\n const entry = entries[index];\n if (replayHash(replay) !== entry.before_hash) {\n return {\n ok: false,\n errors: [`verify_failed:before_hash_mismatch:entry_${index + 1}`],\n };\n }\n const applied = tryApplyReplayPatch(replay, entry.patch);\n if (!applied.ok) {\n return {\n ok: false,\n errors: [`verify_failed:patch_apply_failed:entry_${index + 1}`],\n };\n }\n replay = applied.document;\n if (replayHash(replay) !== entry.after_hash) {\n return {\n ok: false,\n errors: [`verify_failed:after_hash_mismatch:entry_${index + 1}`],\n };\n }\n }\n return { ok: true, errors: [] };\n}\n\n/\n Documents the lenient apply result payload exchanged by command, SDK, and package integrations.\n /\nexport interface LenientApplyResult {\n document: ReplayDocument;\n convertedReplaceToAdd: number;\n skippedOps: number;\n}\n\nfunction tryApplySingleOp(document: unknown, op: HistoryPatchOp): { ok: true; document: unknown } \| { ok: false } {\n try {\n const applied = jsonPatch.applyPatch(\n structuredClone(document),\n [op as jsonPatch.Operation],\n true,\n false,\n ).newDocument as unknown;\n return { ok: true, document: applied };\n } catch {\n return { ok: false };\n }\n}\n\n/\n Apply a legacy patch op-by-op, recovering from drift that strict replay rejects:\n * a `replace` whose path no longer exists is retried as `add`, and any op that\n * still cannot apply against the current replay state is skipped. The resulting\n * document is what the repaired entry's recomputed patch should target.\n /\nexport function lenientApplyReplayPatch(current: ReplayDocument, patch: HistoryPatchOp[]): LenientApplyResult {\n let working: unknown = structuredClone(current);\n let convertedReplaceToAdd = 0;\n let skippedOps = 0;\n\n for (const op of normalizeReplayPatchOps(patch)) {\n const direct = tryApplySingleOp(working, op);\n if (direct.ok) {\n working = direct.document;\n continue;\n }\n if (op.op === \"replace\") {\n const asAdd = tryApplySingleOp(working, { ...op, op: \"add\" });\n if (asAdd.ok) {\n working = asAdd.document;\n convertedReplaceToAdd += 1;\n continue;\n }\n }\n skippedOps += 1;\n }\n\n const candidate = working as { metadata?: unknown; body?: unknown };\n const document: ReplayDocument = {\n metadata:\n typeof candidate.metadata === \"object\" && candidate.metadata !== null\n ? (candidate.metadata as Record<string, unknown>)\n : {},\n body: typeof candidate.body === \"string\" ? candidate.body : current.body,\n };\n return { document, convertedReplaceToAdd, skippedOps };\n}\n\n/\n Documents the reanchor entry detail payload exchanged by command, SDK, and package integrations.\n /\nexport interface ReanchorEntryDetail {\n index: number;\n rehashed: boolean;\n patch_repaired: boolean;\n converted_replace_to_add: number;\n skipped_ops: number;\n}\n\n/\n Documents the reanchor result payload exchanged by command, SDK, and package integrations.\n /\nexport interface ReanchorResult {\n entries: HistoryEntry[];\n finalDocument: ReplayDocument;\n entriesRehashed: number;\n entriesPatchRepaired: number;\n convertedReplaceToAdd: number;\n skippedOps: number;\n details: ReanchorEntryDetail[];\n}\n\n/\n Re-anchor a drifted history chain: replay every entry from empty, recompute the\n * before/after hashes, and only rewrite a patch when the original op set no longer\n * strictly applies (legacy drift). Clean entries keep their patch verbatim so the\n * on-disk diff stays minimal. The returned chain verifies via verifyHistoryChain.\n /\nexport function reanchorHistoryEntries(entries: HistoryEntry[]): ReanchorResult {\n let replay = cloneEmptyReplayDocument();\n const rewritten: HistoryEntry[] = [];\n const details: ReanchorEntryDetail[] = [];\n let entriesRehashed = 0;\n let entriesPatchRepaired = 0;\n let convertedReplaceToAdd = 0;\n let skippedOps = 0;\n\n for (let index = 0; index < entries.length; index += 1) {\n const entry = entries[index];\n const beforeHash = replayHash(replay);\n const strict = tryApplyReplayPatch(replay, entry.patch);\n\n let next: ReplayDocument;\n let outPatch: HistoryPatchOp[];\n let patchRepaired = false;\n let entryConverted = 0;\n let entrySkipped = 0;\n\n if (strict.ok) {\n next = strict.document;\n outPatch = entry.patch;\n } else {\n const lenient = lenientApplyReplayPatch(replay, entry.patch);\n next = lenient.document;\n outPatch = jsonPatch.compare(replay, next) as HistoryPatchOp[];\n patchRepaired = true;\n entryConverted = lenient.convertedReplaceToAdd;\n entrySkipped = lenient.skippedOps;\n convertedReplaceToAdd += entryConverted;\n skippedOps += entrySkipped;\n entriesPatchRepaired += 1;\n }\n\n const afterHash = replayHash(next);\n const rehashed = beforeHash !== entry.before_hash \|\| afterHash !== entry.after_hash;\n if (rehashed) {\n entriesRehashed += 1;\n }\n\n rewritten.push({\n ...entry,\n patch: outPatch,\n before_hash: beforeHash,\n after_hash: afterHash,\n });\n details.push({\n index: index + 1,\n rehashed,\n patch_repaired: patchRepaired,\n converted_replace_to_add: entryConverted,\n skipped_ops: entrySkipped,\n });\n replay = next;\n }\n\n return {\n entries: rewritten,\n finalDocument: replay,\n entriesRehashed,\n entriesPatchRepaired,\n convertedReplaceToAdd,\n skippedOps,\n details,\n };\n}\n\n/\n Implements history entries to raw for the public runtime surface of this module.\n */\nexport function historyEntriesToRaw(entries: HistoryEntry[]): string {\n if (entries.length === 0) {\n return \"\";\n }\n return `${entries.map((entry) => JSON.stringify(entry)).join(\"\\n\")}\\n`;\n}\n"],"names":[],"mappings":"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","debugId":"33ca44a2-2bb0-5ce8-8e1f-2c17e0c4e500"}
1	+ {"version":3,"file":"replay.js","sources":["core/history/replay.ts"],"sourceRoot":"/","sourcesContent":["/*\n @module core/history/replay\n \n Implements append-only history and replay behavior for Replay.\n /\nimport jsonPatch from \"fast-json-patch\";\nimport { FRONT_MATTER_KEY_ORDER } from \"../shared/constants.js\";\nimport { canonicalDocument } from \"../item/item-format.js\";\nimport { toItemRecord } from \"../item/item-record.js\";\nimport { orderObject, sha256Hex, stableStringify } from \"../shared/serialization.js\";\nimport { hashDocument } from \"./history.js\";\nimport type { HistoryEntry, HistoryPatchOp, ItemDocument, ItemMetadata } from \"../../types/index.js\";\n\n/\n Shared history replay/patch mechanics single-sourced for the history, restore,\n * history-redact, and history-repair commands plus the health/validate drift checks.\n \n Each command keeps its own thin error-formatting wrapper so the exact CLI error\n * contracts (restore's rich patch-failure context, redact's op tag, history's\n * generic message) are preserved; only the underlying replay/patch logic is shared.\n /\n\nexport interface ReplayDocument {\n metadata: Record<string, unknown>;\n body: string;\n}\n\nexport const EMPTY_REPLAY_DOCUMENT: ReplayDocument = {\n metadata: {},\n body: \"\",\n};\n\n/\n Implements clone empty replay document for the public runtime surface of this module.\n /\nexport function cloneEmptyReplayDocument(): ReplayDocument {\n return structuredClone(EMPTY_REPLAY_DOCUMENT);\n}\n\n/\n Implements replay hash for the public runtime surface of this module.\n /\nexport function replayHash(document: ReplayDocument): string {\n try {\n return hashDocument(replayToItemDocument(document));\n } catch {\n // Legacy/malformed replay states (for example a stream whose first entry never\n // established a full `create` document, so the canonicalizer cannot normalize it)\n // cannot be canonically hashed. Fall back to a deterministic structural hash so\n // re-anchor and verification stay internally consistent for these streams. Fully\n // formed documents always take the canonical path above, so valid streams are\n // unaffected.\n return sha256Hex(stableStringify({ replay_fallback: true, metadata: document.metadata, body: document.body }));\n }\n}\n\n/\n Implements replay to item document for the public runtime surface of this module.\n /\nexport function replayToItemDocument(document: ReplayDocument): ItemDocument {\n return {\n metadata: document.metadata as ItemMetadata,\n body: document.body,\n };\n}\n\n/\n Converts a materialized replay document into a canonical item document. Use\n * this when callers have already rejected the empty/deleted replay state and\n * need restored metadata validated through the normal front-matter rules.\n /\nexport function replayToCanonicalItemDocument(\n document: ReplayDocument,\n options: Parameters<typeof canonicalDocument>[1] = {},\n): ItemDocument {\n return canonicalDocument(replayToItemDocument(document), options);\n}\n\n/\n Canonicalize an item document into the ordered replay form used when comparing\n * a replayed chain against the on-disk item (restore + history-repair reconciliation).\n /\nexport function toReplayDocument(document: ItemDocument): ReplayDocument {\n if (!document.metadata \|\| Object.keys(document.metadata).length === 0) {\n return {\n metadata: {},\n body: document.body ?? \"\",\n };\n }\n const canonical = canonicalDocument(document);\n return {\n metadata: orderObject(toItemRecord(canonical.metadata), FRONT_MATTER_KEY_ORDER),\n body: canonical.body,\n };\n}\n\n/\n Implements normalize replay patch path for the public runtime surface of this module.\n /\nexport function normalizeReplayPatchPath(path: string): string {\n if (path === \"/front_matter\") {\n return \"/metadata\";\n }\n if (path.startsWith(\"/front_matter/\")) {\n return `/metadata/${path.slice(\"/front_matter/\".length)}`;\n }\n return path;\n}\n\nfunction isHistoryPatchOp(value: unknown): value is HistoryPatchOp {\n return (\n typeof value === \"object\" &&\n value !== null &&\n typeof (value as { op?: unknown }).op === \"string\" &&\n typeof (value as { path?: unknown }).path === \"string\"\n );\n}\n\n/\n Implements normalize replay patch ops for the public runtime surface of this module.\n /\nexport function normalizeReplayPatchOps(patch: HistoryPatchOp[] \| unknown): HistoryPatchOp[] {\n if (!Array.isArray(patch)) {\n return [];\n }\n return patch.filter(isHistoryPatchOp).map((operation) => ({\n ...operation,\n path: normalizeReplayPatchPath(operation.path),\n from: typeof operation.from === \"string\" ? normalizeReplayPatchPath(operation.from) : undefined,\n }));\n}\n\nfunction isReplayDocumentShape(value: unknown): value is { metadata: Record<string, unknown>; body: string } {\n return (\n typeof value === \"object\" &&\n value !== null &&\n \"metadata\" in value &&\n \"body\" in value &&\n typeof (value as { body: unknown }).body === \"string\" &&\n typeof (value as { metadata: unknown }).metadata === \"object\" &&\n (value as { metadata: unknown }).metadata !== null\n );\n}\n\n/\n Restricts replay apply result values accepted by command, SDK, and storage contracts.\n /\nexport type ReplayApplyResult =\n \| { ok: true; document: ReplayDocument }\n \| { ok: false; error: unknown };\n\n/\n Strictly apply a history patch (front_matter->metadata normalized) to a replay\n * document. Returns a result envelope rather than throwing so each caller can\n * format its own error contract.\n /\nexport function tryApplyReplayPatch(current: ReplayDocument, patch: HistoryPatchOp[]): ReplayApplyResult {\n try {\n const normalizedPatch = normalizeReplayPatchOps(patch);\n const applied = jsonPatch.applyPatch(\n structuredClone(current),\n normalizedPatch as jsonPatch.Operation[],\n true,\n false,\n ).newDocument as unknown;\n if (!isReplayDocumentShape(applied)) {\n return { ok: false, error: new Error(\"history_replay_invalid_document_shape\") };\n }\n return { ok: true, document: { metadata: applied.metadata, body: applied.body } };\n } catch (error) {\n return { ok: false, error };\n }\n}\n\n/\n Deterministically verify a history chain: each entry's before_hash must equal\n * the prior replayed after_hash, the patch must strictly apply, and the recorded\n * after_hash must equal the replayed result.\n /\nexport function verifyHistoryChain(entries: HistoryEntry[]): { ok: boolean; errors: string[] } {\n let replay = cloneEmptyReplayDocument();\n for (let index = 0; index < entries.length; index += 1) {\n const entry = entries[index];\n if (replayHash(replay) !== entry.before_hash) {\n return {\n ok: false,\n errors: [`verify_failed:before_hash_mismatch:entry_${index + 1}`],\n };\n }\n const applied = tryApplyReplayPatch(replay, entry.patch);\n if (!applied.ok) {\n return {\n ok: false,\n errors: [`verify_failed:patch_apply_failed:entry_${index + 1}`],\n };\n }\n replay = applied.document;\n if (replayHash(replay) !== entry.after_hash) {\n return {\n ok: false,\n errors: [`verify_failed:after_hash_mismatch:entry_${index + 1}`],\n };\n }\n }\n return { ok: true, errors: [] };\n}\n\n/\n Documents the lenient apply result payload exchanged by command, SDK, and package integrations.\n /\nexport interface LenientApplyResult {\n document: ReplayDocument;\n convertedReplaceToAdd: number;\n skippedOps: number;\n}\n\nfunction tryApplySingleOp(document: unknown, op: HistoryPatchOp): { ok: true; document: unknown } \| { ok: false } {\n try {\n const applied = jsonPatch.applyPatch(\n structuredClone(document),\n [op as jsonPatch.Operation],\n true,\n false,\n ).newDocument as unknown;\n return { ok: true, document: applied };\n } catch {\n return { ok: false };\n }\n}\n\n/\n Apply a legacy patch op-by-op, recovering from drift that strict replay rejects:\n * a `replace` whose path no longer exists is retried as `add`, and any op that\n * still cannot apply against the current replay state is skipped. The resulting\n * document is what the repaired entry's recomputed patch should target.\n /\nexport function lenientApplyReplayPatch(current: ReplayDocument, patch: HistoryPatchOp[]): LenientApplyResult {\n let working: unknown = structuredClone(current);\n let convertedReplaceToAdd = 0;\n let skippedOps = 0;\n\n for (const op of normalizeReplayPatchOps(patch)) {\n const direct = tryApplySingleOp(working, op);\n if (direct.ok) {\n working = direct.document;\n continue;\n }\n if (op.op === \"replace\") {\n const asAdd = tryApplySingleOp(working, { ...op, op: \"add\" });\n if (asAdd.ok) {\n working = asAdd.document;\n convertedReplaceToAdd += 1;\n continue;\n }\n }\n skippedOps += 1;\n }\n\n const candidate = working as { metadata?: unknown; body?: unknown };\n const document: ReplayDocument = {\n metadata:\n typeof candidate.metadata === \"object\" && candidate.metadata !== null\n ? (candidate.metadata as Record<string, unknown>)\n : {},\n body: typeof candidate.body === \"string\" ? candidate.body : current.body,\n };\n return { document, convertedReplaceToAdd, skippedOps };\n}\n\n/\n Documents the reanchor entry detail payload exchanged by command, SDK, and package integrations.\n /\nexport interface ReanchorEntryDetail {\n index: number;\n rehashed: boolean;\n patch_repaired: boolean;\n converted_replace_to_add: number;\n skipped_ops: number;\n}\n\n/\n Documents the reanchor result payload exchanged by command, SDK, and package integrations.\n /\nexport interface ReanchorResult {\n entries: HistoryEntry[];\n finalDocument: ReplayDocument;\n entriesRehashed: number;\n entriesPatchRepaired: number;\n convertedReplaceToAdd: number;\n skippedOps: number;\n details: ReanchorEntryDetail[];\n}\n\n/\n Re-anchor a drifted history chain: replay every entry from empty, recompute the\n * before/after hashes, and only rewrite a patch when the original op set no longer\n * strictly applies (legacy drift). Clean entries keep their patch verbatim so the\n * on-disk diff stays minimal. The returned chain verifies via verifyHistoryChain.\n /\nexport function reanchorHistoryEntries(entries: HistoryEntry[]): ReanchorResult {\n let replay = cloneEmptyReplayDocument();\n const rewritten: HistoryEntry[] = [];\n const details: ReanchorEntryDetail[] = [];\n let entriesRehashed = 0;\n let entriesPatchRepaired = 0;\n let convertedReplaceToAdd = 0;\n let skippedOps = 0;\n\n for (let index = 0; index < entries.length; index += 1) {\n const entry = entries[index];\n const beforeHash = replayHash(replay);\n const strict = tryApplyReplayPatch(replay, entry.patch);\n\n let next: ReplayDocument;\n let outPatch: HistoryPatchOp[];\n let patchRepaired = false;\n let entryConverted = 0;\n let entrySkipped = 0;\n\n if (strict.ok) {\n next = strict.document;\n outPatch = entry.patch;\n } else {\n const lenient = lenientApplyReplayPatch(replay, entry.patch);\n next = lenient.document;\n outPatch = jsonPatch.compare(replay, next) as HistoryPatchOp[];\n patchRepaired = true;\n entryConverted = lenient.convertedReplaceToAdd;\n entrySkipped = lenient.skippedOps;\n convertedReplaceToAdd += entryConverted;\n skippedOps += entrySkipped;\n entriesPatchRepaired += 1;\n }\n\n const afterHash = replayHash(next);\n const rehashed = beforeHash !== entry.before_hash \|\| afterHash !== entry.after_hash;\n if (rehashed) {\n entriesRehashed += 1;\n }\n\n rewritten.push({\n ...entry,\n patch: outPatch,\n before_hash: beforeHash,\n after_hash: afterHash,\n });\n details.push({\n index: index + 1,\n rehashed,\n patch_repaired: patchRepaired,\n converted_replace_to_add: entryConverted,\n skipped_ops: entrySkipped,\n });\n replay = next;\n }\n\n return {\n entries: rewritten,\n finalDocument: replay,\n entriesRehashed,\n entriesPatchRepaired,\n convertedReplaceToAdd,\n skippedOps,\n details,\n };\n}\n\n/\n Implements history entries to raw for the public runtime surface of this module.\n */\nexport function historyEntriesToRaw(entries: HistoryEntry[]): string {\n if (entries.length === 0) {\n return \"\";\n }\n return `${entries.map((entry) => JSON.stringify(entry)).join(\"\\n\")}\\n`;\n}\n"],"names":[],"mappings":"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","debugId":"cf6461d3-7d73-5aa9-afa3-65f14d708e4c"}

package/dist/core/item/item-format-version.d.ts ADDED Viewed

@@ -0,0 +1,87 @@
+/**
+ * @module core/item/item-format-version
+ *
+ * Tracks the on-disk item front-matter format version so a future breaking
+ * storage change can tell already-current items apart from items that a staged
+ * migration must rewrite, without re-parsing and structurally guessing every
+ * file. The version is an explicit, monotonically increasing integer stamped in
+ * front-matter as `pm_format_version`.
+ *
+ * Token economy is a first-class constraint here: the baseline version (1) is
+ * the implicit default and is never serialized, so today's corpus gains zero
+ * bytes and zero churn. The field only materializes once an item reaches
+ * version 2 or higher. Absence of the field is therefore always interpreted as
+ * the baseline version, both now and after future bumps. The classification
+ * helpers below power the advisory `pm health` integrity surface and the
+ * `pm validate` format-version check.
+ */
+import type { ItemMetadata } from "../../types/index.js";
+/**
+ * The original (and implicit) item front-matter format version. Items missing a
+ * `pm_format_version` field are always treated as this version, so the baseline
+ * is never written to disk and adds no per-item token cost.
+ */
+export declare const BASELINE_ITEM_FORMAT_VERSION = 1;
+/**
+ * The format version this runtime writes and considers current. When a breaking
+ * front-matter change ships, bump this constant and add a migration that
+ * rewrites items whose {@link effectiveItemFormatVersion} is lower; items at or
+ * above it need no migration. It stays equal to
+ * {@link BASELINE_ITEM_FORMAT_VERSION} until the first such change.
+ */
+export declare const CURRENT_ITEM_FORMAT_VERSION = 1;
+/**
+ * Resolve the format version an item is effectively stored at. A present,
+ * positive-integer `pm_format_version` is taken verbatim (including versions
+ * ahead of this runtime, so they can be flagged rather than silently clamped);
+ * an absent, malformed, or sub-baseline value resolves to
+ * {@link BASELINE_ITEM_FORMAT_VERSION}.
+ */
+export declare function effectiveItemFormatVersion(metadata: Pick<ItemMetadata, "pm_format_version">): number;
+/**
+ * Reduce an item's `pm_format_version` to its persisted form: the baseline
+ * version (and any malformed or sub-baseline value) is dropped so it is never
+ * serialized, while versions at or above {@link BASELINE_ITEM_FORMAT_VERSION}
+ * plus one are preserved verbatim. This keeps the field absent for the entire
+ * current corpus and only writes it once an item genuinely advances past the
+ * implicit baseline.
+ */
+export declare function normalizeItemFormatVersion(value: unknown): number | undefined;
+/**
+ * Relationship between an item's stored format version and the runtime's
+ * current version: `outdated` (below current, a migration would rewrite it),
+ * `ahead` (above current, written by a newer pm than this one), or `current`.
+ */
+export type ItemFormatVersionStatus = "current" | "outdated" | "ahead";
+/**
+ * Classify a single stored format version against the runtime's current
+ * version. Defaults to {@link CURRENT_ITEM_FORMAT_VERSION}; the `current`
+ * parameter exists so callers (and tests) can evaluate against a hypothetical
+ * future version without mutating the module constant.
+ */
+export declare function classifyItemFormatVersion(version: number, current?: number): ItemFormatVersionStatus;
+/**
+ * One item's reference (id or relative path) paired with the format version it
+ * is stored at, used as input to {@link scanItemFormatVersions}.
+ */
+export interface ItemFormatVersionScanEntry {
+    ref: string;
+    version: number;
+}
+/**
+ * Sorted references partitioned by how their stored format version compares to
+ * the runtime's current version. References at the current version are omitted
+ * from both lists.
+ */
+export interface ItemFormatVersionScanResult {
+    outdated: string[];
+    ahead: string[];
+}
+/**
+ * Partition a set of items by format version into `outdated` (need migration)
+ * and `ahead` (written by a newer pm) reference lists, each sorted for stable
+ * diagnostics. Pushing all comparison branches into this pure, exhaustively
+ * tested helper lets `pm health` and `pm validate` emit findings by iterating
+ * the result lists, with no version-comparison branching of their own.
+ */
+export declare function scanItemFormatVersions(entries: readonly ItemFormatVersionScanEntry[], current?: number): ItemFormatVersionScanResult;

package/dist/core/item/item-format-version.js ADDED Viewed

@@ -0,0 +1,85 @@
+/**
+ * The original (and implicit) item front-matter format version. Items missing a
+ * `pm_format_version` field are always treated as this version, so the baseline
+ * is never written to disk and adds no per-item token cost.
+ */
+!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]="f0e67d63-2f7b-5f4a-b441-7a499c82e0a8")}catch(e){}}();
+export const BASELINE_ITEM_FORMAT_VERSION = 1;
+/**
+ * The format version this runtime writes and considers current. When a breaking
+ * front-matter change ships, bump this constant and add a migration that
+ * rewrites items whose {@link effectiveItemFormatVersion} is lower; items at or
+ * above it need no migration. It stays equal to
+ * {@link BASELINE_ITEM_FORMAT_VERSION} until the first such change.
+ */
+export const CURRENT_ITEM_FORMAT_VERSION = 1;
+/**
+ * Resolve the format version an item is effectively stored at. A present,
+ * positive-integer `pm_format_version` is taken verbatim (including versions
+ * ahead of this runtime, so they can be flagged rather than silently clamped);
+ * an absent, malformed, or sub-baseline value resolves to
+ * {@link BASELINE_ITEM_FORMAT_VERSION}.
+ */
+export function effectiveItemFormatVersion(metadata) {
+    const raw = metadata.pm_format_version;
+    if (typeof raw === "number" && Number.isInteger(raw) && raw >= BASELINE_ITEM_FORMAT_VERSION) {
+        return raw;
+    }
+    return BASELINE_ITEM_FORMAT_VERSION;
+}
+/**
+ * Reduce an item's `pm_format_version` to its persisted form: the baseline
+ * version (and any malformed or sub-baseline value) is dropped so it is never
+ * serialized, while versions at or above {@link BASELINE_ITEM_FORMAT_VERSION}
+ * plus one are preserved verbatim. This keeps the field absent for the entire
+ * current corpus and only writes it once an item genuinely advances past the
+ * implicit baseline.
+ */
+export function normalizeItemFormatVersion(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= BASELINE_ITEM_FORMAT_VERSION) {
+        return undefined;
+    }
+    return value;
+}
+/**
+ * Classify a single stored format version against the runtime's current
+ * version. Defaults to {@link CURRENT_ITEM_FORMAT_VERSION}; the `current`
+ * parameter exists so callers (and tests) can evaluate against a hypothetical
+ * future version without mutating the module constant.
+ */
+export function classifyItemFormatVersion(version, current = CURRENT_ITEM_FORMAT_VERSION) {
+    if (version < current) {
+        return "outdated";
+    }
+    if (version > current) {
+        return "ahead";
+    }
+    return "current";
+}
+/**
+ * Partition a set of items by format version into `outdated` (need migration)
+ * and `ahead` (written by a newer pm) reference lists, each sorted for stable
+ * diagnostics. Pushing all comparison branches into this pure, exhaustively
+ * tested helper lets `pm health` and `pm validate` emit findings by iterating
+ * the result lists, with no version-comparison branching of their own.
+ */
+export function scanItemFormatVersions(entries, current = CURRENT_ITEM_FORMAT_VERSION) {
+    const outdated = [];
+    const ahead = [];
+    for (const entry of entries) {
+        const status = classifyItemFormatVersion(entry.version, current);
+        if (status === "outdated") {
+            outdated.push(entry.ref);
+        }
+        else if (status === "ahead") {
+            ahead.push(entry.ref);
+        }
+    }
+    return {
+        outdated: outdated.sort((left, right) => left.localeCompare(right)),
+        ahead: ahead.sort((left, right) => left.localeCompare(right)),
+    };
+}
+//# sourceMappingURL=item-format-version.js.map
+//# debugId=f0e67d63-2f7b-5f4a-b441-7a499c82e0a8

package/dist/core/item/item-format-version.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"item-format-version.js","sources":["core/item/item-format-version.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/item/item-format-version\n *\n * Tracks the on-disk item front-matter format version so a future breaking\n * storage change can tell already-current items apart from items that a staged\n * migration must rewrite, without re-parsing and structurally guessing every\n * file. The version is an explicit, monotonically increasing integer stamped in\n * front-matter as `pm_format_version`.\n *\n * Token economy is a first-class constraint here: the baseline version (1) is\n * the implicit default and is never serialized, so today's corpus gains zero\n * bytes and zero churn. The field only materializes once an item reaches\n * version 2 or higher. Absence of the field is therefore always interpreted as\n * the baseline version, both now and after future bumps. The classification\n * helpers below power the advisory `pm health` integrity surface and the\n * `pm validate` format-version check.\n */\nimport type { ItemMetadata } from \"../../types/index.js\";\n\n/**\n * The original (and implicit) item front-matter format version. Items missing a\n * `pm_format_version` field are always treated as this version, so the baseline\n * is never written to disk and adds no per-item token cost.\n */\nexport const BASELINE_ITEM_FORMAT_VERSION = 1;\n\n/**\n * The format version this runtime writes and considers current. When a breaking\n * front-matter change ships, bump this constant and add a migration that\n * rewrites items whose {@link effectiveItemFormatVersion} is lower; items at or\n * above it need no migration. It stays equal to\n * {@link BASELINE_ITEM_FORMAT_VERSION} until the first such change.\n */\nexport const CURRENT_ITEM_FORMAT_VERSION = 1;\n\n/**\n * Resolve the format version an item is effectively stored at. A present,\n * positive-integer `pm_format_version` is taken verbatim (including versions\n * ahead of this runtime, so they can be flagged rather than silently clamped);\n * an absent, malformed, or sub-baseline value resolves to\n * {@link BASELINE_ITEM_FORMAT_VERSION}.\n */\nexport function effectiveItemFormatVersion(metadata: Pick<ItemMetadata, \"pm_format_version\">): number {\n const raw = metadata.pm_format_version;\n if (typeof raw === \"number\" && Number.isInteger(raw) && raw >= BASELINE_ITEM_FORMAT_VERSION) {\n return raw;\n }\n return BASELINE_ITEM_FORMAT_VERSION;\n}\n\n/**\n * Reduce an item's `pm_format_version` to its persisted form: the baseline\n * version (and any malformed or sub-baseline value) is dropped so it is never\n * serialized, while versions at or above {@link BASELINE_ITEM_FORMAT_VERSION}\n * plus one are preserved verbatim. This keeps the field absent for the entire\n * current corpus and only writes it once an item genuinely advances past the\n * implicit baseline.\n */\nexport function normalizeItemFormatVersion(value: unknown): number | undefined {\n if (typeof value !== \"number\" || !Number.isInteger(value) || value <= BASELINE_ITEM_FORMAT_VERSION) {\n return undefined;\n }\n return value;\n}\n\n/**\n * Relationship between an item's stored format version and the runtime's\n * current version: `outdated` (below current, a migration would rewrite it),\n * `ahead` (above current, written by a newer pm than this one), or `current`.\n */\nexport type ItemFormatVersionStatus = \"current\" | \"outdated\" | \"ahead\";\n\n/**\n * Classify a single stored format version against the runtime's current\n * version. Defaults to {@link CURRENT_ITEM_FORMAT_VERSION}; the `current`\n * parameter exists so callers (and tests) can evaluate against a hypothetical\n * future version without mutating the module constant.\n */\nexport function classifyItemFormatVersion(\n version: number,\n current: number = CURRENT_ITEM_FORMAT_VERSION,\n): ItemFormatVersionStatus {\n if (version < current) {\n return \"outdated\";\n }\n if (version > current) {\n return \"ahead\";\n }\n return \"current\";\n}\n\n/**\n * One item's reference (id or relative path) paired with the format version it\n * is stored at, used as input to {@link scanItemFormatVersions}.\n */\nexport interface ItemFormatVersionScanEntry {\n ref: string;\n version: number;\n}\n\n/**\n * Sorted references partitioned by how their stored format version compares to\n * the runtime's current version. References at the current version are omitted\n * from both lists.\n */\nexport interface ItemFormatVersionScanResult {\n outdated: string[];\n ahead: string[];\n}\n\n/**\n * Partition a set of items by format version into `outdated` (need migration)\n * and `ahead` (written by a newer pm) reference lists, each sorted for stable\n * diagnostics. Pushing all comparison branches into this pure, exhaustively\n * tested helper lets `pm health` and `pm validate` emit findings by iterating\n * the result lists, with no version-comparison branching of their own.\n */\nexport function scanItemFormatVersions(\n entries: readonly ItemFormatVersionScanEntry[],\n current: number = CURRENT_ITEM_FORMAT_VERSION,\n): ItemFormatVersionScanResult {\n const outdated: string[] = [];\n const ahead: string[] = [];\n for (const entry of entries) {\n const status = classifyItemFormatVersion(entry.version, current);\n if (status === \"outdated\") {\n outdated.push(entry.ref);\n } else if (status === \"ahead\") {\n ahead.push(entry.ref);\n }\n }\n return {\n outdated: outdated.sort((left, right) => left.localeCompare(right)),\n ahead: ahead.sort((left, right) => left.localeCompare(right)),\n };\n}\n"],"names":[],"mappings":"AAmBA;;;;GAIG;;;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CAAC,QAAiD;IAC1F,MAAM,GAAG,GAAG,QAAQ,CAAC,iBAAiB,CAAC;IACvC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,4BAA4B,EAAE,CAAC;QAC5F,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,4BAA4B,CAAC;AACtC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAAc;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,4BAA4B,EAAE,CAAC;QACnG,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AASD;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAe,EACf,UAAkB,2BAA2B;IAE7C,IAAI,OAAO,GAAG,OAAO,EAAE,CAAC;QACtB,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,IAAI,OAAO,GAAG,OAAO,EAAE,CAAC;QACtB,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAqBD;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAA8C,EAC9C,UAAkB,2BAA2B;IAE7C,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,yBAAyB,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACjE,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;YAC1B,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;aAAM,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YAC9B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QACnE,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;KAC9D,CAAC;AACJ,CAAC","debugId":"f0e67d63-2f7b-5f4a-b441-7a499c82e0a8"}

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

@@ -4,11 +4,12 @@
  * Defines item parsing, formatting, and lifecycle helpers for Item Format.
  */
-!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]="c295802c-f55f-56e8-afdc-257cdef6a4cb")}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]="777ea2a9-5aa6-5a90-abb5-a0b6052645f2")}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";
 import { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, } from "../schema/runtime-schema.js";
+import { BASELINE_ITEM_FORMAT_VERSION, normalizeItemFormatVersion } from "./item-format-version.js";
 import { normalizeStatusInput } from "./status.js";
 import { decodeToonItemContent } from "./toon-decode.js";
 import { EXIT_CODE, FRONT_MATTER_KEY_ORDER } from "../shared/constants.js";
@@ -129,6 +130,10 @@ function assertValidFrontMatter(frontMatter, runtimeContext) {
     }
     const itemType = record.type;
     assertFrontMatterCondition(typeof itemType === "string" && itemType.trim().length > 0, "type must be a non-empty string");
+    const formatVersion = record.pm_format_version;
+    if (formatVersion !== undefined) {
+        assertFrontMatterCondition(typeof formatVersion === "number" && Number.isInteger(formatVersion) && formatVersion >= BASELINE_ITEM_FORMAT_VERSION, `pm_format_version must be an integer >= ${BASELINE_ITEM_FORMAT_VERSION}`);
+    }
     const status = record.status;
     assertFrontMatterCondition(typeof status === "string" && status.trim().length > 0, "status must be a non-empty string");
     const statusRegistry = runtimeContext?.statusRegistry;
@@ -849,6 +854,7 @@ export function normalizeFrontMatter(frontMatter, options = {}) {
         title: frontMatter.title,
         description: frontMatter.description,
         type: frontMatter.type,
+        pm_format_version: normalizeItemFormatVersion(frontMatter.pm_format_version),
         source_type: frontMatter.source_type?.trim() || undefined,
         type_options: normalizeTypeOptions(frontMatter.type_options),
         status: normalizedStatus,
@@ -1149,4 +1155,4 @@ export const _testOnlyItemFormat = {
     sortTests,
 };
 //# sourceMappingURL=item-format.js.map
-//# debugId=c295802c-f55f-56e8-afdc-257cdef6a4cb
+//# debugId=777ea2a9-5aa6-5a90-abb5-a0b6052645f2