@unbrained/pm-cli 2026.10.11 → 2026.10.13

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

@@ -1,3 +1,10 @@
+/**
+ * @module sdk/read-output-contracts
+ *
+ * Declares and applies one output-bounding vocabulary to every built-in read
+ * surface without coupling package authors to command-specific option names.
+ */
+import { PM_READ_OUTPUT_SURFACES } from "./read-output/options.js";
 export { resolveReadOutputRecoveryBudget } from "./read-output-budget.js";
 export type { PmReadOutputRecoveryBudget, PmReadOutputRecoveryBudgetInput, } from "./read-output-budget.js";
 export { decodeReadOutputContinuationCursor, encodeReadOutputContinuationCursor, PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES, readOutputCollectionFingerprint, } from "./read-output/continuation.js";
@@ -7,228 +14,227 @@ import { type PmReadOutputSessionReceipt, type PmReadOutputSessionState } from "
 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", "duplicates", "package-catalog", "package-manage", "comments-audit", "assurance"];
-/** Built-in read command supported by the universal output contract. */
-export type PmReadOutputSurface = (typeof PM_READ_OUTPUT_SURFACES)[number];
+export { PM_READ_OUTPUT_SURFACES } from "./read-output/options.js";
+/** Native or package read identity supported by the universal output contract. */
+export type PmReadOutputSurface = (typeof PM_READ_OUTPUT_SURFACES)[number] | `extension:${string}`;
 /** Canonical output controls accepted by every built-in read action. */
 export interface PmReadOutputOptions {
-    /** Comma-separated fields or sections retained in the result. */
-    outputInclude?: string | string[];
-    /** Maximum rows retained, or `unbounded` to disable the shared row ceiling. */
-    outputLimit?: string | number | "unbounded";
-    /** 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;
+/** Comma-separated fields or sections retained in the result. */
+outputInclude?: string | string[];
+/** Maximum rows retained, or `unbounded` to disable the shared row ceiling. */
+outputLimit?: string | number | "unbounded";
+/** 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;
 }
 /** Compatibility spelling retained for a command-specific output control. */
 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. */
-    visibility: "hidden_alias";
+/** 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. */
+visibility: "hidden_alias";
 }
 /** Contract for one output dimension on one read surface. */
 export interface PmReadOutputDimensionContract {
-    /** Stable dimension name. */
-    dimension: PmReadOutputDimension;
-    /** Canonical cross-command CLI option. */
-    canonical_option: string;
-    /** Whether the dimension has executable behavior on this surface. */
-    applicable: boolean;
-    /** Explanation used only when the dimension cannot apply. */
-    inapplicable_reason: string | null;
-    /** Historical command-local options mapped into this dimension. */
-    legacy_aliases: PmReadOutputLegacyAlias[];
+/** Stable dimension name. */
+dimension: PmReadOutputDimension;
+/** Canonical cross-command CLI option. */
+canonical_option: string;
+/** Whether the dimension has executable behavior on this surface. */
+applicable: boolean;
+/** Explanation used only when the dimension cannot apply. */
+inapplicable_reason: string | null;
+/** Historical command-local options mapped into this dimension. */
+legacy_aliases: PmReadOutputLegacyAlias[];
 }
 /** Complete four-dimension contract for one read surface. */
 export interface PmReadOutputSurfaceContract {
-    /** Canonical command root. */
-    command: PmReadOutputSurface;
-    /** Identical dimension keys shared by every read surface. */
-    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";
-    /** Exact command-local whole-result modes accepted by `outputInclude`. */
-    projection_modes?: readonly string[];
+/** Canonical command root. */
+command: PmReadOutputSurface;
+/** Identical dimension keys shared by every read surface. */
+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";
+/** Exact command-local whole-result modes accepted by `outputInclude`. */
+projection_modes?: readonly string[];
 }
 /** Source that selected an effective output dimension. */
 export type PmReadOutputDimensionSource = "canonical" | "legacy" | "intent" | "default";
 /** Resolved value and provenance for one dimension. */
 export interface PmResolvedReadOutputDimension<T> {
-    /** Effective value after precedence resolution. */
-    value: T;
-    /** Layer that supplied the effective value. */
-    source: PmReadOutputDimensionSource;
+/** Effective value after precedence resolution. */
+value: T;
+/** Layer that supplied the effective value. */
+source: PmReadOutputDimensionSource;
 }
 /** Fully resolved output controls for one invocation. */
 export interface PmResolvedReadOutputDimensions {
-    /** Canonical read surface. */
-    command: PmReadOutputSurface;
-    /** Requested field or section selectors. */
-    include?: PmResolvedReadOutputDimension<string[]>;
-    /** Requested row ceiling. */
-    amount?: PmResolvedReadOutputDimension<number | "unbounded">;
-    /** 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">;
-    /** Canonical CLI options observed on the invocation. */
-    canonical_options_used?: string[];
-    /** Compatibility flags observed on the invocation. */
-    legacy_aliases_used: string[];
-    /** One-line migration instructions for observed compatibility flags. */
-    migration_hints: string[];
-    /** Deterministic precedence applied to every dimension. */
-    precedence: readonly ["canonical", "legacy", "intent", "default"];
+/** Canonical read surface. */
+command: PmReadOutputSurface;
+/** Requested field or section selectors. */
+include?: PmResolvedReadOutputDimension<string[]>;
+/** Requested row ceiling. */
+amount?: PmResolvedReadOutputDimension<number | "unbounded">;
+/** 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">;
+/** Canonical CLI options observed on the invocation. */
+canonical_options_used?: string[];
+/** Compatibility flags observed on the invocation. */
+legacy_aliases_used: string[];
+/** One-line migration instructions for observed compatibility flags. */
+migration_hints: string[];
+/** Deterministic precedence applied to every dimension. */
+precedence: readonly ["canonical", "legacy", "intent", "default"];
 }
 /** Machine-readable proof of output dimensions applied to one read. */
 export interface PmReadOutputReceipt {
-    /** Contract format version. */
-    contract_version: 1;
-    /** Canonical read surface. */
-    command: PmReadOutputSurface;
-    /** Dimensions explicitly or compatibly requested by the invocation. */
-    requested_dimensions: PmReadOutputDimension[];
-    /** Layer supplying a default ceiling or the context compatibility ceiling. */
-    budget_source?: "default" | "legacy";
-    /** Applied default or context compatibility ceiling; canonical/session budgets already disclose their value. */
-    budget_tokens?: number;
-    /** Deterministic precedence used during resolution. */
-    precedence: readonly ["canonical", "legacy", "intent", "default"];
-    /** Canonical CLI options observed on the invocation. */
-    canonical_options_used?: string[];
-    /** Compatibility options observed on the invocation. */
-    legacy_aliases_used: string[];
-    /** One-line migration instructions for compatibility options. */
-    migration_hints: string[];
-    /** Deterministic UTF-8 byte token estimate of the result and receipt in the selected JSON or TOON rendering; SDK calls without a format use compact JSON. */
-    estimated_tokens: number;
-    /** Whether the final result fits the requested cost ceiling. */
-    within_budget: boolean;
-    /** Whether long string values were shortened while satisfying the cost ceiling. */
-    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;
-    /** Detail depth selected before destructive string or row compaction. */
-    applied_depth?: "brief";
-    /** Binding constraint that selected the smaller detail projection. */
-    degradation_reason?: "output_budget_reached";
+/** Contract format version. */
+contract_version: 1;
+/** Canonical read surface. */
+command: PmReadOutputSurface;
+/** Dimensions explicitly or compatibly requested by the invocation. */
+requested_dimensions: PmReadOutputDimension[];
+/** Layer supplying a default ceiling or the context compatibility ceiling. */
+budget_source?: "default" | "legacy";
+/** Applied default or context compatibility ceiling; canonical/session budgets already disclose their value. */
+budget_tokens?: number;
+/** Deterministic precedence used during resolution. */
+precedence: readonly ["canonical", "legacy", "intent", "default"];
+/** Canonical CLI options observed on the invocation. */
+canonical_options_used?: string[];
+/** Compatibility options observed on the invocation. */
+legacy_aliases_used: string[];
+/** One-line migration instructions for compatibility options. */
+migration_hints: string[];
+/** Deterministic UTF-8 byte token estimate of the result and receipt in the selected JSON or TOON rendering; SDK calls without a format use compact JSON. */
+estimated_tokens: number;
+/** Whether the final result fits the requested cost ceiling. */
+within_budget: boolean;
+/** Whether long string values were shortened while satisfying the cost ceiling. */
+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;
+/** Detail depth selected before destructive string or row compaction. */
+applied_depth?: "brief";
+/** Binding constraint that selected the smaller detail projection. */
+degradation_reason?: "output_budget_reached";
 }
 /** 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: number | null;
-    /** Bounded continuation instructions for every compacted declared row path. */
-    continuations: PmReadOutputContinuation[];
-    /** Retry guidance, or `recovery` to require the adjacent cursor and transport bindings. */
-    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 | "unbounded";
-        };
-        mcp: {
-            outputBudget: number | "unbounded";
-        };
-    };
+/** 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: number | null;
+/** Bounded continuation instructions for every compacted declared row path. */
+continuations: PmReadOutputContinuation[];
+/** Retry guidance, or `recovery` to require the adjacent cursor and transport bindings. */
+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 | "unbounded";
+};
+mcp: {
+outputBudget: number | "unbounded";
+};
+};
 }
 /** 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;
+/** 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;
+/** 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 {
-    /** Stable omission marker and recovery instruction. */
-    output_budget_exceeded: {
-        /** Confirms that the useful result was deliberately omitted. */
-        omitted_result: true;
-        /** Stable reason for machine-readable recovery. */
-        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;
+/** Stable omission marker and recovery instruction. */
+output_budget_exceeded: {
+/** Confirms that the useful result was deliberately omitted. */
+omitted_result: true;
+/** Stable reason for machine-readable recovery. */
+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;
 }
 /** Read result with an optional shaping receipt or a discriminated omission. */
 export type PmReadOutputResult<Result> = (Result & {
-    read_output?: PmReadOutputReceipt;
-    read_session?: PmReadOutputSessionReceipt;
-    output_budget_truncation?: PmReadOutputTruncationDisclosure;
+read_output?: PmReadOutputReceipt;
+read_session?: PmReadOutputSessionReceipt;
+output_budget_truncation?: PmReadOutputTruncationDisclosure;
 }) | (PmReadOutputBudgetExceeded & {
-    read_session?: PmReadOutputSessionReceipt;
+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> : "outputCursor" extends keyof Options ? PmReadOutputResult<Result> : Result;
@@ -260,8 +266,8 @@ export declare function readOutputIncludeModeOptions(command: string): ReadonlyM
  * remain for post-execution projection.
  */
 export declare function applyReadOutputIncludeModes(command: string, includeValue: unknown, commandOptions: Record<string, unknown>): {
-    selectors: string[];
-    modes: string[];
+selectors: string[];
+modes: string[];
 };
 /**
  * Resolve canonical include modes against one combined options bag, rewriting