@unbrained/pm-cli 2026.9.4 → 2026.9.5

package/dist/core/extensions/extension-types.d.ts

@@ -839,6 +839,8 @@ export interface SchemaItemTypeDefinition {
     description?: string;
     /** Initial status assigned when the contributed item type is created. */
     default_status?: string;
+    /** Dispatch role inherited by next, context, and automatic claims. Gates track outcomes; human roles require decisions. */
+    execution_role?: "agent" | "human" | "gate";
     /** Value that configures or reports required create fields for this contract. */
     required_create_fields?: string[];
     /** Value that configures or reports required create repeatables for this contract. */

package/dist/core/extensions/extension-types.js

@@ -1,6 +1,6 @@
 /** Public contract for known extension capabilities, shared by SDK and presentation-layer consumers. */
 
-!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]="ef5c8553-c206-5bb5-913a-85afb936f6d7")}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]="a2f05fd9-1331-5e75-b8c1-42ad6deb425e")}catch(e){}}();
 export const KNOWN_EXTENSION_CAPABILITIES = [
     "commands",
     "renderers",
@@ -100,4 +100,4 @@ export function createDefaultExtensionGovernancePolicy() {
     };
 }
 //# sourceMappingURL=extension-types.js.map
-//# debugId=ef5c8553-c206-5bb5-913a-85afb936f6d7
+//# debugId=a2f05fd9-1331-5e75-b8c1-42ad6deb425e

package/dist/core/history/drift-scan.d.ts

@@ -1,6 +1,11 @@
+import { type HistoryIdentityDiscontinuity } from "./identity.js";
 import type { ItemMetadata } from "../../types/index.js";
 /** Documents the drift scan result payload exchanged by command, SDK, and package integrations. */
 export interface DriftScanResult {
+    /** Repeated genesis ordinals and observed sequence, keyed by affected item. */
+    identityDiscontinuities?: Array<HistoryIdentityDiscontinuity & {
+        item_id: string;
+    }>;
     /** Value that configures or reports missing streams for this contract. */
     missingStreams: string[];
     /** Value that configures or reports unreadable streams for this contract. */

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

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1c6c65ef-115b-50e2-815e-84f6e91158cd")}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]="80648bfe-2436-5b5a-8a16-b9c2875f95fd")}catch(e){}}();
 import fs from "node:fs/promises";
 import { createHash } from "node:crypto";
 import path from "node:path";
@@ -7,12 +7,14 @@ import { getHistoryPath } from "../store/paths.js";
 import { isFileMissingError, writeFileAtomic } from "../fs/fs-utils.js";
 import { CURRENT_HISTORY_ITEM_HASH_VERSION, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, hashDocumentVerificationCandidates, } from "./history.js";
 import { verifyHistoryChainWithVersion } from "./replay.js";
+import { findHistoryIdentityDiscontinuities, } from "./identity.js";
 import { getWorkspaceHistoryPath, inspectWorkspaceHistoryState, WORKSPACE_HISTORY_ID, } from "./workspace-history.js";
-const DRIFT_CACHE_VERSION = 9;
+const DRIFT_CACHE_VERSION = 10;
 const DRIFT_CACHE_FILENAME = "history-drift-cache.json";
 function getDriftCachePath(pmRoot) {
     return path.join(pmRoot, "runtime", DRIFT_CACHE_FILENAME);
 }
+/** Discard unreadable or stale cache envelopes, including prior verification semantics. */
 async function loadDriftCache(pmRoot) {
     try {
         const raw = await fs.readFile(getDriftCachePath(pmRoot), "utf8");
@@ -123,6 +125,7 @@ async function verifyHistoryStream(historyPath) {
         : verification.item_hash_version;
     return {
         latestAfterHash,
+        identityDiscontinuities: findHistoryIdentityDiscontinuities(entries),
         chainOk: verification.ok,
         versionSkew,
         latestHashComparable: latestHashVersion !== undefined &&
@@ -153,15 +156,15 @@ async function loadFreshStreamVerification(itemId, historyPath, accumulator) {
         return null;
     }
 }
+/** Reverify invalid streams and content-sensitive cache hits; reuse only compatible healthy evidence. */
 async function resolveStreamVerification(params) {
     const cachedContentHash = typeof params.cached?.content_hash === "string" &&
         params.cached.content_hash.length > 0
         ? params.cached.content_hash
         : undefined;
     const canUseCache = cacheMetadataMatches(params.cached, params.stat) &&
-        cachedContentHash !== undefined &&
-        params.cached !== undefined;
-    if (!canUseCache || !params.cached) {
+        cachedContentHash !== undefined;
+    if (!canUseCache || !params.cached || !params.cached.chain_ok) {
         return {
             verification: await loadFreshStreamVerification(params.itemId, params.historyPath, params.accumulator),
             cacheDirty: true,
@@ -183,6 +186,7 @@ async function resolveStreamVerification(params) {
     }
     return {
         verification: {
+            identityDiscontinuities: [],
             latestAfterHash: params.cached.latest_after_hash,
             chainOk: params.cached.chain_ok,
             versionSkew: params.cached.version_skew === true,
@@ -217,6 +221,12 @@ async function scanItemHistory(pmRoot, item, cache, accumulator) {
     });
     if (!resolved.verification)
         return resolved.cacheDirty;
+    if (resolved.verification.identityDiscontinuities.length > 0) {
+        (accumulator.identityDiscontinuities ??= []).push(...resolved.verification.identityDiscontinuities.map((finding) => ({
+            ...finding,
+            item_id: item.id,
+        })));
+    }
     if (resolved.verification.versionSkew) {
         accumulator.versionSkews.push(item.id);
     }
@@ -330,4 +340,4 @@ export async function scanHistoryDrift(pmRoot, items, options = {}) {
     return { ...accumulator, driftedItems };
 }
 //# sourceMappingURL=drift-scan.js.map
-//# debugId=1c6c65ef-115b-50e2-815e-84f6e91158cd
+//# debugId=80648bfe-2436-5b5a-8a16-b9c2875f95fd

package/dist/core/history/event-classification.d.ts

@@ -10,7 +10,7 @@ export declare const HISTORY_EVENT_CLASSIFICATION_VERSION: 1;
 /** Semantic effect of an immutable history event on project recency. */
 export type HistoryEventClass = "substantive" | "maintenance";
 /** Operations whose meaning is always governance or storage maintenance. */
-export declare const MAINTENANCE_HISTORY_OPERATIONS: readonly ["docs_add", "files_add", "history:author-acknowledge", "history_author_acknowledge", "history_compact", "history_compact_baseline", "history_redact", "history_repair", "normalize", "release", "test_run_track", "tests_add", "tests_remove", "update_audit", "update_ownership_bypass"];
+export declare const MAINTENANCE_HISTORY_OPERATIONS: readonly ["docs_add", "files_add", "history:author-acknowledge", "history_author_acknowledge", "history_compact", "history_compact_baseline", "history_redact", "history_repair", "history_salvage", "normalize", "release", "test_run_track", "tests_add", "tests_remove", "update_audit", "update_ownership_bypass"];
 /** Operations whose meaning always advances lifecycle or working context. */
 export declare const SUBSTANTIVE_HISTORY_OPERATIONS: readonly ["append", "cancel", "claim", "close", "comment_add", "create", "learning_add", "note_add", "reopen"];
 /**

package/dist/core/history/event-classification.js

@@ -1,6 +1,6 @@
 /** Current version of the public history-event classification policy. */
 
-!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]="6398c65d-fb5c-5479-93c2-0be963352a92")}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]="9ad6614e-44bc-549c-915c-6177c3a43c1f")}catch(e){}}();
 export const HISTORY_EVENT_CLASSIFICATION_VERSION = 1;
 /** Operations whose meaning is always governance or storage maintenance. */
 export const MAINTENANCE_HISTORY_OPERATIONS = [
@@ -12,6 +12,7 @@ export const MAINTENANCE_HISTORY_OPERATIONS = [
     "history_compact_baseline",
     "history_redact",
     "history_repair",
+    "history_salvage",
     "normalize",
     "release",
     "test_run_track",
@@ -106,4 +107,4 @@ export function classifyHistoryEvent(entry) {
         : "substantive";
 }
 //# sourceMappingURL=event-classification.js.map
-//# debugId=6398c65d-fb5c-5479-93c2-0be963352a92
+//# debugId=9ad6614e-44bc-549c-915c-6177c3a43c1f

package/dist/core/history/history.js

@@ -4,8 +4,10 @@
  * Implements append-only history and replay behavior for 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]="bf6a9831-134c-5dc2-a3e2-74dca00cf22c")}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]="a5449fec-c5b4-5cf4-9a7f-b7c5dc7161c2")}catch(e){}}();
 import jsonPatch from "fast-json-patch";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { EXIT_CODE, ITEM_METADATA_KEY_ORDER } from "../shared/constants.js";
 import { runActiveServiceOverride } from "../extensions/index.js";
 import { appendLineAtomic } from "../fs/fs-utils.js";
@@ -539,7 +541,8 @@ async function applyHistoryAppendOverride(historyPath, entry, result) {
     if (result === false)
         return true;
     if (typeof result === "string") {
-        await appendLineAtomic(historyPath, serializeHistoryLine(result, entry));
+        const line = serializeHistoryLine(result, entry);
+        await appendHistoryLineWithIdentityReservation(historyPath, line);
         await invalidateHistoryDriftCacheForPath(historyPath);
         await removeHistoryEventIndexForHistoryPath(historyPath);
         return true;
@@ -550,11 +553,40 @@ async function applyHistoryAppendOverride(historyPath, entry, result) {
     if (record.skip === true)
         return true;
     const nextHistoryPath = typeof record.history_path === "string" ? record.history_path : historyPath;
-    await appendLineAtomic(nextHistoryPath, serializeHistoryLine(typeof record.line === "string" ? record.line : (record.entry ?? entry), entry));
+    const line = serializeHistoryLine(typeof record.line === "string" ? record.line : (record.entry ?? entry), entry);
+    await appendHistoryLineWithIdentityReservation(nextHistoryPath, line);
     await invalidateHistoryDriftCacheForPath(nextHistoryPath);
     await removeHistoryEventIndexForHistoryPath(nextHistoryPath);
     return true;
 }
+/** Exclusively create genesis streams at their effective destination; never remove a failed partial reservation. */
+async function appendHistoryLineWithIdentityReservation(historyPath, line) {
+    let record;
+    try {
+        record = JSON.parse(line);
+    }
+    catch {
+        // Legacy service overrides may provide non-JSON lines; verification diagnoses them.
+        record = null;
+    }
+    if (!isRecord(record) || record.op !== "create") {
+        await appendLineAtomic(historyPath, line);
+        return;
+    }
+    await fs.mkdir(path.dirname(historyPath), { recursive: true });
+    try {
+        await fs.writeFile(historyPath, `${line}\n`, { encoding: "utf8", flag: "wx" });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        throw new PmCliError("This item identity is reserved by an existing history stream.", EXIT_CODE.CONFLICT, {
+            code: "item_identity_reserved",
+            required: "Choose a new item ID or restore the original item from its history.",
+            nextSteps: ["Run pm history <id> --full, then pm restore <id> <version> to recover the original item."],
+        });
+    }
+}
 /** Implements append history entry for the public runtime surface of this module. */
 export async function appendHistoryEntry(historyPath, entry) {
     const override = await runActiveServiceOverride("history_append", {
@@ -573,7 +605,7 @@ export async function appendHistoryEntry(historyPath, entry) {
         event_class: classifyHistoryEvent(timestampedEntry),
     });
     await appendHistoryEntryWithEventIndex(historyPath, normalizedEntry, async () => {
-        await appendLineAtomic(historyPath, serializeHistoryLine(normalizedEntry, normalizedEntry));
+        await appendHistoryLineWithIdentityReservation(historyPath, serializeHistoryLine(normalizedEntry, normalizedEntry));
     });
     await invalidateHistoryDriftCacheForPath(historyPath);
 }
@@ -583,4 +615,4 @@ export const _testOnly = {
     isDefinedPointerPath,
 };
 //# sourceMappingURL=history.js.map
-//# debugId=bf6a9831-134c-5dc2-a3e2-74dca00cf22c
+//# debugId=a5449fec-c5b4-5cf4-9a7f-b7c5dc7161c2

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,8 +4,9 @@
  * 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]="ce8dfbdf-8471-5843-8179-5608140330e1")}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";
@@ -190,13 +191,12 @@ function assertHistoryEntryIntegrity(entry, index) {
         throw new TypeError(`${integrityError}:entry_${index + 1}`);
     }
 }
-/** 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 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;
@@ -437,4 +437,4 @@ export function historyEntriesToRaw(entries) {
     return `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
 }
 //# sourceMappingURL=replay.js.map
-//# debugId=ce8dfbdf-8471-5843-8179-5608140330e1
+//# 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;