@unbrained/pm-cli 2026.8.14 → 2026.8.16

package/dist/sdk/read-output/continuation.js

@@ -0,0 +1,132 @@
+/**
+ * @module sdk/read-output/continuation
+ *
+ * Encodes, validates, and applies stable continuations for declared read-output
+ * row collections while keeping cursor mechanics separate from dimension
+ * resolution and budget policy.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8e523bbc-5745-514e-a1d8-a6ad6ece001a")}catch(e){}}();
+import { createHash } from "node:crypto";
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+import { resolveReadOutputSurface } from "../read-output-contracts.js";
+import { readOutputRowCollections, sliceReadOutputRowCollection, } from "../read-output-rows.js";
+const MAX_READ_OUTPUT_CURSOR_LENGTH = 4096;
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Fingerprint stable row identities without including volatile observation fields. */
+export function readOutputCollectionFingerprint(path, value) {
+    const identities = Array.isArray(value)
+        ? value.map((row, index) => {
+            if (!isRecord(row))
+                return `index:${String(index)}`;
+            for (const key of [
+                "id",
+                "assertion_id",
+                "measurement_id",
+                "event_id",
+            ]) {
+                const candidate = row[key];
+                if (typeof candidate === "string" && candidate.length > 0) {
+                    return `${key}:${candidate}`;
+                }
+            }
+            return `index:${String(index)}`;
+        })
+        : Object.keys(value);
+    return createHash("sha256")
+        .update(JSON.stringify({ path, identities }))
+        .digest("base64url")
+        .slice(0, 16);
+}
+/** Encode one stable declared-row continuation for CLI, SDK, and MCP callers. */
+export function encodeReadOutputContinuationCursor(cursor) {
+    return Buffer.from(JSON.stringify({
+        v: 1,
+        c: cursor.command,
+        p: cursor.path,
+        o: cursor.offset,
+        n: cursor.total_rows,
+        f: cursor.fingerprint,
+    }), "utf8").toString("base64url");
+}
+/** Decode and validate one universal declared-row continuation cursor. */
+export function decodeReadOutputContinuationCursor(raw) {
+    if (raw.length > MAX_READ_OUTPUT_CURSOR_LENGTH) {
+        throw new PmCliError("The read-output continuation cursor is malformed or unsupported.", EXIT_CODE.USAGE, { code: "read_output_cursor_invalid" });
+    }
+    let candidate;
+    try {
+        candidate = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+    }
+    catch {
+        candidate = null;
+    }
+    if (!isRecord(candidate) ||
+        candidate.v !== 1 ||
+        resolveReadOutputSurface(String(candidate.c ?? "")) !== candidate.c ||
+        typeof candidate.p !== "string" ||
+        candidate.p.length === 0 ||
+        !Number.isSafeInteger(candidate.o) ||
+        candidate.o < 0 ||
+        !Number.isSafeInteger(candidate.n) ||
+        candidate.n < 1 ||
+        typeof candidate.f !== "string" ||
+        candidate.f.length === 0) {
+        throw new PmCliError("The read-output continuation cursor is malformed or unsupported.", EXIT_CODE.USAGE, { code: "read_output_cursor_invalid" });
+    }
+    return {
+        version: 1,
+        command: candidate.c,
+        path: candidate.p,
+        offset: candidate.o,
+        total_rows: candidate.n,
+        fingerprint: candidate.f,
+    };
+}
+/** Place every non-passing assurance assertion before passing evidence. */
+export function prioritizeAssuranceAssertions(result) {
+    if (!Array.isArray(result.assertions))
+        return result;
+    const priority = (row) => {
+        if (!isRecord(row) || row.verdict === "pass")
+            return 4;
+        if (row.verdict === "retired")
+            return 3;
+        return row.enforcement === "block" ? 0 : row.enforcement === "warn" ? 1 : 2;
+    };
+    return {
+        ...result,
+        assertions: result.assertions
+            .map((row, index) => ({ row, index }))
+            .sort((left, right) => priority(left.row) - priority(right.row) || left.index - right.index)
+            .map(({ row }) => row),
+        budget_retention_policy: "verdict_priority",
+    };
+}
+/** Validate and apply a continuation suffix to its declared row collection. */
+export function applyReadOutputContinuation(result, command, cursor) {
+    if (!cursor)
+        return result;
+    if (cursor.command !== command) {
+        throw new PmCliError(`The read-output cursor belongs to ${cursor.command}, not ${command}.`, EXIT_CODE.USAGE, { code: "read_output_cursor_command_mismatch" });
+    }
+    const collection = readOutputRowCollections(result).find((entry) => entry.path === cursor.path);
+    const totalRows = collection
+        ? Array.isArray(collection.value)
+            ? collection.value.length
+            : Object.keys(collection.value).length
+        : 0;
+    if (!collection ||
+        totalRows !== cursor.total_rows ||
+        cursor.offset > totalRows ||
+        readOutputCollectionFingerprint(cursor.path, collection.value) !==
+            cursor.fingerprint) {
+        throw new PmCliError("The read-output continuation no longer matches the declared row collection; restart the bounded read.", EXIT_CODE.USAGE, { code: "read_output_cursor_stale" });
+    }
+    return sliceReadOutputRowCollection(result, cursor.path, cursor.offset);
+}
+//# sourceMappingURL=continuation.js.map
+//# debugId=8e523bbc-5745-514e-a1d8-a6ad6ece001a

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

@@ -10,4 +10,4 @@ export declare function estimateReadOutputTokens(result: unknown): number;
 /** Update a receipt to the fixed-point estimate of the result containing it. */
 export declare function updateReadOutputReceiptEstimate(result: Record<string, unknown>, receipt: PmReadOutputReceipt): void;
 /** Compact strings and rows in place, then return the final exact estimate. */
-export declare function compactReadOutputToBudget(result: Record<string, unknown>, receipt: PmReadOutputReceipt, budget: number): Record<string, unknown>;
+export declare function compactReadOutputToBudget(result: Record<string, unknown>, receipt: PmReadOutputReceipt, budget: number, minimumRowsByPath?: ReadonlyMap<string, number>): Record<string, unknown>;

package/dist/sdk/read-output-budget.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="cc595424-0176-5920-8f4c-d935e6a546ce")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="737ac274-c165-5d1a-8b8e-cb5d57a81c46")}catch(e){}}();
 import { countReadOutputRows, readOutputBudgetCollections, } from "./read-output-rows.js";
 const MAX_ESTIMATE_ITERATIONS = 8;
 const MAX_COMPACTION_ITERATIONS = 64;
@@ -42,15 +42,18 @@ export function updateReadOutputReceiptEstimate(result, receipt) {
     receipt.estimated_tokens = estimate;
 }
 /** Reduce the largest row collection until the budget fits or no rows can move. */
-function compactRowsToBudget(result, receipt, budget) {
+function compactRowsToBudget(result, receipt, budget, minimumRowsByPath) {
     for (let iteration = 0; iteration < MAX_COMPACTION_ITERATIONS; iteration += 1) {
         updateReadOutputReceiptEstimate(result, receipt);
         if (receipt.estimated_tokens <= budget)
             return;
         const candidate = readOutputBudgetCollections(result)
-            .filter((collection) => (Array.isArray(collection.value)
-            ? collection.value.length
-            : Object.keys(collection.value).length) > 1)
+            .filter((collection) => {
+            const length = Array.isArray(collection.value)
+                ? collection.value.length
+                : Object.keys(collection.value).length;
+            return (length > Math.max(1, minimumRowsByPath.get(collection.path) ?? 0));
+        })
             .map((collection) => ({
             collection,
             length: Array.isArray(collection.value)
@@ -61,12 +64,13 @@ function compactRowsToBudget(result, receipt, budget) {
             left.collection.path.localeCompare(right.collection.path))[0]?.collection;
         if (!candidate)
             return;
+        const minimumRows = Math.max(1, minimumRowsByPath.get(candidate.path) ?? 0);
         if (Array.isArray(candidate.value)) {
-            candidate.value.splice(-Math.max(1, Math.ceil(candidate.value.length / 2)));
+            candidate.value.splice(-Math.min(candidate.value.length - minimumRows, Math.max(1, Math.ceil(candidate.value.length / 2))));
         }
         else {
             const keys = Object.keys(candidate.value);
-            for (const key of keys.slice(-Math.max(1, Math.ceil(keys.length / 2)))) {
+            for (const key of keys.slice(-Math.min(keys.length - minimumRows, Math.max(1, Math.ceil(keys.length / 2))))) {
                 delete candidate.value[key];
             }
         }
@@ -82,14 +86,14 @@ function compactRowsToBudget(result, receipt, budget) {
     }
 }
 /** Compact strings and rows in place, then return the final exact estimate. */
-export function compactReadOutputToBudget(result, receipt, budget) {
+export function compactReadOutputToBudget(result, receipt, budget, minimumRowsByPath = new Map()) {
     const stringCompactionState = { compacted: false };
     const compacted = compactStrings(result, stringCompactionState);
     receipt.strings_compacted = stringCompactionState.compacted;
     compacted.read_output = receipt;
-    compactRowsToBudget(compacted, receipt, budget);
+    compactRowsToBudget(compacted, receipt, budget, minimumRowsByPath);
     updateReadOutputReceiptEstimate(compacted, receipt);
     return compacted;
 }
 //# sourceMappingURL=read-output-budget.js.map
-//# debugId=cc595424-0176-5920-8f4c-d935e6a546ce
+//# debugId=737ac274-c165-5d1a-8b8e-cb5d57a81c46

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

@@ -1,3 +1,4 @@
+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"];
@@ -19,6 +20,8 @@ export interface PmReadOutputOptions {
     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;
 }
@@ -54,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";
@@ -128,8 +133,63 @@ export interface PmReadOutputTruncationDisclosure {
     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 {
@@ -141,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;
@@ -154,11 +218,11 @@ export type PmReadOutputResult<Result> = (Result & {
     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. */

package/dist/sdk/read-output-contracts.js

@@ -5,13 +5,16 @@
  * surface without coupling package authors to command-specific option names.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="c78ba845-78ae-5b16-b486-c279f834d601")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e9621264-0180-53cf-862f-b59640b971da")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { compactReadOutputToBudget, estimateReadOutputTokens, updateReadOutputReceiptEstimate, } from "./read-output-budget.js";
 import { resolvePmCommandOutputBudget } from "./cli-contracts/agent-output-contracts.js";
-import { boundReadOutputRows, countReadOutputRows, mapReadOutputRows, readOutputRowPaths, } from "./read-output-rows.js";
+import { boundReadOutputRows, countReadOutputRows, mapReadOutputRows, readOutputRowCollections, readOutputRowPaths, } from "./read-output-rows.js";
+import { applyReadOutputContinuation, decodeReadOutputContinuationCursor, encodeReadOutputContinuationCursor, prioritizeAssuranceAssertions, readOutputCollectionFingerprint, } from "./read-output/continuation.js";
+export { decodeReadOutputContinuationCursor, encodeReadOutputContinuationCursor, } from "./read-output/continuation.js";
 import { applyReadOutputSessionReferences, attachReadOutputSessionReceipt, parseReadOutputSession, readOutputSessionRemainingTokens, } from "./read-output-session.js";
+import { decodeQueryCursorEnvelope, encodeQueryCursor } from "./pagination.js";
 /** Stable output dimensions shared by every read surface. */
 export const PM_READ_OUTPUT_DIMENSIONS = [
     "include",
@@ -61,6 +64,7 @@ export const PM_READ_OUTPUT_OPTION_FLAGS = Object.freeze(PM_READ_OUTPUT_DIMENSIO
 /** Canonical control that composes the four per-call dimensions across reads. */
 export const PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS = Object.freeze([
     "--output-session",
+    "--output-cursor",
     "--output-row-contract",
 ]);
 const LEGACY_FLAGS_BY_COMMAND = {
@@ -194,6 +198,7 @@ function buildSurfaceContract(command) {
         command,
         dimensions,
         precedence: READ_OUTPUT_PRECEDENCE,
+        budget_retention_policy: command === "assurance" ? "verdict_priority" : "ordered_prefix",
     });
 }
 /** Universal output contract for every built-in read surface. */
@@ -232,6 +237,8 @@ const CANONICAL_OPTION_KEYS = [
     "output_format",
     "outputSession",
     "output_session",
+    "outputCursor",
+    "output_cursor",
     "outputRowContract",
     "output_row_contract",
 ];
@@ -273,6 +280,11 @@ const READ_OUTPUT_VALUE_VALIDATORS = [
         },
         message: "--output-session must be a valid session-state object.",
     },
+    {
+        keys: ["outputCursor", "output_cursor"],
+        valid: (value) => typeof value === "string" && value.trim().length > 0,
+        message: "--output-cursor requires a non-empty continuation cursor.",
+    },
 ];
 /** Reject malformed or mutation-scoped universal output controls before command execution. */
 export function validateReadOutputOptions(command, options) {
@@ -486,6 +498,10 @@ export function resolveReadOutputDimensions(command, options) {
     });
     const encoding = resolveEncodingValue(options.outputFormat ?? options.output_format, legacyByDimension.encoding);
     const explicitCost = resolveCostValue(options.outputBudget ?? options.output_budget, legacyByDimension.cost);
+    const completeResultIntent = command.trim().toLowerCase().replaceAll(/\s+/gu, " ").split(" ")[0] ===
+        "list-all" ||
+        legacyByDimension.amount?.flag === "--no-truncate" ||
+        legacyByDimension.include?.flag === "--full";
     const budget = resolvePmCommandOutputBudget(command, {
         generateFallback: true,
     });
@@ -496,10 +512,13 @@ export function resolveReadOutputDimensions(command, options) {
         command: normalizedCommand,
         include: resolveIncludeValue(options.outputInclude ?? options.output_include, legacyByDimension.include),
         amount: resolveAmountValue(options.outputLimit ?? options.output_limit, legacyByDimension.amount),
-        cost: explicitCost ?? {
-            source: "default",
-            value: budget.default_max_estimated_tokens_by_format[resolvedOutputFormat],
-        },
+        cost: explicitCost ??
+            (completeResultIntent
+                ? { source: "intent", value: "unbounded" }
+                : {
+                    source: "default",
+                    value: budget.default_max_estimated_tokens_by_format[resolvedOutputFormat],
+                }),
         encoding,
         legacy_aliases_used: legacyAliasesUsed,
         migration_hints: migrationHints,
@@ -513,6 +532,8 @@ const ENVELOPE_KEYS = new Set([
     "applied_bound",
     "applied_limit",
     "completeness",
+    "continuation_kind",
+    "continuation_path",
     "continuation_contract",
     "count",
     "filters",
@@ -521,6 +542,7 @@ const ENVELOPE_KEYS = new Set([
     "now",
     "omission_receipt",
     "projection",
+    "budget_retention_policy",
     "row_contract",
     "sorting",
     "total",
@@ -715,11 +737,15 @@ export function stabilizeReadOutputReceiptEstimates(result, options) {
     return attachReadOutputSessionContracts(result, session, receipt);
 }
 /** Apply field, amount, and repeat projections to every declared row path. */
-function projectReadOutputRows(result, resolved, session) {
+function projectReadOutputRows(result, resolved, session, cursor) {
     let projected = { ...result };
     if (resolved.include?.source === "canonical") {
         projected = applyIncludeProjection(resolved.command, projected, resolved.include.value);
     }
+    if (resolved.command === "assurance") {
+        projected = prioritizeAssuranceAssertions(projected);
+    }
+    projected = applyReadOutputContinuation(projected, resolved.command, cursor);
     if (resolved.amount?.source === "canonical") {
         projected = applyAmountBound(projected, resolved.amount.value);
     }
@@ -774,7 +800,8 @@ function omitReadOutputForBudget(resolved, requested, session, bindingBudget, om
         output_budget_exceeded: {
             omitted_result: true,
             reason: "requested_budget_infeasible",
-            restore_with: "Increase --output-budget or narrow the read.",
+            restore_with: "Unbounded",
+            recovery: { outputBudget: "unbounded" },
         },
         read_output: minimalReceipt,
     };
@@ -796,7 +823,7 @@ function canReturnReadOutputUnchanged(resolved, requested, session, result) {
         return false;
     const canonicalRequestedCount = requested.filter((dimension) => resolved[dimension]?.source === "canonical").length;
     if (resolved.cost?.value === "unbounded") {
-        return canonicalRequestedCount === 1;
+        return (canonicalRequestedCount === (resolved.cost.source === "canonical" ? 1 : 0));
     }
     if (resolved.cost?.source === "legacy" && canonicalRequestedCount === 0) {
         return true;
@@ -813,31 +840,174 @@ function canReturnReadOutputUnchanged(resolved, requested, session, result) {
  * without this an explicitly requested unbounded read is silently downgraded and
  * the only working recovery is never named.
  */
-function attachReadOutputTruncationDisclosure(projected, resolved, receipt, bindingBudget) {
+function attachReadOutputTruncationDisclosure(projected, resolved, receipt, bindingBudget, continuationCursorRebased, collectionsBeforeBudget) {
     if (!receipt.rows_compacted)
         return;
     const overridden = resolved.amount?.value === "unbounded" ? ["amount"] : [];
+    const afterByPath = new Map(readOutputRowCollections(projected).map((collection) => [
+        collection.path,
+        Array.isArray(collection.value)
+            ? collection.value.length
+            : Object.keys(collection.value).length,
+    ]));
+    const continuations = [...collectionsBeforeBudget.entries()].flatMap(([path, before]) => {
+        // Budget compaction preserves every declared collection and shortens its
+        // contents, so each pre-budget path has a post-budget cardinality.
+        const retainedRows = afterByPath.get(path);
+        if (retainedRows >= before.rows)
+            return [];
+        const offset = before.baseOffset + retainedRows;
+        return [
+            {
+                path,
+                cursor: encodeReadOutputContinuationCursor({
+                    command: resolved.command,
+                    path,
+                    offset,
+                    total_rows: before.totalRows,
+                    fingerprint: before.fingerprint,
+                }),
+                retained_rows: retainedRows,
+                remaining_rows: before.totalRows - offset,
+                total_rows: before.totalRows,
+            },
+        ];
+    });
+    const primary = continuations[0];
+    if (primary && typeof projected.next_cursor !== "string") {
+        projected.next_cursor = primary.cursor;
+    }
+    projected.continuation_kind = continuationCursorRebased
+        ? "producer_cursor"
+        : primary
+            ? "output_cursor"
+            : "none";
     projected.output_budget_truncation = {
         reason: "output_budget_reached",
         budget_source: bindingBudget.source,
         budget_tokens: bindingBudget.tokens,
         overridden_dimensions: overridden,
         compacted_row_paths: receipt.compacted_row_paths,
-        restore_with: "Re-run with --output-budget unbounded for the complete result.",
+        continuation_cursor_rebased: continuationCursorRebased,
+        continuation_available: continuations.length > 0,
+        recovery_budget_multiplier: 1,
+        continuations,
+        restore_with: primary
+            ? "Use recovery binding."
+            : "Increase --output-budget because no declared row collection can be continued.",
+        recovery: primary
+            ? {
+                cursor: primary.cursor,
+                cli: "--output-cursor",
+                sdk: "outputCursor",
+                mcp: "outputCursor",
+            }
+            : {
+                cli: "--output-budget 1200",
+                sdk: { outputBudget: 1200 },
+                mcp: { outputBudget: 1200 },
+            },
     };
 }
+/** Rebase a producer cursor when budget compaction removes rows from its page. */
+function rebaseBudgetCompactedCursor(projected, originalItemCount, cursorSource, cursorContinuesExistingPage) {
+    if (typeof cursorSource !== "string" || !Array.isArray(projected.items)) {
+        return false;
+    }
+    const retainedCount = projected.items.length;
+    if (retainedCount === 0 || retainedCount >= originalItemCount) {
+        return false;
+    }
+    let cursor;
+    try {
+        cursor = decodeQueryCursorEnvelope(cursorSource);
+    }
+    catch {
+        return false;
+    }
+    const sourceIndex = cursor.after_index;
+    if (sourceIndex === undefined)
+        return false;
+    const last = projected.items.at(-1);
+    if (Object.prototype.toString.call(last) !== "[object Object]") {
+        return false;
+    }
+    const lastId = Reflect.get(last, "id");
+    if (typeof lastId !== "string" || lastId.length === 0)
+        return false;
+    const afterIndex = cursorContinuesExistingPage
+        ? sourceIndex - (originalItemCount - retainedCount)
+        : sourceIndex + retainedCount;
+    if (afterIndex < 0)
+        return false;
+    projected.next_cursor = encodeQueryCursor(cursor.fingerprint, lastId, afterIndex, cursor.snapshot);
+    if (typeof projected.applied_limit === "number") {
+        projected.applied_limit = retainedCount;
+    }
+    return true;
+}
+function captureReadOutputContinuationState(projected, cursor, options) {
+    const collectionsBeforeBudget = new Map(readOutputRowCollections(projected).map((collection) => {
+        const rows = Array.isArray(collection.value)
+            ? collection.value.length
+            : Object.keys(collection.value).length;
+        const continued = cursor?.path === collection.path;
+        return [
+            collection.path,
+            {
+                rows,
+                totalRows: continued ? cursor.total_rows : rows,
+                baseOffset: continued ? cursor.offset : 0,
+                fingerprint: continued
+                    ? cursor.fingerprint
+                    : readOutputCollectionFingerprint(collection.path, collection.value),
+            },
+        ];
+    }));
+    const cursorContinuesExistingPage = typeof projected.next_cursor === "string";
+    return {
+        collectionsBeforeBudget,
+        originalItemCount: Array.isArray(projected.items)
+            ? projected.items.length
+            : 0,
+        cursorContinuesExistingPage,
+        cursorSource: cursorContinuesExistingPage
+            ? projected.next_cursor
+            : options.after,
+    };
+}
+function compactReadOutputProjection(projected, resolved, receipt, bindingBudget, session, continuationState) {
+    const assuranceMinimumRows = resolved.command === "assurance" && Array.isArray(projected.assertions)
+        ? projected.assertions.filter((row) => isRecord(row) && row.verdict !== "pass").length
+        : 0;
+    let compacted = compactReadOutputToBudget(projected, receipt, bindingBudget.tokens, assuranceMinimumRows > 0
+        ? new Map([["assertions", assuranceMinimumRows]])
+        : new Map());
+    const continuationCursorRebased = rebaseBudgetCompactedCursor(compacted, continuationState.originalItemCount, continuationState.cursorSource, continuationState.cursorContinuesExistingPage);
+    attachReadOutputTruncationDisclosure(compacted, resolved, receipt, bindingBudget, continuationCursorRebased, continuationState.collectionsBeforeBudget);
+    if (session !== undefined) {
+        compacted = attachReadOutputSessionContracts(compacted, session, receipt);
+    }
+    return compacted;
+}
 /** Apply universal field, row, and token bounds and attach an exact receipt. */
 export function applyReadOutputDimensions(command, options, result) {
     const resolved = resolveReadOutputDimensions(command, options);
     if (!resolved)
         return result;
     const session = parseReadOutputSession(options.outputSession ?? options.output_session);
+    const rawCursor = options.outputCursor ?? options.output_cursor;
+    const cursor = typeof rawCursor === "string"
+        ? decodeReadOutputContinuationCursor(rawCursor)
+        : undefined;
     const requested = requestedDimensions(resolved);
-    if (canReturnReadOutputUnchanged(resolved, requested, session, result)) {
+    if (cursor === undefined &&
+        canReturnReadOutputUnchanged(resolved, requested, session, result)) {
         return result;
     }
     const bindingBudget = resolveBindingReadOutputBudget(resolved, session);
-    let projected = projectReadOutputRows(result, resolved, session);
+    let projected = projectReadOutputRows(result, resolved, session, cursor);
+    const continuationState = captureReadOutputContinuationState(projected, cursor, options);
     const receipt = {
         contract_version: 1,
         command: resolved.command,
@@ -865,11 +1035,7 @@ export function applyReadOutputDimensions(command, options, result) {
     updateReadOutputReceiptEstimate(projected, receipt);
     if (bindingBudget !== undefined &&
         receipt.estimated_tokens > bindingBudget.tokens) {
-        projected = compactReadOutputToBudget(projected, receipt, bindingBudget.tokens);
-        attachReadOutputTruncationDisclosure(projected, resolved, receipt, bindingBudget);
-        if (session !== undefined) {
-            projected = attachReadOutputSessionContracts(projected, session, receipt);
-        }
+        projected = compactReadOutputProjection(projected, resolved, receipt, bindingBudget, session, continuationState);
     }
     if (bindingBudget !== undefined &&
         receipt.estimated_tokens > bindingBudget.tokens) {
@@ -892,4 +1058,4 @@ export function resolveReadOutputEncoding(command, options) {
         : undefined;
 }
 //# sourceMappingURL=read-output-contracts.js.map
-//# debugId=c78ba845-78ae-5b16-b486-c279f834d601
+//# debugId=e9621264-0180-53cf-862f-b59640b971da

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

@@ -11,6 +11,8 @@ export interface PmReadOutputRowCollection {
     /** Array rows or a keyed row map stored at {@link path}. */
     value: unknown[] | Record<string, unknown>;
 }
+/** Replace one declared row collection with a suffix beginning at an offset. */
+export declare function sliceReadOutputRowCollection(result: Record<string, unknown>, rowPath: string, offset: number): Record<string, unknown>;
 /** Resolve declared row paths, falling back to top-level array properties. */
 export declare function readOutputRowPaths(result: Record<string, unknown>): string[];
 /** Resolve every declared row path that currently contains iterable rows. */