@unbrained/pm-cli 2026.8.13 → 2026.8.15

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

@@ -1,31 +1,7 @@
 /** Generated partition 2 of the exhaustive error-code catalog. */
 
-!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]="b129c0ca-3d57-551c-945c-300547b74ff5")}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]="5d64a86d-6ba6-5bbe-a83a-9703690a851e")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_2 = [
-    {
-        code: "merge_conflict_markers_detected",
-        meaning: "Merge conflict markers detected condition.",
-        stability: "stable",
-        exit_code: 1,
-        class: "generic_failure",
-        recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["core/item/item-format.ts"],
-        emitting_commands: ["*"],
-        canonical_code: "merge_conflict_markers_detected",
-        aliases: ["history_merge_conflict_markers_detected"],
-    },
-    {
-        code: "merge_decisions_unreviewed",
-        meaning: "Merge decisions unreviewed condition.",
-        stability: "provisional",
-        exit_code: 1,
-        class: "generic_failure",
-        recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["core/diagnostics/remediation.ts"],
-        emitting_commands: ["*"],
-        canonical_code: "merge_decisions_unreviewed",
-        aliases: [],
-    },
     {
         code: "merge_git_config_unwritable",
         meaning: "Merge git config unwritable condition.",
@@ -363,6 +339,54 @@ export const PM_ERROR_CODE_CATALOG_PART_2 = [
         canonical_code: "project_runtime_stale_read",
         aliases: [],
     },
+    {
+        code: "provenance_value_domain_invalid",
+        meaning: "Provenance value domain invalid condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/diagnostics/remediation.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "provenance_value_domain_invalid",
+        aliases: [],
+    },
+    {
+        code: "read_output_cursor_command_mismatch",
+        meaning: "Read output cursor command mismatch condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/read-output/continuation.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "read_output_cursor_command_mismatch",
+        aliases: [],
+    },
+    {
+        code: "read_output_cursor_invalid",
+        meaning: "Read output cursor invalid condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/read-output/continuation.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "read_output_cursor_invalid",
+        aliases: [],
+    },
+    {
+        code: "read_output_cursor_stale",
+        meaning: "Read output cursor stale condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/read-output/continuation.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "read_output_cursor_stale",
+        aliases: [],
+    },
     {
         code: "redundant_edge",
         meaning: "Redundant edge condition.",
@@ -1605,4 +1629,4 @@ export const PM_ERROR_CODE_CATALOG_PART_2 = [
     },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-2.js.map
-//# debugId=b129c0ca-3d57-551c-945c-300547b74ff5
+//# debugId=5d64a86d-6ba6-5bbe-a83a-9703690a851e

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

@@ -6,6 +6,7 @@
 import type { GlobalOptions } from "../../core/shared/command-types.js";
 import { type AssuranceBundleMutationReceipt, type AssuranceDeclaration, type AssuranceGateVerdict, type AssuranceMutationReceipt } from "./assurance.js";
 import { type AssuranceDerivedProposal, type AssurancePreset, type AssurancePresetId } from "./assurance-presets.js";
+import { type CreateAssuranceWorkspaceContextOptions } from "./assurance-runtime.js";
 /** Assurance registry and evaluation verbs shared by every transport. */
 export declare const ASSURANCE_ACTIONS: readonly ["list", "show", "put", "remove", "run", "verdicts", "presets", "apply", "derive", "promote"];
 /** Assurance declaration kinds shared by every transport. */
@@ -49,6 +50,11 @@ export interface AssuranceActionInput {
     /** Explicit next assertion enforcement level. */
     enforcement?: string;
 }
+/** Embedding-host capabilities used only while evaluating assurance actions. */
+export interface AssuranceActionRuntimeOptions {
+    /** Workspace adapters and provider capabilities supplied by an SDK host. */
+    workspace?: Omit<CreateAssuranceWorkspaceContextOptions, "tree_id" | "trigger">;
+}
 /** Result union returned by transport-neutral assurance execution. */
 export type AssuranceActionResult = AssuranceDeclaration | AssuranceMutationReceipt | AssuranceGateVerdict | AssuranceBundleMutationReceipt | AssurancePreset | {
     items: AssuranceDerivedProposal[];
@@ -89,6 +95,6 @@ export type AssuranceActionResult = AssuranceDeclaration | AssuranceMutationRece
     };
 };
 /** Execute one assurance request through the public assurance SDK primitives. */
-export declare function runAssuranceAction(input: AssuranceActionInput, global?: Pick<GlobalOptions, "path">): Promise<AssuranceActionResult>;
+export declare function runAssuranceAction(input: AssuranceActionInput, global?: Pick<GlobalOptions, "path">, runtime?: AssuranceActionRuntimeOptions): 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>;

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

@@ -1,12 +1,12 @@
 
-!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]="36dfa230-06bd-5902-a0c9-94a7c34cda90")}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]="06d21369-1339-54b2-8d78-442f02e24cef")}catch(e){}}();
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { ASSURANCE_GATE_TRIGGERS, evaluateAssuranceGate, getAssuranceDeclaration, listAssuranceDeclarations, listAssuranceVerdicts, putAssuranceDeclaration, recordAssuranceVerdict, removeAssuranceDeclaration, } from "./assurance.js";
 import { ASSURANCE_PRESET_IDS, acceptAssuranceProposals, applyAssurancePreset, createAssurancePreset, deriveAssuranceProposals, promoteAssuranceAssertion, } from "./assurance-presets.js";
 import { MAX_ASSURANCE_VERDICT_LIMIT } from "./assurance-limits.js";
 import { normalizeAssuranceEvaluation, normalizeAssuranceMutation, } from "./assurance-mutation-error.js";
-import { createAssuranceWorkspaceContext } from "./assurance-runtime.js";
+import { createAssuranceWorkspaceContext, } from "./assurance-runtime.js";
 import { resolvePmRoot } from "../runtime-primitives.js";
 import { parseRuntimeInteger, readRuntimeString } from "../runtime-input.js";
 /** Assurance registry and evaluation verbs shared by every transport. */
@@ -173,7 +173,7 @@ async function runAdoptionAction(action, input, pmRoot) {
         message: input.message,
     }));
 }
-async function runGateAction(input, pmRoot) {
+async function runGateAction(input, pmRoot, runtime) {
     if (!input.id) {
         throw new PmCliError("assurance run requires a gate id", EXIT_CODE.USAGE);
     }
@@ -188,6 +188,7 @@ async function runGateAction(input, pmRoot) {
     const [document, workspaceContext] = await Promise.all([
         readDocument(pmRoot),
         createAssuranceWorkspaceContext(pmRoot, {
+            ...runtime.workspace,
             tree_id: input.tree,
             trigger,
         }),
@@ -205,7 +206,7 @@ async function runGateAction(input, pmRoot) {
     return verdict;
 }
 /** Execute one assurance request through the public assurance SDK primitives. */
-export async function runAssuranceAction(input, global = {}) {
+export async function runAssuranceAction(input, global = {}, runtime = {}) {
     const action = parseAction(input.action);
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
     if (action === "presets" ||
@@ -218,7 +219,7 @@ export async function runAssuranceAction(input, global = {}) {
         return runVerdictsAction(input, pmRoot);
     }
     if (action === "run") {
-        return runGateAction(input, pmRoot);
+        return runGateAction(input, pmRoot, runtime);
     }
     const kind = parseKind(input.kind);
     if (action === "list")
@@ -281,4 +282,4 @@ export function runAssuranceDispatch(args, options, global) {
     }, global);
 }
 //# sourceMappingURL=assurance-action.js.map
-//# debugId=36dfa230-06bd-5902-a0c9-94a7c34cda90
+//# debugId=06d21369-1339-54b2-8d78-442f02e24cef

package/dist/sdk/governance/assurance-mutation-error.d.ts

@@ -1,3 +1,29 @@
+/** Machine-readable location of a refused assurance evaluation. */
+export interface AssuranceEvaluationRefusalContext {
+    /** Gate being evaluated. */
+    gate_id?: string;
+    /** Assertion whose measurement failed. */
+    assertion_id?: string;
+    /** Measurement whose source failed. */
+    measurement_id?: string;
+    /** Measurement source discriminant. */
+    source_kind?: string;
+    /** Field selected from a graph, validate, or health result. */
+    field?: string;
+    /** Validate or health check selected by the source. */
+    check?: string;
+}
+/** Machine-readable location of a failed measurement source resolution. */
+export interface AssuranceSourceResolutionContext {
+    /** Measurement that owns the failed source, once evaluation identifies it. */
+    measurement_id?: string;
+    /** Measurement source discriminant. */
+    source_kind: string;
+    /** Field selected from the source result. */
+    field: string;
+    /** Optional validate or health check selector. */
+    check?: string;
+}
 /** Expected declaration-validation or mutation-policy refusal. */
 export declare class AssuranceMutationRefusalError extends TypeError {
     /** Create one typed refusal while retaining TypeError compatibility for SDK callers. */
@@ -5,8 +31,23 @@ export declare class AssuranceMutationRefusalError extends TypeError {
 }
 /** Expected gate-policy refusal caused by an incomplete or disallowed provider contract. */
 export declare class AssuranceEvaluationRefusalError extends TypeError {
+    /** Structured evaluation location retained across CLI, SDK, and MCP. */
+    readonly context: AssuranceEvaluationRefusalContext;
     /** Create one typed refusal while retaining TypeError compatibility for SDK callers. */
-    constructor(message: string);
+    constructor(message: string, context?: AssuranceEvaluationRefusalContext);
+}
+/** Expected failure to resolve one declared external measurement source. */
+export declare class AssuranceSourceResolutionError extends TypeError {
+    /** Measurement that owns the failed source, once evaluation identifies it. */
+    readonly measurement_id?: string;
+    /** Measurement source discriminant. */
+    readonly source_kind: string;
+    /** Field selected from the source result. */
+    readonly field: string;
+    /** Optional validate or health check selector. */
+    readonly check?: string;
+    /** Create one source-local refusal before gate context is attached. */
+    constructor(message: string, context: AssuranceSourceResolutionContext);
 }
 /** Normalize only expected assurance mutation refusals for CLI and MCP hosts. */
 export declare function normalizeAssuranceMutation<T>(operation: () => Promise<T>): Promise<T>;

package/dist/sdk/governance/assurance-mutation-error.js

@@ -5,7 +5,7 @@
  * faults before transport layers normalize them into stable usage errors.
  */
 
-!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]="93a32771-bf95-5df4-8019-b6be45a5051b")}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]="d2d5135a-8110-527e-8530-653b25b792a4")}catch(e){}}();
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 /** Expected declaration-validation or mutation-policy refusal. */
@@ -18,10 +18,33 @@ export class AssuranceMutationRefusalError extends TypeError {
 }
 /** Expected gate-policy refusal caused by an incomplete or disallowed provider contract. */
 export class AssuranceEvaluationRefusalError extends TypeError {
+    /** Structured evaluation location retained across CLI, SDK, and MCP. */
+    context;
     /** Create one typed refusal while retaining TypeError compatibility for SDK callers. */
-    constructor(message) {
+    constructor(message, context = {}) {
         super(message);
         this.name = "AssuranceEvaluationRefusalError";
+        this.context = context;
+    }
+}
+/** Expected failure to resolve one declared external measurement source. */
+export class AssuranceSourceResolutionError extends TypeError {
+    /** Measurement that owns the failed source, once evaluation identifies it. */
+    measurement_id;
+    /** Measurement source discriminant. */
+    source_kind;
+    /** Field selected from the source result. */
+    field;
+    /** Optional validate or health check selector. */
+    check;
+    /** Create one source-local refusal before gate context is attached. */
+    constructor(message, context) {
+        super(message);
+        this.name = "AssuranceSourceResolutionError";
+        this.measurement_id = context.measurement_id;
+        this.source_kind = context.source_kind;
+        this.field = context.field;
+        this.check = context.check;
     }
 }
 /** Normalize only expected assurance mutation refusals for CLI and MCP hosts. */
@@ -49,10 +72,11 @@ export async function normalizeAssuranceEvaluation(operation) {
             throw new PmCliError(error.message, EXIT_CODE.USAGE, {
                 code: "invalid_argument_value",
                 reason: "assurance_evaluation_refused",
+                ...error.context,
             });
         }
         throw error;
     }
 }
 //# sourceMappingURL=assurance-mutation-error.js.map
-//# debugId=93a32771-bf95-5df4-8019-b6be45a5051b
+//# debugId=d2d5135a-8110-527e-8530-653b25b792a4

package/dist/sdk/governance/assurance-runtime.js

@@ -5,12 +5,13 @@
  * and verdict semantics in the host-neutral assurance module.
  */
 
-!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]="7c99dfd8-2fa4-56c4-8191-229701eab251")}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]="f9c26dab-b2fb-5ca0-b575-682b4b0bb830")}catch(e){}}();
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { runGraph } from "../graph/run.js";
 import { runHealth } from "./health.js";
 import { runValidate } from "./validate.js";
+import { AssuranceSourceResolutionError } from "./assurance-mutation-error.js";
 import { getActiveExtensionRegistrations, resolvePortableWorkspaceContext, } from "../../core/extensions/index.js";
 import { resolveRegisteredAssuranceMeasurementProvider } from "../../core/extensions/runtime-registrations.js";
 import { stableStringify } from "../../core/shared/serialization.js";
@@ -86,13 +87,13 @@ async function runRegisteredProvider(provider, source, pmRoot, trigger) {
         clearTimeout(timeoutHandle);
     }
 }
-function valueAtPath(input, field) {
+function valueAtPath(input, field, sourceKind, check) {
     let current = input;
     for (const segment of field.split(".")) {
         if (typeof current !== "object" ||
             current === null ||
             Array.isArray(current)) {
-            throw new TypeError(`assurance field ${field} is not present`);
+            throw new AssuranceSourceResolutionError(`assurance field ${field} is not present`, { source_kind: sourceKind, field, ...(check ? { check } : {}) });
         }
         current = current[segment];
     }
@@ -102,17 +103,17 @@ function valueAtPath(input, field) {
         current.every((entry) => typeof entry === "string")) {
         return current;
     }
-    throw new TypeError(`assurance field ${field} must resolve to a finite number or string array`);
+    throw new AssuranceSourceResolutionError(`assurance field ${field} must resolve to a finite number or string array`, { source_kind: sourceKind, field, ...(check ? { check } : {}) });
 }
-function checkValue(result, checkName, field) {
+function checkValue(result, checkName, field, sourceKind) {
     const check = result.checks.find((entry) => entry.name === checkName);
     if (!check)
-        throw new TypeError(`assurance check ${checkName} is not present`);
+        throw new AssuranceSourceResolutionError(`assurance check ${checkName} is not present`, { source_kind: sourceKind, field, check: checkName });
     const value = field === "status" || field === "ok"
         ? check.ok
             ? 0
             : 1
-        : valueAtPath(check.details, field);
+        : valueAtPath(check.details, field, sourceKind, checkName);
     return { value, population_size: 1, cost: result.checks.length };
 }
 async function resolveTreeId(pmRoot, explicit) {
@@ -205,7 +206,7 @@ export async function createAssuranceWorkspaceContext(pmRoot, options = {}) {
                 }
                 const result = await pending;
                 return {
-                    value: valueAtPath(result, source.field),
+                    value: valueAtPath(result, source.field, source.kind),
                     population_size: items.length,
                     cost: items.length,
                 };
@@ -213,12 +214,12 @@ export async function createAssuranceWorkspaceContext(pmRoot, options = {}) {
             if (source.kind === "validate") {
                 validateRun ??= runValidate({ counts: true }, global);
                 const result = await validateRun;
-                return checkValue(result, source.check, source.field);
+                return checkValue(result, source.check, source.field, source.kind);
             }
             if (source.kind === "health") {
                 healthRun ??= runHealth(global, { checkOnly: true, full: true });
                 const result = await healthRun;
-                return checkValue(result, source.check, source.field);
+                return checkValue(result, source.check, source.field, source.kind);
             }
             const hostProvider = options.providers?.[source.provider];
             if (hostProvider)
@@ -232,4 +233,4 @@ export async function createAssuranceWorkspaceContext(pmRoot, options = {}) {
     };
 }
 //# sourceMappingURL=assurance-runtime.js.map
-//# debugId=7c99dfd8-2fa4-56c4-8191-229701eab251
+//# debugId=f9c26dab-b2fb-5ca0-b575-682b4b0bb830

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

@@ -2,6 +2,8 @@
 export declare const ASSURANCE_DOCUMENT_VERSION: 1;
 /** Supported lifecycle points that can evaluate a gate. */
 export declare const ASSURANCE_GATE_TRIGGERS: readonly ["pre-commit", "pre-push", "pre-merge", "ci", "pre-release", "post-release", "scheduled", "on-claim", "on-close"];
+/** Supported discriminants for built-in, delegated, and derived measurements. */
+export declare const ASSURANCE_MEASUREMENT_SOURCE_KINDS: readonly ["items", "dependency_kind", "graph", "validate", "health", "history", "links", "provider", "derived"];
 /** Gate lifecycle trigger. */
 export type AssuranceGateTrigger = (typeof ASSURANCE_GATE_TRIGGERS)[number];
 /** Assertion enforcement strength. */
@@ -401,6 +403,13 @@ export interface AssuranceGateVerdict {
     exit_code: 0 | 1;
     /** Per-assertion receipts. */
     assertions: AssuranceAssertionVerdict[];
+    /** Total assertions evaluated before any transport projection or compaction. */
+    assertions_total: number;
+    /** Stable selector for iterating assertion evidence across transports. */
+    row_contract: {
+        row_keys: ["assertions"];
+        jq_selector: ".assertions[]";
+    };
     /** Aggregate compute receipt. */
     cost: AssuranceMeasurementCost;
 }

package/dist/sdk/governance/assurance.js

@@ -7,7 +7,7 @@
  * one deterministic SDK path.
  */
 
-!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]="e491ddd9-60e7-51fd-b0c7-4f6e86ee56f9")}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]="2bf52d6d-7e4f-5ec5-86bd-3e817ef521bb")}catch(e){}}();
 import { createHash } from "node:crypto";
 import path from "node:path";
 import { EXIT_CODE } from "../../core/shared/constants.js";
@@ -15,7 +15,7 @@ import { PmCliError } from "../../core/shared/errors.js";
 import { appendWorkspaceAuditEvent, mutateWorkspaceJsonWithHistory, readFileIfExists, readHistoryEntries, readSettings, resolveAuthor, stableStringify, WORKSPACE_HISTORY_ID, getWorkspaceHistoryPath, } from "../runtime-primitives.js";
 import { resolveCanonicalRelationshipKind } from "../relationships.js";
 import { MAX_ASSURANCE_VERDICT_LIMIT } from "./assurance-limits.js";
-import { AssuranceEvaluationRefusalError, AssuranceMutationRefusalError, } from "./assurance-mutation-error.js";
+import { AssuranceEvaluationRefusalError, AssuranceMutationRefusalError, AssuranceSourceResolutionError, } from "./assurance-mutation-error.js";
 /** Current serialized assurance registry format. */
 export const ASSURANCE_DOCUMENT_VERSION = 1;
 /** Supported lifecycle points that can evaluate a gate. */
@@ -30,6 +30,18 @@ export const ASSURANCE_GATE_TRIGGERS = [
     "on-claim",
     "on-close",
 ];
+/** Supported discriminants for built-in, delegated, and derived measurements. */
+export const ASSURANCE_MEASUREMENT_SOURCE_KINDS = [
+    "items",
+    "dependency_kind",
+    "graph",
+    "validate",
+    "health",
+    "history",
+    "links",
+    "provider",
+    "derived",
+];
 const POLARITY_KEYS = [
     "ceiling",
     "floor",
@@ -161,7 +173,15 @@ export function validateMeasurementDefinition(definition) {
     if (definition.max_cost !== undefined) {
         requireFiniteNonNegative(definition.max_cost, "measurement.max_cost");
     }
-    const source = definition.source;
+    const candidateSource = definition.source;
+    if (Object.prototype.toString.call(candidateSource) !== "[object Object]") {
+        throw new AssuranceMutationRefusalError(`measurement.source.kind must be one of ${ASSURANCE_MEASUREMENT_SOURCE_KINDS.join(", ")}`);
+    }
+    const sourceKind = Reflect.get(candidateSource, "kind");
+    if (!ASSURANCE_MEASUREMENT_SOURCE_KINDS.includes(sourceKind)) {
+        throw new AssuranceMutationRefusalError(`measurement.source.kind must be one of ${ASSURANCE_MEASUREMENT_SOURCE_KINDS.join(", ")}`);
+    }
+    const source = candidateSource;
     if (source.kind === "items") {
         validateItemsMeasurementSource(source);
     }
@@ -240,14 +260,25 @@ function validateGateProviderPolicy(policy) {
 /** Validate and return one gate declaration. */
 export function validateGateDefinition(definition) {
     requireStableId(definition.id, "gate.id");
+    if (!Array.isArray(definition.assertion_ids)) {
+        throw new AssuranceMutationRefusalError("gate.assertion_ids is required and must be an array");
+    }
     if (definition.assertion_ids.length === 0) {
         throw new AssuranceMutationRefusalError("gate requires at least one assertion");
     }
     for (const id of definition.assertion_ids)
         requireStableId(id, "gate.assertion_id");
+    if (!Array.isArray(definition.triggers)) {
+        throw new AssuranceMutationRefusalError(`gate.triggers is required and must be an array of ${ASSURANCE_GATE_TRIGGERS.join(", ")}`);
+    }
     if (definition.triggers.length === 0) {
         throw new AssuranceMutationRefusalError("gate requires at least one trigger");
     }
+    for (const trigger of definition.triggers) {
+        if (!ASSURANCE_GATE_TRIGGERS.includes(trigger)) {
+            throw new AssuranceMutationRefusalError(`gate trigger must be one of ${ASSURANCE_GATE_TRIGGERS.join(", ")}`);
+        }
+    }
     if (definition.provider_policy) {
         validateGateProviderPolicy(definition.provider_policy);
     }
@@ -543,16 +574,10 @@ async function evaluateMeasurementInternal(definition, context, definitions, sta
         if (builtin !== null) {
             result = builtin;
         }
-        else if (definition.source.kind === "graph" ||
-            definition.source.kind === "validate" ||
-            definition.source.kind === "health" ||
-            definition.source.kind === "provider") {
+        else {
             result = await context.external(definition.source);
             providerCalls = 1;
         }
-        else {
-            throw new TypeError(`unsupported assurance source ${definition.source.kind}`);
-        }
     }
     const ownCost = {
         units: result.cost,
@@ -587,7 +612,21 @@ function evaluateMeasurementCached(definition, context, definitions, stack, stat
     const cached = state.cache.get(definition.id);
     if (cached)
         return cached;
-    const evaluation = evaluateMeasurementInternal(definition, context, definitions, stack, state);
+    const evaluation = evaluateMeasurementInternal(definition, context, definitions, stack, state).catch((error) => {
+        if (error instanceof AssuranceSourceResolutionError &&
+            error.measurement_id === undefined) {
+            const sourceContext = {
+                measurement_id: definition.id,
+                source_kind: error.source_kind,
+                field: error.field,
+                ...(error.check ? { check: error.check } : {}),
+            };
+            const sourceError = new AssuranceSourceResolutionError(error.message, sourceContext);
+            sourceError.cause = error;
+            throw sourceError;
+        }
+        throw error;
+    });
     state.cache.set(definition.id, evaluation);
     return evaluation;
 }
@@ -664,14 +703,36 @@ function enforceGateProviderPolicy(gate, document, context, trigger) {
         }
     }
 }
+async function evaluateGateMeasurement(gateId, assertionId, definition, context, definitions) {
+    try {
+        return await evaluateMeasurement(definition, context, definitions);
+    }
+    catch (error) {
+        if (error instanceof AssuranceSourceResolutionError) {
+            const checkLocation = error.check ? ` check ${error.check}` : "";
+            const measurementId = error.measurement_id ?? definition.id;
+            const refusal = new AssuranceEvaluationRefusalError(`assurance gate ${gateId} assertion ${assertionId} measurement ${measurementId} source ${error.source_kind}${checkLocation} field ${error.field} could not resolve: ${error.message}`, {
+                gate_id: gateId,
+                assertion_id: assertionId,
+                measurement_id: measurementId,
+                source_kind: error.source_kind,
+                field: error.field,
+                ...(error.check ? { check: error.check } : {}),
+            });
+            refusal.cause = error;
+            throw refusal;
+        }
+        throw error;
+    }
+}
 /** Evaluate a named gate into one presentation-independent verdict document. */
 export async function evaluateAssuranceGate(gateId, document, context, options) {
     validateAssuranceDocument(document);
     const gateDefinition = document.gates.find((entry) => entry.id === gateId);
     if (!gateDefinition)
-        throw new TypeError(`assurance gate ${gateId} not found`);
+        throw new AssuranceEvaluationRefusalError(`assurance gate ${gateId} not found`);
     if (!gateDefinition.triggers.includes(options.trigger)) {
-        throw new TypeError(`assurance gate ${gateId} does not declare trigger ${options.trigger}`);
+        throw new AssuranceEvaluationRefusalError(`assurance gate ${gateId} does not declare trigger ${options.trigger}`);
     }
     enforceGateProviderPolicy(gateDefinition, document, context, options.trigger);
     const assertions = await mapWithConcurrency(gateDefinition.assertion_ids, EVALUATION_CONCURRENCY, async (id) => {
@@ -688,7 +749,7 @@ export async function evaluateAssuranceGate(gateId, document, context, options)
         else if (assertionDefinition.scope.kind === "filter") {
             const scopeMeasurementId = assertionDefinition.scope.measurement_id;
             const scopeDefinition = document.measurements.find((entry) => entry.id === scopeMeasurementId);
-            const scope = await evaluateMeasurement(scopeDefinition, context, document.measurements);
+            const scope = await evaluateGateMeasurement(gateDefinition.id, assertionDefinition.id, scopeDefinition, context, document.measurements);
             const contributorIds = new Set(scope.contributors);
             scopedContext = {
                 ...context,
@@ -698,7 +759,7 @@ export async function evaluateAssuranceGate(gateId, document, context, options)
         const owner = context.items.find((item) => item.id === assertionDefinition.owner_item_id);
         const ownerTerminal = owner !== undefined &&
             new Set(context.terminal_statuses ?? ["closed", "canceled"]).has(owner.status);
-        return evaluateAssuranceAssertion(assertionDefinition, await evaluateMeasurement(measurementDefinition, scopedContext, document.measurements), { owner_terminal: ownerTerminal });
+        return evaluateAssuranceAssertion(assertionDefinition, await evaluateGateMeasurement(gateDefinition.id, assertionDefinition.id, measurementDefinition, scopedContext, document.measurements), { owner_terminal: ownerTerminal });
     });
     const blocking = assertions.some((entry) => entry.verdict === "fail" && entry.enforcement === "block");
     const warning = assertions.some((entry) => entry.verdict === "fail" && entry.enforcement === "warn");
@@ -711,6 +772,11 @@ export async function evaluateAssuranceGate(gateId, document, context, options)
         verdict: blocking ? "block" : warning ? "warn" : "pass",
         exit_code: blocking ? 1 : 0,
         assertions,
+        assertions_total: assertions.length,
+        row_contract: {
+            row_keys: ["assertions"],
+            jq_selector: ".assertions[]",
+        },
         cost: sumCosts(assertions.map((entry) => entry.cost), Math.max(0, ...assertions.map((entry) => entry.cost.duration_ms))),
     };
 }
@@ -940,4 +1006,4 @@ export async function listAssuranceVerdicts(pmRoot, options = {}) {
         .slice(0, limit);
 }
 //# sourceMappingURL=assurance.js.map
-//# debugId=e491ddd9-60e7-51fd-b0c7-4f6e86ee56f9
+//# debugId=2bf52d6d-7e4f-5ec5-86bd-3e817ef521bb

package/dist/sdk/governance/extension-host-version.d.ts

@@ -0,0 +1,25 @@
+import type { LoadedExtension } from "../../core/extensions/loader.js";
+/** One distinct resolvable pm-cli installation and its extension consumers. */
+export interface ExtensionHostVersionCopy {
+    /** Installed pm-cli version. */
+    version: string;
+    /** Privacy-safe workspace-relative package manifest location. */
+    path: string;
+    /** Dependency layout that exposed this copy. */
+    layout: "host" | "npm" | "pnpm" | "other";
+    /** Loaded extensions resolving this copy. */
+    consumers: string[];
+}
+/** Extension/host version census returned by the health SDK. */
+export interface ExtensionHostVersionCensus {
+    /** Version of the process-hosting pm-cli package. */
+    host_version: string | null;
+    /** Every distinct relevant copy resolved by the host or an extension. */
+    copies: ExtensionHostVersionCopy[];
+    /** Copies whose version differs from the process host. */
+    mismatches: ExtensionHostVersionCopy[];
+    /** Stable health warning tokens for mismatched copies. */
+    warnings: string[];
+}
+/** Scan the host plus the nearest pm-cli package resolvable by every loaded extension. */
+export declare function scanExtensionHostVersions(loadedExtensions: readonly LoadedExtension[], workspaceRoot: string, hostPackageRoot?: string): Promise<ExtensionHostVersionCensus>;