@unbrained/pm-cli 2026.8.13 → 2026.8.15

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

@@ -5,12 +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]="0ab0c72c-cac0-5670-93d1-7a446f8a2301")}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]="f9774018-a5b7-505e-a8ea-cba08392afeb")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
-import { compactReadOutputToBudget, updateReadOutputReceiptEstimate, } from "./read-output-budget.js";
-import { boundReadOutputRows, countReadOutputRows, mapReadOutputRows, readOutputRowPaths, } from "./read-output-rows.js";
+import { compactReadOutputToBudget, estimateReadOutputTokens, updateReadOutputReceiptEstimate, } from "./read-output-budget.js";
+import { resolvePmCommandOutputBudget } from "./cli-contracts/agent-output-contracts.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",
@@ -40,6 +44,8 @@ export const PM_READ_OUTPUT_SURFACES = [
     "stats",
     "aggregate",
     "package-manage",
+    "comments-audit",
+    "assurance",
 ];
 const READ_OUTPUT_PRECEDENCE = [
     "canonical",
@@ -58,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 = {
@@ -91,7 +98,7 @@ const LEGACY_FLAGS_BY_COMMAND = {
         encoding: ["--format"],
     },
     health: {
-        include: ["--brief", "--check-only", "--full", "--summary", "--verbose"],
+        include: ["--brief", "--check-only", "--full", "--summary"],
     },
     deps: {
         include: ["--collapse", "--full", "--summary"],
@@ -113,7 +120,7 @@ const LEGACY_FLAGS_BY_COMMAND = {
         amount: ["--limit", "--unbounded"],
         encoding: ["--stream"],
     },
-    validate: { include: ["--counts", "--full", "--verbose"] },
+    validate: { include: ["--counts", "--full"] },
     events: {
         include: ["--full"],
         amount: ["--limit"],
@@ -129,17 +136,26 @@ const LEGACY_FLAGS_BY_COMMAND = {
     stats: {},
     aggregate: {},
     "package-manage": {},
+    "comments-audit": {},
+    assurance: {},
 };
-const VALUE_BEARING_INCLUDE_ALIASES = new Set(["--fields", "--section"]);
+const VALUE_BEARING_INCLUDE_ALIASES = new Set([
+    "--collapse",
+    "--fields",
+    "--section",
+]);
 const BEHAVIOR_PRESERVING_MIGRATION_HINTS = Object.freeze({
     "--after": "--after retains cursor-position semantics; use --output-limit <n> separately to bound returned rows.",
     "--check-only": "--check-only retains health side-effect semantics; --output-include does not suppress vector refresh.",
+    "--collapse": "--collapse retains dependency grouping semantics; --output-include does not replace it.",
     "--depth": "--depth retains traversal or detail-depth semantics; --output-limit does not replace it.",
     "--follow": "--follow retains event-tail semantics; --output-format does not enable following.",
     "--max-depth": "--max-depth retains graph traversal-depth semantics; --output-limit does not replace it.",
     "--max-paths": "--max-paths retains graph path-search semantics; use --output-limit separately to bound returned rows.",
+    "--no-truncate": "--no-truncate is a compatibility alias; prefer --output-limit unbounded.",
     "--offset": "--offset retains positional pagination semantics; use --output-limit separately to bound returned rows.",
     "--stream": "--stream retains command streaming semantics; --output-format selects only static result encoding.",
+    "--unbounded": "--unbounded is a compatibility alias; prefer --output-limit unbounded.",
 });
 function flagSelector(flag) {
     return flag.slice(2).replaceAll("-", "_");
@@ -170,6 +186,9 @@ function buildSurfaceContract(command) {
             inapplicable_reason: null,
             legacy_aliases: Object.freeze((legacy[dimension] ?? []).map((flag) => Object.freeze({
                 flag,
+                semantics: BEHAVIOR_PRESERVING_MIGRATION_HINTS[flag] === undefined
+                    ? "replacement"
+                    : "behavior_preserving",
                 migration_hint: migrationHint(flag, dimension),
                 visibility: "hidden_alias",
             }))),
@@ -179,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. */
@@ -217,6 +237,8 @@ const CANONICAL_OPTION_KEYS = [
     "output_format",
     "outputSession",
     "output_session",
+    "outputCursor",
+    "output_cursor",
     "outputRowContract",
     "output_row_contract",
 ];
@@ -242,8 +264,8 @@ const READ_OUTPUT_VALUE_VALIDATORS = [
     },
     {
         keys: ["outputBudget", "output_budget"],
-        valid: (value) => positiveInteger(value) !== undefined,
-        message: "--output-budget must be a positive integer.",
+        valid: (value) => value === "unbounded" || positiveInteger(value) !== undefined,
+        message: "--output-budget must be a positive integer or unbounded.",
     },
     {
         keys: ["outputFormat", "output_format"],
@@ -258,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) {
@@ -279,6 +306,68 @@ export function validateReadOutputOptions(command, options) {
         }
     }
 }
+/**
+ * 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 function readOutputIncludeModeOptions(command) {
+    const surface = resolveReadOutputSurface(command);
+    if (!surface)
+        return new Map();
+    return new Map((LEGACY_FLAGS_BY_COMMAND[surface].include ?? [])
+        .filter((flag) => !VALUE_BEARING_INCLUDE_ALIASES.has(flag) &&
+        BEHAVIOR_PRESERVING_MIGRATION_HINTS[flag] === undefined)
+        .map((flag) => [flagSelector(flag), optionKey(flag)]));
+}
+/**
+ * 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 function applyReadOutputIncludeModes(command, includeValue, commandOptions) {
+    const requested = stringList(includeValue) ?? [];
+    const modeOptions = readOutputIncludeModeOptions(command);
+    const selectors = [];
+    const modes = [];
+    for (const token of requested) {
+        const option = modeOptions.get(token);
+        if (option === undefined) {
+            selectors.push(token);
+            continue;
+        }
+        commandOptions[option] = true;
+        modes.push(token);
+    }
+    return { selectors, modes };
+}
+/**
+ * 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 function normalizeReadOutputIncludeModeOptions(command, options) {
+    const include = options.outputInclude ?? options.output_include;
+    if (include === undefined)
+        return;
+    const { selectors, modes } = applyReadOutputIncludeModes(command, include, options);
+    if (modes.length === 0)
+        return;
+    const residual = selectors.length > 0 ? selectors.join(",") : undefined;
+    options.outputInclude = residual;
+    if (Object.hasOwn(options, "output_include")) {
+        options.output_include = residual;
+    }
+}
 function optionKey(flag) {
     return flag
         .slice(2)
@@ -353,6 +442,9 @@ function resolveAmountValue(canonical, legacy) {
         : { source: "legacy", value: legacyLimit };
 }
 function resolveCostValue(canonical, legacy) {
+    if (canonical === "unbounded") {
+        return { source: "canonical", value: "unbounded" };
+    }
     const canonicalBudget = positiveInteger(canonical);
     if (canonicalBudget !== undefined) {
         return { source: "canonical", value: canonicalBudget };
@@ -404,12 +496,28 @@ export function resolveReadOutputDimensions(command, options) {
         const alias = contract.dimensions[dimension].legacy_aliases.find((entry) => entry.flag === resolved.flag);
         return [alias.migration_hint];
     });
+    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";
+    const budget = resolvePmCommandOutputBudget(command, {
+        generateFallback: true,
+    });
+    const resolvedOutputFormat = encoding?.value === "json" || options.resolvedOutputFormat === "json"
+        ? "json"
+        : "toon";
     return {
         command: normalizedCommand,
         include: resolveIncludeValue(options.outputInclude ?? options.output_include, legacyByDimension.include),
         amount: resolveAmountValue(options.outputLimit ?? options.output_limit, legacyByDimension.amount),
-        cost: resolveCostValue(options.outputBudget ?? options.output_budget, legacyByDimension.cost),
-        encoding: resolveEncodingValue(options.outputFormat ?? options.output_format, legacyByDimension.encoding),
+        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,
         precedence: READ_OUTPUT_PRECEDENCE,
@@ -422,6 +530,8 @@ const ENVELOPE_KEYS = new Set([
     "applied_bound",
     "applied_limit",
     "completeness",
+    "continuation_kind",
+    "continuation_path",
     "continuation_contract",
     "count",
     "filters",
@@ -430,6 +540,7 @@ const ENVELOPE_KEYS = new Set([
     "now",
     "omission_receipt",
     "projection",
+    "budget_retention_policy",
     "row_contract",
     "sorting",
     "total",
@@ -525,6 +636,34 @@ function applyGetIncludeProjection(result, selectors) {
     };
     return projected;
 }
+/** Count row objects that still carry at least one field. */
+function countPopulatedRows(result) {
+    let populated = 0;
+    mapReadOutputRows({ ...result }, (entry) => {
+        if (isRecord(entry) && Object.keys(entry).length > 0)
+            populated += 1;
+        return entry;
+    });
+    return populated;
+}
+/**
+ * Refuse an include projection that strips every field from every row.
+ *
+ * Selectors that match no field are not a narrower answer, they are no answer:
+ * without this the surface returns the requested row count as empty objects and
+ * exits 0, so a mistyped or mode-shaped selector is indistinguishable from a
+ * workspace that genuinely holds nothing.
+ */
+function rejectEmptyIncludeProjection(command, original, shaped, selectors) {
+    if (countPopulatedRows(original) === 0 || countPopulatedRows(shaped) > 0) {
+        return;
+    }
+    const modes = [...readOutputIncludeModeOptions(command).keys()];
+    const domain = modes.length > 0
+        ? ` Declared ${command} projection modes: ${modes.join(", ")}.`
+        : ` The ${command} surface declares no projection modes; name row fields instead.`;
+    throw new PmCliError(`Unknown --output-include selector(s) for ${command}: ${selectors.join(", ")}. No selector matched any returned row field.${domain}`, EXIT_CODE.USAGE);
+}
 function applyIncludeProjection(command, result, selectors) {
     if (command === "get") {
         return applyGetIncludeProjection(result, selectors);
@@ -537,11 +676,10 @@ function applyIncludeProjection(command, result, selectors) {
         !rows.some((rowPath) => selector.startsWith(`${rowPath}.`)));
     if (rows.length > 0 && (!selectedRoot || qualifiedRowSelectors.length > 0)) {
         const projected = { ...result };
-        return mapReadOutputRows(projected, (entry) => isRecord(entry)
-            ? projectRecordFields(entry, qualifiedRowSelectors.length > 0
-                ? qualifiedRowSelectors
-                : selectors)
-            : entry);
+        const rowSelectors = qualifiedRowSelectors.length > 0 ? qualifiedRowSelectors : selectors;
+        const shaped = mapReadOutputRows(projected, (entry) => isRecord(entry) ? projectRecordFields(entry, rowSelectors) : entry);
+        rejectEmptyIncludeProjection(command, result, shaped, rowSelectors);
+        return shaped;
     }
     return Object.fromEntries(Object.entries(result).filter(([key]) => selectors.some((selector) => selector.split(".")[0] === key) ||
         ENVELOPE_KEYS.has(key)));
@@ -565,7 +703,8 @@ function applyAmountBound(result, amount) {
     return bounded;
 }
 function requestedDimensions(resolved) {
-    return PM_READ_OUTPUT_DIMENSIONS.filter((dimension) => resolved[dimension] !== undefined);
+    return PM_READ_OUTPUT_DIMENSIONS.filter((dimension) => resolved[dimension] !== undefined &&
+        resolved[dimension]?.source !== "default");
 }
 /** Stabilize the per-call and cross-call receipts in one complete envelope. */
 function attachReadOutputSessionContracts(result, state, receipt) {
@@ -596,11 +735,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);
     }
@@ -611,19 +754,34 @@ function projectReadOutputRows(result, resolved, session) {
 /** Resolve the smallest binding per-call or remaining cross-call ceiling. */
 function resolveBindingReadOutputBudget(resolved, session) {
     const budgets = [
-        ...(resolved.cost?.source === "canonical" ? [resolved.cost.value] : []),
+        ...(resolved.cost !== undefined &&
+            resolved.cost.value !== "unbounded" &&
+            (resolved.cost.source === "canonical" || resolved.cost.source === "default")
+            ? [{ source: resolved.cost.source, tokens: resolved.cost.value }]
+            : []),
         ...(session === undefined
             ? []
-            : [readOutputSessionRemainingTokens(session)]),
+            : [
+                {
+                    source: "session",
+                    tokens: readOutputSessionRemainingTokens(session),
+                },
+            ]),
     ];
-    return budgets.length === 0 ? undefined : Math.min(...budgets);
+    return budgets.sort((left, right) => left.tokens - right.tokens)[0];
 }
 /** Build the smallest truthful omission envelope or reject an exhausted session. */
-function omitReadOutputForBudget(resolved, requested, session, budget) {
+function omitReadOutputForBudget(resolved, requested, session, bindingBudget, omittedResultEstimatedTokens) {
     const minimalReceipt = {
         contract_version: 1,
         command: resolved.command,
         requested_dimensions: requested,
+        ...(bindingBudget.source === "default"
+            ? {
+                budget_source: bindingBudget.source,
+                budget_tokens: bindingBudget.tokens,
+            }
+            : {}),
         precedence: resolved.precedence,
         legacy_aliases_used: [],
         migration_hints: [],
@@ -632,12 +790,16 @@ function omitReadOutputForBudget(resolved, requested, session, budget) {
         strings_compacted: false,
         rows_compacted: false,
         result_omitted: true,
+        ...(session === undefined
+            ? { omitted_result_estimated_tokens: omittedResultEstimatedTokens }
+            : {}),
     };
     const omitted = {
         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,
     };
@@ -647,27 +809,213 @@ function omitReadOutputForBudget(resolved, requested, session, budget) {
     if (session === undefined) {
         updateReadOutputReceiptEstimate(boundedOmission, minimalReceipt);
     }
-    if (session !== undefined && minimalReceipt.estimated_tokens > budget) {
+    if (session !== undefined &&
+        minimalReceipt.estimated_tokens > bindingBudget.tokens) {
         throw new PmCliError("The remaining output-session budget cannot fit its mandatory receipts; start a new session with a larger token_budget.", EXIT_CODE.USAGE);
     }
     return boundedOmission;
 }
+/** Decide whether shaping would add no value to an already-bounded result. */
+function canReturnReadOutputUnchanged(resolved, requested, session, result) {
+    if (session !== undefined)
+        return false;
+    const canonicalRequestedCount = requested.filter((dimension) => resolved[dimension]?.source === "canonical").length;
+    if (resolved.cost?.value === "unbounded") {
+        return (canonicalRequestedCount === (resolved.cost.source === "canonical" ? 1 : 0));
+    }
+    if (resolved.cost?.source === "legacy" && canonicalRequestedCount === 0) {
+        return true;
+    }
+    return (canonicalRequestedCount === 0 &&
+        (resolved.cost === undefined ||
+            estimateReadOutputTokens(result) <= resolved.cost.value));
+}
+/**
+ * Disclose a budget-driven row drop in the envelope that carries it.
+ *
+ * `has_more` and `truncated` say that rows were withheld but not why, by what,
+ * or how to get them: the row-compaction path emits no continuation cursor, so
+ * without this an explicitly requested unbounded read is silently downgraded and
+ * the only working recovery is never named.
+ */
+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,
+        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);
-    const canonicalRequested = requested.filter((dimension) => resolved[dimension]?.source === "canonical");
-    if (canonicalRequested.length === 0 && session === undefined) {
+    if (cursor === undefined &&
+        canReturnReadOutputUnchanged(resolved, requested, session, result)) {
         return result;
     }
-    let projected = projectReadOutputRows(result, resolved, session);
+    const bindingBudget = resolveBindingReadOutputBudget(resolved, session);
+    let projected = projectReadOutputRows(result, resolved, session, cursor);
+    const continuationState = captureReadOutputContinuationState(projected, cursor, options);
     const receipt = {
         contract_version: 1,
         command: resolved.command,
         requested_dimensions: requested,
+        ...(bindingBudget?.source === "default"
+            ? {
+                budget_source: bindingBudget.source,
+                budget_tokens: bindingBudget.tokens,
+            }
+            : {}),
         precedence: resolved.precedence,
         legacy_aliases_used: resolved.legacy_aliases_used,
         migration_hints: resolved.migration_hints,
@@ -683,15 +1031,13 @@ export function applyReadOutputDimensions(command, options, result) {
             ? projected
             : attachReadOutputSessionContracts(projected, session, receipt);
     updateReadOutputReceiptEstimate(projected, receipt);
-    const budget = resolveBindingReadOutputBudget(resolved, session);
-    if (budget !== undefined && receipt.estimated_tokens > budget) {
-        projected = compactReadOutputToBudget(projected, receipt, budget);
-        if (session !== undefined) {
-            projected = attachReadOutputSessionContracts(projected, session, receipt);
-        }
+    if (bindingBudget !== undefined &&
+        receipt.estimated_tokens > bindingBudget.tokens) {
+        projected = compactReadOutputProjection(projected, resolved, receipt, bindingBudget, session, continuationState);
     }
-    if (budget !== undefined && receipt.estimated_tokens > budget) {
-        return omitReadOutputForBudget(resolved, requested, session, budget);
+    if (bindingBudget !== undefined &&
+        receipt.estimated_tokens > bindingBudget.tokens) {
+        return omitReadOutputForBudget(resolved, requested, session, bindingBudget, receipt.estimated_tokens);
     }
     return projected;
 }
@@ -710,4 +1056,4 @@ export function resolveReadOutputEncoding(command, options) {
         : undefined;
 }
 //# sourceMappingURL=read-output-contracts.js.map
-//# debugId=0ab0c72c-cac0-5670-93d1-7a446f8a2301
+//# debugId=f9774018-a5b7-505e-a8ea-cba08392afeb

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

@@ -11,10 +11,23 @@ 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. */
 export declare function readOutputRowCollections(result: Record<string, unknown>): PmReadOutputRowCollection[];
+/**
+ * Discover every collection the token-budget degradation ladder may reduce.
+ *
+ * Ordinary field and amount projections stay bound to declared row paths (or
+ * top-level array fallbacks), because a nested tag list is not an independent
+ * result row. Budget degradation has a different obligation: it must exhaust
+ * nested content collections before omitting the whole useful result. This
+ * census therefore adds nested arrays while excluding receipt/envelope metadata
+ * whose mutation would make the disclosure itself incomplete.
+ */
+export declare function readOutputBudgetCollections(result: Record<string, unknown>): PmReadOutputRowCollection[];
 /** Count array entries and object-map values across declared row collections. */
 export declare function countReadOutputRows(result: Record<string, unknown>): number;
 /**