@unbrained/pm-cli 2026.9.4 → 2026.9.6

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/extensions/module-graph-snapshot.js

@@ -5,7 +5,8 @@
  * verification.
  */
 
-!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]="e81790e9-3de2-5639-a84d-2c4714afbbf4")}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]="361b49b6-942e-55d9-9979-d72bc94721c6")}catch(e){}}();
+import { withHostEnvironmentBoundary } from "../fs/host-environment-errors.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 /**
@@ -23,11 +24,11 @@ export async function snapshotExtensionModuleGraph(snapshotRoot, extension) {
         throw new Error(`Cannot snapshot extension entry outside its package directory: ${extension.entry_path}`);
     }
     const snapshotDirectory = path.join(snapshotRoot, `${extension.layer}-${extension.directory.replace(/[^a-zA-Z0-9._-]/gu, "_")}`);
-    await fs.cp(sourceDirectory, snapshotDirectory, {
+    await withHostEnvironmentBoundary("extension_module_graph_snapshot", () => fs.cp(sourceDirectory, snapshotDirectory, {
         recursive: true,
         force: true,
-    });
+    }));
     return path.join(snapshotDirectory, relativeEntryPath);
 }
 //# sourceMappingURL=module-graph-snapshot.js.map
-//# debugId=e81790e9-3de2-5639-a84d-2c4714afbbf4
+//# debugId=361b49b6-942e-55d9-9979-d72bc94721c6

package/dist/core/fs/host-environment-errors.d.ts

@@ -0,0 +1,27 @@
+import { PmCliError } from "../shared/errors.js";
+/** Optional stable codes used by an existing SDK surface for each fault class. */
+export interface HostEnvironmentFaultCodeOverrides {
+    /** Code used for quota and storage exhaustion. */
+    capacity?: string;
+    /** Code used for access policy and read-only filesystems. */
+    permission?: string;
+    /** Code used for file-descriptor and memory exhaustion. */
+    resource?: string;
+}
+/** Context and compatibility controls for a host-environment boundary. */
+export interface HostEnvironmentBoundaryOptions {
+    /** Existing surface-specific codes that must remain compatible. */
+    codes?: HostEnvironmentFaultCodeOverrides;
+    /** Human explanation of why the operation needs host resources. */
+    why?: string;
+    /** Additional ordered recovery guidance. */
+    nextSteps?: readonly string[];
+    /** Copyable retry command when one is safe. */
+    suggestedRetry?: string;
+}
+/** Return a declared host errno only when it represents recoverable environment state. */
+export declare function classifyHostEnvironmentFault(error: unknown): string | null;
+/** Translate one known host fault into a stable path-redacted SDK refusal. */
+export declare function translateHostEnvironmentFault(error: unknown, operation: string, options?: HostEnvironmentBoundaryOptions): PmCliError | null;
+/** Run one SDK filesystem stage and translate only declared host faults. */
+export declare function withHostEnvironmentBoundary<T>(operation: string, run: () => Promise<T>, options?: HostEnvironmentBoundaryOptions): Promise<T>;

package/dist/core/fs/host-environment-errors.js

@@ -0,0 +1,142 @@
+/**
+ * @module core/fs/host-environment-errors
+ *
+ * Classifies host filesystem/resource failures at SDK boundaries without
+ * leaking local paths or swallowing genuine implementation defects.
+ */
+
+!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]="1262c682-2b8a-506f-a3e1-155ad682d763")}catch(e){}}();
+import { constants as osConstants } from "node:os";
+import { EXIT_CODE } from "../shared/constants.js";
+import { PmCliError } from "../shared/errors.js";
+const HOST_ENVIRONMENT_FAULTS = new Map([
+    [
+        "EACCES",
+        {
+            summary: "was denied filesystem permission",
+            recovery: "Grant the required filesystem access, then retry.",
+            category: "permission",
+        },
+    ],
+    [
+        "EDQUOT",
+        {
+            summary: "exceeded the filesystem quota",
+            recovery: "Raise or reclaim the filesystem quota, then retry.",
+            category: "capacity",
+        },
+    ],
+    [
+        "EMFILE",
+        {
+            summary: "exhausted the process file-descriptor limit",
+            recovery: "Close unused file handles or raise the process limit, then retry.",
+            category: "resource",
+        },
+    ],
+    [
+        "ENFILE",
+        {
+            summary: "exhausted the host file-descriptor limit",
+            recovery: "Free host file descriptors or raise the host limit, then retry.",
+            category: "resource",
+        },
+    ],
+    [
+        "ENOMEM",
+        {
+            summary: "ran out of available memory",
+            recovery: "Free memory or reduce concurrent work, then retry.",
+            category: "resource",
+        },
+    ],
+    [
+        "ENOSPC",
+        {
+            summary: "ran out of storage space",
+            recovery: "Free storage on the filesystem holding the project, then retry.",
+            category: "capacity",
+        },
+    ],
+    [
+        "EPERM",
+        {
+            summary: "was denied by the host permission policy",
+            recovery: "Grant the required filesystem permission, then retry.",
+            category: "permission",
+        },
+    ],
+    [
+        "EROFS",
+        {
+            summary: "targeted a read-only filesystem",
+            recovery: "Use a writable project filesystem or remount it read-write, then retry.",
+            category: "permission",
+        },
+    ],
+]);
+const OPERATION_PATTERN = /^[a-z][a-z0-9_]{0,63}$/u;
+const HOST_ENVIRONMENT_ERRNO_NAMES = new Map([
+    [osConstants.errno.EACCES, "EACCES"],
+    [osConstants.errno.EDQUOT, "EDQUOT"],
+    [osConstants.errno.EMFILE, "EMFILE"],
+    [osConstants.errno.ENFILE, "ENFILE"],
+    [osConstants.errno.ENOMEM, "ENOMEM"],
+    [osConstants.errno.ENOSPC, "ENOSPC"],
+    [osConstants.errno.EPERM, "EPERM"],
+    [osConstants.errno.EROFS, "EROFS"],
+].filter(([errno]) => Number.isInteger(errno)));
+const HOST_ENVIRONMENT_FAULT_CODES = {
+    capacity: { code: "host_environment_capacity_fault" },
+    permission: { code: "host_environment_permission_fault" },
+    resource: { code: "host_environment_resource_fault" },
+};
+/** Return a declared host errno only when it represents recoverable environment state. */
+export function classifyHostEnvironmentFault(error) {
+    if (typeof error !== "object" || error === null) {
+        return null;
+    }
+    const errorRecord = error;
+    if (typeof errorRecord.code === "string" &&
+        HOST_ENVIRONMENT_FAULTS.has(errorRecord.code)) {
+        return errorRecord.code;
+    }
+    if (typeof errorRecord.errno !== "number" ||
+        !Number.isInteger(errorRecord.errno)) {
+        return null;
+    }
+    return HOST_ENVIRONMENT_ERRNO_NAMES.get(Math.abs(errorRecord.errno)) ?? null;
+}
+/** Translate one known host fault into a stable path-redacted SDK refusal. */
+export function translateHostEnvironmentFault(error, operation, options = {}) {
+    const errno = classifyHostEnvironmentFault(error);
+    if (errno === null)
+        return null;
+    if (!OPERATION_PATTERN.test(operation)) {
+        throw new PmCliError("Host environment operation labels must be bounded identifiers.", EXIT_CODE.USAGE, { code: "host_environment_operation_invalid", field: "operation" });
+    }
+    const fault = HOST_ENVIRONMENT_FAULTS.get(errno);
+    return new PmCliError(`Host filesystem operation ${operation} ${fault.summary}.`, EXIT_CODE.GENERIC_FAILURE, {
+        code: options.codes?.[fault.category] ??
+            HOST_ENVIRONMENT_FAULT_CODES[fault.category].code,
+        reason: errno,
+        required: fault.recovery,
+        why: options.why ??
+            "The operating system refused a required project filesystem operation.",
+        nextSteps: [fault.recovery, ...(options.nextSteps ?? [])],
+        ...(options.suggestedRetry
+            ? { recovery: { suggested_retry: options.suggestedRetry } }
+            : {}),
+    });
+}
+/** Run one SDK filesystem stage and translate only declared host faults. */
+export async function withHostEnvironmentBoundary(operation, run, options = {}) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        throw translateHostEnvironmentFault(error, operation, options) ?? error;
+    }
+}
+//# sourceMappingURL=host-environment-errors.js.map
+//# debugId=1262c682-2b8a-506f-a3e1-155ad682d763

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;