@unbrained/pm-cli 2026.8.6 → 2026.8.8

package/dist/sdk/author-attribution.d.ts

@@ -52,6 +52,18 @@ export interface AcknowledgeUnknownAuthorEventsOptions {
     /** Evidence-backed rationale for the attribution. */
     reason: string;
 }
+/** Resolve the mutually exclusive CLI and SDK acknowledgment selectors. */
+export declare function resolveUnknownAuthorAcknowledgmentSelector(rawEvents: readonly string[], allActionable: boolean): {
+    events: UnknownAuthorHistoryEvent[];
+    all_actionable: boolean;
+};
+/** Parse user-facing item or workspace history coordinates into SDK events. */
+export declare function parseUnknownAuthorHistoryEventCoordinates(values: readonly string[]): UnknownAuthorHistoryEvent[];
+/** Normalize an untyped transport payload and execute author acknowledgment. */
+export declare function acknowledgeUnknownAuthorHistoryEventsFromTransport(pmRoot: string, input: Record<string, unknown>): Promise<{
+    acknowledged: number;
+    history_path: string;
+}>;
 /**
  * Append an audited disposition for immutable unknown-author events without
  * rewriting their original streams.

package/dist/sdk/author-attribution.js

@@ -4,11 +4,28 @@
  * Provides reusable diagnostics for mutation-author provenance in tracker 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]="364a8999-58e2-58c9-bfa6-acd8c42ec471")}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]="4fd16197-979e-5269-bed7-f2fb0e2038c2")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
-import { appendWorkspaceAuditEvent } from "../core/history/workspace-history.js";
+import { appendWorkspaceAuditEvent, WORKSPACE_HISTORY_ID, } from "../core/history/workspace-history.js";
 import { readSettings } from "../core/store/settings.js";
+import { EXIT_CODE } from "../core/shared/constants.js";
+import { PmCliError } from "../core/shared/errors.js";
+import { readRuntimeString, readRuntimeStringArray } from "./runtime-input.js";
+/**
+ * Refuse an acknowledgment argument as a classified usage error.
+ *
+ * Argument validation is an expected outcome of a public mutation surface, not a
+ * product failure. Raising a bare `TypeError` left the refusal at exit code 1,
+ * which the CLI observability boundary reports as an unclassified handled error
+ * and the release gate then reads as a blocking production issue. Carrying
+ * {@link EXIT_CODE.USAGE} plus a stable code keeps the refusal teachable and
+ * keeps expected validation out of the error channel without masking genuine
+ * failures, which retain their own exit codes.
+ */
+function refuseAuthorAcknowledgmentArgument(message, context) {
+    throw new PmCliError(message, EXIT_CODE.USAGE, context);
+}
 /** First release-governance anchor after which unknown authors require remediation. */
 export const HISTORY_AUTHOR_ATTRIBUTION_BASELINE = "2026-07-15T06:22:12.276Z";
 /** Parsed epoch for the immutable attribution baseline used by every stream scan. */
@@ -187,6 +204,63 @@ export const scanHistoryAuthorAttribution = async (pmRoot, sampleLimit = 20, inc
         ...(includeActionableEvents ? { actionable_events: actionableEvents } : {}),
     };
 };
+/** Resolve the mutually exclusive CLI and SDK acknowledgment selectors. */
+export function resolveUnknownAuthorAcknowledgmentSelector(rawEvents, allActionable) {
+    const hasExplicitEvents = rawEvents.length > 0;
+    if (hasExplicitEvents && allActionable) {
+        refuseAuthorAcknowledgmentArgument("Specify exactly one selector: repeat --event or pass --all-actionable.", {
+            code: "history_author_acknowledge_selector_conflict",
+            required: "Exactly one of --event or --all-actionable",
+            examples: [
+                'pm history-author-acknowledge --event pm-a1b2:4 --attributed-author agent --reviewer maintainer --reason "Verified provenance"',
+                'pm history-author-acknowledge --all-actionable --attributed-author import-agent --reviewer maintainer --reason "Reviewed the complete actionable set"',
+            ],
+        });
+    }
+    if (!hasExplicitEvents && !allActionable) {
+        refuseAuthorAcknowledgmentArgument("Specify exactly one selector: repeat --event or pass --all-actionable.", {
+            code: "history_author_acknowledge_selector_required",
+            required: "Exactly one of --event or --all-actionable",
+            examples: [
+                'pm history-author-acknowledge --event pm-a1b2:4 --attributed-author agent --reviewer maintainer --reason "Verified provenance"',
+                'pm history-author-acknowledge --all-actionable --attributed-author import-agent --reviewer maintainer --reason "Reviewed the complete actionable set"',
+            ],
+        });
+    }
+    return {
+        events: parseUnknownAuthorHistoryEventCoordinates(rawEvents),
+        all_actionable: allActionable,
+    };
+}
+/** Parse user-facing item or workspace history coordinates into SDK events. */
+export function parseUnknownAuthorHistoryEventCoordinates(values) {
+    return values.map((value) => {
+        const separator = value.lastIndexOf(":");
+        const itemId = value.slice(0, separator).trim();
+        const line = Number(value.slice(separator + 1));
+        const validItemId = itemId === WORKSPACE_HISTORY_ID || /^[a-z0-9][a-z0-9-]*$/iu.test(itemId);
+        if (separator < 1 ||
+            !validItemId ||
+            !Number.isSafeInteger(line) ||
+            line < 1) {
+            refuseAuthorAcknowledgmentArgument(`history-author-acknowledge --event expects <item-id>:<one-based-line>, received "${value}".`, { code: "history_author_acknowledge_target_unreadable" });
+        }
+        return { item_id: itemId, line };
+    });
+}
+/** Normalize an untyped transport payload and execute author acknowledgment. */
+export function acknowledgeUnknownAuthorHistoryEventsFromTransport(pmRoot, input) {
+    const selector = resolveUnknownAuthorAcknowledgmentSelector(readRuntimeStringArray(input.historyEvent), input.allActionable === true || input.all_actionable === true);
+    return acknowledgeUnknownAuthorHistoryEvents(pmRoot, {
+        events: selector.events,
+        all_actionable: selector.all_actionable,
+        attributed_author: readRuntimeString(input, "attributedAuthor") ??
+            readRuntimeString(input, "attributed_author") ??
+            "",
+        reviewer: readRuntimeString(input, "reviewer") ?? "",
+        reason: readRuntimeString(input, "reason") ?? "",
+    });
+}
 /**
  * Append an audited disposition for immutable unknown-author events without
  * rewriting their original streams.
@@ -197,8 +271,11 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
     const reason = options.reason.trim();
     const explicitEvents = options.events ?? [];
     const selectorCount = Number(options.all_actionable === true) + Number(explicitEvents.length > 0);
+    if (selectorCount === 0) {
+        refuseAuthorAcknowledgmentArgument("Specify exactly one selector: events or all_actionable.", { code: "history_author_acknowledge_selector_required" });
+    }
     if (selectorCount > 1) {
-        throw new TypeError("Author acknowledgment accepts either explicit events or all_actionable, not both.");
+        refuseAuthorAcknowledgmentArgument("Author acknowledgment accepts either explicit events or all_actionable, not both.", { code: "history_author_acknowledge_selector_conflict" });
     }
     const selectedEvents = options.all_actionable === true
         ? (await scanHistoryAuthorAttribution(pmRoot, 0, true))
@@ -213,7 +290,7 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
         reason.length > 0,
     ].includes(false);
     if (requiredValuesMissing) {
-        throw new TypeError("Author acknowledgment requires events, reviewer, attributed_author, and reason.");
+        refuseAuthorAcknowledgmentArgument("Author acknowledgment requires events, reviewer, attributed_author, and reason.", { code: "history_author_acknowledge_required_values_missing" });
     }
     const uniqueEvents = [
         ...new Map(selectedEvents.map((event) => [
@@ -223,12 +300,13 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
     ].sort((left, right) => left.item_id.localeCompare(right.item_id) || left.line - right.line);
     for (const event of uniqueEvents) {
         const invalidCoordinate = [
-            /^[a-z0-9][a-z0-9-]*$/i.test(event.item_id),
+            event.item_id === WORKSPACE_HISTORY_ID ||
+                /^[a-z0-9][a-z0-9-]*$/i.test(event.item_id),
             Number.isSafeInteger(event.line),
             event.line >= 1,
         ].includes(false);
         if (invalidCoordinate) {
-            throw new TypeError(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`);
+            refuseAuthorAcknowledgmentArgument(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`, { code: "history_author_acknowledge_target_unreadable" });
         }
         let parsed;
         try {
@@ -237,10 +315,10 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
             parsed = JSON.parse(line ?? "");
         }
         catch {
-            throw new TypeError(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`);
+            refuseAuthorAcknowledgmentArgument(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`, { code: "history_author_acknowledge_target_unreadable" });
         }
         if (classifyHistoryAuthorEvent(parsed) !== "actionable_unknown") {
-            throw new TypeError(`Author acknowledgment target ${event.item_id}:${event.line} is not an actionable unknown-author event.`);
+            refuseAuthorAcknowledgmentArgument(`Author acknowledgment target ${event.item_id}:${event.line} is not an actionable unknown-author event.`, { code: "history_author_acknowledge_target_not_actionable" });
         }
     }
     const settings = await readSettings(pmRoot);
@@ -264,4 +342,4 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
     };
 }
 //# sourceMappingURL=author-attribution.js.map
-//# debugId=364a8999-58e2-58c9-bfa6-acd8c42ec471
+//# debugId=4fd16197-979e-5269-bed7-f2fb0e2038c2

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

@@ -29,6 +29,8 @@ export interface BootstrapGlobalOptions {
     outputBudget?: string;
     /** Canonical renderer encoding for read output. */
     outputFormat?: "toon" | "json";
+    /** Caller-carried cross-call budget and served-item state. */
+    outputSession?: string;
     /** 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]="212ba734-6a06-576f-8ad8-de759727cd75")}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]="1c2ee12c-9a3e-57bc-8336-f6c558458802")}catch(e){}}();
 import { EXECUTABLE_COMMAND_ALIASES, resolveSubcommandFlagContractsForCommand, } from "./cli-contracts.js";
 export { EXECUTABLE_COMMAND_ALIASES };
 import { levenshteinDistanceWithinLimit } from "../core/shared/levenshtein.js";
@@ -16,12 +16,14 @@ const GLOBAL_VALUE_CONSUMING_FLAGS = new Set([
     "--output-limit",
     "--output-budget",
     "--output-format",
+    "--output-session",
 ]);
 const OUTPUT_VALUE_FLAGS = new Set([
     "--output-include",
     "--output-limit",
     "--output-budget",
     "--output-format",
+    "--output-session",
 ]);
 /** Whether a global value-consuming flag uses its inline `--flag=value` form. */
 const isInlineGlobalValueToken = (token) => {
@@ -105,6 +107,9 @@ export function parseBootstrapGlobalOptions(argv) {
                 outputFormat: state.outputValues.get("--output-format"),
             }
             : {}),
+        ...(state.outputValues.get("--output-session") === undefined
+            ? {}
+            : { outputSession: state.outputValues.get("--output-session") }),
         ...(state.author === ""
             ? { authorMissingValue: true }
             : state.author !== undefined
@@ -866,4 +871,4 @@ export const _testOnly = {
     resolveCanonicalFlag,
 };
 //# sourceMappingURL=cli-bootstrap.js.map
-//# debugId=212ba734-6a06-576f-8ad8-de759727cd75
+//# debugId=1c2ee12c-9a3e-57bc-8336-f6c558458802

package/dist/sdk/cli-contracts/command-exit-contracts.d.ts

@@ -0,0 +1,118 @@
+/** Stable numeric exit codes emitted by core pm commands. */
+export type PmCommandExitCode = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7;
+/** Effect-oriented outcome vocabulary shared by shells and structured output. */
+export type PmCommandExitOutcome = "effect" | "internal_failure" | "refused_input" | "refused_tracker_state" | "conflict" | "dependency_failed" | "no_effect" | "partial_effect";
+/** Meaning and success semantics for one stable process exit. */
+export interface PmCommandExitOutcomeContract {
+    /** Stable process exit visible without parsing stdout. */
+    exit_code: PmCommandExitCode;
+    /** Effect-oriented result independent of implementation details. */
+    outcome: PmCommandExitOutcome;
+    /** Whether the command completed its requested control flow successfully. */
+    success: boolean;
+    /** Concise operator-facing meaning. */
+    meaning: string;
+}
+/** Declared numeric exits for one core command path. */
+export interface PmCommandExitContract {
+    /** Normalized command path. */
+    command: string;
+    /** Exhaustive exits the command may emit. */
+    exit_codes: readonly PmCommandExitCode[];
+}
+/** One replay observation used to verify command exit declarations. */
+export interface PmCommandExitObservation {
+    /** Command path executed by the replay. */
+    command: string;
+    /** Process exit observed from the real command boundary. */
+    exit_code: number;
+    /** Stable replay case identifier for diagnostics. */
+    replay_id: string;
+}
+/** Drift report produced by exit-contract replay conformance. */
+export interface PmCommandExitConformanceReport {
+    /** Whether all declaration and observation checks passed. */
+    ok: boolean;
+    /** Expected commands without a declaration. */
+    missing_commands: string[];
+    /** Observations whose command or numeric exit is undeclared. */
+    undeclared_observations: PmCommandExitObservation[];
+    /** Declared numeric outcomes not reached anywhere in the replay corpus. */
+    unreachable_exit_codes: PmCommandExitCode[];
+}
+/** Canonical effect vocabulary for all stable CLI process exits. */
+export declare const PM_COMMAND_EXIT_OUTCOME_CONTRACTS: readonly [{
+    readonly exit_code: 0;
+    readonly outcome: "effect";
+    readonly success: true;
+    readonly meaning: "The requested operation completed with its intended effect.";
+}, {
+    readonly exit_code: 1;
+    readonly outcome: "internal_failure";
+    readonly success: false;
+    readonly meaning: "An unexpected runtime or internal failure prevented completion.";
+}, {
+    readonly exit_code: 2;
+    readonly outcome: "refused_input";
+    readonly success: false;
+    readonly meaning: "The invocation was refused because its input or composition was invalid.";
+}, {
+    readonly exit_code: 3;
+    readonly outcome: "refused_tracker_state";
+    readonly success: false;
+    readonly meaning: "The requested tracker, item, or resource was not present.";
+}, {
+    readonly exit_code: 4;
+    readonly outcome: "conflict";
+    readonly success: false;
+    readonly meaning: "Current state or concurrency prevented the requested effect.";
+}, {
+    readonly exit_code: 5;
+    readonly outcome: "dependency_failed";
+    readonly success: false;
+    readonly meaning: "A required dependency operation failed.";
+}, {
+    readonly exit_code: 6;
+    readonly outcome: "no_effect";
+    readonly success: true;
+    readonly meaning: "The request was valid and completed, but matched nothing to change.";
+}, {
+    readonly exit_code: 7;
+    readonly outcome: "partial_effect";
+    readonly success: true;
+    readonly meaning: "The request completed and changed some, but not all, selected targets.";
+}];
+/** Exhaustive core command exit declarations generated from the command registry. */
+export declare const PM_COMMAND_EXIT_CONTRACTS: readonly PmCommandExitContract[];
+/** Stable successful process exits, including machine-distinct effect states. */
+export declare const PM_SUCCESS_EXIT_CODES: readonly [0, 6, 7];
+/** Portable success effect reported by command result envelopes. */
+export type PmCommandEffect = "effect" | "no_effect" | "partial_effect" | "dependency_failed";
+/** Shell and envelope representation of one command effect or collected failure. */
+export interface PmCommandEffectReceipt {
+    /** Semantic effect observed after command execution. */
+    outcome: PmCommandEffect;
+    /** Stable shell exit paired with the effect. */
+    exit_code: 0 | 5 | 6 | 7;
+}
+/** Counts used to derive one bulk mutation's effect without parsing prose. */
+export interface PmBulkMutationEffectCounts {
+    /** Rows that completed the requested mutation. */
+    applied: number;
+    /** Rows deliberately left unchanged. */
+    skipped: number;
+    /** Rows whose attempted mutation failed. */
+    failed: number;
+    /** Explicit requested identifiers that did not exist. */
+    unmatched: number;
+}
+/** Return whether an exit represents a successful command outcome. */
+export declare function isPmSuccessfulExitCode(exitCode: number): boolean;
+/** Return whether an exit belongs to the declared pm process vocabulary. */
+export declare function isPmKnownExitCode(exitCode: number): exitCode is PmCommandExitCode;
+/** Resolve an exact command contract, falling back to its declared root path. */
+export declare function resolvePmCommandExitContract(commandPath: string): PmCommandExitContract | undefined;
+/** Verify command coverage, observed exits, and vocabulary reachability for a replay corpus. */
+export declare function analyzePmCommandExitConformance(observations: readonly PmCommandExitObservation[], expectedCommands?: readonly string[], contracts?: readonly PmCommandExitContract[]): PmCommandExitConformanceReport;
+/** Derive deterministic full, empty, partial, or failed semantics for a bulk mutation. */
+export declare function derivePmBulkMutationEffect(counts: PmBulkMutationEffectCounts): PmCommandEffectReceipt;

package/dist/sdk/cli-contracts/command-exit-contracts.js

@@ -0,0 +1,152 @@
+/**
+ * @module sdk/command-exit-contracts
+ *
+ * Declares shell-visible command outcomes and derives effect receipts shared by
+ * CLI, SDK, MCP, packages, telemetry, and conformance gates.
+ */
+
+!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]="5bbc21f0-f517-571a-8ecf-45f20f0e793d")}catch(e){}}();
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PM_CORE_COMMAND_NAMES } from "./enum-contracts.js";
+/** Canonical effect vocabulary for all stable CLI process exits. */
+export const PM_COMMAND_EXIT_OUTCOME_CONTRACTS = [
+    {
+        exit_code: EXIT_CODE.SUCCESS,
+        outcome: "effect",
+        success: true,
+        meaning: "The requested operation completed with its intended effect.",
+    },
+    {
+        exit_code: EXIT_CODE.GENERIC_FAILURE,
+        outcome: "internal_failure",
+        success: false,
+        meaning: "An unexpected runtime or internal failure prevented completion.",
+    },
+    {
+        exit_code: EXIT_CODE.USAGE,
+        outcome: "refused_input",
+        success: false,
+        meaning: "The invocation was refused because its input or composition was invalid.",
+    },
+    {
+        exit_code: EXIT_CODE.NOT_FOUND,
+        outcome: "refused_tracker_state",
+        success: false,
+        meaning: "The requested tracker, item, or resource was not present.",
+    },
+    {
+        exit_code: EXIT_CODE.CONFLICT,
+        outcome: "conflict",
+        success: false,
+        meaning: "Current state or concurrency prevented the requested effect.",
+    },
+    {
+        exit_code: EXIT_CODE.DEPENDENCY_FAILED,
+        outcome: "dependency_failed",
+        success: false,
+        meaning: "A required dependency operation failed.",
+    },
+    {
+        exit_code: EXIT_CODE.NO_EFFECT,
+        outcome: "no_effect",
+        success: true,
+        meaning: "The request was valid and completed, but matched nothing to change.",
+    },
+    {
+        exit_code: EXIT_CODE.PARTIAL_EFFECT,
+        outcome: "partial_effect",
+        success: true,
+        meaning: "The request completed and changed some, but not all, selected targets.",
+    },
+];
+const STANDARD_COMMAND_EXIT_CODES = [
+    EXIT_CODE.SUCCESS,
+    EXIT_CODE.GENERIC_FAILURE,
+    EXIT_CODE.USAGE,
+    EXIT_CODE.NOT_FOUND,
+    EXIT_CODE.CONFLICT,
+    EXIT_CODE.DEPENDENCY_FAILED,
+];
+const EFFECT_AWARE_BULK_COMMANDS = new Set(["close-many", "update-many"]);
+/** Exhaustive core command exit declarations generated from the command registry. */
+export const PM_COMMAND_EXIT_CONTRACTS = PM_CORE_COMMAND_NAMES.map((command) => ({
+    command,
+    exit_codes: EFFECT_AWARE_BULK_COMMANDS.has(command)
+        ? [
+            ...STANDARD_COMMAND_EXIT_CODES,
+            EXIT_CODE.NO_EFFECT,
+            EXIT_CODE.PARTIAL_EFFECT,
+        ]
+        : [...STANDARD_COMMAND_EXIT_CODES],
+}));
+const COMMAND_EXIT_CONTRACT_BY_PATH = new Map(PM_COMMAND_EXIT_CONTRACTS.map((contract) => [contract.command, contract]));
+/** Stable successful process exits, including machine-distinct effect states. */
+export const PM_SUCCESS_EXIT_CODES = [
+    EXIT_CODE.SUCCESS,
+    EXIT_CODE.NO_EFFECT,
+    EXIT_CODE.PARTIAL_EFFECT,
+];
+/** Return whether an exit represents a successful command outcome. */
+export function isPmSuccessfulExitCode(exitCode) {
+    return PM_SUCCESS_EXIT_CODES.includes(exitCode);
+}
+/** Return whether an exit belongs to the declared pm process vocabulary. */
+export function isPmKnownExitCode(exitCode) {
+    return PM_COMMAND_EXIT_OUTCOME_CONTRACTS.some((contract) => contract.exit_code === exitCode);
+}
+/** Resolve an exact command contract, falling back to its declared root path. */
+export function resolvePmCommandExitContract(commandPath) {
+    const normalized = commandPath
+        .trim()
+        .toLowerCase()
+        .split(/\s+/u)
+        .filter(Boolean)
+        .join(" ");
+    return (COMMAND_EXIT_CONTRACT_BY_PATH.get(normalized) ??
+        COMMAND_EXIT_CONTRACT_BY_PATH.get(normalized.split(" ")[0]));
+}
+/** Verify command coverage, observed exits, and vocabulary reachability for a replay corpus. */
+export function analyzePmCommandExitConformance(observations, expectedCommands = PM_CORE_COMMAND_NAMES, contracts = PM_COMMAND_EXIT_CONTRACTS) {
+    const contractsByCommand = new Map(contracts.map((contract) => [contract.command, contract]));
+    const missingCommands = expectedCommands.filter((command) => !contractsByCommand.has(command));
+    const undeclaredObservations = observations.filter((observation) => {
+        const contract = contractsByCommand.get(observation.command) ??
+            contractsByCommand.get(observation.command.split(" ")[0]);
+        return (contract === undefined ||
+            !contract.exit_codes.includes(observation.exit_code));
+    });
+    const observedExitCodes = new Set(observations.map((entry) => entry.exit_code));
+    const declaredExitCodes = new Set(contracts.flatMap((contract) => contract.exit_codes));
+    const unreachableExitCodes = [...declaredExitCodes]
+        .filter((exitCode) => !observedExitCodes.has(exitCode))
+        .sort((left, right) => left - right);
+    return {
+        ok: missingCommands.length === 0 &&
+            undeclaredObservations.length === 0 &&
+            unreachableExitCodes.length === 0,
+        missing_commands: missingCommands,
+        undeclared_observations: undeclaredObservations,
+        unreachable_exit_codes: unreachableExitCodes,
+    };
+}
+/** Derive deterministic full, empty, partial, or failed semantics for a bulk mutation. */
+export function derivePmBulkMutationEffect(counts) {
+    if (counts.applied === 0 && counts.failed > 0) {
+        return {
+            outcome: "dependency_failed",
+            exit_code: EXIT_CODE.DEPENDENCY_FAILED,
+        };
+    }
+    if (counts.applied === 0) {
+        return { outcome: "no_effect", exit_code: EXIT_CODE.NO_EFFECT };
+    }
+    if (counts.skipped > 0 || counts.failed > 0 || counts.unmatched > 0) {
+        return {
+            outcome: "partial_effect",
+            exit_code: EXIT_CODE.PARTIAL_EFFECT,
+        };
+    }
+    return { outcome: "effect", exit_code: EXIT_CODE.SUCCESS };
+}
+//# sourceMappingURL=command-exit-contracts.js.map
+//# debugId=5bbc21f0-f517-571a-8ecf-45f20f0e793d

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

@@ -7,11 +7,11 @@
  * 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]="5f5b9bd3-1b92-5fb2-b649-6eb942a7a3c4")}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]="0fd4d2b0-725f-53ed-8b2b-2eeb19406cb7")}catch(e){}}();
 import { PM_TOOL_ACTIONS } from "./enum-contracts.js";
 import { resolveSubcommandFlagContractsForCommand, } from "./flag-contracts.js";
 import { pmToolActionParameterKeys } from "./tool-schema.js";
-import { PM_READ_OUTPUT_OPTION_FLAGS, resolveReadOutputSurface, } from "../read-output-contracts.js";
+import { PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS, PM_READ_OUTPUT_OPTION_FLAGS, resolveReadOutputSurface, } from "../read-output-contracts.js";
 const CLI_TRANSPORT_FLAGS = new Set([
     "--author",
     "--follow",
@@ -22,6 +22,7 @@ const CLI_TRANSPORT_FLAGS = new Set([
     "--output-limit",
     "--output-budget",
     "--output-format",
+    "--output-session",
     "--no-changed-fields",
     "--no-extensions",
     "--no-pager",
@@ -30,7 +31,10 @@ const CLI_TRANSPORT_FLAGS = new Set([
     "--quiet",
     "--interval-ms",
 ]);
-const READ_OUTPUT_OPTION_FLAGS = new Set(PM_READ_OUTPUT_OPTION_FLAGS);
+const READ_OUTPUT_OPTION_FLAGS = new Set([
+    ...PM_READ_OUTPUT_OPTION_FLAGS,
+    ...PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS,
+]);
 const CLI_PRESENTATION_FLAGS = new Set([
     "--brief",
     "--format",
@@ -116,7 +120,9 @@ const ACTION_FLAG_PARAMETER_OVERRIDES = {
     },
     files: { "--note": "addNote" },
     docs: { "--note": "addNote" },
-    notes: { "--file": "text" },
+    comments: { "--full-history": "full" },
+    notes: { "--file": "text", "--full-history": "full" },
+    learnings: { "--full-history": "full" },
     gc: { "--scope": "gcScope" },
     contracts: { "--action": "contractAction" },
     schema: {
@@ -137,6 +143,27 @@ const ACTION_FLAG_PARAMETER_OVERRIDES = {
     package: { "--gh": "github", "--scaffold": "init" },
     install: { "--gh": "github" },
 };
+const ACTION_STRUCTURED_FLAG_PARAMETERS = {
+    stats: {
+        "--analytics": [
+            "measurements",
+            "metric",
+            "measurementLimit",
+            "observe",
+            "improvementDirection",
+            "measurementSource",
+            "measurementItem",
+            "measurementRevision",
+            "author",
+            "message",
+            "provenanceCoverage",
+            "fleetAttribution",
+            "since",
+            "eventLimit",
+            "minimumSample",
+        ],
+    },
+};
 function actionCommand(action) {
     if (action.startsWith("extension-")) {
         return `extension ${action.slice("extension-".length)}`;
@@ -168,6 +195,17 @@ function aliasTarget(flag, contracts) {
     return contracts.find(({ aliases }) => aliases?.includes(flag))?.flag;
 }
 function classifyCliInput(action, contract, contracts, sdkParameters) {
+    const structuredParameters = ACTION_STRUCTURED_FLAG_PARAMETERS[action]?.[contract.flag];
+    if (structuredParameters !== undefined &&
+        structuredParameters.every((parameter) => sdkParameters.has(parameter))) {
+        return {
+            surface: "cli",
+            input: contract.flag,
+            counterpart: structuredParameters[0],
+            disposition: "shared",
+            reason: "The validated CLI JSON object fans out across strict SDK parameters.",
+        };
+    }
     const parameter = parameterForFlag(action, contract.flag);
     if (sdkParameters.has(parameter)) {
         return {
@@ -242,6 +280,17 @@ function classifyCliInput(action, contract, contracts, sdkParameters) {
     };
 }
 function classifySdkInput(action, parameter, cliEntries) {
+    const structuredCounterpart = Object.entries(ACTION_STRUCTURED_FLAG_PARAMETERS[action] ?? {}).find(([flag, parameters]) => parameters.includes(parameter) &&
+        cliEntries.some(({ input, disposition }) => input === flag && disposition === "shared"));
+    if (structuredCounterpart !== undefined) {
+        return {
+            surface: "sdk",
+            input: parameter,
+            counterpart: structuredCounterpart[0],
+            disposition: "shared",
+            reason: "The strict SDK parameter is reachable through the validated CLI JSON object.",
+        };
+    }
     const cliCounterpart = cliEntries.find(({ counterpart, disposition }) => counterpart === parameter &&
         (disposition === "shared" ||
             disposition === "compatibility_alias" ||
@@ -317,4 +366,4 @@ export function analyzeSdkCliParameterCompleteness(source = {}) {
     });
 }
 //# sourceMappingURL=completeness.js.map
-//# debugId=5f5b9bd3-1b92-5fb2-b649-6eb942a7a3c4
+//# debugId=0fd4d2b0-725f-53ed-8b2b-2eeb19406cb7

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]="01e8d488-ce63-54cc-848e-e7842a9d873d")}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]="932a6144-c4b4-5153-b8ff-0ef29e308bd0")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { RESERVED_EXTENSION_HOST_FLAGS } from "../../core/extensions/reserved-host-flags.js";
 function normalizeFlagAliasKey(flag) {
@@ -222,6 +222,7 @@ export const COMMENTS_FLAG_CONTRACTS = [
     { flag: "--edit" },
     { flag: "--delete" },
     { flag: "--limit" },
+    { flag: "--full-history" },
     { flag: "--author" },
     { flag: "--message" },
     { flag: "--force" },
@@ -243,6 +244,7 @@ export const NOTES_FLAG_CONTRACTS = [
     { flag: "--since" },
     { flag: "--event-type" },
     { flag: "--include-meta" },
+    { flag: "--full-history" },
     { flag: "--author" },
     { flag: "--message" },
     { flag: "--force" },
@@ -251,6 +253,7 @@ export const NOTES_FLAG_CONTRACTS = [
 export const LEARNINGS_FLAG_CONTRACTS = [
     { flag: "--add", aliases: ["--learning"] },
     { flag: "--limit" },
+    { flag: "--full-history" },
     { flag: "--author" },
     { flag: "--message" },
     { flag: "--force" },
@@ -911,6 +914,7 @@ export const STATS_FLAG_CONTRACTS = [
     { flag: "--by-tag" },
     { flag: "--by-priority" },
     { flag: "--tag-prefix" },
+    { flag: "--analytics" },
 ];
 /** Public contract for duplicate-cluster discovery flags. */
 export const DUPLICATES_FLAG_CONTRACTS = [
@@ -1751,4 +1755,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=01e8d488-ce63-54cc-848e-e7842a9d873d
+//# debugId=932a6144-c4b4-5153-b8ff-0ef29e308bd0