@unbrained/pm-cli 2026.8.11 → 2026.8.13

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

@@ -5,26 +5,101 @@
  * 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]="0dbe4ce9-9714-588d-bc85-d2591b7a5400")}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]="7c99dfd8-2fa4-56c4-8191-229701eab251")}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 { getHistoryPath, listAllItemMetadataLight, readHistoryEntries, readSettings, resolveItemTypeRegistry, resolveRuntimeStatusRegistry, } from "../runtime-primitives.js";
+import { getActiveExtensionRegistrations, resolvePortableWorkspaceContext, } from "../../core/extensions/index.js";
+import { resolveRegisteredAssuranceMeasurementProvider } from "../../core/extensions/runtime-registrations.js";
+import { stableStringify } from "../../core/shared/serialization.js";
+import { getHistoryPath, listAllItemMetadata, readHistoryEntries, readSettings, resolveItemTypeRegistry, resolveRuntimeStatusRegistry, } from "../runtime-primitives.js";
 const execFileAsync = promisify(execFile);
 const HISTORY_READ_CONCURRENCY = 16;
+const DEFAULT_PROVIDER_TIMEOUT_MS = 30_000;
+function assertProviderResult(provider, key, result) {
+    const keyDefinition = provider.keys[key];
+    const valueMatches = keyDefinition.value_type === "number"
+        ? typeof result.value === "number" && Number.isFinite(result.value)
+        : Array.isArray(result.value) &&
+            result.value.every((entry) => typeof entry === "string");
+    if (!valueMatches) {
+        throw new TypeError(`assurance provider ${provider.id} key ${key} returned the wrong value type`);
+    }
+    if (!Number.isInteger(result.population_size) ||
+        result.population_size < 0 ||
+        !Number.isFinite(result.cost) ||
+        result.cost < 0) {
+        throw new TypeError(`assurance provider ${provider.id} returned an invalid population or cost`);
+    }
+    return result;
+}
+function validateProviderParameters(provider, source) {
+    const keyDefinition = provider.keys[source.key];
+    if (!keyDefinition) {
+        throw new TypeError(`assurance provider ${provider.id} does not declare key ${source.key}`);
+    }
+    const parameters = source.parameters ?? {};
+    const schema = keyDefinition.parameters ?? {};
+    for (const required of Object.entries(schema)
+        .filter(([, definition]) => definition.required === true)
+        .map(([name]) => name)) {
+        if (!Object.hasOwn(parameters, required)) {
+            throw new TypeError(`assurance provider ${provider.id} key ${source.key} requires parameter ${required}`);
+        }
+    }
+    for (const [name, value] of Object.entries(parameters)) {
+        const definition = schema[name];
+        if (!definition) {
+            throw new TypeError(`assurance provider ${provider.id} key ${source.key} does not declare parameter ${name}`);
+        }
+        if (value === null || typeof value !== definition.type) {
+            throw new TypeError(`assurance provider ${provider.id} parameter ${name} must be ${definition.type}`);
+        }
+    }
+    return { ...parameters };
+}
+async function runRegisteredProvider(provider, source, pmRoot, trigger) {
+    const parameters = validateProviderParameters(provider, source);
+    const providerPromise = Promise.resolve().then(() => provider.resolve({
+        provider: provider.id,
+        key: source.key,
+        parameters,
+        trigger,
+        pm_root: pmRoot,
+        ...resolvePortableWorkspaceContext(pmRoot),
+    }));
+    providerPromise.catch(() => { });
+    let timeoutHandle;
+    try {
+        const result = await Promise.race([
+            providerPromise,
+            new Promise((_, reject) => {
+                timeoutHandle = setTimeout(() => reject(new TypeError(`assurance provider ${provider.id} timed out`)), provider.timeout_ms ?? DEFAULT_PROVIDER_TIMEOUT_MS);
+                timeoutHandle.unref?.();
+            }),
+        ]);
+        return assertProviderResult(provider, source.key, result);
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+    }
+}
 function valueAtPath(input, field) {
     let current = input;
     for (const segment of field.split(".")) {
-        if (typeof current !== "object" || current === null || Array.isArray(current)) {
+        if (typeof current !== "object" ||
+            current === null ||
+            Array.isArray(current)) {
             throw new TypeError(`assurance field ${field} is not present`);
         }
         current = current[segment];
     }
     if (typeof current === "number" && Number.isFinite(current))
         return current;
-    if (Array.isArray(current) && current.every((entry) => typeof entry === "string")) {
+    if (Array.isArray(current) &&
+        current.every((entry) => typeof entry === "string")) {
         return current;
     }
     throw new TypeError(`assurance field ${field} must resolve to a finite number or string array`);
@@ -33,8 +108,8 @@ function checkValue(result, checkName, field) {
     const check = result.checks.find((entry) => entry.name === checkName);
     if (!check)
         throw new TypeError(`assurance check ${checkName} is not present`);
-    const value = field === "status"
-        ? check.status === "ok"
+    const value = field === "status" || field === "ok"
+        ? check.ok
             ? 0
             : 1
         : valueAtPath(check.details, field);
@@ -85,7 +160,7 @@ export async function createAssuranceWorkspaceContext(pmRoot, options = {}) {
     const settings = await readSettings(pmRoot);
     const typeRegistry = resolveItemTypeRegistry(settings);
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
-    const metadata = await listAllItemMetadataLight(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema);
+    const metadata = await listAllItemMetadata(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema);
     const items = metadata.map((item) => ({
         ...item,
         id: item.id,
@@ -93,6 +168,17 @@ export async function createAssuranceWorkspaceContext(pmRoot, options = {}) {
         type: item.type,
     }));
     const global = { path: pmRoot };
+    const activeRegistrations = getActiveExtensionRegistrations();
+    const registeredProviderCapabilities = Object.fromEntries((activeRegistrations?.assurance_providers ?? []).map((registration) => [
+        registration.definition.id,
+        {
+            cost_class: registration.runtime_definition.cost_class,
+            network: registration.runtime_definition.network,
+        },
+    ]));
+    const graphRuns = new Map();
+    let validateRun;
+    let healthRun;
     return {
         tree_id: options.resolve_tree === false
             ? (options.tree_id ?? "working-copy")
@@ -102,9 +188,22 @@ export async function createAssuranceWorkspaceContext(pmRoot, options = {}) {
             ? []
             : await readWorkspaceHistory(pmRoot, items),
         terminal_statuses: [...statusRegistry.terminal_statuses],
+        provider_capabilities: {
+            ...registeredProviderCapabilities,
+            ...options.provider_capabilities,
+        },
         external: async (source) => {
             if (source.kind === "graph") {
-                const result = await runGraph(source.operation, undefined, undefined, { ...source.parameters, full: true }, global);
+                const key = stableStringify({
+                    operation: source.operation,
+                    parameters: source.parameters ?? {},
+                });
+                let pending = graphRuns.get(key);
+                if (pending === undefined) {
+                    pending = runGraph(source.operation, undefined, undefined, { ...source.parameters, full: true }, global);
+                    graphRuns.set(key, pending);
+                }
+                const result = await pending;
                 return {
                     value: valueAtPath(result, source.field),
                     population_size: items.length,
@@ -112,20 +211,25 @@ export async function createAssuranceWorkspaceContext(pmRoot, options = {}) {
                 };
             }
             if (source.kind === "validate") {
-                const result = await runValidate({ counts: true }, global);
+                validateRun ??= runValidate({ counts: true }, global);
+                const result = await validateRun;
                 return checkValue(result, source.check, source.field);
             }
             if (source.kind === "health") {
-                const result = await runHealth(global, { checkOnly: true, full: true });
+                healthRun ??= runHealth(global, { checkOnly: true, full: true });
+                const result = await healthRun;
                 return checkValue(result, source.check, source.field);
             }
-            const provider = options.providers?.[source.provider];
-            if (!provider) {
+            const hostProvider = options.providers?.[source.provider];
+            if (hostProvider)
+                return hostProvider(source);
+            const registeredProvider = resolveRegisteredAssuranceMeasurementProvider(activeRegistrations, source.provider);
+            if (!registeredProvider) {
                 throw new TypeError(`assurance provider ${source.provider} is not registered`);
             }
-            return provider(source);
+            return runRegisteredProvider(registeredProvider.runtime_definition, source, pmRoot, options.trigger ?? "sdk");
         },
     };
 }
 //# sourceMappingURL=assurance-runtime.js.map
-//# debugId=0dbe4ce9-9714-588d-bc85-d2591b7a5400
+//# debugId=7c99dfd8-2fa4-56c4-8191-229701eab251

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

@@ -6,6 +6,8 @@ export declare const ASSURANCE_GATE_TRIGGERS: readonly ["pre-commit", "pre-push"
 export type AssuranceGateTrigger = (typeof ASSURANCE_GATE_TRIGGERS)[number];
 /** Assertion enforcement strength. */
 export type AssuranceEnforcement = "block" | "warn" | "observe";
+/** Provider execution classes ordered from cheapest to most expensive. */
+export type AssuranceProviderCostClass = "low" | "medium" | "high";
 /** Assertion lifetime after its owning work item becomes terminal. */
 export type AssuranceLifetime = "hold" | "retire";
 /** Numeric or labelled-set value produced by a measurement. */
@@ -32,11 +34,11 @@ export interface AssuranceItemRecord {
     /** Typed relationships. */
     dependencies?: AssuranceDependencyRecord[];
     /** Linked files. */
-    files?: Array<Record<string, unknown>>;
+    files?: object[];
     /** Linked tests. */
-    tests?: Array<Record<string, unknown>>;
+    tests?: object[];
     /** Linked docs. */
-    docs?: Array<Record<string, unknown>>;
+    docs?: object[];
     /** Extension-owned metadata remains filterable. */
     [key: string]: unknown;
 }
@@ -67,6 +69,8 @@ export interface AssuranceItemsSource {
     field?: string;
     /** Required exact value for field. */
     equals?: string | number | boolean | null;
+    /** Presence predicate for the selected field. */
+    state?: "present" | "missing";
 }
 /** Typed relationship-count source. */
 export interface AssuranceDependencyKindSource {
@@ -244,6 +248,18 @@ export interface AssuranceGateDefinition {
     triggers: AssuranceGateTrigger[];
     /** Optional description. */
     description?: string;
+    /** Explicit provider allow-list and trigger-specific execution policy. */
+    provider_policy?: {
+        /** Provider ids this gate may invoke. An empty set refuses every provider. */
+        allowed_providers: string[];
+        /** Trigger rules; an omitted rule refuses provider execution for that trigger. */
+        triggers: Partial<Record<AssuranceGateTrigger, {
+            /** Highest provider cost class allowed at this trigger. */
+            max_cost_class: AssuranceProviderCostClass;
+            /** Whether network-declaring providers may run. */
+            allow_network: boolean;
+        }>>;
+    };
 }
 /** Complete persisted assurance registry. */
 export interface AssuranceDocument {
@@ -256,6 +272,24 @@ export interface AssuranceDocument {
     /** Gate declarations. */
     gates: AssuranceGateDefinition[];
 }
+/** Atomic set of ordinary declarations used by presets and accepted proposals. */
+export interface AssuranceDeclarationBundle {
+    /** Measurement declarations to create without overwriting divergent ids. */
+    measurements: AssuranceMeasurementDefinition[];
+    /** Assertion declarations to create without overwriting divergent ids. */
+    assertions: AssuranceAssertionDefinition[];
+    /** Gate declarations to create without overwriting divergent ids. */
+    gates: AssuranceGateDefinition[];
+}
+/** Audited receipt for one atomic assurance bundle application. */
+export interface AssuranceBundleMutationReceipt {
+    /** Whether persistence changed. */
+    changed: boolean;
+    /** Stable ids created by the bundle. */
+    created_ids: string[];
+    /** Stable ids already present with byte-equivalent declarations. */
+    unchanged_ids: string[];
+}
 /** Host adapter result for graph, validate, health, or provider sources. */
 export interface AssuranceExternalMeasurementResult {
     /** Observed value. */
@@ -277,6 +311,11 @@ export interface AssuranceEvaluationContext {
     history: AssuranceHistoryRecord[];
     /** Status ids that make an assertion owner terminal. */
     terminal_statuses?: string[];
+    /** Host-declared capabilities for provider-policy enforcement. */
+    provider_capabilities?: Readonly<Record<string, {
+        cost_class: AssuranceProviderCostClass;
+        network: boolean;
+    }>>;
     /** External source adapter. Implementations must enforce an appropriate timeout. */
     external: (source: AssuranceGraphSource | AssuranceValidateSource | AssuranceHealthSource | AssuranceProviderSource) => Promise<AssuranceExternalMeasurementResult>;
 }
@@ -297,6 +336,8 @@ export interface AssuranceMeasurementCost {
 export interface AssuranceMeasurementResult {
     /** Measurement id. */
     id: string;
+    /** Stable fingerprint of the exact declaration that produced this result. */
+    definition_fingerprint: string;
     /** Observed value. */
     value: AssuranceValue;
     /** Population denominator. */
@@ -319,6 +360,8 @@ export interface AssuranceAssertionVerdict {
     assertion_id: string;
     /** Stable observation key used to obtain the evaluated value. */
     measurement_id: string;
+    /** Stable fingerprint of the measurement declaration used for this verdict. */
+    measurement_definition_fingerprint: string;
     /** Explicit scope. */
     scope: AssuranceScope;
     /** Population denominator. */
@@ -401,12 +444,12 @@ export declare function createEmptyAssuranceDocument(): AssuranceDocument;
 export declare function evaluateMeasurement(definition: AssuranceMeasurementDefinition, context: AssuranceEvaluationContext, definitions?: AssuranceMeasurementDefinition[]): Promise<AssuranceMeasurementResult>;
 /** Evaluate one assertion against a precomputed measurement receipt. */
 export declare function evaluateAssuranceAssertion(definition: AssuranceAssertionDefinition, measurement: AssuranceMeasurementResult, options?: {
-    owner_terminal?: boolean;
+    /** Whether the owning item is terminal. */ owner_terminal?: boolean;
 }): AssuranceAssertionVerdict;
 /** Evaluate a named gate into one presentation-independent verdict document. */
 export declare function evaluateAssuranceGate(gateId: string, document: AssuranceDocument, context: AssuranceEvaluationContext, options: {
-    trigger: AssuranceGateTrigger; /** Skip persistence in the caller. */
-    dry_run?: boolean;
+    /** Trigger being evaluated. */ trigger: AssuranceGateTrigger;
+    /** Skip persistence in the caller. */ dry_run?: boolean;
 }): Promise<AssuranceGateVerdict>;
 /** Read all declarations of one kind with a stable row selector receipt. */
 export declare function listAssuranceDeclarations(pmRoot: string, kind: AssuranceDeclarationKind): Promise<{
@@ -421,6 +464,8 @@ export declare function listAssuranceDeclarations(pmRoot: string, kind: Assuranc
 export declare function getAssuranceDeclaration(pmRoot: string, kind: AssuranceDeclarationKind, id: string): Promise<AssuranceDeclaration>;
 /** Create or update one declaration through audited singleton persistence. */
 export declare function putAssuranceDeclaration(pmRoot: string, kind: AssuranceDeclarationKind, definition: AssuranceDeclaration, options?: AssuranceMutationOptions): Promise<AssuranceMutationReceipt>;
+/** Apply a declaration bundle atomically, idempotently, and without replacing divergent ids. */
+export declare function putAssuranceDeclarationBundle(pmRoot: string, bundle: AssuranceDeclarationBundle, options?: AssuranceMutationOptions): Promise<AssuranceBundleMutationReceipt>;
 /** Remove an unreferenced declaration through audited singleton persistence. */
 export declare function removeAssuranceDeclaration(pmRoot: string, kind: AssuranceDeclarationKind, id: string, options?: AssuranceMutationOptions): Promise<AssuranceMutationReceipt>;
 /** Append one immutable gate verdict without changing registry state. */