@unbrained/pm-cli 2026.10.12 → 2026.10.13

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

@@ -6,91 +6,91 @@ import { type CommitWorkspaceTransactionOptions, type WorkspaceTransactionJsonVa
  * as the already-applied result, so ids must be stable and transaction-owned.
  */
 export interface BulkItemCreateMutation {
-    /** Discriminates the creation operation. */
-    op: "create";
-    /** Explicit stable item id (normalized with the configured id_prefix). */
-    id: string;
-    /** Creation options forwarded to the public `create` runtime primitive. */
-    options: PmClientFullMutationOptions;
+/** Discriminates the creation operation. */
+op: "create";
+/** Explicit stable item id (normalized with the configured id_prefix). */
+id: string;
+/** Creation options forwarded to the public `create` runtime primitive. */
+options: PmClientFullMutationOptions;
 }
 /** One atomic item update inside a bulk mutation batch. */
 export interface BulkItemUpdateMutation {
-    /** Discriminates the update operation. */
-    op: "update";
-    /** Target item id. */
-    id: string;
-    /** Update options forwarded to the public `update` runtime primitive. */
-    options: PmClientFullMutationOptions;
+/** Discriminates the update operation. */
+op: "update";
+/** Target item id. */
+id: string;
+/** Update options forwarded to the public `update` runtime primitive. */
+options: PmClientFullMutationOptions;
 }
 /** One atomic item closure inside a bulk mutation batch. */
 export interface BulkItemCloseMutation {
-    /** Discriminates the close operation. */
-    op: "close";
-    /** Target item id. */
-    id: string;
-    /** Close reason recorded on the item. */
-    reason: string;
-    /** Close options forwarded to the public `close` runtime primitive. */
-    options?: PmClientFullMutationOptions;
+/** Discriminates the close operation. */
+op: "close";
+/** Target item id. */
+id: string;
+/** Close reason recorded on the item. */
+reason: string;
+/** Close options forwarded to the public `close` runtime primitive. */
+options?: PmClientFullMutationOptions;
 }
 /** One atomic claim release inside a bulk mutation batch. */
 export interface BulkItemReleaseMutation {
-    /** Discriminates the claim-release operation. */
-    op: "release";
-    /** Target item id. */
-    id: string;
-    /** Release options forwarded to the public `release` runtime primitive. */
-    options?: PmClientFullMutationOptions;
+/** Discriminates the claim-release operation. */
+op: "release";
+/** Target item id. */
+id: string;
+/** Release options forwarded to the public `release` runtime primitive. */
+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;
-    /** Stable idempotency key reused to recover an interrupted batch. */
-    transactionId: string;
-    /** Attributable actor recorded in the journal and forwarded to mutations. */
-    author: string;
-    /** Ordered item mutations; compensations run in reverse order. */
-    mutations: readonly BulkItemMutation[];
-    /**
+/** Tracker root that owns the journal and workspace-wide writer lock. */
+pmRoot: string;
+/** Stable idempotency key reused to recover an interrupted batch. */
+transactionId: string;
+/** Attributable actor recorded in the journal and forwarded to mutations. */
+author: string;
+/** Ordered item mutations; compensations run in reverse order. */
+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`).
      */
-    createCompensation?: "close" | "delete";
-    /** 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?: CommitWorkspaceTransactionOptions["onTransition"];
+createCompensation?: "close" | "delete";
+/** 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?: CommitWorkspaceTransactionOptions["onTransition"];
 }
 /** Journal-safe outcome recorded for one committed bulk item mutation. */
 export interface BulkItemMutationOutcome {
-    /** Canonical id of the mutated item. */
-    id: string;
-    /** Operation the batch applied for this item. */
-    op: BulkItemMutation["op"];
+/** Canonical id of the mutated item. */
+id: string;
+/** Operation the batch applied for this item. */
+op: BulkItemMutation["op"];
 }
 /** Successful durable result of a bulk item-mutation transaction. */
 export interface CommitItemMutationsResult {
-    /** Stable transaction identifier. */
-    transactionId: string;
-    /** Final durable state. */
-    status: "committed";
-    /** Whether an interrupted journal was resumed. */
-    recovered: boolean;
-    /** One outcome per mutation, keyed by the derived transaction step id. */
-    results: Record<string, BulkItemMutationOutcome>;
+/** Stable transaction identifier. */
+transactionId: string;
+/** Final durable state. */
+status: "committed";
+/** Whether an interrupted journal was resumed. */
+recovered: boolean;
+/** One outcome per mutation, keyed by the derived transaction step id. */
+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>;
@@ -107,25 +107,25 @@ declare function bulkHistoryMarker(transactionId: string, stepId: string, phase:
 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;
+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";
+pmRoot: string;
+author: string;
+transactionId: string;
+createCompensation: "close" | "delete";
 }, 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;
-    /** Distinguishes newly staged execution from idempotent replay without fresh step validation. */
-    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[];
+/** True when the coordinator executed staged validation; false for an already committed journal replay. */
+validated: boolean;
+/** Distinguishes newly staged execution from idempotent replay without fresh step validation. */
+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[];
 }
 /** 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>;
@@ -143,28 +143,28 @@ export declare function previewItemMutations(options: Pick<CommitItemMutationsOp
 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;
-    /** Stable idempotency key for the composed completion. */
-    transactionId: string;
-    /** Attributable actor for evidence, closure, and claim release. */
-    author: string;
-    /** Item being completed. */
-    id: string;
-    /** Durable close reason. */
-    reason: string;
-    /** Evidence and linked-resource updates recorded before closure. */
-    evidence?: PmClientFullMutationOptions;
-    /** Structured closure fields and validation policy. */
-    closeOptions?: PmClientFullMutationOptions;
-    /** Claim-release controls. */
-    releaseOptions?: PmClientFullMutationOptions;
-    /** Workspace transaction lock lifetime in seconds. */
-    lockTtlSeconds?: number;
-    /** Maximum time to wait for the workspace transaction lock. */
-    lockWaitMs?: number;
-    /** Optional transition observer used by telemetry and crash tests. */
-    onTransition?: CommitWorkspaceTransactionOptions["onTransition"];
+/** Tracker root that owns the item and transaction journal. */
+pmRoot: string;
+/** Stable idempotency key for the composed completion. */
+transactionId: string;
+/** Attributable actor for evidence, closure, and claim release. */
+author: string;
+/** Item being completed. */
+id: string;
+/** Durable close reason. */
+reason: string;
+/** Evidence and linked-resource updates recorded before closure. */
+evidence?: PmClientFullMutationOptions;
+/** Structured closure fields and validation policy. */
+closeOptions?: PmClientFullMutationOptions;
+/** Claim-release controls. */
+releaseOptions?: PmClientFullMutationOptions;
+/** Workspace transaction lock lifetime in seconds. */
+lockTtlSeconds?: number;
+/** Maximum time to wait for the workspace transaction lock. */
+lockWaitMs?: number;
+/** Optional transition observer used by telemetry and crash tests. */
+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[];
@@ -177,11 +177,11 @@ export declare function buildItemCompletionMutations(options: Pick<CommitItemCom
 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;
+buildCreateStep: typeof buildCreateStep;
+bulkHistoryMarker: typeof bulkHistoryMarker;
+compensateByRestore: typeof compensateByRestore;
+deriveStepId: typeof deriveStepId;
+isUpdateMarkerApplied: typeof isUpdateMarkerApplied;
+readItemSnapshot: typeof readItemSnapshot;
 };
 export {};

package/dist/sdk/learnings.d.ts

@@ -8,51 +8,51 @@ import type { LogNote } from "../types/index.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;
-    /** Read learning text from stdin. */
-    stdin?: boolean;
-    /** Read learning text from a UTF-8 file. */
-    file?: string;
-    /** Replace the learning at this one-based index. */
-    edit?: number;
-    /** Delete the learning at this one-based index. */
-    delete?: number;
-    /** Value that configures or reports limit for this contract. */
-    limit?: string;
-    /** Return complete learning history after a mutation instead of a bounded receipt. */
-    fullHistory?: boolean;
-    /** Append only when no learning has the same resolved author and text. */
-    ifAbsent?: boolean;
-    /** Value that configures or reports author for this contract. */
-    author?: string;
-    /** Human-readable explanation suitable for logs and agent-facing output. */
-    message?: string;
-    /** Value that configures or reports force for this contract. */
-    force?: boolean;
+/** Value that configures or reports add for this contract. */
+add?: string;
+/** Read learning text from stdin. */
+stdin?: boolean;
+/** Read learning text from a UTF-8 file. */
+file?: string;
+/** Replace the learning at this one-based index. */
+edit?: number;
+/** Delete the learning at this one-based index. */
+delete?: number;
+/** Value that configures or reports limit for this contract. */
+limit?: string;
+/** Return complete learning history after a mutation instead of a bounded receipt. */
+fullHistory?: boolean;
+/** Append only when no learning has the same resolved author and text. */
+ifAbsent?: boolean;
+/** Value that configures or reports author for this contract. */
+author?: string;
+/** Human-readable explanation suitable for logs and agent-facing output. */
+message?: string;
+/** Value that configures or reports force for this contract. */
+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;
-    /** Value that configures or reports learnings for this contract. */
-    learnings: LogNote[];
-    /** Value that configures or reports count for this contract. */
-    count: number;
-    /** Total learning count after the mutation. */
-    total_count?: number;
-    /** Number of learning entries returned in this projection. */
-    returned_count?: number;
-    /** Whether additional stored learning entries were withheld. */
-    has_more?: boolean;
-    /** Applied read limit when one was requested. */
-    limit?: number;
-    /** Mutation identity when this result changed the collection. */
-    mutation_receipt?: AnnotationMutationReceipt;
-    /** Declares whether older learnings were withheld from a mutation response. */
-    omission_receipt?: AnnotationOmissionReceipt;
-    /** Whether a requested mutation changed persisted state. */
-    changed?: boolean;
+/** Stable identifier used to reference this record across commands and storage. */
+id: string;
+/** Value that configures or reports learnings for this contract. */
+learnings: LogNote[];
+/** Value that configures or reports count for this contract. */
+count: number;
+/** Total learning count after the mutation. */
+total_count?: number;
+/** Number of learning entries returned in this projection. */
+returned_count?: number;
+/** Whether additional stored learning entries were withheld. */
+has_more?: boolean;
+/** Applied read limit when one was requested. */
+limit?: number;
+/** Mutation identity when this result changed the collection. */
+mutation_receipt?: AnnotationMutationReceipt;
+/** Declares whether older learnings were withheld from a mutation response. */
+omission_receipt?: AnnotationOmissionReceipt;
+/** Whether a requested mutation changed persisted state. */
+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>;

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

@@ -1,25 +1,25 @@
 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;
-    /** Value that configures or reports author for this contract. */
-    author?: string;
-    /** Human-readable explanation suitable for logs and agent-facing output. */
-    message?: string;
-    /** Value that configures or reports force for this contract. */
-    force?: boolean;
+/** Value that configures or reports body for this contract. */
+body: string;
+/** Value that configures or reports author for this contract. */
+author?: string;
+/** Human-readable explanation suitable for logs and agent-facing output. */
+message?: string;
+/** Value that configures or reports force for this contract. */
+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>;
-    /** Value that configures or reports appended for this contract. */
-    appended: string;
-    /** Value that configures or reports changed fields for this contract. */
-    changed_fields: string[];
+/** Value that configures or reports item for this contract. */
+item: Record<string, unknown>;
+/** Value that configures or reports appended for this contract. */
+appended: string;
+/** Value that configures or reports changed fields for this contract. */
+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>;

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

@@ -4,50 +4,50 @@ import { type NextRecommendation, type NextOptions } from "../query/next.js";
 export declare const NO_AVAILABLE_NEXT_ITEM_CODE = "no_available_next_item";
 /** Documents the claim result payload exchanged by command, SDK, and package integrations. */
 export interface ClaimResult {
-    /** Value that configures or reports item for this contract. */
-    item: Record<string, unknown>;
-    /** Metadata fields changed by this claim; empty for an idempotent or skipped claim. */
-    changed_fields?: string[];
-    /** Value that configures or reports claimed by for this contract. */
-    claimed_by: string;
-    /** Value that configures or reports previous assignee for this contract. */
-    previous_assignee: string | null;
-    /** Value that configures or reports forced for this contract. */
-    forced: boolean;
-    /** Value that configures or reports skipped for this contract. */
-    skipped?: boolean;
-    /** Value that configures or reports warnings for this contract. */
-    warnings?: string[];
+/** Value that configures or reports item for this contract. */
+item: Record<string, unknown>;
+/** Metadata fields changed by this claim; empty for an idempotent or skipped claim. */
+changed_fields?: string[];
+/** Value that configures or reports claimed by for this contract. */
+claimed_by: string;
+/** Value that configures or reports previous assignee for this contract. */
+previous_assignee: string | null;
+/** Value that configures or reports forced for this contract. */
+forced: boolean;
+/** Value that configures or reports skipped for this contract. */
+skipped?: boolean;
+/** Value that configures or reports warnings for this contract. */
+warnings?: string[];
 }
 /** Result of atomically selecting and claiming the next caller-available item. */
 export interface ClaimNextAvailableResult extends ClaimResult {
-    /** True when an actionable candidate was claimed. */
-    available: true;
-    /** Value that configures or reports recommendation for this contract. */
-    recommendation: NextRecommendation;
-    /** Value that configures or reports attempts for this contract. */
-    attempts: number;
+/** True when an actionable candidate was claimed. */
+available: true;
+/** Value that configures or reports recommendation for this contract. */
+recommendation: NextRecommendation;
+/** Value that configures or reports attempts for this contract. */
+attempts: number;
 }
 /** Non-error empty result returned when an if-available candidate walk is exhausted. */
 export interface ClaimNextUnavailableResult {
-    /** Indicates that no candidate remained claimable. */
-    available: false;
-    /** Empty item projection for a deliberately unavailable selection. */
-    item: null;
-    /** Caller identity that attempted the selection. */
-    claimed_by: string;
-    /** No previous owner exists for an empty selection. */
-    previous_assignee: null;
-    /** Whether forced selection was requested. */
-    forced: boolean;
-    /** Signals a deliberate non-error skip. */
-    skipped: true;
-    /** No recommendation survived the bounded walk. */
-    recommendation: null;
-    /** Number of ranked candidates attempted. */
-    attempts: number;
-    /** Stable machine-readable exhaustion warning. */
-    warnings: [typeof NO_AVAILABLE_NEXT_ITEM_CODE];
+/** Indicates that no candidate remained claimable. */
+available: false;
+/** Empty item projection for a deliberately unavailable selection. */
+item: null;
+/** Caller identity that attempted the selection. */
+claimed_by: string;
+/** No previous owner exists for an empty selection. */
+previous_assignee: null;
+/** Whether forced selection was requested. */
+forced: boolean;
+/** Signals a deliberate non-error skip. */
+skipped: true;
+/** No recommendation survived the bounded walk. */
+recommendation: null;
+/** Number of ranked candidates attempted. */
+attempts: number;
+/** Stable machine-readable exhaustion warning. */
+warnings: [typeof NO_AVAILABLE_NEXT_ITEM_CODE];
 }
 /** Result of a successful or deliberately empty atomic next-work claim. */
 export type ClaimNextResult = ClaimNextAvailableResult | ClaimNextUnavailableResult;
@@ -56,31 +56,31 @@ export declare function isAlreadyClaimedError(error: unknown): boolean;
 type ClaimRunner = (id: string, force: boolean, global: GlobalOptions, options: ClaimMutationOptions) => Promise<ClaimResult>;
 /** Documents the release result payload exchanged by command, SDK, and package integrations. */
 export interface ReleaseResult {
-    /** Value that configures or reports item for this contract. */
-    item: Record<string, unknown>;
-    /** Ownership fields actually removed, or an empty list for an unclaimed item. */
-    changed_fields?: string[];
-    /** Value that configures or reports released by for this contract. */
-    released_by: string;
-    /** Value that configures or reports previous assignee for this contract. */
-    previous_assignee: string | null;
-    /** Value that configures or reports forced for this contract. */
-    forced: boolean;
-    /** Stable handoff diagnostics shared by CLI and MCP consumers. */
-    warnings?: string[];
-    /** Concrete recovery commands when releasing ownership leaves work in progress. */
-    suggestions?: string[];
+/** Value that configures or reports item for this contract. */
+item: Record<string, unknown>;
+/** Ownership fields actually removed, or an empty list for an unclaimed item. */
+changed_fields?: string[];
+/** Value that configures or reports released by for this contract. */
+released_by: string;
+/** Value that configures or reports previous assignee for this contract. */
+previous_assignee: string | null;
+/** Value that configures or reports forced for this contract. */
+forced: boolean;
+/** Stable handoff diagnostics shared by CLI and MCP consumers. */
+warnings?: string[];
+/** Concrete recovery commands when releasing ownership leaves work in progress. */
+suggestions?: string[];
 }
 /** Documents the claim mutation options payload exchanged by command, SDK, and package integrations. */
 export interface ClaimMutationOptions {
-    /** Value that configures or reports author for this contract. */
-    author?: string;
-    /** Human-readable explanation suitable for logs and agent-facing output. */
-    message?: string;
-    /** Value that configures or reports if available for this contract. */
-    ifAvailable?: boolean;
-    /** Maximum ranked candidates attempted by `claim --next`. */
-    maxAttempts?: string | number;
+/** Value that configures or reports author for this contract. */
+author?: string;
+/** Human-readable explanation suitable for logs and agent-facing output. */
+message?: string;
+/** Value that configures or reports if available for this contract. */
+ifAvailable?: boolean;
+/** Maximum ranked candidates attempted by `claim --next`. */
+maxAttempts?: string | number;
 }
 /** Documents the release mutation options payload exchanged by command, SDK, and package integrations. */
 export type ReleaseMutationOptions = ClaimMutationOptions;