@unbrained/pm-cli 2026.8.4 → 2026.8.6

package/dist/sdk/lifecycle/create.js

@@ -4,9 +4,9 @@
  * Implements the pm create command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5f01dc2b-6239-5724-aa36-8f81b580b76a")}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]="93dc76a3-f205-5a44-85bd-5a6fad80c8d4")}catch(e){}}();
 import { pathExists, removeFileIfExists, writeFileAtomic, appendHistoryEntry, createHistoryEntry, generateItemId, normalizeItemId, canonicalDocument, normalizeItemMetadata, serializeItemDocument, assertParentReferenceIsNotSelf, isPlaceholderReferenceToken, normalizeParentReferenceValue, validateMissingParentReference, validateSprintOrReleaseValue, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, resolvePriority, getFocusedItem, normalizeStatusInput, canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveItemTypeRegistry, resolveCommandOptionPolicyState, resolveTypeDefinition, resolveTypeName, validateTypeOptions, acquireLock, printError, buildInvalidTypeError, resolveTypeSynonym, collectRuntimeCreateFieldValues, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, ITEM_METADATA_KEY_ORDER, PmCliError, nowIso, resolveIsoOrRelative, getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveCommandHandler, runActiveBeforeMutationHooks, runActiveOnWriteHooks, collectRegisteredItemFieldNames, applyRegisteredItemFieldDefaultsAndValidation, parseRegisteredItemFieldAssignments, listAllItemMetadataLight, locateItem, createMutationGuardSdk, getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
-import { requireTerminalReason } from "../lifecycle-policy.js";
+import { requireTerminalReasonWithRecovery } from "../lifecycle-policy.js";
 import { evaluateSimilarityGovernance, similarityAdvisoryWarnings, } from "../similarity.js";
 import { acquireItemMetadataDerivedIndexLock, refreshItemMetadataDerivedIndex, } from "../item-metadata-index.js";
 import { collectNewOrderingCycleWarnings } from "../graph/mutation-advisory.js";
@@ -1384,13 +1384,28 @@ function resolveCreateOrder(unsetKeys, resolvedOptions) {
     return order;
 }
 /** Resolve an author-controlled reason for an item created directly in the close status. */
-function resolveCreateCloseReason(status, statusRegistry, settings, resolvedOptions, resolution) {
-    if (status !== statusRegistry.close_status ||
-        !settings.governance.require_close_reason) {
-        return { closeReason: undefined, warnings: [] };
+function resolveCreateCloseReason(status, statusRegistry, settings, resolvedOptions, resolution, nowValue) {
+    if (resolvedOptions.completedAt !== undefined &&
+        status !== statusRegistry.close_status) {
+        throw new PmCliError("--completed-at requires a terminal create status.", EXIT_CODE.USAGE);
     }
+    const completedAt = status !== statusRegistry.close_status
+        ? undefined
+        : resolvedOptions.completedAt === undefined
+            ? nowValue
+            : resolveIsoOrRelative(resolvedOptions.completedAt, new Date(nowValue), "completed-at");
+    if (status !== statusRegistry.close_status) {
+        return { closeReason: undefined, completedAt, warnings: [] };
+    }
+    const reasonInput = settings.governance.require_close_reason
+        ? {
+            explicit: resolvedOptions.closeReason ?? resolvedOptions.message,
+            resolution,
+        }
+        : { explicit: resolvedOptions.closeReason };
     return {
-        closeReason: requireTerminalReason({ explicit: resolvedOptions.message, resolution }, true).closeReason,
+        closeReason: requireTerminalReasonWithRecovery(reasonInput, settings.governance.require_close_reason, { operation: "create", status }).closeReason,
+        completedAt,
         warnings: [],
     };
 }
@@ -1671,9 +1686,10 @@ export async function runCreate(options, global) {
     // GH-249: creating an item directly in the close status must honor
     // governance.require_close_reason, just like `pm close` (errors when missing)
     // and `pm update --status closed` (defaults + warns).
-    const closeReasonResolution = resolveCreateCloseReason(status, statusRegistry, settings, resolvedOptions, resolution);
+    const closeReasonResolution = resolveCreateCloseReason(status, statusRegistry, settings, resolvedOptions, resolution, nowValue);
     const closeReason = closeReasonResolution.closeReason;
     const closedAt = status === statusRegistry.close_status ? nowValue : undefined;
+    const completedAt = closeReasonResolution.completedAt;
     validationWarnings.push(...closeReasonResolution.warnings);
     const itemMetadata = normalizeItemMetadata({
         id,
@@ -1683,7 +1699,7 @@ export async function runCreate(options, global) {
         type_options: validatedTypeOptions.normalized,
         status,
         closed_at: closedAt,
-        completed_at: closedAt,
+        completed_at: completedAt,
         close_reason: closeReason,
         priority,
         tags,
@@ -1825,4 +1841,4 @@ export const _testOnlyCreateCommand = {
     typeOptionExampleValue,
 };
 //# sourceMappingURL=create.js.map
-//# debugId=5f01dc2b-6239-5724-aa36-8f81b580b76a
+//# debugId=93dc76a3-f205-5a44-85bd-5a6fad80c8d4

package/dist/sdk/lifecycle-policy.d.ts

@@ -58,6 +58,13 @@ export interface TerminalReasonResolution {
     /** Field that supplied the resolved reason. */
     source: TerminalReasonSource;
 }
+/** Presentation context used to make terminal-policy recovery actionable. */
+export interface TerminalReasonRecoveryContext {
+    /** Operation whose input failed terminal-reason governance. */
+    operation: "close" | "create";
+    /** Terminal status requested by a create operation. */
+    status?: string;
+}
 /** Result of applying ordering-edge lifecycle policy to mutable item metadata. */
 export interface TerminalOrderingMutation {
     /** Metadata fields changed by the policy. */
@@ -71,6 +78,8 @@ export declare const DEFAULT_TERMINAL_TRANSITION_POLICY: Readonly<TerminalTransi
 export declare function resolveTerminalReason(input: TerminalReasonInput): TerminalReasonResolution;
 /** Enforce close-reason governance without inventing immutable history content. */
 export declare function requireTerminalReason(input: TerminalReasonInput, required: boolean): TerminalReasonResolution;
+/** Enforce close-reason governance with recovery for a specific operation. */
+export declare function requireTerminalReasonWithRecovery(input: TerminalReasonInput, required: boolean, recovery: TerminalReasonRecoveryContext): TerminalReasonResolution;
 /**
  * Apply terminal ordering policy while clearing only transient blocked-state
  * scalars. Preserving `blocked_by` dependency rows keeps predecessor history

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/package-migrations.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @module sdk/package-migrations
+ *
+ * Provides one-shot SDK helpers for extension and package migration lifecycle.
+ */
+import { type ExtensionCommandOptions, type ExtensionCommandResult, type PackageCommandOptions, type PackageCommandResult, type PmClientOptions } from "./runtime.js";
+/** Plan or apply active extension migrations without constructing a reusable client. */
+export declare function extensionMigrate(options?: ExtensionCommandOptions, clientOptions?: PmClientOptions): Promise<ExtensionCommandResult>;
+/** Plan or apply active package migrations without constructing a reusable client. */
+export declare function packageMigrate(options?: PackageCommandOptions, clientOptions?: PmClientOptions): Promise<PackageCommandResult>;

package/dist/sdk/package-migrations.js

@@ -0,0 +1,21 @@
+/**
+ * @module sdk/package-migrations
+ *
+ * Provides one-shot SDK helpers for extension and package migration lifecycle.
+ */
+
+!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]="5bbfab95-010d-5507-ab01-f8f43943d295")}catch(e){}}();
+import { PmClient, } from "./runtime.js";
+/** Plan or apply active extension migrations without constructing a reusable client. */
+export function extensionMigrate(options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).extension(undefined, {
+        ...options,
+        migrate: true,
+    });
+}
+/** Plan or apply active package migrations without constructing a reusable client. */
+export function packageMigrate(options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).packageMigrate(options);
+}
+//# sourceMappingURL=package-migrations.js.map
+//# debugId=5bbfab95-010d-5507-ab01-f8f43943d295

package/dist/sdk/runtime.d.ts

@@ -336,6 +336,8 @@ export declare class PmClient {
     packageActivate(target: string, options?: PackageCommandOptions): Promise<PackageCommandResult>;
     /** Disable an installed package using the same action as `pm package deactivate`. */
     packageDeactivate(target: string, options?: PackageCommandOptions): Promise<PackageCommandResult>;
+    /** Plan or apply active package migrations with durable workspace receipts. */
+    packageMigrate(options?: PackageCommandOptions): Promise<PackageCommandResult>;
     /** Upgrade the pm CLI and/or managed packages through the public SDK dispatcher. */
     upgrade(target?: string, options?: UpgradeCommandOptions): Promise<UpgradeResult>;
 }

package/dist/sdk/runtime.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Runtime.
  */
 
-!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]="196ad1a3-c78f-5eef-90fd-ea5de108b9fa")}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]="57628397-0652-5a7b-8521-2f0fb2abb787")}catch(e){}}();
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -669,6 +669,10 @@ export class PmClient {
     packageDeactivate(target, options = {}) {
         return this.runTyped("package-deactivate", { target, options });
     }
+    /** Plan or apply active package migrations with durable workspace receipts. */
+    packageMigrate(options = {}) {
+        return this.package(undefined, { ...options, migrate: true });
+    }
     /** Upgrade the pm CLI and/or managed packages through the public SDK dispatcher. */
     upgrade(target, options = {}) {
         return this.runTyped("upgrade", {
@@ -1958,4 +1962,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=196ad1a3-c78f-5eef-90fd-ea5de108b9fa
+//# debugId=57628397-0652-5a7b-8521-2f0fb2abb787

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.