@unbrained/pm-cli 2026.10.14 → 2026.10.17

package/dist/sdk/workspace-snapshot.d.ts

@@ -1,13 +1,13 @@
 /** Current content-addressed workspace snapshot manifest schema identifier. */
 export declare const SNAPSHOT_SCHEMA = "https://schema.unbrained.dev/pm/workspace-snapshot/v1";
 /** Workspace snapshot action tokens accepted by the SDK and CLI dispatcher. */
-export declare const WORKSPACE_SNAPSHOT_ACTIONS: readonly ["create", "list", "inspect", "restore", "delete"];
+export declare const WORKSPACE_SNAPSHOT_ACTIONS:readonly ["create","list","inspect","restore","delete"];
 /** Filesystem operations required by atomic snapshot publish and restore swaps. */
 export interface WorkspaceSnapshotAtomicOperations {
 /** Rename one filesystem entry atomically. */
-renameEntry: (source: string, target: string) => Promise<void>;
+renameEntry:(source:string,target:string) => Promise<void>;
 /** Remove one filesystem entry recursively. */
-removeEntry: (target: string) => Promise<void>;
+removeEntry:(target:string) => Promise<void>;
 }
 /** Keeps one workspace writer lease current while a long restore is active. */
 declare class WorkspaceLockHeartbeat {
@@ -18,111 +18,111 @@ private timer;
 private refresh;
 private failure;
 /** Capture the exact lock identity and derive a sub-TTL renewal interval. */
-constructor(lockPath: string, owner: string, ttlSeconds: number);
+constructor(lockPath:string,owner:string,ttlSeconds:number);
 /** Begin renewing the lock without keeping the process alive on its own. */
-start(): void;
+start():void;
 /** Force and await one owned renewal so callers can establish a fresh lease boundary. */
-refreshNow(): Promise<void>;
+refreshNow():Promise<void>;
 /** Fail the restore before activation when lease ownership was lost. */
-assertHealthy(): void;
+assertHealthy():void;
 /** Stop future renewals and await the last in-flight atomic write. */
-stop(): Promise<void>;
+stop():Promise<void>;
 /** Serialize renewal attempts and retain the first ownership failure. */
 private scheduleRenewal;
 /** Atomically refresh only the lock still owned by this process and actor. */
 private renew;
 }
 /** Internal heartbeat constructor exposed only for deterministic lock tests. */
-export declare const _testOnlyWorkspaceSnapshot: {
-WorkspaceLockHeartbeat: typeof WorkspaceLockHeartbeat;
-withSnapshotFilesystemGuard: typeof withSnapshotFilesystemGuard;
+export declare const _testOnlyWorkspaceSnapshot:{
+WorkspaceLockHeartbeat:typeof WorkspaceLockHeartbeat;
+withSnapshotFilesystemGuard:typeof withSnapshotFilesystemGuard;
 };
 /** Immutable manifest stored with every content-addressed snapshot object. */
 export interface WorkspaceSnapshotManifest {
 /** Versioned snapshot schema identifier. */
-schema: typeof SNAPSHOT_SCHEMA;
+schema:typeof SNAPSHOT_SCHEMA;
 /** SHA-256 identity derived from sorted paths and file bytes. */
-fingerprint: string;
+fingerprint:string;
 /** Sorted authoritative tracker-relative file paths. */
-files: readonly string[];
+files:readonly string[];
 /** Total authoritative payload size in bytes. */
-bytes: number;
+bytes:number;
 }
 /** Named reference returned by snapshot list operations. */
 export interface WorkspaceSnapshotReference {
 /** Human-authored stable reference name. */
-name: string;
+name:string;
 /** Referenced content fingerprint. */
-fingerprint: string;
+fingerprint:string;
 }
 /** Snapshot create outcome, including whether the object was deduplicated. */
 export interface CreateWorkspaceSnapshotResult {
 /** Immutable manifest for the captured state. */
-manifest: WorkspaceSnapshotManifest;
+manifest:WorkspaceSnapshotManifest;
 /** Optional named reference updated by the operation. */
-name?: string;
+name?:string;
 /** True when an identical content object already existed. */
-deduplicated: boolean;
+deduplicated:boolean;
 }
 /** Exact destructive impact computed before a workspace snapshot restore. */
 export interface WorkspaceSnapshotRestorePlan {
 /** Target snapshot fingerprint. */
-target_fingerprint: string;
+target_fingerprint:string;
 /** Fingerprint of the authoritative state that would be replaced. */
-current_fingerprint: string;
+current_fingerprint:string;
 /** Authoritative files whose bytes differ between current and target state. */
-changed_file_count: number;
+changed_file_count:number;
 /** Current authoritative files absent from the target snapshot. */
-removed_file_count: number;
+removed_file_count:number;
 /** Target authoritative files absent from current state. */
-added_file_count: number;
+added_file_count:number;
 /** Current item documents absent from the target snapshot. */
-removed_item_count: number;
+removed_item_count:number;
 /** History streams absent from, or shorter in, the target snapshot. */
-affected_history_stream_count: number;
+affected_history_stream_count:number;
 /** History entries that the target snapshot does not retain. */
-removed_history_entry_count: number;
+removed_history_entry_count:number;
 /** Per-stream evidence for history reductions. */
-affected_history_streams: readonly WorkspaceSnapshotHistoryImpact[];
+affected_history_streams:readonly WorkspaceSnapshotHistoryImpact[];
 /** True when applying the plan changes authoritative state. */
-changes_authoritative_state: boolean;
+changes_authoritative_state:boolean;
 }
 /** One history stream whose retained entry count would decrease on restore. */
 export interface WorkspaceSnapshotHistoryImpact {
 /** Tracker-relative history stream path. */
-path: string;
+path:string;
 /** Entry count in current authoritative state. */
-current_entries: number;
+current_entries:number;
 /** Entry count in the target snapshot, or zero when the stream is absent. */
-target_entries: number;
+target_entries:number;
 /** Entries no longer present after applying the target snapshot. */
-removed_entries: number;
+removed_entries:number;
 }
 /** Options for a guarded, audited workspace snapshot restore. */
 export interface RestoreWorkspaceSnapshotOptions {
 /** Explicit destructive-operation confirmation. */
-force?: boolean;
+force?:boolean;
 /** Actor recorded on the durable workspace audit event. */
-author?: string;
+author?:string;
 /** Optional human-readable restore rationale. */
-message?: string;
+message?:string;
 /** Workspace-writer and audit lock time-to-live in seconds. */
-lockTtlSeconds?: number;
+lockTtlSeconds?:number;
 /** Maximum workspace-writer and audit lock wait in milliseconds. */
-lockWaitMs?: number;
+lockWaitMs?:number;
 }
 /** Result of an audited and reversible workspace snapshot restore. */
 export interface RestoreWorkspaceSnapshotResult {
 /** Immutable target manifest that supplied the restored payload. */
-manifest: WorkspaceSnapshotManifest;
+manifest:WorkspaceSnapshotManifest;
 /** Exact impact accepted by the caller. */
-plan: WorkspaceSnapshotRestorePlan;
+plan:WorkspaceSnapshotRestorePlan;
 /** Recovery object containing the complete pre-restore authoritative state. */
-recovery_fingerprint: string;
+recovery_fingerprint:string;
 /** Workspace audit stream receiving the restore event. */
-audit_history_path: string;
+audit_history_path:string;
 /** Stable audit operation appended after staging and before activation. */
-audit_operation: "workspace_snapshot_restore";
+audit_operation:"workspace_snapshot_restore";
 }
 /**
  * Runs a bounded snapshot filesystem stage, converting host environment faults
@@ -131,27 +131,27 @@ audit_operation: "workspace_snapshot_restore";
  * The operation label is a fixed identifier, never a path: snapshot failures
  * are reported without disclosing workspace topology.
  */
-declare function withSnapshotFilesystemGuard<T>(operation: string, run: () => Promise<T>): Promise<T>;
+declare function withSnapshotFilesystemGuard<T>(operation:string,run:() => Promise<T>):Promise<T>;
 /**
  * Publish a prepared immutable object, treating a concurrent winning publish
  * as successful deduplication.
  */
-export declare function publishWorkspaceSnapshotObject(temporaryRoot: string, objectRoot: string, operations?: WorkspaceSnapshotAtomicOperations): Promise<boolean>;
+export declare function publishWorkspaceSnapshotObject(temporaryRoot:string,objectRoot:string,operations?:WorkspaceSnapshotAtomicOperations):Promise<boolean>;
 /** Activate a staged tracker root and restore the backup if activation fails. */
-export declare function swapWorkspaceSnapshotRoot(staging: string, pmRoot: string, backup: string, operations?: WorkspaceSnapshotAtomicOperations): Promise<void>;
+export declare function swapWorkspaceSnapshotRoot(staging:string,pmRoot:string,backup:string,operations?:WorkspaceSnapshotAtomicOperations):Promise<void>;
 /** Capture authoritative tracker state as a deduplicated immutable object. */
-export declare function createWorkspaceSnapshot(pmRoot: string, options?: {
-name?: string;
-}): Promise<CreateWorkspaceSnapshotResult>;
+export declare function createWorkspaceSnapshot(pmRoot:string,options?:{
+name?:string;
+}):Promise<CreateWorkspaceSnapshotResult>;
 /** Read and verify a snapshot manifest by named reference or fingerprint. */
-export declare function inspectWorkspaceSnapshot(pmRoot: string, target: string): Promise<WorkspaceSnapshotManifest>;
+export declare function inspectWorkspaceSnapshot(pmRoot:string,target:string):Promise<WorkspaceSnapshotManifest>;
 /** List immutable objects and human-readable named references. */
-export declare function listWorkspaceSnapshots(pmRoot: string): Promise<{
-objects: WorkspaceSnapshotManifest[];
-references: WorkspaceSnapshotReference[];
+export declare function listWorkspaceSnapshots(pmRoot:string):Promise<{
+objects:WorkspaceSnapshotManifest[];
+references:WorkspaceSnapshotReference[];
 }>;
 /** Compute the exact authoritative and history impact of restoring a snapshot. */
-export declare function planWorkspaceSnapshotRestore(pmRoot: string, target: string): Promise<WorkspaceSnapshotRestorePlan>;
+export declare function planWorkspaceSnapshotRestore(pmRoot:string,target:string):Promise<WorkspaceSnapshotRestorePlan>;
 /**
  * Atomically replace tracker state with an audited, reversible snapshot.
  *
@@ -159,7 +159,7 @@ export declare function planWorkspaceSnapshotRestore(pmRoot: string, target: str
  * state is captured as an immutable recovery object before staging begins, and
  * the staged `_workspace` stream receives the restore event before activation.
  */
-export declare function restoreWorkspaceSnapshotWithRecovery(pmRoot: string, target: string, options?: RestoreWorkspaceSnapshotOptions): Promise<RestoreWorkspaceSnapshotResult>;
+export declare function restoreWorkspaceSnapshotWithRecovery(pmRoot:string,target:string,options?:RestoreWorkspaceSnapshotOptions):Promise<RestoreWorkspaceSnapshotResult>;
 /**
  * Restore a snapshot through the backward-compatible SDK signature.
  *
@@ -168,10 +168,10 @@ export declare function restoreWorkspaceSnapshotWithRecovery(pmRoot: string, tar
  * that need impact, recovery, and audit coordinates should use
  * `restoreWorkspaceSnapshotWithRecovery`.
  */
-export declare function restoreWorkspaceSnapshot(pmRoot: string, target: string): Promise<WorkspaceSnapshotManifest>;
+export declare function restoreWorkspaceSnapshot(pmRoot:string,target:string):Promise<WorkspaceSnapshotManifest>;
 /** Delete a named reference, or an unreferenced immutable object fingerprint. */
-export declare function deleteWorkspaceSnapshot(pmRoot: string, target: string): Promise<{
-deleted: "reference" | "object";
-target: string;
+export declare function deleteWorkspaceSnapshot(pmRoot:string,target:string):Promise<{
+deleted:"reference" | "object";
+target:string;
 }>;
 export {};

package/dist/sdk/workspace-transaction-gc.d.ts

@@ -1,46 +1,46 @@
 /** Documents one journal-sweep decision row surfaced by the transaction GC. */
 export interface WorkspaceTransactionGcEntry {
 /** Relative path like "transactions/sdk/<transactionId>.json". */
-file: string;
+file:string;
 /** Journal status read from the receipt, or null when unreadable. */
-status: string | null;
+status:string | null;
 /** Age in seconds derived from the journal's updatedAt, or null when unparseable. */
-age_seconds: number | null;
+age_seconds:number | null;
 /** Whether the journal was (or would be) pruned. */
-stale: boolean;
+stale:boolean;
 /** Why the journal was retained, when it was. */
-reason?: "active" | "fresh" | "unparseable";
+reason?:"active" | "fresh" | "unparseable";
 }
 /** Extension hooks mirroring the checkpoint GC so reads/writes stay observable. */
 export interface WorkspaceTransactionGcHooks {
 /** Invoked before reading each journal file. */
-onRead?: (absolutePath: string) => Promise<string[]>;
+onRead?:(absolutePath:string) => Promise<string[]>;
 /** Invoked after removing each journal file. */
-onWrite?: (absolutePath: string) => Promise<string[]>;
+onWrite?:(absolutePath:string) => Promise<string[]>;
 }
 /** Documents the transaction GC options payload exchanged by command, SDK, and package integrations. */
 export interface WorkspaceTransactionGcOptions {
 /** Preview prune decisions without deleting any journal. */
-dryRun: boolean;
+dryRun:boolean;
 /** Prune terminal journals older than this many days. Negative values are clamped to zero; a non-finite value disables pruning entirely so bad input never deletes recovery receipts. */
-retentionDays: number;
+retentionDays:number;
 /** Clock override for deterministic tests (milliseconds since epoch). */
-now?: number;
+now?:number;
 /** Extension observability hooks. */
-hooks?: WorkspaceTransactionGcHooks;
+hooks?:WorkspaceTransactionGcHooks;
 }
 /** Documents the transaction GC result payload exchanged by command, SDK, and package integrations. */
 export interface WorkspaceTransactionGcResult {
 /** Number of journal files scanned. */
-scanned: number;
+scanned:number;
 /** Relative paths of pruned journals. */
-removed: string[];
+removed:string[];
 /** Relative paths of retained journals. */
-retained: string[];
+retained:string[];
 /** Non-fatal sweep warnings. */
-warnings: string[];
+warnings:string[];
 /** One decision row per scanned journal. */
-entries: WorkspaceTransactionGcEntry[];
+entries:WorkspaceTransactionGcEntry[];
 }
 /** Sweep `transactions/sdk/` and prune terminal workspace-transaction journals older than the retention window. One decision row is reported per journal so `pm gc` output stays auditable. */
-export declare function runWorkspaceTransactionGc(pmRoot: string, options: WorkspaceTransactionGcOptions): Promise<WorkspaceTransactionGcResult>;
+export declare function runWorkspaceTransactionGc(pmRoot:string,options:WorkspaceTransactionGcOptions):Promise<WorkspaceTransactionGcResult>;

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

@@ -2,68 +2,68 @@
 export type WorkspaceTransactionStepState = "pending" | "applied" | "compensated";
 /** JSON-compatible values retained in the durable transaction journal. */
 export type WorkspaceTransactionJsonValue = null | boolean | number | string | WorkspaceTransactionJsonValue[] | {
-[key: string]: WorkspaceTransactionJsonValue;
+[key:string]:WorkspaceTransactionJsonValue;
 };
 /** Result returned by a step inspection during replay or recovery. */
 export interface WorkspaceTransactionStepInspection {
 /** Current durable state of the step's domain mutation. */
-state: WorkspaceTransactionStepState;
+state:WorkspaceTransactionStepState;
 /** Reconstructed result when the mutation is already applied. */
-result?: WorkspaceTransactionJsonValue;
+result?:WorkspaceTransactionJsonValue;
 }
 /** One idempotent forward mutation with an append-only compensation. */
 export interface WorkspaceTransactionStep {
 /** Stable identifier unique within the transaction plan. */
-id: string;
+id:string;
 /** Inspect durable domain state without mutating it. */
-inspect(): Promise<WorkspaceTransactionStepInspection>;
+inspect():Promise<WorkspaceTransactionStepInspection>;
 /** Capture journal-safe pre-mutation data required by compensation. */
-prepareCompensation?(): Promise<WorkspaceTransactionJsonValue | undefined>;
+prepareCompensation?():Promise<WorkspaceTransactionJsonValue | undefined>;
 /** Apply the forward mutation and return a journal-safe result, or store nothing. */
-apply(): Promise<WorkspaceTransactionJsonValue | undefined>;
+apply():Promise<WorkspaceTransactionJsonValue | undefined>;
 /** Idempotently reconcile only this step's exact forward mutation when present. */
-compensate(data?: WorkspaceTransactionJsonValue): Promise<void>;
+compensate(data?:WorkspaceTransactionJsonValue):Promise<void>;
 }
 /** Observable transition points available to diagnostics and failure injection. */
 export type WorkspaceTransactionTransition = "prepared" | "step_applied" | "step_recorded" | "committing" | "committed" | "compensating" | "step_compensating" | "step_compensated" | "compensated";
 /** Context emitted at each transaction transition. */
 export interface WorkspaceTransactionTransitionContext {
 /** Stable transaction identifier. */
-transactionId: string;
+transactionId:string;
 /** Current durable transaction attempt. */
-attempt: number;
+attempt:number;
 /** Transition reached; `step_applied` follows mutation and precedes journal recording. */
-transition: WorkspaceTransactionTransition;
+transition:WorkspaceTransactionTransition;
 /** Step associated with a step-level transition. */
-stepId?: string;
+stepId?:string;
 }
 /** Options accepted by the public workspace transaction coordinator. */
 export interface CommitWorkspaceTransactionOptions {
 /** Tracker root that owns the journal and workspace-wide writer lock. */
-pmRoot: string;
+pmRoot:string;
 /** Stable idempotency key reused to recover an interrupted transaction. */
-transactionId: string;
+transactionId:string;
 /** Attributable actor recorded in the durable journal. */
-author: string;
+author:string;
 /** Ordered idempotent mutations; compensations run in reverse order. */
-steps: readonly WorkspaceTransactionStep[];
+steps:readonly WorkspaceTransactionStep[];
 /** 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?(context: WorkspaceTransactionTransitionContext): void | Promise<void>;
+onTransition?(context:WorkspaceTransactionTransitionContext):void | Promise<void>;
 }
 /** Successful durable transaction result. */
 export interface WorkspaceTransactionCommitResult {
 /** 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 result per ordered transaction step. */
-results: Record<string, WorkspaceTransactionJsonValue>;
+results:Record<string,WorkspaceTransactionJsonValue>;
 }
 /**
  * Deliberate process-boundary interruption used by deterministic crash tests.
@@ -72,14 +72,14 @@ results: Record<string, WorkspaceTransactionJsonValue>;
  */
 export declare class WorkspaceTransactionInterruptedError extends Error {
 /** Create one explicit crash-boundary interruption. */
-constructor(message?: string);
+constructor(message?:string);
 }
 /** Validate transaction identity before preview staging or acquiring any writer lock. */
-export declare function validateWorkspaceTransactionIdentity(options: Pick<CommitWorkspaceTransactionOptions, "pmRoot" | "transactionId" | "author">): Pick<CommitWorkspaceTransactionOptions, "pmRoot" | "transactionId" | "author">;
+export declare function validateWorkspaceTransactionIdentity(options:Pick<CommitWorkspaceTransactionOptions,"pmRoot" | "transactionId" | "author">):Pick<CommitWorkspaceTransactionOptions,"pmRoot" | "transactionId" | "author">;
 /**
  * Commit an ordered set of idempotent SDK mutations under one workspace writer
  * lock. The durable journal resumes interrupted forward work, while ordinary
  * failures append reverse-order compensations. This provides atomic logical
  * replay without deleting or rewriting immutable domain histories.
  */
-export declare function commitWorkspaceTransaction(options: CommitWorkspaceTransactionOptions): Promise<WorkspaceTransactionCommitResult>;
+export declare function commitWorkspaceTransaction(options:CommitWorkspaceTransactionOptions):Promise<WorkspaceTransactionCommitResult>;

package/dist/sdk/workspace-transaction.js

@@ -1,3 +1,3 @@
-(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]="0bd9a904-c076-5c2a-a9d8-42a543625e33")}catch{}})();import{mkdir,readFile}from"node:fs/promises";import path from"node:path";import{acquireLock}from"../core/lock/lock.js";import{isFileMissingError,writeFileAtomic}from"../core/fs/fs-utils.js";import{nowIso}from"../core/shared/time.js";class WorkspaceTransactionInterruptedError extends Error{constructor(message="Workspace transaction interrupted"){super(message),this.name="WorkspaceTransactionInterruptedError"}}const WORKSPACE_TRANSACTION_LOCK_ID="sdk-workspace-transaction",TRANSACTION_ID_PATTERN=/^[a-zA-Z0-9._-]+$/,DEFAULT_LOCK_TTL_SECONDS=30,DEFAULT_LOCK_WAIT_MS=3e3;function requiredIdentifier(value,label){if(typeof value!="string")throw new TypeError(`${label} must be a string`);const normalized=value.trim();if(!normalized||!TRANSACTION_ID_PATTERN.test(normalized))throw new TypeError(`${label} must match [a-zA-Z0-9._-]+`);return normalized}function requiredText(value,label){if(typeof value!="string")throw new TypeError(`${label} must be a string`);const normalized=value.trim();if(!normalized)throw new TypeError(`${label} must be non-empty`);return normalized}function validateWorkspaceTransactionIdentity(options){return{pmRoot:requiredText(options.pmRoot,"Transaction pmRoot"),transactionId:requiredIdentifier(options.transactionId,"Transaction id"),author:requiredText(options.author,"Transaction author")}}function positiveInteger(value,fallback,label){const resolved=value??fallback;if(!Number.isInteger(resolved)||resolved<=0)throw new TypeError(`${label} must be a positive integer`);return resolved}function journalPath(pmRoot,transactionId){return path.join(pmRoot,"transactions","sdk",`${transactionId}.json`)}async function writeJournal(pmRoot,journal){journal.updatedAt=nowIso();const target=journalPath(pmRoot,journal.transactionId);await mkdir(path.dirname(target),{recursive:!0}),await writeFileAtomic(target,`${JSON.stringify(journal,null,2)}
-`)}function hasValidJournalMetadata(journal){return Number.isInteger(journal.attempt)&&typeof journal.author=="string"&&typeof journal.createdAt=="string"&&typeof journal.updatedAt=="string"}function createResultMap(source){return Object.assign(Object.create(null),source)}function cloneJournalValue(value,label){try{const serialized=JSON.stringify(value,(_key,nestedValue)=>{if(typeof nestedValue=="number"&&!Number.isFinite(nestedValue))throw new TypeError(`${label} contains a non-finite number`);if(nestedValue===void 0||typeof nestedValue=="function"||typeof nestedValue=="symbol")throw new TypeError(`${label} contains a non-JSON value`);return nestedValue});return JSON.parse(serialized)}catch(error){throw new TypeError(`${label} must be JSON serializable`,{cause:error})}}function cloneOptionalJournalValue(value,label){return value===void 0?void 0:cloneJournalValue(value,label)}function setJournalEntry(target,stepId,value,label){const cloned=cloneOptionalJournalValue(value,label);cloned===void 0?delete target[stepId]:target[stepId]=cloned}function isJournalMap(value){return value!==null&&typeof value=="object"&&!Array.isArray(value)}function hasUniqueKnownStepIds(value,stepIds){return Array.isArray(value)&&new Set(value).size===value.length&&value.every(stepId=>typeof stepId=="string"&&stepIds.includes(stepId))}function hasValidJournalLifecycle(journal,stepIds){if(!hasUniqueKnownStepIds(journal.startedStepIds,stepIds)||!hasUniqueKnownStepIds(journal.completedStepIds,stepIds)||!isJournalMap(journal.results)||!isJournalMap(journal.compensationData))return!1;const startedStepIds=journal.startedStepIds,started=new Set(startedStepIds),completedStepIds=journal.completedStepIds,completed=new Set(completedStepIds);return Object.keys(journal.compensationData).some(stepId=>!started.has(stepId))||Object.keys(journal.results).some(stepId=>!completed.has(stepId))?!1:journal.status==="committed"?stepIds.every(stepId=>completed.has(stepId)):journal.status!=="compensated"||completed.size===0&&started.size===0}function parseJournal(raw,transactionId,stepIds){let parsed;try{parsed=JSON.parse(raw)}catch{throw new TypeError(`Workspace transaction ${transactionId} journal is invalid JSON`)}if(!parsed||typeof parsed!="object"||Array.isArray(parsed))throw new TypeError(`Workspace transaction ${transactionId} journal is invalid`);const journal=parsed,identityMatches=journal.schemaVersion===1&&journal.transactionId===transactionId,stepsMatch=Array.isArray(journal.stepIds)&&journal.stepIds.length===stepIds.length&&journal.stepIds.every((stepId,index)=>stepId===stepIds[index]),lifecycleMatches=hasValidJournalLifecycle(journal,stepIds),metadataMatches=hasValidJournalMetadata(journal),statusMatches=["applying","compensating","compensated","committed"].includes(String(journal.status));if(!identityMatches||!stepsMatch||!lifecycleMatches||!metadataMatches||!statusMatches)throw new TypeError(`Workspace transaction ${transactionId} journal does not match the supplied plan`);return{...journal,results:createResultMap(journal.results),compensationData:createResultMap(journal.compensationData)}}async function prepareJournalForApply(options,transactionId,author,stepIds,existing){let journal=existing;const recovered=journal!==void 0;if(journal?.status==="compensating"&&await compensateAppliedSteps(options,journal),journal===void 0||journal.status==="compensated"){const timestamp=nowIso();journal={schemaVersion:1,transactionId,author,status:"applying",attempt:(journal?.attempt??0)+1,createdAt:journal?.createdAt??timestamp,updatedAt:timestamp,stepIds,startedStepIds:[],completedStepIds:[],results:createResultMap(),compensationData:createResultMap()},await writeJournal(options.pmRoot,journal),await emitTransition(options,journal,"prepared")}return{journal,recovered}}async function applyPreparedTransaction(options,journal,recovered){try{await discoverAppliedSteps(journal,options.steps),await writeJournal(options.pmRoot,journal);const completed=new Set(journal.completedStepIds),started=new Set(journal.startedStepIds);for(const step of options.steps){if(completed.has(step.id))continue;const inspection=await step.inspect();let result=cloneOptionalJournalValue(inspection.result,`Step ${step.id} result`);if(inspection.state!=="applied"){const compensationData=await step.prepareCompensation?.();setJournalEntry(journal.compensationData,step.id,compensationData,`Step ${step.id} compensation data`),started.add(step.id),journal.startedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>started.has(stepId)),await writeJournal(options.pmRoot,journal);const appliedResult=await step.apply();result=cloneOptionalJournalValue(appliedResult,`Step ${step.id} result`)}await emitTransition(options,journal,"step_applied",step.id),completed.add(step.id),journal.completedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>completed.has(stepId)),setJournalEntry(journal.results,step.id,result,`Step ${step.id} result`),await writeJournal(options.pmRoot,journal),await emitTransition(options,journal,"step_recorded",step.id)}return await emitTransition(options,journal,"committing"),journal.status="committed",await writeJournal(options.pmRoot,journal),await emitTransition(options,journal,"committed"),{transactionId:journal.transactionId,status:"committed",recovered,results:createResultMap(journal.results)}}catch(error){if(error instanceof WorkspaceTransactionInterruptedError||journal.status==="committed")throw error;try{await compensateAppliedSteps(options,journal)}catch(compensationError){throw new AggregateError([error,compensationError],`Workspace transaction failed and compensation failed: ${String(compensationError)}`,{cause:compensationError})}throw error}}async function loadJournal(pmRoot,transactionId,stepIds){try{return parseJournal(await readFile(journalPath(pmRoot,transactionId),"utf8"),transactionId,stepIds)}catch(error){if(error!==null&&typeof error=="object"&&"code"in error&&isFileMissingError(error))return;throw error}}async function emitTransition(options,journal,transition,stepId){await options.onTransition?.({transactionId:journal.transactionId,attempt:journal.attempt,transition,...stepId===void 0?{}:{stepId}})}async function discoverAppliedSteps(journal,steps){const completed=new Set,results=createResultMap();for(const step of steps){const inspection=await step.inspect();inspection.state==="applied"&&(completed.add(step.id),setJournalEntry(results,step.id,inspection.result,`Step ${step.id} result`))}journal.results=results,journal.completedStepIds=steps.map(step=>step.id).filter(stepId=>completed.has(stepId))}async function compensateAppliedSteps(options,journal){journal.status="compensating",await writeJournal(options.pmRoot,journal),await emitTransition(options,journal,"compensating");const completed=new Set(journal.completedStepIds),started=new Set(journal.startedStepIds);for(const step of[...options.steps].reverse()){if(!started.has(step.id)&&!completed.has(step.id))continue;let shouldCompensate;try{shouldCompensate=started.has(step.id)&&(await step.inspect()).state==="applied"}catch{shouldCompensate=started.has(step.id)}shouldCompensate&&(await emitTransition(options,journal,"step_compensating",step.id),await step.compensate(journal.compensationData[step.id])),completed.delete(step.id),started.delete(step.id),journal.completedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>completed.has(stepId)),journal.startedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>started.has(stepId)),delete journal.results[step.id],delete journal.compensationData[step.id],await writeJournal(options.pmRoot,journal),await emitTransition(options,journal,"step_compensated",step.id)}journal.status="compensated",await writeJournal(options.pmRoot,journal),await emitTransition(options,journal,"compensated")}async function commitWorkspaceTransaction(options){const{pmRoot,transactionId,author}=validateWorkspaceTransactionIdentity(options),lockTtlSeconds=positiveInteger(options.lockTtlSeconds,DEFAULT_LOCK_TTL_SECONDS,"Transaction lock TTL"),lockWaitMs=positiveInteger(options.lockWaitMs,DEFAULT_LOCK_WAIT_MS,"Transaction lock wait"),steps=[...options.steps];if(steps.length===0)throw new TypeError("Workspace transaction requires at least one step");const stepIds=steps.map(step=>{const stepId=requiredIdentifier(step.id,"Transaction step id");if(stepId!==step.id)throw new TypeError("Transaction step id must not contain surrounding whitespace");return stepId});if(new Set(stepIds).size!==stepIds.length)throw new TypeError("Workspace transaction step ids must be unique");const stableOptions={...options,pmRoot,transactionId,author,steps,lockTtlSeconds,lockWaitMs},release=await acquireLock(pmRoot,WORKSPACE_TRANSACTION_LOCK_ID,lockTtlSeconds,author,!1,!1,lockWaitMs);try{const existing=await loadJournal(pmRoot,transactionId,stepIds),recovered=existing!==void 0;if(existing?.status==="committed")return{transactionId,status:"committed",recovered:!0,results:createResultMap(existing.results)};const prepared=await prepareJournalForApply(stableOptions,transactionId,author,stepIds,existing);return await applyPreparedTransaction(stableOptions,prepared.journal,recovered||prepared.recovered)}finally{await release()}}export{WorkspaceTransactionInterruptedError,commitWorkspaceTransaction,validateWorkspaceTransactionIdentity};
+(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]="1fae5539-4eb8-5eba-bfd6-a191c89448ec")}catch{}})();import{mkdir,readFile}from"node:fs/promises";import path from"node:path";import{acquireLock}from"../core/lock/lock.js";import{isFileMissingError,writeFileAtomic}from"../core/fs/fs-utils.js";import{nowIso}from"../core/shared/time.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";class WorkspaceTransactionInterruptedError extends Error{constructor(message="Workspace transaction interrupted"){super(message),this.name="WorkspaceTransactionInterruptedError"}}const WORKSPACE_TRANSACTION_LOCK_ID="sdk-workspace-transaction",TRANSACTION_ID_PATTERN=/^[a-zA-Z0-9._-]+$/,DEFAULT_LOCK_TTL_SECONDS=30,DEFAULT_LOCK_WAIT_MS=3e3;function requiredIdentifier(value,label){if(typeof value!="string")throw new TypeError(`${label} must be a string`);const normalized=value.trim();if(!normalized||!TRANSACTION_ID_PATTERN.test(normalized))throw new TypeError(`${label} must match [a-zA-Z0-9._-]+`);return normalized}function requiredText(value,label){if(typeof value!="string")throw new TypeError(`${label} must be a string`);const normalized=value.trim();if(!normalized)throw new TypeError(`${label} must be non-empty`);return normalized}function validateWorkspaceTransactionIdentity(options){return{pmRoot:requiredText(options.pmRoot,"Transaction pmRoot"),transactionId:requiredIdentifier(options.transactionId,"Transaction id"),author:requiredText(options.author,"Transaction author")}}function positiveInteger(value,fallback,label){const resolved=value??fallback;if(!Number.isInteger(resolved)||resolved<=0)throw new TypeError(`${label} must be a positive integer`);return resolved}function journalPath(pmRoot,transactionId){return path.join(pmRoot,"transactions","sdk",`${transactionId}.json`)}async function writeJournal(pmRoot,journal){journal.updatedAt=nowIso();const target=journalPath(pmRoot,journal.transactionId);await mkdir(path.dirname(target),{recursive:!0}),await writeFileAtomic(target,`${JSON.stringify(journal,null,2)}
+`)}function hasValidJournalMetadata(journal){return Number.isInteger(journal.attempt)&&typeof journal.author=="string"&&typeof journal.createdAt=="string"&&typeof journal.updatedAt=="string"}function createResultMap(source){return Object.assign(Object.create(null),source)}function cloneJournalValue(value,label){try{const serialized=JSON.stringify(value,(_key,nestedValue)=>{if(typeof nestedValue=="number"&&!Number.isFinite(nestedValue))throw new TypeError(`${label} contains a non-finite number`);if(nestedValue===void 0||typeof nestedValue=="function"||typeof nestedValue=="symbol")throw new TypeError(`${label} contains a non-JSON value`);return nestedValue});return JSON.parse(serialized)}catch(error){throw new TypeError(`${label} must be JSON serializable`,{cause:error})}}function cloneOptionalJournalValue(value,label){return value===void 0?void 0:cloneJournalValue(value,label)}function setJournalEntry(target,stepId,value,label){const cloned=cloneOptionalJournalValue(value,label);cloned===void 0?delete target[stepId]:target[stepId]=cloned}function isJournalMap(value){return value!==null&&typeof value=="object"&&!Array.isArray(value)}function hasUniqueKnownStepIds(value,stepIds){return Array.isArray(value)&&new Set(value).size===value.length&&value.every(stepId=>typeof stepId=="string"&&stepIds.includes(stepId))}function hasValidJournalLifecycle(journal,stepIds){if(!hasUniqueKnownStepIds(journal.startedStepIds,stepIds)||!hasUniqueKnownStepIds(journal.completedStepIds,stepIds)||!isJournalMap(journal.results)||!isJournalMap(journal.compensationData))return!1;const startedStepIds=journal.startedStepIds,started=new Set(startedStepIds),completedStepIds=journal.completedStepIds,completed=new Set(completedStepIds);return Object.keys(journal.compensationData).some(stepId=>!started.has(stepId))||Object.keys(journal.results).some(stepId=>!completed.has(stepId))?!1:journal.status==="committed"?stepIds.every(stepId=>completed.has(stepId)):journal.status!=="compensated"||completed.size===0&&started.size===0}function invalidJournal(transactionId,detail){return new PmCliError(`Workspace transaction ${transactionId} journal is invalid (${detail})`,EXIT_CODE.CONFLICT,{code:"transaction_journal_invalid",required:"A valid durable journal is required before transaction recovery can continue.",why:"Corrupt journal data cannot establish which steps applied or still require compensation.",nextSteps:["Preserve the journal and inspect its integrity or restore a verified backup before retrying.","Do not switch to a new transaction id to bypass an unreadable journal; previously applied work may remain."]})}function journalPlanMismatch(transactionId){return new PmCliError(`Workspace transaction ${transactionId} journal does not match the supplied plan`,EXIT_CODE.CONFLICT,{code:"transaction_plan_mismatch",required:"Replay the exact plan that started this transaction, or start a new transaction with a different id.",why:"A journal records the plan it is resuming; applying a different plan under the same id could skip or duplicate steps.",nextSteps:["Re-run with the original document to resume or replay it.","Pass --transaction-id <new-id> (or a new transactionId over MCP) to commit the changed plan as its own transaction.","Run pm ops gc --scope transactions --dry-run to inspect abandoned journals before pruning them."]})}function parseJournal(raw,transactionId,stepIds){let parsed;try{parsed=JSON.parse(raw)}catch{throw invalidJournal(transactionId,"invalid JSON")}if(!parsed||typeof parsed!="object"||Array.isArray(parsed))throw invalidJournal(transactionId,"expected an object");const journal=parsed;if(!(journal.schemaVersion===1&&journal.transactionId===transactionId))throw invalidJournal(transactionId,"schema version or transaction id does not match the journal file");const recordedStepIds=journal.stepIds;if(!Array.isArray(recordedStepIds)||!hasUniqueKnownStepIds(recordedStepIds,recordedStepIds)||!hasValidJournalLifecycle(journal,recordedStepIds)||!hasValidJournalMetadata(journal)||typeof journal.status!="string"||!["applying","compensating","compensated","committed"].includes(journal.status))throw invalidJournal(transactionId,"invalid lifecycle, metadata, status or step ids");if(!(journal.status==="compensated"||recordedStepIds.length===stepIds.length&&recordedStepIds.every((stepId,index)=>stepId===stepIds[index])))throw journalPlanMismatch(transactionId);return{...journal,results:createResultMap(journal.results),compensationData:createResultMap(journal.compensationData)}}async function prepareJournalForApply(options,transactionId,author,stepIds,existing){let journal=existing;const recovered=journal!==void 0;if(journal?.status==="compensating"&&await compensateAppliedSteps(options,journal),journal===void 0||journal.status==="compensated"){const timestamp=nowIso();journal={schemaVersion:1,transactionId,author,status:"applying",attempt:(journal?.attempt??0)+1,createdAt:journal?.createdAt??timestamp,updatedAt:timestamp,stepIds,startedStepIds:[],completedStepIds:[],results:createResultMap(),compensationData:createResultMap()},await writeJournal(options.pmRoot,journal),await emitTransition(options,journal,"prepared")}return{journal,recovered}}async function applyPreparedTransaction(options,journal,recovered){try{await discoverAppliedSteps(journal,options.steps),await writeJournal(options.pmRoot,journal);const completed=new Set(journal.completedStepIds),started=new Set(journal.startedStepIds);for(const step of options.steps){if(completed.has(step.id))continue;const inspection=await step.inspect();let result=cloneOptionalJournalValue(inspection.result,`Step ${step.id} result`);if(inspection.state!=="applied"){const compensationData=await step.prepareCompensation?.();setJournalEntry(journal.compensationData,step.id,compensationData,`Step ${step.id} compensation data`),started.add(step.id),journal.startedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>started.has(stepId)),await writeJournal(options.pmRoot,journal);const appliedResult=await step.apply();result=cloneOptionalJournalValue(appliedResult,`Step ${step.id} result`)}await emitTransition(options,journal,"step_applied",step.id),completed.add(step.id),journal.completedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>completed.has(stepId)),setJournalEntry(journal.results,step.id,result,`Step ${step.id} result`),await writeJournal(options.pmRoot,journal),await emitTransition(options,journal,"step_recorded",step.id)}return await emitTransition(options,journal,"committing"),journal.status="committed",await writeJournal(options.pmRoot,journal),await emitTransition(options,journal,"committed"),{transactionId:journal.transactionId,status:"committed",recovered,results:createResultMap(journal.results)}}catch(error){if(error instanceof WorkspaceTransactionInterruptedError||journal.status==="committed")throw error;try{await compensateAppliedSteps(options,journal)}catch(compensationError){throw new AggregateError([error,compensationError],`Workspace transaction failed and compensation failed: ${String(compensationError)}`,{cause:compensationError})}throw error}}async function loadJournal(pmRoot,transactionId,stepIds){try{return parseJournal(await readFile(journalPath(pmRoot,transactionId),"utf8"),transactionId,stepIds)}catch(error){if(error!==null&&typeof error=="object"&&"code"in error&&isFileMissingError(error))return;throw error}}async function emitTransition(options,journal,transition,stepId){await options.onTransition?.({transactionId:journal.transactionId,attempt:journal.attempt,transition,...stepId===void 0?{}:{stepId}})}async function discoverAppliedSteps(journal,steps){const completed=new Set,results=createResultMap();for(const step of steps){const inspection=await step.inspect();inspection.state==="applied"&&(completed.add(step.id),setJournalEntry(results,step.id,inspection.result,`Step ${step.id} result`))}journal.results=results,journal.completedStepIds=steps.map(step=>step.id).filter(stepId=>completed.has(stepId))}async function compensateAppliedSteps(options,journal){journal.status="compensating",await writeJournal(options.pmRoot,journal),await emitTransition(options,journal,"compensating");const completed=new Set(journal.completedStepIds),started=new Set(journal.startedStepIds);for(const step of[...options.steps].reverse()){if(!started.has(step.id)&&!completed.has(step.id))continue;let shouldCompensate;try{shouldCompensate=started.has(step.id)&&(await step.inspect()).state==="applied"}catch{shouldCompensate=started.has(step.id)}shouldCompensate&&(await emitTransition(options,journal,"step_compensating",step.id),await step.compensate(journal.compensationData[step.id])),completed.delete(step.id),started.delete(step.id),journal.completedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>completed.has(stepId)),journal.startedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>started.has(stepId)),delete journal.results[step.id],delete journal.compensationData[step.id],await writeJournal(options.pmRoot,journal),await emitTransition(options,journal,"step_compensated",step.id)}journal.status="compensated",await writeJournal(options.pmRoot,journal),await emitTransition(options,journal,"compensated")}async function commitWorkspaceTransaction(options){const{pmRoot,transactionId,author}=validateWorkspaceTransactionIdentity(options),lockTtlSeconds=positiveInteger(options.lockTtlSeconds,DEFAULT_LOCK_TTL_SECONDS,"Transaction lock TTL"),lockWaitMs=positiveInteger(options.lockWaitMs,DEFAULT_LOCK_WAIT_MS,"Transaction lock wait"),steps=[...options.steps];if(steps.length===0)throw new TypeError("Workspace transaction requires at least one step");const stepIds=steps.map(step=>{const stepId=requiredIdentifier(step.id,"Transaction step id");if(stepId!==step.id)throw new TypeError("Transaction step id must not contain surrounding whitespace");return stepId});if(new Set(stepIds).size!==stepIds.length)throw new TypeError("Workspace transaction step ids must be unique");const stableOptions={...options,pmRoot,transactionId,author,steps,lockTtlSeconds,lockWaitMs},release=await acquireLock(pmRoot,WORKSPACE_TRANSACTION_LOCK_ID,lockTtlSeconds,author,!1,!1,lockWaitMs);try{const existing=await loadJournal(pmRoot,transactionId,stepIds),recovered=existing!==void 0;if(existing?.status==="committed")return{transactionId,status:"committed",recovered:!0,results:createResultMap(existing.results)};const prepared=await prepareJournalForApply(stableOptions,transactionId,author,stepIds,existing);return await applyPreparedTransaction(stableOptions,prepared.journal,recovered||prepared.recovered)}finally{await release()}}export{WorkspaceTransactionInterruptedError,commitWorkspaceTransaction,validateWorkspaceTransactionIdentity};
 //# sourceMappingURL=workspace-transaction.js.map

package/dist/sdk/workspace.d.ts

@@ -13,20 +13,20 @@ export declare const PM_GITIGNORE_DEFAULT_TRACKER_ROOT = ".agents/pm";
  * state with their own GC (`pm gc --scope transactions|checkpoints`), so
  * keeping them untracked is the recorded merge-safety disposition.
  */
-export declare const PM_GITIGNORE_RUNTIME_DIRECTORIES: readonly ["runtime/", "search/", "locks/", "transactions/", "checkpoints/"];
+export declare const PM_GITIGNORE_RUNTIME_DIRECTORIES:readonly ["runtime/","search/","locks/","transactions/","checkpoints/"];
 /** Tracker-relative curated search evidence that remains version controlled. */
-export declare const PM_GITIGNORE_TRACKED_FILES: readonly ["search/eval-queries.json"];
+export declare const PM_GITIGNORE_TRACKED_FILES:readonly ["search/eval-queries.json"];
 /** Result of reconciling the init-owned repository ignore block. */
 export interface EnsurePmGitignoreResult {
 /** Absolute path to the reconciled file. */
-path: string;
+path:string;
 /** Whether the file content changed. */
-changed: boolean;
+changed:boolean;
 }
 /** Return whether a relative path escapes its owning root, without rejecting valid names such as `..pm`. */
-export declare function isPathOutsideRoot(relativePath: string): boolean;
+export declare function isPathOutsideRoot(relativePath:string):boolean;
 /** Return the canonical pm ignore block rendered for the given workspace-relative tracker root (defaults to `.agents/pm`), primarily for documentation and tests. */
-export declare function getPmGitignoreBlock(trackerRelativeRoot?: string): string;
+export declare function getPmGitignoreBlock(trackerRelativeRoot?:string):string;
 /**
  * Idempotently create or replace the fenced pm cache block in a workspace
  * `.gitignore`. When `pmRoot` is provided the ignored runtime directories are
@@ -35,7 +35,7 @@ export declare function getPmGitignoreBlock(trackerRelativeRoot?: string): strin
  * A tracker root outside the workspace needs no ignore rules here, so the
  * file is left untouched.
  */
-export declare function ensurePmGitignore(workspaceRoot: string, options?: {
+export declare function ensurePmGitignore(workspaceRoot:string,options?:{
 /** Absolute tracker root; rendered relative to the workspace root. */
-pmRoot?: string;
-}): Promise<EnsurePmGitignoreResult>;
+pmRoot?:string;
+}):Promise<EnsurePmGitignoreResult>;