@unbrained/pm-cli 2026.8.10 → 2026.8.12

package/dist/sdk/agent/refusal-reachability.js

@@ -0,0 +1,72 @@
+/** Compare declared refusal states with real-entrypoint observations. */
+
+!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]="55318c8e-1fbd-5abd-b18f-f0cc1f81dd5c")}catch(e){}}();
+export function verifyPmRefusalReachability(catalog, observations) {
+    const declarations = catalog.flatMap((contract) => (contract.owned_states ?? []).map((state) => ({ contract, state })));
+    const findings = [];
+    const observationsByProbe = new Map();
+    for (const observation of observations) {
+        if (observationsByProbe.has(observation.probe_id)) {
+            findings.push({
+                kind: "duplicate_probe",
+                probe_id: observation.probe_id,
+                detail: `Observation ${observation.probe_id} was supplied more than once.`,
+            });
+            continue;
+        }
+        observationsByProbe.set(observation.probe_id, observation);
+    }
+    const declaredProbeIds = new Set(declarations.map(({ state }) => state.probe_id));
+    for (const { contract, state } of declarations) {
+        const observation = observationsByProbe.get(state.probe_id);
+        if (!observation) {
+            findings.push({
+                kind: "missing_probe",
+                probe_id: state.probe_id,
+                detail: `No entrypoint observation was recorded for ${contract.code}.`,
+            });
+            continue;
+        }
+        if (observation.code !== contract.code) {
+            findings.push({
+                kind: "wrong_error_code",
+                probe_id: state.probe_id,
+                detail: `Expected ${contract.code}; observed ${observation.code}.`,
+            });
+        }
+        if (observation.exit_class !== state.expected_exit_class) {
+            findings.push({
+                kind: "wrong_exit_class",
+                probe_id: state.probe_id,
+                detail: `Expected ${state.expected_exit_class}; observed ${observation.exit_class}.`,
+            });
+        }
+        if (!state.entrypoints.includes(observation.entrypoint)) {
+            findings.push({
+                kind: "wrong_entrypoint",
+                probe_id: state.probe_id,
+                detail: `Expected one of ${state.entrypoints.join(", ")}; observed ${observation.entrypoint}.`,
+            });
+        }
+    }
+    for (const observation of observations) {
+        if (!declaredProbeIds.has(observation.probe_id)) {
+            findings.push({
+                kind: "undeclared_probe",
+                probe_id: observation.probe_id,
+                detail: `Observation ${observation.probe_id} has no catalog declaration.`,
+            });
+        }
+    }
+    findings.sort((left, right) => left.probe_id !== right.probe_id
+        ? left.probe_id.localeCompare(right.probe_id)
+        : left.kind.localeCompare(right.kind));
+    return {
+        ok: findings.length === 0,
+        declared_probe_count: declarations.length,
+        observed_probe_count: observations.length,
+        findings,
+    };
+}
+//# sourceMappingURL=refusal-reachability.js.map
+//# debugId=55318c8e-1fbd-5abd-b18f-f0cc1f81dd5c

package/dist/sdk/agent/subcommand-recovery.d.ts

@@ -0,0 +1,40 @@
+import { PmCliError, type PmCliErrorRecoveryPayload } from "../../core/shared/errors.js";
+/** Catalog-only alias retained for consumers of the former package lifecycle code. */
+export declare const UNKNOWN_SUBCOMMAND_COMPATIBILITY_CODES: readonly [{
+    readonly code: "unknown_lifecycle_action";
+}];
+/** Inputs for constructing a portable unknown-subcommand refusal. */
+export interface UnknownSubcommandErrorOptions {
+    /** Command family path without the rejected token. */
+    command_path: string;
+    /** Rejected positional token. */
+    token: string;
+    /** Complete declared subcommand vocabulary for the family. */
+    allowed: readonly string[];
+    /** Human-readable command family, defaulting to `pm <command_path>`. */
+    display_name?: string;
+    /** Positional token role used in the compatibility message. */
+    token_kind?: "subcommand" | "action" | "path";
+    /** Arguments that follow the rejected token and should survive a retry. */
+    trailing_args?: readonly string[];
+    /** Family-aware retry that takes precedence over edit-distance recovery. */
+    retry_command?: string;
+    /** Compatibility suffix appended after the allowed-value sentence. */
+    message_suffix?: string;
+    /** Additional ranked recovery candidates supplied by the command family. */
+    fallback_candidates?: PmCliErrorRecoveryPayload["fallback_candidates"];
+    /** Transport exit used by non-CLI protocol adapters. */
+    exit_code?: number;
+    /** Additional family-specific examples. */
+    examples?: readonly string[];
+}
+declare function nearestSubcommand(token: string, allowed: readonly string[]): string | undefined;
+declare function renderCommand(tokens: readonly string[]): string;
+/** Build the shared typed refusal used by CLI, SDK, MCP, and packages. */
+export declare function createUnknownSubcommandError(options: UnknownSubcommandErrorOptions): PmCliError;
+/** Test-only access to deterministic nearest-match behavior. */
+export declare const _testOnly: {
+    nearestSubcommand: typeof nearestSubcommand;
+    renderCommand: typeof renderCommand;
+};
+export {};

package/dist/sdk/agent/subcommand-recovery.js

@@ -0,0 +1,84 @@
+/**
+ * @module sdk/agent/subcommand-recovery
+ *
+ * Provides one SDK-owned refusal contract for unknown positional subcommands.
+ */
+
+!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]="a9b23a46-0bba-5174-8793-dfc37016d1fb")}catch(e){}}();
+import { levenshteinDistanceWithinLimit } from "../../core/shared/levenshtein.js";
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError, } from "../../core/shared/errors.js";
+/** Catalog-only alias retained for consumers of the former package lifecycle code. */
+export const UNKNOWN_SUBCOMMAND_COMPATIBILITY_CODES = [
+    { code: "unknown_lifecycle_action" },
+];
+function nearestSubcommand(token, allowed) {
+    const normalized = token.trim().toLowerCase();
+    if (normalized.length === 0)
+        return undefined;
+    const maxDistance = Math.floor(normalized.length / 3);
+    return allowed
+        .map((candidate) => ({
+        candidate,
+        distance: levenshteinDistanceWithinLimit(normalized, candidate.toLowerCase(), maxDistance) ?? Number.POSITIVE_INFINITY,
+    }))
+        .filter(({ distance }) => Number.isFinite(distance))
+        .sort((left, right) => left.distance !== right.distance
+        ? left.distance - right.distance
+        : left.candidate.localeCompare(right.candidate))[0]?.candidate;
+}
+function renderCommand(tokens) {
+    return ["pm", ...tokens]
+        .map((token) => /^[A-Za-z0-9_./:@=-]+$/u.test(token) ? token : JSON.stringify(token))
+        .join(" ");
+}
+/** Build the shared typed refusal used by CLI, SDK, MCP, and packages. */
+export function createUnknownSubcommandError(options) {
+    const commandPath = options.command_path.trim().replaceAll(/\s+/gu, " ");
+    const normalizedToken = options.token.trim();
+    const token = normalizedToken.length === 0 ? "<empty>" : normalizedToken;
+    const allowed = [...new Set(options.allowed.map((value) => value.trim()))]
+        .filter(Boolean)
+        .sort((left, right) => left.localeCompare(right));
+    if (commandPath.length === 0 || token.length === 0 || allowed.length === 0) {
+        throw new TypeError("Unknown-subcommand contracts require a path, token, and allowed set");
+    }
+    const commandTokens = commandPath.split(" ");
+    const trailingArgs = options.trailing_args ?? [];
+    const displayName = options.display_name ?? `pm ${commandPath}`;
+    const tokenKind = options.token_kind ?? "subcommand";
+    const nearest = options.retry_command
+        ? undefined
+        : nearestSubcommand(token, allowed);
+    const attemptedCommand = renderCommand([
+        ...commandTokens,
+        token,
+        ...trailingArgs,
+    ]);
+    const suggestedRetry = options.retry_command ??
+        (nearest
+            ? renderCommand([...commandTokens, nearest, ...trailingArgs])
+            : undefined);
+    return new PmCliError(`Unknown ${displayName} ${tokenKind} "${token}". Allowed: ${allowed.join(", ")}${options.message_suffix ?? ""}`, options.exit_code ?? EXIT_CODE.USAGE, {
+        code: "unknown_subcommand",
+        reason: "unknown_positional_token",
+        examples: [
+            ...(suggestedRetry ? [suggestedRetry] : []),
+            ...(options.examples ?? []),
+            `pm ${commandPath} --help`,
+        ],
+        nextSteps: suggestedRetry
+            ? [`Retry with the suggested command: ${suggestedRetry}`]
+            : ["Choose one value from recovery.allowed_values."],
+        recovery: {
+            attempted_command: attemptedCommand,
+            allowed_values: allowed,
+            suggested_retry: suggestedRetry,
+            fallback_candidates: options.fallback_candidates,
+        },
+    });
+}
+/** Test-only access to deterministic nearest-match behavior. */
+export const _testOnly = { nearestSubcommand, renderCommand };
+//# sourceMappingURL=subcommand-recovery.js.map
+//# debugId=a9b23a46-0bba-5174-8793-dfc37016d1fb

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. */
@@ -49,6 +51,14 @@ export interface BootstrapHelpRequest {
 }
 /** Implements parse bootstrap help request for the public runtime surface of this module. */
 export declare function parseBootstrapHelpRequest(argv: string[]): BootstrapHelpRequest;
+/**
+ * Index of the command token in argv — the first non-flag token, skipping the
+ * value-consuming/global bootstrap flags. Returns undefined when there is none
+ * (bare invocation, only global flags, or a leading `--`). Single source of truth
+ * for command-position scanning shared by {@link parseBootstrapCommandName} and the
+ * command-alias rewrite so their precedence rules can never drift apart.
+ */
+export declare function findBootstrapCommandTokenIndex(argv: string[]): number | undefined;
 /** Implements parse bootstrap command name for the public runtime surface of this module. */
 export declare function parseBootstrapCommandName(argv: string[]): string | undefined;
 /** Implements apply bootstrap pager policy for the public runtime surface of this module. */

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]="a53eea26-8b9e-5666-aa32-66b4dc4cd868")}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") }),
@@ -194,7 +198,7 @@ export function parseBootstrapHelpRequest(argv) {
  * for command-position scanning shared by {@link parseBootstrapCommandName} and the
  * command-alias rewrite so their precedence rules can never drift apart.
  */
-function findCommandTokenIndex(argv) {
+export function findBootstrapCommandTokenIndex(argv) {
     for (let index = 0; index < argv.length; index += 1) {
         const token = argv[index];
         if (token === "--") {
@@ -220,7 +224,7 @@ function findCommandTokenIndex(argv) {
 }
 /** Implements parse bootstrap command name for the public runtime surface of this module. */
 export function parseBootstrapCommandName(argv) {
-    const index = findCommandTokenIndex(argv);
+    const index = findBootstrapCommandTokenIndex(argv);
     return index === undefined ? undefined : argv[index].trim().toLowerCase();
 }
 function shouldDisablePagerForInvocation(argv, bootstrapGlobal) {
@@ -279,7 +283,7 @@ const EXTENSION_ACTION_SYNTAX_TOKENS = new Set([
 ]);
 /** Implements normalize legacy extension action syntax for the public runtime surface of this module. */
 export function normalizeLegacyExtensionActionSyntax(argv) {
-    const extensionIndex = findCommandTokenIndex(argv);
+    const extensionIndex = findBootstrapCommandTokenIndex(argv);
     if (extensionIndex === undefined || argv[extensionIndex] !== "extension") {
         return [...argv];
     }
@@ -310,7 +314,7 @@ const CLI_EXECUTABLE_ALIASES = new Set(["pm", "pm-cli"]);
  * `bunx <package> pm-cli init` behave like direct executable invocations.
  */
 function stripLeadingExecutableAlias(argv, trace) {
-    const index = findCommandTokenIndex(argv);
+    const index = findBootstrapCommandTokenIndex(argv);
     if (index === undefined) {
         return argv;
     }
@@ -334,7 +338,7 @@ function stripLeadingExecutableAlias(argv, trace) {
  * value-consuming global flag, mirroring {@link parseBootstrapCommandName}.
  */
 function rewriteCommandAlias(argv, trace) {
-    const index = findCommandTokenIndex(argv);
+    const index = findBootstrapCommandTokenIndex(argv);
     if (index === undefined) {
         return argv;
     }
@@ -886,4 +890,4 @@ export const _testOnly = {
     resolveCanonicalFlag,
 };
 //# sourceMappingURL=cli-bootstrap.js.map
-//# debugId=a53eea26-8b9e-5666-aa32-66b4dc4cd868
+//# 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]="0fd4d2b0-725f-53ed-8b2b-2eeb19406cb7")}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",
@@ -76,6 +77,11 @@ const CLI_POSITIONAL_PARAMETERS = new Set([
     "text",
 ]);
 const ACTION_POSITIONAL_PARAMETERS = {
+    assurance: {
+        id: "<id>",
+        kind: "<kind>",
+        subcommand: "<action>",
+    },
     event: { title: "<title>" },
     files: { lookupPath: "lookup <path...>" },
     meet: { title: "<title>" },
@@ -89,6 +95,7 @@ const ACTION_POSITIONAL_PARAMETERS = {
     },
 };
 const ACTION_FLAG_PARAMETER_OVERRIDES = {
+    assurance: { "--tree": "treeId" },
     init: {
         "--id-prefix": "idPrefix",
         "--no-merge-fence": "mergeFence",
@@ -143,6 +150,9 @@ const ACTION_FLAG_PARAMETER_OVERRIDES = {
     package: { "--gh": "github", "--scaffold": "init" },
     install: { "--gh": "github" },
 };
+const GLOBAL_FLAG_PARAMETER_OVERRIDES = {
+    "--pm-path": "path",
+};
 const ACTION_STRUCTURED_FLAG_PARAMETERS = {
     stats: {
         "--analytics": [
@@ -174,7 +184,8 @@ function actionCommand(action) {
     return action;
 }
 function parameterForFlag(action, flag) {
-    const override = ACTION_FLAG_PARAMETER_OVERRIDES[action]?.[flag];
+    const override = ACTION_FLAG_PARAMETER_OVERRIDES[action]?.[flag] ??
+        GLOBAL_FLAG_PARAMETER_OVERRIDES[flag];
     if (override !== undefined)
         return override;
     return flag
@@ -366,4 +377,4 @@ export function analyzeSdkCliParameterCompleteness(source = {}) {
     });
 }
 //# sourceMappingURL=completeness.js.map
-//# debugId=0fd4d2b0-725f-53ed-8b2b-2eeb19406cb7
+//# debugId=13847453-3016-5855-a816-2cadc2ca4870

package/dist/sdk/cli-contracts/enum-contracts.d.ts

@@ -23,7 +23,7 @@ export declare const PM_EXTENSION_POLICY_SURFACE_CONTRACTS: readonly ["commands.
 /** Restricts pm extension policy surface contract values accepted by command, SDK, and storage contracts. */
 export type PmExtensionPolicySurfaceContract = (typeof PM_EXTENSION_POLICY_SURFACE_CONTRACTS)[number];
 /** Public contract for pm core command names, shared by SDK and presentation-layer consumers. */
-export declare const PM_CORE_COMMAND_NAMES: readonly ["init", "config", "extension", "package", "packages", "install", "upgrade", "create", "item", "copy", "focus", "list", "list-all", "list-draft", "list-open", "list-in-progress", "list-blocked", "list-closed", "list-canceled", "aggregate", "context", "ctx", "get", "graph", "search", "duplicates", "eval", "next", "history", "events", "history-redact", "history-repair", "history-compact", "history-author-acknowledge", "merge", "schema", "profile", "activity", "restore", "update", "update-many", "close", "close-many", "delete", "append", "comments", "notes", "learnings", "files", "docs", "deps", "plan", "test", "test-all", "telemetry", "stats", "health", "validate", "gc", "workspace", "contracts", "claim", "release", "start-task", "pause-task", "close-task", "meet", "event", "remind", "help"];
+export declare const PM_CORE_COMMAND_NAMES: readonly ["init", "config", "extension", "package", "packages", "install", "upgrade", "create", "item", "copy", "focus", "list", "list-all", "list-draft", "list-open", "list-in-progress", "list-blocked", "list-closed", "list-canceled", "aggregate", "context", "ctx", "get", "graph", "search", "duplicates", "eval", "next", "history", "events", "history-redact", "history-repair", "history-compact", "history-author-acknowledge", "merge", "schema", "profile", "activity", "restore", "update", "update-many", "close", "close-many", "delete", "append", "comments", "notes", "learnings", "files", "docs", "deps", "plan", "test", "test-all", "telemetry", "stats", "health", "validate", "assurance", "gc", "workspace", "contracts", "claim", "release", "start-task", "pause-task", "close-task", "meet", "event", "remind", "help"];
 /** Supported values accepted by the graph subcommand contract across CLI, SDK, and MCP surfaces. */
 export declare const GRAPH_SUBCOMMAND_VALUES: readonly ["ancestors", "descendants", "predecessors", "successors", "paths", "impact", "analyze", "audit", "communities", "redundancy", "dominators", "slack", "centrality", "articulation", "plan", "index"];
 /** Restricts graph subcommand values accepted by command, SDK, and MCP contracts. */

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

@@ -4,7 +4,7 @@
  * Defines SDK command-contract metadata for Enum Contracts.
  */
 
-!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]="15daa637-4d30-5794-bdb5-87585d443cd3")}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]="818ca284-2aaa-5d35-b280-8c963d443b0c")}catch(e){}}();
 import { KNOWN_EXTENSION_CAPABILITIES, KNOWN_EXTENSION_POLICY_MODES, KNOWN_EXTENSION_POLICY_SURFACES, KNOWN_EXTENSION_SANDBOX_PROFILES, KNOWN_EXTENSION_SERVICE_NAMES, KNOWN_EXTENSION_TRUST_MODES, } from "../../core/extensions/extension-types.js";
 /** Public contract for pm extension capability contracts, shared by SDK and presentation-layer consumers. */
 export const PM_EXTENSION_CAPABILITY_CONTRACTS = [
@@ -90,6 +90,7 @@ export const PM_CORE_COMMAND_NAMES = [
     "stats",
     "health",
     "validate",
+    "assurance",
     "gc",
     "workspace",
     "contracts",
@@ -190,4 +191,4 @@ export function isPmExtensionPolicySurfaceContract(value) {
     return PM_EXTENSION_POLICY_SURFACE_CONTRACTS.includes(value);
 }
 //# sourceMappingURL=enum-contracts.js.map
-//# debugId=15daa637-4d30-5794-bdb5-87585d443cd3
+//# debugId=818ca284-2aaa-5d35-b280-8c963d443b0c

package/dist/sdk/cli-contracts/flag-contracts.d.ts

@@ -168,6 +168,8 @@ export declare const DUPLICATES_FLAG_CONTRACTS: CliFlagContract[];
 export declare const HEALTH_FLAG_CONTRACTS: CliFlagContract[];
 /** Public contract for validate flag contracts, shared by SDK and presentation-layer consumers. */
 export declare const VALIDATE_FLAG_CONTRACTS: CliFlagContract[];
+/** Public assurance registry and gate-evaluation flag contracts. */
+export declare const ASSURANCE_FLAG_CONTRACTS: CliFlagContract[];
 /** Creates flag contracts using the validated operation inputs. */
 export declare const CREATE_FLAG_CONTRACTS: CliFlagContract[];
 /** Atomic item-batch flags shared by contracts, help, and completions. */

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]="e54d77e5-5c63-5ab6-9ea1-71ed8a1e433d")}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) {
@@ -279,6 +279,9 @@ export const FILES_FLAG_CONTRACTS = [
     { flag: "--offset" },
     { flag: "--no-truncate" },
     { flag: "--strict-read" },
+    { flag: "--explain" },
+    { flag: "--lines", value_name: "start:end" },
+    { flag: "--decision-depth", value_name: "n", value_type: "number" },
     { flag: "--author" },
     { flag: "--message" },
     { flag: "--force" },
@@ -872,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" },
@@ -937,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" },
@@ -1003,6 +1008,17 @@ export const VALIDATE_FLAG_CONTRACTS = [
     { flag: "--counts" },
     { flag: "--full" },
 ];
+/** Public assurance registry and gate-evaluation flag contracts. */
+export const ASSURANCE_FLAG_CONTRACTS = [
+    { flag: "--definition", value_name: "json" },
+    { flag: "--trigger", value_name: "value" },
+    { flag: "--tree", value_name: "value" },
+    { flag: "--gate", value_name: "id" },
+    { flag: "--limit", value_name: "number" },
+    { flag: "--dry-run" },
+    { flag: "--author", value_name: "value" },
+    { flag: "--message", value_name: "value" },
+];
 const ITEM_OWNERSHIP_AND_ISSUE_FLAG_CONTRACTS = [
     { flag: "--assignee" },
     { flag: "--parent" },
@@ -1377,6 +1393,7 @@ export const ACTIVITY_FLAG_CONTRACTS = [
     { flag: "--limit" },
     { flag: "--unbounded" },
     { flag: "--compact" },
+    { flag: "--raw" },
     { flag: "--full" },
     { flag: "--provenance" },
     { flag: "--provenance-summary" },
@@ -1694,6 +1711,7 @@ const SUBCOMMAND_FLAG_CONTRACTS_BY_COMMAND = new Map([
     ["test-all", TEST_ALL_FLAG_CONTRACTS],
     ["telemetry", TELEMETRY_FLAG_CONTRACTS],
     ["health", HEALTH_FLAG_CONTRACTS],
+    ["assurance", ASSURANCE_FLAG_CONTRACTS],
     ["validate", VALIDATE_FLAG_CONTRACTS],
     ["gc", GC_FLAG_CONTRACTS],
     ["stats", STATS_FLAG_CONTRACTS],
@@ -1796,4 +1814,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=e54d77e5-5c63-5ab6-9ea1-71ed8a1e433d
+//# debugId=40309a44-7d45-5333-9003-6fc740e827c8

package/dist/sdk/cli-contracts/registration-helpers.d.ts

@@ -70,22 +70,39 @@ export declare function printActivityJsonStream(result: ActivityCommandResult, o
 export declare function normalizeSearchOptions(options: Record<string, unknown>): Record<string, unknown>;
 /** Implements normalize search keywords input for the public runtime surface of this module. */
 export declare function normalizeSearchKeywordsInput(keywords: string[]): string;
-/** Implements normalize activity options for the public runtime surface of this module. */
-export declare function normalizeActivityOptions(options: Record<string, unknown>): {
+/** Canonical Commander-normalized activity query options. */
+export interface NormalizedActivityOptions {
+    /** Exact item identifier filter. */
     id?: string;
+    /** Exact immutable history operation filter. */
     op?: string;
+    /** Exact recorded author filter. */
     author?: string;
+    /** Inclusive activity window lower bound. */
     from?: string;
+    /** Inclusive activity window upper bound. */
     to?: string;
+    /** Maximum projected row count encoded as Commander text. */
     limit?: string;
+    /** Select the compact raw-event projection. */
     compact?: boolean;
+    /** Select a raw event projection instead of the item digest. */
+    raw?: boolean;
+    /** Disable the default projection row bound. */
     unbounded?: boolean;
+    /** Select privacy-safe provenance event rows. */
     provenance?: boolean;
+    /** Include constant-size provenance completeness metrics. */
     provenanceSummary?: boolean;
+    /** Canonical harness filters supplied by Commander. */
     harness?: string[];
+    /** Privacy-safe agent invocation fingerprint filters. */
     agentInstance?: string[];
+    /** Exact provenance dimension predicates. */
     provenanceFilter?: string[];
-};
+}
+/** Implements normalize activity options for the public runtime surface of this module. */
+export declare function normalizeActivityOptions(options: Record<string, unknown>): NormalizedActivityOptions;
 /** Implements resolve activity stream mode for the public runtime surface of this module. */
 export declare function resolveActivityStreamMode(raw: unknown): boolean;
 /** Implements normalize context options for the public runtime surface of this module. */

package/dist/sdk/cli-contracts/registration-helpers.js

@@ -4,7 +4,7 @@
  * Provides CLI runtime support for Registration Helpers.
  */
 
-!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]="5f92dd0d-4eb1-5a7b-8891-931dd15deb81")}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]="daefefd1-3b0b-513d-8b8c-ab17f90b995a")}catch(e){}}();
 import { Option } from "commander";
 import { pathExists, refreshSearchArtifactsForMutation, shouldRunSearchRefreshInForeground, EXIT_CODE, PmCliError, printError, printResult, writeStdout, getSettingsPath, resolvePmRoot, readSettings, runActiveServiceOverride, setActiveCommandResult, } from "../runtime-primitives.js";
 import { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, readFirstValueFromCommanderOptions, readFirstStringFromCommanderOptions, readStringArrayFromCommanderOptions, } from "../cli-contracts.js";
@@ -100,7 +100,7 @@ export function getGlobalOptions(command) {
         : typeof reader.opts === "function"
             ? reader.opts()
             : {};
-    return {
+    const normalized = {
         json: opts.json === true ? true : undefined,
         quiet: Boolean(opts.quiet),
         noChangedFields: opts.changedFields === false,
@@ -112,20 +112,19 @@ export function getGlobalOptions(command) {
         outputLimit: readStringCommandOption(opts, "outputLimit"),
         outputBudget: readStringCommandOption(opts, "outputBudget"),
         outputSession: readStringCommandOption(opts, "outputSession"),
+        ...(opts.outputRowContract === true ? { outputRowContract: true } : {}),
         ...(opts.outputFormat === "toon" || opts.outputFormat === "json"
             ? { outputFormat: opts.outputFormat }
             : {}),
-        path: typeof opts.pmPath === "string"
-            ? opts.pmPath
-            : typeof opts.path === "string"
-                ? opts.path
-                : undefined,
+        path: readStringCommandOption(opts, "pmPath") ??
+            readStringCommandOption(opts, "path"),
         noExtensions: opts.extensions === false,
         noPager: Boolean(opts.noPager),
         profile: Boolean(opts.profile),
         ...(commandPath.length > 0 ? { command: commandPath } : {}),
         ...(typeof opts.author === "string" ? { author: opts.author } : {}),
     };
+    return normalized;
 }
 /** Implements get command path for the public runtime surface of this module. */
 export function getCommandPath(command) {
@@ -239,6 +238,7 @@ export function buildBackgroundTestCommandArgs(id, options) {
     pushRepeatableValueFlag(args, "--add", options.add);
     pushRepeatableValueFlag(args, "--add-json", options.addJson);
     pushRepeatableValueFlag(args, "--remove", options.remove);
+    pushRepeatableValueFlag(args, "--remove-index", options.removeIndex);
     pushOptionalValueFlag(args, "--match", options.match);
     pushOptionalValueFlag(args, "--only-index", options.onlyIndex);
     pushOptionalBooleanFlag(args, "--only-last", options.onlyLast);
@@ -792,7 +792,7 @@ export function normalizeSearchKeywordsInput(keywords) {
 /** Implements normalize activity options for the public runtime surface of this module. */
 export function normalizeActivityOptions(options) {
     const readActivityString = (target) => readFirstStringFromCommanderOptions(options, resolveCommanderContract(ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, target));
-    return {
+    const normalized = {
         id: readActivityString("id"),
         op: readActivityString("op"),
         author: readActivityString("author"),
@@ -801,9 +801,14 @@ export function normalizeActivityOptions(options) {
         limit: readActivityString("limit"),
         compact: options.full === true || options.provenance === true
             ? false
-            : options.compact === false
-                ? false
-                : true,
+            : options.compact === true || options.raw === true
+                ? true
+                : undefined,
+        ...(options.raw === true ||
+            options.compact === true ||
+            options.full === true
+            ? { raw: true }
+            : {}),
         unbounded: optionTrue(options, "unbounded"),
         provenance: optionTrue(options, "provenance"),
         provenanceSummary: optionTrue(options, "provenanceSummary"),
@@ -817,6 +822,7 @@ export function normalizeActivityOptions(options) {
             ? options.provenanceFilter
             : undefined,
     };
+    return Object.fromEntries(Object.entries(normalized).filter(([, value]) => value !== undefined));
 }
 const ACTIVITY_STREAM_ENABLED_VALUES = new Set([
     "",
@@ -978,4 +984,4 @@ export const _testOnly = {
     collectMutationItemIds,
 };
 //# sourceMappingURL=registration-helpers.js.map
-//# debugId=5f92dd0d-4eb1-5a7b-8891-931dd15deb81
+//# debugId=daefefd1-3b0b-513d-8b8c-ab17f90b995a