@unbrained/pm-cli 2026.10.11 → 2026.10.13

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

@@ -4,125 +4,125 @@ export declare const SNAPSHOT_SCHEMA = "https://schema.unbrained.dev/pm/workspac
 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>;
-    /** Remove one filesystem entry recursively. */
-    removeEntry: (target: string) => Promise<void>;
+/** Rename one filesystem entry atomically. */
+renameEntry: (source: string, target: string) => Promise<void>;
+/** Remove one filesystem entry recursively. */
+removeEntry: (target: string) => Promise<void>;
 }
 /** Keeps one workspace writer lease current while a long restore is active. */
 declare class WorkspaceLockHeartbeat {
-    private readonly lockPath;
-    private readonly owner;
-    private readonly intervalMs;
-    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);
-    /** Begin renewing the lock without keeping the process alive on its own. */
-    start(): void;
-    /** Force and await one owned renewal so callers can establish a fresh lease boundary. */
-    refreshNow(): Promise<void>;
-    /** Fail the restore before activation when lease ownership was lost. */
-    assertHealthy(): void;
-    /** Stop future renewals and await the last in-flight atomic write. */
-    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;
+private readonly lockPath;
+private readonly owner;
+private readonly intervalMs;
+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);
+/** Begin renewing the lock without keeping the process alive on its own. */
+start(): void;
+/** Force and await one owned renewal so callers can establish a fresh lease boundary. */
+refreshNow(): Promise<void>;
+/** Fail the restore before activation when lease ownership was lost. */
+assertHealthy(): void;
+/** Stop future renewals and await the last in-flight atomic write. */
+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;
+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;
-    /** SHA-256 identity derived from sorted paths and file bytes. */
-    fingerprint: string;
-    /** Sorted authoritative tracker-relative file paths. */
-    files: readonly string[];
-    /** Total authoritative payload size in bytes. */
-    bytes: number;
+/** Versioned snapshot schema identifier. */
+schema: typeof SNAPSHOT_SCHEMA;
+/** SHA-256 identity derived from sorted paths and file bytes. */
+fingerprint: string;
+/** Sorted authoritative tracker-relative file paths. */
+files: readonly string[];
+/** Total authoritative payload size in bytes. */
+bytes: number;
 }
 /** Named reference returned by snapshot list operations. */
 export interface WorkspaceSnapshotReference {
-    /** Human-authored stable reference name. */
-    name: string;
-    /** Referenced content fingerprint. */
-    fingerprint: string;
+/** Human-authored stable reference name. */
+name: string;
+/** Referenced content fingerprint. */
+fingerprint: string;
 }
 /** Snapshot create outcome, including whether the object was deduplicated. */
 export interface CreateWorkspaceSnapshotResult {
-    /** Immutable manifest for the captured state. */
-    manifest: WorkspaceSnapshotManifest;
-    /** Optional named reference updated by the operation. */
-    name?: string;
-    /** True when an identical content object already existed. */
-    deduplicated: boolean;
+/** Immutable manifest for the captured state. */
+manifest: WorkspaceSnapshotManifest;
+/** Optional named reference updated by the operation. */
+name?: string;
+/** True when an identical content object already existed. */
+deduplicated: boolean;
 }
 /** Exact destructive impact computed before a workspace snapshot restore. */
 export interface WorkspaceSnapshotRestorePlan {
-    /** Target snapshot fingerprint. */
-    target_fingerprint: string;
-    /** Fingerprint of the authoritative state that would be replaced. */
-    current_fingerprint: string;
-    /** Authoritative files whose bytes differ between current and target state. */
-    changed_file_count: number;
-    /** Current authoritative files absent from the target snapshot. */
-    removed_file_count: number;
-    /** Target authoritative files absent from current state. */
-    added_file_count: number;
-    /** Current item documents absent from the target snapshot. */
-    removed_item_count: number;
-    /** History streams absent from, or shorter in, the target snapshot. */
-    affected_history_stream_count: number;
-    /** History entries that the target snapshot does not retain. */
-    removed_history_entry_count: number;
-    /** Per-stream evidence for history reductions. */
-    affected_history_streams: readonly WorkspaceSnapshotHistoryImpact[];
-    /** True when applying the plan changes authoritative state. */
-    changes_authoritative_state: boolean;
+/** Target snapshot fingerprint. */
+target_fingerprint: string;
+/** Fingerprint of the authoritative state that would be replaced. */
+current_fingerprint: string;
+/** Authoritative files whose bytes differ between current and target state. */
+changed_file_count: number;
+/** Current authoritative files absent from the target snapshot. */
+removed_file_count: number;
+/** Target authoritative files absent from current state. */
+added_file_count: number;
+/** Current item documents absent from the target snapshot. */
+removed_item_count: number;
+/** History streams absent from, or shorter in, the target snapshot. */
+affected_history_stream_count: number;
+/** History entries that the target snapshot does not retain. */
+removed_history_entry_count: number;
+/** Per-stream evidence for history reductions. */
+affected_history_streams: readonly WorkspaceSnapshotHistoryImpact[];
+/** True when applying the plan changes authoritative state. */
+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;
-    /** Entry count in current authoritative state. */
-    current_entries: number;
-    /** Entry count in the target snapshot, or zero when the stream is absent. */
-    target_entries: number;
-    /** Entries no longer present after applying the target snapshot. */
-    removed_entries: number;
+/** Tracker-relative history stream path. */
+path: string;
+/** Entry count in current authoritative state. */
+current_entries: number;
+/** Entry count in the target snapshot, or zero when the stream is absent. */
+target_entries: number;
+/** Entries no longer present after applying the target snapshot. */
+removed_entries: number;
 }
 /** Options for a guarded, audited workspace snapshot restore. */
 export interface RestoreWorkspaceSnapshotOptions {
-    /** Explicit destructive-operation confirmation. */
-    force?: boolean;
-    /** Actor recorded on the durable workspace audit event. */
-    author?: string;
-    /** Optional human-readable restore rationale. */
-    message?: string;
-    /** Workspace-writer and audit lock time-to-live in seconds. */
-    lockTtlSeconds?: number;
-    /** Maximum workspace-writer and audit lock wait in milliseconds. */
-    lockWaitMs?: number;
+/** Explicit destructive-operation confirmation. */
+force?: boolean;
+/** Actor recorded on the durable workspace audit event. */
+author?: string;
+/** Optional human-readable restore rationale. */
+message?: string;
+/** Workspace-writer and audit lock time-to-live in seconds. */
+lockTtlSeconds?: number;
+/** Maximum workspace-writer and audit lock wait in milliseconds. */
+lockWaitMs?: number;
 }
 /** Result of an audited and reversible workspace snapshot restore. */
 export interface RestoreWorkspaceSnapshotResult {
-    /** Immutable target manifest that supplied the restored payload. */
-    manifest: WorkspaceSnapshotManifest;
-    /** Exact impact accepted by the caller. */
-    plan: WorkspaceSnapshotRestorePlan;
-    /** Recovery object containing the complete pre-restore authoritative state. */
-    recovery_fingerprint: string;
-    /** Workspace audit stream receiving the restore event. */
-    audit_history_path: string;
-    /** Stable audit operation appended after staging and before activation. */
-    audit_operation: "workspace_snapshot_restore";
+/** Immutable target manifest that supplied the restored payload. */
+manifest: WorkspaceSnapshotManifest;
+/** Exact impact accepted by the caller. */
+plan: WorkspaceSnapshotRestorePlan;
+/** Recovery object containing the complete pre-restore authoritative state. */
+recovery_fingerprint: string;
+/** Workspace audit stream receiving the restore event. */
+audit_history_path: string;
+/** Stable audit operation appended after staging and before activation. */
+audit_operation: "workspace_snapshot_restore";
 }
 /**
  * Runs a bounded snapshot filesystem stage, converting host environment faults
@@ -141,14 +141,14 @@ export declare function publishWorkspaceSnapshotObject(temporaryRoot: string, ob
 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;
+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>;
 /** List immutable objects and human-readable named references. */
 export declare function listWorkspaceSnapshots(pmRoot: string): Promise<{
-    objects: WorkspaceSnapshotManifest[];
-    references: WorkspaceSnapshotReference[];
+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>;
@@ -171,7 +171,7 @@ export declare function restoreWorkspaceSnapshotWithRecovery(pmRoot: string, tar
 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;
+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;
-    /** Journal status read from the receipt, or null when unreadable. */
-    status: string | null;
-    /** Age in seconds derived from the journal's updatedAt, or null when unparseable. */
-    age_seconds: number | null;
-    /** Whether the journal was (or would be) pruned. */
-    stale: boolean;
-    /** Why the journal was retained, when it was. */
-    reason?: "active" | "fresh" | "unparseable";
+/** Relative path like "transactions/sdk/<transactionId>.json". */
+file: string;
+/** Journal status read from the receipt, or null when unreadable. */
+status: string | null;
+/** Age in seconds derived from the journal's updatedAt, or null when unparseable. */
+age_seconds: number | null;
+/** Whether the journal was (or would be) pruned. */
+stale: boolean;
+/** Why the journal was retained, when it was. */
+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[]>;
-    /** Invoked after removing each journal file. */
-    onWrite?: (absolutePath: string) => Promise<string[]>;
+/** Invoked before reading each journal file. */
+onRead?: (absolutePath: string) => Promise<string[]>;
+/** Invoked after removing each journal file. */
+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;
-    /** 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;
-    /** Clock override for deterministic tests (milliseconds since epoch). */
-    now?: number;
-    /** Extension observability hooks. */
-    hooks?: WorkspaceTransactionGcHooks;
+/** Preview prune decisions without deleting any journal. */
+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;
+/** Clock override for deterministic tests (milliseconds since epoch). */
+now?: number;
+/** Extension observability hooks. */
+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;
-    /** Relative paths of pruned journals. */
-    removed: string[];
-    /** Relative paths of retained journals. */
-    retained: string[];
-    /** Non-fatal sweep warnings. */
-    warnings: string[];
-    /** One decision row per scanned journal. */
-    entries: WorkspaceTransactionGcEntry[];
+/** Number of journal files scanned. */
+scanned: number;
+/** Relative paths of pruned journals. */
+removed: string[];
+/** Relative paths of retained journals. */
+retained: string[];
+/** Non-fatal sweep warnings. */
+warnings: string[];
+/** One decision row per scanned journal. */
+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>;

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;
-    /** Reconstructed result when the mutation is already applied. */
-    result?: WorkspaceTransactionJsonValue;
+/** Current durable state of the step's domain mutation. */
+state: WorkspaceTransactionStepState;
+/** Reconstructed result when the mutation is already applied. */
+result?: WorkspaceTransactionJsonValue;
 }
 /** One idempotent forward mutation with an append-only compensation. */
 export interface WorkspaceTransactionStep {
-    /** Stable identifier unique within the transaction plan. */
-    id: string;
-    /** Inspect durable domain state without mutating it. */
-    inspect(): Promise<WorkspaceTransactionStepInspection>;
-    /** Capture journal-safe pre-mutation data required by compensation. */
-    prepareCompensation?(): Promise<WorkspaceTransactionJsonValue | undefined>;
-    /** Apply the forward mutation and return a journal-safe result, or store nothing. */
-    apply(): Promise<WorkspaceTransactionJsonValue | undefined>;
-    /** Idempotently reconcile only this step's exact forward mutation when present. */
-    compensate(data?: WorkspaceTransactionJsonValue): Promise<void>;
+/** Stable identifier unique within the transaction plan. */
+id: string;
+/** Inspect durable domain state without mutating it. */
+inspect(): Promise<WorkspaceTransactionStepInspection>;
+/** Capture journal-safe pre-mutation data required by compensation. */
+prepareCompensation?(): Promise<WorkspaceTransactionJsonValue | undefined>;
+/** Apply the forward mutation and return a journal-safe result, or store nothing. */
+apply(): Promise<WorkspaceTransactionJsonValue | undefined>;
+/** Idempotently reconcile only this step's exact forward mutation when present. */
+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;
-    /** Current durable transaction attempt. */
-    attempt: number;
-    /** Transition reached; `step_applied` follows mutation and precedes journal recording. */
-    transition: WorkspaceTransactionTransition;
-    /** Step associated with a step-level transition. */
-    stepId?: string;
+/** Stable transaction identifier. */
+transactionId: string;
+/** Current durable transaction attempt. */
+attempt: number;
+/** Transition reached; `step_applied` follows mutation and precedes journal recording. */
+transition: WorkspaceTransactionTransition;
+/** Step associated with a step-level transition. */
+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;
-    /** Stable idempotency key reused to recover an interrupted transaction. */
-    transactionId: string;
-    /** Attributable actor recorded in the durable journal. */
-    author: string;
-    /** Ordered idempotent mutations; compensations run in reverse order. */
-    steps: readonly WorkspaceTransactionStep[];
-    /** Lock lifetime in seconds; size this above the longest expected attempt. */
-    lockTtlSeconds?: number;
-    /** Maximum time to wait for the workspace writer lock. */
-    lockWaitMs?: number;
-    /** Optional transition observer used by telemetry and deterministic crash tests. */
-    onTransition?(context: WorkspaceTransactionTransitionContext): void | Promise<void>;
+/** Tracker root that owns the journal and workspace-wide writer lock. */
+pmRoot: string;
+/** Stable idempotency key reused to recover an interrupted transaction. */
+transactionId: string;
+/** Attributable actor recorded in the durable journal. */
+author: string;
+/** Ordered idempotent mutations; compensations run in reverse order. */
+steps: readonly WorkspaceTransactionStep[];
+/** Lock lifetime in seconds; size this above the longest expected attempt. */
+lockTtlSeconds?: number;
+/** Maximum time to wait for the workspace writer lock. */
+lockWaitMs?: number;
+/** Optional transition observer used by telemetry and deterministic crash tests. */
+onTransition?(context: WorkspaceTransactionTransitionContext): void | Promise<void>;
 }
 /** Successful durable transaction result. */
 export interface WorkspaceTransactionCommitResult {
-    /** Stable transaction identifier. */
-    transactionId: string;
-    /** Final durable state. */
-    status: "committed";
-    /** Whether an interrupted journal was resumed. */
-    recovered: boolean;
-    /** One result per ordered transaction step. */
-    results: Record<string, WorkspaceTransactionJsonValue>;
+/** Stable transaction identifier. */
+transactionId: string;
+/** Final durable state. */
+status: "committed";
+/** Whether an interrupted journal was resumed. */
+recovered: boolean;
+/** One result per ordered transaction step. */
+results: Record<string, WorkspaceTransactionJsonValue>;
 }
 /**
  * Deliberate process-boundary interruption used by deterministic crash tests.
@@ -71,8 +71,8 @@ export interface WorkspaceTransactionCommitResult {
  * normal in-process compensation path.
  */
 export declare class WorkspaceTransactionInterruptedError extends Error {
-    /** Create one explicit crash-boundary interruption. */
-    constructor(message?: string);
+/** Create one explicit crash-boundary interruption. */
+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">;

package/dist/sdk/workspace.d.ts

@@ -18,10 +18,10 @@ export declare const PM_GITIGNORE_RUNTIME_DIRECTORIES: readonly ["runtime/", "se
 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;
-    /** Whether the file content changed. */
-    changed: boolean;
+/** Absolute path to the reconciled file. */
+path: string;
+/** Whether the file content changed. */
+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;
@@ -36,6 +36,6 @@ export declare function getPmGitignoreBlock(trackerRelativeRoot?: string): strin
  * file is left untouched.
  */
 export declare function ensurePmGitignore(workspaceRoot: string, options?: {
-    /** Absolute tracker root; rendered relative to the workspace root. */
-    pmRoot?: string;
+/** Absolute tracker root; rendered relative to the workspace root. */
+pmRoot?: string;
 }): Promise<EnsurePmGitignoreResult>;