@unbrained/pm-cli 2026.8.13 → 2026.8.15

package/dist/sdk/read-output-contracts.d.ts

@@ -1,10 +1,11 @@
+export { decodeReadOutputContinuationCursor, encodeReadOutputContinuationCursor, } from "./read-output/continuation.js";
 import { type PmReadOutputSessionReceipt, type PmReadOutputSessionState } from "./read-output-session.js";
 /** Stable output dimensions shared by every read surface. */
 export declare const PM_READ_OUTPUT_DIMENSIONS: readonly ["include", "amount", "cost", "encoding"];
 /** One member of the universal read-output dimension set. */
 export type PmReadOutputDimension = (typeof PM_READ_OUTPUT_DIMENSIONS)[number];
 /** Built-in command roots whose primary operation is a read. */
-export declare const PM_READ_OUTPUT_SURFACES: readonly ["list", "context", "search", "get", "next", "health", "deps", "graph", "history", "activity", "validate", "events", "contracts", "comments", "notes", "files", "docs", "stats", "aggregate", "package-manage"];
+export declare const PM_READ_OUTPUT_SURFACES: readonly ["list", "context", "search", "get", "next", "health", "deps", "graph", "history", "activity", "validate", "events", "contracts", "comments", "notes", "files", "docs", "stats", "aggregate", "package-manage", "comments-audit", "assurance"];
 /** Built-in read command supported by the universal output contract. */
 export type PmReadOutputSurface = (typeof PM_READ_OUTPUT_SURFACES)[number];
 /** Canonical output controls accepted by every built-in read action. */
@@ -13,12 +14,14 @@ export interface PmReadOutputOptions {
     outputInclude?: string | string[];
     /** Maximum rows retained, or `unbounded` to disable the shared row ceiling. */
     outputLimit?: string | number | "unbounded";
-    /** Maximum estimated result tokens. */
-    outputBudget?: string | number;
+    /** Maximum estimated result tokens, or `unbounded` to disable the default ceiling. */
+    outputBudget?: string | number | "unbounded";
     /** Requested static renderer encoding; streaming remains a command behavior. */
     outputFormat?: "json" | "toon";
     /** Caller-carried cross-call budget and served-fact state. */
     outputSession?: string | PmReadOutputSessionState;
+    /** Opaque continuation returned after a budget-compacted declared row path. */
+    outputCursor?: string;
     /** Include row selector and encoding discovery metadata. */
     outputRowContract?: boolean;
 }
@@ -26,6 +29,8 @@ export interface PmReadOutputOptions {
 export interface PmReadOutputLegacyAlias {
     /** Historical CLI spelling. */
     flag: string;
+    /** Strength of the migration promise carried by this alias. */
+    semantics?: "replacement" | "behavior_preserving";
     /** One-line migration instruction for agents and help generators. */
     migration_hint: string;
     /** Compatibility aliases are accepted but omitted from the canonical vocabulary. */
@@ -52,6 +57,8 @@ export interface PmReadOutputSurfaceContract {
     dimensions: Record<PmReadOutputDimension, PmReadOutputDimensionContract>;
     /** Deterministic precedence from strongest caller declaration to fallback. */
     precedence: readonly ["canonical", "legacy", "intent", "default"];
+    /** Stable policy used before budget compaction selects retained rows. */
+    budget_retention_policy: "ordered_prefix" | "verdict_priority";
 }
 /** Source that selected an effective output dimension. */
 export type PmReadOutputDimensionSource = "canonical" | "legacy" | "intent" | "default";
@@ -70,8 +77,8 @@ export interface PmResolvedReadOutputDimensions {
     include?: PmResolvedReadOutputDimension<string[]>;
     /** Requested row ceiling. */
     amount?: PmResolvedReadOutputDimension<number | "unbounded">;
-    /** Requested estimated-token ceiling. */
-    cost?: PmResolvedReadOutputDimension<number>;
+    /** Requested estimated-token ceiling or explicit opt-out. */
+    cost?: PmResolvedReadOutputDimension<number | "unbounded">;
     /** Requested static encoding or a retained legacy streaming behavior. */
     encoding?: PmResolvedReadOutputDimension<"json" | "toon" | "stream">;
     /** Compatibility flags observed on the invocation. */
@@ -89,6 +96,10 @@ export interface PmReadOutputReceipt {
     command: PmReadOutputSurface;
     /** Dimensions explicitly or compatibly requested by the invocation. */
     requested_dimensions: PmReadOutputDimension[];
+    /** Layer that supplied an automatically applied token ceiling. */
+    budget_source?: "default";
+    /** Automatically applied token ceiling; explicit/session budgets already disclose their value. */
+    budget_tokens?: number;
     /** Deterministic precedence used during resolution. */
     precedence: readonly ["canonical", "legacy", "intent", "default"];
     /** Compatibility options observed on the invocation. */
@@ -103,8 +114,82 @@ export interface PmReadOutputReceipt {
     strings_compacted: boolean;
     /** Whether row collections were reduced while satisfying the cost ceiling. */
     rows_compacted: boolean;
+    /** Declared or nested collection paths reduced by budget degradation. */
+    compacted_row_paths?: string[];
     /** Whether the requested cost ceiling forced the useful result to be omitted. */
     result_omitted: boolean;
+    /** Estimated tokens in the useful result immediately before whole-result omission. */
+    omitted_result_estimated_tokens?: number;
+}
+/** Machine-readable explanation of budget-driven row degradation. */
+export interface PmReadOutputTruncationDisclosure {
+    /** Stable reason for dropping rows. */
+    reason: "output_budget_reached";
+    /** Layer that supplied the binding ceiling. */
+    budget_source: PmReadOutputDimensionSource | "session";
+    /** Binding estimated-token ceiling. */
+    budget_tokens: number;
+    /** Explicit dimensions whose unbounded request was overridden by the ceiling. */
+    overridden_dimensions: PmReadOutputDimension[];
+    /** Declared or nested collection paths reduced by budget degradation. */
+    compacted_row_paths: string[];
+    /** Whether next_cursor was moved back to the last row that survived compaction. */
+    continuation_cursor_rebased: boolean;
+    /** Whether at least one declared row collection can be resumed within the budget. */
+    continuation_available: boolean;
+    /** Maximum next-page useful-result budget relative to the current budget. */
+    recovery_budget_multiplier: 1;
+    /** Bounded continuation instructions for every compacted declared row path. */
+    continuations: PmReadOutputContinuation[];
+    /** Executable recovery instruction for retrieving the complete result. */
+    restore_with: string;
+    /** Transport-specific machine recovery options. */
+    recovery: {
+        /** Opaque value supplied through each declared transport binding. */
+        cursor: string;
+        /** CLI option accepting cursor. */
+        cli: "--output-cursor";
+        /** SDK option field accepting cursor. */
+        sdk: "outputCursor";
+        /** MCP input field accepting cursor. */
+        mcp: "outputCursor";
+    } | {
+        cli: string;
+        sdk: {
+            outputBudget: number;
+        };
+        mcp: {
+            outputBudget: number;
+        };
+    };
+}
+/** One resumable declared-row collection withheld by budget compaction. */
+export interface PmReadOutputContinuation {
+    /** Dot-delimited declared row path being resumed. */
+    path: string;
+    /** Opaque cursor accepted by CLI, SDK, and MCP outputCursor inputs. */
+    cursor: string;
+    /** Rows retained from this path in the current response. */
+    retained_rows: number;
+    /** Rows remaining after the current response. */
+    remaining_rows: number;
+    /** Total rows in the stable collection snapshot. */
+    total_rows: number;
+}
+/** Versioned, command-bound cursor payload for one stable declared row collection. */
+export interface PmReadOutputCursorEnvelope {
+    /** Serialized cursor format version. */
+    version: 1;
+    /** Canonical read surface that produced the cursor. */
+    command: PmReadOutputSurface;
+    /** Dot-delimited declared row path being continued. */
+    path: string;
+    /** Zero-based index of the first withheld row. */
+    offset: number;
+    /** Stable pre-projection denominator for the row collection. */
+    total_rows: number;
+    /** Stable identity fingerprint used to refuse stale continuation. */
+    fingerprint: string;
 }
 /** Result returned when the requested cost ceiling cannot fit useful content. */
 export interface PmReadOutputBudgetExceeded {
@@ -116,6 +201,10 @@ export interface PmReadOutputBudgetExceeded {
         reason: "requested_budget_infeasible";
         /** Human- and agent-readable recovery instruction. */
         restore_with: string;
+        /** Transport-specific machine recovery options. */
+        recovery: {
+            outputBudget: "unbounded";
+        };
     };
     /** Exact receipt for the bounded omission envelope. */
     read_output: PmReadOutputReceipt;
@@ -124,21 +213,52 @@ export interface PmReadOutputBudgetExceeded {
 export type PmReadOutputResult<Result> = (Result & {
     read_output?: PmReadOutputReceipt;
     read_session?: PmReadOutputSessionReceipt;
+    output_budget_truncation?: PmReadOutputTruncationDisclosure;
 }) | (PmReadOutputBudgetExceeded & {
     read_session?: PmReadOutputSessionReceipt;
 });
 /** Select the omission-aware result type when an option shape can request a budget. */
-export type PmReadOutputResultFor<Result, Options> = "outputBudget" extends keyof Options ? PmReadOutputResult<Result> : "outputSession" extends keyof Options ? PmReadOutputResult<Result> : Result;
+export type PmReadOutputResultFor<Result, Options> = "outputBudget" extends keyof Options ? PmReadOutputResult<Result> : "outputSession" extends keyof Options ? PmReadOutputResult<Result> : "outputCursor" extends keyof Options ? PmReadOutputResult<Result> : Result;
 /** Canonical CLI flags that opt a read invocation into universal output shaping. */
 export declare const PM_READ_OUTPUT_OPTION_FLAGS: readonly string[];
 /** Canonical control that composes the four per-call dimensions across reads. */
-export declare const PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS: readonly ["--output-session", "--output-row-contract"];
+export declare const PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS: readonly ["--output-session", "--output-cursor", "--output-row-contract"];
 /** Universal output contract for every built-in read surface. */
 export declare const PM_READ_OUTPUT_SURFACE_CONTRACTS: readonly PmReadOutputSurfaceContract[];
 /** Resolve a command or list/context alias to its canonical read-output surface. */
 export declare function resolveReadOutputSurface(command: string): PmReadOutputSurface | undefined;
 /** Reject malformed or mutation-scoped universal output controls before command execution. */
 export declare function validateReadOutputOptions(command: string, options: Record<string, unknown>): void;
+/**
+ * Map every canonical `--output-include` token that names a projection mode
+ * rather than a row field onto the command-local option that mode already owns.
+ *
+ * The include dimension folds two kinds of legacy alias into one canonical
+ * spelling: value-bearing selectors (`--fields`, `--section`) that name row
+ * fields, and mode flags (`--brief`, `--full`, `--summary`, ...) that select a
+ * whole declared projection. Only the first kind can be honoured by projecting
+ * an already-computed result, so mode tokens have to reach the command itself.
+ */
+export declare function readOutputIncludeModeOptions(command: string): ReadonlyMap<string, string>;
+/**
+ * Translate canonical projection-mode tokens into the command-local options
+ * they alias, so the spelling the migration hints recommend is behaviour
+ * identical to the legacy flag it replaces, and return the field selectors that
+ * remain for post-execution projection.
+ */
+export declare function applyReadOutputIncludeModes(command: string, includeValue: unknown, commandOptions: Record<string, unknown>): {
+    selectors: string[];
+    modes: string[];
+};
+/**
+ * Resolve canonical include modes against one combined options bag, rewriting
+ * the include value in place to the selectors that remain.
+ *
+ * Used by dispatch paths that carry command options and universal output
+ * controls in a single record, so an action honours a mode token exactly as the
+ * CLI does.
+ */
+export declare function normalizeReadOutputIncludeModeOptions(command: string, options: Record<string, unknown>): void;
 /** Resolve canonical and compatibility controls into the universal dimension set. */
 export declare function resolveReadOutputDimensions(command: string, options: Record<string, unknown>): PmResolvedReadOutputDimensions | undefined;
 /** Recompute read and optional session receipts after a final envelope projection. */