@unbrained/pm-cli 2026.8.4 → 2026.8.5

package/sdk/public-surface.json

@@ -1,6 +1,6 @@
 {
   "aggregate_completeness": {
-    "covered_symbols": 1417,
+    "covered_symbols": 1432,
     "excluded": [
       {
         "name": "_testOnlyCliContracts",
@@ -8,7 +8,7 @@
       }
     ],
     "missing": [],
-    "required_symbols": 1418
+    "required_symbols": 1433
   },
   "breaking_acknowledgements": [
     {
@@ -758,6 +758,38 @@
       ],
       "package_version": "2026.8.3",
       "reason": "Aggregate filter metadata now discloses multi-status OR selections through optional status_values while preserving status compatibility"
+    },
+    {
+      "changes": [
+        "signature ./sdk:ContractsResult",
+        "signature ./sdk:PM_COMMAND_OUTPUT_BUDGET_CONTRACTS",
+        "signature ./sdk:PmCommandOutputBudgetContract",
+        "signature ./sdk:PmErrorCodeContract",
+        "signature ./sdk:resolvePmCommandOutputBudget",
+        "signature ./sdk/contracts:PM_COMMAND_OUTPUT_BUDGET_CONTRACTS",
+        "signature ./sdk/contracts:PmCommandOutputBudgetContract",
+        "signature ./sdk/contracts:PmErrorCodeContract",
+        "signature ./sdk/contracts:resolvePmCommandOutputBudget",
+        "signature ./sdk/runtime:ContractsResult",
+        "signature ./sdk/runtime:PmErrorCodeContract"
+      ],
+      "package_version": "2026.8.4",
+      "reason": "Output contracts now expose format-aware budgets, envelope families, and classified error metadata; existing call forms and runtime fields remain compatible."
+    },
+    {
+      "changes": [
+        "signature ./sdk:parseMutationReceipt",
+        "signature ./sdk/contracts:parseMutationReceipt"
+      ],
+      "package_version": "2026.8.4",
+      "reason": "PR 895 pre-merge correction: expose explicit string JSON and decoded unknown mutation-receipt overloads before the new API is released."
+    },
+    {
+      "changes": [
+        "signature ./sdk:BulkItemMutation"
+      ],
+      "package_version": "2026.8.4",
+      "reason": "Add the release mutation variant required for atomic evidence-close-release completion; exhaustive BulkItemMutation consumers must handle release"
     }
   ],
   "entrypoints": {
@@ -1718,6 +1750,12 @@
           "name": "buildItemChildrenRollup",
           "signature": "(parentId: string, corpus: Iterable<ItemMetadata>, statusRegistry: RuntimeStatusRegistry, sampleLimit?: number) => ChildRollupContext | calls: (parentId: string, corpus: Iterable<ItemMetadata>, statusRegistry: RuntimeStatusRegistry, sampleLimit?: number) => ChildRollupContext"
         },
+        {
+          "classification": "advanced_export",
+          "kind": "function",
+          "name": "buildItemCompletionMutations",
+          "signature": "(options: Pick<CommitItemCompletionOptions, \"closeOptions\" | \"evidence\" | \"id\" | \"reason\" | \"releaseOptions\">) => BulkItemMutation[] | calls: (options: Pick<CommitItemCompletionOptions, \"id\" | \"reason\" | \"evidence\" | \"closeOptions\" | \"releaseOptions\">) => BulkItemMutation[]"
+        },
         {
           "classification": "supported",
           "kind": "function",
@@ -1842,7 +1880,7 @@
           "classification": "advanced_export",
           "kind": "type",
           "name": "BulkItemMutation",
-          "signature": "export type BulkItemMutation = BulkItemCreateMutation | BulkItemUpdateMutation | BulkItemCloseMutation;"
+          "signature": "export type BulkItemMutation = BulkItemCreateMutation | BulkItemUpdateMutation | BulkItemCloseMutation | BulkItemReleaseMutation;"
         },
         {
           "classification": "advanced_export",
@@ -1850,6 +1888,12 @@
           "name": "BulkItemMutationOutcome",
           "signature": "export interface BulkItemMutationOutcome { id: string; op: BulkItemMutation[\"op\"]; }"
         },
+        {
+          "classification": "advanced_export",
+          "kind": "interface",
+          "name": "BulkItemReleaseMutation",
+          "signature": "export interface BulkItemReleaseMutation { op: \"release\"; id: string; options?: PmClientFullMutationOptions; }"
+        },
         {
           "classification": "advanced_export",
           "kind": "interface",
@@ -2324,6 +2368,18 @@
           "name": "CommitImportedItemResult",
           "signature": "export type CommitImportedItemResult = { committed: true; writeWarnings: string[]; } | { committed: false; conflictWarning: string; };"
         },
+        {
+          "classification": "advanced_export",
+          "kind": "function",
+          "name": "commitItemCompletion",
+          "signature": "(options: CommitItemCompletionOptions) => Promise<CommitItemMutationsResult> | calls: (options: CommitItemCompletionOptions) => Promise<CommitItemMutationsResult>"
+        },
+        {
+          "classification": "advanced_export",
+          "kind": "interface",
+          "name": "CommitItemCompletionOptions",
+          "signature": "export interface CommitItemCompletionOptions { pmRoot: string; transactionId: string; author: string; id: string; reason: string; evidence?: PmClientFullMutationOptions; closeOptions?: PmClientFullMutationOptions; releaseOptions?: PmClientFullMutationOptions; lockTtlSeconds?: number; lockWaitMs?: number; onTransition?: CommitWorkspaceTransactionOptions[\"onTransition\"]; }"
+        },
         {
           "classification": "advanced_export",
           "kind": "function",
@@ -2874,7 +2930,7 @@
           "classification": "advanced_export",
           "kind": "interface",
           "name": "ContractsResult",
-          "signature": "export interface ContractsResult { schema_version: string | null; schema_id: string | null; selected: { action: string | null; command: string | null; summary: boolean; schema_only: boolean; flags_only: boolean; availability_only: boolean; runtime_only: boolean; command_scoped: boolean; }; actions?: string[]; action_availability?: ContractsActionAvailability[]; commands: string[]; schema?: Record<string, unknown>; schema_omitted_reason?: string; command_flags_omitted_reason?: string; commander_aliases_omitted_reason?: string; command_flags?: CommandFlagSurface[]; list_projections?: ListCommandProjectionSurface[]; command_aliases?: CommandAliasSurface[]; commander_aliases?: Record<string, CommanderOptionAliasContract[]>; extension_commands?: ExtensionCommandContract[]; command_summaries?: CommandSummarySurface[]; output_policy?: { token_estimate: \"ceil(utf8_bytes / 4)\"; degradation_ladder: string[]; allows_unbounded_opt_out: boolean; }; runtime_schema?: { statuses: string[]; open_status: string; close_status: string; canceled_status: string; types: string[]; fields_by_command: Record<string, string[]>; }; extension_contracts?: { capabilities: string[]; services: string[]; policy_modes: string[]; policy_mode_scope: \"extensions.policy.mode\"; policy_surfaces: string[]; trust_modes: string[]; trust_mode_scope: \"extensions.policy.trust_mode\"; sandbox_profiles: string[]; manifest_versions: number[]; compatibility: { current: string; previous: string[]; breaking_strategy: string; }; }; governance_contracts?: { ownership_enforcement_modes: string[]; create_modes: string[]; close_validation_modes: string[]; workflow_enforcement_modes: string[]; }; mcp_tools?: McpToolContract[]; context_intents?: readonly PmContextIntentContract[]; read_output_dimensions?: readonly PmReadOutputSurfaceContract[]; error_codes?: readonly PmErrorCodeContract[]; }"
+          "signature": "export interface ContractsResult { schema_version: string | null; schema_id: string | null; selected: { action: string | null; command: string | null; summary: boolean; schema_only: boolean; flags_only: boolean; availability_only: boolean; runtime_only: boolean; command_scoped: boolean; }; actions?: string[]; action_availability?: ContractsActionAvailability[]; commands: string[]; schema?: Record<string, unknown>; schema_omitted_reason?: string; command_flags_omitted_reason?: string; commander_aliases_omitted_reason?: string; command_flags?: CommandFlagSurface[]; list_projections?: ListCommandProjectionSurface[]; command_aliases?: CommandAliasSurface[]; commander_aliases?: Record<string, CommanderOptionAliasContract[]>; extension_commands?: ExtensionCommandContract[]; command_summaries?: CommandSummarySurface[]; output_policy?: { token_estimate: \"ceil(utf8_bytes / 4)\"; degradation_ladder: string[]; allows_unbounded_opt_out: boolean; }; runtime_schema?: { statuses: string[]; open_status: string; close_status: string; canceled_status: string; types: string[]; fields_by_command: Record<string, string[]>; }; extension_contracts?: { capabilities: string[]; services: string[]; policy_modes: string[]; policy_mode_scope: \"extensions.policy.mode\"; policy_surfaces: string[]; trust_modes: string[]; trust_mode_scope: \"extensions.policy.trust_mode\"; sandbox_profiles: string[]; manifest_versions: number[]; compatibility: { current: string; previous: string[]; breaking_strategy: string; }; }; governance_contracts?: { ownership_enforcement_modes: string[]; create_modes: string[]; close_validation_modes: string[]; workflow_enforcement_modes: string[]; }; mcp_tools?: McpToolContract[]; context_intents?: readonly PmContextIntentContract[]; read_output_dimensions?: readonly PmReadOutputSurfaceContract[]; error_codes?: readonly PmErrorCodeContract[]; command_output_contracts?: Array<{ budget: PmCommandOutputBudgetContract; envelope: PmCommandOutputEnvelopeContract; }>; }"
         },
         {
           "classification": "supported",
@@ -3062,6 +3118,12 @@
           "name": "createPmCliProgram",
           "signature": "(version: string) => Command | calls: (version: string) => Command"
         },
+        {
+          "classification": "contract_data",
+          "kind": "function",
+          "name": "createPmCommandOutputBudget",
+          "signature": "(command: string, budgetClass?: PmOutputBudgetClass) => PmCommandOutputBudgetContract | calls: (command: string, budgetClass?: PmOutputBudgetClass) => PmCommandOutputBudgetContract"
+        },
         {
           "classification": "supported",
           "kind": "function",
@@ -3362,6 +3424,12 @@
           "name": "definePmCommandOutputBudget",
           "signature": "<TContract extends PmCommandOutputBudgetContract>(contract: TContract) => TContract | calls: <TContract extends PmCommandOutputBudgetContract>(contract: TContract) => TContract"
         },
+        {
+          "classification": "contract_data",
+          "kind": "function",
+          "name": "definePmCommandOutputEnvelope",
+          "signature": "<TContract extends PmCommandOutputEnvelopeContract>(contract: TContract) => TContract | calls: <TContract extends PmCommandOutputEnvelopeContract>(contract: TContract) => TContract"
+        },
         {
           "classification": "contract_data",
           "kind": "function",
@@ -4562,6 +4630,12 @@
           "name": "EXTERNAL_DEPENDENCY_SOURCE_KIND",
           "signature": "\"global\""
         },
+        {
+          "classification": "advanced_export",
+          "kind": "value",
+          "name": "EXTERNAL_DEPENDENCY_SOURCE_KIND_ALIAS",
+          "signature": "\"external\""
+        },
         {
           "classification": "advanced_export",
           "kind": "function",
@@ -5642,6 +5716,12 @@
           "name": "inferConsistentVectorDimension",
           "signature": "(vectors: readonly number[][], context: string) => number | calls: (vectors: readonly number[][], context: string) => number"
         },
+        {
+          "classification": "contract_data",
+          "kind": "function",
+          "name": "inferPmOutputBudgetClass",
+          "signature": "(command: string) => PmOutputBudgetClass | calls: (command: string) => PmOutputBudgetClass"
+        },
         {
           "classification": "advanced_export",
           "kind": "function",
@@ -5828,6 +5908,12 @@
           "name": "isPmExtensionServiceNameContract",
           "signature": "(value: string) => value is PmExtensionServiceNameContract | calls: (value: string) => value is PmExtensionServiceNameContract"
         },
+        {
+          "classification": "contract_data",
+          "kind": "function",
+          "name": "isPmMutationReceipt",
+          "signature": "(value: unknown) => value is PmCliMutationReceipt | calls: (value: unknown) => value is PmCliMutationReceipt"
+        },
         {
           "classification": "contract_data",
           "kind": "function",
@@ -5882,6 +5968,12 @@
           "name": "isTimestampLiteral",
           "signature": "(input: string) => boolean | calls: (input: string) => boolean"
         },
+        {
+          "classification": "contract_data",
+          "kind": "value",
+          "name": "ITEM_COMPLETE_FLAG_CONTRACTS",
+          "signature": "CliFlagContract[]"
+        },
         {
           "classification": "supported",
           "kind": "value",
@@ -7358,6 +7450,12 @@
           "name": "parseMultiValueFilter",
           "signature": "(raw: string | undefined, options: MultiValueFilterOptions) => string[] | undefined | calls: (raw: string | undefined, options: MultiValueFilterOptions) => string[] | undefined"
         },
+        {
+          "classification": "contract_data",
+          "kind": "function",
+          "name": "parseMutationReceipt",
+          "signature": "{ (json: string): PmMutationReceipt; (value: unknown): PmMutationReceipt; } | calls: (json: string) => PmMutationReceipt ; (value: unknown) => PmMutationReceipt"
+        },
         {
           "classification": "advanced_export",
           "kind": "function",
@@ -7650,7 +7748,13 @@
           "classification": "contract_data",
           "kind": "value",
           "name": "PM_COMMAND_OUTPUT_BUDGET_CONTRACTS",
-          "signature": "{ command: \"activity\" | \"aggregate\" | \"append\" | \"claim\" | \"close-many\" | \"close-task\" | \"close\" | \"comments\" | \"config\" | \"context\" | \"contracts\" | \"copy\" | \"create\" | \"ctx\" | \"delete\" | \"deps\" | \"docs\" | \"duplicates\" | \"eval\" | \"event\" | \"events\" | \"extension\" | \"files\" | \"focus\" | \"gc\" | \"get\" | \"graph\" | \"health\" | \"help\" | \"history-author-acknowledge\" | \"history-compact\" | \"history-redact\" | \"history-repair\" | \"history\" | \"init\" | \"install\" | \"item\" | \"learnings\" | \"list-all\" | \"list-blocked\" | \"list-canceled\" | \"list-closed\" | \"list-draft\" | \"list-in-progress\" | \"list-open\" | \"list\" | \"meet\" | \"merge\" | \"next\" | \"notes\" | \"package\" | \"packages\" | \"pause-task\" | \"plan\" | \"profile\" | \"release\" | \"remind\" | \"restore\" | \"schema\" | \"search\" | \"start-task\" | \"stats\" | \"telemetry\" | \"test-all\" | \"test\" | \"update-many\" | \"update\" | \"upgrade\" | \"validate\" | \"workspace\"; budget_class: \"discovery\" | \"governance\" | \"mutation\" | \"read\"; default_max_estimated_tokens: number; degradation_ladder: readonly [\"full\", \"compact\", \"brief\", \"summary\", \"counts\"]; allows_unbounded_opt_out: true; token_estimate: \"ceil(utf8_bytes / 4)\"; }[]"
+          "signature": "PmCommandOutputBudgetContract[]"
+        },
+        {
+          "classification": "contract_data",
+          "kind": "value",
+          "name": "PM_COMMAND_OUTPUT_ENVELOPE_CONTRACTS",
+          "signature": "PmCommandOutputEnvelopeContract[]"
         },
         {
           "classification": "advanced_export",
@@ -7688,6 +7792,12 @@
           "name": "PM_ERROR_CODE_CATALOG",
           "signature": "readonly PmErrorCodeContract[]"
         },
+        {
+          "classification": "contract_data",
+          "kind": "value",
+          "name": "PM_ERROR_CODE_EXIT_CLASS_CONTRACTS",
+          "signature": "readonly [{ readonly exit_code: 1; readonly class: \"generic_failure\"; }, { readonly exit_code: 2; readonly class: \"usage\"; }, { readonly exit_code: 3; readonly class: \"not_found\"; }, { readonly exit_code: 4; readonly class: \"conflict\"; }, { readonly exit_code: 5; readonly class: \"dependency_failed\"; }]"
+        },
         {
           "classification": "contract_data",
           "kind": "value",
@@ -7796,6 +7906,12 @@
           "name": "PM_OUTPUT_DEGRADATION_STEPS",
           "signature": "readonly [\"full\", \"compact\", \"brief\", \"summary\", \"counts\"]"
         },
+        {
+          "classification": "contract_data",
+          "kind": "value",
+          "name": "PM_OUTPUT_ENVELOPE_KINDS",
+          "signature": "readonly [\"mutation_receipt\", \"entity\", \"collection\", \"diagnostic\", \"stream\"]"
+        },
         {
           "classification": "supported",
           "kind": "value",
@@ -8000,6 +8116,12 @@
           "name": "PmCliExpectedError",
           "signature": "export interface PmCliExpectedError extends Error { name: typeof PM_CLI_EXPECTED_ERROR_NAME; exitCode: number; context: PmCliErrorContext; cause?: unknown; }"
         },
+        {
+          "classification": "contract_data",
+          "kind": "interface",
+          "name": "PmCliMutationReceipt",
+          "signature": "export interface PmCliMutationReceipt { id: string; status: string; changed_field_count: number; close_reason?: string; deleted?: boolean; previous_status?: string; warnings?: readonly unknown[]; }"
+        },
         {
           "classification": "contract_data",
           "kind": "type",
@@ -8016,7 +8138,13 @@
           "classification": "contract_data",
           "kind": "interface",
           "name": "PmCommandOutputBudgetContract",
-          "signature": "export interface PmCommandOutputBudgetContract { command: (typeof PM_CORE_COMMAND_NAMES)[number]; budget_class: PmOutputBudgetClass; default_max_estimated_tokens: number; degradation_ladder: readonly PmOutputDegradationStep[]; allows_unbounded_opt_out: boolean; token_estimate: \"ceil(utf8_bytes / 4)\"; }"
+          "signature": "export interface PmCommandOutputBudgetContract { command: string; budget_class: PmOutputBudgetClass; default_max_estimated_tokens: number; default_max_estimated_tokens_by_format: Readonly<{ toon: number; json: number; }>; degradation_ladder: readonly PmOutputDegradationStep[]; allows_unbounded_opt_out: boolean; token_estimate: \"ceil(utf8_bytes / 4)\"; }"
+        },
+        {
+          "classification": "contract_data",
+          "kind": "interface",
+          "name": "PmCommandOutputEnvelopeContract",
+          "signature": "export interface PmCommandOutputEnvelopeContract { command: string; kind: PmOutputEnvelopeKind; wrapper_key: string | null; cardinality: \"one\" | \"many\" | \"none\"; format_flag: \"--json\"; }"
         },
         {
           "classification": "advanced_export",
@@ -8078,11 +8206,17 @@
           "name": "PmCreateActionOptions",
           "signature": "export type PmCreateActionOptions = DeclaredProperties<CreateCommandOptions>;"
         },
+        {
+          "classification": "contract_data",
+          "kind": "type",
+          "name": "PmErrorCodeClass",
+          "signature": "export type PmErrorCodeClass = \"generic_failure\" | \"usage\" | \"not_found\" | \"conflict\" | \"dependency_failed\";"
+        },
         {
           "classification": "contract_data",
           "kind": "interface",
           "name": "PmErrorCodeContract",
-          "signature": "export interface PmErrorCodeContract { code: string; meaning: string; stability: PmErrorCodeStability; exit_code: 1 | 2 | 3 | 4 | 5; recovery: string; sources: string[]; }"
+          "signature": "export interface PmErrorCodeContract { code: string; meaning: string; stability: PmErrorCodeStability; exit_code: 1 | 2 | 3 | 4 | 5; class: PmErrorCodeClass; recovery: string; sources: string[]; emitting_commands: string[]; }"
         },
         {
           "classification": "contract_data",
@@ -8156,6 +8290,12 @@
           "name": "PmMutationAttributionOptions",
           "signature": "export type PmMutationAttributionOptions = { author?: string; message?: string; force?: boolean; };"
         },
+        {
+          "classification": "contract_data",
+          "kind": "interface",
+          "name": "PmMutationReceipt",
+          "signature": "export interface PmMutationReceipt { id: string; status: string; changedFieldCount: number; closeReason?: string; deleted?: boolean; previousStatus?: string; warnings?: readonly unknown[]; }"
+        },
         {
           "classification": "contract_data",
           "kind": "type",
@@ -8174,6 +8314,12 @@
           "name": "PmOutputDegradationStep",
           "signature": "export type PmOutputDegradationStep = (typeof PM_OUTPUT_DEGRADATION_STEPS)[number];"
         },
+        {
+          "classification": "contract_data",
+          "kind": "type",
+          "name": "PmOutputEnvelopeKind",
+          "signature": "export type PmOutputEnvelopeKind = (typeof PM_OUTPUT_ENVELOPE_KINDS)[number];"
+        },
         {
           "classification": "contract_data",
           "kind": "interface",
@@ -9854,6 +10000,12 @@
           "name": "requireTerminalReason",
           "signature": "(input: TerminalReasonInput, required: boolean) => TerminalReasonResolution | calls: (input: TerminalReasonInput, required: boolean) => TerminalReasonResolution"
         },
+        {
+          "classification": "advanced_export",
+          "kind": "function",
+          "name": "requireTerminalReasonWithRecovery",
+          "signature": "(input: TerminalReasonInput, required: boolean, recovery: TerminalReasonRecoveryContext) => TerminalReasonResolution | calls: (input: TerminalReasonInput, required: boolean, recovery: TerminalReasonRecoveryContext) => TerminalReasonResolution"
+        },
         {
           "classification": "supported",
           "kind": "value",
@@ -9992,6 +10144,12 @@
           "name": "ResolvedCompletionTimestamp",
           "signature": "export interface ResolvedCompletionTimestamp { resolved: true; timestamp: string; source: CompletionTimestampSource; fallback: boolean; }"
         },
+        {
+          "classification": "advanced_export",
+          "kind": "interface",
+          "name": "ResolvedItemMutationDocument",
+          "signature": "export interface ResolvedItemMutationDocument { schema_version: 1; mutations: BulkItemMutation[]; references: Record<string, string>; }"
+        },
         {
           "classification": "advanced_export",
           "kind": "interface",
@@ -10070,6 +10228,18 @@
           "name": "resolveItemBlockers",
           "signature": "(item: Pick<ItemMetadata, \"blocked_by\" | \"dependencies\">, itemsById: Map<string, ItemMetadata>, statusRegistry: RuntimeStatusRegistry) => ResolvedBlocker[] | calls: (item: Pick<ItemMetadata, \"blocked_by\" | \"dependencies\">, itemsById: Map<string, ItemMetadata>, statusRegistry: RuntimeStatusRegistry) => ResolvedBlocker[]"
         },
+        {
+          "classification": "advanced_export",
+          "kind": "function",
+          "name": "resolveItemMutationDocument",
+          "signature": "(input: string, options: ResolveItemMutationDocumentOptions) => ResolvedItemMutationDocument | calls: (input: string, options: ResolveItemMutationDocumentOptions) => ResolvedItemMutationDocument"
+        },
+        {
+          "classification": "advanced_export",
+          "kind": "interface",
+          "name": "ResolveItemMutationDocumentOptions",
+          "signature": "export interface ResolveItemMutationDocumentOptions { transactionId: string; idPrefix: string; }"
+        },
         {
           "classification": "advanced_export",
           "kind": "function",
@@ -10122,7 +10292,13 @@
           "classification": "contract_data",
           "kind": "function",
           "name": "resolvePmCommandOutputBudget",
-          "signature": "(command: string) => PmCommandOutputBudgetContract | null | calls: (command: string) => PmCommandOutputBudgetContract | null"
+          "signature": "{ (command: string, options: { generateFallback: true; }): PmCommandOutputBudgetContract; (command: string, options?: { generateFallback?: false; }): PmCommandOutputBudgetContract | null; } | calls: (command: string, options: { generateFallback: true; }) => PmCommandOutputBudgetContract ; (command: string, options?: { generateFallback?: false; }) => PmCommandOutputBudgetContract | null"
+        },
+        {
+          "classification": "contract_data",
+          "kind": "function",
+          "name": "resolvePmCommandOutputEnvelope",
+          "signature": "(command: string) => PmCommandOutputEnvelopeContract | calls: (command: string) => PmCommandOutputEnvelopeContract"
         },
         {
           "classification": "advanced_export",
@@ -12326,6 +12502,12 @@
           "name": "TerminalReasonInput",
           "signature": "export interface TerminalReasonInput { explicit?: string; duplicateOf?: string; resolution?: string; message?: string; }"
         },
+        {
+          "classification": "advanced_export",
+          "kind": "interface",
+          "name": "TerminalReasonRecoveryContext",
+          "signature": "export interface TerminalReasonRecoveryContext { operation: \"close\" | \"create\"; status?: string; }"
+        },
         {
           "classification": "advanced_export",
           "kind": "interface",
@@ -14924,6 +15106,12 @@
           "name": "CREATE_FLAG_CONTRACTS",
           "signature": "CliFlagContract[]"
         },
+        {
+          "classification": "contract_data",
+          "kind": "function",
+          "name": "createPmCommandOutputBudget",
+          "signature": "(command: string, budgetClass?: PmOutputBudgetClass) => PmCommandOutputBudgetContract | calls: (command: string, budgetClass?: PmOutputBudgetClass) => PmCommandOutputBudgetContract"
+        },
         {
           "classification": "contract_data",
           "kind": "function",
@@ -14936,6 +15124,12 @@
           "name": "definePmCommandOutputBudget",
           "signature": "<TContract extends PmCommandOutputBudgetContract>(contract: TContract) => TContract | calls: <TContract extends PmCommandOutputBudgetContract>(contract: TContract) => TContract"
         },
+        {
+          "classification": "contract_data",
+          "kind": "function",
+          "name": "definePmCommandOutputEnvelope",
+          "signature": "<TContract extends PmCommandOutputEnvelopeContract>(contract: TContract) => TContract | calls: <TContract extends PmCommandOutputEnvelopeContract>(contract: TContract) => TContract"
+        },
         {
           "classification": "contract_data",
           "kind": "function",
@@ -15188,6 +15382,12 @@
           "name": "HISTORY_REPAIR_FLAG_CONTRACTS",
           "signature": "CliFlagContract[]"
         },
+        {
+          "classification": "contract_data",
+          "kind": "function",
+          "name": "inferPmOutputBudgetClass",
+          "signature": "(command: string) => PmOutputBudgetClass | calls: (command: string) => PmOutputBudgetClass"
+        },
         {
           "classification": "contract_data",
           "kind": "value",
@@ -15224,6 +15424,12 @@
           "name": "isPmExtensionServiceNameContract",
           "signature": "(value: string) => value is PmExtensionServiceNameContract | calls: (value: string) => value is PmExtensionServiceNameContract"
         },
+        {
+          "classification": "contract_data",
+          "kind": "function",
+          "name": "isPmMutationReceipt",
+          "signature": "(value: unknown) => value is PmCliMutationReceipt | calls: (value: unknown) => value is PmCliMutationReceipt"
+        },
         {
           "classification": "contract_data",
           "kind": "function",
@@ -15236,6 +15442,12 @@
           "name": "isReadOutputBudgetExceeded",
           "signature": "(result: unknown) => result is PmReadOutputBudgetExceeded | calls: (result: unknown) => result is PmReadOutputBudgetExceeded"
         },
+        {
+          "classification": "contract_data",
+          "kind": "value",
+          "name": "ITEM_COMPLETE_FLAG_CONTRACTS",
+          "signature": "CliFlagContract[]"
+        },
         {
           "classification": "contract_data",
           "kind": "value",
@@ -15308,6 +15520,12 @@
           "name": "PACKAGE_INIT_FLAG_CONTRACTS",
           "signature": "CliFlagContract[]"
         },
+        {
+          "classification": "contract_data",
+          "kind": "function",
+          "name": "parseMutationReceipt",
+          "signature": "{ (json: string): PmMutationReceipt; (value: unknown): PmMutationReceipt; } | calls: (json: string) => PmMutationReceipt ; (value: unknown) => PmMutationReceipt"
+        },
         {
           "classification": "contract_data",
           "kind": "value",
@@ -15336,7 +15554,13 @@
           "classification": "contract_data",
           "kind": "value",
           "name": "PM_COMMAND_OUTPUT_BUDGET_CONTRACTS",
-          "signature": "{ command: \"activity\" | \"aggregate\" | \"append\" | \"claim\" | \"close-many\" | \"close-task\" | \"close\" | \"comments\" | \"config\" | \"context\" | \"contracts\" | \"copy\" | \"create\" | \"ctx\" | \"delete\" | \"deps\" | \"docs\" | \"duplicates\" | \"eval\" | \"event\" | \"events\" | \"extension\" | \"files\" | \"focus\" | \"gc\" | \"get\" | \"graph\" | \"health\" | \"help\" | \"history-author-acknowledge\" | \"history-compact\" | \"history-redact\" | \"history-repair\" | \"history\" | \"init\" | \"install\" | \"item\" | \"learnings\" | \"list-all\" | \"list-blocked\" | \"list-canceled\" | \"list-closed\" | \"list-draft\" | \"list-in-progress\" | \"list-open\" | \"list\" | \"meet\" | \"merge\" | \"next\" | \"notes\" | \"package\" | \"packages\" | \"pause-task\" | \"plan\" | \"profile\" | \"release\" | \"remind\" | \"restore\" | \"schema\" | \"search\" | \"start-task\" | \"stats\" | \"telemetry\" | \"test-all\" | \"test\" | \"update-many\" | \"update\" | \"upgrade\" | \"validate\" | \"workspace\"; budget_class: \"discovery\" | \"governance\" | \"mutation\" | \"read\"; default_max_estimated_tokens: number; degradation_ladder: readonly [\"full\", \"compact\", \"brief\", \"summary\", \"counts\"]; allows_unbounded_opt_out: true; token_estimate: \"ceil(utf8_bytes / 4)\"; }[]"
+          "signature": "PmCommandOutputBudgetContract[]"
+        },
+        {
+          "classification": "contract_data",
+          "kind": "value",
+          "name": "PM_COMMAND_OUTPUT_ENVELOPE_CONTRACTS",
+          "signature": "PmCommandOutputEnvelopeContract[]"
         },
         {
           "classification": "contract_data",
@@ -15356,6 +15580,12 @@
           "name": "PM_ERROR_CODE_CATALOG",
           "signature": "readonly PmErrorCodeContract[]"
         },
+        {
+          "classification": "contract_data",
+          "kind": "value",
+          "name": "PM_ERROR_CODE_EXIT_CLASS_CONTRACTS",
+          "signature": "readonly [{ readonly exit_code: 1; readonly class: \"generic_failure\"; }, { readonly exit_code: 2; readonly class: \"usage\"; }, { readonly exit_code: 3; readonly class: \"not_found\"; }, { readonly exit_code: 4; readonly class: \"conflict\"; }, { readonly exit_code: 5; readonly class: \"dependency_failed\"; }]"
+        },
         {
           "classification": "contract_data",
           "kind": "value",
@@ -15410,6 +15640,12 @@
           "name": "PM_OUTPUT_DEGRADATION_STEPS",
           "signature": "readonly [\"full\", \"compact\", \"brief\", \"summary\", \"counts\"]"
         },
+        {
+          "classification": "contract_data",
+          "kind": "value",
+          "name": "PM_OUTPUT_ENVELOPE_KINDS",
+          "signature": "readonly [\"mutation_receipt\", \"entity\", \"collection\", \"diagnostic\", \"stream\"]"
+        },
         {
           "classification": "contract_data",
           "kind": "value",
@@ -15506,6 +15742,12 @@
           "name": "PmBulkMutationFilterOptions",
           "signature": "export type PmBulkMutationFilterOptions = OptionsFromContracts<typeof TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE>;"
         },
+        {
+          "classification": "contract_data",
+          "kind": "interface",
+          "name": "PmCliMutationReceipt",
+          "signature": "export interface PmCliMutationReceipt { id: string; status: string; changed_field_count: number; close_reason?: string; deleted?: boolean; previous_status?: string; warnings?: readonly unknown[]; }"
+        },
         {
           "classification": "contract_data",
           "kind": "type",
@@ -15522,7 +15764,13 @@
           "classification": "contract_data",
           "kind": "interface",
           "name": "PmCommandOutputBudgetContract",
-          "signature": "export interface PmCommandOutputBudgetContract { command: (typeof PM_CORE_COMMAND_NAMES)[number]; budget_class: PmOutputBudgetClass; default_max_estimated_tokens: number; degradation_ladder: readonly PmOutputDegradationStep[]; allows_unbounded_opt_out: boolean; token_estimate: \"ceil(utf8_bytes / 4)\"; }"
+          "signature": "export interface PmCommandOutputBudgetContract { command: string; budget_class: PmOutputBudgetClass; default_max_estimated_tokens: number; default_max_estimated_tokens_by_format: Readonly<{ toon: number; json: number; }>; degradation_ladder: readonly PmOutputDegradationStep[]; allows_unbounded_opt_out: boolean; token_estimate: \"ceil(utf8_bytes / 4)\"; }"
+        },
+        {
+          "classification": "contract_data",
+          "kind": "interface",
+          "name": "PmCommandOutputEnvelopeContract",
+          "signature": "export interface PmCommandOutputEnvelopeContract { command: string; kind: PmOutputEnvelopeKind; wrapper_key: string | null; cardinality: \"one\" | \"many\" | \"none\"; format_flag: \"--json\"; }"
         },
         {
           "classification": "contract_data",
@@ -15560,11 +15808,17 @@
           "name": "PmCreateActionOptions",
           "signature": "export type PmCreateActionOptions = DeclaredProperties<CreateCommandOptions>;"
         },
+        {
+          "classification": "contract_data",
+          "kind": "type",
+          "name": "PmErrorCodeClass",
+          "signature": "export type PmErrorCodeClass = \"generic_failure\" | \"usage\" | \"not_found\" | \"conflict\" | \"dependency_failed\";"
+        },
         {
           "classification": "contract_data",
           "kind": "interface",
           "name": "PmErrorCodeContract",
-          "signature": "export interface PmErrorCodeContract { code: string; meaning: string; stability: PmErrorCodeStability; exit_code: 1 | 2 | 3 | 4 | 5; recovery: string; sources: string[]; }"
+          "signature": "export interface PmErrorCodeContract { code: string; meaning: string; stability: PmErrorCodeStability; exit_code: 1 | 2 | 3 | 4 | 5; class: PmErrorCodeClass; recovery: string; sources: string[]; emitting_commands: string[]; }"
         },
         {
           "classification": "contract_data",
@@ -15614,6 +15868,12 @@
           "name": "PmMutationAttributionOptions",
           "signature": "export type PmMutationAttributionOptions = { author?: string; message?: string; force?: boolean; };"
         },
+        {
+          "classification": "contract_data",
+          "kind": "interface",
+          "name": "PmMutationReceipt",
+          "signature": "export interface PmMutationReceipt { id: string; status: string; changedFieldCount: number; closeReason?: string; deleted?: boolean; previousStatus?: string; warnings?: readonly unknown[]; }"
+        },
         {
           "classification": "contract_data",
           "kind": "type",
@@ -15632,6 +15892,12 @@
           "name": "PmOutputDegradationStep",
           "signature": "export type PmOutputDegradationStep = (typeof PM_OUTPUT_DEGRADATION_STEPS)[number];"
         },
+        {
+          "classification": "contract_data",
+          "kind": "type",
+          "name": "PmOutputEnvelopeKind",
+          "signature": "export type PmOutputEnvelopeKind = (typeof PM_OUTPUT_ENVELOPE_KINDS)[number];"
+        },
         {
           "classification": "contract_data",
           "kind": "interface",
@@ -15810,7 +16076,13 @@
           "classification": "contract_data",
           "kind": "function",
           "name": "resolvePmCommandOutputBudget",
-          "signature": "(command: string) => PmCommandOutputBudgetContract | null | calls: (command: string) => PmCommandOutputBudgetContract | null"
+          "signature": "{ (command: string, options: { generateFallback: true; }): PmCommandOutputBudgetContract; (command: string, options?: { generateFallback?: false; }): PmCommandOutputBudgetContract | null; } | calls: (command: string, options: { generateFallback: true; }) => PmCommandOutputBudgetContract ; (command: string, options?: { generateFallback?: false; }) => PmCommandOutputBudgetContract | null"
+        },
+        {
+          "classification": "contract_data",
+          "kind": "function",
+          "name": "resolvePmCommandOutputEnvelope",
+          "signature": "(command: string) => PmCommandOutputEnvelopeContract | calls: (command: string) => PmCommandOutputEnvelopeContract"
         },
         {
           "classification": "contract_data",
@@ -20940,7 +21212,7 @@
           "classification": "advanced_export",
           "kind": "interface",
           "name": "ContractsResult",
-          "signature": "export interface ContractsResult { schema_version: string | null; schema_id: string | null; selected: { action: string | null; command: string | null; summary: boolean; schema_only: boolean; flags_only: boolean; availability_only: boolean; runtime_only: boolean; command_scoped: boolean; }; actions?: string[]; action_availability?: ContractsActionAvailability[]; commands: string[]; schema?: Record<string, unknown>; schema_omitted_reason?: string; command_flags_omitted_reason?: string; commander_aliases_omitted_reason?: string; command_flags?: CommandFlagSurface[]; list_projections?: ListCommandProjectionSurface[]; command_aliases?: CommandAliasSurface[]; commander_aliases?: Record<string, CommanderOptionAliasContract[]>; extension_commands?: ExtensionCommandContract[]; command_summaries?: CommandSummarySurface[]; output_policy?: { token_estimate: \"ceil(utf8_bytes / 4)\"; degradation_ladder: string[]; allows_unbounded_opt_out: boolean; }; runtime_schema?: { statuses: string[]; open_status: string; close_status: string; canceled_status: string; types: string[]; fields_by_command: Record<string, string[]>; }; extension_contracts?: { capabilities: string[]; services: string[]; policy_modes: string[]; policy_mode_scope: \"extensions.policy.mode\"; policy_surfaces: string[]; trust_modes: string[]; trust_mode_scope: \"extensions.policy.trust_mode\"; sandbox_profiles: string[]; manifest_versions: number[]; compatibility: { current: string; previous: string[]; breaking_strategy: string; }; }; governance_contracts?: { ownership_enforcement_modes: string[]; create_modes: string[]; close_validation_modes: string[]; workflow_enforcement_modes: string[]; }; mcp_tools?: McpToolContract[]; context_intents?: readonly PmContextIntentContract[]; read_output_dimensions?: readonly PmReadOutputSurfaceContract[]; error_codes?: readonly PmErrorCodeContract[]; }"
+          "signature": "export interface ContractsResult { schema_version: string | null; schema_id: string | null; selected: { action: string | null; command: string | null; summary: boolean; schema_only: boolean; flags_only: boolean; availability_only: boolean; runtime_only: boolean; command_scoped: boolean; }; actions?: string[]; action_availability?: ContractsActionAvailability[]; commands: string[]; schema?: Record<string, unknown>; schema_omitted_reason?: string; command_flags_omitted_reason?: string; commander_aliases_omitted_reason?: string; command_flags?: CommandFlagSurface[]; list_projections?: ListCommandProjectionSurface[]; command_aliases?: CommandAliasSurface[]; commander_aliases?: Record<string, CommanderOptionAliasContract[]>; extension_commands?: ExtensionCommandContract[]; command_summaries?: CommandSummarySurface[]; output_policy?: { token_estimate: \"ceil(utf8_bytes / 4)\"; degradation_ladder: string[]; allows_unbounded_opt_out: boolean; }; runtime_schema?: { statuses: string[]; open_status: string; close_status: string; canceled_status: string; types: string[]; fields_by_command: Record<string, string[]>; }; extension_contracts?: { capabilities: string[]; services: string[]; policy_modes: string[]; policy_mode_scope: \"extensions.policy.mode\"; policy_surfaces: string[]; trust_modes: string[]; trust_mode_scope: \"extensions.policy.trust_mode\"; sandbox_profiles: string[]; manifest_versions: number[]; compatibility: { current: string; previous: string[]; breaking_strategy: string; }; }; governance_contracts?: { ownership_enforcement_modes: string[]; create_modes: string[]; close_validation_modes: string[]; workflow_enforcement_modes: string[]; }; mcp_tools?: McpToolContract[]; context_intents?: readonly PmContextIntentContract[]; read_output_dimensions?: readonly PmReadOutputSurfaceContract[]; error_codes?: readonly PmErrorCodeContract[]; command_output_contracts?: Array<{ budget: PmCommandOutputBudgetContract; envelope: PmCommandOutputEnvelopeContract; }>; }"
         },
         {
           "classification": "supported",
@@ -21990,7 +22262,7 @@
           "classification": "contract_data",
           "kind": "interface",
           "name": "PmErrorCodeContract",
-          "signature": "export interface PmErrorCodeContract { code: string; meaning: string; stability: PmErrorCodeStability; exit_code: 1 | 2 | 3 | 4 | 5; recovery: string; sources: string[]; }"
+          "signature": "export interface PmErrorCodeContract { code: string; meaning: string; stability: PmErrorCodeStability; exit_code: 1 | 2 | 3 | 4 | 5; class: PmErrorCodeClass; recovery: string; sources: string[]; emitting_commands: string[]; }"
         },
         {
           "classification": "supported",
@@ -23822,6 +24094,7 @@
     "history_target_out_of_range",
     "history_unknown_author_events",
     "init_existing_settings_requires_force",
+    "init_gitignore_unwritable",
     "init_id_prefix_conflict",
     "init_id_prefix_path_like",
     "integrity_history_conflict_marker",
@@ -23840,6 +24113,7 @@
     "invalid_event_since",
     "invalid_provenance_predicate",
     "invalid_query_cursor",
+    "invalid_workspace_snapshot_target",
     "item_document_invalid",
     "item_document_roundtrip_failed",
     "item_id_collision",
@@ -23972,6 +24246,10 @@
     "workflow_type_unknown",
     "workspace_history_state_conflict",
     "workspace_root_pm_path",
+    "workspace_snapshot_force_required",
+    "workspace_snapshot_manifest_mismatch",
+    "workspace_snapshot_name_reserved_fingerprint",
+    "workspace_snapshot_not_found",
     "wrong_item_type"
   ],
   "package": "@unbrained/pm-cli",