@unbrained/pm-cli 2026.8.14 → 2026.8.15

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]="f9774018-a5b7-505e-a8ea-cba08392afeb")}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,8 @@ 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";
     const budget = resolvePmCommandOutputBudget(command, {
         generateFallback: true,
     });
@@ -496,10 +510,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 +530,8 @@ const ENVELOPE_KEYS = new Set([
     "applied_bound",
     "applied_limit",
     "completeness",
+    "continuation_kind",
+    "continuation_path",
     "continuation_contract",
     "count",
     "filters",
@@ -521,6 +540,7 @@ const ENVELOPE_KEYS = new Set([
     "now",
     "omission_receipt",
     "projection",
+    "budget_retention_policy",
     "row_contract",
     "sorting",
     "total",
@@ -715,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);
     }
@@ -774,7 +798,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 +821,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 +838,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 +1033,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 +1056,4 @@ export function resolveReadOutputEncoding(command, options) {
         : undefined;
 }
 //# sourceMappingURL=read-output-contracts.js.map
-//# debugId=c78ba845-78ae-5b16-b486-c279f834d601
+//# debugId=f9774018-a5b7-505e-a8ea-cba08392afeb

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

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

@@ -5,11 +5,14 @@
  * envelopes, including dot-delimited nested paths used by graph projections.
  */
 
-!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]="03e25a43-f05c-5bc6-a42a-140914e522d5")}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]="0c69ff43-7bbc-5128-9533-bbf15365126b")}catch(e){}}();
 const BUDGET_METADATA_ROOT_KEYS = new Set([
     "applied_bound",
     "completeness",
+    "budget_retention_policy",
     "continuation_contract",
+    "continuation_kind",
+    "continuation_path",
     "filters",
     "omission_receipt",
     "output_budget_truncation",
@@ -48,6 +51,16 @@ function replaceValueAtPath(result, rowPath, replacement) {
     target[segments.at(-1)] = replacement;
     return root;
 }
+/** Replace one declared row collection with a suffix beginning at an offset. */
+export function sliceReadOutputRowCollection(result, rowPath, offset) {
+    const collection = readOutputRowCollections(result).find((entry) => entry.path === rowPath);
+    if (!collection)
+        return result;
+    const replacement = Array.isArray(collection.value)
+        ? collection.value.slice(offset)
+        : Object.fromEntries(Object.entries(collection.value).slice(offset));
+    return replaceValueAtPath(result, rowPath, replacement);
+}
 /** Resolve declared row paths, falling back to top-level array properties. */
 export function readOutputRowPaths(result) {
     const contract = result.row_contract;
@@ -142,4 +155,4 @@ export function boundReadOutputRows(result, amount) {
     return { result: projected, truncated };
 }
 //# sourceMappingURL=read-output-rows.js.map
-//# debugId=03e25a43-f05c-5bc6-a42a-140914e522d5
+//# debugId=0c69ff43-7bbc-5128-9533-bbf15365126b

package/dist/sdk/runtime-input.js

@@ -5,7 +5,7 @@
  * primitives are shared by native action dispatchers and MCP-specific adapters.
  */
 
-!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]="bcda2578-3b01-5e64-9d53-cd32c0f927b8")}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]="0e153ece-4fc0-5134-97f0-c2315aff0031")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { asRecordClone } from "../core/shared/primitives.js";
@@ -83,6 +83,7 @@ export function actionGlobalOptions(args) {
         outputLimit: readRuntimeScalarString(args, "outputLimit"),
         outputBudget: readRuntimeScalarString(args, "outputBudget"),
         outputSession: readRuntimeString(args, "outputSession"),
+        outputCursor: readRuntimeString(args, "outputCursor"),
         outputFormat: outputFormat === "json" || outputFormat === "toon"
             ? outputFormat
             : undefined,
@@ -167,6 +168,7 @@ const UNIVERSAL_READ_OUTPUT_OPTION_KEYS = [
     "outputBudget",
     "outputFormat",
     "outputSession",
+    "outputCursor",
 ];
 /** Reconcile MCP array/scalar option spellings with CLI flag expectations. */
 export function normalizeMcpOptionsArrays(options, action) {
@@ -501,4 +503,4 @@ export function updateManyOptionsFromFlat(options) {
     };
 }
 //# sourceMappingURL=runtime-input.js.map
-//# debugId=bcda2578-3b01-5e64-9d53-cd32c0f927b8
+//# debugId=0e153ece-4fc0-5134-97f0-c2315aff0031

package/docs/ASSURANCE.md

@@ -1,6 +1,6 @@
 # Project Assurance Primitives
 
-Tracker: [pm-2lex4r](../.agents/pm/features/pm-2lex4r.toon), [pm-lyfu7b](../.agents/pm/features/pm-lyfu7b.toon), [pm-wn6wot](../.agents/pm/features/pm-wn6wot.toon), [pm-91xeam](../.agents/pm/features/pm-91xeam.toon), [pm-uhv1m5](../.agents/pm/features/pm-uhv1m5.toon), [pm-m7bb7r](../.agents/pm/features/pm-m7bb7r.toon), [pm-py7qv2](../.agents/pm/issues/pm-py7qv2.toon), [pm-33mjrw](../.agents/pm/issues/pm-33mjrw.toon), [pm-q6n8sj](../.agents/pm/issues/pm-q6n8sj.toon), [pm-h06944](../.agents/pm/issues/pm-h06944.toon), [pm-dwj33e](../.agents/pm/decisions/pm-dwj33e.toon)
+Tracker: [pm-2lex4r](../.agents/pm/features/pm-2lex4r.toon), [pm-lyfu7b](../.agents/pm/features/pm-lyfu7b.toon), [pm-wn6wot](../.agents/pm/features/pm-wn6wot.toon), [pm-91xeam](../.agents/pm/features/pm-91xeam.toon), [pm-uhv1m5](../.agents/pm/features/pm-uhv1m5.toon), [pm-m7bb7r](../.agents/pm/features/pm-m7bb7r.toon), [pm-py7qv2](../.agents/pm/issues/pm-py7qv2.toon), [pm-33mjrw](../.agents/pm/issues/pm-33mjrw.toon), [pm-q6n8sj](../.agents/pm/issues/pm-q6n8sj.toon), [pm-h06944](../.agents/pm/issues/pm-h06944.toon), [pm-88mo8m](../.agents/pm/issues/pm-88mo8m.toon), [pm-atnfh4](../.agents/pm/issues/pm-atnfh4.toon), [pm-xmmafu](../.agents/pm/issues/pm-xmmafu.toon), [pm-4ok4ex](../.agents/pm/tasks/pm-4ok4ex.toon), [pm-dwj33e](../.agents/pm/decisions/pm-dwj33e.toon)
 
 ## Agent Quick Context
 
@@ -43,6 +43,14 @@ Measurements support these built-in sources:
 | `derived`         | Combine numeric measurements with deterministic arithmetic and cycle detection.                                                          |
 | `provider`        | Delegate a measurement to an explicitly supplied host/package resolver.                                                                  |
 
+`ASSURANCE_MEASUREMENT_SOURCE_KINDS` and `ASSURANCE_GATE_TRIGGERS` are the
+public SDK constants for these closed vocabularies. Runtime validation rejects
+missing arrays and unknown discriminants with `AssuranceMutationRefusalError`;
+it never persists an unrecognized source or leaks an incidental JavaScript
+property-access error. Hosts that generate forms or package schemas can obtain
+the same values from `pm contracts --command assurance --json` under
+`assurance_contracts`.
+
 Each measurement may declare `max_cost`. Evaluation fails closed when the total abstract compute units exceed that ceiling. Every result reports units, scanned items, scanned history rows, provider calls, duration, population size, and contributors.
 
 One workspace context memoizes identical graph operations and the shared
@@ -263,15 +271,64 @@ await pm.assurance({
 });
 ```
 
-For direct host composition, use `evaluateMeasurement`, `evaluateAssuranceGate`, `createAssuranceWorkspaceContext`, the preset/derivation helpers, and the audited declaration/verdict helpers exported from `@unbrained/pm-cli/sdk`. Active extension registrations are discovered automatically. Embedding hosts may additionally pass stable resolver ids and matching `provider_capabilities` to `createAssuranceWorkspaceContext`; an absent resolver or capability fails loudly. The core evaluator bounds concurrent assertions and expression operands, and workspace history loading uses bounded concurrency; item-only callers can explicitly skip history and Git identity resolution.
+For direct host composition, use `evaluateMeasurement`, `evaluateAssuranceGate`, `createAssuranceWorkspaceContext`, the preset/derivation helpers, and the audited declaration/verdict helpers exported from `@unbrained/pm-cli/sdk` and its focused `@unbrained/pm-cli/sdk/governance` entrypoint. Active extension registrations are discovered automatically. Embedding hosts may additionally pass stable resolver ids and matching `provider_capabilities` to `createAssuranceWorkspaceContext`; an absent resolver or capability fails loudly. The core evaluator bounds concurrent assertions and expression operands, and workspace history loading uses bounded concurrency; item-only callers can explicitly skip history and Git identity resolution.
+
+Hosts that want the normal action transport and its audited registry lookup can
+pass the same adapters as the third `runAssuranceAction` argument. The request
+and project path remain transport data; resolver capabilities remain explicit
+runtime authority:
+
+```ts
+await runAssuranceAction(
+  {
+    action: "run",
+    id: "repository-static-quality",
+    trigger: "ci",
+    dry_run: true,
+  },
+  { path: ".agents/pm" },
+  {
+    workspace: {
+      include_history: false,
+      providers: {
+        "repository-quality": resolveRepositoryQualityMeasurement,
+      },
+      provider_capabilities: {
+        "repository-quality": { cost_class: "high", network: false },
+      },
+    },
+  },
+);
+```
+
+This is the migration boundary for repository automation: scripts may remain
+focused process adapters, while assertion composition, provider policy,
+negative controls, lifecycle triggers, and verdicts move into ordinary
+assurance declarations. `scripts/release/gate-registry.json` records every
+gate script as migrated, provider-backed, or retained and fails unless the
+migrated/provider-backed population is the majority.
+
+`AssuranceMutationRefusalError` and `AssuranceEvaluationRefusalError` are
+exported from both `@unbrained/pm-cli/sdk` and
+`@unbrained/pm-cli/sdk/governance`, so hosts can classify expected declaration
+or evaluation refusals without parsing messages. Source-resolution refusals
+also carry the gate, assertion, measurement, source kind, field, and optional
+health/validate check, so a zero value remains distinct from an absent or
+mistyped field.
 
 Generic SDK and MCP dispatch use `action: "assurance"` with `subcommand` set to `list`, `show`, `put`, `remove`, `run`, `verdicts`, `presets`, `apply`, `derive`, or `promote`. Discover the current machine contract instead of copying parameter lists:
 
 ```bash
 pm contracts --action assurance --schema-only --json
 pm contracts --command assurance --flags-only --json
+pm contracts --command assurance --json
 ```
 
+Command-scoped contract output omits unrelated extension, governance,
+relationship, and Commander-alias catalogs unless `--full` is requested. This
+keeps the selected action schema and its assurance vocabularies complete under
+the default output budget instead of truncating the very enum a caller needs.
+
 ## Verdict Contract
 
 A gate emits one object containing:

package/docs/COMMANDS.md

@@ -4,6 +4,8 @@ This is a task-oriented command guide. For exact flags, use runtime help because
 
 Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-qd3woa](../.agents/pm/issues/pm-qd3woa.toon), [pm-ypuc39](../.agents/pm/issues/pm-ypuc39.toon), [pm-tz2ikr](../.agents/pm/issues/pm-tz2ikr.toon), the schema-migration recovery contract [pm-s79kel](../.agents/pm/issues/pm-s79kel.toon), the lossless mutation contracts [pm-x3dq0l](../.agents/pm/issues/pm-x3dq0l.toon), [pm-lppm6y](../.agents/pm/issues/pm-lppm6y.toon), and [pm-embm6t](../.agents/pm/issues/pm-embm6t.toon), and the SDK-first agent grammar tranche [pm-p316vn](../.agents/pm/issues/pm-p316vn.toon), [pm-st7wgu](../.agents/pm/issues/pm-st7wgu.toon), [pm-mkinft](../.agents/pm/issues/pm-mkinft.toon), [pm-ulqu](../.agents/pm/issues/pm-ulqu.toon), [pm-qmjx](../.agents/pm/issues/pm-qmjx.toon), [pm-4bzq](../.agents/pm/features/pm-4bzq.toon), [pm-x2vx](../.agents/pm/issues/pm-x2vx.toon), and [pm-g543](../.agents/pm/issues/pm-g543.toon).
 
+Workspace-integrity contracts are tracked by [pm-22rzjp](../.agents/pm/issues/pm-22rzjp.toon), [pm-76fkpp](../.agents/pm/issues/pm-76fkpp.toon), [pm-igdvfq](../.agents/pm/issues/pm-igdvfq.toon), [pm-643e0k](../.agents/pm/issues/pm-643e0k.toon), and [pm-larv4r](../.agents/pm/issues/pm-larv4r.toon).
+
 ```bash
 pm <command> --help
 pm <command> --help --json
@@ -965,6 +967,8 @@ pm history-repair <id> --dry-run
 pm history-repair <id> --message "re-anchor legacy drift"
 pm history-repair --all --dry-run
 pm history-repair --all --message "bulk re-anchor drifted streams"
+pm history-repair --all --normalize-provenance --dry-run
+pm history-repair --all --normalize-provenance --message "normalize invalid legacy provenance"
 pm activity                         # item digest for the last 24 hours
 pm activity --raw --id <id> --limit 50
 pm activity --full --id <id> --limit 50
@@ -1020,8 +1024,10 @@ For governance dashboards, `--metadata-coverage` adds a `metadata_coverage` bloc
 `history-redact` rewrites matching history payloads deterministically, recomputes hash chains, and appends an auditable `history_redact` marker entry when changes are applied. Its result reports only `literal_count`, `regex_count`, `total_count`, and whether the default replacement was selected; literal values, regex source text, and replacement text are never echoed in CLI, SDK, MCP, recovery, profile, or telemetry output. Treat regex text as sensitive input because it can contain the exact material being removed.
 `history-compact` rewrites long streams into a synthetic checkpoint baseline plus a retained tail (`--before` accepts a 1-based version or ISO timestamp), re-anchors hashes, verifies integrity, and appends an auditable `history_compact` marker when applied.
 `history-compact` bulk mode (mutually exclusive with a positional `<id>`) compacts many streams in one audited pass. Select with `--ids <a,b,c>` (an explicit list — used on its own, not combined with the scan selectors below), or a scan: `--all-over <N>` (every stream with more than N entries) and/or a lifecycle filter `--closed` (terminal items only) or `--all-streams` (every stream). `--closed` and `--all-streams` are mutually exclusive. `--min-entries <N>` (default 3) skips already-compact streams; when `history.compact_policy` is enabled and `--all-over` is omitted, the policy's `max_entries` becomes the default threshold. `--before` is single-id only and is rejected in bulk mode. Each selected stream runs the same single-item compaction; one failing stream never aborts the rest — the result reports `totals` (`streams_considered`/`selected`/`items_compacted`/`items_skipped`/`items_errored`) plus one row per stream (`compacted`/`skipped` with a `skip_reason`/`errored`), and the command exits non-zero only if any stream errored.
-`history-repair` re-anchors a drifted history chain when `pm health`/`pm validate --check-history-drift` report stale hashes: it replays the stream, recomputes every before/after hash, repairs legacy patch ops that no longer strictly apply, reconciles the latest hash with the on-disk item, and appends an auditable `history_repair` marker. It never modifies item content and is a safe no-op on a clean stream.
-`history-repair --all` (mutually exclusive with `<id>`) runs the same drift scan `pm health` uses and applies the audited single-stream repair (ownership check, lock, post-repair no-drift verification, `--message` audit marker, per-stream `--force`) to every drifted stream in one pass. One failing stream never aborts the rest: the result lists one compact row per drifted stream (`repaired` / `skipped_clean` / `failed`) plus `totals`, and the command exits non-zero only if any stream failed.
+`history-repair` re-anchors a drifted history chain when `pm health`/`pm validate --check-history-drift` report stale hashes: it replays the stream, recomputes every before/after hash using the stream's detected hash epoch, repairs legacy patch ops that no longer strictly apply, reconciles the latest hash with the on-disk item, and appends an auditable `history_repair` marker. It never modifies item content and is a safe no-op on a clean stream. The result reports the before/after hash versions and whether the epoch was preserved or selected for an ambiguous broken stream, preventing old/new runtimes from alternately rewriting an otherwise consistent legacy chain.
+`history-repair --all` (mutually exclusive with `<id>`) runs the same drift scan `pm health` uses and applies the audited single-stream repair (ownership check, lock, post-repair no-drift verification, `--message` audit marker, per-stream `--force`) to every drifted stream in one pass. One failing stream never aborts the rest: the result lists one compact row per targeted stream (`repaired` / `skipped_clean` / `failed`) plus `totals`, and the command exits non-zero only if any stream failed. Add `--normalize-provenance` to include streams containing invalid boolean or single-digit provenance observations. The normalizer removes only those invalid observations and writes aggregate harness/dimension/kind counts in the audit receipt; it never echoes or retains the removed value.
+
+Every `pm health` projection exposes `findings` and `failed_because`. A finding binds one warning token to its owning check, stable code, `advisory|gate_failing` severity, and either an executable remediation or `no_safe_automatic_remediation`. Extension health also publishes `host_version_census`, which enumerates the host and every pm-cli copy resolved by loaded extensions across npm/pnpm layouts. A version mismatch makes the extension check non-clean; matching workspace-linked or deduplicated copies remain healthy.
 
 `pm health --verbose-author-events --json` includes the complete actionable unknown-author coordinate list and an explicit `samples_truncated` marker. After evidence review, `pm history-author-acknowledge --all-actionable --attributed-author <principal> --reviewer <reviewer> --reason <evidence>` records one append-only disposition for the current complete set. `--all-actionable` and repeatable `--event <item-id:line>` are mutually exclusive; reviewer, attributed author, and reason remain mandatory.
 

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -1,17 +1,17 @@
 # Universal Read Output Contracts
 
-Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), and [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.toon).
+Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.toon), [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon), [pm-e5gl05](../.agents/pm/issues/pm-e5gl05.toon), and [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon).
 
 ## Agent Quick Context
 
 Every built-in read surface uses four output dimensions: what to include, how much to return, how much the result may cost, and how to encode it. The same canonical controls work through the CLI, SDK, MCP, generated schemas, runtime contracts, and shell completions.
 
-| Dimension | CLI                             | SDK and MCP     | Meaning                                                                |
-| --------- | ------------------------------- | --------------- | ---------------------------------------------------------------------- |
-| Include   | `--output-include <csv>`        | `outputInclude` | Retain named fields or sections, or select a declared projection mode. |
-| Amount    | `--output-limit <n\|unbounded>` | `outputLimit`   | Bound shared row collections.                                          |
-| Cost      | `--output-budget <tokens>`      | `outputBudget`  | Fail closed when even the compact result cannot fit.                   |
-| Encoding  | `--output-format <toon\|json>`  | `outputFormat`  | Select the CLI renderer and record the requested encoding.             |
+| Dimension | CLI                              | SDK and MCP     | Meaning                                                                |
+| --------- | -------------------------------- | --------------- | ---------------------------------------------------------------------- |
+| Include   | `--output-include <csv>`         | `outputInclude` | Retain named fields or sections, or select a declared projection mode. |
+| Amount    | `--output-limit <n\|unbounded>`  | `outputLimit`   | Bound shared row collections.                                          |
+| Cost      | `--output-budget <n\|unbounded>` | `outputBudget`  | Fail closed when even the compact result cannot fit.                   |
+| Encoding  | `--output-format <toon\|json>`   | `outputFormat`  | Select the CLI renderer and record the requested encoding.             |
 
 The contract covers `list`, `context`, `search`, `get`, `next`, `health`, `deps`, `graph`, `history`, `activity`, `validate`, `events`, `contracts`, `comments`, `notes`, `files`, `docs`, `stats`, and `aggregate`, including list aliases and `ctx`.
 
@@ -117,6 +117,12 @@ tracker content.
 
 Resolution is deterministic: canonical controls win over command-local compatibility options, which win over intent defaults, which win over command defaults. Existing options such as `--fields`, `--limit`, `--token-budget`, `--format`, `--brief`, and `--full` remain accepted. Contract output marks them as hidden compatibility aliases and supplies a migration hint; traversal, cursor, side-effect, and streaming controls instead receive an explicit behavior-preservation hint because a static output control cannot replace their semantics. Callers that omit the four shaping dimensions retain the established data projection; the one intentional envelope correction is that repeated `row_contract` metadata is now opt-in.
 
+Completeness spellings preserve their established promise. `pm list-all` and
+list-family `--no-truncate` imply an unbounded cost dimension when the caller
+does not supply `--output-budget`; they cannot silently return a budget-trimmed
+subset while claiming to return every matched row. An explicit canonical
+budget still has precedence and may request a bounded result deliberately.
+
 ```bash
 pm list-open --output-include id,title,status --output-limit 10
 pm context --for orient --output-budget 900 --output-format toon
@@ -127,7 +133,41 @@ pm contracts --full --json
 
 Every projected result carries a `read_output` receipt with the requested dimensions, precedence, observed compatibility aliases, deterministic estimated token count, string/row compaction signals, and budget outcome. Budget degradation discovers nested arrays as well as declared result rows, so validation diagnostics and other governance payloads compact their inner findings before the useful result is omitted. `compacted_row_paths` names every reduced collection without redefining those nested arrays as ordinary pagination rows.
 
-When rows are dropped to satisfy a ceiling, the result also carries `output_budget_truncation`, naming the binding budget and its source, any explicitly requested dimension the budget overrode, every compacted collection path, and an executable recovery instruction — a default ceiling can override an explicit `--output-limit unbounded`, and that override is reported rather than silent. If no useful content can fit, `PmReadOutputBudgetExceeded` provides a discriminated omission result and reports `omitted_result_estimated_tokens`, the last useful-result estimate before omission; use `isReadOutputBudgetExceeded` before accessing result-specific fields. Universal controls are rejected on mutation commands and on the mutation mode of hybrid commands such as `comments`, `notes`, `files`, and `docs`.
+When rows are dropped to satisfy a ceiling, the result also carries `output_budget_truncation`, naming the binding budget and its source, any explicitly requested dimension the budget overrode, every compacted collection path, and executable CLI/SDK/MCP recovery options — a default ceiling can override an explicit `--output-limit unbounded`, and that override is reported rather than silent. If a producer supplied an opaque item-page cursor, compaction rebases it to the last row actually returned and reports `continuation_cursor_rebased: true`; following the cursor therefore cannot skip rows removed from the middle of a producer page. If no useful content can fit, `PmReadOutputBudgetExceeded` provides a discriminated omission result, a compact `{ outputBudget: "unbounded" }` recovery object, and `omitted_result_estimated_tokens`, the last useful-result estimate before omission; use `isReadOutputBudgetExceeded` before accessing result-specific fields. Universal controls are rejected on mutation commands and on the mutation mode of hybrid commands such as `comments`, `notes`, `files`, and `docs`.
+
+Cursor recovery carries the opaque value once in `recovery.cursor` and declares
+the accepting `cli`, `sdk`, and `mcp` binding beside it. This avoids
+serializing the same cursor once per transport while retaining an executable,
+machine-readable binding for each surface.
+
+Budget-compacted declared row paths are independently resumable. The
+disclosure's `continuations` entries name the row path, retained/remaining/total
+counts, and an opaque cursor. `continuation_kind` distinguishes a rebased
+producer cursor, a universal output cursor, and a terminal page;
+`next_cursor` mirrors the first universal entry for ordinary one-path
+consumers. Replay the same query and budget
+with `--output-cursor <cursor>` / `outputCursor`. The cursor validates the
+command, declared row path, total, and stable row identities before slicing, so
+a mismatched or stale replay fails closed instead of skipping evidence. A
+bounded recovery therefore does not require replacing a 600-token request with
+an unbounded multi-megabyte response;
+`recovery_budget_multiplier: 1` declares that each next page retains the same
+useful-result ceiling.
+
+Assurance declares `budget_retention_policy: verdict_priority`: failing block,
+warn, and observe rows precede retired and passing rows while preserving order
+within each class. `assertions_total` remains the pre-projection denominator,
+and the `assertions` row path uses the same continuation primitive. A blocking
+verdict consequently keeps its causal evidence on the first bounded page even
+when the failing assertion was declared last.
+
+Diagnostic gates retain bounded, actionable predicates. Every metadata field
+required by the active validation profile emits a numeric count, including
+zero, so assurance expressions can distinguish a clean check from a missing
+key. Health retains at most 100 warning rows and reports `warning_count`,
+`warning_limit`, and `warnings_truncated`; `--strict-exit` defaults to summary
+projection unless `--full` is explicit, keeping the failing check identities
+and warning codes inside the ordinary budget.
 
 ## SDK and Package Usage
 
@@ -150,6 +190,7 @@ const result = await pm.list({
     spent_tokens: 0,
     seen_item_ids: [],
   },
+  // Supply outputCursor from output_budget_truncation to fetch the next row page.
 });
 ```