@unbrained/pm-cli 2026.8.11 → 2026.8.12

package/dist/core/history/history.js

@@ -4,7 +4,7 @@
  * Implements append-only history and replay behavior for 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]="ce2dace3-7c86-5edf-8bda-083a0b3e7f2b")}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]="2fc7f675-3500-5abb-8d5c-9ca9caa803b6")}catch(e){}}();
 import jsonPatch from "fast-json-patch";
 import { ITEM_METADATA_KEY_ORDER } from "../shared/constants.js";
 import { runActiveServiceOverride } from "../extensions/index.js";
@@ -20,6 +20,42 @@ const EMPTY_LEGACY_HASH_DOCUMENT = {
     front_matter: {},
     body: "",
 };
+/** Hash epoch that preserves linked-test insertion order in immutable history. */
+export const CURRENT_HISTORY_ITEM_HASH_VERSION = 2;
+/** Hash epochs understood by this runtime. */
+export const SUPPORTED_HISTORY_ITEM_HASH_VERSIONS = [1, 2];
+function compareOptionalStrings(left, right) {
+    return (left ?? "").localeCompare(right ?? "");
+}
+function compareOptionalNumbers(left, right) {
+    return (left ?? 0) - (right ?? 0);
+}
+function compareJsonValues(left, right, fallback) {
+    // Preserve the original v1 comparator byte-for-byte: replacing JSON.stringify
+    // with stableStringify would invalidate immutable hashes from legacy streams.
+    return JSON.stringify(left ?? fallback).localeCompare(JSON.stringify(right ?? fallback));
+}
+function compareLegacyLinkedTests(left, right) {
+    const comparisons = [
+        left.scope.localeCompare(right.scope),
+        compareOptionalStrings(left.path, right.path),
+        compareOptionalStrings(left.command, right.command),
+        compareOptionalNumbers(left.timeout_seconds, right.timeout_seconds),
+        compareOptionalStrings(left.pm_context_mode, right.pm_context_mode),
+        Number(Boolean(left.shared_host_safe)) - Number(Boolean(right.shared_host_safe)),
+        compareJsonValues(left.env_clear, right.env_clear, []),
+        compareJsonValues(left.env_set, right.env_set, {}),
+        compareJsonValues(left.assert_stdout_contains, right.assert_stdout_contains, []),
+        compareJsonValues(left.assert_stdout_regex, right.assert_stdout_regex, []),
+        compareJsonValues(left.assert_stderr_contains, right.assert_stderr_contains, []),
+        compareJsonValues(left.assert_stderr_regex, right.assert_stderr_regex, []),
+        compareOptionalNumbers(left.assert_stdout_min_lines, right.assert_stdout_min_lines),
+        compareJsonValues(left.assert_json_field_equals, right.assert_json_field_equals, {}),
+        compareJsonValues(left.assert_json_field_gte, right.assert_json_field_gte, {}),
+        compareOptionalStrings(left.note, right.note),
+    ];
+    return comparisons.find((comparison) => comparison !== 0) ?? 0;
+}
 function decodeJsonPointer(path) {
     if (!path || path === "/") {
         return [];
@@ -81,7 +117,7 @@ function normalizeHistoryPatchOps(beforeDocument, patch) {
     }
     return normalized;
 }
-function canonicalHashDocument(document) {
+function canonicalHashDocument(document, version) {
     const hasMetadata = document.metadata && Object.keys(document.metadata).length > 0;
     if (!hasMetadata) {
         return {
@@ -90,7 +126,13 @@ function canonicalHashDocument(document) {
         };
     }
     const canonical = canonicalDocument(document);
-    const orderedMetadata = orderObject(toItemRecord(canonical.metadata), ITEM_METADATA_KEY_ORDER);
+    const metadata = version === 1 && canonical.metadata.tests
+        ? {
+            ...canonical.metadata,
+            tests: [...canonical.metadata.tests].sort(compareLegacyLinkedTests),
+        }
+        : canonical.metadata;
+    const orderedMetadata = orderObject(toItemRecord(metadata), ITEM_METADATA_KEY_ORDER);
     return {
         front_matter: orderedMetadata,
         body: canonical.body,
@@ -113,7 +155,14 @@ function canonicalPatchDocument(document) {
 }
 /** Implements hash document for the public runtime surface of this module. */
 export function hashDocument(document) {
-    return sha256Hex(stableStringify(canonicalHashDocument(document)));
+    return hashDocumentForVersion(document, CURRENT_HISTORY_ITEM_HASH_VERSION);
+}
+/** Hash an item with an explicit canonicalization epoch for replay compatibility. */
+export function hashDocumentForVersion(document, version) {
+    if (!SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.some((supportedVersion) => supportedVersion === version)) {
+        throw new TypeError(`unsupported_item_hash_version:${String(version)}`);
+    }
+    return sha256Hex(stableStringify(canonicalHashDocument(document, version)));
 }
 /** Implements hash empty document for the public runtime surface of this module. */
 export function hashEmptyDocument() {
@@ -121,8 +170,8 @@ export function hashEmptyDocument() {
 }
 /** Implements create history entry for the public runtime surface of this module. */
 export function createHistoryEntry(params) {
-    const beforeHashCanonical = canonicalHashDocument(params.before);
-    const afterHashCanonical = canonicalHashDocument(params.after);
+    const beforeHashCanonical = canonicalHashDocument(params.before, CURRENT_HISTORY_ITEM_HASH_VERSION);
+    const afterHashCanonical = canonicalHashDocument(params.after, CURRENT_HISTORY_ITEM_HASH_VERSION);
     const beforePatchCanonical = canonicalPatchDocument(params.before);
     const afterPatchCanonical = canonicalPatchDocument(params.after);
     const rawPatch = jsonPatch.compare(beforePatchCanonical, afterPatchCanonical);
@@ -159,6 +208,7 @@ export function createHistoryEntry(params) {
         patch,
         before_hash: sha256Hex(stableStringify(beforeHashCanonical)),
         after_hash: sha256Hex(stableStringify(afterHashCanonical)),
+        item_hash_version: CURRENT_HISTORY_ITEM_HASH_VERSION,
         message: params.message === undefined ? undefined : params.message,
         ...(context === undefined ? {} : { context }),
     };
@@ -242,4 +292,4 @@ export const _testOnly = {
     isDefinedPointerPath,
 };
 //# sourceMappingURL=history.js.map
-//# debugId=ce2dace3-7c86-5edf-8bda-083a0b3e7f2b
+//# debugId=2fc7f675-3500-5abb-8d5c-9ca9caa803b6

package/dist/core/history/replay.d.ts

@@ -1,4 +1,5 @@
 import { canonicalDocument } from "../item/item-format.js";
+import { type HistoryItemHashVersion } from "./history.js";
 import type { HistoryEntry, HistoryPatchOp, ItemDocument } from "../../types/index.js";
 /**
  * Shared history replay/patch mechanics single-sourced for the history, restore,
@@ -19,7 +20,7 @@ export declare const EMPTY_REPLAY_DOCUMENT: ReplayDocument;
 /** Implements clone empty replay document for the public runtime surface of this module. */
 export declare function cloneEmptyReplayDocument(): ReplayDocument;
 /** Implements replay hash for the public runtime surface of this module. */
-export declare function replayHash(document: ReplayDocument): string;
+export declare function replayHash(document: ReplayDocument, version?: HistoryItemHashVersion): string;
 /** Implements replay to item document for the public runtime surface of this module. */
 export declare function replayToItemDocument(document: ReplayDocument): ItemDocument;
 /** Converts a materialized replay document into a canonical item document. Use this when callers have already rejected the empty/deleted replay state and need restored metadata validated through the normal item-metadata rules. */
@@ -41,6 +42,13 @@ export type ReplayApplyResult = {
 /** Strictly apply a history patch (front_matter->metadata normalized) to a replay document. Returns a result envelope rather than throwing so each caller can format its own error contract. */
 export declare function tryApplyReplayPatch(current: ReplayDocument, patch: HistoryPatchOp[]): ReplayApplyResult;
 /** Deterministically verify a history chain: each entry's before_hash must equal the prior replayed after_hash, the patch must strictly apply, and the recorded after_hash must equal the replayed result. */
+/** Verify a chain and report the explicit or auto-detected item hash epoch. */
+export declare function verifyHistoryChainWithVersion(entries: HistoryEntry[]): {
+    ok: boolean;
+    errors: string[];
+    item_hash_version?: HistoryItemHashVersion;
+};
+/** Deterministically verify a history chain while preserving the legacy result shape. */
 export declare function verifyHistoryChain(entries: HistoryEntry[]): {
     ok: boolean;
     errors: string[];

package/dist/core/history/replay.js

@@ -4,13 +4,13 @@
  * Implements append-only history and replay behavior for Replay.
  */
 
-!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]="c8668470-7e57-5dee-8e41-298e7c697b77")}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]="a1283470-00c7-5e91-8676-e1c1a667537f")}catch(e){}}();
 import jsonPatch from "fast-json-patch";
 import { ITEM_METADATA_KEY_ORDER } from "../shared/constants.js";
 import { canonicalDocument } from "../item/item-format.js";
 import { toItemRecord } from "../item/item-record.js";
 import { orderObject, sha256Hex, stableStringify, } from "../shared/serialization.js";
-import { hashDocument } from "./history.js";
+import { CURRENT_HISTORY_ITEM_HASH_VERSION, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, hashDocumentForVersion, } from "./history.js";
 /** Public contract for empty replay document, shared by SDK and presentation-layer consumers. */
 export const EMPTY_REPLAY_DOCUMENT = {
     metadata: {},
@@ -21,11 +21,11 @@ export function cloneEmptyReplayDocument() {
     return structuredClone(EMPTY_REPLAY_DOCUMENT);
 }
 /** Implements replay hash for the public runtime surface of this module. */
-export function replayHash(document) {
+export function replayHash(document, version = CURRENT_HISTORY_ITEM_HASH_VERSION) {
     if (Object.keys(document.metadata).length === 0 ||
         Array.isArray(document.metadata.tags)) {
         try {
-            return hashDocument(replayToItemDocument(document));
+            return hashDocumentForVersion(replayToItemDocument(document), version);
         }
         catch {
             // Fall through when another malformed legacy field cannot be canonicalized.
@@ -124,14 +124,20 @@ export function tryApplyReplayPatch(current, patch) {
     }
 }
 /** Deterministically verify a history chain: each entry's before_hash must equal the prior replayed after_hash, the patch must strictly apply, and the recorded after_hash must equal the replayed result. */
-export function verifyHistoryChain(entries) {
+/** Verify a chain and report the explicit or auto-detected item hash epoch. */
+export function verifyHistoryChainWithVersion(entries) {
     let replay = cloneEmptyReplayDocument();
+    let detectedVersion;
     for (let index = 0; index < entries.length; index += 1) {
         const entry = entries[index];
-        if (replayHash(replay) !== entry.before_hash) {
+        const explicitVersion = entry.item_hash_version;
+        if (explicitVersion !== undefined &&
+            !SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.includes(explicitVersion)) {
             return {
                 ok: false,
-                errors: [`verify_failed:before_hash_mismatch:entry_${index + 1}`],
+                errors: [
+                    `verify_failed:unsupported_item_hash_version:${String(explicitVersion)}:entry_${index + 1}`,
+                ],
             };
         }
         const applied = tryApplyReplayPatch(replay, entry.patch);
@@ -141,15 +147,38 @@ export function verifyHistoryChain(entries) {
                 errors: [`verify_failed:patch_apply_failed:entry_${index + 1}`],
             };
         }
-        replay = applied.document;
-        if (replayHash(replay) !== entry.after_hash) {
+        const candidates = explicitVersion === undefined
+            ? [CURRENT_HISTORY_ITEM_HASH_VERSION, 1]
+            : [explicitVersion];
+        const beforeMatches = candidates.filter((version) => replayHash(replay, version) === entry.before_hash);
+        if (beforeMatches.length === 0) {
+            return {
+                ok: false,
+                errors: [`verify_failed:before_hash_mismatch:entry_${index + 1}`],
+            };
+        }
+        const version = beforeMatches.find((candidate) => replayHash(applied.document, candidate) === entry.after_hash);
+        if (version === undefined) {
             return {
                 ok: false,
                 errors: [`verify_failed:after_hash_mismatch:entry_${index + 1}`],
             };
         }
+        replay = applied.document;
+        detectedVersion = version;
     }
-    return { ok: true, errors: [] };
+    return {
+        ok: true,
+        errors: [],
+        ...(detectedVersion === undefined
+            ? {}
+            : { item_hash_version: detectedVersion }),
+    };
+}
+/** Deterministically verify a history chain while preserving the legacy result shape. */
+export function verifyHistoryChain(entries) {
+    const result = verifyHistoryChainWithVersion(entries);
+    return { ok: result.ok, errors: result.errors };
 }
 function tryApplySingleOp(document, op) {
     try {
@@ -192,6 +221,11 @@ export function lenientApplyReplayPatch(current, patch) {
 }
 /** Re-anchor a drifted history chain: replay every entry from empty, recompute the before/after hashes, and only rewrite a patch when the original op set no longer strictly applies (legacy drift). Clean entries keep their patch verbatim so the on-disk diff stays minimal. The returned chain verifies via verifyHistoryChain. */
 export function reanchorHistoryEntries(entries) {
+    const unsupportedIndex = entries.findIndex((entry) => entry.item_hash_version !== undefined &&
+        !SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.includes(entry.item_hash_version));
+    if (unsupportedIndex >= 0) {
+        throw new TypeError(`unsupported_item_hash_version:${String(entries[unsupportedIndex]?.item_hash_version)}:entry_${unsupportedIndex + 1}`);
+    }
     let replay = cloneEmptyReplayDocument();
     const rewritten = [];
     const details = [];
@@ -201,7 +235,7 @@ export function reanchorHistoryEntries(entries) {
     let skippedOps = 0;
     for (let index = 0; index < entries.length; index += 1) {
         const entry = entries[index];
-        const beforeHash = replayHash(replay);
+        const beforeHash = replayHash(replay, CURRENT_HISTORY_ITEM_HASH_VERSION);
         const strict = tryApplyReplayPatch(replay, entry.patch);
         let next;
         let outPatch;
@@ -223,7 +257,7 @@ export function reanchorHistoryEntries(entries) {
             skippedOps += entrySkipped;
             entriesPatchRepaired += 1;
         }
-        const afterHash = replayHash(next);
+        const afterHash = replayHash(next, CURRENT_HISTORY_ITEM_HASH_VERSION);
         const rehashed = beforeHash !== entry.before_hash || afterHash !== entry.after_hash;
         if (rehashed) {
             entriesRehashed += 1;
@@ -233,6 +267,7 @@ export function reanchorHistoryEntries(entries) {
             patch: outPatch,
             before_hash: beforeHash,
             after_hash: afterHash,
+            item_hash_version: CURRENT_HISTORY_ITEM_HASH_VERSION,
         });
         details.push({
             index: index + 1,
@@ -261,4 +296,4 @@ export function historyEntriesToRaw(entries) {
     return `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
 }
 //# sourceMappingURL=replay.js.map
-//# debugId=c8668470-7e57-5dee-8e41-298e7c697b77
+//# debugId=a1283470-00c7-5e91-8676-e1c1a667537f

package/dist/core/output/output.d.ts

@@ -24,6 +24,8 @@ export interface OutputOptions {
     outputFormat?: "toon" | "json";
     /** Caller-carried cross-call budget and served-item state. */
     outputSession?: string;
+    /** Include machine-readable row location and row-encoding metadata. */
+    outputRowContract?: boolean;
     /** Fallback output format used when callers do not provide an override. */
     defaultOutputFormat?: "toon" | "json";
     /** Value that configures or reports command for this contract. */

package/dist/core/output/output.js

@@ -4,7 +4,7 @@
  * Formats compact human and machine output for Output.
  */
 
-!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]="b52d2756-f640-5f53-981f-05fa23fa1718")}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]="5aaf8b90-5b95-5102-9ea4-b877c696d593")}catch(e){}}();
 import { getActiveCommandContext, runActiveCommandOverride, runActiveRendererOverride, runActiveServiceOverrideSync, setActiveCommandResult, } from "../extensions/index.js";
 import { EXIT_CODE } from "../shared/constants.js";
 import { isHostOutputSuppressed } from "./output-control.js";
@@ -12,6 +12,7 @@ import { projectMutationResult } from "./mutation-projection.js";
 import { attachReadOutputContracts } from "../../sdk/context-intent-contracts.js";
 import { attachOutputTokenAccounting } from "../../sdk/output-token-accounting.js";
 import { resolveReadOutputEncoding } from "../../sdk/read-output-contracts.js";
+import { encode as encodeToon } from "@toon-format/toon";
 const DECLARED_PROCESS_EXIT_CODES = new Set(Object.values(EXIT_CODE));
 const NATIVE_OUTPUT_MARKER = "__pm_native_output";
 let streamErrorHandlersInstalled = false;
@@ -114,6 +115,44 @@ function renderScalar(value) {
         return "null";
     return JSON.stringify(value);
 }
+function isToonPrimitive(value) {
+    return (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean");
+}
+function tabularObjectArray(value) {
+    if (value.length === 0 || !value.every(isPlainObject))
+        return false;
+    const keys = Object.keys(value[0]);
+    return (keys.length > 0 &&
+        value.every((entry) => Object.keys(entry).length === keys.length &&
+            keys.every((key) => Object.hasOwn(entry, key) && isToonPrimitive(entry[key]))));
+}
+function indentToon(encoded, depth) {
+    const indent = "  ".repeat(depth);
+    return encoded
+        .split("\n")
+        .map((line) => `${indent}${line}`)
+        .join("\n");
+}
+/** Render one object field while preserving nested and tabular TOON structure. */
+function renderToonObjectEntry(key, entry, depth) {
+    const indent = "  ".repeat(depth);
+    if (!isPlainObject(entry) && !Array.isArray(entry)) {
+        return `${indent}${key}: ${renderScalar(entry)}`;
+    }
+    if (Array.isArray(entry) && entry.length === 0) {
+        return `${indent}${key}: []`;
+    }
+    if (Array.isArray(entry) && tabularObjectArray(entry)) {
+        return indentToon(encodeToon({ [key]: entry }), depth);
+    }
+    if (isPlainObject(entry) && Object.keys(entry).length === 0) {
+        return `${indent}${key}: {}`;
+    }
+    return `${indent}${key}:\n${renderToonValue(entry, depth + 1)}`;
+}
 function compactToonValue(value) {
     if (value === null || value === undefined) {
         return undefined;
@@ -147,6 +186,9 @@ function renderToonValue(value, depth) {
     if (Array.isArray(value)) {
         if (value.length === 0)
             return "[]";
+        if (tabularObjectArray(value)) {
+            return indentToon(encodeToon(value), depth);
+        }
         return value
             .map((entry) => {
             if (!isPlainObject(entry) && !Array.isArray(entry)) {
@@ -167,18 +209,7 @@ function renderToonValue(value, depth) {
         if (entries.length === 0)
             return "{}";
         return entries
-            .map(([key, entry]) => {
-            if (!isPlainObject(entry) && !Array.isArray(entry)) {
-                return `${indent}${key}: ${renderScalar(entry)}`;
-            }
-            if (Array.isArray(entry) && entry.length === 0) {
-                return `${indent}${key}: []`;
-            }
-            if (isPlainObject(entry) && Object.keys(entry).length === 0) {
-                return `${indent}${key}: {}`;
-            }
-            return `${indent}${key}:\n${renderToonValue(entry, depth + 1)}`;
-        })
+            .map(([key, entry]) => renderToonObjectEntry(key, entry, depth))
             .join("\n");
     }
     return `${indent}${renderScalar(value)}`;
@@ -335,6 +366,7 @@ function formatEffectiveOutput(effectiveResult, nativeOutput, options) {
             ["outputBudget", options.outputBudget],
             ["outputFormat", options.outputFormat],
             ["outputSession", options.outputSession],
+            ["outputRowContract", options.outputRowContract],
         ].filter((entry) => entry[1] !== undefined)),
     };
     const format = resolveReadOutputEncoding(command ?? "", commandOptions) ??
@@ -424,4 +456,4 @@ export const outputTestOnly = {
     renderToonValue,
 };
 //# sourceMappingURL=output.js.map
-//# debugId=b52d2756-f640-5f53-981f-05fa23fa1718
+//# debugId=5aaf8b90-5b95-5102-9ea4-b877c696d593

package/dist/core/shared/command-types.d.ts

@@ -29,6 +29,8 @@ export interface GlobalOptions {
     outputFormat?: "toon" | "json";
     /** Caller-carried cross-call budget and served-item state. */
     outputSession?: string;
+    /** Include the machine-readable row selector and TOON encoding contract. */
+    outputRowContract?: boolean;
     /** Filesystem path used for path resolution. */
     path?: string;
     /** Value that configures or reports no extensions for this contract. */

package/dist/core/shared/command-types.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ff47df0c-93db-5e20-be4e-48a2aedfeebf")}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]="044af354-3047-5fd4-ae65-458a259dedca")}catch(e){}}();
 export {};
 //# sourceMappingURL=command-types.js.map
-//# debugId=ff47df0c-93db-5e20-be4e-48a2aedfeebf
+//# debugId=044af354-3047-5fd4-ae65-458a259dedca

package/dist/core/shared/errors.d.ts

@@ -11,6 +11,11 @@ export interface PmCliErrorRecoveryPayload {
     attempted_command?: string;
     /** Value that configures or reports normalized args for this contract. */
     normalized_args?: string[];
+    /** Positional tokens paired with their parser roles for unambiguous recovery. */
+    parsed_positionals?: Array<{
+        role: string;
+        value: string;
+    }>;
     /** Value that configures or reports provided fields for this contract. */
     provided_fields?: string[];
     /** Value that configures or reports missing for this contract. */

package/dist/core/shared/errors.js

@@ -1,6 +1,6 @@
 /** Implements the exported pm cli error runtime abstraction for core/shared/errors.ts. */
 
-!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]="df6f6758-f972-5bf4-aaa8-b16dd9a247f3")}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]="62fb0ba7-643f-5b33-870b-df875559610a")}catch(e){}}();
 export class PmCliError extends Error {
     /** Value that configures or reports exit code for this contract. */
     exitCode;
@@ -18,4 +18,4 @@ export class PmCliError extends Error {
     }
 }
 //# sourceMappingURL=errors.js.map
-//# debugId=df6f6758-f972-5bf4-aaa8-b16dd9a247f3
+//# debugId=62fb0ba7-643f-5b33-870b-df875559610a

package/dist/core/store/item-metadata-cache.d.ts

@@ -83,7 +83,7 @@ export interface ListCacheOptions {
     includeBody?: boolean;
     /** When false, heavy collection fields (comments/notes/learnings/files/tests/ test_runs/docs) are neither loaded from nor written to the separate collections cache, and are absent from the returned metadata. Light-only callers (`pm list` compact, stats, deps, activity, calendar, close) skip the large collections cache entirely. Defaults to true so any caller that does read those fields stays correct. */
     includeCollections?: boolean;
-    /** Force canonical item enumeration and stat validation even when a fresh derived index is available. Validation, repair, migration, and equivalence tests use this correctness path. */
+    /** Force canonical item enumeration and authoritative file reads even when stat-matched cache tiers or a fresh derived index are available. Validation, repair, migration, and equivalence tests use this correctness path. */
     forceSourceScan?: boolean;
     /** Minimum item count required before the directory-signature derived-index fast path is used. Defaults to 500 so small workspaces preserve per-file external-edit detection; tests and specialized SDK hosts may lower it explicitly. */
     derivedIndexMinimumItems?: number;

package/dist/core/store/item-metadata-cache.js

@@ -4,7 +4,7 @@
  * Reads and writes tracker storage with format-aware helpers for the item metadata cache.
  */
 
-!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]="8ed70856-9cba-599d-8b53-21a981af1f40")}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]="58d1ab81-16b6-5c93-ade4-ba189ea48c9b")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
@@ -257,7 +257,8 @@ async function loadBodyCache(pmRoot, contextFingerprint) {
     };
     const cachePath = getBodyCachePath(pmRoot);
     const active = await loadEnvelopeMemoized(cachePath, parse);
-    return contextFingerprint && active?.context_fingerprint !== contextFingerprint
+    return contextFingerprint &&
+        active?.context_fingerprint !== contextFingerprint
         ? await loadEnvelopeMemoized(getContextCachePath(cachePath, contextFingerprint), parse)
         : active;
 }
@@ -274,7 +275,8 @@ async function loadCollectionsCache(pmRoot, contextFingerprint) {
     };
     const cachePath = getCollectionsCachePath(pmRoot);
     const active = await loadEnvelopeMemoized(cachePath, parse);
-    return contextFingerprint && active?.context_fingerprint !== contextFingerprint
+    return contextFingerprint &&
+        active?.context_fingerprint !== contextFingerprint
         ? await loadEnvelopeMemoized(getContextCachePath(cachePath, contextFingerprint), parse)
         : active;
 }
@@ -518,12 +520,16 @@ async function readCachedDocumentParts(filePath, relativePath, context) {
     const itemFormat = getItemFormatFromPath(filePath);
     await dispatchCachedDocumentReadHooks(filePath, context.warnings, context.dispatchReadHooks);
     const cachedEntry = context.previousEntries[relativePath];
-    const metadataCached = cachedEntry !== undefined &&
+    const metadataCached = !context.forceSourceRead &&
+        cachedEntry !== undefined &&
         statMatches(cachedEntry, mtimeMs, ctimeMs, size);
     const cachedBody = context.previousBodies[relativePath];
-    const bodyCached = cachedBody !== undefined && statMatches(cachedBody, mtimeMs, ctimeMs, size);
+    const bodyCached = !context.forceSourceRead &&
+        cachedBody !== undefined &&
+        statMatches(cachedBody, mtimeMs, ctimeMs, size);
     const cachedCollections = context.previousCollections[relativePath];
-    const collectionsCached = cachedCollections !== undefined &&
+    const collectionsCached = !context.forceSourceRead &&
+        cachedCollections !== undefined &&
         statMatches(cachedCollections, mtimeMs, ctimeMs, size);
     const needRead = !metadataCached ||
         (context.includeBody && !bodyCached) ||
@@ -1028,6 +1034,7 @@ export async function listAllDocumentCandidatesCached(pmRoot, preferredFormat, t
         extensionFieldNames,
         includeBody,
         includeCollections,
+        forceSourceRead: options.forceSourceScan === true,
         dispatchReadHooks,
         previousEntries,
         previousBodies,
@@ -1107,4 +1114,4 @@ export async function listAllDocumentsCachedLight(pmRoot, preferredFormat, typeT
     }));
 }
 //# sourceMappingURL=item-metadata-cache.js.map
-//# debugId=8ed70856-9cba-599d-8b53-21a981af1f40
+//# debugId=58d1ab81-16b6-5c93-ade4-ba189ea48c9b

package/dist/sdk/cli-bootstrap.d.ts

@@ -31,6 +31,8 @@ export interface BootstrapGlobalOptions {
     outputFormat?: "toon" | "json";
     /** Caller-carried cross-call budget and served-item state. */
     outputSession?: string;
+    /** Whether machine-readable row discovery metadata is requested. */
+    outputRowContract?: boolean;
     /** Invocation-wide mutation author override. */
     author?: string;
     /** Whether `--author` was present without its required value. */

package/dist/sdk/cli-bootstrap.js

@@ -4,7 +4,7 @@
  * Provides public bootstrap argument normalization for embedded CLI hosts.
  */
 
-!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]="eac8ed6b-43c4-54fa-820a-220154001a6b")}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]="7b3209a8-8580-542c-9e80-21d04df3f61f")}catch(e){}}();
 import { EXECUTABLE_COMMAND_ALIASES, resolveSubcommandFlagContractsForCommand, } from "./cli-contracts.js";
 export { EXECUTABLE_COMMAND_ALIASES };
 import { levenshteinDistanceWithinLimit } from "../core/shared/levenshtein.js";
@@ -47,6 +47,7 @@ const BOOTSTRAP_BOOLEAN_FLAGS = new Set([
     "--quiet",
     "--lean",
     "--token-accounting",
+    "--output-row-contract",
 ]);
 /** Consume one bootstrap-global token and update the accumulated parse state. */
 function consumeBootstrapGlobalToken(argv, index, state) {
@@ -95,6 +96,9 @@ export function parseBootstrapGlobalOptions(argv) {
         quiet: state.booleanFlags.has("--quiet"),
         lean: state.booleanFlags.has("--lean"),
         tokenAccounting: state.booleanFlags.has("--token-accounting"),
+        ...(state.booleanFlags.has("--output-row-contract")
+            ? { outputRowContract: true }
+            : {}),
         ...(state.outputValues.get("--output-include") === undefined
             ? {}
             : { outputInclude: state.outputValues.get("--output-include") }),
@@ -886,4 +890,4 @@ export const _testOnly = {
     resolveCanonicalFlag,
 };
 //# sourceMappingURL=cli-bootstrap.js.map
-//# debugId=eac8ed6b-43c4-54fa-820a-220154001a6b
+//# debugId=7b3209a8-8580-542c-9e80-21d04df3f61f

package/dist/sdk/cli-contracts/completeness.js

@@ -7,7 +7,7 @@
  * a hand-picked test list.
  */
 
-!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]="11dade38-a681-599f-b3b7-8d121418366d")}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]="13847453-3016-5855-a816-2cadc2ca4870")}catch(e){}}();
 import { PM_TOOL_ACTIONS } from "./enum-contracts.js";
 import { resolveSubcommandFlagContractsForCommand, } from "./flag-contracts.js";
 import { pmToolActionParameterKeys } from "./tool-schema.js";
@@ -23,6 +23,7 @@ const CLI_TRANSPORT_FLAGS = new Set([
     "--output-budget",
     "--output-format",
     "--output-session",
+    "--output-row-contract",
     "--no-changed-fields",
     "--no-extensions",
     "--no-pager",
@@ -376,4 +377,4 @@ export function analyzeSdkCliParameterCompleteness(source = {}) {
     });
 }
 //# sourceMappingURL=completeness.js.map
-//# debugId=11dade38-a681-599f-b3b7-8d121418366d
+//# debugId=13847453-3016-5855-a816-2cadc2ca4870

package/dist/sdk/cli-contracts/flag-contracts.js

@@ -7,7 +7,7 @@
  * flag surface stays single-sourced across the CLI, SDK, and MCP boundaries.
  */
 
-!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]="48d9a5c7-f747-5fac-a534-01a4b3b7af2c")}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]="40309a44-7d45-5333-9003-6fc740e827c8")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { RESERVED_EXTENSION_HOST_FLAGS } from "../../core/extensions/reserved-host-flags.js";
 function normalizeFlagAliasKey(flag) {
@@ -875,6 +875,7 @@ export const TEST_FLAG_CONTRACTS = [
     { flag: "--add" },
     { flag: "--add-json" },
     { flag: "--remove" },
+    { flag: "--remove-index", repeatable: true },
     { flag: "--run" },
     { flag: "--match" },
     { flag: "--only-index" },
@@ -940,6 +941,7 @@ export const GC_FLAG_CONTRACTS = [
 ];
 /** Public contract for stats flag contracts, shared by SDK and presentation-layer consumers. */
 export const STATS_FLAG_CONTRACTS = [
+    { flag: "--include-empty" },
     { flag: "--storage" },
     { flag: "--metadata-coverage" },
     { flag: "--field-utilization" },
@@ -1391,6 +1393,7 @@ export const ACTIVITY_FLAG_CONTRACTS = [
     { flag: "--limit" },
     { flag: "--unbounded" },
     { flag: "--compact" },
+    { flag: "--raw" },
     { flag: "--full" },
     { flag: "--provenance" },
     { flag: "--provenance-summary" },
@@ -1811,4 +1814,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=48d9a5c7-f747-5fac-a534-01a4b3b7af2c
+//# debugId=40309a44-7d45-5333-9003-6fc740e827c8