@unbrained/pm-cli 2026.9.3 → 2026.9.5

package/dist/sdk/history/salvage.js

@@ -0,0 +1,248 @@
+/**
+ * @module sdk/history/salvage
+ * Recover an invalid JSONL suffix while preserving every verified prefix byte.
+ */
+
+!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]="49af8ec4-dd6b-56ef-8833-9c776fa35c85")}catch(e){}}();
+import { isUtf8 } from "node:buffer";
+import { readFile } from "node:fs/promises";
+import { isFileMissingError, readFileIfExists, } from "../../core/fs/fs-utils.js";
+import { acquireLock } from "../../core/lock/lock.js";
+import { createHistoryEntry, sealHistoryRecord, } from "../../core/history/history.js";
+import { checkHistoryRewriteOwnership, writeHistoryRawWithRollback, } from "../../core/history/history-rewrite.js";
+import { replayHistoryToTarget } from "../../core/history/projection.js";
+import { replayToItemDocument, verifyHistoryChainWithVersion, } from "../../core/history/replay.js";
+import { findFirstMergeConflictMarker } from "../../core/shared/conflict-markers.js";
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+import { sha256Hex } from "../../core/shared/serialization.js";
+import { nowIso } from "../../core/shared/time.js";
+import { runActiveOnReadHooks, runActiveOnWriteHooks, } from "../../core/extensions/index.js";
+import { locateItem, readLocatedItemSnapshot, } from "../../core/store/item-store.js";
+/** Decode a whole record or identify an invalid suffix without hiding a valid record. */
+function decodeSalvageLine(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        // A complete record followed by crash padding is not a disposable line.
+        // Refuse instead of silently dropping that record along with the padding.
+        if (line.trimStart().startsWith("{") && line.includes("}")) {
+            throw new PmCliError("History salvage cannot discard a potentially complete record with trailing corruption.", EXIT_CODE.CONFLICT, { code: "history_salvage_refused" });
+        }
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new PmCliError("History salvage would conceal interior corruption or a malformed record.", EXIT_CODE.CONFLICT, { code: "history_salvage_refused" });
+    }
+    const entry = parsed;
+    if (!Array.isArray(entry.patch) ||
+        ![
+            entry.ts,
+            entry.author,
+            entry.op,
+            entry.before_hash,
+            entry.after_hash,
+        ].every((field) => typeof field === "string")) {
+        throw new PmCliError("History salvage requires complete history records before the invalid tail.", EXIT_CODE.CONFLICT, { code: "history_salvage_refused" });
+    }
+    return entry;
+}
+/**
+ * Select a hash-verified prefix. Any parseable JSON after the first invalid
+ * line makes the corruption interior and therefore unsalvageable by truncation.
+ */
+export function inspectHistoryTail(raw) {
+    if (findFirstMergeConflictMarker(raw)) {
+        throw new PmCliError("Resolve history merge conflicts before salvage.", EXIT_CODE.CONFLICT, { code: "history_salvage_refused" });
+    }
+    const entries = [];
+    let offset = 0;
+    let invalidOffset;
+    let invalidLine = 0;
+    for (const [index, line] of raw.split("\n").entries()) {
+        if (!line.trim()) {
+            offset += line.length + 1;
+            continue;
+        }
+        const parsed = decodeSalvageLine(line);
+        if (parsed === null) {
+            if (invalidOffset === undefined) {
+                invalidOffset = offset;
+                invalidLine = index + 1;
+            }
+            offset += line.length + 1;
+            continue;
+        }
+        if (invalidOffset !== undefined) {
+            throw new PmCliError("History salvage would discard a record or conceal interior corruption.", EXIT_CODE.CONFLICT, {
+                code: "history_salvage_refused",
+                required: "Recover the damaged record from version control or a backup; no bytes were changed.",
+            });
+        }
+        entries.push(parsed);
+        offset += line.length + 1;
+    }
+    const verification = verifyHistoryChainWithVersion(entries);
+    if (!verification.ok || verification.item_hash_version === undefined) {
+        throw new PmCliError("History salvage requires a nonempty verified prefix.", EXIT_CODE.CONFLICT, {
+            code: "history_salvage_refused",
+            verification_errors: verification.errors,
+            required: "Recover an intact history prefix from version control or a backup.",
+        });
+    }
+    return {
+        entries,
+        itemHashVersion: verification.item_hash_version,
+        prefix: invalidOffset === undefined ? raw : raw.slice(0, invalidOffset),
+        receipt: invalidOffset === undefined
+            ? null
+            : {
+                first_invalid_line: invalidLine,
+                discarded_bytes: Buffer.byteLength(raw.slice(invalidOffset)),
+                discarded_sha256: sha256Hex(raw.slice(invalidOffset)),
+                retained_entries: entries.length,
+            },
+    };
+}
+/** Prefer the live item's owner; history supplies ownership only when its file is unreadable. */
+async function readSalvageOwnership(subject, settings, fallback) {
+    if (!subject.located)
+        return { itemRaw: null, document: fallback };
+    const snapshot = await readLocatedItemSnapshot(subject.located, {
+        schema: settings.schema,
+    });
+    return { itemRaw: snapshot.raw, document: snapshot.document ?? fallback };
+}
+/** Refuse lossy decoding so suffix receipts and rollback always describe original bytes. */
+async function readSalvageStream(historyPath) {
+    let bytes;
+    try {
+        bytes = await readFile(historyPath);
+    }
+    catch (error) {
+        if (isFileMissingError(error))
+            return null;
+        throw error;
+    }
+    if (!isUtf8(bytes)) {
+        throw new PmCliError("History salvage requires UTF-8 input; recover binary corruption from a byte-preserving backup.", EXIT_CODE.CONFLICT, { code: "history_salvage_refused" });
+    }
+    return bytes.toString("utf8");
+}
+/** Salvage one explicitly selected stream under its normal ownership and lock policy. */
+export async function salvageHistoryTail(params) {
+    const { subject, settings, options, author } = params;
+    if ([
+        options.normalizeProvenance,
+        options.auditOperation,
+        options.auditContext,
+        options.auditContextById,
+        options.forceAuditEntry,
+        options.mergeReceiptProof,
+        options.mergeReceiptProofById,
+    ].some(Boolean)) {
+        throw new PmCliError("Tail salvage cannot be combined with other repair modes.", EXIT_CODE.USAGE);
+    }
+    const raw = await readSalvageStream(subject.historyPath);
+    if (raw === null)
+        throw new PmCliError(`No history stream exists for ${subject.id}.`, EXIT_CODE.NOT_FOUND);
+    await runActiveOnReadHooks({ path: subject.historyPath, scope: "project" });
+    const selected = inspectHistoryTail(raw);
+    const replay = replayHistoryToTarget(selected.entries, selected.entries.length - 1);
+    const document = replayToItemDocument(replay);
+    if (typeof replay.metadata.id === "string" &&
+        replay.metadata.id !== subject.id) {
+        throw new PmCliError("History belongs to another item; salvage refused.", EXIT_CODE.CONFLICT, { code: "history_salvage_refused" });
+    }
+    const ownership = await readSalvageOwnership(subject, settings, document);
+    const warnings = checkHistoryRewriteOwnership({
+        itemDocument: ownership.document,
+        subjectId: subject.id,
+        author,
+        force: options.force,
+        settings,
+    });
+    const version = selected.itemHashVersion;
+    const dryRun = options.dryRun === true;
+    const changed = selected.receipt !== null;
+    if (changed && !dryRun) {
+        const release = await acquireLock(params.pmRoot, subject.id, settings.locks.ttl_seconds, author, Boolean(options.force), settings.governance.force_required_for_stale_lock, settings.locks.wait_ms);
+        try {
+            const currentRaw = await readSalvageStream(subject.historyPath);
+            const located = await locateItem(params.pmRoot, subject.id, settings.id_prefix, settings.item_format, params.typeRegistry.type_to_folder);
+            const currentItem = located
+                ? await readFileIfExists(located.itemPath)
+                : null;
+            if (currentRaw !== raw || currentItem !== ownership.itemRaw) {
+                throw new PmCliError("History or item changed while waiting for salvage lock; retry.", EXIT_CODE.CONFLICT);
+            }
+            const audit = sealHistoryRecord({
+                ...createHistoryEntry({
+                    nowIso: nowIso(),
+                    author,
+                    op: "history_salvage",
+                    before: document,
+                    after: document,
+                    message: options.message,
+                    context: { history_salvage: selected.receipt },
+                }),
+                before_hash: selected.entries.at(-1).after_hash,
+                after_hash: selected.entries.at(-1).after_hash,
+                item_hash_version: version,
+            });
+            await writeHistoryRawWithRollback({
+                historyPath: subject.historyPath,
+                historyRawUnderLock: raw,
+                nextHistoryRaw: `${selected.prefix}${JSON.stringify(audit)}\n`,
+            });
+            warnings.push(...(await runActiveOnWriteHooks({
+                path: subject.historyPath,
+                scope: "project",
+                op: "history_salvage:history",
+            })));
+        }
+        finally {
+            await release();
+        }
+    }
+    return {
+        id: subject.id,
+        dry_run: dryRun,
+        changed,
+        history: {
+            path: subject.historyPath,
+            entries_scanned: selected.entries.length,
+            chain_drift_before: false,
+            entries_rehashed: 0,
+            entries_patch_repaired: 0,
+            converted_replace_to_add: 0,
+            skipped_ops: 0,
+            reconciled_with_item: false,
+            audit_entry_added: changed && !dryRun,
+            verify_ok: true,
+            verify_errors: [],
+            item_hash_version_before: version,
+            item_hash_version_after: version,
+            version_disposition: "preserved",
+        },
+        item: {
+            exists: subject.located !== null,
+            path: subject.located?.itemPath ?? null,
+            matched_chain_before: null,
+        },
+        provenance_normalization: {
+            requested: false,
+            changed: false,
+            events_changed: 0,
+            observations_removed: 0,
+            invalid_values: [],
+        },
+        ...(selected.receipt ? { salvage: selected.receipt } : {}),
+        warnings,
+        generated_at: nowIso(),
+    };
+}
+//# sourceMappingURL=salvage.js.map
+//# debugId=49af8ec4-dd6b-56ef-8833-9c776fa35c85

package/dist/sdk/history-compact.js

@@ -4,16 +4,17 @@
  * Implements the pm history compact command surface and its agent-facing runtime behavior.
  */
 
-!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]="31152621-df59-54a5-a28d-63119e734e6e")}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]="26c39ecd-5d72-5cc9-b22b-6abc33fbf4ac")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { createHistoryEntry } from "../core/history/history.js";
+import { createHistoryEntry, hashHistoryStream, sealHistoryRecord, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, } from "../core/history/history.js";
 import { selectHistoryCompactBulkTargets, } from "../core/history/history-compact-bulk.js";
 import { executeHistoryRewrite, writeHistoryRawWithRollback, } from "../core/history/history-rewrite.js";
-import { cloneEmptyReplayDocument, historyEntriesToRaw, replayHash, replayToItemDocument, toReplayDocument, verifyHistoryChain, } from "../core/history/replay.js";
+import { cloneEmptyReplayDocument, historyEntriesToRaw, replayHashVerificationCandidates, replayToItemDocument, toReplayDocument, verifyHistoryChain, } from "../core/history/replay.js";
 import { applyHistoryPatch } from "../core/history/projection.js";
 import { readHistoryEntries } from "../core/history/read.js";
+import { historyVersionOffset } from "../core/history/version-address.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
 import { lifecycleClassifierFromStatusRegistry } from "../core/governance/metadata-coverage.js";
 import { resolveRuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
@@ -29,6 +30,7 @@ import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 import { resolveAuthor } from "../core/shared/author.js";
 import { resolveHistorySubject } from "./history-redact.js";
+/** Translate a durable version or timestamp boundary into physical compacted and retained counts. */
 function parseBeforeBoundary(before, entries) {
     if (before === undefined) {
         return {
@@ -44,12 +46,13 @@ function parseBeforeBoundary(before, entries) {
     }
     if (/^\d+$/.test(raw)) {
         const version = Number.parseInt(raw, 10);
+        const offset = historyVersionOffset(entries);
         if (!Number.isSafeInteger(version) ||
-            version < 1 ||
-            version > entries.length + 1) {
-            throw new PmCliError(`history-compact --before version must be between 1 and ${entries.length + 1}.`, EXIT_CODE.USAGE);
+            version < offset + 1 ||
+            version > offset + entries.length + 1) {
+            throw new PmCliError(`history-compact --before version must be between ${offset + 1} and ${offset + entries.length + 1}.`, EXIT_CODE.USAGE);
         }
-        const compactCount = Math.max(0, Math.min(entries.length, version - 1));
+        const compactCount = version - offset - 1;
         return {
             kind: "version",
             raw,
@@ -79,18 +82,13 @@ function parseBeforeBoundary(before, entries) {
         retainedCount: entries.length - compactCount,
     };
 }
+/** Fold the already verified stream once, capturing its compaction checkpoint. */
 function replayHistoryAndResolveCheckpoint(entries, compactCount) {
     let replay = cloneEmptyReplayDocument();
     let checkpoint = cloneEmptyReplayDocument();
     for (let index = 0; index < entries.length; index += 1) {
         const entry = entries[index];
-        if (replayHash(replay) !== entry.before_hash) {
-            throw new PmCliError(`history-compact detected before-hash drift at entry ${index + 1}; run pm history-repair first.`, EXIT_CODE.CONFLICT);
-        }
         replay = applyHistoryPatch(replay, entry.patch, index + 1, entry.op);
-        if (replayHash(replay) !== entry.after_hash) {
-            throw new PmCliError(`history-compact detected after-hash drift at entry ${index + 1}; run pm history-repair first.`, EXIT_CODE.CONFLICT);
-        }
         if (index + 1 === compactCount) {
             checkpoint = structuredClone(replay);
         }
@@ -100,23 +98,7 @@ function replayHistoryAndResolveCheckpoint(entries, compactCount) {
         finalReplay: replay,
     };
 }
-function reanchorRetainedEntries(retainedEntries, seed, retainedEntryOffset) {
-    let replay = structuredClone(seed);
-    const rewritten = [];
-    for (const [index, entry] of retainedEntries.entries()) {
-        const beforeHash = replayHash(replay);
-        replay = applyHistoryPatch(replay, entry.patch, retainedEntryOffset + index + 1, entry.op);
-        rewritten.push({
-            ...entry,
-            before_hash: beforeHash,
-            after_hash: replayHash(replay),
-        });
-    }
-    return {
-        entries: rewritten,
-        finalReplay: replay,
-    };
-}
+/** Snapshot the live item and compare it with the stream's supported historical hash surfaces. */
 async function loadHistoryCompactCurrentItem(subject, settings, historyEntries) {
     const loadedItem = subject.located
         ? await readLocatedItem(subject.located, { schema: settings.schema })
@@ -128,11 +110,12 @@ async function loadHistoryCompactCurrentItem(subject, settings, historyEntries)
             matchedChainBefore: null,
         };
     }
+    const lastEntry = historyEntries[historyEntries.length - 1];
     return {
         loadedItem,
         currentItemRawBeforeLock: loadedItem.raw,
-        matchedChainBefore: replayHash(toReplayDocument(loadedItem.document)) ===
-            historyEntries[historyEntries.length - 1]?.after_hash,
+        matchedChainBefore: SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.some((version) => (lastEntry.item_hash_version === undefined || lastEntry.item_hash_version === version) &&
+            replayHashVerificationCandidates(toReplayDocument(loadedItem.document), version).includes(lastEntry.after_hash)),
     };
 }
 function buildHistoryCompactMessage(options, boundary) {
@@ -151,6 +134,7 @@ function buildHistoryCompactBaselineMessage(boundary) {
     }
     return `history-compact baseline snapshot before ${boundary.raw}.`;
 }
+/** Replace the pruned prefix with a durable-addressed checkpoint while retaining original records and hash semantics. */
 function buildHistoryCompactEntries(params) {
     if (!params.changed) {
         return {
@@ -161,16 +145,35 @@ function buildHistoryCompactEntries(params) {
     }
     const { checkpoint, finalReplay } = replayHistoryAndResolveCheckpoint(params.historyEntries, params.boundary.compactCount);
     const retained = params.historyEntries.slice(params.boundary.compactCount);
-    const reanchored = reanchorRetainedEntries(retained, checkpoint, params.boundary.compactCount);
+    const offset = historyVersionOffset(params.historyEntries, true);
     const baselineEntry = createHistoryEntry({
-        nowIso: nowIso(),
+        nowIso: params.historyEntries[params.boundary.compactCount - 1].ts,
         author: params.author,
         op: "history_compact_baseline",
         before: replayToItemDocument(cloneEmptyReplayDocument()),
         after: replayToItemDocument(checkpoint),
         message: buildHistoryCompactBaselineMessage(params.boundary),
+        context: {
+            history_compaction: {
+                contract_version: 1,
+                version_offset: offset === null ? null : offset + params.boundary.compactCount - 1,
+                checkpoint_timestamp_semantics: "last_compacted_entry",
+                pruned_entry_count: params.boundary.compactCount,
+                pruned_stream_digest: hashHistoryStream(params.historyEntries.slice(0, params.boundary.compactCount)),
+                retained_proof: "stream_digest_and_checkpoint",
+                limitation: "individual_pruned_entries_require_pre_compaction_stream",
+            },
+        },
     });
-    const rewrittenEntries = [baselineEntry, ...reanchored.entries];
+    const checkpointEntry = params.historyEntries[params.boundary.compactCount - 1];
+    // Preserve the checkpoint's epoch and semantic hash variant. Do not introduce
+    // an explicit epoch into an unversioned stream: it would pin later legacy reads.
+    const rewrittenEntries = [sealHistoryRecord({
+            ...baselineEntry,
+            before_hash: params.historyEntries[0].before_hash,
+            after_hash: checkpointEntry.after_hash,
+            item_hash_version: checkpointEntry.item_hash_version,
+        }), ...retained];
     if (!params.dryRun) {
         rewrittenEntries.push(createHistoryEntry({
             nowIso: nowIso(),
@@ -270,7 +273,8 @@ export async function runHistoryCompact(id, options, global) {
             rewrittenEntries,
         })));
     }
-    const firstRetainedEntry = boundary.retainedCount > 0 ? boundary.compactCount + 1 : null;
+    const offset = historyVersionOffset(historyEntries, true);
+    const firstRetainedEntry = boundary.retainedCount > 0 && offset !== null ? offset + boundary.compactCount + 1 : null;
     return {
         id: subject.id,
         dry_run: dryRun,
@@ -521,4 +525,4 @@ export async function runHistoryCompactBulk(options, global) {
     };
 }
 //# sourceMappingURL=history-compact.js.map
-//# debugId=31152621-df59-54a5-a28d-63119e734e6e
+//# debugId=26c39ecd-5d72-5cc9-b22b-6abc33fbf4ac

package/dist/sdk/history-read.d.ts

@@ -1,6 +1,7 @@
 import { applyHistoryPatch, ensureMaterializedHistoryTarget, extractPatchFailureContext, replayHistoryToTarget, resolveHistoryTarget, type ResolvedHistoryTarget } from "../core/history/projection.js";
 import { readHistoryEntries } from "../core/history/read.js";
 import type { HistoryEntry, ItemDocument } from "../types/index.js";
+export { findHistoryIdentityDiscontinuities, type HistoryIdentityDiscontinuity, } from "../core/history/identity.js";
 /** Workspace resolution controls accepted by {@link getItemAt}. */
 export interface GetItemAtOptions {
     /** Explicit tracker root, equivalent to the CLI global `--pm-path`. */
@@ -14,8 +15,8 @@ export interface GetItemAtResult {
     document: ItemDocument;
     /** Always true, preventing consumers from confusing this with current state. */
     reconstructed: true;
-    /** One-based version included in the projection. */
-    as_of_version: number;
+    /** Durable one-based version; null when a legacy checkpoint lost its mapping. */
+    as_of_version: number | null;
     /** Timestamp of the final included history entry. */
     as_of_timestamp: string;
     /** Normalized target resolution metadata shared with restore. */

package/dist/sdk/history-read.js

@@ -7,11 +7,12 @@
  * systems without acquiring locks or appending history.
  */
 
-!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]="f1ea4209-59d4-53f0-a8ea-2e060e385d14")}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]="6fe766e2-93e8-5653-beb5-16bd92efae51")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
 import { applyHistoryPatch, ensureMaterializedHistoryTarget, extractPatchFailureContext, replayHistoryToTarget, resolveHistoryTarget, } from "../core/history/projection.js";
 import { readHistoryEntries } from "../core/history/read.js";
+import { historyVersionOffset } from "../core/history/version-address.js";
 import { hashDocument, hashDocumentVerificationCandidates, hashEmptyDocument, } from "../core/history/history.js";
 import { replayToCanonicalItemDocument, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
@@ -20,6 +21,7 @@ import { PmCliError } from "../core/shared/errors.js";
 import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 import { resolveHistorySubject } from "./history-redact.js";
+export { findHistoryIdentityDiscontinuities, } from "../core/history/identity.js";
 /**
  * Verify a history chain and optionally compare it with a current document.
  *
@@ -80,10 +82,11 @@ export async function getItemAt(id, target, options = {}) {
         throw new PmCliError(`History target resolved to item ${document.metadata.id}, expected ${subject.id}.`, EXIT_CODE.GENERIC_FAILURE);
     }
     const targetEntry = history[resolvedTarget.historyIndex];
+    const offset = historyVersionOffset(history, true);
     return {
         document,
         reconstructed: true,
-        as_of_version: resolvedTarget.historyIndex + 1,
+        as_of_version: offset === null ? null : offset + resolvedTarget.historyIndex + 1,
         as_of_timestamp: targetEntry.ts,
         target: resolvedTarget,
         history_length: history.length,
@@ -91,4 +94,4 @@ export async function getItemAt(id, target, options = {}) {
 }
 export { applyHistoryPatch, ensureMaterializedHistoryTarget, extractPatchFailureContext, readHistoryEntries, replayHistoryToTarget, resolveHistoryTarget, };
 //# sourceMappingURL=history-read.js.map
-//# debugId=f1ea4209-59d4-53f0-a8ea-2e060e385d14
+//# debugId=6fe766e2-93e8-5653-beb5-16bd92efae51

package/dist/sdk/history-redact.js

@@ -4,11 +4,11 @@
  * Implements the pm history redact command surface and its agent-facing runtime behavior.
  */
 
-!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]="05b945f2-4f96-5f88-98ff-84cc856d0d57")}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]="bd1e86b0-6696-5fba-8dd4-b9636bf3ee60")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import { pathExists, readFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
-import { createHistoryEntry } from "../core/history/history.js";
+import { createHistoryEntry, resealHistoryRewrite, verifyHistoryRecordHash, } from "../core/history/history.js";
 import { invalidateHistoryDriftCacheForPath } from "../core/history/drift-cache.js";
 import { executeHistoryRewrite } from "../core/history/history-rewrite.js";
 import { EMPTY_REPLAY_DOCUMENT, historyEntriesToRaw, replayHash, replayToItemDocument, verifyHistoryChain, } from "../core/history/replay.js";
@@ -189,6 +189,22 @@ function redactUnknownValue(value, rules, replacement) {
         replacements: 0,
     };
 }
+function redactHistoryPatch(patch, rules, replacement) {
+    let replacements = 0;
+    const redactedPatch = patch.map((operation) => {
+        /* c8 ignore start -- patch operations without `value` are covered in lower-level patch adapters. */
+        if (!Object.prototype.hasOwnProperty.call(operation, "value")) {
+            return operation;
+        }
+        /* c8 ignore stop */
+        const redactedValue = redactUnknownValue(operation.value, rules, replacement);
+        replacements += redactedValue.replacements;
+        return redactedValue.replacements > 0
+            ? { ...operation, value: redactedValue.value }
+            : operation;
+    });
+    return { patch: redactedPatch, replacements };
+}
 function inspectHistoryIntegrity(entries) {
     let replay = structuredClone(EMPTY_REPLAY_DOCUMENT);
     let hashMismatchesBefore = 0;
@@ -214,6 +230,7 @@ function inspectHistoryIntegrity(entries) {
 function redactHistoryEntry(entry, rules, replacement) {
     let replacements = 0;
     let changed = false;
+    let reanchorEvidenceRedacted = false;
     let nextMessage = entry.message;
     if (typeof entry.message === "string") {
         const redactedMessage = redactStringValue(entry.message, rules, replacement);
@@ -223,31 +240,41 @@ function redactHistoryEntry(entry, rules, replacement) {
             changed = true;
         }
     }
-    const nextPatch = entry.patch.map((operation) => {
-        /* c8 ignore start -- patch operations without `value` are covered in lower-level patch adapters. */
-        if (!Object.prototype.hasOwnProperty.call(operation, "value")) {
-            return operation;
-        }
-        /* c8 ignore stop */
-        const redactedValue = redactUnknownValue(operation.value, rules, replacement);
-        replacements += redactedValue.replacements;
-        if (redactedValue.replacements > 0) {
-            changed = true;
-            return {
-                ...operation,
-                value: redactedValue.value,
-            };
-        }
-        return operation;
+    const redactedPatch = redactHistoryPatch(entry.patch, rules, replacement);
+    replacements += redactedPatch.replacements;
+    changed ||= redactedPatch.replacements > 0;
+    const nextReanchorEvidence = entry.reanchor_evidence?.map((evidence) => {
+        const redactedEvidencePatch = evidence.patch
+            ? redactHistoryPatch(evidence.patch, rules, replacement)
+            : { patch: undefined, replacements: 0 };
+        const redactedEvidenceRecord = evidence.record
+            ? redactUnknownValue(evidence.record, rules, replacement)
+            : { value: undefined, replacements: 0 };
+        replacements += redactedEvidencePatch.replacements;
+        replacements += redactedEvidenceRecord.replacements;
+        const evidenceChanged = redactedEvidencePatch.replacements > 0 ||
+            redactedEvidenceRecord.replacements > 0;
+        changed ||= evidenceChanged;
+        if (!evidenceChanged)
+            return evidence;
+        reanchorEvidenceRedacted = true;
+        const { patch: _sensitivePatch, record: _sensitiveRecord, record_hash: _priorRecordHash, record_hash_version: _priorRecordHashVersion, ...digestOnlyEvidence } = evidence;
+        return redactedEvidencePatch.replacements > 0
+            ? digestOnlyEvidence
+            : { ...digestOnlyEvidence, patch: evidence.patch };
     });
     return {
         entry: {
             ...entry,
             message: nextMessage,
-            patch: nextPatch,
+            patch: redactedPatch.patch,
+            ...(nextReanchorEvidence
+                ? { reanchor_evidence: nextReanchorEvidence }
+                : {}),
         },
         replacements,
         changed,
+        reanchorEvidenceRedacted,
     };
 }
 function rewriteHistoryEntries(entries, rules, replacement) {
@@ -256,7 +283,12 @@ function rewriteHistoryEntries(entries, rules, replacement) {
     let replacements = 0;
     const rewrittenEntries = [];
     for (let index = 0; index < entries.length; index += 1) {
-        const redacted = redactHistoryEntry(entries[index], rules, replacement);
+        const original = entries[index];
+        const recordVerification = verifyHistoryRecordHash(original);
+        if (!recordVerification.ok) {
+            throw new PmCliError(`history-redact refuses invalid immutable record ${index + 1} (${recordVerification.error}).`, EXIT_CODE.GENERIC_FAILURE);
+        }
+        const redacted = redactHistoryEntry(original, rules, replacement);
         replacements += redacted.replacements;
         if (redacted.changed) {
             entriesChanged += 1;
@@ -264,11 +296,14 @@ function rewriteHistoryEntries(entries, rules, replacement) {
         const beforeHash = replayHash(replay);
         replay = applyHistoryPatch(replay, redacted.entry.patch, index + 1, redacted.entry.op);
         const afterHash = replayHash(replay);
-        rewrittenEntries.push({
+        rewrittenEntries.push(resealHistoryRewrite(original, {
             ...redacted.entry,
             before_hash: beforeHash,
             after_hash: afterHash,
-        });
+        }, {
+            retainPriorRecord: redacted.changed,
+            retainPriorRecordHash: !redacted.changed,
+        }));
     }
     return {
         entries: rewrittenEntries,
@@ -606,4 +641,4 @@ export const _testOnly = {
     redactUnknownValue,
 };
 //# sourceMappingURL=history-redact.js.map
-//# debugId=05b945f2-4f96-5f88-98ff-84cc856d0d57
+//# debugId=bd1e86b0-6696-5fba-8dd4-b9636bf3ee60

package/dist/sdk/history-repair.d.ts

@@ -1,3 +1,4 @@
+import { type HistorySalvageReceipt } from "./history/salvage.js";
 import { type ReplayDocument } from "../core/history/replay.js";
 import type { GlobalOptions } from "../core/shared/command-types.js";
 import type { HistoryEntry } from "../types/index.js";
@@ -5,6 +6,8 @@ import { type MergeDecisionReceipt } from "./merge/receipts.js";
 import { type ProvenanceNormalizationReceipt } from "./governance/provenance-health.js";
 /** Documents the history repair command options payload exchanged by command, SDK, and package integrations. */
 export interface HistoryRepairCommandOptions {
+    /** Remove only an invalid trailing suffix after a verified prefix; never re-anchor or reconcile. */
+    salvageTail?: boolean;
     /** Value that configures or reports dry run for this contract. */
     dryRun?: boolean;
     /** Value that configures or reports author for this contract. */
@@ -36,6 +39,8 @@ export interface HistoryRepairCommandOptions {
 }
 /** Documents the history repair result payload exchanged by command, SDK, and package integrations. */
 export interface HistoryRepairResult {
+    /** Present when invalid trailing bytes were selected for explicit salvage. */
+    salvage?: HistorySalvageReceipt;
     /** Stable identifier used to reference this record across commands and storage. */
     id: string;
     /** Value that configures or reports dry run for this contract. */