@unbrained/pm-cli 2026.10.14 → 2026.10.17

package/dist/sdk/item-transaction.d.ts

@@ -1,134 +1,197 @@
+import { loadRuntimeSchemaFromOptionalFiles } from "../core/schema/runtime-schema.js";
+import type { ItemTypeDefinition,PmSettings } from "../types/index.js";
+import { type ItemMutationUpsertCandidate } from "./structured-mutations.js";
 import { type PmClientFullMutationOptions } from "./runtime.js";
-import { type CommitWorkspaceTransactionOptions, type WorkspaceTransactionJsonValue, type WorkspaceTransactionStep } from "./workspace-transaction.js";
+import { type CommitWorkspaceTransactionOptions,type WorkspaceTransactionJsonValue,type WorkspaceTransactionStep } from "./workspace-transaction.js";
 /**
  * One atomic item creation inside a bulk mutation batch. The explicit `id`
- * doubles as the idempotency key: recovery treats an existing item with this id
- * as the already-applied result, so ids must be stable and transaction-owned.
+ * doubles as the idempotency key: recovery adopts an existing item unless it
+ * remains closed after compensation. IDs must be stable and transaction-owned.
  */
 export interface BulkItemCreateMutation {
 /** Discriminates the creation operation. */
-op: "create";
+op:"create";
 /** Explicit stable item id (normalized with the configured id_prefix). */
-id: string;
+id:string;
 /** Creation options forwarded to the public `create` runtime primitive. */
-options: PmClientFullMutationOptions;
+options:PmClientFullMutationOptions;
+/**
+     * Keyed-upsert guard re-checked under the writer lock. The planner resolves
+     * upsert matches before the lock, so a create row keeps the key it was
+     * planned against; the commit refuses with `upsert_key_conflict` when another
+     * writer created an item with the same key value after planning.
+     */
+unique?:BulkItemUniqueKey;
+}
+/** Unique-key guard carried by a create row planned under keyed upsert. */
+export interface BulkItemUniqueKey {
+/** Item field (core or declared custom metadata key) the upsert planner matched on. */
+key:string;
+/** The row's own value for that field, compared on canonical content. */
+value:unknown;
+}
+/** Schema facts a transaction needs, hydrated the same way whether or not the host scoped settings reads to configuration only. */
+export interface TransactionSchemaContext {
+/** Runtime schema with statuses, fields, and workflows merged from their files. */
+schema:PmSettings["schema"];
+/** Custom item types declared in the types file, when the settings read skipped hydration. */
+typeDefinitionsFromFile:ItemTypeDefinition[];
+}
+/**
+ * Resolve the runtime schema for planning or guarding a transaction. A preview
+ * host may scope settings reads to inline configuration only (no schema
+ * hydration, no scaffolding), in which case declared custom fields and types
+ * live solely in their schema files; load them through the guarded reader so
+ * no symlink, special file, or out-of-root path is ever opened in place.
+ */
+export declare function resolveTransactionSchema(pmRoot:string,settings:PmSettings):Promise<TransactionSchemaContext>;
+/** Collect every existing item that carries a value for the upsert key, covering core and declared custom keys across custom-type folders. */
+export declare function listUpsertKeyCandidates(pmRoot:string,settings:PmSettings,schemaContext:TransactionSchemaContext,key:string):Promise<ItemMutationUpsertCandidate[]>;
+/** Per-transaction index of existing upsert-key values, scanned lazily under the writer lock. */
+interface UniqueKeyIndex {
+/** Existing item ids per canonical key value. */
+lookup(key:string):Promise<Map<string,string[]>>;
+/** Advance cached scans from the created item's metadata without another project scan. */
+recordCreate(item:Readonly<Record<string,unknown>>):Promise<void>;
+/** Drop cached scans after a step may have changed existing key values. */
+invalidate():void;
+}
+/** Shared configuration for every step a bulk mutation batch builds. */
+interface BulkMutationStepConfig {
+pmRoot:string;
+author:string;
+transactionId:string;
+createCompensation:"close" | "delete";
+uniqueIndex:UniqueKeyIndex;
 }
 /** One atomic item update inside a bulk mutation batch. */
 export interface BulkItemUpdateMutation {
 /** Discriminates the update operation. */
-op: "update";
+op:"update";
 /** Target item id. */
-id: string;
+id:string;
 /** Update options forwarded to the public `update` runtime primitive. */
-options: PmClientFullMutationOptions;
+options:PmClientFullMutationOptions;
+/**
+     * Keyed-upsert selection re-checked under the target item lock. The planner
+     * chose this target by key value before the lock; the commit checks the
+     * locked document and refuses with `upsert_match_changed` when the value was changed or
+     * removed after planning, so the update never lands on a mismatched item.
+     */
+match?:BulkItemUniqueKey;
 }
 /** One atomic item closure inside a bulk mutation batch. */
 export interface BulkItemCloseMutation {
 /** Discriminates the close operation. */
-op: "close";
+op:"close";
 /** Target item id. */
-id: string;
+id:string;
 /** Close reason recorded on the item. */
-reason: string;
+reason:string;
 /** Close options forwarded to the public `close` runtime primitive. */
-options?: PmClientFullMutationOptions;
+options?:PmClientFullMutationOptions;
 }
 /** One atomic claim release inside a bulk mutation batch. */
 export interface BulkItemReleaseMutation {
 /** Discriminates the claim-release operation. */
-op: "release";
+op:"release";
 /** Target item id. */
-id: string;
+id:string;
 /** Release options forwarded to the public `release` runtime primitive. */
-options?: PmClientFullMutationOptions;
+options?:PmClientFullMutationOptions;
 }
 /** Union of the item mutations a bulk transaction batch can carry. */
 export type BulkItemMutation = BulkItemCreateMutation | BulkItemUpdateMutation | BulkItemCloseMutation | BulkItemReleaseMutation;
 /** Options accepted by the bulk item-mutation transaction helper. */
 export interface CommitItemMutationsOptions {
 /** Tracker root that owns the journal and workspace-wide writer lock. */
-pmRoot: string;
+pmRoot:string;
 /** Stable idempotency key reused to recover an interrupted batch. */
-transactionId: string;
+transactionId:string;
 /** Attributable actor recorded in the journal and forwarded to mutations. */
-author: string;
+author:string;
 /** Ordered item mutations; compensations run in reverse order. */
-mutations: readonly BulkItemMutation[];
+mutations:readonly BulkItemMutation[];
 /**
      * Compensation strategy for created items: `close` (default) preserves the
      * item and its history with an explanatory close reason, `delete` removes
-     * the item document (its history stream is retained by `pm delete`).
+     * the item document (its history stream is retained by `pm delete`). A retry
+     * refuses a still-closed compensated creation until explicitly reopened.
      */
-createCompensation?: "close" | "delete";
+createCompensation?:"close" | "delete";
 /** Lock lifetime in seconds; size this above the longest expected attempt. */
-lockTtlSeconds?: number;
+lockTtlSeconds?:number;
 /** Maximum time to wait for the workspace writer lock. */
-lockWaitMs?: number;
+lockWaitMs?:number;
 /** Optional transition observer used by telemetry and deterministic crash tests. */
-onTransition?: CommitWorkspaceTransactionOptions["onTransition"];
+onTransition?:CommitWorkspaceTransactionOptions["onTransition"];
 }
 /** Journal-safe outcome recorded for one committed bulk item mutation. */
 export interface BulkItemMutationOutcome {
 /** Canonical id of the mutated item. */
-id: string;
+id:string;
 /** Operation the batch applied for this item. */
-op: BulkItemMutation["op"];
+op:BulkItemMutation["op"];
 }
 /** Successful durable result of a bulk item-mutation transaction. */
 export interface CommitItemMutationsResult {
 /** Stable transaction identifier. */
-transactionId: string;
+transactionId:string;
 /** Final durable state. */
-status: "committed";
+status:"committed";
 /** Whether an interrupted journal was resumed. */
-recovered: boolean;
+recovered:boolean;
 /** One outcome per mutation, keyed by the derived transaction step id. */
-results: Record<string, BulkItemMutationOutcome>;
+results:Record<string,BulkItemMutationOutcome>;
 }
 interface LocatedItemSnapshot {
-id: string;
-closedAt: string | undefined;
-updatedAt: string;
-assignee: string | undefined;
-claimPrincipal: string | undefined;
+id:string;
+closedAt:string | undefined;
+updatedAt:string;
+assignee:string | undefined;
+claimPrincipal:string | undefined;
 }
 /** Read one item's transaction-relevant fields, mapping not-found to undefined. */
-declare function readItemSnapshot(pmRoot: string, id: string): Promise<LocatedItemSnapshot | undefined>;
+declare function readItemSnapshot(pmRoot:string,id:string):Promise<LocatedItemSnapshot | undefined>;
 /** Derive a journal-safe step id bound to position, target, and payload. */
-declare function deriveStepId(mutation: BulkItemMutation, index: number): string;
+declare function deriveStepId(mutation:BulkItemMutation,index:number):string;
 /** Build the durable history-message marker for one bulk mutation phase. */
-declare function bulkHistoryMarker(transactionId: string, stepId: string, phase: "apply" | "compensate"): string;
+declare function bulkHistoryMarker(transactionId:string,stepId:string,phase:"apply" | "compensate"):string;
 /**
  * Report whether a step's forward mutation is durably applied. Mutable item
  * fields cannot prove transaction ownership, so the apply marker in immutable
  * history is the source of truth; a later compensation marker means the
  * mutation was rolled back and must re-apply.
  */
-declare function isUpdateMarkerApplied(pmRoot: string, canonicalId: string, transactionId: string, stepId: string): Promise<boolean>;
+declare function isUpdateMarkerApplied(pmRoot:string,canonicalId:string,transactionId:string,stepId:string):Promise<boolean>;
 /** Idempotently restore an item to its captured pre-mutation version. */
-declare function compensateByRestore(config: {
-pmRoot: string;
-author: string;
-transactionId: string;
-}, itemId: string, stepId: string, data: WorkspaceTransactionJsonValue | undefined): Promise<void>;
+declare function compensateByRestore(config:{
+pmRoot:string;
+author:string;
+transactionId:string;
+},itemId:string,stepId:string,data:WorkspaceTransactionJsonValue | undefined):Promise<void>;
 /** Build the workspace-transaction step for one item creation. */
-declare function buildCreateStep(config: {
-pmRoot: string;
-author: string;
-transactionId: string;
-createCompensation: "close" | "delete";
-}, mutation: BulkItemCreateMutation, stepId: string): WorkspaceTransactionStep;
+declare function buildCreateStep(config:BulkMutationStepConfig,mutation:BulkItemCreateMutation,stepId:string):WorkspaceTransactionStep;
 /** Evidence and explicit limits of a non-writing semantic transaction preview. */
 export interface ItemMutationPreviewValidation {
 /** True when the coordinator executed staged validation; false for an already committed journal replay. */
-validated: boolean;
+validated:boolean;
 /** Distinguishes newly staged execution from idempotent replay without fresh step validation. */
-state: "staged_snapshot" | "replayed_committed_plan";
+state:"staged_snapshot" | "replayed_committed_plan";
 /** Preview leaves current commit state and executable extension effects unvalidated, including host-run pending migrations, mutation guards and hooks. */
-unresolved_commit_constraints: readonly string[];
+unresolved_commit_constraints:readonly string[];
 }
+/**
+ * Load the runtime schema (statuses, fields, workflows, custom types) with the
+ * preview's guards instead of reading the configured files in place. Hosts
+ * that scope settings reads to inline configuration (dry-run planning) use
+ * this so declared fields stay visible without opening a symlink, FIFO, or
+ * out-of-root schema path; such inputs refuse with
+ * `transaction_preview_non_regular_file` or `transaction_preview_external_schema`.
+ */
+export declare function loadGuardedRuntimeSchema(pmRoot:string,schemaSettings:Partial<PmSettings["schema"]> | undefined):Promise<Awaited<ReturnType<typeof loadRuntimeSchemaFromOptionalFiles>>>;
 /** Validate ordered mutations using apply's coordinator in a disposable tracker, without source writes, journals or extension hooks. */
-export declare function previewItemMutations(options: Pick<CommitItemMutationsOptions, "pmRoot" | "transactionId" | "author" | "mutations">): Promise<ItemMutationPreviewValidation>;
+export declare function previewItemMutations(options:Pick<CommitItemMutationsOptions,"pmRoot" | "transactionId" | "author" | "mutations">):Promise<ItemMutationPreviewValidation>;
 /**
  * Commit an ordered batch of item create/update/close mutations atomically
  * (all-or-nothing) in one durable workspace transaction. This is the
@@ -140,48 +203,48 @@ export declare function previewItemMutations(options: Pick<CommitItemMutationsOp
  * close-or-delete compensation for creates. A stable `transactionId` makes
  * interrupted batches resumable across processes and agents.
  */
-export declare function commitItemMutations(options: CommitItemMutationsOptions): Promise<CommitItemMutationsResult>;
+export declare function commitItemMutations(options:CommitItemMutationsOptions):Promise<CommitItemMutationsResult>;
 /** Options for completing one item as a single atomic SDK transaction. */
 export interface CommitItemCompletionOptions {
 /** Tracker root that owns the item and transaction journal. */
-pmRoot: string;
+pmRoot:string;
 /** Stable idempotency key for the composed completion. */
-transactionId: string;
+transactionId:string;
 /** Attributable actor for evidence, closure, and claim release. */
-author: string;
+author:string;
 /** Item being completed. */
-id: string;
+id:string;
 /** Durable close reason. */
-reason: string;
+reason:string;
 /** Evidence and linked-resource updates recorded before closure. */
-evidence?: PmClientFullMutationOptions;
+evidence?:PmClientFullMutationOptions;
 /** Structured closure fields and validation policy. */
-closeOptions?: PmClientFullMutationOptions;
+closeOptions?:PmClientFullMutationOptions;
 /** Claim-release controls. */
-releaseOptions?: PmClientFullMutationOptions;
+releaseOptions?:PmClientFullMutationOptions;
 /** Workspace transaction lock lifetime in seconds. */
-lockTtlSeconds?: number;
+lockTtlSeconds?:number;
 /** Maximum time to wait for the workspace transaction lock. */
-lockWaitMs?: number;
+lockWaitMs?:number;
 /** Optional transition observer used by telemetry and crash tests. */
-onTransition?: CommitWorkspaceTransactionOptions["onTransition"];
+onTransition?:CommitWorkspaceTransactionOptions["onTransition"];
 }
 /** Build the ordered mutation sequence used by atomic item completion. */
-export declare function buildItemCompletionMutations(options: Pick<CommitItemCompletionOptions, "id" | "reason" | "evidence" | "closeOptions" | "releaseOptions">): BulkItemMutation[];
+export declare function buildItemCompletionMutations(options:Pick<CommitItemCompletionOptions,"id" | "reason" | "evidence" | "closeOptions" | "releaseOptions">):BulkItemMutation[];
 /**
  * Record evidence, close an item, and release its claim as one compensating
  * transaction. A failure restores the exact pre-completion item version, so
  * callers never observe the protocol's otherwise possible half-finished
  * states through a committed result.
  */
-export declare function commitItemCompletion(options: CommitItemCompletionOptions): Promise<CommitItemMutationsResult>;
+export declare function commitItemCompletion(options:CommitItemCompletionOptions):Promise<CommitItemMutationsResult>;
 /** Public contract for test only item transaction internals, shared with white-box specs. */
-export declare const _testOnlyItemTransaction: {
-buildCreateStep: typeof buildCreateStep;
-bulkHistoryMarker: typeof bulkHistoryMarker;
-compensateByRestore: typeof compensateByRestore;
-deriveStepId: typeof deriveStepId;
-isUpdateMarkerApplied: typeof isUpdateMarkerApplied;
-readItemSnapshot: typeof readItemSnapshot;
+export declare const _testOnlyItemTransaction:{
+buildCreateStep:typeof buildCreateStep;
+bulkHistoryMarker:typeof bulkHistoryMarker;
+compensateByRestore:typeof compensateByRestore;
+deriveStepId:typeof deriveStepId;
+isUpdateMarkerApplied:typeof isUpdateMarkerApplied;
+readItemSnapshot:typeof readItemSnapshot;
 };
 export {};

package/dist/sdk/item-transaction.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]="7ff78f44-c9db-5221-b09a-32b78876b461")}catch{}})();import crypto from"node:crypto";import{constants}from"node:fs";import{isFileMissingError,readRegularFile,transactionPreviewNonRegularFileError}from"../core/fs/fs-utils.js";import{cp,lstat,mkdir,mkdtemp,open,readdir,realpath,rm,stat,writeFile}from"node:fs/promises";import{tmpdir}from"node:os";import{getActiveExtensionRegistrations,setActiveExtensionRegistrations}from"../core/extensions/index.js";import path from"node:path";import{transferMutationStdinTokenPolicy}from"../core/item/parse.js";import{EXIT_CODE,PM_REQUIRED_SUBDIRS,SETTINGS_DEFAULTS,SETTINGS_FILENAME}from"../core/shared/constants.js";import{resolveItemTypeRegistry}from"../core/item/type-registry.js";import{DEFAULT_RUNTIME_SCHEMA_FILE_PATHS,filePathForSchemaSection,loadRuntimeSchemaFromOptionalFiles,normalizeRuntimeSchemaSettings}from"../core/schema/runtime-schema.js";import{validateSettings}from"../core/store/settings-validator.js";import{resolveWorkspaceRoot}from"../core/store/paths.js";import{getSessionStatePath}from"../core/session/session-state.js";import{PmCliError}from"../core/shared/errors.js";import{stableStringify}from"../core/shared/serialization.js";import{readHistoryEntries}from"./history-read.js";import{PM_CONTEXT_INTENTS_FILE}from"./context-intent-runtime.js";import{close,create,deleteItem,get,release,restore,update,runWithActiveExtensions}from"./runtime.js";import{commitWorkspaceTransaction,validateWorkspaceTransactionIdentity}from"./workspace-transaction.js";function mergeTransactionMutationOptions(source,additions){const merged={...source,...additions};return source===void 0?merged:transferMutationStdinTokenPolicy(source,merged)}async function readItemSnapshot(pmRoot,id){try{const item=(await get(id,{},{pmRoot})).item;return{id:item.id,closedAt:item.closed_at,updatedAt:item.updated_at,assignee:item.assignee,claimPrincipal:item.claim_principal}}catch(error){if(error instanceof PmCliError&&error.exitCode===EXIT_CODE.NOT_FOUND)return;throw error}}function deriveStepId(mutation,index){const sanitizedTarget=mutation.id.replaceAll(/[^a-zA-Z0-9._-]/gu,"_"),fingerprint=crypto.createHash("sha256").update(stableStringify(mutation)).digest("hex").slice(0,12);return`${index+1}-${mutation.op}-${sanitizedTarget}-${fingerprint}`}function deriveOutcomeKey(mutation,index){const sanitizedTarget=mutation.id.replaceAll(/[^a-zA-Z0-9._-]/gu,"_");return`${index+1}-${mutation.op}-${sanitizedTarget}`}function bulkHistoryMarker(transactionId,stepId,phase){return`bulk-item-transaction ${transactionId} ${stepId} ${phase}`}async function isUpdateMarkerApplied(pmRoot,canonicalId,transactionId,stepId){const entries=await readHistoryEntries(path.join(pmRoot,"history",`${canonicalId}.jsonl`),canonicalId),applyMarker=bulkHistoryMarker(transactionId,stepId,"apply"),compensateMarker=bulkHistoryMarker(transactionId,stepId,"compensate");for(let index=entries.length-1;index>=0;index-=1){const message=entries[index].message;if(message===applyMarker)return!0;if(message===compensateMarker)return!1}return!1}async function prepareRestoreCompensation(pmRoot,mutation){const snapshot=await readItemSnapshot(pmRoot,mutation.id);if(snapshot?.updatedAt===void 0)throw new PmCliError(`Bulk ${mutation.op} target ${mutation.id} does not exist or has no restorable version`,EXIT_CODE.NOT_FOUND);return{target_updated_at:snapshot.updatedAt}}async function compensateByRestore(config,itemId,stepId,data){const target=data!==null&&typeof data=="object"&&!Array.isArray(data)?data.target_updated_at:void 0;typeof target=="string"&&await readItemSnapshot(config.pmRoot,itemId)!==void 0&&await restore(itemId,target,{force:!0,author:config.author,message:bulkHistoryMarker(config.transactionId,stepId,"compensate")},{pmRoot:config.pmRoot})}function buildCreateStep(config,mutation,stepId){return{id:stepId,async inspect(){const snapshot=await readItemSnapshot(config.pmRoot,mutation.id);return snapshot===void 0?{state:"pending"}:{state:"applied",result:{id:snapshot.id,op:"create"}}},async apply(){const createdItem=(await create(mergeTransactionMutationOptions(mutation.options,{author:config.author,id:mutation.id}),{pmRoot:config.pmRoot})).item;return{id:String(createdItem.id),op:"create"}},async compensate(){const snapshot=await readItemSnapshot(config.pmRoot,mutation.id);if(snapshot!==void 0){if(config.createCompensation==="delete"){await deleteItem(mutation.id,{force:!0,author:config.author,message:`Compensate interrupted bulk transaction ${config.transactionId}`},{pmRoot:config.pmRoot});return}snapshot.closedAt===void 0&&await close(mutation.id,`Compensated: interrupted bulk transaction ${config.transactionId}`,{force:!0,author:config.author},{pmRoot:config.pmRoot})}}}}function buildUpdateStep(config,mutation,stepId){return{id:stepId,async inspect(){const snapshot=await readItemSnapshot(config.pmRoot,mutation.id);return snapshot===void 0?{state:"pending"}:await isUpdateMarkerApplied(config.pmRoot,snapshot.id,config.transactionId,stepId)?{state:"applied",result:{id:snapshot.id,op:"update"}}:{state:"pending"}},async prepareCompensation(){return prepareRestoreCompensation(config.pmRoot,mutation)},async apply(){const updatedItem=(await update(mutation.id,mergeTransactionMutationOptions(mutation.options,{author:config.author,message:bulkHistoryMarker(config.transactionId,stepId,"apply")}),{pmRoot:config.pmRoot})).item;return{id:String(updatedItem.id),op:"update"}},async compensate(data){await compensateByRestore(config,mutation.id,stepId,data)}}}function buildCloseStep(config,mutation,stepId){return{id:stepId,async inspect(){const snapshot=await readItemSnapshot(config.pmRoot,mutation.id);return snapshot===void 0?{state:"pending"}:await isUpdateMarkerApplied(config.pmRoot,snapshot.id,config.transactionId,stepId)?{state:"applied",result:{id:snapshot.id,op:"close"}}:snapshot.closedAt===void 0?{state:"pending"}:{state:"applied",result:{id:snapshot.id,op:"close"}}},async prepareCompensation(){return prepareRestoreCompensation(config.pmRoot,mutation)},async apply(){const closedItem=(await close(mutation.id,mutation.reason,mergeTransactionMutationOptions(mutation.options,{author:config.author,message:bulkHistoryMarker(config.transactionId,stepId,"apply")}),{pmRoot:config.pmRoot})).item;return{id:String(closedItem.id),op:"close"}},async compensate(data){await compensateByRestore(config,mutation.id,stepId,data)}}}function buildReleaseStep(config,mutation,stepId){return{id:stepId,async inspect(){const snapshot=await readItemSnapshot(config.pmRoot,mutation.id);return snapshot===void 0?{state:"pending"}:await isUpdateMarkerApplied(config.pmRoot,snapshot.id,config.transactionId,stepId)?{state:"applied",result:{id:snapshot.id,op:"release"}}:snapshot.assignee!==void 0||snapshot.claimPrincipal!==void 0?{state:"pending"}:{state:"applied",result:{id:snapshot.id,op:"release"}}},async prepareCompensation(){return prepareRestoreCompensation(config.pmRoot,mutation)},async apply(){const releasedItem=(await release(mutation.id,mergeTransactionMutationOptions(mutation.options,{author:config.author,message:bulkHistoryMarker(config.transactionId,stepId,"apply")}),{pmRoot:config.pmRoot})).item;return{id:String(releasedItem.id),op:"release"}},async compensate(data){await compensateByRestore(config,mutation.id,stepId,data)}}}function buildStepForMutation(config,mutation,index){const stepId=deriveStepId(mutation,index);switch(mutation.op){case"create":return buildCreateStep(config,mutation,stepId);case"update":return buildUpdateStep(config,mutation,stepId);case"close":return buildCloseStep(config,mutation,stepId);case"release":return buildReleaseStep(config,mutation,stepId)}}function assertValidBulkMutation(mutation,index){if(mutation===null||typeof mutation!="object"||Array.isArray(mutation))throw new TypeError(`Bulk mutation ${index+1} must be an object`);if(!["create","update","close","release"].includes(mutation.op))throw new TypeError(`Bulk mutation ${index+1} op must be create, update, close, or release`);if(typeof mutation.id!="string"||mutation.id.trim().length===0)throw new TypeError(`Bulk mutation ${index+1} requires a non-empty id`);if(mutation.op==="close"&&(typeof mutation.reason!="string"||mutation.reason.trim().length===0))throw new TypeError(`Bulk close mutation ${index+1} requires a non-empty reason`)}async function validateMutationOperation(mutation,index,run){try{return await run()}catch(error){throw error instanceof PmCliError?new PmCliError(error.message,error.exitCode,{...error.context,transaction_operation:{index,op:mutation.op,id:mutation.id}}):error}}function includePreviewPath(root,file,ownedPaths,retainedPaths){const relative=path.relative(root,file);return["locks","runtime","search"].includes(relative.split(path.sep)[0])?retainedPaths.some(retained=>relative===retained||relative.startsWith(`${retained}${path.sep}`)||retained.startsWith(`${relative}${path.sep}`)):relative===""||ownedPaths===void 0||ownedPaths.some(owned=>relative===owned||relative.startsWith(`${owned}${path.sep}`)||owned.startsWith(`${relative}${path.sep}`))}async function previewEntryStat(file){const entry=await lstat(file);if(entry.isSymbolicLink())await stat(file);else if(entry.isDirectory()||entry.isFile())return entry;throw transactionPreviewNonRegularFileError()}async function previewFileDigest(file){const handle=await open(file,constants.O_RDONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK);try{const entry=await handle.stat();if(!entry.isFile())throw transactionPreviewNonRegularFileError();const contents=crypto.createHash("sha256");if(entry.size>0)for await(const chunk of handle.createReadStream({highWaterMark:64*1024,end:entry.size-1,autoClose:!1}))contents.update(chunk);return contents.digest()}finally{await handle.close()}}async function previewTrackerFingerprint(root,ownedPaths,retainedPaths){const fingerprint=crypto.createHash("sha256");async function visit(directory){for(const name of(await readdir(directory)).sort()){const file=path.join(directory,name);includePreviewPath(root,file,ownedPaths,retainedPaths)&&((await previewEntryStat(file)).isDirectory()?await visit(file):(fingerprint.update(JSON.stringify(path.relative(root,file))),fingerprint.update(await previewFileDigest(file))))}}return await visit(root),fingerprint.digest("hex")}function previewSnapshotChangedError(){return new PmCliError("Tracker changed while preparing the transaction preview; retry against stable state.",EXIT_CODE.CONFLICT,{code:"transaction_preview_snapshot_changed"})}async function isDisappearingPreviewPath(error){if(!isFileMissingError(error))return!1;const file=error.path;if(typeof file!="string")return!1;const original=path.resolve(file);let candidate=original;for(;;)try{const entry=await lstat(candidate);return candidate!==original&&entry.isDirectory()}catch(lookupError){if(!isFileMissingError(lookupError))return!1;const parent=path.dirname(candidate);if(parent===candidate)return!1;candidate=parent}}async function readPreviewConfiguration(root,relative){const file=path.join(root,relative);try{let current=root;for(const component of relative.split(path.sep).slice(0,-1))current=path.join(current,component),await previewEntryStat(current);if(!(await previewEntryStat(file)).isFile())throw transactionPreviewNonRegularFileError();return await readRegularFile(file,transactionPreviewNonRegularFileError())}catch(error){if(await isDisappearingPreviewPath(error))return;throw error}}async function resolvePreviewStorage(root,configurationRoot,registrations){const configuration=new Map,rawSettings=await readPreviewConfiguration(root,SETTINGS_FILENAME);configuration.set(SETTINGS_FILENAME,rawSettings);let parsed;try{parsed=JSON.parse(rawSettings??"null")}catch{parsed=null}const validated=validateSettings(parsed),settings=validated.success?validated.data:void 0,schema=normalizeRuntimeSchemaSettings(settings?.schema);for(const[section,configuredPath]of Object.entries(schema.files)){const relative=path.relative(root,filePathForSchemaSection(root,configuredPath,DEFAULT_RUNTIME_SCHEMA_FILE_PATHS[section]));if(relative===""||!path.resolve(root,relative).startsWith(path.join(root,path.sep)))throw new PmCliError("Transaction preview requires schema files inside the selected tracker root; relocate the configured schema file before retrying.",EXIT_CODE.USAGE,{code:"transaction_preview_external_schema",field:`schema.files.${section}`});schema.files[section]=relative;const contents=await readPreviewConfiguration(root,relative);if(configuration.set(relative,contents),contents!==void 0){const target=path.join(configurationRoot,relative);await mkdir(path.dirname(target),{recursive:!0}),await writeFile(target,contents)}}const sessionPath=path.relative(root,getSessionStatePath(root));configuration.set(sessionPath,await readPreviewConfiguration(root,sessionPath));const loaded=await loadRuntimeSchemaFromOptionalFiles(configurationRoot,schema),registry=resolveItemTypeRegistry({...SETTINGS_DEFAULTS,item_types:{definitions:[...settings?.item_types?.definitions??[],...loaded.type_definitions_from_file??[]]}},registrations),ownedPaths=resolveWorkspaceRoot(root)===root?[...PM_REQUIRED_SUBDIRS.filter(Boolean),SETTINGS_FILENAME,PM_CONTEXT_INTENTS_FILE,"transactions",...registry.folders,...configuration.keys()].map(entry=>path.normalize(entry)):void 0,stagedSettings=settings===void 0?void 0:JSON.stringify({...parsed,schema:{...settings.schema,files:schema.files}});return{configuration,ownedPaths,stagedSettings,registryFolders:registry.folders}}async function stagePreviewTracker(sourceRoot,stagedRoot,registrations){await stat(sourceRoot);try{const resolvedRoot=await realpath(sourceRoot),storage=await resolvePreviewStorage(resolvedRoot,path.join(path.dirname(stagedRoot),"configuration"),registrations),retainedPaths=[...storage.configuration.keys(),...storage.registryFolders].map(entry=>path.normalize(entry)),sourceFingerprint=await previewTrackerFingerprint(resolvedRoot,storage.ownedPaths,retainedPaths);await cp(resolvedRoot,stagedRoot,{recursive:!0,dereference:!1,filter:async source=>includePreviewPath(resolvedRoot,source,storage.ownedPaths,retainedPaths)?(await previewEntryStat(source),!0):!1});const[currentFingerprint,stagedFingerprint]=await Promise.all([previewTrackerFingerprint(resolvedRoot,storage.ownedPaths,retainedPaths),previewTrackerFingerprint(stagedRoot,storage.ownedPaths,retainedPaths)]);if(sourceFingerprint!==currentFingerprint||sourceFingerprint!==stagedFingerprint)throw previewSnapshotChangedError();for(const[relative,contents]of storage.configuration)if(await readPreviewConfiguration(stagedRoot,relative)!==contents)throw previewSnapshotChangedError();storage.stagedSettings!==void 0&&await writeFile(path.join(stagedRoot,SETTINGS_FILENAME),storage.stagedSettings)}catch(error){throw await isDisappearingPreviewPath(error)?previewSnapshotChangedError():error}}async function previewItemMutations(options){const identity=validateWorkspaceTransactionIdentity(options),mutations=[...options.mutations];if(mutations.length===0)throw new TypeError("Bulk item transaction requires at least one mutation");for(const[index,mutation]of mutations.entries())assertValidBulkMutation(mutation,index);const registrations=getActiveExtensionRegistrations(),root=await mkdtemp(path.join(tmpdir(),"pm-transaction-preview-")),stagedRoot=path.join(root,"tracker");try{await stagePreviewTracker(identity.pmRoot,stagedRoot,registrations);let validated=!1;return await runWithActiveExtensions({path:stagedRoot,noExtensions:!0},async()=>{setActiveExtensionRegistrations(registrations);const config={...identity,pmRoot:stagedRoot,createCompensation:"close"},steps=mutations.map((mutation,index)=>{const step=buildStepForMutation(config,mutation,index);return{...step,inspect:()=>validateMutationOperation(mutation,index,()=>step.inspect()),prepareCompensation:()=>validateMutationOperation(mutation,index,async()=>step.prepareCompensation?.()),apply:()=>validateMutationOperation(mutation,index,()=>step.apply())}});await commitWorkspaceTransaction({...identity,pmRoot:stagedRoot,steps,onTransition:({transition})=>{transition==="committed"&&(validated=!0)}})}),{validated,state:validated?"staged_snapshot":"replayed_committed_plan",unresolved_commit_constraints:["concurrent_tracker_changes","extension_mutation_guards_and_hooks"]}}finally{await rm(root,{recursive:!0,force:!0})}}async function commitItemMutations(options){const mutations=[...options.mutations];if(mutations.length===0)throw new TypeError("Bulk item transaction requires at least one mutation");for(const[index,mutation]of mutations.entries())assertValidBulkMutation(mutation,index);const createCompensation=options.createCompensation??"close";if(!["close","delete"].includes(createCompensation))throw new TypeError("Bulk item transaction createCompensation must be close or delete");const stepConfig={pmRoot:options.pmRoot,author:options.author,transactionId:options.transactionId,createCompensation},committed=await commitWorkspaceTransaction({pmRoot:options.pmRoot,transactionId:options.transactionId,author:options.author,steps:mutations.map((mutation,index)=>buildStepForMutation(stepConfig,mutation,index)),...options.lockTtlSeconds===void 0?{}:{lockTtlSeconds:options.lockTtlSeconds},...options.lockWaitMs===void 0?{}:{lockWaitMs:options.lockWaitMs},...options.onTransition===void 0?{}:{onTransition:options.onTransition}}),results={};for(const[index,mutation]of mutations.entries()){const stepId=deriveStepId(mutation,index),value=committed.results[stepId];results[deriveOutcomeKey(mutation,index)]=value}return{transactionId:committed.transactionId,status:"committed",recovered:committed.recovered,results}}function buildItemCompletionMutations(options){const mutations=[];return options.evidence!==void 0&&Object.keys(options.evidence).length>0&&mutations.push({op:"update",id:options.id,options:options.evidence}),mutations.push({op:"close",id:options.id,reason:options.reason,...options.closeOptions===void 0?{}:{options:options.closeOptions}},{op:"release",id:options.id,...options.releaseOptions===void 0?{}:{options:options.releaseOptions}}),mutations}function commitItemCompletion(options){return commitItemMutations({pmRoot:options.pmRoot,transactionId:options.transactionId,author:options.author,mutations:buildItemCompletionMutations(options),...options.lockTtlSeconds===void 0?{}:{lockTtlSeconds:options.lockTtlSeconds},...options.lockWaitMs===void 0?{}:{lockWaitMs:options.lockWaitMs},...options.onTransition===void 0?{}:{onTransition:options.onTransition}})}const _testOnlyItemTransaction={buildCreateStep,bulkHistoryMarker,compensateByRestore,deriveStepId,isUpdateMarkerApplied,readItemSnapshot};export{_testOnlyItemTransaction,buildItemCompletionMutations,commitItemCompletion,commitItemMutations,previewItemMutations};
+(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]="03112259-10b6-53a9-8e6b-e541ac8c7d5d")}catch{}})();import crypto from"node:crypto";import{constants}from"node:fs";import{isFileMissingError,readRegularFile,transactionPreviewNonRegularFileError}from"../core/fs/fs-utils.js";import{cp,lstat,mkdir,mkdtemp,open,readdir,realpath,rm,stat,writeFile}from"node:fs/promises";import{tmpdir}from"node:os";import{getActiveExtensionRegistrations,setActiveExtensionRegistrations}from"../core/extensions/index.js";import path from"node:path";import{transferMutationStdinTokenPolicy}from"../core/item/parse.js";import{EXIT_CODE,PM_REQUIRED_SUBDIRS,SETTINGS_DEFAULTS,SETTINGS_FILENAME}from"../core/shared/constants.js";import{resolveItemTypeRegistry}from"../core/item/type-registry.js";import{listAllItemMetadataLight}from"../core/store/item-store.js";import{runWithItemMutationPrecondition}from"../core/store/item-mutation-precondition.js";import{isConfigurationOnlySettingsRead,readSettings}from"../core/store/settings.js";import{DEFAULT_RUNTIME_SCHEMA_FILE_PATHS,filePathForSchemaSection,loadRuntimeSchemaFromOptionalFiles,normalizeRuntimeSchemaSettings}from"../core/schema/runtime-schema.js";import{validateSettings}from"../core/store/settings-validator.js";import{resolveWorkspaceRoot}from"../core/store/paths.js";import{getSessionStatePath}from"../core/session/session-state.js";import{PmCliError}from"../core/shared/errors.js";import{stableUpsertValue}from"./structured-mutations.js";import{stableStringify}from"../core/shared/serialization.js";import{assertMutationOptionValueTypes}from"./lifecycle/mutation-option-validation.js";import{readHistoryEntries}from"./history-read.js";import{PM_CONTEXT_INTENTS_FILE}from"./context-intent-runtime.js";import{close,create,deleteItem,get,release,restore,update,runWithActiveExtensions}from"./runtime.js";import{commitWorkspaceTransaction,validateWorkspaceTransactionIdentity}from"./workspace-transaction.js";async function resolveTransactionSchema(pmRoot,settings){if(!isConfigurationOnlySettingsRead(pmRoot))return{schema:normalizeRuntimeSchemaSettings(settings.schema),typeDefinitionsFromFile:[]};const loaded=await loadGuardedRuntimeSchema(pmRoot,settings.schema);return{schema:loaded.schema,typeDefinitionsFromFile:loaded.type_definitions_from_file??[]}}async function listUpsertKeyCandidates(pmRoot,settings,schemaContext,key){const typeRegistry=resolveItemTypeRegistry({...settings,item_types:{...settings.item_types,definitions:[...settings.item_types?.definitions??[],...schemaContext.typeDefinitionsFromFile]}},getActiveExtensionRegistrations());return(await listAllItemMetadataLight(pmRoot,settings.item_format,typeRegistry.type_to_folder,void 0,schemaContext.schema)).flatMap(item=>{const value=item[key];return value==null?[]:[{id:item.id,value}]})}function createUniqueKeyIndex(pmRoot){const scans=new Map,scan=async key=>{const settings=await readSettings(pmRoot),schemaContext=await resolveTransactionSchema(pmRoot,settings),byValue=new Map;for(const candidate of await listUpsertKeyCandidates(pmRoot,settings,schemaContext,key)){const stable=stableUpsertValue(candidate.value);byValue.set(stable,[...byValue.get(stable)??[],candidate.id])}return byValue};return{lookup(key){const pending=scans.get(key)??scan(key);return scans.set(key,pending),pending},async recordCreate(item){for(const[key,pending]of scans){const value=item[key];if(value==null)continue;const byValue=await pending,stable=stableUpsertValue(value);byValue.set(stable,[...byValue.get(stable)??[],String(item.id)])}},invalidate(){scans.clear()}}}async function assertUniqueKeyFree(index,unique){const stable=stableUpsertValue(unique.value),existing=(await index.lookup(unique.key)).get(stable)??[];if(existing.length!==0)throw new PmCliError(`Upsert key "${unique.key}" value ${JSON.stringify(stable)} now matches existing item ${existing.join(", ")}; the plan was resolved before it existed.`,EXIT_CODE.CONFLICT,{code:"upsert_key_conflict",required:"Re-plan the document so the row updates the existing item instead of creating a duplicate.",why:"Keyed upsert is resolved before the writer lock, so every remaining create is re-checked under the lock; concurrent imports therefore cannot create two items for one key value.",nextSteps:["Re-run pm item mutate with the same document and --upsert-key; the re-plan turns the row into an update of the existing item.","Inspect the existing item first when its content should win over the document row."]})}function assertUpsertMatchCurrent(document,id,match){const current=document.metadata[match.key],expected=stableUpsertValue(match.value);if(stableUpsertValue(current)!==expected)throw new PmCliError(`Item ${id} no longer carries upsert key "${match.key}" value ${JSON.stringify(expected)}; the plan selected it before the key changed.`,EXIT_CODE.CONFLICT,{code:"upsert_match_changed",required:"Re-plan the document so the row is resolved against the current key values.",why:"Keyed upsert selects its target before the writer lock, so the update re-reads the key under the lock instead of updating a mismatched item blindly.",nextSteps:["Re-run pm item mutate with the same document and --upsert-key; the re-plan creates or re-targets the row from the current key values."]})}function isValidUniqueKey(value){if(value===null||typeof value!="object"||Array.isArray(value))return!1;const candidate=value;return typeof candidate.key=="string"&&candidate.key.trim().length>0&&candidate.value!==void 0&&candidate.value!==null}function mergeTransactionMutationOptions(source,additions){const merged={...source,...additions};return source===void 0?merged:transferMutationStdinTokenPolicy(source,merged)}async function readItemSnapshot(pmRoot,id){try{const item=(await get(id,{},{pmRoot})).item;return{id:item.id,closedAt:item.closed_at,updatedAt:item.updated_at,assignee:item.assignee,claimPrincipal:item.claim_principal}}catch(error){if(error instanceof PmCliError&&error.exitCode===EXIT_CODE.NOT_FOUND)return;throw error}}function deriveStepId(mutation,index){const sanitizedTarget=mutation.id.replaceAll(/[^a-zA-Z0-9._-]/gu,"_"),fingerprint=crypto.createHash("sha256").update(stableStringify(mutation)).digest("hex").slice(0,12);return`${index+1}-${mutation.op}-${sanitizedTarget}-${fingerprint}`}function deriveOutcomeKey(mutation,index){const sanitizedTarget=mutation.id.replaceAll(/[^a-zA-Z0-9._-]/gu,"_");return`${index+1}-${mutation.op}-${sanitizedTarget}`}function bulkHistoryMarker(transactionId,stepId,phase){return`bulk-item-transaction ${transactionId} ${stepId} ${phase}`}async function isUpdateMarkerApplied(pmRoot,canonicalId,transactionId,stepId){const entries=await readHistoryEntries(path.join(pmRoot,"history",`${canonicalId}.jsonl`),canonicalId),applyMarker=bulkHistoryMarker(transactionId,stepId,"apply"),compensateMarker=bulkHistoryMarker(transactionId,stepId,"compensate");for(let index=entries.length-1;index>=0;index-=1){const message=entries[index].message;if(message===applyMarker)return!0;if(message===compensateMarker)return!1}return!1}async function prepareRestoreCompensation(pmRoot,mutation){const snapshot=await readItemSnapshot(pmRoot,mutation.id);if(snapshot?.updatedAt===void 0)throw new PmCliError(`Bulk ${mutation.op} target ${mutation.id} does not exist or has no restorable version`,EXIT_CODE.NOT_FOUND);return{target_updated_at:snapshot.updatedAt}}async function compensateByRestore(config,itemId,stepId,data){const target=data!==null&&typeof data=="object"&&!Array.isArray(data)?data.target_updated_at:void 0;typeof target=="string"&&await readItemSnapshot(config.pmRoot,itemId)!==void 0&&await restore(itemId,target,{force:!0,author:config.author,message:bulkHistoryMarker(config.transactionId,stepId,"compensate")},{pmRoot:config.pmRoot})}function buildCreateStep(config,mutation,stepId){return{id:stepId,async inspect(){const snapshot=await readItemSnapshot(config.pmRoot,mutation.id);if(snapshot===void 0)return{state:"pending"};if(snapshot.closedAt!==void 0){const history=await readHistoryEntries(path.join(config.pmRoot,"history",`${snapshot.id}.jsonl`),snapshot.id),reason=`Compensated: interrupted bulk transaction ${config.transactionId}`;if(history.filter(entry=>entry.op==="close").at(-1)?.patch.some(change=>change.op==="add"||change.op==="replace"?change.path==="/metadata/close_reason"&&change.value===reason:!1)??!1)throw new PmCliError(`Created item ${snapshot.id} remains closed by transaction compensation; explicitly reopen or reconcile it before retrying.`,EXIT_CODE.CONFLICT,{code:"transaction_create_compensated",item_id:snapshot.id,required:"Review the compensated item and explicitly reopen it before retrying the same document.",why:"This item's latest closure belongs to transaction compensation. Automatically reopening it could overwrite later lifecycle decisions.",nextSteps:[`Run pm item reopen ${snapshot.id} "Retry compensated creation" after reviewing its history, then retry the transaction.`]})}return{state:"applied",result:{id:snapshot.id,op:"create"}}},async apply(){mutation.unique!==void 0&&await assertUniqueKeyFree(config.uniqueIndex,mutation.unique);const createdItem=(await create(mergeTransactionMutationOptions(mutation.options,{author:config.author,id:mutation.id}),{pmRoot:config.pmRoot})).item;return await config.uniqueIndex.recordCreate(createdItem),{id:String(createdItem.id),op:"create"}},async compensate(){const snapshot=await readItemSnapshot(config.pmRoot,mutation.id);if(snapshot!==void 0){if(config.createCompensation==="delete"){await deleteItem(mutation.id,{force:!0,author:config.author,message:`Compensate interrupted bulk transaction ${config.transactionId}`},{pmRoot:config.pmRoot});return}snapshot.closedAt===void 0&&await close(mutation.id,`Compensated: interrupted bulk transaction ${config.transactionId}`,{force:!0,author:config.author},{pmRoot:config.pmRoot})}}}}function buildUpdateStep(config,mutation,stepId){return{id:stepId,async inspect(){const snapshot=await readItemSnapshot(config.pmRoot,mutation.id);return snapshot===void 0?{state:"pending"}:await isUpdateMarkerApplied(config.pmRoot,snapshot.id,config.transactionId,stepId)?{state:"applied",result:{id:snapshot.id,op:"update"}}:{state:"pending"}},async prepareCompensation(){return prepareRestoreCompensation(config.pmRoot,mutation)},async apply(){const applyUpdate=()=>update(mutation.id,mergeTransactionMutationOptions(mutation.options,{author:config.author,message:bulkHistoryMarker(config.transactionId,stepId,"apply")}),{pmRoot:config.pmRoot}),match=mutation.match,updatedItem=(match===void 0?await applyUpdate():await runWithItemMutationPrecondition({pmRoot:config.pmRoot,id:String((await get(mutation.id,{},{pmRoot:config.pmRoot})).item.id),validate:document=>assertUpsertMatchCurrent(document,mutation.id,match)},applyUpdate)).item;return config.uniqueIndex.invalidate(),{id:String(updatedItem.id),op:"update"}},async compensate(data){await compensateByRestore(config,mutation.id,stepId,data)}}}function buildCloseStep(config,mutation,stepId){return{id:stepId,async inspect(){const snapshot=await readItemSnapshot(config.pmRoot,mutation.id);return snapshot===void 0?{state:"pending"}:await isUpdateMarkerApplied(config.pmRoot,snapshot.id,config.transactionId,stepId)?{state:"applied",result:{id:snapshot.id,op:"close"}}:snapshot.closedAt===void 0?{state:"pending"}:{state:"applied",result:{id:snapshot.id,op:"close"}}},async prepareCompensation(){return prepareRestoreCompensation(config.pmRoot,mutation)},async apply(){const closedItem=(await close(mutation.id,mutation.reason,mergeTransactionMutationOptions(mutation.options,{author:config.author,message:bulkHistoryMarker(config.transactionId,stepId,"apply")}),{pmRoot:config.pmRoot})).item;return config.uniqueIndex.invalidate(),{id:String(closedItem.id),op:"close"}},async compensate(data){await compensateByRestore(config,mutation.id,stepId,data)}}}function buildReleaseStep(config,mutation,stepId){return{id:stepId,async inspect(){const snapshot=await readItemSnapshot(config.pmRoot,mutation.id);return snapshot===void 0?{state:"pending"}:await isUpdateMarkerApplied(config.pmRoot,snapshot.id,config.transactionId,stepId)?{state:"applied",result:{id:snapshot.id,op:"release"}}:snapshot.assignee!==void 0||snapshot.claimPrincipal!==void 0?{state:"pending"}:{state:"applied",result:{id:snapshot.id,op:"release"}}},async prepareCompensation(){return prepareRestoreCompensation(config.pmRoot,mutation)},async apply(){const releasedItem=(await release(mutation.id,mergeTransactionMutationOptions(mutation.options,{author:config.author,message:bulkHistoryMarker(config.transactionId,stepId,"apply")}),{pmRoot:config.pmRoot})).item;return config.uniqueIndex.invalidate(),{id:String(releasedItem.id),op:"release"}},async compensate(data){await compensateByRestore(config,mutation.id,stepId,data)}}}function buildStepForMutation(config,mutation,index){const stepId=deriveStepId(mutation,index);switch(mutation.op){case"create":return buildCreateStep(config,mutation,stepId);case"update":return buildUpdateStep(config,mutation,stepId);case"close":return buildCloseStep(config,mutation,stepId);case"release":return buildReleaseStep(config,mutation,stepId)}}function assertValidBulkMutation(mutation,index){if(mutation===null||typeof mutation!="object"||Array.isArray(mutation))throw new TypeError(`Bulk mutation ${index+1} must be an object`);if(!["create","update","close","release"].includes(mutation.op))throw new TypeError(`Bulk mutation ${index+1} op must be create, update, close, or release`);if(typeof mutation.id!="string"||mutation.id.trim().length===0)throw new TypeError(`Bulk mutation ${index+1} requires a non-empty id`);if(mutation.op==="close"&&(typeof mutation.reason!="string"||mutation.reason.trim().length===0))throw new TypeError(`Bulk close mutation ${index+1} requires a non-empty reason`);if(mutation.op==="create"&&mutation.unique!==void 0&&!isValidUniqueKey(mutation.unique))throw new TypeError(`Bulk create mutation ${index+1} unique must be an object with a non-empty key and a value`);if(mutation.op==="update"&&mutation.match!==void 0&&!isValidUniqueKey(mutation.match))throw new TypeError(`Bulk update mutation ${index+1} match must be an object with a non-empty key and a value`);assertMutationOptionValueTypes(mutation.options,mutation.op,index)}function assertValidBulkMutations(mutations){if(mutations.length===0)throw new TypeError("Bulk item transaction requires at least one mutation");const keys=new Map;for(const[index,mutation]of mutations.entries()){if(assertValidBulkMutation(mutation,index),mutation.op!=="create"||mutation.unique===void 0)continue;const{key,value}=mutation.unique,values=keys.get(key)??new Map,stable=stableUpsertValue(value),previous=values.get(stable);if(previous!==void 0)throw new PmCliError(`Bulk create mutations ${previous+1} and ${index+1} share the upsert key value ${JSON.stringify(stable)} for "${key}".`,EXIT_CODE.USAGE,{code:"upsert_key_duplicate",required:"Each create must carry a distinct unique key value within one batch.",why:"Direct SDK batches must preserve the same uniqueness invariant as planned document rows."});values.set(stable,index),keys.set(key,values)}}async function validateMutationOperation(mutation,index,run){try{return await run()}catch(error){throw error instanceof PmCliError?new PmCliError(error.message,error.exitCode,{...error.context,transaction_operation:{index,op:mutation.op,id:mutation.id}}):error}}function includePreviewPath(root,file,ownedPaths,retainedPaths){const relative=path.relative(root,file);return["locks","runtime","search"].includes(relative.split(path.sep)[0])?retainedPaths.some(retained=>relative===retained||relative.startsWith(`${retained}${path.sep}`)||retained.startsWith(`${relative}${path.sep}`)):relative===""||ownedPaths===void 0||ownedPaths.some(owned=>relative===owned||relative.startsWith(`${owned}${path.sep}`)||owned.startsWith(`${relative}${path.sep}`))}async function previewEntryStat(file){const entry=await lstat(file);if(entry.isSymbolicLink())await stat(file);else if(entry.isDirectory()||entry.isFile())return entry;throw transactionPreviewNonRegularFileError()}async function previewFileDigest(file){const handle=await open(file,constants.O_RDONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK);try{const entry=await handle.stat();if(!entry.isFile())throw transactionPreviewNonRegularFileError();const contents=crypto.createHash("sha256");if(entry.size>0)for await(const chunk of handle.createReadStream({highWaterMark:64*1024,end:entry.size-1,autoClose:!1}))contents.update(chunk);return contents.digest()}finally{await handle.close()}}async function previewTrackerFingerprint(root,ownedPaths,retainedPaths){const fingerprint=crypto.createHash("sha256");async function visit(directory){for(const name of(await readdir(directory)).sort()){const file=path.join(directory,name);includePreviewPath(root,file,ownedPaths,retainedPaths)&&((await previewEntryStat(file)).isDirectory()?await visit(file):(fingerprint.update(JSON.stringify(path.relative(root,file))),fingerprint.update(await previewFileDigest(file))))}}return await visit(root),fingerprint.digest("hex")}function previewSnapshotChangedError(){return new PmCliError("Tracker changed while preparing the transaction preview; retry against stable state.",EXIT_CODE.CONFLICT,{code:"transaction_preview_snapshot_changed"})}async function isDisappearingPreviewPath(error){if(!isFileMissingError(error))return!1;const file=error.path;if(typeof file!="string")return!1;const original=path.resolve(file);let candidate=original;for(;;)try{const entry=await lstat(candidate);return candidate!==original&&entry.isDirectory()}catch(lookupError){if(!isFileMissingError(lookupError))return!1;const parent=path.dirname(candidate);if(parent===candidate)return!1;candidate=parent}}async function readPreviewConfiguration(root,relative){const file=path.join(root,relative);try{let current=root;for(const component of relative.split(path.sep).slice(0,-1))current=path.join(current,component),await previewEntryStat(current);if(!(await previewEntryStat(file)).isFile())throw transactionPreviewNonRegularFileError();return await readRegularFile(file,transactionPreviewNonRegularFileError())}catch(error){if(await isDisappearingPreviewPath(error))return;throw error}}async function stageGuardedSchemaSections(root,configurationRoot,schemaSettings,configuration){const schema=normalizeRuntimeSchemaSettings(schemaSettings);for(const[section,configuredPath]of Object.entries(schema.files)){const relative=path.relative(root,filePathForSchemaSection(root,configuredPath,DEFAULT_RUNTIME_SCHEMA_FILE_PATHS[section]));if(relative===""||!path.resolve(root,relative).startsWith(path.join(root,path.sep)))throw new PmCliError("Transaction preview requires schema files inside the selected tracker root; relocate the configured schema file before retrying.",EXIT_CODE.USAGE,{code:"transaction_preview_external_schema",field:`schema.files.${section}`});schema.files[section]=relative;const contents=await readPreviewConfiguration(root,relative);if(configuration?.set(relative,contents),contents!==void 0){const target=path.join(configurationRoot,relative);await mkdir(path.dirname(target),{recursive:!0}),await writeFile(target,contents)}}return loadRuntimeSchemaFromOptionalFiles(configurationRoot,schema)}async function loadGuardedRuntimeSchema(pmRoot,schemaSettings){await stat(pmRoot);const root=await mkdtemp(path.join(tmpdir(),"pm-schema-plan-"));try{const resolvedRoot=await realpath(pmRoot);return await stageGuardedSchemaSections(resolvedRoot,path.join(root,"configuration"),schemaSettings)}catch(error){throw await isDisappearingPreviewPath(error)?previewSnapshotChangedError():error}finally{await rm(root,{recursive:!0,force:!0})}}async function resolvePreviewStorage(root,configurationRoot,registrations){const configuration=new Map,rawSettings=await readPreviewConfiguration(root,SETTINGS_FILENAME);configuration.set(SETTINGS_FILENAME,rawSettings);let parsed;try{parsed=JSON.parse(rawSettings??"null")}catch{parsed=null}const validated=validateSettings(parsed),settings=validated.success?validated.data:void 0,loaded=await stageGuardedSchemaSections(root,configurationRoot,settings?.schema,configuration),schema=loaded.schema,sessionPath=path.relative(root,getSessionStatePath(root));configuration.set(sessionPath,await readPreviewConfiguration(root,sessionPath));const registry=resolveItemTypeRegistry({...SETTINGS_DEFAULTS,item_types:{definitions:[...settings?.item_types?.definitions??[],...loaded.type_definitions_from_file??[]]}},registrations),ownedPaths=resolveWorkspaceRoot(root)===root?[...PM_REQUIRED_SUBDIRS.filter(Boolean),SETTINGS_FILENAME,PM_CONTEXT_INTENTS_FILE,"transactions",...registry.folders,...configuration.keys()].map(entry=>path.normalize(entry)):void 0,stagedSettings=settings===void 0?void 0:JSON.stringify({...parsed,schema:{...settings.schema,files:schema.files}});return{configuration,ownedPaths,stagedSettings,registryFolders:registry.folders}}async function stagePreviewTracker(sourceRoot,stagedRoot,registrations){await stat(sourceRoot);try{const resolvedRoot=await realpath(sourceRoot),storage=await resolvePreviewStorage(resolvedRoot,path.join(path.dirname(stagedRoot),"configuration"),registrations),retainedPaths=[...storage.configuration.keys(),...storage.registryFolders].map(entry=>path.normalize(entry)),sourceFingerprint=await previewTrackerFingerprint(resolvedRoot,storage.ownedPaths,retainedPaths);await cp(resolvedRoot,stagedRoot,{recursive:!0,dereference:!1,filter:async source=>includePreviewPath(resolvedRoot,source,storage.ownedPaths,retainedPaths)?(await previewEntryStat(source),!0):!1});const[currentFingerprint,stagedFingerprint]=await Promise.all([previewTrackerFingerprint(resolvedRoot,storage.ownedPaths,retainedPaths),previewTrackerFingerprint(stagedRoot,storage.ownedPaths,retainedPaths)]);if(sourceFingerprint!==currentFingerprint||sourceFingerprint!==stagedFingerprint)throw previewSnapshotChangedError();for(const[relative,contents]of storage.configuration)if(await readPreviewConfiguration(stagedRoot,relative)!==contents)throw previewSnapshotChangedError();storage.stagedSettings!==void 0&&await writeFile(path.join(stagedRoot,SETTINGS_FILENAME),storage.stagedSettings)}catch(error){throw await isDisappearingPreviewPath(error)?previewSnapshotChangedError():error}}async function previewItemMutations(options){const identity=validateWorkspaceTransactionIdentity(options),mutations=[...options.mutations];assertValidBulkMutations(mutations);const registrations=getActiveExtensionRegistrations(),root=await mkdtemp(path.join(tmpdir(),"pm-transaction-preview-")),stagedRoot=path.join(root,"tracker");try{await stagePreviewTracker(identity.pmRoot,stagedRoot,registrations);let validated=!1;return await runWithActiveExtensions({path:stagedRoot,noExtensions:!0},async()=>{setActiveExtensionRegistrations(registrations);const config={...identity,pmRoot:stagedRoot,createCompensation:"close",uniqueIndex:createUniqueKeyIndex(stagedRoot)},steps=mutations.map((mutation,index)=>{const step=buildStepForMutation(config,mutation,index);return{...step,inspect:()=>validateMutationOperation(mutation,index,()=>step.inspect()),prepareCompensation:()=>validateMutationOperation(mutation,index,async()=>step.prepareCompensation?.()),apply:()=>validateMutationOperation(mutation,index,()=>step.apply())}});await commitWorkspaceTransaction({...identity,pmRoot:stagedRoot,steps,onTransition:({transition})=>{transition==="committed"&&(validated=!0)}})}),{validated,state:validated?"staged_snapshot":"replayed_committed_plan",unresolved_commit_constraints:["concurrent_tracker_changes","extension_mutation_guards_and_hooks"]}}finally{await rm(root,{recursive:!0,force:!0})}}async function commitItemMutations(options){const mutations=[...options.mutations];assertValidBulkMutations(mutations);const createCompensation=options.createCompensation??"close";if(!["close","delete"].includes(createCompensation))throw new TypeError("Bulk item transaction createCompensation must be close or delete");const stepConfig={pmRoot:options.pmRoot,author:options.author,transactionId:options.transactionId,createCompensation,uniqueIndex:createUniqueKeyIndex(options.pmRoot)},committed=await commitWorkspaceTransaction({pmRoot:options.pmRoot,transactionId:options.transactionId,author:options.author,steps:mutations.map((mutation,index)=>buildStepForMutation(stepConfig,mutation,index)),...options.lockTtlSeconds===void 0?{}:{lockTtlSeconds:options.lockTtlSeconds},...options.lockWaitMs===void 0?{}:{lockWaitMs:options.lockWaitMs},...options.onTransition===void 0?{}:{onTransition:options.onTransition}}),results={};for(const[index,mutation]of mutations.entries()){const stepId=deriveStepId(mutation,index),value=committed.results[stepId];results[deriveOutcomeKey(mutation,index)]=value}return{transactionId:committed.transactionId,status:"committed",recovered:committed.recovered,results}}function buildItemCompletionMutations(options){const mutations=[];return options.evidence!==void 0&&Object.keys(options.evidence).length>0&&mutations.push({op:"update",id:options.id,options:options.evidence}),mutations.push({op:"close",id:options.id,reason:options.reason,...options.closeOptions===void 0?{}:{options:options.closeOptions}},{op:"release",id:options.id,...options.releaseOptions===void 0?{}:{options:options.releaseOptions}}),mutations}function commitItemCompletion(options){return commitItemMutations({pmRoot:options.pmRoot,transactionId:options.transactionId,author:options.author,mutations:buildItemCompletionMutations(options),...options.lockTtlSeconds===void 0?{}:{lockTtlSeconds:options.lockTtlSeconds},...options.lockWaitMs===void 0?{}:{lockWaitMs:options.lockWaitMs},...options.onTransition===void 0?{}:{onTransition:options.onTransition}})}const _testOnlyItemTransaction={buildCreateStep,bulkHistoryMarker,compensateByRestore,deriveStepId,isUpdateMarkerApplied,readItemSnapshot};export{_testOnlyItemTransaction,buildItemCompletionMutations,commitItemCompletion,commitItemMutations,listUpsertKeyCandidates,loadGuardedRuntimeSchema,previewItemMutations,resolveTransactionSchema};
 //# sourceMappingURL=item-transaction.js.map

package/dist/sdk/learnings.d.ts

@@ -5,54 +5,54 @@
  */
 import { type GlobalOptions } from "./runtime-primitives.js";
 import type { LogNote } from "../types/index.js";
-import { type AnnotationMutationReceipt, type AnnotationOmissionReceipt } from "./annotations.js";
+import { type AnnotationMutationReceipt,type AnnotationOmissionReceipt } from "./annotations.js";
 /** Documents the learnings command options payload exchanged by command, SDK, and package integrations. */
 export interface LearningsCommandOptions {
 /** Value that configures or reports add for this contract. */
-add?: string;
+add?:string;
 /** Read learning text from stdin. */
-stdin?: boolean;
+stdin?:boolean;
 /** Read learning text from a UTF-8 file. */
-file?: string;
+file?:string;
 /** Replace the learning at this one-based index. */
-edit?: number;
+edit?:number;
 /** Delete the learning at this one-based index. */
-delete?: number;
+delete?:number;
 /** Value that configures or reports limit for this contract. */
-limit?: string;
+limit?:string;
 /** Return complete learning history after a mutation instead of a bounded receipt. */
-fullHistory?: boolean;
+fullHistory?:boolean;
 /** Append only when no learning has the same resolved author and text. */
-ifAbsent?: boolean;
+ifAbsent?:boolean;
 /** Value that configures or reports author for this contract. */
-author?: string;
+author?:string;
 /** Human-readable explanation suitable for logs and agent-facing output. */
-message?: string;
+message?:string;
 /** Value that configures or reports force for this contract. */
-force?: boolean;
+force?:boolean;
 }
 /** Documents the learnings result payload exchanged by command, SDK, and package integrations. */
 export interface LearningsResult {
 /** Stable identifier used to reference this record across commands and storage. */
-id: string;
+id:string;
 /** Value that configures or reports learnings for this contract. */
-learnings: LogNote[];
+learnings:LogNote[];
 /** Value that configures or reports count for this contract. */
-count: number;
+count:number;
 /** Total learning count after the mutation. */
-total_count?: number;
+total_count?:number;
 /** Number of learning entries returned in this projection. */
-returned_count?: number;
+returned_count?:number;
 /** Whether additional stored learning entries were withheld. */
-has_more?: boolean;
+has_more?:boolean;
 /** Applied read limit when one was requested. */
-limit?: number;
+limit?:number;
 /** Mutation identity when this result changed the collection. */
-mutation_receipt?: AnnotationMutationReceipt;
+mutation_receipt?:AnnotationMutationReceipt;
 /** Declares whether older learnings were withheld from a mutation response. */
-omission_receipt?: AnnotationOmissionReceipt;
+omission_receipt?:AnnotationOmissionReceipt;
 /** Whether a requested mutation changed persisted state. */
-changed?: boolean;
+changed?:boolean;
 }
 /** Implements run learnings for the public runtime surface of this module. */
-export declare function runLearnings(id: string, options: LearningsCommandOptions, global: GlobalOptions): Promise<LearningsResult>;
+export declare function runLearnings(id:string,options:LearningsCommandOptions,global:GlobalOptions):Promise<LearningsResult>;

package/dist/sdk/lifecycle/append.d.ts

@@ -2,24 +2,24 @@ import { type GlobalOptions } from "../runtime-primitives.js";
 /** Documents the append command options payload exchanged by command, SDK, and package integrations. */
 export interface AppendCommandOptions {
 /** Value that configures or reports body for this contract. */
-body: string;
+body:string;
 /** Value that configures or reports author for this contract. */
-author?: string;
+author?:string;
 /** Human-readable explanation suitable for logs and agent-facing output. */
-message?: string;
+message?:string;
 /** Value that configures or reports force for this contract. */
-force?: boolean;
+force?:boolean;
 }
 /** Presentation-neutral input accepted by the SDK-owned body append operation. */
 export type AppendOperationOptions = AppendCommandOptions;
 /** Documents the append result payload exchanged by command, SDK, and package integrations. */
 export interface AppendResult {
 /** Value that configures or reports item for this contract. */
-item: Record<string, unknown>;
+item:Record<string,unknown>;
 /** Value that configures or reports appended for this contract. */
-appended: string;
+appended:string;
 /** Value that configures or reports changed fields for this contract. */
-changed_fields: string[];
+changed_fields:string[];
 }
 /** Implements run append for the public runtime surface of this module. */
-export declare function runAppend(id: string, options: AppendCommandOptions, global: GlobalOptions): Promise<AppendResult>;
+export declare function runAppend(id:string,options:AppendCommandOptions,global:GlobalOptions):Promise<AppendResult>;