@unbrained/pm-cli 2026.9.4 → 2026.9.6

package/dist/sdk/guide-topics.js

@@ -4,7 +4,7 @@
  * Provides CLI runtime support for Guide Topics.
  */
 
-!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]="7c57f381-8318-5235-aa92-c96c6cedb021")}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]="feba1227-c2a2-5ca3-83e6-3fd2780e6cbb")}catch(e){}}();
 import { listPmCommandCapabilityGroups } from "./agent-capability-contracts.js";
 function normalizeTopicToken(value) {
     return value.trim().toLowerCase().replaceAll("_", "-");
@@ -518,6 +518,8 @@ const GUIDE_TOPICS = [
         intent: "Use this when more than one agent or worktree mutates the same tracker and the results must merge without hand resolution.",
         commands: [
             "pm merge install",
+            "pm merge report",
+            "pm merge reconcile --dry-run",
             "pm claim <ID>",
             "pm release <ID>",
             "pm validate --check-history-drift",
@@ -530,6 +532,17 @@ const GUIDE_TOPICS = [
                 prompt: "Run the merge installer in every fresh clone or worktree before the first branch merge of tracker data.",
                 commands: ["pm merge install", "pm health --check-only"],
             },
+            {
+                name: "Settle A Merge Before Trusting Health",
+                goal: "A lossless merge still leaves pending receipts that strict health reports until they are reconciled.",
+                prompt: "After any branch merge that touched tracker data, read the merge report, preview the reconciliation, then apply it; only then treat a health verdict as a statement about the data.",
+                commands: [
+                    "pm merge report",
+                    "pm merge reconcile --dry-run",
+                    'pm merge reconcile --message "Post-merge history reconciliation"',
+                    "pm health --check-only",
+                ],
+            },
             {
                 name: "Hand Work Between Agents Safely",
                 goal: "Ownership and evidence survive the handoff.",
@@ -553,6 +566,107 @@ const GUIDE_TOPICS = [
         ],
         related: ["workflows", "assurance", "commands"],
     },
+    {
+        id: "evidence",
+        aliases: ["record", "annotations", "learnings", "history-maintenance"],
+        title: "Evidence, Durable Knowledge, and Record Maintenance",
+        summary: "Append comments, notes, learnings, files, docs, and tests to items, and maintain the immutable history those records live in.",
+        intent: "Use this when work must be explained to the next agent, when a durable lesson should outlive the item, or when a history stream needs verification, repair, redaction, compaction, or author attribution.",
+        commands: [
+            'pm comments <ID> "<progress or verification evidence>"',
+            'pm notes <ID> --add "<rationale that belongs on the item>"',
+            'pm learnings <ID> --add "<lesson that should outlive the item>"',
+            "pm append <ID> --body -",
+            "pm files <ID> --add path=<path>,scope=project,note=<why>",
+            "pm history <ID> --verify --strict-exit",
+            "pm history-repair --all --dry-run",
+            "pm history-redact <ID> --literal <secret> --dry-run",
+            "pm history-compact <ID> --dry-run",
+            "pm history-author-acknowledge --all-actionable --dry-run",
+            "pm close-many --ids <ID>,<ID> --reason <text> --dry-run",
+            "pm test-all --status open --limit 10 --progress",
+        ],
+        workflows: [
+            {
+                name: "Record While Working, Not After",
+                goal: "Another agent can rebuild the full situation from the item alone.",
+                prompt: "Add a comment for each verified step, a note for each rationale the item body does not carry, and a learning for each lesson that applies beyond this item. Prefer appending over rewriting.",
+                commands: [
+                    'pm comments <ID> "Evidence: <what changed and what passed>"',
+                    'pm notes <ID> --add "Decision log: <why this shape>"',
+                    'pm learnings <ID> --add "<durable lesson>"',
+                    "pm learnings <ID> --limit 5",
+                ],
+            },
+            {
+                name: "Verify And Repair A History Stream",
+                goal: "Every mutation stays provable and the chain re-anchors after drift.",
+                prompt: "Verify the chain with a strict exit before trusting a stream, preview any repair, and record why the repair was needed in the audit message.",
+                commands: [
+                    "pm history <ID> --verify --strict-exit",
+                    "pm history-repair --all --dry-run",
+                    'pm history-repair --all --message "<why the chain drifted>"',
+                    "pm validate --check-history-drift",
+                ],
+            },
+            {
+                name: "Redact, Compact, Or Attribute Without Losing Proof",
+                goal: "Sensitive text, stream length, and unknown authors are handled through audited rewrites.",
+                prompt: "Preview every history rewrite with --dry-run, read the receipt, then apply. Compaction renumbers ordinal versions, so record the checkpoint it created.",
+                commands: [
+                    "pm history-redact <ID> --literal <secret> --dry-run",
+                    "pm history-compact <ID> --dry-run",
+                    "pm history-author-acknowledge --all-actionable --dry-run",
+                ],
+            },
+        ],
+        docs: [
+            {
+                path: "docs/COMMANDS.md",
+                purpose: "Annotation, bulk, and history-and-recovery command families.",
+            },
+            {
+                path: "docs/MUTATION_INTEGRITY.md",
+                purpose: "Provenance and content-safety policy every mutation shares.",
+            },
+            {
+                path: "docs/AGENT_GUIDE.md",
+                purpose: "Evidence expectations in the agent loop and self-repair remediation.",
+            },
+        ],
+        related: ["workflows", "assurance", "merge", "graph"],
+    },
+    {
+        id: "automation",
+        aliases: ["calendar", "reminders", "meetings", "events"],
+        title: "Reminders, Events, and Meetings",
+        summary: "Attach time to items so context and agenda views can surface deadlines, meetings, and reminders when they matter.",
+        intent: "Use this when an item needs a due signal, a scheduled event, or a meeting record that later context reads should surface.",
+        commands: [
+            "pm remind <title> --at <when> --parent <ID>",
+            "pm event <title> --start <when> --parent <ID>",
+            "pm meet <title> --start <when> --duration <span> --parent <ID>",
+            "pm context --limit 10",
+        ],
+        workflows: [
+            {
+                name: "Put A Deadline Where Context Will Find It",
+                goal: "Time-bound work surfaces in the agenda section of context reads.",
+                prompt: "Record the reminder or event under the item that owns the work, then confirm it appears in the agenda summary of a context read.",
+                commands: [
+                    "pm remind <title> --at <when> --parent <ID>",
+                    "pm context --limit 10",
+                ],
+            },
+        ],
+        docs: [
+            {
+                path: "docs/COMMANDS.md",
+                purpose: "Calendar and context command family.",
+            },
+        ],
+        related: ["workflows", "quickstart", "extensions"],
+    },
 ];
 const TOPIC_BY_TOKEN = new Map();
 for (const topic of GUIDE_TOPICS) {
@@ -591,4 +705,4 @@ export function resolveGuideTopic(rawTopic) {
     return TOPIC_BY_TOKEN.get(normalized) ?? null;
 }
 //# sourceMappingURL=guide-topics.js.map
-//# debugId=7c57f381-8318-5235-aa92-c96c6cedb021
+//# debugId=feba1227-c2a2-5ca3-83e6-3fd2780e6cbb

package/dist/sdk/history/salvage.d.ts

@@ -0,0 +1,35 @@
+import { type HistoryItemHashVersion } from "../../core/history/history.js";
+import type { ItemTypeRegistry } from "../../core/item/type-registry.js";
+import type { HistoryEntry, PmSettings } from "../../types/index.js";
+import type { HistorySubject } from "../history-redact.js";
+import type { HistoryRepairCommandOptions, HistoryRepairResult } from "../history-repair.js";
+/** Evidence describing only the discarded suffix, without retaining its contents. */
+export interface HistorySalvageReceipt {
+    /** One-based physical line where invalid trailing bytes begin. */
+    first_invalid_line: number;
+    /** UTF-8 bytes removed from the suffix. */
+    discarded_bytes: number;
+    /** SHA-256 of the removed bytes for local backup comparison. */
+    discarded_sha256: string;
+    /** Number of complete verified records retained. */
+    retained_entries: number;
+}
+/**
+ * Select a hash-verified prefix. Any parseable JSON after the first invalid
+ * line makes the corruption interior and therefore unsalvageable by truncation.
+ */
+export declare function inspectHistoryTail(raw: string): {
+    entries: HistoryEntry[];
+    prefix: string;
+    receipt: HistorySalvageReceipt | null;
+    itemHashVersion: HistoryItemHashVersion;
+};
+/** Salvage one explicitly selected stream under its normal ownership and lock policy. */
+export declare function salvageHistoryTail(params: {
+    pmRoot: string;
+    subject: HistorySubject;
+    settings: PmSettings;
+    typeRegistry: ItemTypeRegistry;
+    options: HistoryRepairCommandOptions;
+    author: string;
+}): Promise<HistoryRepairResult>;

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]="7570ecac-7f15-5a1b-9b2d-2f1744a00720")}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, hashHistoryStream, resealHistoryRewrite, } 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(resealHistoryRewrite(entry, {
-            ...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,9 +145,9 @@ 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()),
@@ -172,6 +156,8 @@ function buildHistoryCompactEntries(params) {
         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",
@@ -179,7 +165,15 @@ function buildHistoryCompactEntries(params) {
             },
         },
     });
-    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(),
@@ -279,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,
@@ -530,4 +525,4 @@ export async function runHistoryCompactBulk(options, global) {
     };
 }
 //# sourceMappingURL=history-compact.js.map
-//# debugId=7570ecac-7f15-5a1b-9b2d-2f1744a00720
+//# 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