@unbrained/pm-cli 2026.10.14 → 2026.10.17

package/dist/sdk/lifecycle/restore.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ebfa0c5e-461b-5078-8272-69086e84b4dc")}catch{}})();import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{enforceWorkflowMutation}from"../../core/policy/workflow-policy-store.js";import jsonPatch from"fast-json-patch";import fs from"node:fs/promises";import{readLocatedItemSnapshot}from"../../core/store/item-store.js";import{readHistorySnapshot}from"../../core/history/read.js";import{verifyHistoryRewriteNoDrift}from"../../core/history/history-rewrite.js";import{resolveHistorySubject}from"../history/subject.js";import{historyVersionOffset}from"../../core/history/version-address.js";import{writeFileAtomic,appendHistoryEntry,createHistoryEntry,replayToCanonicalItemDocument,replayToItemDocument,toReplayDocument,enforceHistoryStreamPolicyForItem,canonicalDocument,serializeItemDocument,resolveItemTypeRegistry,acquireLock,EXIT_CODE,PmCliError,nowIso,getActiveExtensionRegistrations,projectAfterCommandItemSnapshot,recordAfterCommandAffectedItem,runActiveOnWriteHooks,runActiveBeforeMutationHooks,createMutationGuardSdk,getItemPath,resolvePmRoot,readSettings,resolveAuthor}from"../runtime-primitives.js";import{applyHistoryPatch,ensureMaterializedHistoryTarget as ensureMaterializedRestoreTarget,extractPatchFailureContext,replayHistoryToTarget as replayToTarget,resolveHistoryTarget}from"../history-read.js";import{acquireItemMetadataDerivedIndexLock,refreshItemMetadataDerivedIndex}from"../item-metadata-index.js";async function readRestoreItem(located,settings,history){const snapshot=await readLocatedItemSnapshot(located,{schema:settings.schema});return snapshot.error===null?{raw:snapshot.raw,document:snapshot.document}:{raw:snapshot.raw,document:replayCurrentDocument(history),recovered:!0}}function ensureReplayTarget(target,history){return resolveHistoryTarget(target,history,{errorSubject:"restore",allowFutureTimestamp:!0})}function replayCurrentDocument(history){const currentReplay=replayToTarget(history,history.length-1);return Object.keys(currentReplay.metadata).length===0?{metadata:{},body:currentReplay.body}:canonicalDocument(replayToItemDocument(currentReplay))}async function resolveRestoreSubject(pmRoot,id,settings,typeToFolder){const subject=await resolveHistorySubject(pmRoot,id,settings,typeToFolder),historyPolicy=subject.located?await enforceHistoryStreamPolicyForItem({pmRoot,settings,itemId:subject.id,commandLabel:"restore"}):{warnings:[]};return{...subject,historyPolicyWarnings:historyPolicy.warnings}}function changedFields(beforeDocument,afterDocument){const beforeReplay=toReplayDocument(beforeDocument),afterReplay=toReplayDocument(afterDocument),patch=jsonPatch.compare(beforeReplay,afterReplay),fields=new Set;for(const op of patch){if(op.path==="/body"||op.path.startsWith("/body/")){fields.add("body");continue}const segment=op.path.replace(/^\/(?:metadata|front_matter)\/?/,"").split("/")[0];fields.add(segment.replaceAll("~1","/").replaceAll("~0","~"))}return Array.from(fields).sort((a,b)=>a.localeCompare(b))}async function loadRestoreStateUnderLock(params){const verified=await verifyHistoryRewriteNoDrift({pmRoot:params.pmRoot,subject:params.subject,settings:params.settings,typeRegistry:params.typeRegistry,historyRawBeforeLock:params.historyRawBeforeLock,currentItemRawBeforeLock:params.currentItemRawBeforeLock,operation:"restore",readItem:located=>readRestoreItem(located,params.settings,params.history)});return{loadedItemUnderLock:verified.loadedItemUnderLock,existingItemPath:verified.locatedUnderLock?.itemPath??null}}function resolveRestoreCurrentState(loadedItemUnderLock,history){return loadedItemUnderLock?{document:loadedItemUnderLock.document,originalRaw:loadedItemUnderLock.raw}:{document:replayCurrentDocument(history),originalRaw:null}}function collectRestoreOwnershipWarnings(params){const assigned=params.document.metadata.assignee?.trim();if(!(assigned&&assigned!==params.author&&!params.force))return[];if(params.enforcement==="strict")throw new PmCliError(`Item ${params.resolvedId} is assigned to ${assigned}. Use --force to override.`,EXIT_CODE.CONFLICT);return params.enforcement==="warn"?[`ownership_warning:assignee_conflict:${params.resolvedId}:${assigned}`]:[]}async function restorePreviousItemAfterHistoryFailure(params){if(params.existingItemPath&&params.resolvedOriginalRaw!==null&&params.restoredItemPath!==params.existingItemPath){await writeFileAtomic(params.existingItemPath,params.resolvedOriginalRaw),await fs.rm(params.restoredItemPath,{force:!0});return}if(params.existingItemPath&&params.resolvedOriginalRaw!==null){await writeFileAtomic(params.existingItemPath,params.resolvedOriginalRaw);return}await fs.rm(params.restoredItemPath,{force:!0})}async function runRestoreWriteHooks(params){return[...await runActiveOnWriteHooks({path:params.restoredItemPath,scope:"project",op:"restore",item_id:params.after.metadata.id,item_type:params.after.metadata.type,before:params.before,after:params.after,changed_fields:["restored"]}),...await runActiveOnWriteHooks({path:params.historyPath,scope:"project",op:"restore:history",item_id:params.after.metadata.id,item_type:params.after.metadata.type,before:params.before,after:params.after,changed_fields:["restored"]})]}async function runRestore(id,target,options,global2){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot),typeRegistry=resolveItemTypeRegistry(settings,getActiveExtensionRegistrations()),subject=await resolveRestoreSubject(pmRoot,id,settings,typeRegistry.type_to_folder),resolvedId=subject.id,{raw:historyRawBeforeLock,entries:history}=await readHistorySnapshot(subject.historyPath,resolvedId);if(history.length===0)throw new PmCliError(`No history exists for ${resolvedId}; restore is unavailable.`,EXIT_CODE.NOT_FOUND);const resolvedTarget=ensureReplayTarget(target,history),replayDocument=ensureMaterializedRestoreTarget(replayToTarget(history,resolvedTarget.historyIndex),resolvedTarget),restoredDocument=replayToCanonicalItemDocument(replayDocument,{schema:settings.schema});if(restoredDocument.metadata.id!==resolvedId)throw new PmCliError(`Restore target resolved to item ${restoredDocument.metadata.id}, expected ${resolvedId}.`,EXIT_CODE.GENERIC_FAILURE);const currentItemRawBeforeLock=(subject.located?await readRestoreItem(subject.located,settings,history):null)?.raw??null,author=resolveAuthor(options.author,settings.author_default),releaseLock=await acquireLock(pmRoot,resolvedId,settings.locks.ttl_seconds,author,!!options.force,settings.governance.force_required_for_stale_lock,settings.locks.wait_ms);try{const{loadedItemUnderLock,existingItemPath}=await loadRestoreStateUnderLock({pmRoot,subject,settings,typeRegistry,historyRawBeforeLock,currentItemRawBeforeLock,history}),itemFormat="toon",currentState=resolveRestoreCurrentState(loadedItemUnderLock,history),ownershipWarnings=collectRestoreOwnershipWarnings({document:currentState.document,author,force:options.force,enforcement:settings.governance.ownership_enforcement,resolvedId}),restoreChangedFields=changedFields(currentState.document,restoredDocument),workflowPolicy=await enforceWorkflowMutation({pmRoot,settings,operation:"restore",author,before:currentState.document,after:restoredDocument});await runActiveBeforeMutationHooks({pm_root:pmRoot,operation:"restore",before:currentState.document,after:restoredDocument,changed_fields:restoreChangedFields,sdk:createMutationGuardSdk({pmRoot,settings,typeToFolder:typeRegistry.type_to_folder})});const serializedRestore=serializeItemDocument(restoredDocument,{format:itemFormat,schema:settings.schema}),restoredItemPath=getItemPath(pmRoot,restoredDocument.metadata.type,resolvedId,itemFormat,typeRegistry.type_to_folder),releaseDerivedIndexLock=await acquireItemMetadataDerivedIndexLock(pmRoot,author);let derivedIndexWarnings=[];try{await writeFileAtomic(restoredItemPath,serializedRestore),existingItemPath&&restoredItemPath!==existingItemPath&&await fs.rm(existingItemPath);const historyEntry=createHistoryEntry({nowIso:nowIso(),author,op:"restore",before:currentState.document,after:restoredDocument,message:options.message,context:workflowPolicy.decisions.length===0?void 0:{workflow_policies:workflowPolicy.decisions}});try{await appendHistoryEntry(subject.historyPath,historyEntry)}catch(error){throw await restorePreviousItemAfterHistoryFailure({existingItemPath,resolvedOriginalRaw:currentState.originalRaw,restoredItemPath}),error}derivedIndexWarnings=await refreshItemMetadataDerivedIndex({pmRoot,preferredFormat:settings.item_format,typeToFolder:typeRegistry.type_to_folder,schema:settings.schema,itemPath:restoredItemPath,previousItemPath:existingItemPath??void 0,document:restoredDocument})}finally{await releaseDerivedIndexLock()}const hookWarnings=await runRestoreWriteHooks({restoredItemPath,historyPath:subject.historyPath,before:currentState.document,after:restoredDocument});recordAfterCommandAffectedItem({id:restoredDocument.metadata.id,op:"restore",item_type:restoredDocument.metadata.type,previous_status:currentState.document.metadata.status,status:restoredDocument.metadata.status,previous:projectAfterCommandItemSnapshot(currentState.document.metadata,restoreChangedFields),current:projectAfterCommandItemSnapshot(restoredDocument.metadata,restoreChangedFields),changed_fields:restoreChangedFields});const targetEntry=history[resolvedTarget.historyIndex],offset=historyVersionOffset(history,!0);return{item:restoredDocument.metadata,restored_from:{kind:resolvedTarget.kind,target:resolvedTarget.raw,history_index:resolvedTarget.historyIndex+1,version:offset===null?null:offset+resolvedTarget.historyIndex+1,entry_ts:targetEntry.ts,entry_op:targetEntry.op},changed_fields:restoreChangedFields,warnings:[...workflowPolicy.warnings,...loadedItemUnderLock?.recovered?["restore_unreadable_item_recovered"]:[],...subject.historyPolicyWarnings,...ownershipWarnings,...derivedIndexWarnings,...hookWarnings]}}finally{await releaseLock()}}const _testOnlyRestoreCommand={applyHistoryPatch,changedFields,ensureMaterializedRestoreTarget,ensureReplayTarget,extractPatchFailureContext,replayCurrentDocument,replayToTarget,resolveRestoreSubject};export{_testOnlyRestoreCommand,runRestore};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="930f2c41-96dd-5812-9cbb-c0fa4ee620c2")}catch{}})();import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{normalizeItemFormatVersion,requiredItemFormatVersion}from"../../core/item/item-format-version.js";import{assertProjectRuntimeFormatGuard}from"../environment/project-runtime-compatibility.js";import{enforceWorkflowMutation}from"../../core/policy/workflow-policy-store.js";import jsonPatch from"fast-json-patch";import fs from"node:fs/promises";import{readLocatedItemSnapshot}from"../../core/store/item-store.js";import{readHistorySnapshot}from"../../core/history/read.js";import{verifyHistoryRewriteNoDrift}from"../../core/history/history-rewrite.js";import{resolveHistorySubject}from"../history/subject.js";import{historyVersionOffset}from"../../core/history/version-address.js";import{writeFileAtomic,appendHistoryEntry,createHistoryEntry,replayToCanonicalItemDocument,replayToItemDocument,toReplayDocument,enforceHistoryStreamPolicyForItem,canonicalDocument,serializeItemDocument,resolveItemTypeRegistry,acquireLock,EXIT_CODE,PmCliError,nowIso,getActiveExtensionRegistrations,projectAfterCommandItemSnapshot,recordAfterCommandAffectedItem,runActiveOnWriteHooks,runActiveBeforeMutationHooks,createMutationGuardSdk,getItemPath,resolvePmRoot,resolveWorkspaceRoot,readSettings,resolveAuthor}from"../runtime-primitives.js";import{applyHistoryPatch,ensureMaterializedHistoryTarget as ensureMaterializedRestoreTarget,extractPatchFailureContext,replayHistoryToTarget as replayToTarget,resolveHistoryTarget}from"../history-read.js";import{acquireItemMetadataDerivedIndexLock,refreshItemMetadataDerivedIndex}from"../item-metadata-index.js";async function readRestoreItem(located,settings,history){const snapshot=await readLocatedItemSnapshot(located,{schema:settings.schema});return snapshot.error===null?{raw:snapshot.raw,document:snapshot.document}:{raw:snapshot.raw,document:replayCurrentDocument(history),recovered:!0}}function ensureReplayTarget(target,history){return resolveHistoryTarget(target,history,{errorSubject:"restore",allowFutureTimestamp:!0})}function replayCurrentDocument(history){const currentReplay=replayToTarget(history,history.length-1);return Object.keys(currentReplay.metadata).length===0?{metadata:{},body:currentReplay.body}:canonicalDocument(replayToItemDocument(currentReplay))}async function resolveRestoreSubject(pmRoot,id,settings,typeToFolder){const subject=await resolveHistorySubject(pmRoot,id,settings,typeToFolder),historyPolicy=subject.located?await enforceHistoryStreamPolicyForItem({pmRoot,settings,itemId:subject.id,commandLabel:"restore"}):{warnings:[]};return{...subject,historyPolicyWarnings:historyPolicy.warnings}}function changedFields(beforeDocument,afterDocument){const beforeReplay=toReplayDocument(beforeDocument),afterReplay=toReplayDocument(afterDocument),patch=jsonPatch.compare(beforeReplay,afterReplay),fields=new Set;for(const op of patch){if(op.path==="/body"||op.path.startsWith("/body/")){fields.add("body");continue}const segment=op.path.replace(/^\/(?:metadata|front_matter)\/?/,"").split("/")[0];fields.add(segment.replaceAll("~1","/").replaceAll("~0","~"))}return Array.from(fields).sort((a,b)=>a.localeCompare(b))}async function loadRestoreStateUnderLock(params){const verified=await verifyHistoryRewriteNoDrift({pmRoot:params.pmRoot,subject:params.subject,settings:params.settings,typeRegistry:params.typeRegistry,historyRawBeforeLock:params.historyRawBeforeLock,currentItemRawBeforeLock:params.currentItemRawBeforeLock,operation:"restore",readItem:located=>readRestoreItem(located,params.settings,params.history)});return{loadedItemUnderLock:verified.loadedItemUnderLock,existingItemPath:verified.locatedUnderLock?.itemPath??null}}function resolveRestoreCurrentState(loadedItemUnderLock,history){return loadedItemUnderLock?{document:loadedItemUnderLock.document,originalRaw:loadedItemUnderLock.raw}:{document:replayCurrentDocument(history),originalRaw:null}}function collectRestoreOwnershipWarnings(params){const assigned=params.document.metadata.assignee?.trim();if(!(assigned&&assigned!==params.author&&!params.force))return[];if(params.enforcement==="strict")throw new PmCliError(`Item ${params.resolvedId} is assigned to ${assigned}. Use --force to override.`,EXIT_CODE.CONFLICT);return params.enforcement==="warn"?[`ownership_warning:assignee_conflict:${params.resolvedId}:${assigned}`]:[]}async function restorePreviousItemAfterHistoryFailure(params){if(params.existingItemPath&&params.resolvedOriginalRaw!==null&&params.restoredItemPath!==params.existingItemPath){await writeFileAtomic(params.existingItemPath,params.resolvedOriginalRaw),await fs.rm(params.restoredItemPath,{force:!0});return}if(params.existingItemPath&&params.resolvedOriginalRaw!==null){await writeFileAtomic(params.existingItemPath,params.resolvedOriginalRaw);return}await fs.rm(params.restoredItemPath,{force:!0})}async function runRestoreWriteHooks(params){return[...await runActiveOnWriteHooks({path:params.restoredItemPath,scope:"project",op:"restore",item_id:params.after.metadata.id,item_type:params.after.metadata.type,before:params.before,after:params.after,changed_fields:["restored"]}),...await runActiveOnWriteHooks({path:params.historyPath,scope:"project",op:"restore:history",item_id:params.after.metadata.id,item_type:params.after.metadata.type,before:params.before,after:params.after,changed_fields:["restored"]})]}async function runRestore(id,target,options,global2){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot),typeRegistry=resolveItemTypeRegistry(settings,getActiveExtensionRegistrations()),subject=await resolveRestoreSubject(pmRoot,id,settings,typeRegistry.type_to_folder),resolvedId=subject.id,{raw:historyRawBeforeLock,entries:history}=await readHistorySnapshot(subject.historyPath,resolvedId);if(history.length===0)throw new PmCliError(`No history exists for ${resolvedId}; restore is unavailable.`,EXIT_CODE.NOT_FOUND);const resolvedTarget=ensureReplayTarget(target,history),replayDocument=ensureMaterializedRestoreTarget(replayToTarget(history,resolvedTarget.historyIndex),resolvedTarget),restoredDocument=replayToCanonicalItemDocument(replayDocument,{schema:settings.schema});if(restoredDocument.metadata.id!==resolvedId)throw new PmCliError(`Restore target resolved to item ${restoredDocument.metadata.id}, expected ${resolvedId}.`,EXIT_CODE.GENERIC_FAILURE);const currentItemRawBeforeLock=(subject.located?await readRestoreItem(subject.located,settings,history):null)?.raw??null,author=resolveAuthor(options.author,settings.author_default),releaseLock=await acquireLock(pmRoot,resolvedId,settings.locks.ttl_seconds,author,!!options.force,settings.governance.force_required_for_stale_lock,settings.locks.wait_ms);try{const{loadedItemUnderLock,existingItemPath}=await loadRestoreStateUnderLock({pmRoot,subject,settings,typeRegistry,historyRawBeforeLock,currentItemRawBeforeLock,history}),itemFormat="toon",currentState=resolveRestoreCurrentState(loadedItemUnderLock,history);restoredDocument.metadata.pm_format_version=normalizeItemFormatVersion(Math.max(requiredItemFormatVersion(restoredDocument.metadata),requiredItemFormatVersion(currentState.document.metadata))),assertProjectRuntimeFormatGuard(resolveWorkspaceRoot(pmRoot),requiredItemFormatVersion(restoredDocument.metadata));const ownershipWarnings=collectRestoreOwnershipWarnings({document:currentState.document,author,force:options.force,enforcement:settings.governance.ownership_enforcement,resolvedId}),restoreChangedFields=changedFields(currentState.document,restoredDocument),workflowPolicy=await enforceWorkflowMutation({pmRoot,settings,operation:"restore",author,before:currentState.document,after:restoredDocument});await runActiveBeforeMutationHooks({pm_root:pmRoot,operation:"restore",before:currentState.document,after:restoredDocument,changed_fields:restoreChangedFields,sdk:createMutationGuardSdk({pmRoot,settings,typeToFolder:typeRegistry.type_to_folder})});const serializedRestore=serializeItemDocument(restoredDocument,{format:itemFormat,schema:settings.schema}),restoredItemPath=getItemPath(pmRoot,restoredDocument.metadata.type,resolvedId,itemFormat,typeRegistry.type_to_folder),releaseDerivedIndexLock=await acquireItemMetadataDerivedIndexLock(pmRoot,author);let derivedIndexWarnings=[];try{await writeFileAtomic(restoredItemPath,serializedRestore),existingItemPath&&restoredItemPath!==existingItemPath&&await fs.rm(existingItemPath);const historyEntry=createHistoryEntry({nowIso:nowIso(),author,op:"restore",before:currentState.document,after:restoredDocument,message:options.message,context:workflowPolicy.decisions.length===0?void 0:{workflow_policies:workflowPolicy.decisions}});try{await appendHistoryEntry(subject.historyPath,historyEntry)}catch(error){throw await restorePreviousItemAfterHistoryFailure({existingItemPath,resolvedOriginalRaw:currentState.originalRaw,restoredItemPath}),error}derivedIndexWarnings=await refreshItemMetadataDerivedIndex({pmRoot,preferredFormat:settings.item_format,typeToFolder:typeRegistry.type_to_folder,schema:settings.schema,itemPath:restoredItemPath,previousItemPath:existingItemPath??void 0,document:restoredDocument})}finally{await releaseDerivedIndexLock()}const hookWarnings=await runRestoreWriteHooks({restoredItemPath,historyPath:subject.historyPath,before:currentState.document,after:restoredDocument});recordAfterCommandAffectedItem({id:restoredDocument.metadata.id,op:"restore",item_type:restoredDocument.metadata.type,previous_status:currentState.document.metadata.status,status:restoredDocument.metadata.status,previous:projectAfterCommandItemSnapshot(currentState.document.metadata,restoreChangedFields),current:projectAfterCommandItemSnapshot(restoredDocument.metadata,restoreChangedFields),changed_fields:restoreChangedFields});const targetEntry=history[resolvedTarget.historyIndex],offset=historyVersionOffset(history,!0);return{item:restoredDocument.metadata,restored_from:{kind:resolvedTarget.kind,target:resolvedTarget.raw,history_index:resolvedTarget.historyIndex+1,version:offset===null?null:offset+resolvedTarget.historyIndex+1,entry_ts:targetEntry.ts,entry_op:targetEntry.op},changed_fields:restoreChangedFields,warnings:[...workflowPolicy.warnings,...loadedItemUnderLock?.recovered?["restore_unreadable_item_recovered"]:[],...subject.historyPolicyWarnings,...ownershipWarnings,...derivedIndexWarnings,...hookWarnings]}}finally{await releaseLock()}}const _testOnlyRestoreCommand={applyHistoryPatch,changedFields,ensureMaterializedRestoreTarget,ensureReplayTarget,extractPatchFailureContext,replayCurrentDocument,replayToTarget,resolveRestoreSubject};export{_testOnlyRestoreCommand,runRestore};
 //# sourceMappingURL=restore.js.map

package/dist/sdk/lifecycle/shared-unset-fields.d.ts

@@ -3,47 +3,47 @@
  *
  * Single-sources unset-field metadata shared by create and update command handlers.
  */
-import { type RuntimeFieldCommand, type RuntimeFieldRegistry } from "../runtime-primitives.js";
+import { type RuntimeFieldCommand,type RuntimeFieldRegistry } from "../runtime-primitives.js";
 /** Describes one command option that can be removed from item metadata through `--unset`. */
 export interface CommandUnsetFieldDefinition {
 /** Value that configures or reports canonical for this contract. */
-canonical: string;
+canonical:string;
 /** Value that configures or reports aliases for this contract. */
-aliases: readonly string[];
+aliases:readonly string[];
 /** Value that configures or reports option key for this contract. */
-optionKey: string;
+optionKey:string;
 /** Value that configures or reports item metadata key for this contract. */
-metadataKey: string;
+metadataKey:string;
 }
 /** Public contract for common unset field definitions before close reason, shared by SDK and presentation-layer consumers. */
-export declare const COMMON_UNSET_FIELD_DEFINITIONS_BEFORE_CLOSE_REASON: readonly CommandUnsetFieldDefinition[];
+export declare const COMMON_UNSET_FIELD_DEFINITIONS_BEFORE_CLOSE_REASON:readonly CommandUnsetFieldDefinition[];
 /** Public contract for common unset field definitions after close reason before author, shared by SDK and presentation-layer consumers. */
-export declare const COMMON_UNSET_FIELD_DEFINITIONS_AFTER_CLOSE_REASON_BEFORE_AUTHOR: readonly CommandUnsetFieldDefinition[];
+export declare const COMMON_UNSET_FIELD_DEFINITIONS_AFTER_CLOSE_REASON_BEFORE_AUTHOR:readonly CommandUnsetFieldDefinition[];
 /** Public contract for common unset field definitions before author, shared by SDK and presentation-layer consumers. */
-export declare const COMMON_UNSET_FIELD_DEFINITIONS_BEFORE_AUTHOR: readonly CommandUnsetFieldDefinition[];
+export declare const COMMON_UNSET_FIELD_DEFINITIONS_BEFORE_AUTHOR:readonly CommandUnsetFieldDefinition[];
 /** Public contract for common unset field definitions after author, shared by SDK and presentation-layer consumers. */
-export declare const COMMON_UNSET_FIELD_DEFINITIONS_AFTER_AUTHOR: readonly CommandUnsetFieldDefinition[];
+export declare const COMMON_UNSET_FIELD_DEFINITIONS_AFTER_AUTHOR:readonly CommandUnsetFieldDefinition[];
 /** Result of matching a runtime schema field against a command `--unset` token. */
 export interface RuntimeUnsetFieldDefinition {
 /** Value that configures or reports option key for this contract. */
-optionKey: string;
+optionKey:string;
 /** Value that configures or reports item metadata key for this contract. */
-metadataKey: string;
+metadataKey:string;
 }
 /** Result of parsing command-level `--unset` tokens into metadata and option-key sets. */
 export interface ParsedCommandUnsetTargets {
 /** Value that configures or reports item metadata keys for this contract. */
-metadataKeys: Set<string>;
+metadataKeys:Set<string>;
 /** Value that configures or reports option keys for this contract. */
-optionKeys: Set<string>;
+optionKeys:Set<string>;
 }
 /** Resolve one normalized `--unset` token to a item-metadata/option pair. */
-export type CommandUnsetTargetResolver = (trimmedToken: string) => RuntimeUnsetFieldDefinition | undefined;
+export type CommandUnsetTargetResolver = (trimmedToken:string) => RuntimeUnsetFieldDefinition | undefined;
 /** Parse and validate common command `--unset` tokens while preserving command-specific field resolution. */
-export declare function parseCommandUnsetTargets(options: {
-readonly raw: readonly string[] | undefined;
-readonly resolveDefinition: CommandUnsetTargetResolver;
-readonly supportedFields: string;
-}): ParsedCommandUnsetTargets;
+export declare function parseCommandUnsetTargets(options:{
+readonly raw:readonly string[] | undefined;
+readonly resolveDefinition:CommandUnsetTargetResolver;
+readonly supportedFields:string;
+}):ParsedCommandUnsetTargets;
 /** Resolve a runtime-schema field definition from a command `--unset` token. */
-export declare function resolveRuntimeUnsetFieldDefinition(token: string, command: RuntimeFieldCommand, runtimeFieldRegistry: RuntimeFieldRegistry | undefined): RuntimeUnsetFieldDefinition | undefined;
+export declare function resolveRuntimeUnsetFieldDefinition(token:string,command:RuntimeFieldCommand,runtimeFieldRegistry:RuntimeFieldRegistry | undefined):RuntimeUnsetFieldDefinition | undefined;

package/dist/sdk/lifecycle/structured-mutation-plan.d.ts

@@ -0,0 +1,33 @@
+import type { PmSettings } from "../../types/index.js";
+import { type ResolvedItemMutationDocument } from "../structured-mutations.js";
+/** Inputs for planning one mutation document against a workspace. */
+export interface PlanItemMutationDocumentOptions {
+/** Tracker root whose schema and items govern the plan. */
+pmRoot:string;
+/** Raw document text: JSON array, versioned envelope, single record, or JSON Lines. */
+input:string;
+/** Explicit stable transaction id; omitted ids derive from the document bytes. */
+transactionId?:string;
+/** Stored field key, declared field key or option target identifying existing items. Stored keys take precedence over aliases. */
+upsertKey?:string;
+/** Already-read settings, to avoid a second settings read on hot paths. */
+settings?:PmSettings;
+}
+/** Resolved plan plus the transaction identity the caller must reuse to resume. */
+export interface PlannedItemMutationDocument extends ResolvedItemMutationDocument {
+/** Transaction id to pass to preview/commit; stable across replays of the same document. */
+transaction_id:string;
+/** Whether the transaction id came from the caller or was derived from the document. */
+transaction_id_source:"explicit" | "derived";
+/** Upsert key applied to create rows, when any. */
+upsert_key?:string;
+}
+/**
+ * Resolve a mutation document against the workspace. Reads happen before the
+ * writer lock; the returned batch is deterministic for the same document,
+ * schema, and existing items, so interrupted or repeated imports replay
+ * through the transaction journal instead of duplicating work. Create rows
+ * left by keyed upsert carry a `unique` guard that the commit re-checks under
+ * the lock, so a concurrent writer cannot slip a duplicate in after planning.
+ */
+export declare function planItemMutationDocument(options:PlanItemMutationDocumentOptions):Promise<PlannedItemMutationDocument>;

package/dist/sdk/lifecycle/structured-mutation-plan.js

@@ -0,0 +1,2 @@
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="3c45eeb2-58f2-58f9-ad24-e439967b99ef")}catch{}})();import{resolveRuntimeFieldRegistry,runtimeFieldOptionTarget}from"../../core/schema/runtime-schema.js";import{listUpsertKeyCandidates,resolveTransactionSchema}from"../item-transaction.js";import{readSettings}from"../../core/store/settings.js";import{resolveCoreUpsertMetadataKey}from"./core-item-fields.js";import{EXIT_CODE}from"../../core/shared/constants.js";import{PmCliError}from"../../core/shared/errors.js";import{deriveMutationTransactionId,resolveItemMutationDocument}from"../structured-mutations.js";async function planItemMutationDocument(options){const suppliedKey=options.upsertKey?.trim();if(suppliedKey!==void 0&&suppliedKey.length===0)throw new PmCliError("Upsert key must be a non-empty field name.",EXIT_CODE.USAGE);const settings=options.settings??await readSettings(options.pmRoot),explicit=options.transactionId?.trim()??"",transactionId=explicit.length>0?explicit:deriveMutationTransactionId(options.input),planSchema=await resolveTransactionSchema(options.pmRoot,settings),runtimeFields=resolveRuntimeFieldRegistry(planSchema.schema).definitions,upsertKey=(runtimeFields.find(field=>field.metadata_key===suppliedKey)??runtimeFields.find(field=>field.key===suppliedKey||runtimeFieldOptionTarget(field)===suppliedKey))?.metadata_key??resolveCoreUpsertMetadataKey(suppliedKey),upsert=upsertKey===void 0?void 0:{key:upsertKey,existing:await listUpsertKeyCandidates(options.pmRoot,settings,planSchema,upsertKey)};return{...resolveItemMutationDocument(options.input,{transactionId,idPrefix:settings.id_prefix,runtimeFields,...upsert===void 0?{}:{upsert}}),transaction_id:transactionId,transaction_id_source:explicit.length>0?"explicit":"derived",...upsert===void 0?{}:{upsert_key:upsert.key}}}export{planItemMutationDocument};
+//# sourceMappingURL=structured-mutation-plan.js.map

package/dist/sdk/lifecycle/task-composition.d.ts

@@ -1,19 +1,19 @@
 import type { GlobalOptions } from "../../core/shared/command-types.js";
-import { type ClaimMutationOptions } from "./claim.js";
+import { type ReleaseMutationOptions } from "./claim.js";
 import { type CloseCommandOptions } from "./close.js";
-import type { StartTaskResult, PauseTaskResult, CloseTaskResult } from "../runtime-public-contracts.js";
+import type { StartTaskResult,PauseTaskResult,CloseTaskResult } from "../runtime-public-contracts.js";
 /** Ownership inputs shared by the explicit-item start and pause compositions. */
-export interface TaskCompositionOptions extends ClaimMutationOptions {
+export interface TaskCompositionOptions extends ReleaseMutationOptions {
 /** Permit the same ownership and terminal overrides as constituent mutations. */
-force?: boolean;
+force?:boolean;
 /** Ranked selection cannot be combined with an explicit-item composition. */
-next?: boolean;
+next?:boolean;
 }
 /** Preserve a failed step's diagnostics while reporting the earlier durable mutation, without implying rollback. */
-export declare function finishComposition<T>(id: string, completed: "claim" | "update" | "close", operation: () => Promise<T>): Promise<T>;
+export declare function finishComposition<T>(id:string,completed:"claim" | "update" | "close",operation:() => Promise<T>):Promise<T>;
 /** Claim explicit work and advance it through the workspace's configured workflow. */
-export declare function runStartTask(id: string, options: TaskCompositionOptions, global: GlobalOptions): Promise<StartTaskResult>;
+export declare function runStartTask(id:string,options:TaskCompositionOptions,global:GlobalOptions):Promise<StartTaskResult>;
 /** Return work to its configured open status, then release ownership. */
-export declare function runPauseTask(id: string, options: TaskCompositionOptions, global: GlobalOptions): Promise<PauseTaskResult>;
+export declare function runPauseTask(id:string,options:TaskCompositionOptions,global:GlobalOptions):Promise<PauseTaskResult>;
 /** Record all close evidence before releasing assignment metadata. */
-export declare function runCloseTask(id: string, reason: string | undefined, options: CloseCommandOptions, global: GlobalOptions): Promise<CloseTaskResult>;
+export declare function runCloseTask(id:string,reason:string | undefined,options:CloseCommandOptions,global:GlobalOptions):Promise<CloseTaskResult>;

package/dist/sdk/lifecycle/task-composition.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="69182e8d-b8c7-5b70-8650-185a8f07f6ee")}catch{}})();import{PmCliError}from"../../core/shared/errors.js";import{EXIT_CODE}from"../../core/shared/constants.js";import{resolveRuntimeStatusRegistry}from"../../core/schema/runtime-schema.js";import{resolvePmRoot}from"../../core/store/paths.js";import{readSettings}from"../../core/store/settings.js";import{runClaim,runRelease}from"./claim.js";import{runClose}from"./close.js";import{runUpdate}from"./update.js";import{resolveStartTaskInProgressStatus}from"../start-task-status.js";import{mutationOptionsWithOverrides}from"../runtime-input.js";async function finishComposition(id,completed,operation){try{return await operation()}catch(error){const context=error instanceof PmCliError?error.context:{},failure=new PmCliError(error instanceof Error?error.message:String(error),error instanceof PmCliError?error.exitCode:EXIT_CODE.GENERIC_FAILURE,{...context,item_id:id,why:`${completed} completed for ${id} before the following step failed. No rollback was performed.${context.why?` ${context.why}`:""}`,nextSteps:[`Inspect the persisted state with pm get ${id} and pm history ${id} before retrying the failed step.`,...context.nextSteps??[]]});throw failure.cause=error,failure}}async function runStartTask(id,options,global2){if(options.next===!0||options.ifAvailable===!0)throw new PmCliError("--start cannot be combined with --next or --if-available for an explicit item",EXIT_CODE.USAGE,{code:"invalid_argument_value",required:"Remove --next and --if-available when starting an explicit item.",nextSteps:["Remove --next and --if-available, keep the explicit item ID and other supplied arguments, then retry."]});const settings=await readSettings(resolvePmRoot(process.cwd(),global2.path)),status=resolveStartTaskInProgressStatus(resolveRuntimeStatusRegistry(settings.schema)),claim=await runClaim(id,options.force===!0,global2,options),canonicalId=claim.item.id,update=await finishComposition(canonicalId,"claim",()=>runUpdate(canonicalId,mutationOptionsWithOverrides(options,{status},["assignee","start","next","ifAvailable","maxAttempts"]),global2));return{id:canonicalId,action:"start_task",claim,update}}async function runPauseTask(id,options,global2){const settings=await readSettings(resolvePmRoot(process.cwd(),global2.path)),status=resolveRuntimeStatusRegistry(settings.schema).open_status,update=await runUpdate(id,mutationOptionsWithOverrides(options,{status},["assignee","pause"]),global2),canonicalId=update.item.id,release=await finishComposition(canonicalId,"update",()=>runRelease(canonicalId,options.force===!0,global2,options));return{id:canonicalId,action:"pause_task",update,release}}async function runCloseTask(id,reason,options,global2){const close=await runClose(id,reason,options,global2),canonicalId=close.item.id,release=await finishComposition(canonicalId,"close",()=>runRelease(canonicalId,options.force===!0,global2,options));return{id:canonicalId,action:"close_task",close,release}}export{finishComposition,runCloseTask,runPauseTask,runStartTask};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="23f3ce6b-d536-5df2-92b1-ec756d53aa02")}catch{}})();import{PmCliError}from"../../core/shared/errors.js";import{EXIT_CODE}from"../../core/shared/constants.js";import{resolveRuntimeStatusRegistry}from"../../core/schema/runtime-schema.js";import{resolvePmRoot}from"../../core/store/paths.js";import{readSettings}from"../../core/store/settings.js";import{runClaim,runRelease}from"./claim.js";import{resolveReleaseHandoff}from"./release-handoff.js";import{runClose}from"./close.js";import{runUpdate}from"./update.js";import{resolveStartTaskInProgressStatus}from"../start-task-status.js";import{mutationOptionsWithOverrides}from"../runtime-input.js";async function finishComposition(id,completed,operation){try{return await operation()}catch(error){const context=error instanceof PmCliError?error.context:{},failure=new PmCliError(error instanceof Error?error.message:String(error),error instanceof PmCliError?error.exitCode:EXIT_CODE.GENERIC_FAILURE,{...context,item_id:id,why:`${completed} completed for ${id} before the following step failed. No rollback was performed.${context.why?` ${context.why}`:""}`,nextSteps:[`Inspect the persisted state with pm get ${id} and pm history ${id} before retrying the failed step.`,...context.nextSteps??[]]});throw failure.cause=error,failure}}async function runStartTask(id,options,global2){if(options.next===!0||options.ifAvailable===!0)throw new PmCliError("--start cannot be combined with --next or --if-available for an explicit item",EXIT_CODE.USAGE,{code:"invalid_argument_value",required:"Remove --next and --if-available when starting an explicit item.",nextSteps:["Remove --next and --if-available, keep the explicit item ID and other supplied arguments, then retry."]});const settings=await readSettings(resolvePmRoot(process.cwd(),global2.path)),status=resolveStartTaskInProgressStatus(resolveRuntimeStatusRegistry(settings.schema)),claim=await runClaim(id,options.force===!0,global2,options),canonicalId=claim.item.id,update=await finishComposition(canonicalId,"claim",()=>runUpdate(canonicalId,mutationOptionsWithOverrides(options,{status},["assignee","start","next","ifAvailable","maxAttempts"]),global2));return{id:canonicalId,action:"start_task",claim,update}}async function runPauseTask(id,options,global2){const settings=await readSettings(resolvePmRoot(process.cwd(),global2.path)),registry=resolveRuntimeStatusRegistry(settings.schema);resolveReleaseHandoff({...options,pause:!0},registry);const status=registry.open_status,update=await runUpdate(id,mutationOptionsWithOverrides(options,{status},["assignee","pause"]),global2),canonicalId=update.item.id,release=await finishComposition(canonicalId,"update",()=>runRelease(canonicalId,options.force===!0,global2,options));return{id:canonicalId,action:"pause_task",update,release}}async function runCloseTask(id,reason,options,global2){const close=await runClose(id,reason,options,global2),canonicalId=close.item.id,release=await finishComposition(canonicalId,"close",()=>runRelease(canonicalId,options.force===!0,global2,options));return{id:canonicalId,action:"close_task",close,release}}export{finishComposition,runCloseTask,runPauseTask,runStartTask};
 //# sourceMappingURL=task-composition.js.map

package/dist/sdk/lifecycle/update-many.d.ts

@@ -1,107 +1,107 @@
-import { type RuntimeFieldRegistry, type RuntimeStatusRegistry, type GlobalOptions } from "../runtime-primitives.js";
-import type { ItemStatus, PmSettings } from "../../types/index.js";
+import { type RuntimeFieldRegistry,type RuntimeStatusRegistry,type GlobalOptions } from "../runtime-primitives.js";
+import type { ItemStatus,PmSettings } from "../../types/index.js";
 import { hasListFilters } from "../query/list-filter-shared.js";
-import { type ListOptions, type ListedItem } from "../query/list.js";
+import { type ListOptions,type ListedItem } from "../query/list.js";
 import { type UpdateCommandOptions } from "./update.js";
 import { type PmCommandEffectReceipt } from "../cli-contracts/command-exit-contracts.js";
 /** Documents the update many command options payload exchanged by command, SDK, and package integrations. */
 export interface UpdateManyCommandOptions {
 /** Lifecycle state reported for status. */
-status?: string;
+status?:string;
 /** Value that configures or reports list for this contract. */
-list: ListOptions;
+list:ListOptions;
 /** Value that configures or reports update for this contract. */
-update: UpdateCommandOptions;
+update:UpdateCommandOptions;
 /** Value that configures or reports dry run for this contract. */
-dryRun?: boolean;
+dryRun?:boolean;
 /** Value that configures or reports rollback for this contract. */
-rollback?: string;
+rollback?:string;
 /** Value that configures or reports checkpoint for this contract. */
-checkpoint?: boolean;
+checkpoint?:boolean;
 }
 /** Presentation-neutral input accepted by the SDK-owned bulk update operation. */
 export type UpdateManyOperationOptions = UpdateManyCommandOptions;
 interface PlannedChange {
-field: string;
-before: unknown;
-after: unknown;
+field:string;
+before:unknown;
+after:unknown;
 }
 interface PlannedItemDiff {
-id: string;
-changes: PlannedChange[];
-warnings?: string[];
+id:string;
+changes:PlannedChange[];
+warnings?:string[];
 }
 interface UpdateManyApplyResultRow {
-id: string;
-status: "updated" | "failed" | "skipped";
-changed_fields?: string[];
-warnings?: string[];
-error?: string;
+id:string;
+status:"updated" | "failed" | "skipped";
+changed_fields?:string[];
+warnings?:string[];
+error?:string;
 }
 interface UpdateManyRollbackResultRow {
-id: string;
-status: "restored" | "failed";
-changed_fields?: string[];
-warnings?: string[];
-error?: string;
+id:string;
+status:"restored" | "failed";
+changed_fields?:string[];
+warnings?:string[];
+error?:string;
 }
 /** Documents the update many result payload exchanged by command, SDK, and package integrations. */
 export interface UpdateManyResult extends PmCommandEffectReceipt {
 /** Value that configures or reports mode for this contract. */
-mode: "dry_run" | "apply" | "rollback";
+mode:"dry_run" | "apply" | "rollback";
 /** Number of matched entries represented by this result. */
-matched_count: number;
+matched_count:number;
 /** Value that configures or reports dry run for this contract. */
-dry_run: boolean;
+dry_run:boolean;
 /** Value that configures or reports filters for this contract. */
-filters?: Record<string, unknown>;
+filters?:Record<string,unknown>;
 /** Inputs that customize the planned update operation. */
-planned_update_options?: Record<string, unknown>;
+planned_update_options?:Record<string,unknown>;
 /** Value that configures or reports item plans for this contract. */
-item_plans?: PlannedItemDiff[];
+item_plans?:PlannedItemDiff[];
 /** Value that configures or reports checkpoint for this contract. */
-checkpoint?: {
-id: string;
-created_at: string;
-path: string;
-rollback_command: string;
+checkpoint?:{
+id:string;
+created_at:string;
+path:string;
+rollback_command:string;
 };
 /** Number of updated entries represented by this result. */
-updated_count?: number;
+updated_count?:number;
 /** Number of skipped entries represented by this result. */
-skipped_count?: number;
+skipped_count?:number;
 /** Number of failed entries represented by this result. */
-failed_count?: number;
+failed_count?:number;
 /** Number of restored entries represented by this result. */
-restored_count?: number;
+restored_count?:number;
 /** Value that configures or reports rollback checkpoint id for this contract. */
-rollback_checkpoint_id?: string;
+rollback_checkpoint_id?:string;
 /** Value that configures or reports rows for this contract. */
-rows?: UpdateManyApplyResultRow[] | UpdateManyRollbackResultRow[];
+rows?:UpdateManyApplyResultRow[] | UpdateManyRollbackResultRow[];
 /** Value that configures or reports ids for this contract. */
-ids: string[];
+ids:string[];
 /** Explicitly requested --ids values that matched no tracked item. */
-unmatched_ids?: string[];
+unmatched_ids?:string[];
 /** Number of explicitly requested --ids values that matched no tracked item. */
-unmatched_count?: number;
+unmatched_count?:number;
 }
 /** Implements run update many for the public runtime surface of this module. */
-export declare const runUpdateMany: (options: UpdateManyCommandOptions, global: GlobalOptions) => Promise<UpdateManyResult>;
+export declare const runUpdateMany:(options:UpdateManyCommandOptions,global:GlobalOptions) => Promise<UpdateManyResult>;
 /** Public contract for test only update many command, shared by SDK and presentation-layer consumers. */
-export declare const _testOnlyUpdateManyCommand: {
-assertPlannedUpdateValuesValid: (update: UpdateCommandOptions, settings: PmSettings, statusRegistry: RuntimeStatusRegistry, pmRoot: string) => void;
-buildCollectionMutationPlans: (row: Record<string, unknown>, update: UpdateCommandOptions) => PlannedChange[];
-buildPlannedItemDiff: (item: ListedItem, runtimeFieldRegistry: RuntimeFieldRegistry, update?: UpdateCommandOptions) => PlannedItemDiff;
-buildTagMutationPlan: (row: Record<string, unknown>, update: UpdateCommandOptions) => PlannedChange | undefined;
-collectionValueCount: (field: string, value: unknown) => number;
-hasAnyUpdateMutationInput: (options: UpdateCommandOptions) => boolean;
-hasListFilters: typeof hasListFilters;
-normalizeStatusFilter: (value: string | undefined, statusRegistry: RuntimeStatusRegistry) => ItemStatus[] | undefined;
-normalizeCollectionBeforeValue: (field: string, value: unknown) => unknown;
-normalizeExistingTags: (value: unknown) => string[];
-normalizeUnsetField: (rawField: string) => string;
-rejectBlankIdsFilter: (list: ListOptions | undefined) => void;
-sanitizeUpdateOptionsForSummary: (options: UpdateCommandOptions) => Record<string, unknown>;
-toComparablePreviewValue: (optionKey: keyof UpdateCommandOptions, value: unknown) => unknown;
+export declare const _testOnlyUpdateManyCommand:{
+assertPlannedUpdateValuesValid:(update:UpdateCommandOptions,settings:PmSettings,statusRegistry:RuntimeStatusRegistry,pmRoot:string) => void;
+buildCollectionMutationPlans:(row:Record<string,unknown>,update:UpdateCommandOptions) => PlannedChange[];
+buildPlannedItemDiff:(item:ListedItem,runtimeFieldRegistry:RuntimeFieldRegistry,update?:UpdateCommandOptions) => PlannedItemDiff;
+buildTagMutationPlan:(row:Record<string,unknown>,update:UpdateCommandOptions) => PlannedChange | undefined;
+collectionValueCount:(field:string,value:unknown) => number;
+hasAnyUpdateMutationInput:(options:UpdateCommandOptions) => boolean;
+hasListFilters:typeof hasListFilters;
+normalizeStatusFilter:(value:string | undefined,statusRegistry:RuntimeStatusRegistry) => ItemStatus[] | undefined;
+normalizeCollectionBeforeValue:(field:string,value:unknown) => unknown;
+normalizeExistingTags:(value:unknown) => string[];
+normalizeUnsetField:(rawField:string) => string;
+rejectBlankIdsFilter:(list:ListOptions | undefined) => void;
+sanitizeUpdateOptionsForSummary:(options:UpdateCommandOptions) => Record<string,unknown>;
+toComparablePreviewValue:(optionKey:keyof UpdateCommandOptions,value:unknown) => unknown;
 };
 export {};