@unbrained/pm-cli 2026.8.14 → 2026.8.15

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/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

@@ -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. */