@unbrained/pm-cli 2026.8.9 → 2026.8.11

package/dist/sdk/extension.js

@@ -4,7 +4,7 @@
  * Implements the pm extension command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f4b47053-cc05-51f2-b5cb-cc6dba3365c2")}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]="8b0fbe09-2221-5b8e-8712-90a83df19306")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { activateExtensions, createSerialQueue, loadExtensions, nextExtensionReloadToken, } from "../core/extensions/index.js";
@@ -20,6 +20,7 @@ import { nowIso } from "../core/shared/time.js";
 import { resolveGlobalPmRoot, resolvePmRoot } from "../core/store/paths.js";
 import { readSettings, writeSettings } from "../core/store/settings.js";
 import { quoteCommandArg, renderPmCommand } from "./command-line.js";
+import { createUnknownSubcommandError } from "./agent/subcommand-recovery.js";
 import { ensureTypeFolderScaffold } from "./schema.js";
 // Cohesive helper groups now live in ./extension/* sibling modules. They are
 // imported for the command wiring that stays here and re-exported below so
@@ -321,21 +322,21 @@ const buildUnknownLifecycleActionError = (target, options) => {
         return new PmCliError(`One action flag is required. Use one of: ${LIFECYCLE_ACTION_FLAG_HINT}. Bare \`pm package\` and \`pm extension\` default to --explore.`, EXIT_CODE.USAGE);
     }
     const command = `pm ${noun} ${suggestion.flag}`;
-    return new PmCliError(`Unknown ${noun} lifecycle action "${target}". Did you mean "${suggestion.flag}"?`, EXIT_CODE.USAGE, {
-        code: "unknown_lifecycle_action",
-        required: `Use one of: ${LIFECYCLE_ACTION_FLAG_HINT}.`,
-        examples: [command, `pm ${noun} --help`],
-        recovery: {
-            attempted_command: `pm ${noun} ${target}`,
-            suggested_retry: command,
-            fallback_candidates: [
-                {
-                    source: "lifecycle_action",
-                    command,
-                    reason: `nearest lifecycle action for "${target}"`,
-                },
-            ],
-        },
+    return createUnknownSubcommandError({
+        command_path: noun,
+        display_name: `${noun} lifecycle`,
+        token_kind: "action",
+        token: target,
+        allowed: Object.keys(IMPLICIT_EXTENSION_ACTIONS),
+        retry_command: command,
+        message_suffix: `. Did you mean "${suggestion.flag}"?`,
+        fallback_candidates: [
+            {
+                source: "lifecycle_action",
+                command,
+                reason: `nearest lifecycle action for "${target}"`,
+            },
+        ],
     });
 };
 // Maps each boolean action flag to the lifecycle action it selects. `scaffold`
@@ -2190,4 +2191,4 @@ export const _testOnly = {
     withExtensionInstallLock,
 };
 //# sourceMappingURL=extension.js.map
-//# debugId=f4b47053-cc05-51f2-b5cb-cc6dba3365c2
+//# debugId=8b0fbe09-2221-5b8e-8712-90a83df19306

package/dist/sdk/files.d.ts

@@ -1,6 +1,7 @@
 import type { GlobalOptions } from "../core/shared/command-types.js";
 import type { ItemDocument, LinkedFile, LinkScope } from "../types/index.js";
 import { type LinkedPathValidation } from "./linked-artifacts.js";
+import { type SourceLineRange, type SourceTraceabilityExplanation, type SourceTraceabilityReceipt } from "./traceability/source-traceability.js";
 /** Documents the files command options payload exchanged by command, SDK, and package integrations. */
 export interface FilesCommandOptions {
     /** Value that configures or reports add for this contract. */
@@ -112,6 +113,12 @@ export interface FilesLookupOptions {
     noTruncate?: boolean;
     /** Fail when any authoritative item cannot be read. */
     strictRead?: boolean;
+    /** Include rationale, governing-decision paths, and ambiguity receipts. */
+    explain?: boolean;
+    /** Optional inclusive line range; implies explain and requires one path. */
+    lineRange?: SourceLineRange;
+    /** Maximum relationship depth searched for a governing decision. */
+    decisionDepth?: number;
 }
 /** Token-efficient item identity returned by reverse linked-file lookup. */
 export interface FilesLookupItem {
@@ -134,6 +141,8 @@ export interface FilesLookupMatch {
     item: FilesLookupItem;
     /** Matching linked-file evidence. */
     files: LinkedFile[];
+    /** Optional bounded rationale and line-attribution explanation. */
+    traceability?: SourceTraceabilityExplanation;
 }
 /** Reverse linked-file lookup result with bounded output and read provenance. */
 export interface FilesLookupResult {
@@ -160,6 +169,8 @@ export interface FilesLookupResult {
     warnings: string[];
     /** Ordered reverse-traceability matches. */
     matches: FilesLookupMatch[];
+    /** Aggregate receipt for an explained source query. */
+    traceability_receipt?: SourceTraceabilityReceipt;
 }
 interface TextReference {
     field: string;

package/dist/sdk/files.js

@@ -4,7 +4,7 @@
  * Implements the pm files command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5e45d0f1-a1a7-50ea-a9a3-ec6283d3471d")}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]="515cd35c-8e0e-51d4-8ad9-1cea5be8a572")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathExists } from "../core/fs/fs-utils.js";
@@ -20,6 +20,7 @@ import { readSettings } from "../core/store/settings.js";
 import { resolveAuthor } from "../core/shared/author.js";
 import { isPathWithinDirectory } from "../core/fs/path-utils.js";
 import { dedupeLinkedArtifacts, normalizeLinkedPath, renameArtifactsResultKey, runLinkedArtifacts, sortLinkedArtifacts, } from "./linked-artifacts.js";
+import { explainSourceTraceability, } from "./traceability/source-traceability.js";
 /** Bounds fuzzy relative-path scanning while preserving full absolute-path discovery. */
 const RELATIVE_REFERENCE_SCAN_MAX_CHARS = 32_768;
 function normalizeCandidatePathForOutput(value) {
@@ -251,8 +252,51 @@ function projectFilesLookupItem(item) {
         updated_at: item.updated_at,
     };
 }
+function compareFilesLookupCandidates(left, right) {
+    const byPriority = left.item.priority - right.item.priority;
+    if (byPriority !== 0)
+        return byPriority;
+    const byUpdated = right.item.updated_at.localeCompare(left.item.updated_at);
+    return byUpdated === 0
+        ? left.item.id.localeCompare(right.item.id)
+        : byUpdated;
+}
+function matchingFilesLookupCandidates(params) {
+    return params.metadata
+        .map((item) => ({
+        item,
+        files: (item.files ?? [])
+            .filter((file) => params.paths.includes(normalizeLinkedPath(file.path)) &&
+            (params.scope === undefined || file.scope === params.scope))
+            .sort((left, right) => {
+            const byPath = left.path.localeCompare(right.path);
+            return byPath === 0 ? left.scope.localeCompare(right.scope) : byPath;
+        }),
+    }))
+        .filter((match) => match.files.length > 0)
+        .sort(compareFilesLookupCandidates);
+}
+async function resolveFilesLookupTraceability(params) {
+    if (!params.explain)
+        return undefined;
+    return explainSourceTraceability({
+        workspaceRoot: params.workspaceRoot,
+        paths: params.paths,
+        candidates: params.matching,
+        corpus: params.metadata,
+        ...(params.lineRange ? { lineRange: params.lineRange } : {}),
+        ...(params.decisionDepth === undefined
+            ? {}
+            : { decisionDepth: params.decisionDepth }),
+    });
+}
 async function queryFilesLookupIndex(params) {
-    if ([params.strictRead, params.noTruncate, hasActiveOnReadHooks()].includes(true)) {
+    if ([
+        params.strictRead,
+        params.noTruncate,
+        params.explain,
+        hasActiveOnReadHooks(),
+    ].includes(true)) {
         return null;
     }
     const indexState = await readItemMetadataDerivedIndexState(params.pmRoot, [
@@ -272,32 +316,34 @@ async function queryFilesLookupIndex(params) {
 async function queryFilesLookupSource(params) {
     const warnings = [];
     const metadata = await listAllItemMetadata(params.pmRoot, params.settings.item_format, params.typeToFolder, warnings, params.settings.schema);
-    const matching = metadata
-        .map((item) => ({
-        item,
-        files: (item.files ?? [])
-            .filter((file) => params.paths.includes(normalizeLinkedPath(file.path)) &&
-            (params.scope === undefined || file.scope === params.scope))
-            .sort((left, right) => {
-            const byPath = left.path.localeCompare(right.path);
-            return byPath === 0 ? left.scope.localeCompare(right.scope) : byPath;
-        }),
-    }))
-        .filter((match) => match.files.length > 0)
-        .sort((left, right) => {
-        const byPriority = left.item.priority - right.item.priority;
-        if (byPriority !== 0)
-            return byPriority;
-        const byUpdated = right.item.updated_at.localeCompare(left.item.updated_at);
-        return byUpdated === 0
-            ? left.item.id.localeCompare(right.item.id)
-            : byUpdated;
+    const matching = matchingFilesLookupCandidates({
+        metadata,
+        paths: params.paths,
+        scope: params.scope,
     });
     const readWarnings = warnings.filter((warning) => /^item_list_(?:item|directory)_read_failed:/u.test(warning));
     if (params.strictRead && readWarnings.length > 0) {
         throw new PmCliError(`Files lookup could not read every item: ${readWarnings.join("; ")}`, EXIT_CODE.GENERIC_FAILURE);
     }
-    const page = matching.slice(params.offset, params.limit === undefined ? undefined : params.offset + params.limit);
+    const traceability = await resolveFilesLookupTraceability({
+        explain: params.explain,
+        workspaceRoot: params.workspaceRoot,
+        paths: params.paths,
+        matching,
+        metadata,
+        lineRange: params.lineRange,
+        decisionDepth: params.decisionDepth,
+    });
+    const ranked = traceability
+        ? [...matching].sort((left, right) => {
+            const byScore = traceability.explanations.get(right.item.id).score -
+                traceability.explanations.get(left.item.id).score;
+            if (byScore !== 0)
+                return byScore;
+            return compareFilesLookupCandidates(left, right);
+        })
+        : matching;
+    const page = ranked.slice(params.offset, params.limit === undefined ? undefined : params.offset + params.limit);
     return {
         paths: params.paths,
         total: matching.length,
@@ -314,7 +360,11 @@ async function queryFilesLookupSource(params) {
         matches: page.map((match) => ({
             item: projectFilesLookupItem(match.item),
             files: match.files,
+            ...(traceability
+                ? { traceability: traceability.explanations.get(match.item.id) }
+                : {}),
         })),
+        ...(traceability ? { traceability_receipt: traceability.receipt } : {}),
     };
 }
 /** Resolve the pm items that reference one or more source paths. */
@@ -325,6 +375,9 @@ export async function runFilesLookup(options, global) {
         throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
     }
     const paths = await normalizeFilesLookupPaths(options.paths, workspaceRoot);
+    if (options.lineRange && paths.length !== 1) {
+        throw new PmCliError("Files lookup line attribution requires exactly one source path.", EXIT_CODE.USAGE);
+    }
     const settings = await readSettings(pmRoot);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const { offset, limit } = resolveFilesLookupWindow(options);
@@ -337,6 +390,7 @@ export async function runFilesLookup(options, global) {
         offset,
         strictRead: options.strictRead === true,
         noTruncate: options.noTruncate === true,
+        explain: options.explain === true || options.lineRange !== undefined,
     });
     if (indexed) {
         return {
@@ -364,6 +418,10 @@ export async function runFilesLookup(options, global) {
         limit,
         offset,
         strictRead: options.strictRead === true,
+        workspaceRoot,
+        explain: options.explain === true || options.lineRange !== undefined,
+        lineRange: options.lineRange,
+        decisionDepth: options.decisionDepth,
     });
 }
 /** Implements run files discover for the public runtime surface of this module. */
@@ -479,4 +537,4 @@ export async function runFilesDiscover(id, options, global) {
     };
 }
 //# sourceMappingURL=files.js.map
-//# debugId=5e45d0f1-a1a7-50ea-a9a3-ec6283d3471d
+//# debugId=515cd35c-8e0e-51d4-8ad9-1cea5be8a572

package/dist/sdk/generated-error-code-catalog.js

@@ -4,10 +4,34 @@
  * Generated by scripts/generate-error-code-catalog.mjs. Do not edit manually.
  */
 
-!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]="bcb7a0a9-268f-5cf8-aefc-766b67e92168")}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]="07d93565-d5ef-5c3d-ae8a-214973e6ec20")}catch(e){}}();
 import { definePmErrorCodeCatalog } from "./error-code-catalog.js";
 /** Exhaustive catalog generated from literal error guidance declarations. */
 export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
+    {
+        code: "acceptance_criteria_mutation_conflict",
+        meaning: "Acceptance criteria mutation conflict condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/lifecycle/update.ts"],
+        emitting_commands: ["update", "update-many"],
+        canonical_code: "acceptance_criteria_mutation_conflict",
+        aliases: [],
+    },
+    {
+        code: "acceptance_criteria_remove_unmatched",
+        meaning: "Acceptance criteria remove unmatched condition.",
+        stability: "provisional",
+        exit_code: 3,
+        class: "not_found",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/lifecycle/update-many.ts", "sdk/lifecycle/update.ts"],
+        emitting_commands: ["update", "update-many"],
+        canonical_code: "acceptance_criteria_remove_unmatched",
+        aliases: [],
+    },
     {
         code: "acceptance_criteria_semicolon_forbidden",
         meaning: "Acceptance criteria semicolon forbidden condition.",
@@ -92,6 +116,18 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         canonical_code: "append_empty_body",
         aliases: [],
     },
+    {
+        code: "assurance_registry_invalid",
+        meaning: "Assurance registry invalid condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/governance/assurance.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "assurance_registry_invalid",
+        aliases: [],
+    },
     {
         code: "body_file_conflicts_with_body",
         meaning: "Body file conflicts with body condition.",
@@ -308,6 +344,42 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         canonical_code: "conflicting_lifecycle_owner",
         aliases: [],
     },
+    {
+        code: "context_signal_store_invalid",
+        meaning: "Context signal store invalid condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/context-signal-store.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "context_signal_store_invalid",
+        aliases: [],
+    },
+    {
+        code: "context_signal_store_stale",
+        meaning: "Context signal store stale condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/context-signal-store.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "context_signal_store_stale",
+        aliases: [],
+    },
+    {
+        code: "context_signal_store_write_failed",
+        meaning: "Context signal store write failed condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/context-signal-store.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "context_signal_store_write_failed",
+        aliases: [],
+    },
     {
         code: "context_takes_no_item_argument",
         meaning: "Context takes no item argument condition.",
@@ -356,6 +428,18 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         canonical_code: "dependency_edge_not_allowed",
         aliases: [],
     },
+    {
+        code: "dependency_target_not_found",
+        meaning: "Dependency target not found condition.",
+        stability: "provisional",
+        exit_code: 3,
+        class: "not_found",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/dependency-flag-validation.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "dependency_target_not_found",
+        aliases: [],
+    },
     {
         code: "duplicate_command",
         meaning: "Duplicate command condition.",
@@ -2174,13 +2258,16 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         code: "tracker_not_initialized",
         meaning: "Tracker not initialized condition.",
         stability: "stable",
-        exit_code: 1,
-        class: "generic_failure",
+        exit_code: 3,
+        class: "not_found",
         recovery: "Inspect the structured error guidance and retry the suggested command.",
         sources: ["cli/error-guidance.ts", "core/telemetry/observability.ts"],
         emitting_commands: ["*"],
         canonical_code: "tracker_not_initialized",
         aliases: [],
+        owned_states: [
+            { state: "selected_tracker_root_is_a_regular_file", probe_id: "tracker-root-regular-file", entrypoints: ["list"], expected_exit_class: "not_found" },
+        ],
     },
     {
         code: "tracker_root_missing",
@@ -2313,9 +2400,9 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         exit_code: 2,
         class: "usage",
         recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["sdk/extension.ts"],
+        sources: ["sdk/agent/subcommand-recovery.ts"],
         emitting_commands: ["*"],
-        canonical_code: "unknown_lifecycle_action",
+        canonical_code: "unknown_subcommand",
         aliases: [],
     },
     {
@@ -2329,6 +2416,9 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         emitting_commands: ["*"],
         canonical_code: "unknown_option",
         aliases: [],
+        owned_states: [
+            { state: "declared_option_is_rejected_on_the_selected_command_path", probe_id: "cross-command-unknown-option", entrypoints: ["deps"], expected_exit_class: "usage" },
+        ],
     },
     {
         code: "unknown_plan_template",
@@ -2373,15 +2463,16 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         exit_code: 2,
         class: "usage",
         recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: [
-            "cli/register-mutation.ts",
-            "cli/register-operations.ts",
-            "sdk/runtime-extended-actions.ts",
-            "sdk/telemetry.ts",
-        ],
+        sources: ["cli/error-guidance.ts", "sdk/agent/subcommand-recovery.ts"],
         emitting_commands: ["*"],
         canonical_code: "unknown_subcommand",
-        aliases: [],
+        aliases: ["unknown_lifecycle_action"],
+        owned_states: [
+            { state: "config_action_token_is_not_declared", probe_id: "config-unknown-action", entrypoints: ["config"], expected_exit_class: "usage" },
+            { state: "graph_command_token_is_not_declared", probe_id: "graph-unknown-subcommand", entrypoints: ["graph"], expected_exit_class: "usage" },
+            { state: "nested_command_token_is_not_declared_by_its_family", probe_id: "schema-unknown-subcommand", entrypoints: ["schema"], expected_exit_class: "usage" },
+            { state: "package_lifecycle_token_is_not_declared", probe_id: "package-unknown-action", entrypoints: ["package"], expected_exit_class: "usage" },
+        ],
     },
     {
         code: "unsupported_update_option",
@@ -3057,4 +3148,4 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
     },
 ]);
 //# sourceMappingURL=generated-error-code-catalog.js.map
-//# debugId=bcb7a0a9-268f-5cf8-aefc-766b67e92168
+//# debugId=07d93565-d5ef-5c3d-ae8a-214973e6ec20

package/dist/sdk/governance/assurance-action-contracts.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @module sdk/governance/assurance-action-contracts
+ *
+ * Exposes assurance action transport types without coupling callers to the
+ * governance implementation module.
+ */
+export type { AssuranceActionInput, AssuranceActionResult, } from "./assurance-action.js";

package/dist/sdk/governance/assurance-action-contracts.js

@@ -0,0 +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]="443beddb-37c9-5244-a157-e07624e4a6d2")}catch(e){}}();
+export {};
+//# sourceMappingURL=assurance-action-contracts.js.map
+//# debugId=443beddb-37c9-5244-a157-e07624e4a6d2

package/dist/sdk/governance/assurance-action.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @module sdk/assurance-action
+ *
+ * Normalizes the assurance action vocabulary once for CLI, SDK, and MCP hosts.
+ */
+import type { GlobalOptions } from "../../core/shared/command-types.js";
+import { type AssuranceDeclaration, type AssuranceGateVerdict, type AssuranceMutationReceipt } from "./assurance.js";
+/** Assurance registry and evaluation verbs shared by every transport. */
+export declare const ASSURANCE_ACTIONS: readonly ["list", "show", "put", "remove", "run", "verdicts"];
+/** Assurance declaration kinds shared by every transport. */
+export declare const ASSURANCE_DECLARATION_KINDS: readonly ["measurement", "assertion", "gate"];
+/** Assurance action verb. */
+export type AssuranceAction = (typeof ASSURANCE_ACTIONS)[number];
+/** Transport-neutral assurance action request. */
+export interface AssuranceActionInput {
+    /** CRUD, evaluation, or verdict-history action. */
+    action: string;
+    /** Declaration kind for registry actions. */
+    kind?: string;
+    /** Declaration id, gate id, or verdict gate filter. */
+    id?: string;
+    /** JSON object or serialized JSON declaration for put. */
+    definition?: unknown;
+    /** Lifecycle trigger for gate evaluation. */
+    trigger?: string;
+    /** Explicit commit, tree, or snapshot identity. */
+    tree?: string;
+    /** Verdict-history gate filter when id is used by another host field. */
+    gate?: string;
+    /** Maximum newest durable verdicts returned. */
+    limit?: number | string;
+    /** Evaluate without appending an immutable verdict. */
+    dry_run?: boolean;
+    /** Retain the complete mutation receipt; assurance receipts are complete by default. */
+    fullChangedFields?: boolean;
+    /** Project declaration mutations to their stable id. */
+    idOnly?: boolean;
+    /** Explicit author override. */
+    author?: string;
+    /** Audited mutation rationale. */
+    message?: string;
+}
+/** Result union returned by transport-neutral assurance execution. */
+export type AssuranceActionResult = AssuranceDeclaration | AssuranceMutationReceipt | AssuranceGateVerdict | {
+    id: string;
+} | {
+    /** Registry declarations. */
+    items: AssuranceDeclaration[];
+    /** Number of declarations. */
+    count: number;
+    /** Stable row-selection contract. */
+    row_contract: {
+        row_keys: ["items"];
+        jq_selector: ".items[]";
+    };
+} | {
+    /** Durable gate verdicts. */
+    items: AssuranceGateVerdict[];
+    /** Number of verdicts. */
+    count: number;
+    /** Stable row-selection contract. */
+    row_contract: {
+        row_keys: ["items"];
+        jq_selector: ".items[]";
+    };
+};
+/** Execute one assurance request through the public assurance SDK primitives. */
+export declare function runAssuranceAction(input: AssuranceActionInput, global?: Pick<GlobalOptions, "path">): Promise<AssuranceActionResult>;
+/** Normalize a generic SDK or MCP argument envelope into one assurance request. */
+export declare function runAssuranceDispatch(args: Record<string, unknown>, options: Record<string, unknown>, global: GlobalOptions): Promise<AssuranceActionResult>;