@unbrained/pm-cli 2026.8.12 → 2026.8.14

package/dist/sdk/history-read.d.ts

@@ -37,6 +37,14 @@ export interface HistoryVerificationResult {
     current_item_hash?: string;
     /** Whether the supplied document matches the newest history hash. */
     current_matches_latest?: boolean;
+    /** Whether every governed workspace singleton matches the latest replayed state. */
+    workspace_state_matches_latest?: boolean;
+    /** Governed singleton paths whose JSON differs from the replayed value. */
+    workspace_state_mismatches?: string[];
+    /** Governed singleton paths absent from disk. */
+    workspace_state_missing?: string[];
+    /** Governed singleton paths unreadable as safe workspace-local JSON. */
+    workspace_state_unreadable?: string[];
 }
 /**
  * Verify a history chain and optionally compare it with a current document.

package/dist/sdk/history-read.js

@@ -7,7 +7,7 @@
  * systems without acquiring locks or appending history.
  */
 
-!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]="bccbd81b-988f-569d-8dbf-c0998d813953")}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]="04f5d4d2-4021-5ce2-b35a-2134d98d2ad7")}catch(e){}}();
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
 import { pathExists } from "../core/fs/fs-utils.js";
 import { applyHistoryPatch, ensureMaterializedHistoryTarget, extractPatchFailureContext, replayHistoryToTarget, resolveHistoryTarget, } from "../core/history/projection.js";
@@ -85,4 +85,4 @@ export async function getItemAt(id, target, options = {}) {
 }
 export { applyHistoryPatch, ensureMaterializedHistoryTarget, extractPatchFailureContext, readHistoryEntries, replayHistoryToTarget, resolveHistoryTarget, };
 //# sourceMappingURL=history-read.js.map
-//# debugId=bccbd81b-988f-569d-8dbf-c0998d813953
+//# debugId=04f5d4d2-4021-5ce2-b35a-2134d98d2ad7

package/dist/sdk/index.d.ts

@@ -58,6 +58,7 @@ export * from "./compose.js";
 export * from "./governance/assurance.js";
 export * from "./governance/assurance-action.js";
 export * from "./governance/assurance-runtime.js";
+export * from "./governance/assurance-presets.js";
 export * from "./compile-cache.js";
 export * from "./environment/project-runtime-compatibility.js";
 export * from "./environment/source-context.js";
@@ -83,7 +84,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, type WorkspaceAuditEventOptions, type WorkspaceHistoryChange, type WorkspaceJsonMutation, type WorkspaceJsonMutationOptions, type WorkspaceJsonWriteOptions, } from "../core/history/workspace-history.js";
+export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, inspectWorkspaceHistoryState, mutateWorkspaceJsonWithHistory, reconcileWorkspaceJsonHistory, restoreWorkspaceJsonFromHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, type WorkspaceAuditEventOptions, type WorkspaceHistoryChange, type WorkspaceHistoryStateAgreement, type WorkspaceJsonMutation, type WorkspaceJsonMutationOptions, type WorkspaceJsonReconciliationOptions, type WorkspaceJsonRestoreOptions, type WorkspaceJsonRestoreResult, type WorkspaceJsonWriteOptions, } from "../core/history/workspace-history.js";
 export * from "./history-redact.js";
 export { _testOnly } from "./history-redact.js";
 export * from "./history-repair.js";
@@ -94,7 +95,7 @@ export { runDeps, type DepsCollapseMode, type DepsFormat, type DepsGraphEdge, ty
 export * from "./graph/index.js";
 export { runDocs } from "./docs.js";
 export { runFiles, runFilesDiscover, runFilesLookup, type FilesDiscoveryCandidate, type FilesLookupItem, type FilesLookupMatch, } from "./files.js";
-export { applyPathMigrations, applyStandaloneNote, artifactKey, dedupeLinkedArtifacts, ensureScope, expandAddGlobEntries, normalizeLinkedPath, parseAddEntries, parseAddGlobEntries, parseMigrateEntries, parseRemoveEntries, renameArtifactsResultKey, runLinkedArtifacts, sortLinkedArtifacts, validateLinkedPaths, type AddGlobEntry, type LinkedArtifact, type LinkedArtifactCommandOptions, type LinkedArtifactKindConfig, type LinkedArtifactResult, type LinkedPathValidation, type PathMigration, } from "./linked-artifacts.js";
+export { applyPathMigrations, applyStandaloneNote, artifactKey, assertLinkedArtifactMutationIsUnambiguous, dedupeLinkedArtifacts, ensureScope, expandAddGlobEntries, normalizeLinkedPath, parseAddEntries, parseAddGlobEntries, parseMigrateEntries, parseRemoveEntries, renameArtifactsResultKey, runLinkedArtifacts, sortLinkedArtifacts, validateLinkedPaths, type AddGlobEntry, type LinkedArtifact, type LinkedArtifactCommandOptions, type LinkedArtifactKindConfig, type LinkedArtifactResult, type LinkedPathValidation, type PathMigration, } from "./linked-artifacts.js";
 export * from "./pagination.js";
 export * from "./query/item-filter-options.js";
 export * from "./query/parsers.js";

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]="14672b89-6a87-59a0-8164-6b01a9c91ee1")}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";
@@ -56,6 +56,7 @@ export * from "./compose.js";
 export * from "./governance/assurance.js";
 export * from "./governance/assurance-action.js";
 export * from "./governance/assurance-runtime.js";
+export * from "./governance/assurance-presets.js";
 export * from "./compile-cache.js";
 export * from "./environment/project-runtime-compatibility.js";
 export * from "./environment/source-context.js";
@@ -81,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";
@@ -92,7 +93,7 @@ export { runDeps, } from "./dependencies.js";
 export * from "./graph/index.js";
 export { runDocs } from "./docs.js";
 export { runFiles, runFilesDiscover, runFilesLookup, } from "./files.js";
-export { applyPathMigrations, applyStandaloneNote, artifactKey, dedupeLinkedArtifacts, ensureScope, expandAddGlobEntries, normalizeLinkedPath, parseAddEntries, parseAddGlobEntries, parseMigrateEntries, parseRemoveEntries, renameArtifactsResultKey, runLinkedArtifacts, sortLinkedArtifacts, validateLinkedPaths, } from "./linked-artifacts.js";
+export { applyPathMigrations, applyStandaloneNote, artifactKey, assertLinkedArtifactMutationIsUnambiguous, dedupeLinkedArtifacts, ensureScope, expandAddGlobEntries, normalizeLinkedPath, parseAddEntries, parseAddGlobEntries, parseMigrateEntries, parseRemoveEntries, renameArtifactsResultKey, runLinkedArtifacts, sortLinkedArtifacts, validateLinkedPaths, } from "./linked-artifacts.js";
 export * from "./pagination.js";
 export * from "./query/item-filter-options.js";
 export * from "./query/parsers.js";
@@ -150,4 +151,4 @@ export * from "./governance.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=14672b89-6a87-59a0-8164-6b01a9c91ee1
+//# debugId=a05170b2-a48d-5275-ac04-aafc9f8315b2

package/dist/sdk/linked-artifacts.d.ts

@@ -115,6 +115,8 @@ export declare function parseRemoveEntries(raw: string[] | undefined): string[];
 export declare function parseMigrateEntries(raw: string[] | undefined): PathMigration[];
 /** Implements apply path migrations for the public runtime surface of this module. */
 export declare function applyPathMigrations(artifactPath: string, migrations: PathMigration[]): string;
+/** Reject a transaction that resolves the same linked path into both add and remove sets. */
+export declare function assertLinkedArtifactMutationIsUnambiguous(adds: LinkedArtifact[], removes: string[], migrations?: PathMigration[]): void;
 /** Implements normalize linked path for the public runtime surface of this module. */
 export declare function normalizeLinkedPath(value: string): string;
 /** Anchor a local linked path to the project workspace while preserving remote references and absolute paths. */

package/dist/sdk/linked-artifacts.js

@@ -4,11 +4,11 @@
  * 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]="3fe80124-596b-591c-9f0d-fbbc129c6bb4")}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]="585364aa-e5ff-56b6-8276-8f741fbd6be4")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import fg from "fast-glob";
-import { pathExists } from "../core/fs/fs-utils.js";
+import { isFileAbsentError, pathExists } from "../core/fs/fs-utils.js";
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
 import { assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, parseCsvKv, } from "../core/item/parse.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
@@ -179,6 +179,30 @@ export function applyPathMigrations(artifactPath, migrations) {
     }
     return next;
 }
+/** Reject a transaction that resolves the same linked path into both add and remove sets. */
+export function assertLinkedArtifactMutationIsUnambiguous(adds, removes, migrations = []) {
+    if (adds.length === 0 || removes.length === 0) {
+        return;
+    }
+    const addedPaths = new Set(adds.map((entry) => applyPathMigrations(entry.path, migrations)));
+    const conflicts = [
+        ...new Set(removes
+            .map((entry) => applyPathMigrations(entry, migrations))
+            .filter((entry) => addedPaths.has(entry))),
+    ].sort((left, right) => left.localeCompare(right));
+    if (conflicts.length === 0) {
+        return;
+    }
+    throw new PmCliError(`Linked artifact mutation cannot add and remove the same normalized path in one transaction: ${conflicts.join(", ")}. Split the replacement into separate commands so each history event has one unambiguous intent.`, EXIT_CODE.USAGE, {
+        code: "linked_artifact_mutation_conflict",
+        reason: "same_path_added_and_removed",
+        required: "Use distinct normalized paths for --add and --remove in one invocation.",
+        why: "Conflicting batch intent cannot be applied deterministically without silently discarding metadata or a removal.",
+        nextSteps: [
+            "Run the removal and addition as separate commands with a --message describing each intent.",
+        ],
+    });
+}
 /** Implements normalize linked path for the public runtime surface of this module. */
 export function normalizeLinkedPath(value) {
     return value.split(path.sep).join("/");
@@ -293,7 +317,7 @@ export async function validateLinkedPaths(paths, workspaceRoot = process.cwd())
             if (typeof error === "object" &&
                 error !== null &&
                 "code" in error &&
-                error.code === "ENOENT") {
+                isFileAbsentError(error)) {
                 missingPaths.push(relativePath);
                 continue;
             }
@@ -384,6 +408,7 @@ export async function runLinkedArtifacts(id, options, global, config) {
     const adds = applyStandaloneNote([...parsedAdds, ...expandedGlobAdds], options.note, parsedAdds.length > 0 || addGlobs.length > 0);
     const removes = parseRemoveEntries(resolvedRemoves).map((entry) => anchorLinkedPath(entry, workspaceRoot, invocationRoot));
     const migrations = parseMigrateEntries(resolvedMigrations);
+    assertLinkedArtifactMutationIsUnambiguous(adds, removes, migrations);
     const shouldMutate = adds.length > 0 || removes.length > 0 || migrations.length > 0;
     if (!shouldMutate) {
         const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
@@ -454,4 +479,4 @@ export function renameArtifactsResultKey(result, key) {
     return out;
 }
 //# sourceMappingURL=linked-artifacts.js.map
-//# debugId=3fe80124-596b-591c-9f0d-fbbc129c6bb4
+//# debugId=585364aa-e5ff-56b6-8276-8f741fbd6be4

package/dist/sdk/merge/install.js

@@ -8,7 +8,8 @@
  * mutations refresh the fenced block automatically once it is installed.
  */
 
-!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]="94d2a7a8-ce00-5689-b2f6-3d4813234b55")}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]="5e1810a5-04b8-5929-8eee-7a63f1684860")}catch(e){}}();
+import { isFileMissingError } from "../../core/fs/fs-utils.js";
 import { readFile, realpath, writeFile } from "node:fs/promises";
 import { execFile } from "node:child_process";
 import path from "node:path";
@@ -253,7 +254,7 @@ async function reconcileGitattributesBlock(workspaceRoot, patterns, dryRun) {
         current = await readFile(gitattributesPath, "utf8");
     }
     catch (error) {
-        if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+        if (!(error instanceof Error && "code" in error && isFileMissingError(error))) {
             throw error;
         }
     }
@@ -414,7 +415,7 @@ export async function refreshMergeAttributeFenceIfInstalled(pmRoot) {
         catch (error) {
             if (error instanceof Error &&
                 "code" in error &&
-                error.code === "ENOENT") {
+                isFileMissingError(error)) {
                 return { status: "not_installed", path: gitattributesPath };
             }
             throw error;
@@ -560,4 +561,4 @@ export async function installMergeFence(options) {
     };
 }
 //# sourceMappingURL=install.js.map
-//# debugId=94d2a7a8-ce00-5689-b2f6-3d4813234b55
+//# debugId=5e1810a5-04b8-5929-8eee-7a63f1684860

package/dist/sdk/query/activity.js

@@ -4,7 +4,8 @@
  * Implements the pm activity 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]="27a71d4d-f496-5d0a-9771-caa43b81e1f7")}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]="49304d18-d722-5413-8e4d-4f2c3df4a1ca")}catch(e){}}();
+import { isFileMissingError } from "../../core/fs/fs-utils.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations, runActiveOnReadHooks, pathExists, enforceHistoryStreamPolicyForItems, resolveItemTypeRegistry, EXIT_CODE, PmCliError, compareTimestampStrings, nowIso, resolveIsoOrRelative, listAllItemMetadataLight, getSettingsPath, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
@@ -107,7 +108,7 @@ async function listHistoryFiles(historyDir) {
     }
     catch (error) {
         // Activity should degrade gracefully when optional history storage is absent.
-        if (error.code === "ENOENT") {
+        if (isFileMissingError(error)) {
             return [];
         }
         throw error;
@@ -399,4 +400,4 @@ export async function runActivity(options, global) {
     };
 }
 //# sourceMappingURL=activity.js.map
-//# debugId=27a71d4d-f496-5d0a-9771-caa43b81e1f7
+//# debugId=49304d18-d722-5413-8e4d-4f2c3df4a1ca

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-budget.d.ts

@@ -5,6 +5,8 @@
  * 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. */

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]="cc595424-0176-5920-8f4c-d935e6a546ce")}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;
@@ -43,7 +47,7 @@ function compactRowsToBudget(result, receipt, budget) {
         updateReadOutputReceiptEstimate(result, receipt);
         if (receipt.estimated_tokens <= budget)
             return;
-        const candidate = readOutputRowCollections(result)
+        const candidate = readOutputBudgetCollections(result)
             .filter((collection) => (Array.isArray(collection.value)
             ? collection.value.length
             : Object.keys(collection.value).length) > 1)
@@ -67,6 +71,9 @@ function compactRowsToBudget(result, receipt, budget) {
             }
         }
         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") {
@@ -85,4 +92,4 @@ export function compactReadOutputToBudget(result, receipt, budget) {
     return compacted;
 }
 //# sourceMappingURL=read-output-budget.js.map
-//# debugId=1726fdce-dc71-5707-ae75-b588691e813d
+//# debugId=cc595424-0176-5920-8f4c-d935e6a546ce

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

@@ -4,7 +4,7 @@ export declare const PM_READ_OUTPUT_DIMENSIONS: readonly ["include", "amount", "
 /** One member of the universal read-output dimension set. */
 export type PmReadOutputDimension = (typeof PM_READ_OUTPUT_DIMENSIONS)[number];
 /** Built-in command roots whose primary operation is a read. */
-export declare const PM_READ_OUTPUT_SURFACES: readonly ["list", "context", "search", "get", "next", "health", "deps", "graph", "history", "activity", "validate", "events", "contracts", "comments", "notes", "files", "docs", "stats", "aggregate", "package-manage"];
+export declare const PM_READ_OUTPUT_SURFACES: readonly ["list", "context", "search", "get", "next", "health", "deps", "graph", "history", "activity", "validate", "events", "contracts", "comments", "notes", "files", "docs", "stats", "aggregate", "package-manage", "comments-audit", "assurance"];
 /** Built-in read command supported by the universal output contract. */
 export type PmReadOutputSurface = (typeof PM_READ_OUTPUT_SURFACES)[number];
 /** Canonical output controls accepted by every built-in read action. */
@@ -13,8 +13,8 @@ export interface PmReadOutputOptions {
     outputInclude?: string | string[];
     /** Maximum rows retained, or `unbounded` to disable the shared row ceiling. */
     outputLimit?: string | number | "unbounded";
-    /** Maximum estimated result tokens. */
-    outputBudget?: string | number;
+    /** Maximum estimated result tokens, or `unbounded` to disable the default ceiling. */
+    outputBudget?: string | number | "unbounded";
     /** Requested static renderer encoding; streaming remains a command behavior. */
     outputFormat?: "json" | "toon";
     /** Caller-carried cross-call budget and served-fact state. */
@@ -26,6 +26,8 @@ export interface PmReadOutputOptions {
 export interface PmReadOutputLegacyAlias {
     /** Historical CLI spelling. */
     flag: string;
+    /** Strength of the migration promise carried by this alias. */
+    semantics?: "replacement" | "behavior_preserving";
     /** One-line migration instruction for agents and help generators. */
     migration_hint: string;
     /** Compatibility aliases are accepted but omitted from the canonical vocabulary. */
@@ -70,8 +72,8 @@ export interface PmResolvedReadOutputDimensions {
     include?: PmResolvedReadOutputDimension<string[]>;
     /** Requested row ceiling. */
     amount?: PmResolvedReadOutputDimension<number | "unbounded">;
-    /** Requested estimated-token ceiling. */
-    cost?: PmResolvedReadOutputDimension<number>;
+    /** Requested estimated-token ceiling or explicit opt-out. */
+    cost?: PmResolvedReadOutputDimension<number | "unbounded">;
     /** Requested static encoding or a retained legacy streaming behavior. */
     encoding?: PmResolvedReadOutputDimension<"json" | "toon" | "stream">;
     /** Compatibility flags observed on the invocation. */
@@ -89,6 +91,10 @@ export interface PmReadOutputReceipt {
     command: PmReadOutputSurface;
     /** Dimensions explicitly or compatibly requested by the invocation. */
     requested_dimensions: PmReadOutputDimension[];
+    /** Layer that supplied an automatically applied token ceiling. */
+    budget_source?: "default";
+    /** Automatically applied token ceiling; explicit/session budgets already disclose their value. */
+    budget_tokens?: number;
     /** Deterministic precedence used during resolution. */
     precedence: readonly ["canonical", "legacy", "intent", "default"];
     /** Compatibility options observed on the invocation. */
@@ -103,8 +109,27 @@ export interface PmReadOutputReceipt {
     strings_compacted: boolean;
     /** Whether row collections were reduced while satisfying the cost ceiling. */
     rows_compacted: boolean;
+    /** Declared or nested collection paths reduced by budget degradation. */
+    compacted_row_paths?: string[];
     /** Whether the requested cost ceiling forced the useful result to be omitted. */
     result_omitted: boolean;
+    /** Estimated tokens in the useful result immediately before whole-result omission. */
+    omitted_result_estimated_tokens?: number;
+}
+/** Machine-readable explanation of budget-driven row degradation. */
+export interface PmReadOutputTruncationDisclosure {
+    /** Stable reason for dropping rows. */
+    reason: "output_budget_reached";
+    /** Layer that supplied the binding ceiling. */
+    budget_source: PmReadOutputDimensionSource | "session";
+    /** Binding estimated-token ceiling. */
+    budget_tokens: number;
+    /** Explicit dimensions whose unbounded request was overridden by the ceiling. */
+    overridden_dimensions: PmReadOutputDimension[];
+    /** Declared or nested collection paths reduced by budget degradation. */
+    compacted_row_paths: string[];
+    /** Executable recovery instruction for retrieving the complete result. */
+    restore_with: string;
 }
 /** Result returned when the requested cost ceiling cannot fit useful content. */
 export interface PmReadOutputBudgetExceeded {
@@ -124,6 +149,7 @@ export interface PmReadOutputBudgetExceeded {
 export type PmReadOutputResult<Result> = (Result & {
     read_output?: PmReadOutputReceipt;
     read_session?: PmReadOutputSessionReceipt;
+    output_budget_truncation?: PmReadOutputTruncationDisclosure;
 }) | (PmReadOutputBudgetExceeded & {
     read_session?: PmReadOutputSessionReceipt;
 });
@@ -139,6 +165,36 @@ export declare const PM_READ_OUTPUT_SURFACE_CONTRACTS: readonly PmReadOutputSurf
 export declare function resolveReadOutputSurface(command: string): PmReadOutputSurface | undefined;
 /** Reject malformed or mutation-scoped universal output controls before command execution. */
 export declare function validateReadOutputOptions(command: string, options: Record<string, unknown>): void;
+/**
+ * Map every canonical `--output-include` token that names a projection mode
+ * rather than a row field onto the command-local option that mode already owns.
+ *
+ * The include dimension folds two kinds of legacy alias into one canonical
+ * spelling: value-bearing selectors (`--fields`, `--section`) that name row
+ * fields, and mode flags (`--brief`, `--full`, `--summary`, ...) that select a
+ * whole declared projection. Only the first kind can be honoured by projecting
+ * an already-computed result, so mode tokens have to reach the command itself.
+ */
+export declare function readOutputIncludeModeOptions(command: string): ReadonlyMap<string, string>;
+/**
+ * Translate canonical projection-mode tokens into the command-local options
+ * they alias, so the spelling the migration hints recommend is behaviour
+ * identical to the legacy flag it replaces, and return the field selectors that
+ * remain for post-execution projection.
+ */
+export declare function applyReadOutputIncludeModes(command: string, includeValue: unknown, commandOptions: Record<string, unknown>): {
+    selectors: string[];
+    modes: string[];
+};
+/**
+ * Resolve canonical include modes against one combined options bag, rewriting
+ * the include value in place to the selectors that remain.
+ *
+ * Used by dispatch paths that carry command options and universal output
+ * controls in a single record, so an action honours a mode token exactly as the
+ * CLI does.
+ */
+export declare function normalizeReadOutputIncludeModeOptions(command: string, options: Record<string, unknown>): void;
 /** Resolve canonical and compatibility controls into the universal dimension set. */
 export declare function resolveReadOutputDimensions(command: string, options: Record<string, unknown>): PmResolvedReadOutputDimensions | undefined;
 /** Recompute read and optional session receipts after a final envelope projection. */