@unbrained/pm-cli 2026.8.4 → 2026.8.5

package/dist/sdk/lifecycle-policy.js

@@ -5,7 +5,7 @@
  * item enters a terminal lifecycle state.
  */
 
-!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]="1433b857-3f29-5ef7-a5b3-8a70584df054")}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]="a7ae3c89-b50b-5e4f-8273-8318bc976d84")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 /** Default terminal policy shared by CLI, SDK, and MCP operations. */
@@ -36,22 +36,35 @@ export function resolveTerminalReason(input) {
 }
 /** Enforce close-reason governance without inventing immutable history content. */
 export function requireTerminalReason(input, required) {
+    return requireTerminalReasonWithRecovery(input, required, {
+        operation: "close",
+    });
+}
+/** Enforce close-reason governance with recovery for a specific operation. */
+export function requireTerminalReasonWithRecovery(input, required, recovery) {
     const resolution = resolveTerminalReason(input);
     if (!required || resolution.closeReason !== undefined) {
         return resolution;
     }
-    throw new PmCliError("Close reason text is required because governance.require_close_reason is enabled", EXIT_CODE.USAGE, {
-        code: "close_reason_required",
-        required: "Provide an author-controlled closing summary as the reason, message, resolution, or duplicate target.",
-        why: "governance.require_close_reason is enabled, so tools must not invent immutable closure evidence.",
-        examples: [
+    const examples = recovery.operation === "create"
+        ? [
+            `pm create --title "<title>" --type <type> --status ${recovery.status ?? "closed"} --close-reason "<closing summary>"`,
+            `pm create --title "<title>" --type <type> --status ${recovery.status ?? "closed"} --resolution "<resolution summary>"`,
+            `pm create --stdin-json < item.json`,
+        ]
+        : [
             'pm close <id> "Done: <what changed and why>"',
             'pm close <id> --reason "<closing summary>"',
             'pm close <id> -m "<closing summary>"',
             "pm close <id> --duplicate-of <canonical-id>",
-        ],
+        ];
+    throw new PmCliError("Close reason text is required because governance.require_close_reason is enabled", EXIT_CODE.USAGE, {
+        code: "close_reason_required",
+        required: "Provide an author-controlled closing summary as the reason, message, resolution, or duplicate target.",
+        why: "governance.require_close_reason is enabled, so tools must not invent immutable closure evidence.",
+        examples,
         nextSteps: [
-            "Re-run the terminal transition with a closing summary.",
+            `Re-run the ${recovery.operation} operation with a closing summary.`,
             "To stop requiring reasons, run: pm config set governance-require-close-reason --policy disabled",
         ],
     });
@@ -105,4 +118,4 @@ export function applyTerminalOrderingPolicy(metadata, policy) {
     };
 }
 //# sourceMappingURL=lifecycle-policy.js.map
-//# debugId=1433b857-3f29-5ef7-a5b3-8a70584df054
+//# debugId=a7ae3c89-b50b-5e4f-8273-8318bc976d84

package/dist/sdk/merge/driver.js

@@ -9,7 +9,7 @@
  * merge never corrupts tracker storage the way raw conflict markers do.
  */
 
-!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]="9426a3fa-19bd-598f-90f6-df26a03bd9eb")}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]="182fee45-4de8-502d-8aec-84b5b8e4aecb")}catch(e){}}();
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
@@ -164,7 +164,10 @@ export async function runMergeDriver(options, global) {
     }
     const guidance = [];
     if (conflicts.length > 0) {
-        guidance.push(`Both branches changed ${conflicts.join(", ")}; the ${preferred} value was kept. Review the merged file, re-apply the losing change if needed, then "git add" it.`);
+        const receiptGuidance = result.receipt === undefined
+            ? 'Run "pm merge report" to inspect clone-local merge evidence.'
+            : `Run "pm merge report" and correlate receipt ${result.receipt.receipt_id} with item ${result.receipt.item_id}; clone-local discarded values are never copied into this result.`;
+        guidance.push(`Both branches changed ${conflicts.join(", ")}; the ${preferred} value was kept. ${receiptGuidance} Review the merged file, re-apply the losing change if needed, then "git add" it.`);
     }
     if (artifact === "history" && result.history?.reanchored) {
         guidance.push('The merged history chain was re-anchored. Run "pm validate --check-history-drift" and "pm history-repair --all" after the merge to reconcile item state with merged history.');
@@ -181,4 +184,4 @@ export async function runMergeDriver(options, global) {
     };
 }
 //# sourceMappingURL=driver.js.map
-//# debugId=9426a3fa-19bd-598f-90f6-df26a03bd9eb
+//# debugId=182fee45-4de8-502d-8aec-84b5b8e4aecb

package/dist/sdk/output-contracts.d.ts

@@ -0,0 +1,67 @@
+/** Stable machine-readable result families used across pm transports. */
+export declare const PM_OUTPUT_ENVELOPE_KINDS: readonly ["mutation_receipt", "entity", "collection", "diagnostic", "stream"];
+/** Restricts portable result-envelope families. */
+export type PmOutputEnvelopeKind = (typeof PM_OUTPUT_ENVELOPE_KINDS)[number];
+/** Describes how one command exposes its default machine-readable result. */
+export interface PmCommandOutputEnvelopeContract {
+    /** Canonical command path. */
+    command: string;
+    /** Semantic result family. */
+    kind: PmOutputEnvelopeKind;
+    /** Root key carrying the primary value, or null for a flat receipt/stream. */
+    wrapper_key: string | null;
+    /** Whether the output can carry multiple primary rows. */
+    cardinality: "one" | "many" | "none";
+    /** Stable format-flag spelling accepted by every command. */
+    format_flag: "--json";
+}
+/** Normalized SDK representation of the flat CLI mutation receipt. */
+export interface PmMutationReceipt {
+    /** Mutated item or plan identifier. */
+    id: string;
+    /** Resulting lifecycle status or deletion outcome. */
+    status: string;
+    /** Number of fields changed by the mutation. */
+    changedFieldCount: number;
+    /** Persisted close reason when the command closed work. */
+    closeReason?: string;
+    /** Whether a destructive mutation removed its target. */
+    deleted?: boolean;
+    /** Status before the mutation when the command reports it. */
+    previousStatus?: string;
+    /** Non-fatal mutation warnings retained by the transport. */
+    warnings?: readonly unknown[];
+}
+/** Wire representation emitted by CLI mutation commands in JSON mode. */
+export interface PmCliMutationReceipt {
+    /** Mutated item or plan identifier. */
+    id: string;
+    /** Resulting lifecycle status or deletion outcome. */
+    status: string;
+    /** Number of fields changed by the mutation. */
+    changed_field_count: number;
+    /** Persisted close reason when the command closed work. */
+    close_reason?: string;
+    /** Whether a destructive mutation removed its target. */
+    deleted?: boolean;
+    /** Status before the mutation when the command reports it. */
+    previous_status?: string;
+    /** Non-fatal mutation warnings retained by the transport. */
+    warnings?: readonly unknown[];
+}
+/** Validate and preserve one package-authored output-envelope declaration. */
+export declare function definePmCommandOutputEnvelope<TContract extends PmCommandOutputEnvelopeContract>(contract: TContract): TContract;
+/** Default envelope declaration for every built-in command. */
+export declare const PM_COMMAND_OUTPUT_ENVELOPE_CONTRACTS: PmCommandOutputEnvelopeContract[];
+/** Resolve a built-in envelope or generate a conservative package fallback. */
+export declare function resolvePmCommandOutputEnvelope(command: string): PmCommandOutputEnvelopeContract;
+/** Return whether an unknown value is the flat CLI mutation receipt shape. */
+export declare function isPmMutationReceipt(value: unknown): value is PmCliMutationReceipt;
+/**
+ * Parse and normalize the flat JSON receipt emitted by mutation commands.
+ * Wrapped read envelopes are rejected so a wrong consumer assumption fails at
+ * the integration boundary instead of silently returning an undefined id.
+ */
+export declare function parseMutationReceipt(json: string): PmMutationReceipt;
+/** Parse and normalize an already decoded mutation receipt value. */
+export declare function parseMutationReceipt(value: unknown): PmMutationReceipt;

package/dist/sdk/output-contracts.js

@@ -0,0 +1,173 @@
+/**
+ * @module sdk/output-contracts
+ *
+ * Defines portable result-envelope contracts and safe mutation receipt parsing
+ * for CLI, SDK, MCP, and package 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]="af86d275-63a8-5205-a8b3-154efdbd8e2a")}catch(e){}}();
+import { PM_CORE_COMMAND_NAMES } from "./cli-contracts/enum-contracts.js";
+/** Stable machine-readable result families used across pm transports. */
+export const PM_OUTPUT_ENVELOPE_KINDS = [
+    "mutation_receipt",
+    "entity",
+    "collection",
+    "diagnostic",
+    "stream",
+];
+const MUTATION_COMMANDS = new Set([
+    "append",
+    "claim",
+    "close",
+    "close-task",
+    "copy",
+    "create",
+    "delete",
+    "focus",
+    "pause-task",
+    "release",
+    "restore",
+    "start-task",
+    "update",
+]);
+const COLLECTION_MUTATION_COMMANDS = new Set(["close-many", "update-many"]);
+const COLLECTION_COMMANDS = new Set([
+    "activity",
+    "comments",
+    "contracts",
+    "events",
+    "history",
+    "learnings",
+    "list",
+    "notes",
+    "search",
+]);
+const DIAGNOSTIC_COMMANDS = new Set([
+    "aggregate",
+    "deps",
+    "graph",
+    "health",
+    "stats",
+    "validate",
+]);
+/** Validate and preserve one package-authored output-envelope declaration. */
+export function definePmCommandOutputEnvelope(contract) {
+    if (contract.command.trim().length === 0) {
+        throw new TypeError("command must be a non-empty command path");
+    }
+    if (!PM_OUTPUT_ENVELOPE_KINDS.includes(contract.kind)) {
+        throw new TypeError(`Unsupported output envelope kind: ${contract.kind}`);
+    }
+    return contract;
+}
+function createOutputEnvelopeContract(command) {
+    const normalizedCommand = command.trim().replace(/\s+/gu, " ");
+    const [rootCommand = normalizedCommand] = normalizedCommand.split(" ");
+    if (COLLECTION_MUTATION_COMMANDS.has(rootCommand)) {
+        return definePmCommandOutputEnvelope({
+            command: normalizedCommand,
+            kind: "collection",
+            wrapper_key: "rows",
+            cardinality: "many",
+            format_flag: "--json",
+        });
+    }
+    if (MUTATION_COMMANDS.has(rootCommand)) {
+        return definePmCommandOutputEnvelope({
+            command: normalizedCommand,
+            kind: "mutation_receipt",
+            wrapper_key: null,
+            cardinality: "one",
+            format_flag: "--json",
+        });
+    }
+    if (COLLECTION_COMMANDS.has(rootCommand)) {
+        return definePmCommandOutputEnvelope({
+            command: normalizedCommand,
+            kind: "collection",
+            wrapper_key: rootCommand === "contracts" ? null : "items",
+            cardinality: "many",
+            format_flag: "--json",
+        });
+    }
+    if (DIAGNOSTIC_COMMANDS.has(rootCommand)) {
+        return definePmCommandOutputEnvelope({
+            command: normalizedCommand,
+            kind: "diagnostic",
+            wrapper_key: null,
+            cardinality: "none",
+            format_flag: "--json",
+        });
+    }
+    return definePmCommandOutputEnvelope({
+        command: normalizedCommand,
+        kind: rootCommand === "get" ? "entity" : "diagnostic",
+        wrapper_key: rootCommand === "get" ? "item" : null,
+        cardinality: rootCommand === "get" ? "one" : "none",
+        format_flag: "--json",
+    });
+}
+/** Default envelope declaration for every built-in command. */
+export const PM_COMMAND_OUTPUT_ENVELOPE_CONTRACTS = PM_CORE_COMMAND_NAMES.map((command) => createOutputEnvelopeContract(command));
+const OUTPUT_ENVELOPE_BY_COMMAND = new Map(PM_COMMAND_OUTPUT_ENVELOPE_CONTRACTS.map((contract) => [contract.command, contract]));
+/** Resolve a built-in envelope or generate a conservative package fallback. */
+export function resolvePmCommandOutputEnvelope(command) {
+    const normalized = command.trim().replace(/\s+/gu, " ");
+    if (normalized.length === 0) {
+        throw new TypeError("command must be a non-empty command path");
+    }
+    const [rootCommand = normalized] = normalized.split(" ");
+    const declared = OUTPUT_ENVELOPE_BY_COMMAND.get(rootCommand);
+    return declared
+        ? { ...declared, command: normalized }
+        : createOutputEnvelopeContract(normalized);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Return whether an unknown value is the flat CLI mutation receipt shape. */
+export function isPmMutationReceipt(value) {
+    return (isRecord(value) &&
+        typeof value.id === "string" &&
+        value.id.length > 0 &&
+        typeof value.status === "string" &&
+        value.status.length > 0 &&
+        Number.isSafeInteger(value.changed_field_count) &&
+        Number(value.changed_field_count) >= 0 &&
+        (value.close_reason === undefined ||
+            typeof value.close_reason === "string") &&
+        (value.deleted === undefined || typeof value.deleted === "boolean") &&
+        (value.previous_status === undefined ||
+            typeof value.previous_status === "string") &&
+        (value.warnings === undefined || Array.isArray(value.warnings)));
+}
+/** Implement string parsing and decoded-value validation at one boundary. */
+export function parseMutationReceipt(input) {
+    let value = input;
+    if (typeof input === "string") {
+        try {
+            value = JSON.parse(input);
+        }
+        catch (error) {
+            throw new TypeError(`Mutation receipt must be valid JSON: ${String(error)}`, { cause: error });
+        }
+    }
+    if (!isPmMutationReceipt(value)) {
+        throw new TypeError("Mutation receipt must be a flat object with top-level id, status, and changed_field_count fields");
+    }
+    return {
+        id: value.id,
+        status: value.status,
+        changedFieldCount: value.changed_field_count,
+        ...(typeof value.close_reason === "string"
+            ? { closeReason: value.close_reason }
+            : {}),
+        ...(typeof value.deleted === "boolean" ? { deleted: value.deleted } : {}),
+        ...(typeof value.previous_status === "string"
+            ? { previousStatus: value.previous_status }
+            : {}),
+        ...(Array.isArray(value.warnings) ? { warnings: value.warnings } : {}),
+    };
+}
+//# sourceMappingURL=output-contracts.js.map
+//# debugId=af86d275-63a8-5205-a8b3-154efdbd8e2a

package/dist/sdk/package-import-adapters.js

@@ -13,7 +13,7 @@
  * helper bodies while keeping each package's explicit field mapping in the package.
  */
 
-!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]="03e4257c-7d89-531b-adb0-664e77e7da18")}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]="c2567f6a-cd1c-56b5-a93d-41e92ed574bf")}catch(e){}}();
 import { appendHistoryEntry, createHistoryEntry, } from "../core/history/history.js";
 import { acquireLock } from "../core/lock/lock.js";
 import { parseTags } from "../core/item/parse.js";
@@ -442,4 +442,4 @@ export async function commitImportedItem(params) {
     }
 }
 //# sourceMappingURL=package-import-adapters.js.map
-//# debugId=03e4257c-7d89-531b-adb0-664e77e7da18
+//# debugId=c2567f6a-cd1c-56b5-a93d-41e92ed574bf

package/dist/sdk/structured-mutations.d.ts

@@ -1,4 +1,20 @@
 import type { BulkItemMutation } from "./item-transaction.js";
+/** Controls for resolving one versioned mutation document. */
+export interface ResolveItemMutationDocumentOptions {
+    /** Stable transaction identity used to derive replay-safe create ids. */
+    transactionId: string;
+    /** Workspace item-id prefix. */
+    idPrefix: string;
+}
+/** Fully validated mutation document ready for preview or commit. */
+export interface ResolvedItemMutationDocument {
+    /** Versioned structured-input contract. */
+    schema_version: 1;
+    /** Atomic mutations with every local reference replaced by a concrete id. */
+    mutations: BulkItemMutation[];
+    /** Batch-local alias to concrete-id receipt. */
+    references: Record<string, string>;
+}
 /** Validated transaction controls shared by atomic CLI and MCP adapters. */
 export interface AtomicMutationControls {
     /** Compensation policy applied to created items when a later step fails. */
@@ -12,6 +28,13 @@ export interface AtomicMutationControls {
 export declare function parseAtomicMutationControls(value: Record<string, unknown>): AtomicMutationControls;
 /** Parse a JSON array, or an object containing `mutations`, into an atomic mutation batch. */
 export declare function parseItemMutationBatch(input: string): BulkItemMutation[];
+/**
+ * Resolve a versioned heterogeneous mutation document. Create rows may declare
+ * a unique `ref`; omitted ids are derived deterministically from the stable
+ * transaction id, and `@ref` forward references are supported in target ids,
+ * parent/blocked-by options, and dependency entries.
+ */
+export declare function resolveItemMutationDocument(input: string, options: ResolveItemMutationDocumentOptions): ResolvedItemMutationDocument;
 /**
  * Convert a direct item JSON document or `pm get --json` envelope into the
  * create/update option shape. Explicit CLI flags override document values.

package/dist/sdk/structured-mutations.js

@@ -5,13 +5,26 @@
  * transaction contract and normalizes full item documents for CLI round trips.
  */
 
-!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]="6471aca6-b7e1-51c0-b905-5617dfb7ef2a")}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]="91be2c5d-c495-54bc-ac79-b4c645ad2c6e")}catch(e){}}();
+import crypto from "node:crypto";
+import { normalizeItemId, normalizePrefix } from "../core/item/id.js";
 import { EXIT_CODE, ITEM_PROJECT_CONTEXT_KEYS, } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { levenshteinDistanceWithinLimit } from "../core/shared/levenshtein.js";
-import { CLOSE_FLAG_CONTRACTS } from "./cli-contracts/flag-contracts.js";
+import { CLOSE_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, } from "./cli-contracts/flag-contracts.js";
 import { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, } from "./cli-contracts/commander-mutation-options.js";
 const MUTATION_ROW_KEYS = ["op", "id", "reason", "options"];
+const REFERENCED_MUTATION_ROW_KEYS = [
+    ...MUTATION_ROW_KEYS,
+    "ref",
+];
+const MUTATION_DOCUMENT_KEYS = ["schema_version", "mutations"];
+const MUTATION_REFERENCE_SOURCE = "[a-z][a-z0-9._-]{0,63}";
+const MUTATION_REFERENCE_PATTERN = new RegExp(`^${MUTATION_REFERENCE_SOURCE}$`, "u");
+const MUTATION_DEPENDENCY_REFERENCE_PATTERN = new RegExp(`(^|,)id=@(${MUTATION_REFERENCE_SOURCE})(?=,|$)`, "gu");
+const flagToOptionKey = (flag) => flag
+    .slice(2)
+    .replaceAll(/-([a-z])/gu, (_match, letter) => letter.toUpperCase());
 const ITEM_ENVELOPE_KEYS = [
     "item",
     "linked",
@@ -26,13 +39,16 @@ const READ_ONLY_ITEM_KEYS = new Set([
     "created_at",
     "updated_at",
     "closed_at",
-    "completed_at",
     "version",
     "format_version",
     "path",
     "author",
 ]);
-const UPDATE_READ_ONLY_ITEM_KEYS = new Set([...READ_ONLY_ITEM_KEYS, "id"]);
+const UPDATE_READ_ONLY_ITEM_KEYS = new Set([
+    ...READ_ONLY_ITEM_KEYS,
+    "completed_at",
+    "id",
+]);
 const ITEM_FIELD_KEYS = new Set([
     "id",
     "title",
@@ -56,6 +72,7 @@ const ITEM_FIELD_KEYS = new Set([
     "regression",
     "customer_impact",
     "close_reason",
+    "completed_at",
     "dependencies",
     "comments",
     "notes",
@@ -70,9 +87,8 @@ const ITEM_FIELD_KEYS = new Set([
 const MUTATION_OPTION_KEYS = {
     create: CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.map((contract) => contract.target),
     update: UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.map((contract) => contract.target),
-    close: CLOSE_FLAG_CONTRACTS.map((contract) => contract.flag
-        .slice(2)
-        .replaceAll(/-([a-z])/gu, (_match, letter) => letter.toUpperCase())).filter((key) => key !== "reason"),
+    close: CLOSE_FLAG_CONTRACTS.map((contract) => flagToOptionKey(contract.flag)).filter((key) => key !== "reason"),
+    release: RELEASE_FLAG_CONTRACTS.map((contract) => flagToOptionKey(contract.flag)),
 };
 /** Validate and normalize atomic transaction controls at every transport boundary. */
 export function parseAtomicMutationControls(value) {
@@ -172,8 +188,11 @@ function validateMutationOptions(options, op, index) {
 function validateMutationRow(value, index) {
     const mutation = validateMutationObject(value, index);
     const { op, id, reason } = mutation;
-    if (op !== "create" && op !== "update" && op !== "close") {
-        throw new PmCliError(`Mutation ${index + 1} op must be create, update, or close.`, EXIT_CODE.USAGE);
+    if (op !== "create" &&
+        op !== "update" &&
+        op !== "close" &&
+        op !== "release") {
+        throw new PmCliError(`Mutation ${index + 1} op must be create, update, close, or release.`, EXIT_CODE.USAGE);
     }
     const options = validateMutationOptions(mutation.options, op, index);
     if (typeof id !== "string" || id.trim().length === 0) {
@@ -193,6 +212,15 @@ function validateMutationRow(value, index) {
                 : { options: options }),
         };
     }
+    if (op === "release") {
+        return {
+            op,
+            id: normalizedId,
+            ...(options === undefined
+                ? {}
+                : { options: options }),
+        };
+    }
     if (!isPlainObject(options)) {
         throw new PmCliError(`Mutation ${index + 1} ${op} requires an options object.`, EXIT_CODE.USAGE);
     }
@@ -215,6 +243,187 @@ export function parseItemMutationBatch(input) {
     }
     return rows.map((row, index) => validateMutationRow(row, index));
 }
+function deriveReferencedItemId(transactionId, reference, idPrefix) {
+    const digest = crypto
+        .createHash("sha256")
+        .update(transactionId)
+        .update("\0")
+        .update(reference)
+        .digest("hex");
+    const token = BigInt(`0x${digest.slice(0, 16)}`)
+        .toString(36)
+        .padStart(13, "0")
+        .slice(-12);
+    return `${normalizePrefix(idPrefix)}${token}`;
+}
+function replaceExactMutationReference(value, references) {
+    if (typeof value !== "string" || !value.startsWith("@")) {
+        return value;
+    }
+    const reference = value.slice(1);
+    const resolved = references[reference];
+    if (resolved === undefined) {
+        throw new PmCliError(`Unknown mutation reference "${value}".`, EXIT_CODE.USAGE);
+    }
+    return resolved;
+}
+function replaceDependencyReference(value, references) {
+    if (typeof value !== "string")
+        return value;
+    const resolvedValue = value.replace(MUTATION_DEPENDENCY_REFERENCE_PATTERN, (_match, prefix, reference) => {
+        const resolved = references[reference];
+        if (resolved === undefined) {
+            throw new PmCliError(`Unknown mutation reference "@${reference}".`, EXIT_CODE.USAGE);
+        }
+        return `${prefix}id=${resolved}`;
+    });
+    if (/(^|,)id=@/u.test(resolvedValue)) {
+        throw new PmCliError(`Malformed mutation reference in dependency "${value}".`, EXIT_CODE.USAGE);
+    }
+    return resolvedValue;
+}
+function referencedAliases(value) {
+    if (typeof value !== "string")
+        return [];
+    if (value.startsWith("@"))
+        return [value.slice(1)];
+    return [...value.matchAll(MUTATION_DEPENDENCY_REFERENCE_PATTERN)]
+        .map((match) => match[1])
+        .filter((reference) => reference !== undefined);
+}
+function assertAcyclicCreateReferences(rows) {
+    const graph = new Map();
+    for (const row of rows) {
+        if (row.op !== "create" || typeof row.ref !== "string")
+            continue;
+        const mutationOptions = isPlainObject(row.options) ? row.options : {};
+        const dependencies = Array.isArray(mutationOptions.dep)
+            ? mutationOptions.dep
+            : mutationOptions.dep === undefined
+                ? []
+                : [mutationOptions.dep];
+        graph.set(row.ref, [mutationOptions.parent, mutationOptions.blockedBy, ...dependencies]
+            .flatMap(referencedAliases));
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (reference) => {
+        if (visiting.has(reference)) {
+            throw new PmCliError(`Mutation reference cycle includes "@${reference}".`, EXIT_CODE.USAGE);
+        }
+        if (visited.has(reference))
+            return;
+        visiting.add(reference);
+        for (const dependency of graph.get(reference)) {
+            if (graph.has(dependency))
+                visit(dependency);
+        }
+        visiting.delete(reference);
+        visited.add(reference);
+    };
+    for (const reference of graph.keys())
+        visit(reference);
+}
+function parseMutationDocumentRows(input) {
+    const parsed = parseJsonValue(input, "Mutation document");
+    const envelope = Array.isArray(parsed)
+        ? { schema_version: 1, mutations: parsed }
+        : parsed;
+    if (!isPlainObject(envelope)) {
+        throw new PmCliError("Mutation document must be a JSON array or object.", EXIT_CODE.USAGE);
+    }
+    for (const key of Object.keys(envelope)) {
+        if (!MUTATION_DOCUMENT_KEYS.includes(key)) {
+            throw unknownKeyError("mutation document", key, MUTATION_DOCUMENT_KEYS);
+        }
+    }
+    if (envelope.schema_version !== undefined &&
+        envelope.schema_version !== 1) {
+        throw new PmCliError("Mutation document schema_version must be 1.", EXIT_CODE.USAGE);
+    }
+    if (!Array.isArray(envelope.mutations) || envelope.mutations.length === 0) {
+        throw new PmCliError("Mutation document requires a non-empty mutations array.", EXIT_CODE.USAGE);
+    }
+    return envelope.mutations.map((row, index) => {
+        if (!isPlainObject(row)) {
+            throw new PmCliError(`Mutation ${index + 1} must be an object.`, EXIT_CODE.USAGE);
+        }
+        for (const key of Object.keys(row)) {
+            if (!REFERENCED_MUTATION_ROW_KEYS.includes(key)) {
+                throw unknownKeyError(`mutation ${index + 1}`, key, REFERENCED_MUTATION_ROW_KEYS);
+            }
+        }
+        return { ...row };
+    });
+}
+function collectMutationReferences(rows, options) {
+    const references = Object.create(null);
+    for (const [index, row] of rows.entries()) {
+        if (row.ref === undefined)
+            continue;
+        if (row.op !== "create") {
+            throw new PmCliError(`Mutation ${index + 1} ref is only valid for create operations.`, EXIT_CODE.USAGE);
+        }
+        if (typeof row.ref !== "string" ||
+            !MUTATION_REFERENCE_PATTERN.test(row.ref)) {
+            throw new PmCliError(`Mutation ${index + 1} ref must match ${MUTATION_REFERENCE_PATTERN.source}.`, EXIT_CODE.USAGE);
+        }
+        if (references[row.ref] !== undefined) {
+            throw new PmCliError(`Duplicate mutation ref "${row.ref}".`, EXIT_CODE.USAGE);
+        }
+        references[row.ref] =
+            typeof row.id === "string" && row.id.trim().length > 0
+                ? normalizeItemId(row.id, options.idPrefix)
+                : deriveReferencedItemId(options.transactionId, row.ref, options.idPrefix);
+    }
+    return references;
+}
+/**
+ * Resolve a versioned heterogeneous mutation document. Create rows may declare
+ * a unique `ref`; omitted ids are derived deterministically from the stable
+ * transaction id, and `@ref` forward references are supported in target ids,
+ * parent/blocked-by options, and dependency entries.
+ */
+export function resolveItemMutationDocument(input, options) {
+    const rows = parseMutationDocumentRows(input);
+    const references = collectMutationReferences(rows, options);
+    assertAcyclicCreateReferences(rows);
+    const resolvedRows = rows.map((row) => {
+        const resolved = { ...row };
+        const reference = typeof resolved.ref === "string" ? resolved.ref : undefined;
+        delete resolved.ref;
+        if (reference !== undefined) {
+            resolved.id = references[reference];
+        }
+        else {
+            resolved.id = replaceExactMutationReference(resolved.id, references);
+        }
+        if (isPlainObject(resolved.options)) {
+            const mutationOptions = { ...resolved.options };
+            for (const key of ["parent", "blockedBy"]) {
+                if (mutationOptions[key] !== undefined) {
+                    mutationOptions[key] = replaceExactMutationReference(mutationOptions[key], references);
+                }
+            }
+            if (Array.isArray(mutationOptions.dep)) {
+                mutationOptions.dep = mutationOptions.dep.map((entry) => replaceDependencyReference(entry, references));
+            }
+            else if (mutationOptions.dep !== undefined) {
+                mutationOptions.dep = replaceDependencyReference(mutationOptions.dep, references);
+            }
+            resolved.options = mutationOptions;
+        }
+        return resolved;
+    });
+    const mutations = parseItemMutationBatch(JSON.stringify(resolvedRows));
+    const createIds = mutations
+        .filter((mutation) => mutation.op === "create")
+        .map((mutation) => mutation.id);
+    if (new Set(createIds).size !== createIds.length) {
+        throw new PmCliError("Duplicate resolved create id in mutation document.", EXIT_CODE.USAGE);
+    }
+    return { schema_version: 1, mutations, references };
+}
 function serializePairs(value, keys) {
     return keys
         .filter((key) => value[key] !== undefined && value[key] !== null)
@@ -359,4 +568,4 @@ export function validateItemMutationRows(value) {
     return parseItemMutationBatch(JSON.stringify(value));
 }
 //# sourceMappingURL=structured-mutations.js.map
-//# debugId=6471aca6-b7e1-51c0-b905-5617dfb7ef2a
+//# debugId=91be2c5d-c495-54bc-ac79-b4c645ad2c6e