@unbrained/pm-cli 2026.8.17 → 2026.8.19

package/dist/sdk/query/get.js

@@ -4,9 +4,10 @@
  * Implements the SDK-owned item query shared by every surface.
  */
 
-!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]="c35e787c-a9a1-5ffa-9dcf-62780fceed4c")}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]="1ba3eb17-c44c-5b62-8ae0-c2506fca9c62")}catch(e){}}();
 import { pathExists, getActiveExtensionRegistrations, toItemRecord, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, ITEM_METADATA_KEY_ORDER, TYPE_TO_FOLDER, PmCliError, buildItemNotFoundError, listAllItemMetadataLight, locateItem, readLocatedItem, getHistoryPath, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { readHistoryEntries } from "../history-read.js";
+import { renderPmCommand } from "../command-line.js";
 import { recordContextUsageTouches } from "../context-usage.js";
 import { buildItemChildrenRollup, } from "../item-children.js";
 import { buildItemSchedule, } from "../item-schedule.js";
@@ -142,7 +143,7 @@ function parseGetFields(raw) {
 function normalizeGetField(field) {
     return field.startsWith("item.") ? field.slice("item.".length) : field;
 }
-function validateGetFields(fields, runtimeMetadataKeys) {
+function validateGetFields(fields, runtimeMetadataKeys, id) {
     if (fields === null) {
         return;
     }
@@ -179,6 +180,13 @@ function validateGetFields(fields, runtimeMetadataKeys) {
         "schedule.reminders",
         "schedule.events",
     ]);
+    const allowedValues = [
+        ...[...itemFields].flatMap((field) => [field, `item.${field}`]),
+        ...allowedRootFields,
+        ...allowedLinkedFields,
+        ...allowedClaimStateFields,
+        ...allowedScheduleFields,
+    ].sort();
     const unknown = fields.filter((field) => {
         const normalized = normalizeGetField(field);
         return (!itemFields.has(normalized) &&
@@ -188,6 +196,12 @@ function validateGetFields(fields, runtimeMetadataKeys) {
             !allowedScheduleFields.has(normalized));
     });
     if (unknown.length > 0) {
+        const suggestedRetryArguments = [
+            "get",
+            id,
+            "--fields",
+            "id,title,status",
+        ];
         throw new PmCliError(`Unknown get --fields value(s): ${unknown.join(", ")}`, EXIT_CODE.USAGE, {
             code: "unknown_field_projection",
             examples: [
@@ -195,6 +209,11 @@ function validateGetFields(fields, runtimeMetadataKeys) {
                 "pm get <id> --fields id,title,claim_state",
                 "pm get <id> --fields id,title,body,linked.files",
             ],
+            recovery: {
+                allowed_values: allowedValues,
+                suggested_retry: renderPmCommand(suggestedRetryArguments),
+                suggested_retry_args: suggestedRetryArguments,
+            },
         });
     }
 }
@@ -309,9 +328,9 @@ async function loadGetItemContext(id, global, at) {
         body: loaded.document.body,
     };
 }
-function validateGetProjectionFields(fields, settings, historical) {
+function validateGetProjectionFields(fields, settings, historical, id) {
     const runtimeMetadataKeys = resolveRuntimeFieldRegistry(settings.schema).definitions.map((field) => field.metadata_key);
-    validateGetFields(fields, runtimeMetadataKeys);
+    validateGetFields(fields, runtimeMetadataKeys, id);
     if (historical && fieldsIncludeRoot(fields ?? [], "children")) {
         throw new PmCliError("Get --at cannot project children because workspace-level historical relationships are not yet indexed.", EXIT_CODE.USAGE);
     }
@@ -397,7 +416,7 @@ async function buildGetTree(context, options, treeDepth, global) {
 export async function runGet(id, global, options = {}) {
     const projection = resolveGetProjection(options);
     const context = await loadGetItemContext(id, global, options.at);
-    validateGetProjectionFields(projection.fields, context.settings, context.historical !== undefined);
+    validateGetProjectionFields(projection.fields, context.settings, context.historical !== undefined, context.locatedId);
     const includeBody = shouldIncludeGetField({ ...projection, field: "body" });
     const includeLinked = shouldIncludeGetField({
         ...projection,
@@ -463,4 +482,4 @@ export const _testOnlyGetCommand = {
     shouldAutoIncludeGetChildren,
 };
 //# sourceMappingURL=get.js.map
-//# debugId=c35e787c-a9a1-5ffa-9dcf-62780fceed4c
+//# debugId=1ba3eb17-c44c-5b62-8ae0-c2506fca9c62

package/dist/sdk/query/list.js

@@ -4,7 +4,7 @@
  * Implements the pm list 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]="ec0c4c57-e3c2-54b3-bcf4-b4ab3b1d964e")}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]="e2cb56ba-2f89-5589-8abf-f08cc7fa2b6b")}catch(e){}}();
 import { pathExists } from "../../core/fs/fs-utils.js";
 import { getActiveExtensionRegistrations, hasActiveOnReadHooks, } from "../../core/extensions/index.js";
 import { toItemRecord } from "../../core/item/item-record.js";
@@ -533,6 +533,9 @@ function validateListProjectionFields(projection, runtimeMetadataKeys) {
         ...TREE_METADATA_FIELDS,
         ...runtimeMetadataKeys,
     ]);
+    const allowedValues = [...allowed]
+        .flatMap((field) => [field, `item.${field}`])
+        .sort();
     const unknown = projection.fields.filter((field) => !allowed.has(normalizeProjectionField(field)));
     if (unknown.length > 0) {
         throw new PmCliError(`Unknown list --fields value(s): ${unknown.join(", ")}`, EXIT_CODE.USAGE, {
@@ -542,6 +545,17 @@ function validateListProjectionFields(projection, runtimeMetadataKeys) {
                 "pm list --fields id,title,parent,priority --limit 10",
                 "pm list-all --fields id,title,body --limit 5",
             ],
+            recovery: {
+                allowed_values: allowedValues,
+                suggested_retry: "pm list --fields id,title,status --limit 10",
+                suggested_retry_args: [
+                    "list",
+                    "--fields",
+                    "id,title,status",
+                    "--limit",
+                    "10",
+                ],
+            },
         });
     }
 }
@@ -1106,6 +1120,9 @@ function buildVerboseListFilters(params) {
     if (noTruncate) {
         filters.no_truncate = true;
     }
+    if (options.strictRead === true) {
+        filters.strict_read = true;
+    }
     if (treeEnabled) {
         filters.tree = true;
         if (treeDepth !== undefined) {
@@ -1240,4 +1257,4 @@ export const _testOnly = {
     withTreeMetadata,
 };
 //# sourceMappingURL=list.js.map
-//# debugId=ec0c4c57-e3c2-54b3-bcf4-b4ab3b1d964e
+//# debugId=e2cb56ba-2f89-5589-8abf-f08cc7fa2b6b

package/dist/sdk/query/search-contracts.d.ts

@@ -62,7 +62,7 @@ export declare function parseSearchDeadline(raw: string | undefined, fieldLabel:
 /** Resolve mutually exclusive compact, full, or explicit-field projection. */
 export declare function parseSearchProjection(options: SearchOptions): SearchProjectionConfig;
 /** Validate explicit projection fields against core and runtime metadata. */
-export declare function validateSearchProjectionFields(projection: SearchProjectionConfig, runtimeFieldRegistry: RuntimeFieldRegistry): void;
+export declare function validateSearchProjectionFields(projection: SearchProjectionConfig, runtimeFieldRegistry: RuntimeFieldRegistry, query?: string): void;
 /** Parse a non-empty normalized query into lexical tokens. */
 export declare function parseSearchTokens(query: string): string[];
 /** Documents the search tuning payload exchanged by command, SDK, and package integrations. */

package/dist/sdk/query/search-contracts.js

@@ -4,11 +4,12 @@
  * Owns search input parsing, output projection contracts, and tuning defaults.
  */
 
-!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]="47576eb5-4ddf-5e04-9e1d-c961da39b754")}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]="e737cdf9-734c-5010-864f-60e8052dd9c1")}catch(e){}}();
 import { coerceNumberInRange } from "../../core/shared/primitives.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { resolveIsoOrRelative } from "../../core/shared/time.js";
+import { renderPmCommand } from "../command-line.js";
 const DEFAULT_COMPACT_SEARCH_FIELDS = [
     "id",
     "title",
@@ -174,23 +175,31 @@ export function parseSearchProjection(options) {
     return { mode: "full", fields: [] };
 }
 /** Validate explicit projection fields against core and runtime metadata. */
-export function validateSearchProjectionFields(projection, runtimeFieldRegistry) {
+export function validateSearchProjectionFields(projection, runtimeFieldRegistry, query = "<query>") {
     if (projection.mode !== "fields")
         return;
     const runtimeKeys = new Set(runtimeFieldRegistry.definitions.flatMap((field) => [
         field.key,
         field.metadata_key,
     ]));
+    const allowedValues = new Set([
+        ...SEARCH_HIT_FIELD_KEYS,
+        ...SEARCH_ITEM_FIELD_KEYS,
+        ...[...SEARCH_ITEM_FIELD_KEYS].map((field) => `item.${field}`),
+        ...runtimeKeys,
+        ...[...runtimeKeys].map((field) => `item.${field}`),
+    ]);
     const unknown = projection.fields.filter((field) => {
         const normalized = field.trim();
-        const itemKey = normalized.startsWith("item.")
-            ? normalized.slice("item.".length)
-            : normalized;
-        return (!SEARCH_HIT_FIELD_KEYS.has(normalized) &&
-            !SEARCH_ITEM_FIELD_KEYS.has(itemKey) &&
-            !runtimeKeys.has(itemKey));
+        return !allowedValues.has(normalized);
     });
     if (unknown.length > 0) {
+        const suggestedRetryArguments = [
+            "search",
+            query,
+            "--fields",
+            "id,title,status,score",
+        ];
         throw new PmCliError(`Unknown search --fields value(s): ${unknown.join(", ")}`, EXIT_CODE.USAGE, {
             examples: [
                 "pm search <query> --fields id,title,status,score",
@@ -199,6 +208,11 @@ export function validateSearchProjectionFields(projection, runtimeFieldRegistry)
             nextSteps: [
                 "Use item.<field> for explicit item metadata fields, or run pm search --help for projection examples.",
             ],
+            recovery: {
+                allowed_values: [...allowedValues].sort(),
+                suggested_retry: renderPmCommand(suggestedRetryArguments),
+                suggested_retry_args: suggestedRetryArguments,
+            },
         });
     }
 }
@@ -283,4 +297,4 @@ export function resolveSearchTuning(settings) {
     };
 }
 //# sourceMappingURL=search-contracts.js.map
-//# debugId=47576eb5-4ddf-5e04-9e1d-c961da39b754
+//# debugId=e737cdf9-734c-5010-864f-60e8052dd9c1

package/dist/sdk/query/search.js

@@ -4,7 +4,7 @@
  * Implements the pm search 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]="1750b332-dd40-5497-b410-26c8c7436329")}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]="0582c462-43fc-563c-b209-d6e3c39948f4")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
@@ -1552,7 +1552,7 @@ async function resolveSearchRuntimeContext(prepared, global) {
     const settings = resolveSettingsWithSemanticRuntimeDefaults(storedSettings).settings;
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
     const runtimeFieldRegistry = resolveRuntimeFieldRegistry(settings.schema);
-    validateSearchProjectionFields(prepared.projection, runtimeFieldRegistry);
+    validateSearchProjectionFields(prepared.projection, runtimeFieldRegistry, prepared.query);
     const runtimeFieldFilters = collectRuntimeFilterValues(prepared.options, runtimeFieldRegistry, "search");
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const providerResolution = resolveEmbeddingProviders(settings);
@@ -1961,4 +1961,4 @@ export async function runSearch(rawQuery, rawOptions, global) {
     return withSearchWorkspaceMemory(buildSearchResultForHits(response, projectedItems, total, page.limited.length, effectiveProjection, page.pageExtras), workspaceMemoryResult);
 }
 //# sourceMappingURL=search.js.map
-//# debugId=1750b332-dd40-5497-b410-26c8c7436329
+//# debugId=0582c462-43fc-563c-b209-d6e3c39948f4

package/dist/sdk/query.d.ts

@@ -4,6 +4,7 @@
  * Provides focused read, search, pagination, and context-ranking primitives.
  */
 export * from "./query/list.js";
+export * from "./query/complete-list.js";
 export * from "./query/search.js";
 export { runActivity, type ActivityCommandOptions, type ActivityEntry, type ActivityResult, type CompactActivityEntry, } from "./query/activity.js";
 export * from "./query/aggregate.js";

package/dist/sdk/query.js

@@ -4,8 +4,9 @@
  * Provides focused read, search, pagination, and context-ranking primitives.
  */
 
-!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]="5e04dc9d-8e2d-5ef2-bf8b-6b18bd87c3bc")}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]="036baf5a-3ba9-55ea-a11b-d9e94a848b92")}catch(e){}}();
 export * from "./query/list.js";
+export * from "./query/complete-list.js";
 export * from "./query/search.js";
 export { runActivity, } from "./query/activity.js";
 export * from "./query/aggregate.js";
@@ -29,4 +30,4 @@ export * from "./context-usage.js";
 export * from "./workspace-memory.js";
 export * from "./duplicates.js";
 //# sourceMappingURL=query.js.map
-//# debugId=5e04dc9d-8e2d-5ef2-bf8b-6b18bd87c3bc
+//# debugId=036baf5a-3ba9-55ea-a11b-d9e94a848b92

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

@@ -1,5 +1,5 @@
 import type { PmReadOutputCursorEnvelope, PmReadOutputSurface } from "../read-output-contracts.js";
-/** Fingerprint stable row identities without including volatile observation fields. */
+/** Fingerprint the complete canonical row snapshot so changed evidence fails closed. */
 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;

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

@@ -6,38 +6,21 @@
  * 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){}}();
+!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]="1c73c31e-6246-5730-8c8a-d3ba7c9ec112")}catch(e){}}();
 import { createHash } from "node:crypto";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
+import { stableStringify } from "../../core/shared/serialization.js";
 import { resolveReadOutputSurface } from "../read-output-contracts.js";
-import { readOutputRowCollections, sliceReadOutputRowCollection, } from "../read-output-rows.js";
+import { readOutputContinuationRowCollections, 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. */
+/** Fingerprint the complete canonical row snapshot so changed evidence fails closed. */
 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 }))
+        .update(stableStringify({ path, value }))
         .digest("base64url")
         .slice(0, 16);
 }
@@ -113,7 +96,7 @@ export function applyReadOutputContinuation(result, command, cursor) {
     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 collection = readOutputContinuationRowCollections(result).find((entry) => entry.path === cursor.path);
     const totalRows = collection
         ? Array.isArray(collection.value)
             ? collection.value.length
@@ -129,4 +112,4 @@ export function applyReadOutputContinuation(result, command, cursor) {
     return sliceReadOutputRowCollection(result, cursor.path, cursor.offset);
 }
 //# sourceMappingURL=continuation.js.map
-//# debugId=8e523bbc-5745-514e-a1d8-a6ad6ece001a
+//# debugId=1c73c31e-6246-5730-8c8a-d3ba7c9ec112

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

@@ -5,7 +5,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", "comments-audit", "assurance"];
+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-catalog", "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. */
@@ -226,7 +226,7 @@ export declare const PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS: readonly ["--outpu
 /** 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. */
-export declare function resolveReadOutputSurface(command: string): PmReadOutputSurface | undefined;
+export declare function resolveReadOutputSurface(command: string, options?: Record<string, unknown>): PmReadOutputSurface | undefined;
 /** Reject malformed or mutation-scoped universal output controls before command execution. */
 export declare function validateReadOutputOptions(command: string, options: Record<string, unknown>): void;
 /**

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

@@ -5,12 +5,12 @@
  * 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]="e9621264-0180-53cf-862f-b59640b971da")}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]="b3c001df-9891-5cf7-990b-8d9da7b51801")}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, readOutputRowCollections, readOutputRowPaths, } from "./read-output-rows.js";
+import { boundReadOutputRows, countReadOutputRows, mapReadOutputRows, readOutputBudgetCollections, readOutputContinuationRowCollections, 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";
@@ -43,6 +43,7 @@ export const PM_READ_OUTPUT_SURFACES = [
     "docs",
     "stats",
     "aggregate",
+    "package-catalog",
     "package-manage",
     "comments-audit",
     "assurance",
@@ -135,6 +136,7 @@ const LEGACY_FLAGS_BY_COMMAND = {
     docs: {},
     stats: {},
     aggregate: {},
+    "package-catalog": {},
     "package-manage": {},
     "comments-audit": {},
     assurance: {},
@@ -208,15 +210,26 @@ const SURFACE_CONTRACT_BY_COMMAND = new Map(PM_READ_OUTPUT_SURFACE_CONTRACTS.map
     contract,
 ]));
 /** Resolve a command or list/context alias to its canonical read-output surface. */
-export function resolveReadOutputSurface(command) {
+export function resolveReadOutputSurface(command, options = {}) {
     const normalizedCommand = command
         .trim()
         .toLowerCase()
         .replaceAll(/\s+/gu, " ");
-    const root = normalizedCommand === "package manage" ||
-        normalizedCommand === "package-manage"
-        ? "package-manage"
-        : normalizedCommand.split(" ")[0];
+    const packageMode = normalizedCommand === "package catalog" ||
+        normalizedCommand === "packages catalog" ||
+        normalizedCommand === "package-catalog" ||
+        ((normalizedCommand === "package" ||
+            normalizedCommand === "packages" ||
+            normalizedCommand === "extension") &&
+            (options.catalog === true ||
+                options.target === "catalog" ||
+                options.action === "catalog"));
+    const root = packageMode
+        ? "package-catalog"
+        : normalizedCommand === "package manage" ||
+            normalizedCommand === "package-manage"
+            ? "package-manage"
+            : normalizedCommand.split(" ")[0];
     const normalized = root.startsWith("list-")
         ? "list"
         : root === "ctx"
@@ -247,6 +260,20 @@ const HYBRID_READ_MUTATION_KEYS = {
     notes: ["add", "addJson", "stdin", "file", "edit", "delete"],
     files: ["add", "addGlob", "remove", "migrate", "apply", "note"],
     docs: ["add", "addGlob", "remove", "migrate", "note"],
+    "package-catalog": [
+        "activate",
+        "adopt",
+        "adoptAll",
+        "deactivate",
+        "doctor",
+        "init",
+        "install",
+        "manage",
+        "migrate",
+        "reload",
+        "scaffold",
+        "uninstall",
+    ],
 };
 function hasCanonicalReadOutputOptions(options) {
     return CANONICAL_OPTION_KEYS.some((key) => options[key] !== undefined);
@@ -290,7 +317,7 @@ const READ_OUTPUT_VALUE_VALIDATORS = [
 export function validateReadOutputOptions(command, options) {
     if (!hasCanonicalReadOutputOptions(options))
         return;
-    const normalizedCommand = resolveReadOutputSurface(command);
+    const normalizedCommand = resolveReadOutputSurface(command, options);
     if (!normalizedCommand) {
         throw new PmCliError(`Universal output controls apply only to read commands; ${command || "this command"} is not a read surface.`, EXIT_CODE.USAGE);
     }
@@ -471,7 +498,7 @@ function resolveEncodingValue(canonical, legacy) {
 }
 /** Resolve canonical and compatibility controls into the universal dimension set. */
 export function resolveReadOutputDimensions(command, options) {
-    const normalizedCommand = resolveReadOutputSurface(command);
+    const normalizedCommand = resolveReadOutputSurface(command, options);
     if (!normalizedCommand)
         return undefined;
     const contract = SURFACE_CONTRACT_BY_COMMAND.get(normalizedCommand);
@@ -736,6 +763,54 @@ export function stabilizeReadOutputReceiptEstimates(result, options) {
     }
     return attachReadOutputSessionContracts(result, session, receipt);
 }
+/** Declare independently resumable validate diagnostic arrays on rich results. */
+function attachValidateDiagnosticRowContract(command, result) {
+    if (command !== "validate")
+        return result;
+    const projection = isRecord(result.projection)
+        ? result.projection
+        : undefined;
+    const declaredFieldGroups = Array.isArray(projection?.declared_field_groups)
+        ? projection.declared_field_groups
+        : [];
+    if (!declaredFieldGroups.some((group) => isRecord(group) && group.name === "diagnostic_rows")) {
+        return result;
+    }
+    const diagnosticCollectionPaths = [
+        ...new Set(readOutputBudgetCollections(result)
+            .map(({ path }) => path)
+            .filter((path) => /^checks\.\d+\.details\./u.test(path))),
+    ];
+    const diagnosticRowKeys = diagnosticCollectionPaths.filter((path) => !diagnosticCollectionPaths.some((candidate) => candidate !== path && path.startsWith(`${candidate}.`)));
+    if (diagnosticRowKeys.length === 0)
+        return result;
+    const existingContract = isRecord(result.row_contract)
+        ? result.row_contract
+        : {};
+    const existingRowKeys = Array.isArray(existingContract.row_keys)
+        ? existingContract.row_keys.filter((entry) => typeof entry === "string")
+        : [];
+    const existingContinuationRowKeys = Array.isArray(existingContract.continuation_row_keys)
+        ? existingContract.continuation_row_keys.filter((entry) => typeof entry === "string")
+        : [];
+    const rowKeys = existingRowKeys.length > 0 ? existingRowKeys : diagnosticRowKeys;
+    const continuationRowKeys = [...new Set(diagnosticRowKeys)];
+    return JSON.stringify(rowKeys) === JSON.stringify(existingRowKeys) &&
+        JSON.stringify(continuationRowKeys) ===
+            JSON.stringify(existingContinuationRowKeys)
+        ? result
+        : {
+            ...result,
+            row_contract: {
+                ...existingContract,
+                row_keys: rowKeys,
+                continuation_row_keys: continuationRowKeys,
+                jq_selector: typeof existingContract.jq_selector === "string"
+                    ? existingContract.jq_selector
+                    : ".checks[].details",
+            },
+        };
+}
 /** Apply field, amount, and repeat projections to every declared row path. */
 function projectReadOutputRows(result, resolved, session, cursor) {
     let projected = { ...result };
@@ -844,7 +919,7 @@ function attachReadOutputTruncationDisclosure(projected, resolved, receipt, bind
     if (!receipt.rows_compacted)
         return;
     const overridden = resolved.amount?.value === "unbounded" ? ["amount"] : [];
-    const afterByPath = new Map(readOutputRowCollections(projected).map((collection) => [
+    const afterByPath = new Map(readOutputContinuationRowCollections(projected).map((collection) => [
         collection.path,
         Array.isArray(collection.value)
             ? collection.value.length
@@ -947,7 +1022,7 @@ function rebaseBudgetCompactedCursor(projected, originalItemCount, cursorSource,
     return true;
 }
 function captureReadOutputContinuationState(projected, cursor, options) {
-    const collectionsBeforeBudget = new Map(readOutputRowCollections(projected).map((collection) => {
+    const collectionsBeforeBudget = new Map(readOutputContinuationRowCollections(projected).map((collection) => {
         const rows = Array.isArray(collection.value)
             ? collection.value.length
             : Object.keys(collection.value).length;
@@ -1005,8 +1080,9 @@ export function applyReadOutputDimensions(command, options, result) {
         canReturnReadOutputUnchanged(resolved, requested, session, result)) {
         return result;
     }
+    const continuationReadyResult = attachValidateDiagnosticRowContract(resolved.command, result);
     const bindingBudget = resolveBindingReadOutputBudget(resolved, session);
-    let projected = projectReadOutputRows(result, resolved, session, cursor);
+    let projected = projectReadOutputRows(continuationReadyResult, resolved, session, cursor);
     const continuationState = captureReadOutputContinuationState(projected, cursor, options);
     const receipt = {
         contract_version: 1,
@@ -1058,4 +1134,4 @@ export function resolveReadOutputEncoding(command, options) {
         : undefined;
 }
 //# sourceMappingURL=read-output-contracts.js.map
-//# debugId=e9621264-0180-53cf-862f-b59640b971da
+//# debugId=b3c001df-9891-5cf7-990b-8d9da7b51801

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

@@ -15,8 +15,12 @@ export interface PmReadOutputRowCollection {
 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 collections that may be resumed independently from primary result rows. */
+export declare function readOutputContinuationRowPaths(result: Record<string, unknown>): string[];
 /** Resolve every declared row path that currently contains iterable rows. */
 export declare function readOutputRowCollections(result: Record<string, unknown>): PmReadOutputRowCollection[];
+/** Resolve every declared continuation path that currently contains iterable rows. */
+export declare function readOutputContinuationRowCollections(result: Record<string, unknown>): PmReadOutputRowCollection[];
 /**
  * Discover every collection the token-budget degradation ladder may reduce.
  *