@unbrained/pm-cli 2026.8.13 → 2026.8.15

package/dist/sdk/index.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 
-!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]="8664ab01-dc47-5344-b2d7-9ac315e8a74b")}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]="a05170b2-a48d-5275-ac04-aafc9f8315b2")}catch(e){}}();
 export { PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./agent-session-context.js";
 export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, normalizeAnnotationTransportOptions, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, } from "./annotations.js";
@@ -82,7 +82,7 @@ export * from "./history-compact.js";
 export * from "./history-read.js";
 export * from "./history-provenance.js";
 export * from "./mutation-events.js";
-export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, mutateWorkspaceJsonWithHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, } from "../core/history/workspace-history.js";
+export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, inspectWorkspaceHistoryState, mutateWorkspaceJsonWithHistory, reconcileWorkspaceJsonHistory, restoreWorkspaceJsonFromHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, } from "../core/history/workspace-history.js";
 export * from "./history-redact.js";
 export { _testOnly } from "./history-redact.js";
 export * from "./history-repair.js";
@@ -151,4 +151,4 @@ export * from "./governance.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=8664ab01-dc47-5344-b2d7-9ac315e8a74b
+//# debugId=a05170b2-a48d-5275-ac04-aafc9f8315b2

package/dist/sdk/linked-artifacts.js

@@ -4,7 +4,7 @@
  * Implements the pm linked artifacts command surface and its agent-facing runtime behavior.
  */
 
-!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]="585364aa-e5ff-56b6-8276-8f741fbd6be4")}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]="256b39b7-882e-553c-9dea-813bfd363dd7")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import fg from "fast-glob";
@@ -57,9 +57,20 @@ export function looksLikeStructuredPathEntry(raw) {
     if (/^(?:[-*+]\s+)?(?:path|scope|note)\s*[:=]/i.test(raw)) {
         return true;
     }
-    // A first-key typo (e.g. `lable=main,path=…`) must still be parsed so the
-    // unknown key is rejected rather than swallowed as a bare path (GH-258).
-    return looksLikeGenericKeyValueEntry(raw);
+    // An equals sign is valid inside filesystem paths and URL query strings.
+    // Preserve unmistakable whitespace-free path/URL shapes while routing
+    // leading assignment syntax through the structured-key allowlist so typos
+    // and malformed URL-plus-note input remain atomic failures (GH-258,
+    // GH-1000).
+    const equalsIndex = raw.indexOf("=");
+    if (equalsIndex >= 0 &&
+        !/\s/u.test(raw) &&
+        (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(raw) ||
+            /^(?:[A-Za-z]:[\\/]|[\\/]{1,2}|\.\.?(?:[\\/]))/u.test(raw) ||
+            [raw.indexOf("/"), raw.indexOf("\\")].some((separatorIndex) => separatorIndex >= 0 && separatorIndex < equalsIndex))) {
+        return false;
+    }
+    return raw.includes("=") || looksLikeGenericKeyValueEntry(raw);
 }
 function expandBareCommaSeparatedAddEntries(raw) {
     return raw.flatMap((entry) => {
@@ -479,4 +490,4 @@ export function renameArtifactsResultKey(result, key) {
     return out;
 }
 //# sourceMappingURL=linked-artifacts.js.map
-//# debugId=585364aa-e5ff-56b6-8276-8f741fbd6be4
+//# debugId=256b39b7-882e-553c-9dea-813bfd363dd7

package/dist/sdk/pagination.d.ts

@@ -1,4 +1,17 @@
 import type { CliFlagContract } from "./cli-contracts/flag-contracts.js";
+/** Validated transport envelope carried by an opaque query cursor. */
+export interface QueryCursorEnvelope {
+    /** Serialized cursor contract version. */
+    version: number;
+    /** Stable fingerprint of the query semantics that produced the cursor. */
+    fingerprint: string;
+    /** Stable id of the last row emitted by the producer. */
+    after_id: string;
+    /** Zero-based position of the last emitted row when available. */
+    after_index?: number;
+    /** Opaque producer-defined snapshot token for stable continuation. */
+    snapshot?: string;
+}
 /** Decoded cursor state for advanced package and retrieval-window integrations. */
 export interface QueryCursorState {
     /** Stable id of the last row emitted by the previous page. */
@@ -27,6 +40,8 @@ export declare function selectCursorSemanticOptions(options: Readonly<Record<str
 export declare function createQueryFingerprint(command: string, contract: unknown): string;
 /** Encode the last emitted item id into a versioned opaque base64url cursor. */
 export declare function encodeQueryCursor(fingerprint: string, afterId: string, afterIndex?: number, snapshot?: string): string;
+/** Decode and validate an opaque cursor without imposing caller query identity. */
+export declare function decodeQueryCursorEnvelope(cursor: unknown): QueryCursorEnvelope;
 /** Decode and validate complete cursor state against a query fingerprint. */
 export declare function decodeQueryCursorState(cursor: unknown, expectedFingerprint: string): QueryCursorState;
 /** Decode and validate a cursor against the normalized query fingerprint. */

package/dist/sdk/pagination.js

@@ -5,7 +5,7 @@
  * package-authored query surfaces.
  */
 
-!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]="83fe180b-9d95-5d19-9d3b-ba3821700e61")}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]="d3329fac-693d-566c-a30a-43f8fb37938f")}catch(e){}}();
 import { createHash } from "node:crypto";
 import { PmCliError } from "../core/shared/errors.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
@@ -78,8 +78,8 @@ function isQueryCursorEnvelope(value) {
         (envelope.snapshot === undefined ||
             (typeof envelope.snapshot === "string" && envelope.snapshot.length > 0)));
 }
-/** Decode and validate complete cursor state against a query fingerprint. */
-export function decodeQueryCursorState(cursor, expectedFingerprint) {
+/** Decode and validate an opaque cursor without imposing caller query identity. */
+export function decodeQueryCursorEnvelope(cursor) {
     if (typeof cursor !== "string") {
         throw invalidCursor("Query cursor is malformed.");
     }
@@ -99,7 +99,11 @@ export function decodeQueryCursorState(cursor, expectedFingerprint) {
     if (!isQueryCursorEnvelope(parsed)) {
         throw invalidCursor("Query cursor version or payload is unsupported.");
     }
-    const envelope = parsed;
+    return parsed;
+}
+/** Decode and validate complete cursor state against a query fingerprint. */
+export function decodeQueryCursorState(cursor, expectedFingerprint) {
+    const envelope = decodeQueryCursorEnvelope(cursor);
     if (envelope.fingerprint !== expectedFingerprint) {
         throw invalidCursor(`Query cursor does not match the current filters, sort, or query (${envelope.fingerprint} != ${expectedFingerprint}).`);
     }
@@ -156,4 +160,4 @@ export const QUERY_CURSOR_CONTRACT = Object.freeze({
     max_length: MAX_CURSOR_LENGTH,
 });
 //# sourceMappingURL=pagination.js.map
-//# debugId=83fe180b-9d95-5d19-9d3b-ba3821700e61
+//# debugId=d3329fac-693d-566c-a30a-43f8fb37938f

package/dist/sdk/query/context.d.ts

@@ -399,6 +399,10 @@ export interface ContextRankingSummary {
         score: number;
         contributions: ContextRelevanceContributions;
     }>;
+    /** Number of candidates considered before answer-sized projection. */
+    candidate_count: number;
+    /** Number of candidate explanations omitted because their rows were not served. */
+    omitted_count: number;
     /** Rebuildable feature-store freshness and provenance. */
     feature_store?: {
         source: "derived_index" | "scan_fallback";
@@ -462,7 +466,7 @@ export declare function packRankedContextItems(report: ContextRelevanceReport<It
 /** Projects the SDK packer report onto the stable low-token command envelope. */
 export declare function toContextPackingSummary(report: ContextPackingReport<ItemMetadata>): ContextPackingSummary;
 /** Project a full scorer report onto the low-token command explanation shape. */
-export declare function toContextRankingSummary<TItem>(report: ContextRelevanceReport<TItem>, featureStore?: ContextSignalStoreReadResult): ContextRankingSummary;
+export declare function toContextRankingSummary<TItem>(report: ContextRelevanceReport<TItem>, featureStore?: ContextSignalStoreReadResult, servedItemIds?: ReadonlySet<string>): ContextRankingSummary;
 declare function completionPct(closed: number, total: number): number;
 /** Indexes items by their parent id, yielding a parent→direct-children map used by the hierarchy/progress rollups and by focus-row child completion. Items without a parent are skipped. Exported so sibling read commands reuse the same index. */
 export declare function buildChildrenByParent(allItems: ItemMetadata[]): Map<string, ItemMetadata[]>;

package/dist/sdk/query/context.js

@@ -4,7 +4,7 @@
  * Implements the pm context command surface and its agent-facing runtime behavior.
  */
 
-!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]="757a0349-9fb6-579d-ab29-fabaad790ce4")}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]="ee5279f2-7489-59fb-8f96-f2e035434cce")}catch(e){}}();
 import { SETTINGS_DEFAULTS, EXIT_CODE, PmCliError, compareTimestampStrings, nowIso, isTerminalStatus, normalizeStatusForRegistry, normalizeStatusInput, resolveRuntimeStatusRegistry, resolvePmRoot, readSettings, resolveAuthor, discoverExtensions, } from "../runtime-primitives.js";
 import { collectDependencyBlockedIds, resolveItemBlockers, } from "../actionability.js";
 import { CONTEXT_DEPTH_VALUES, CONTEXT_SECTION_VALUES, } from "../../types/index.js";
@@ -455,17 +455,22 @@ export function toContextPackingSummary(report) {
     };
 }
 /** Project a full scorer report onto the low-token command explanation shape. */
-export function toContextRankingSummary(report, featureStore) {
+export function toContextRankingSummary(report, featureStore, servedItemIds) {
+    const ranked = servedItemIds === undefined
+        ? report.ranked
+        : report.ranked.filter((entry) => servedItemIds.has(entry.id));
     return {
         model: report.model,
         available_signals: report.available_signals,
-        items: report.ranked.map((entry) => ({
+        items: ranked.map((entry) => ({
             id: entry.id,
             rank: entry.rank,
             baseline_rank: entry.baseline_rank,
             score: entry.score,
             contributions: entry.contributions,
         })),
+        candidate_count: report.ranked.length,
+        omitted_count: report.ranked.length - ranked.length,
         ...(featureStore
             ? {
                 feature_store: {
@@ -1659,7 +1664,11 @@ export async function runContext(options, global) {
     attachOptionalContextSections(result, sections, focusGroups.featureStore.warning_details);
     applyContextTagProjection(result, options.noTags === true);
     if (options.explainRanking === true) {
-        result.ranking = toContextRankingSummary(focusGroups.ranking, focusGroups.featureStore);
+        result.ranking = toContextRankingSummary(focusGroups.ranking, focusGroups.featureStore, new Set([
+            ...focusGroups.highLevel,
+            ...focusGroups.lowLevel,
+            ...focusGroups.blockedFallback,
+        ].map((entry) => entry.id)));
         result.packing = toContextPackingSummary(focusGroups.packing);
     }
     applyContextFocusProjection(result, runtime.focusFields);
@@ -1670,4 +1679,4 @@ export async function runContext(options, global) {
     return result;
 }
 //# sourceMappingURL=context.js.map
-//# debugId=757a0349-9fb6-579d-ab29-fabaad790ce4
+//# debugId=ee5279f2-7489-59fb-8f96-f2e035434cce

package/dist/sdk/query/history.js

@@ -4,8 +4,8 @@
  * Implements the pm history command surface and its agent-facing runtime behavior.
  */
 
-!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]="1638ef81-7558-5d51-8561-99c958de2d03")}catch(e){}}();
-import { pathExists, computeHistoryDiff, patchPathToChangedField, normalizeReplayPatchOps, verifyHistoryChain, enforceHistoryStreamPolicyForItem, EXIT_CODE, PmCliError, getActiveExtensionRegistrations, normalizeItemId, resolveItemTypeRegistry, locateItem, readLocatedItem, getHistoryPath, getWorkspaceHistoryPath, getSettingsPath, resolvePmRoot, readSettings, WORKSPACE_HISTORY_ID, } from "../runtime-primitives.js";
+!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]="f18d7526-01eb-593b-bf50-788c08a35e5d")}catch(e){}}();
+import { pathExists, computeHistoryDiff, patchPathToChangedField, normalizeReplayPatchOps, verifyHistoryChain, enforceHistoryStreamPolicyForItem, EXIT_CODE, PmCliError, getActiveExtensionRegistrations, normalizeItemId, resolveItemTypeRegistry, locateItem, readLocatedItem, getHistoryPath, getWorkspaceHistoryPath, inspectWorkspaceHistoryState, getSettingsPath, resolvePmRoot, readSettings, WORKSPACE_HISTORY_ID, } from "../runtime-primitives.js";
 import { readHistoryEntries, verifyHistoryEntries, } from "../history-read.js";
 export { readHistoryEntries } from "../history-read.js";
 import { parseLimit } from "./parsers.js";
@@ -140,8 +140,25 @@ export async function runHistory(id, options, global) {
             })).document
             : undefined;
         result.verification = verifyHistoryEntries(fullHistory, currentDocument);
+        if (resolvedId === WORKSPACE_HISTORY_ID && result.verification.ok) {
+            const agreement = await inspectWorkspaceHistoryState(resolvePmRoot(process.cwd(), global.path));
+            result.verification = {
+                ...result.verification,
+                ok: agreement.ok,
+                errors: agreement.ok
+                    ? result.verification.errors
+                    : [
+                        ...result.verification.errors,
+                        "verify_failed:workspace_state_mismatch",
+                    ],
+                workspace_state_matches_latest: agreement.ok,
+                workspace_state_mismatches: agreement.mismatched_documents,
+                workspace_state_missing: agreement.missing_documents,
+                workspace_state_unreadable: agreement.unreadable_documents,
+            };
+        }
     }
     return result;
 }
 //# sourceMappingURL=history.js.map
-//# debugId=1638ef81-7558-5d51-8561-99c958de2d03
+//# debugId=f18d7526-01eb-593b-bf50-788c08a35e5d

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

@@ -0,0 +1,11 @@
+import type { PmReadOutputCursorEnvelope, PmReadOutputSurface } from "../read-output-contracts.js";
+/** Fingerprint stable row identities without including volatile observation fields. */
+export declare function readOutputCollectionFingerprint(path: string, value: unknown[] | Record<string, unknown>): string;
+/** Encode one stable declared-row continuation for CLI, SDK, and MCP callers. */
+export declare function encodeReadOutputContinuationCursor(cursor: Omit<PmReadOutputCursorEnvelope, "version">): string;
+/** Decode and validate one universal declared-row continuation cursor. */
+export declare function decodeReadOutputContinuationCursor(raw: string): PmReadOutputCursorEnvelope;
+/** Place every non-passing assurance assertion before passing evidence. */
+export declare function prioritizeAssuranceAssertions(result: Record<string, unknown>): Record<string, unknown>;
+/** Validate and apply a continuation suffix to its declared row collection. */
+export declare function applyReadOutputContinuation(result: Record<string, unknown>, command: PmReadOutputSurface, cursor: PmReadOutputCursorEnvelope | undefined): Record<string, unknown>;

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

@@ -5,7 +5,9 @@
  * read-output contract without expanding its public declaration module.
  */
 import type { PmReadOutputReceipt } from "./read-output-contracts.js";
+/** Estimate the conservative token cost of a JSON-shaped result. */
+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,8 +1,12 @@
 
-!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]="1726fdce-dc71-5707-ae75-b588691e813d")}catch(e){}}();
-import { countReadOutputRows, readOutputRowCollections, } from "./read-output-rows.js";
+!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;
+/** Estimate the conservative token cost of a JSON-shaped result. */
+export function estimateReadOutputTokens(result) {
+    return Math.ceil(Buffer.byteLength(JSON.stringify(result), "utf8") / 4);
+}
 /** Return whether a value is a non-array object record. */
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -30,7 +34,7 @@ export function updateReadOutputReceiptEstimate(result, receipt) {
     let estimate = receipt.estimated_tokens;
     for (let iteration = 0; iteration < MAX_ESTIMATE_ITERATIONS; iteration += 1) {
         receipt.estimated_tokens = estimate;
-        const measured = Math.ceil(Buffer.byteLength(JSON.stringify(result), "utf8") / 4);
+        const measured = estimateReadOutputTokens(result);
         if (measured === estimate)
             return;
         estimate = measured;
@@ -38,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 = readOutputRowCollections(result)
-            .filter((collection) => (Array.isArray(collection.value)
-            ? collection.value.length
-            : Object.keys(collection.value).length) > 1)
+        const candidate = readOutputBudgetCollections(result)
+            .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)
@@ -57,16 +64,20 @@ 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];
             }
         }
         receipt.rows_compacted = true;
+        receipt.compacted_row_paths = [
+            ...new Set([...(receipt.compacted_row_paths ?? []), candidate.path]),
+        ].sort((left, right) => left.localeCompare(right));
         result.has_more = true;
         result.truncated = true;
         if (typeof result.count === "number") {
@@ -75,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=1726fdce-dc71-5707-ae75-b588691e813d
+//# debugId=737ac274-c165-5d1a-8b8e-cb5d57a81c46