@unbrained/pm-cli 2026.9.3 → 2026.9.5

package/dist/core/history/identity.d.ts

@@ -0,0 +1,15 @@
+/** @module core/history/identity
+ * Identifies multiple genesis records without inferring an unrecorded writer.
+ */
+import type { HistoryEntry } from "../../types/index.js";
+/** Evidence of a second subject occupying one append-only identity stream. */
+export interface HistoryIdentityDiscontinuity {
+    /** One-based physical ordinal of the original create or retained baseline. */
+    prior_genesis_index: number;
+    /** One-based physical ordinal of the later create record. */
+    repeated_create_index: number;
+    /** Observed record sequence, not an assertion about branch or writer origin. */
+    sequence: "delete_then_create" | "multiple_creates" | "checkpoint_then_create";
+}
+/** Find every repeated genesis, including histories that start at a checkpoint. */
+export declare function findHistoryIdentityDiscontinuities(entries: readonly HistoryEntry[]): HistoryIdentityDiscontinuity[];

package/dist/core/history/identity.js

@@ -0,0 +1,31 @@
+/** Find every repeated genesis, including histories that start at a checkpoint. */
+
+!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]="ffaea7bd-daa4-5ff5-8cd5-82ad04e2256e")}catch(e){}}();
+export function findHistoryIdentityDiscontinuities(entries) {
+    const findings = [];
+    const checkpoint = entries[0]?.op === "history_compact_baseline";
+    let genesis = checkpoint ? 1 : undefined;
+    let deleted = false;
+    for (const [index, entry] of entries.entries()) {
+        if (entry.op === "delete")
+            deleted = true;
+        if (entry.op !== "create")
+            continue;
+        if (genesis !== undefined) {
+            findings.push({
+                prior_genesis_index: genesis,
+                repeated_create_index: index + 1,
+                sequence: deleted
+                    ? "delete_then_create"
+                    : checkpoint
+                        ? "checkpoint_then_create"
+                        : "multiple_creates",
+            });
+        }
+        genesis ??= index + 1;
+        deleted = false;
+    }
+    return findings;
+}
+//# sourceMappingURL=identity.js.map
+//# debugId=ffaea7bd-daa4-5ff5-8cd5-82ad04e2256e

package/dist/core/history/projection.js

@@ -6,10 +6,11 @@
  * replay kernel so read and write paths cannot disagree about a version.
  */
 
-!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]="47c087c2-124a-58b7-a5c9-09403235f4a2")}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]="2efbffc1-722c-5f3a-9ca5-e4e7a4f97729")}catch(e){}}();
 import { EXIT_CODE } from "../shared/constants.js";
 import { PmCliError } from "../shared/errors.js";
-import { EMPTY_REPLAY_DOCUMENT, replayHash, tryApplyReplayPatch, } from "./replay.js";
+import { historyVersionOffset } from "./version-address.js";
+import { EMPTY_REPLAY_DOCUMENT, verifyHistoryChain, tryApplyReplayPatch, } from "./replay.js";
 /** Find the final history entry recorded at or before a parsed timestamp. */
 function findHistoryIndexAtTimestamp(history, parsedTarget) {
     let historyIndex = -1;
@@ -25,7 +26,7 @@ function findHistoryIndexAtTimestamp(history, parsedTarget) {
     return historyIndex;
 }
 /** Build structured target-range guidance once for every resolver error path. */
-function buildHistoryTargetGuidance(history) {
+function buildHistoryTargetGuidance(history, offset) {
     const firstTimestamp = history[0]?.ts ?? null;
     const lastTimestamp = history.at(-1)?.ts ?? null;
     const guidance = {
@@ -44,9 +45,12 @@ function buildHistoryTargetGuidance(history) {
         },
     };
     if (lastTimestamp !== null) {
-        guidance.examples = ["1", String(history.length), lastTimestamp];
-        guidance.valid_range.first_version = 1;
-        guidance.valid_range.last_version = history.length;
+        guidance.examples = [lastTimestamp];
+        if (offset !== null) {
+            guidance.examples.unshift(String(offset + 1), String(offset + history.length));
+            guidance.valid_range.first_version = offset + 1;
+            guidance.valid_range.last_version = offset + history.length;
+        }
     }
     return { guidance, lastTimestamp };
 }
@@ -90,18 +94,25 @@ export function resolveHistoryTarget(target, history, options = {}) {
     const trimmed = target.trim();
     const errorSubject = options.errorSubject ?? "history";
     const errorSubjectTitle = errorSubject === "restore" ? "Restore" : "History";
-    const { guidance, lastTimestamp } = buildHistoryTargetGuidance(history);
+    const { guidance, lastTimestamp } = buildHistoryTargetGuidance(history, historyVersionOffset(history, true));
     if (!trimmed) {
         throw new PmCliError(`Missing ${errorSubject} target. Use a timestamp or version number.`, EXIT_CODE.USAGE, guidance);
     }
     if (/^\d+$/.test(trimmed)) {
+        const offset = historyVersionOffset(history);
         const version = Number(trimmed);
+        if (version >= 1 && version <= offset) {
+            throw new PmCliError(`History version ${version} was pruned by compaction.`, EXIT_CODE.USAGE, {
+                ...guidance,
+                code: "history_version_pruned",
+            });
+        }
         if (!Number.isSafeInteger(version) ||
             version < 1 ||
-            version > history.length) {
-            throw new PmCliError(`${errorSubjectTitle} version must be between 1 and ${history.length} for this item.`, EXIT_CODE.USAGE, guidance);
+            version > offset + history.length) {
+            throw new PmCliError(`${errorSubjectTitle} version must be between ${offset + 1} and ${offset + history.length} for this item.`, EXIT_CODE.USAGE, guidance);
         }
-        return { kind: "version", raw: trimmed, historyIndex: version - 1 };
+        return { kind: "version", raw: trimmed, historyIndex: version - offset - 1 };
     }
     const parsedTarget = Date.parse(trimmed);
     if (!Number.isFinite(parsedTarget)) {
@@ -137,28 +148,50 @@ export function applyHistoryPatch(current, patch, entryNumber, entryOp) {
 }
 /** Replay and hash-verify a history stream through a zero-based target entry. */
 export function replayHistoryToTarget(history, targetIndex) {
+    const first = history[0];
+    if (first && first.op !== "create" && first.op !== "history_compact_baseline") {
+        const baseline = tryApplyReplayPatch(EMPTY_REPLAY_DOCUMENT, first.patch);
+        if (!baseline.ok || typeof baseline.document.metadata.id !== "string") {
+            throw new PmCliError("History starts without a reconstructable item baseline.", EXIT_CODE.GENERIC_FAILURE, {
+                code: "history_baseline_unavailable",
+                required: "Recover the original create entry or a complete checkpoint from version control.",
+                nextSteps: ["Run pm history <id> --full to inspect the missing baseline."],
+            });
+        }
+    }
+    const selected = history.slice(0, targetIndex + 1);
+    const verification = verifyHistoryChain([...selected]);
     let document = structuredClone(EMPTY_REPLAY_DOCUMENT);
     for (let index = 0; index <= targetIndex; index += 1) {
         const entry = history[index];
         if (!entry) {
             throw new PmCliError(`History target entry ${index + 1} does not exist.`, EXIT_CODE.USAGE);
         }
-        if (replayHash(document) !== entry.before_hash) {
-            throw new PmCliError(`History hash mismatch before replay at entry ${index + 1}.`, EXIT_CODE.GENERIC_FAILURE);
-        }
         document = applyHistoryPatch(document, entry.patch, index + 1, entry.op);
-        if (replayHash(document) !== entry.after_hash) {
-            throw new PmCliError(`History hash mismatch after replay at entry ${index + 1}.`, EXIT_CODE.GENERIC_FAILURE);
-        }
+    }
+    if (!verification.ok) {
+        throw new PmCliError(`History cannot be replayed: ${verification.errors.join(", ")}.`, EXIT_CODE.GENERIC_FAILURE, {
+            code: "history_replay_invalid",
+            verification_errors: verification.errors,
+            required: "Inspect the history integrity findings before attempting recovery.",
+            nextSteps: ["Run pm history <id> --verify --full."],
+        });
     }
     return document;
 }
 /** Reject a version whose reconstructed state represents a deleted item. */
 export function ensureMaterializedHistoryTarget(replayDocument, target) {
     if (Object.keys(replayDocument.metadata).length > 0) {
+        if (typeof replayDocument.metadata.id !== "string" || !Array.isArray(replayDocument.metadata.tags)) {
+            throw new PmCliError("History has no complete item baseline for this target.", EXIT_CODE.GENERIC_FAILURE, {
+                code: "history_baseline_unavailable",
+                required: "Recover the original create entry or a complete checkpoint from version control.",
+                nextSteps: ["Run pm history <id> --full to inspect the first recorded state."],
+            });
+        }
         return replayDocument;
     }
     throw new PmCliError(`History target ${target.raw} resolves to a deleted state; choose a version or timestamp where the item exists.`, EXIT_CODE.USAGE);
 }
 //# sourceMappingURL=projection.js.map
-//# debugId=47c087c2-124a-58b7-a5c9-09403235f4a2
+//# debugId=2efbffc1-722c-5f3a-9ca5-e4e7a4f97729

package/dist/core/history/read.js

@@ -7,7 +7,7 @@
  * maintenance APIs from depending on presentation-layer modules.
  */
 
-!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]="aa65b74d-ef5d-57ed-b613-3034da52a8ba")}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]="999c126a-112a-50f6-b53e-bd36dbc5b885")}catch(e){}}();
 import { readFileIfExists } from "../fs/fs-utils.js";
 import { runActiveOnReadHooks } from "../extensions/index.js";
 import { EXIT_CODE } from "../shared/constants.js";
@@ -46,10 +46,13 @@ export async function readHistoryEntries(historyPath, itemId) {
             entries.push(JSON.parse(line));
         }
         catch {
-            throw new PmCliError(`History for ${itemId} contains invalid JSON at line ${index + 1}. Repair or restore the history stream and retry.`, EXIT_CODE.GENERIC_FAILURE);
+            throw new PmCliError(`History for ${itemId} contains invalid JSON at line ${index + 1}. Repair or restore the history stream and retry.`, EXIT_CODE.GENERIC_FAILURE, {
+                code: "history_json_invalid",
+                nextSteps: [`Run pm history-repair ${itemId} --salvage-tail --dry-run to check whether only an invalid suffix is damaged.`],
+            });
         }
     }
     return entries;
 }
 //# sourceMappingURL=read.js.map
-//# debugId=aa65b74d-ef5d-57ed-b613-3034da52a8ba
+//# debugId=999c126a-112a-50f6-b53e-bd36dbc5b885

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

@@ -47,7 +47,6 @@ export type ReplayApplyResult = {
 };
 /** Strictly apply a history patch (front_matter->metadata normalized) to a replay document. Returns a result envelope rather than throwing so each caller can format its own error contract. */
 export declare function tryApplyReplayPatch(current: ReplayDocument, patch: HistoryPatchOp[]): ReplayApplyResult;
-/** Deterministically verify a history chain: each entry's before_hash must equal the prior replayed after_hash, the patch must strictly apply, and the recorded after_hash must equal the replayed result. */
 /** Verify a chain and report the explicit or auto-detected item hash epoch. */
 export declare function verifyHistoryChainWithVersion(entries: HistoryEntry[]): {
     ok: boolean;
@@ -119,6 +118,6 @@ export interface ReanchorHistoryOptions {
  */
 export declare function resolveHistoryRepairItemHashVersion(entries: HistoryEntry[]): HistoryItemHashVersion;
 /** Re-anchor a drifted history chain: replay every entry from empty, recompute the before/after hashes, and only rewrite a patch when the original op set no longer strictly applies (legacy drift). Clean entries keep their patch verbatim so the on-disk diff stays minimal. The returned chain verifies via verifyHistoryChain. */
-export declare function reanchorHistoryEntries(entries: HistoryEntry[], itemHashVersion?: 1 | 2 | 3, options?: ReanchorHistoryOptions): ReanchorResult;
+export declare function reanchorHistoryEntries(entries: HistoryEntry[], itemHashVersion?: HistoryItemHashVersion, options?: ReanchorHistoryOptions): ReanchorResult;
 /** Implements history entries to raw for the public runtime surface of this module. */
 export declare function historyEntriesToRaw(entries: HistoryEntry[]): string;

package/dist/core/history/replay.js

@@ -4,13 +4,14 @@
  * 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]="c9488ed4-8228-5e7c-9717-69dd7a3275c4")}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]="b0230e20-93c4-531c-9cc1-85f85c1def7a")}catch(e){}}();
 import jsonPatch from "fast-json-patch";
+import { findHistoryIdentityDiscontinuities } from "./identity.js";
 import { ITEM_METADATA_KEY_ORDER } from "../shared/constants.js";
 import { canonicalDocument } from "../item/item-format.js";
 import { toItemRecord } from "../item/item-record.js";
 import { orderObject, sha256Hex, stableStringify, } from "../shared/serialization.js";
-import { CURRENT_HISTORY_ITEM_HASH_VERSION, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, hashDocumentVerificationCandidates, } from "./history.js";
+import { CURRENT_HISTORY_ITEM_HASH_VERSION, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, hashDocumentVerificationCandidates, resealHistoryRewrite, verifyHistoryRecordHash, verifyHistoryRewriteEvidence, } from "./history.js";
 /** Public contract for empty replay document, shared by SDK and presentation-layer consumers. */
 export const EMPTY_REPLAY_DOCUMENT = {
     metadata: {},
@@ -165,13 +166,37 @@ function historyEntryHashCandidates(explicitVersion, authoritativeVersion) {
         ? [...SUPPORTED_HISTORY_ITEM_HASH_VERSIONS]
         : [authoritativeVersion];
 }
-/** Deterministically verify a history chain: each entry's before_hash must equal the prior replayed after_hash, the patch must strictly apply, and the recorded after_hash must equal the replayed result. */
+/** Return the first record or retained-rewrite integrity failure for one entry. */
+function historyEntryIntegrityError(entry) {
+    const recordVerification = verifyHistoryRecordHash(entry);
+    if (!recordVerification.ok)
+        return recordVerification.error;
+    const rewriteVerification = verifyHistoryRewriteEvidence(entry);
+    return rewriteVerification.ok ? undefined : rewriteVerification.error;
+}
+/** Validate immutable metadata and apply one patch for chain verification. */
+function verifyHistoryEntryInput(entry, replay) {
+    const integrityError = historyEntryIntegrityError(entry);
+    if (integrityError)
+        return { ok: false, error: integrityError };
+    const applied = tryApplyReplayPatch(replay, entry.patch);
+    return applied.ok
+        ? { ok: true, document: applied.document }
+        : { ok: false, error: "patch_apply_failed" };
+}
+/** Refuse any entry whose current or retained immutable envelope is invalid. */
+function assertHistoryEntryIntegrity(entry, index) {
+    const integrityError = historyEntryIntegrityError(entry);
+    if (integrityError) {
+        throw new TypeError(`${integrityError}:entry_${index + 1}`);
+    }
+}
 /** Verify a chain and report the explicit or auto-detected item hash epoch. */
 export function verifyHistoryChainWithVersion(entries) {
     let replay = cloneEmptyReplayDocument();
     let detectedVersion;
     let authoritativeExplicitVersion;
-    const errors = [];
+    const errors = findHistoryIdentityDiscontinuities(entries).map((finding) => `verify_failed:duplicate_create:entry_${finding.repeated_create_index}:prior_${finding.prior_genesis_index}`);
     for (let index = 0; index < entries.length; index += 1) {
         const entry = entries[index];
         const explicitVersion = entry.item_hash_version;
@@ -179,18 +204,15 @@ export function verifyHistoryChainWithVersion(entries) {
         if (unsupportedVersion) {
             errors.push(`verify_failed:unsupported_item_hash_version:${String(explicitVersion)}:entry_${index + 1}`);
         }
-        const applied = tryApplyReplayPatch(replay, entry.patch);
-        if (!applied.ok) {
+        const input = verifyHistoryEntryInput(entry, replay);
+        if (!input.ok) {
             return {
                 ok: false,
-                errors: [
-                    ...errors,
-                    `verify_failed:patch_apply_failed:entry_${index + 1}`,
-                ],
+                errors: [...errors, `verify_failed:${input.error}:entry_${index + 1}`],
             };
         }
         if (unsupportedVersion) {
-            replay = applied.document;
+            replay = input.document;
             detectedVersion = undefined;
             authoritativeExplicitVersion = undefined;
             continue;
@@ -201,7 +223,7 @@ export function verifyHistoryChainWithVersion(entries) {
         const candidates = historyEntryHashCandidates(explicitVersion, authoritativeExplicitVersion);
         const candidateMatches = candidates.map((version) => ({
             version,
-            match: matchReplayHashCandidates(replay, applied.document, version, entry),
+            match: matchReplayHashCandidates(replay, input.document, version, entry),
         }));
         const matchingVersion = candidateMatches.find(({ match }) => match.pairIndex >= 0);
         if (matchingVersion === undefined) {
@@ -215,7 +237,7 @@ export function verifyHistoryChainWithVersion(entries) {
             };
         }
         const version = matchingVersion.version;
-        replay = applied.document;
+        replay = input.document;
         detectedVersion = version;
         authoritativeExplicitVersion =
             explicitVersion ??
@@ -304,6 +326,27 @@ export function resolveHistoryRepairItemHashVersion(entries) {
     }
     return CURRENT_HISTORY_ITEM_HASH_VERSION;
 }
+/** Apply one patch strictly or return its deterministic lenient repair projection. */
+function applyReanchorPatch(replay, entry) {
+    const strict = tryApplyReplayPatch(replay, entry.patch);
+    if (strict.ok) {
+        return {
+            next: strict.document,
+            patch: entry.patch,
+            repaired: false,
+            converted: 0,
+            skipped: 0,
+        };
+    }
+    const lenient = lenientApplyReplayPatch(replay, entry.patch);
+    return {
+        next: lenient.document,
+        patch: jsonPatch.compare(replay, lenient.document),
+        repaired: true,
+        converted: lenient.convertedReplaceToAdd,
+        skipped: lenient.skippedOps,
+    };
+}
 /** Re-anchor a drifted history chain: replay every entry from empty, recompute the before/after hashes, and only rewrite a patch when the original op set no longer strictly applies (legacy drift). Clean entries keep their patch verbatim so the on-disk diff stays minimal. The returned chain verifies via verifyHistoryChain. */
 export function reanchorHistoryEntries(entries, itemHashVersion = resolveHistoryRepairItemHashVersion(entries), options = {}) {
     const unsupportedIndex = entries.findIndex((entry) => isUnsupportedExplicitHistoryItemHashVersion(entry.item_hash_version));
@@ -322,27 +365,12 @@ export function reanchorHistoryEntries(entries, itemHashVersion = resolveHistory
         entries.some((entry) => entry.item_hash_version !== undefined);
     for (let index = 0; index < entries.length; index += 1) {
         const entry = entries[index];
-        const strict = tryApplyReplayPatch(replay, entry.patch);
-        let next;
-        let outPatch;
-        let patchRepaired = false;
-        let entryConverted = 0;
-        let entrySkipped = 0;
-        if (strict.ok) {
-            next = strict.document;
-            outPatch = entry.patch;
-        }
-        else {
-            const lenient = lenientApplyReplayPatch(replay, entry.patch);
-            next = lenient.document;
-            outPatch = jsonPatch.compare(replay, next);
-            patchRepaired = true;
-            entryConverted = lenient.convertedReplaceToAdd;
-            entrySkipped = lenient.skippedOps;
-            convertedReplaceToAdd += entryConverted;
-            skippedOps += entrySkipped;
-            entriesPatchRepaired += 1;
-        }
+        assertHistoryEntryIntegrity(entry, index);
+        const patchApplication = applyReanchorPatch(replay, entry);
+        const { next, patch: outPatch, repaired: patchRepaired, converted: entryConverted, skipped: entrySkipped, } = patchApplication;
+        convertedReplaceToAdd += entryConverted;
+        skippedOps += entrySkipped;
+        entriesPatchRepaired += Number(patchRepaired);
         const hashMatch = matchReplayHashCandidates(replay, next, itemHashVersion, entry);
         if (semanticIndex === undefined || options.continuousHashSurface !== true) {
             semanticIndex = [
@@ -361,7 +389,7 @@ export function reanchorHistoryEntries(entries, itemHashVersion = resolveHistory
         if (rehashed) {
             entriesRehashed += 1;
         }
-        const rewrittenEntry = {
+        let rewrittenEntry = {
             ...entry,
             patch: outPatch,
             before_hash: beforeHash,
@@ -373,6 +401,12 @@ export function reanchorHistoryEntries(entries, itemHashVersion = resolveHistory
         else {
             delete rewrittenEntry.item_hash_version;
         }
+        const versionChanged = rewrittenEntry.item_hash_version !== entry.item_hash_version;
+        if (rehashed || patchRepaired || versionChanged) {
+            rewrittenEntry = resealHistoryRewrite(entry, rewrittenEntry, {
+                retainOriginalPatch: patchRepaired,
+            });
+        }
         rewritten.push(rewrittenEntry);
         details.push({
             index: index + 1,
@@ -403,4 +437,4 @@ export function historyEntriesToRaw(entries) {
     return `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
 }
 //# sourceMappingURL=replay.js.map
-//# debugId=c9488ed4-8228-5e7c-9717-69dd7a3275c4
+//# debugId=b0230e20-93c4-531c-9cc1-85f85c1def7a

package/dist/core/history/version-address.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @module core/history/version-address
+ * Stable ordinal addressing for streams whose retained prefix is a checkpoint.
+ */
+import type { HistoryEntry } from "../../types/index.js";
+/**
+ * Return the number added to physical one-based positions to obtain durable
+ * version addresses. Legacy checkpoints cannot prove their original ordinal;
+ * refusing them prevents silently selecting a different historical state.
+ */
+export declare function historyVersionOffset(history: readonly HistoryEntry[], allowUnknown: true): number | null;
+/** Resolve a required durable offset, refusing ambiguous legacy checkpoints. */
+export declare function historyVersionOffset(history: readonly HistoryEntry[], allowUnknown?: false): number;

package/dist/core/history/version-address.js

@@ -0,0 +1,33 @@
+
+!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]="7ad4e6c0-7545-51cb-9af7-4ba1ad4c4758")}catch(e){}}();
+import { EXIT_CODE } from "../shared/constants.js";
+import { PmCliError } from "../shared/errors.js";
+/** Resolve the checkpoint offset with an explicit opt-in for unknown legacy addresses. */
+export function historyVersionOffset(history, allowUnknown = false) {
+    const first = history[0];
+    if (first?.op !== "history_compact_baseline")
+        return 0;
+    const receipt = first.context?.history_compaction;
+    const offset = typeof receipt === "object" &&
+        receipt !== null &&
+        "version_offset" in receipt
+        ? receipt.version_offset
+        : undefined;
+    if (typeof offset === "number" &&
+        Number.isSafeInteger(offset) &&
+        offset >= 0 &&
+        Number.isSafeInteger(offset + history.length)) {
+        return offset;
+    }
+    if (allowUnknown)
+        return null;
+    throw new PmCliError("This compacted stream has no trustworthy version offset; numeric history addresses are unavailable.", EXIT_CODE.USAGE, {
+        code: "history_version_mapping_unavailable",
+        required: "Use a retained timestamp or recover the pre-compaction stream from version control.",
+        nextSteps: [
+            "Run pm history <id> --full to inspect the retained timestamps and checkpoint evidence.",
+        ],
+    });
+}
+//# sourceMappingURL=version-address.js.map
+//# debugId=7ad4e6c0-7545-51cb-9af7-4ba1ad4c4758

package/dist/core/item/actionability.d.ts

@@ -1,5 +1,8 @@
 import type { RuntimeStatusRegistry } from "../schema/runtime-schema.js";
 import type { ItemMetadata, ItemStatus } from "../../types/index.js";
+import { type ItemTypeRegistry } from "./type-registry.js";
+/** Resolve dispatch semantics once for SDK callers, honoring custom and extension type aliases before built-in defaults. */
+export declare function resolveItemExecutionRole(type: string, registry?: ItemTypeRegistry): "agent" | "human" | "gate";
 /** Built-in ordering kinds that must remain reachable by blocker resolution. */
 export declare const ACTIONABILITY_ORDERING_KINDS: readonly string[];
 /** Collects the blocker item ids declared by an item: the legacy scalar `blocked_by` field plus every `blocked_by` dependency edge. Ids are trimmed, de-duplicated, and returned in stable lexicographic order. This is the single source of truth for "what must close before this item can proceed", shared by `pm next` readiness classification and the close-time auto-unblock sweep. */
@@ -54,11 +57,28 @@ export interface ActionabilityReport {
     ready: ActionableEntry[];
     /** Active leaves with at least one open blocker — waiting to become ready. */
     blocked: ActionableEntry[];
+    /** Active containers with unresolved descendants, including their blocker evidence. */
+    containers: ActionableEntry[];
+    /** Unblocked leaf work that requires a human decision. */
+    decisions: ActionableEntry[];
+    /** Unblocked leaf outcome gates held out of automatic dispatch. */
+    gates: ActionableEntry[];
     /** Active candidates considered before the leaf/blocker split. */
     active_count: number;
     /** Active candidates skipped because they still have open descendants. */
     container_count: number;
 }
+/** Explicit dispatch opt-ins; dependency and lifecycle blocking always remain enforced. */
+export interface ActionabilitySelectionOptions {
+    /** Include human decision work in the executable selection. */
+    includeDecisions?: boolean;
+    /** Include outcome gates in the executable selection. */
+    includeGates?: boolean;
+    /** Include containers whose descendants are still unfinished. */
+    includeContainers?: boolean;
+}
+/** Select dispatch candidates from a classified report while retaining held-out worklists. Ownership and ranking remain caller responsibilities. */
+export declare function selectActionableEntries(report: ActionabilityReport, statusRegistry: RuntimeStatusRegistry, options?: ActionabilitySelectionOptions, typeRegistry?: ItemTypeRegistry): Pick<ActionabilityReport, "ready" | "decisions" | "gates">;
 /**
  * Partitions a candidate set into ready vs blocked leaf work using the corpus to
  * resolve blockers, descendants, and downstream dependents.
@@ -70,4 +90,4 @@ export interface ActionabilityReport {
  * blockers and the non-terminal items it would unblock. Returned lists preserve
  * the candidate order so the caller can apply its own ranking.
  */
-export declare function computeActionabilityReport(candidates: ItemMetadata[], corpus: ItemMetadata[], statusRegistry: RuntimeStatusRegistry): ActionabilityReport;
+export declare function computeActionabilityReport(candidates: ItemMetadata[], corpus: ItemMetadata[], statusRegistry: RuntimeStatusRegistry, typeRegistry?: ItemTypeRegistry): ActionabilityReport;

package/dist/core/item/actionability.js

@@ -10,9 +10,15 @@
  * `blocked_by` resolution a single source of truth.
  */
 
-!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]="0605f770-d868-5fe9-a186-45f00d2e93b4")}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]="7d98ca40-57e8-5afe-8e9d-b694da0130d1")}catch(e){}}();
 import { isTerminalStatus, normalizeStatusForRegistry } from "./status.js";
+import { BUILTIN_ITEM_EXECUTION_ROLES, resolveTypeDefinition } from "./type-registry.js";
 import { isExternalDependencyReference, isExternalDependencySourceKind, } from "./dependency-reference.js";
+/** Resolve dispatch semantics once for SDK callers, honoring custom and extension type aliases before built-in defaults. */
+export function resolveItemExecutionRole(type, registry) {
+    const definition = registry === undefined ? undefined : resolveTypeDefinition(type, registry);
+    return definition?.execution_role ?? BUILTIN_ITEM_EXECUTION_ROLES[type.trim().toLowerCase()] ?? "agent";
+}
 /** Dependency kind that marks "this item is blocked by the referenced item". */
 const BLOCKED_BY_DEPENDENCY_KIND = "blocked_by";
 /** Reverse dependency kind that marks "this item blocks the referenced item". */
@@ -177,6 +183,24 @@ export function collectDependencyBlockedIds(corpus, statusRegistry) {
     }
     return blocked;
 }
+/** Select dispatch candidates from a classified report while retaining held-out worklists. Ownership and ranking remain caller responsibilities. */
+export function selectActionableEntries(report, statusRegistry, options = {}, typeRegistry) {
+    const candidates = [...report.ready, ...report.decisions, ...report.gates];
+    if (options.includeContainers === true) {
+        candidates.push(...report.containers.filter((entry) => entry.open_blockers.length === 0 && !statusRegistry.blocked_statuses.has(normalizeStatusForRegistry(entry.item.status, statusRegistry))));
+    }
+    const selected = { ready: [], decisions: [], gates: [] };
+    for (const entry of candidates) {
+        const role = resolveItemExecutionRole(entry.item.type, typeRegistry);
+        if (role === "human" && options.includeDecisions !== true)
+            selected.decisions.push(entry);
+        else if (role === "gate" && options.includeGates !== true)
+            selected.gates.push(entry);
+        else
+            selected.ready.push(entry);
+    }
+    return selected;
+}
 /** Resolves the registry's active status set, falling back to just the canonical open status when a custom schema declares none — the same safety net `pm context` applies so the report never misclassifies every item as inactive. */
 function resolveActiveStatusSet(statusRegistry) {
     /* c8 ignore start -- fallback applies only to custom schemas that intentionally define zero active statuses */
@@ -242,7 +266,7 @@ function indexCorpus(corpus) {
  * blockers and the non-terminal items it would unblock. Returned lists preserve
  * the candidate order so the caller can apply its own ranking.
  */
-export function computeActionabilityReport(candidates, corpus, statusRegistry) {
+export function computeActionabilityReport(candidates, corpus, statusRegistry, typeRegistry) {
     const { itemsById, childrenByParent, blockedByReverse, blockerIdsByItem } = indexCorpus(corpus);
     const activeStatuses = new Set([
         ...resolveActiveStatusSet(statusRegistry),
@@ -255,16 +279,14 @@ export function computeActionabilityReport(candidates, corpus, statusRegistry) {
         .map((entry) => normalizeItemId(entry.id)));
     const ready = [];
     const blocked = [];
+    const containers = [];
+    const decisions = [];
+    const gates = [];
     let activeCount = 0;
-    let containerCount = 0;
     for (const item of candidates) {
         if (!activeStatuses.has(normalizeStatusForRegistry(item.status, statusRegistry)))
             continue;
         activeCount += 1;
-        if (hasOpenDescendant(item.id, childrenByParent, statusRegistry)) {
-            containerCount += 1;
-            continue;
-        }
         const openBlockers = resolveItemBlockersWithIndex(item, itemsById, statusRegistry, blockerIdsByItem).filter((blocker) => !blocker.resolved);
         const unblocks = (blockedByReverse.get(normalizeItemId(item.id)) ?? [])
             .filter((dependentId) => nonTerminalIds.has(normalizeItemId(dependentId)))
@@ -274,9 +296,19 @@ export function computeActionabilityReport(candidates, corpus, statusRegistry) {
             open_blockers: openBlockers,
             unblocks,
         };
+        if (hasOpenDescendant(item.id, childrenByParent, statusRegistry)) {
+            containers.push(entry);
+            continue;
+        }
         const lifecycleBlocked = statusRegistry.blocked_statuses.has(normalizeStatusForRegistry(item.status, statusRegistry));
         if (openBlockers.length === 0 && !lifecycleBlocked) {
-            ready.push(entry);
+            const role = resolveItemExecutionRole(item.type, typeRegistry);
+            if (role === "human")
+                decisions.push(entry);
+            else if (role === "gate")
+                gates.push(entry);
+            else
+                ready.push(entry);
         }
         else {
             blocked.push(entry);
@@ -285,9 +317,12 @@ export function computeActionabilityReport(candidates, corpus, statusRegistry) {
     return {
         ready,
         blocked,
+        containers,
+        decisions,
+        gates,
         active_count: activeCount,
-        container_count: containerCount,
+        container_count: containers.length,
     };
 }
 //# sourceMappingURL=actionability.js.map
-//# debugId=0605f770-d868-5fe9-a186-45f00d2e93b4
+//# debugId=7d98ca40-57e8-5afe-8e9d-b694da0130d1

package/dist/core/item/id.js

@@ -4,7 +4,7 @@
  * Defines item parsing, formatting, and lifecycle helpers for Id.
  */
 
-!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]="6b3f1585-ab12-57ca-80eb-d3cebc384c52")}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]="04f02467-a4ee-5616-9fbf-3df1141efccf")}catch(e){}}();
 import crypto from "node:crypto";
 import path from "node:path";
 import { TYPE_TO_FOLDER } from "../shared/constants.js";
@@ -60,11 +60,13 @@ function randomToken(length) {
     }
     return token;
 }
+/** Reserve an identity when either a live item path or its retained history exists. */
 async function idExists(pmRoot, id, typeToFolder) {
     const checks = [...new Set(Object.values(typeToFolder))].flatMap((folder) => [
         path.join(pmRoot, folder, `${id}.md`),
         path.join(pmRoot, folder, `${id}.toon`),
     ]);
+    checks.push(path.join(pmRoot, "history", `${id}.jsonl`));
     return (await Promise.all(checks.map((target) => pathExists(target)))).some(Boolean);
 }
 /** Bounds accepted for the configurable random id token length (`ids.token_length`). */
@@ -95,8 +97,10 @@ export async function generateItemId(pmRoot, prefix, options = {}) {
     while (tokenLength <= maxTokenLength) {
         for (let i = 0; i < 32; i += 1) {
             const id = `${normalizePrefix(prefix)}${randomToken(tokenLength)}`;
-            if (options.probeExisting === false ||
-                !(await idExists(pmRoot, id, options.typeToFolder ?? TYPE_TO_FOLDER))) {
+            const occupied = await (options.probeExisting === false
+                ? pathExists(path.join(pmRoot, "history", `${id}.jsonl`))
+                : idExists(pmRoot, id, options.typeToFolder ?? TYPE_TO_FOLDER));
+            if (!occupied) {
                 return id;
             }
             attempts += 1;
@@ -106,4 +110,4 @@ export async function generateItemId(pmRoot, prefix, options = {}) {
     throw new Error(`Unable to generate unique id after ${attempts} attempts`);
 }
 //# sourceMappingURL=id.js.map
-//# debugId=6b3f1585-ab12-57ca-80eb-d3cebc384c52
+//# debugId=04f02467-a4ee-5616-9fbf-3df1141efccf