@unbrained/pm-cli 2026.8.11 → 2026.8.13

package/dist/sdk/governance/assurance.js

@@ -7,12 +7,15 @@
  * 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]="2c6c336c-abaa-53f7-94ac-ba4d5ab7c76a")}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]="e491ddd9-60e7-51fd-b0c7-4f6e86ee56f9")}catch(e){}}();
+import { createHash } from "node:crypto";
 import path from "node:path";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
-import { appendWorkspaceAuditEvent, mutateWorkspaceJsonWithHistory, readFileIfExists, readHistoryEntries, resolveAuthor, stableStringify, WORKSPACE_HISTORY_ID, getWorkspaceHistoryPath, } from "../runtime-primitives.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";
 /** Current serialized assurance registry format. */
 export const ASSURANCE_DOCUMENT_VERSION = 1;
 /** Supported lifecycle points that can evaluate a gate. */
@@ -43,18 +46,18 @@ const EVALUATION_CONCURRENCY = 4;
 const DEFAULT_VERDICT_LIMIT = 50;
 function requireStableId(value, field) {
     if (!ID_PATTERN.test(value)) {
-        throw new TypeError(`${field} must be a stable lowercase id`);
+        throw new AssuranceMutationRefusalError(`${field} must be a stable lowercase id`);
     }
 }
 function requireFiniteNonNegative(value, field) {
     if (!Number.isFinite(value) || value < 0) {
-        throw new TypeError(`${field} must be a finite non-negative number`);
+        throw new AssuranceMutationRefusalError(`${field} must be a finite non-negative number`);
     }
 }
 function boundFor(assertion) {
     const present = POLARITY_KEYS.filter((key) => assertion[key] !== undefined);
     if (present.length !== 1) {
-        throw new TypeError(`assertion ${assertion.id} must declare exactly one polarity`);
+        throw new AssuranceMutationRefusalError(`assertion ${assertion.id} must declare exactly one polarity`);
     }
     const polarity = present[0];
     const raw = assertion[polarity];
@@ -79,10 +82,12 @@ function compareBound(observed, bound) {
         return false;
     }
     const numericBound = bound.value;
-    if (bound.polarity === "ceiling" || bound.polarity === "monotone_nonincreasing") {
+    if (bound.polarity === "ceiling" ||
+        bound.polarity === "monotone_nonincreasing") {
         return observed <= numericBound;
     }
-    if (bound.polarity === "floor" || bound.polarity === "monotone_nondecreasing") {
+    if (bound.polarity === "floor" ||
+        bound.polarity === "monotone_nondecreasing") {
         return observed >= numericBound;
     }
     return observed === 0;
@@ -97,12 +102,15 @@ function proveNegativeControl(assertion) {
 function boundUpdateIsLoosening(beforeBound, afterBound) {
     if (beforeBound.polarity !== afterBound.polarity)
         return true;
-    if (typeof beforeBound.value === "number" && typeof afterBound.value === "number") {
-        return (beforeBound.polarity === "ceiling" || beforeBound.polarity === "monotone_nonincreasing"
+    if (typeof beforeBound.value === "number" &&
+        typeof afterBound.value === "number") {
+        return beforeBound.polarity === "ceiling" ||
+            beforeBound.polarity === "monotone_nonincreasing"
             ? afterBound.value > beforeBound.value
-            : beforeBound.polarity === "floor" || beforeBound.polarity === "monotone_nondecreasing"
+            : beforeBound.polarity === "floor" ||
+                beforeBound.polarity === "monotone_nondecreasing"
                 ? afterBound.value < beforeBound.value
-                : afterBound.value !== beforeBound.value);
+                : afterBound.value !== beforeBound.value;
     }
     if (beforeBound.polarity === "subset_of") {
         const beforeValues = beforeBound.value;
@@ -125,11 +133,28 @@ export function assuranceAssertionUpdateIsLoosening(before, after) {
         warn: 1,
         block: 2,
     };
-    const lifetimeLoosened = (before.lifetime ?? "hold") === "hold" && (after.lifetime ?? "hold") === "retire";
+    const lifetimeLoosened = (before.lifetime ?? "hold") === "hold" &&
+        (after.lifetime ?? "hold") === "retire";
     return (boundUpdateIsLoosening(boundFor(before), boundFor(after)) ||
         enforcementRank[after.enforcement] < enforcementRank[before.enforcement] ||
         lifetimeLoosened);
 }
+/** Validate the field predicate contract of an item-backed measurement source. */
+function validateItemsMeasurementSource(source) {
+    if (source.state !== undefined &&
+        !(source.state === "present" || source.state === "missing")) {
+        throw new AssuranceMutationRefusalError("items source state must be present or missing");
+    }
+    const hasEquals = Object.hasOwn(source, "equals");
+    const hasState = source.state !== undefined;
+    const predicateCount = Number(hasEquals) + Number(hasState);
+    if (source.field !== undefined && predicateCount !== 1) {
+        throw new AssuranceMutationRefusalError("items source with field requires exactly one of equals or state");
+    }
+    if (source.field === undefined && predicateCount !== 0) {
+        throw new AssuranceMutationRefusalError("items source equals/state requires field");
+    }
+}
 /** Validate and return one measurement declaration. */
 export function validateMeasurementDefinition(definition) {
     requireStableId(definition.id, "measurement.id");
@@ -137,14 +162,19 @@ export function validateMeasurementDefinition(definition) {
         requireFiniteNonNegative(definition.max_cost, "measurement.max_cost");
     }
     const source = definition.source;
-    if (source.kind === "items" && source.field !== undefined && source.equals === undefined) {
-        throw new TypeError("items source with field requires equals");
+    if (source.kind === "items") {
+        validateItemsMeasurementSource(source);
     }
-    if (source.kind === "dependency_kind" && source.dependency_kind.trim().length === 0) {
-        throw new TypeError("dependency_kind source requires dependency_kind");
+    if (source.kind === "dependency_kind" &&
+        (typeof source.dependency_kind !== "string" ||
+            source.dependency_kind.trim().length === 0)) {
+        throw new AssuranceMutationRefusalError("dependency_kind source requires dependency_kind");
     }
-    if ((source.kind === "graph" || source.kind === "validate" || source.kind === "health") && source.field.trim().length === 0) {
-        throw new TypeError(`${source.kind} source requires field`);
+    if ((source.kind === "graph" ||
+        source.kind === "validate" ||
+        source.kind === "health") &&
+        (typeof source.field !== "string" || source.field.trim().length === 0)) {
+        throw new AssuranceMutationRefusalError(`${source.kind} source requires field`);
     }
     if (source.kind === "provider") {
         requireStableId(source.provider, "provider source provider");
@@ -156,72 +186,108 @@ export function validateMeasurementDefinition(definition) {
 export function validateAssertionDefinition(definition) {
     requireStableId(definition.id, "assertion.id");
     requireStableId(definition.measurement_id, "assertion.measurement_id");
-    if (definition.owner_item_id.trim().length === 0) {
-        throw new TypeError("assertion.owner_item_id is required");
+    if (typeof definition.owner_item_id !== "string" ||
+        definition.owner_item_id.trim().length === 0) {
+        throw new AssuranceMutationRefusalError("assertion.owner_item_id is required");
     }
     const bound = boundFor(definition);
     if (typeof bound.value === "number" && !Number.isFinite(bound.value)) {
-        throw new TypeError(`assertion.${bound.polarity} must be a finite number`);
+        throw new AssuranceMutationRefusalError(`assertion.${bound.polarity} must be a finite number`);
     }
-    if (definition.lifetime === "retire" && !definition.retire_reason?.trim()) {
-        throw new TypeError("retired assertion requires retire_reason");
+    if (definition.lifetime === "retire" &&
+        (typeof definition.retire_reason !== "string" ||
+            definition.retire_reason.trim().length === 0)) {
+        throw new AssuranceMutationRefusalError("retired assertion requires retire_reason");
     }
     if (definition.scope.kind === "filter") {
         requireStableId(definition.scope.measurement_id, "assertion.scope.measurement_id");
     }
     const cases = definition.negative_control?.cases;
-    if (!Array.isArray(cases) || !cases.some((entry) => entry.expected === "pass") || !cases.some((entry) => entry.expected === "fail")) {
-        throw new TypeError("assertion negative control requires pass and fail cases");
+    if (!Array.isArray(cases) ||
+        !cases.some((entry) => entry.expected === "pass") ||
+        !cases.some((entry) => entry.expected === "fail")) {
+        throw new AssuranceMutationRefusalError("assertion negative control requires pass and fail cases");
     }
     if (!proveNegativeControl(definition)) {
-        throw new TypeError(`assertion ${definition.id} negative control does not prove its bound`);
+        throw new AssuranceMutationRefusalError(`assertion ${definition.id} negative control does not prove its bound`);
     }
     return definition;
 }
+function validateGateProviderPolicy(policy) {
+    if (!Array.isArray(policy.allowed_providers)) {
+        throw new AssuranceMutationRefusalError("gate provider_policy.allowed_providers must be an array");
+    }
+    for (const provider of policy.allowed_providers) {
+        requireStableId(provider, "gate.provider_policy.allowed_provider");
+    }
+    if (typeof policy.triggers !== "object" ||
+        policy.triggers === null ||
+        Array.isArray(policy.triggers)) {
+        throw new AssuranceMutationRefusalError("gate provider_policy.triggers must be an object");
+    }
+    for (const [trigger, rule] of Object.entries(policy.triggers)) {
+        if (!ASSURANCE_GATE_TRIGGERS.includes(trigger)) {
+            throw new AssuranceMutationRefusalError(`gate provider policy has unknown trigger ${trigger}`);
+        }
+        if (typeof rule !== "object" ||
+            rule === null ||
+            !["low", "medium", "high"].includes(rule.max_cost_class) ||
+            typeof rule.allow_network !== "boolean") {
+            throw new AssuranceMutationRefusalError(`gate provider policy trigger ${trigger} is invalid`);
+        }
+    }
+}
 /** Validate and return one gate declaration. */
 export function validateGateDefinition(definition) {
     requireStableId(definition.id, "gate.id");
     if (definition.assertion_ids.length === 0) {
-        throw new TypeError("gate requires at least one assertion");
+        throw new AssuranceMutationRefusalError("gate requires at least one assertion");
     }
     for (const id of definition.assertion_ids)
         requireStableId(id, "gate.assertion_id");
     if (definition.triggers.length === 0) {
-        throw new TypeError("gate requires at least one trigger");
+        throw new AssuranceMutationRefusalError("gate requires at least one trigger");
+    }
+    if (definition.provider_policy) {
+        validateGateProviderPolicy(definition.provider_policy);
     }
     return definition;
 }
 /** Validate registry references, uniqueness, and declaration-local contracts. */
 export function validateAssuranceDocument(document) {
     if (document.version !== ASSURANCE_DOCUMENT_VERSION) {
-        throw new TypeError(`unsupported assurance document version ${String(document.version)}`);
+        throw new AssuranceMutationRefusalError(`unsupported assurance document version ${String(document.version)}`);
     }
     const ids = new Set();
     for (const definition of document.measurements) {
         validateMeasurementDefinition(definition);
-        if (ids.has(`measurement:${definition.id}`))
-            throw new TypeError(`duplicate measurement ${definition.id}`);
+        if (ids.has(`measurement:${definition.id}`)) {
+            throw new AssuranceMutationRefusalError(`duplicate measurement ${definition.id}`);
+        }
         ids.add(`measurement:${definition.id}`);
     }
     for (const definition of document.assertions) {
         validateAssertionDefinition(definition);
-        if (ids.has(`assertion:${definition.id}`))
-            throw new TypeError(`duplicate assertion ${definition.id}`);
+        if (ids.has(`assertion:${definition.id}`)) {
+            throw new AssuranceMutationRefusalError(`duplicate assertion ${definition.id}`);
+        }
         ids.add(`assertion:${definition.id}`);
     }
     for (const definition of document.gates) {
         validateGateDefinition(definition);
         const missing = definition.assertion_ids.filter((id) => !document.assertions.some((assertionDefinition) => assertionDefinition.id === id));
-        if (missing.length > 0)
-            throw new TypeError(`gate ${definition.id} references missing assertions: ${missing.join(", ")}`);
-        if (ids.has(`gate:${definition.id}`))
-            throw new TypeError(`duplicate gate ${definition.id}`);
+        if (missing.length > 0) {
+            throw new AssuranceMutationRefusalError(`gate ${definition.id} references missing assertions: ${missing.join(", ")}`);
+        }
+        if (ids.has(`gate:${definition.id}`)) {
+            throw new AssuranceMutationRefusalError(`duplicate gate ${definition.id}`);
+        }
         ids.add(`gate:${definition.id}`);
     }
     const measurementIds = new Set(document.measurements.map((entry) => entry.id));
     for (const [measurementId, consumers] of collectMeasurementReferences(document)) {
         if (!measurementIds.has(measurementId)) {
-            throw new TypeError(`${consumers.join(", ")} references missing measurement ${measurementId}`);
+            throw new AssuranceMutationRefusalError(`${consumers.join(", ")} references missing measurement ${measurementId}`);
         }
     }
     return document;
@@ -261,17 +327,60 @@ function collectMeasurementReferences(document) {
     }
     return references;
 }
+function collectGateProviderIds(gate, document) {
+    const pending = gate.assertion_ids.flatMap((assertionId) => {
+        const assertion = document.assertions.find((entry) => entry.id === assertionId);
+        return [
+            assertion.measurement_id,
+            ...(assertion.scope.kind === "filter"
+                ? [assertion.scope.measurement_id]
+                : []),
+        ];
+    });
+    const visited = new Set();
+    const providers = new Set();
+    while (pending.length > 0) {
+        const measurementId = pending.pop();
+        if (visited.has(measurementId))
+            continue;
+        visited.add(measurementId);
+        const measurement = document.measurements.find((entry) => entry.id === measurementId);
+        if (measurement.source.kind === "provider") {
+            providers.add(measurement.source.provider);
+        }
+        else if (measurement.source.kind === "derived") {
+            collectExpressionMeasurementReferences(measurement.source.expression, pending);
+        }
+    }
+    return providers;
+}
 /** Create an empty, valid assurance registry. */
 export function createEmptyAssuranceDocument() {
-    return { version: ASSURANCE_DOCUMENT_VERSION, measurements: [], assertions: [], gates: [] };
+    return {
+        version: ASSURANCE_DOCUMENT_VERSION,
+        measurements: [],
+        assertions: [],
+        gates: [],
+    };
 }
 function itemsSourceResult(source, context) {
-    const matches = context.items.filter((item) => (source.statuses === undefined || source.statuses.includes(item.status)) &&
+    const matches = context.items.filter((item) => (source.statuses === undefined ||
+        source.statuses.includes(item.status)) &&
         (source.types === undefined || source.types.includes(item.type)) &&
         (source.tags === undefined ||
             source.tags.every((tag) => item.tags?.includes(tag))) &&
         (source.field === undefined ||
-            valuesEqual(item[source.field], source.equals)));
+            (() => {
+                const value = item[source.field];
+                if (source.state !== undefined) {
+                    const missing = value === undefined ||
+                        value === null ||
+                        value === "" ||
+                        (Array.isArray(value) && value.length === 0);
+                    return source.state === "missing" ? missing : !missing;
+                }
+                return valuesEqual(value, source.equals);
+            })()));
     return {
         value: matches.length,
         population_size: context.items.length,
@@ -281,9 +390,13 @@ function itemsSourceResult(source, context) {
 }
 function dependencyKindSourceResult(source, context) {
     const contributors = [];
+    const requestedKind = resolveCanonicalRelationshipKind(source.dependency_kind) ??
+        source.dependency_kind.trim().toLowerCase();
     for (const item of context.items) {
         for (const dependency of item.dependencies ?? []) {
-            if (dependency.kind === source.dependency_kind) {
+            const dependencyKind = resolveCanonicalRelationshipKind(dependency.kind) ??
+                dependency.kind.trim().toLowerCase();
+            if (dependencyKind === requestedKind) {
                 contributors.push(`${item.id}->${dependency.id}`);
             }
         }
@@ -340,7 +453,13 @@ function sumCosts(costs, durationMs) {
         history_entries: total.history_entries + cost.history_entries,
         provider_calls: total.provider_calls + cost.provider_calls,
         duration_ms: durationMs,
-    }), { units: 0, items_scanned: 0, history_entries: 0, provider_calls: 0, duration_ms: durationMs });
+    }), {
+        units: 0,
+        items_scanned: 0,
+        history_entries: 0,
+        provider_calls: 0,
+        duration_ms: durationMs,
+    });
 }
 function arithmeticValue(operator, values) {
     if (values.length === 0)
@@ -373,7 +492,12 @@ async function mapWithConcurrency(values, limit, transform) {
 }
 async function evaluateExpression(expression, context, definitions, stack, state) {
     if ("literal" in expression)
-        return { value: expression.literal, costs: [], population_size: 0, contributors: [] };
+        return {
+            value: expression.literal,
+            costs: [],
+            population_size: 0,
+            contributors: [],
+        };
     if ("measurement" in expression) {
         const definition = definitions.find((entry) => entry.id === expression.measurement);
         if (!definition)
@@ -383,7 +507,12 @@ async function evaluateExpression(expression, context, definitions, stack, state
             throw new TypeError(`derived measurement ${definition.id} is not numeric`);
         const costs = state.charged.has(definition.id) ? [] : [result.cost];
         state.charged.add(definition.id);
-        return { value: result.value, costs, population_size: result.population_size, contributors: result.contributors };
+        return {
+            value: result.value,
+            costs,
+            population_size: result.population_size,
+            contributors: result.contributors,
+        };
     }
     const operands = await mapWithConcurrency(expression.operands, EVALUATION_CONCURRENCY, (operand) => evaluateExpression(operand, context, definitions, stack, state));
     return {
@@ -401,7 +530,12 @@ async function evaluateMeasurementInternal(definition, context, definitions, sta
     let providerCalls = 0;
     if (definition.source.kind === "derived") {
         const derived = await evaluateExpression(definition.source.expression, context, definitions, [...stack, definition.id], state);
-        result = { value: derived.value, population_size: derived.population_size, cost: 0, contributors: derived.contributors };
+        result = {
+            value: derived.value,
+            population_size: derived.population_size,
+            cost: 0,
+            contributors: derived.contributors,
+        };
         nestedCosts = derived.costs;
     }
     else {
@@ -422,16 +556,29 @@ async function evaluateMeasurementInternal(definition, context, definitions, sta
     }
     const ownCost = {
         units: result.cost,
-        items_scanned: definition.source.kind === "items" || definition.source.kind === "dependency_kind" || definition.source.kind === "links" ? context.items.length : 0,
+        items_scanned: definition.source.kind === "items" ||
+            definition.source.kind === "dependency_kind" ||
+            definition.source.kind === "links"
+            ? context.items.length
+            : 0,
         history_entries: definition.source.kind === "history" ? context.history.length : 0,
         provider_calls: providerCalls,
         duration_ms: Date.now() - startedAt,
     };
     const cost = sumCosts([...nestedCosts, ownCost], Date.now() - startedAt);
     if (definition.max_cost !== undefined && cost.units > definition.max_cost) {
-        throw new TypeError(`measurement ${definition.id} exceeded cost ceiling ${definition.max_cost} with ${cost.units}`);
+        throw new AssuranceEvaluationRefusalError(`measurement ${definition.id} exceeded cost ceiling ${definition.max_cost} with ${cost.units}`);
     }
-    return { id: definition.id, value: result.value, population_size: result.population_size, cost, contributors: result.contributors ?? [] };
+    return {
+        id: definition.id,
+        definition_fingerprint: `sha256:${createHash("sha256")
+            .update(stableStringify(definition))
+            .digest("hex")}`,
+        value: result.value,
+        population_size: result.population_size,
+        cost,
+        contributors: result.contributors ?? [],
+    };
 }
 function evaluateMeasurementCached(definition, context, definitions, stack, state) {
     if (stack.includes(definition.id)) {
@@ -454,7 +601,8 @@ export async function evaluateMeasurement(definition, context, definitions = [de
 function assertionDistance(observed, bound) {
     if (typeof observed !== "number" || typeof bound.value !== "number")
         return null;
-    if (bound.polarity === "ceiling" || bound.polarity === "monotone_nonincreasing")
+    if (bound.polarity === "ceiling" ||
+        bound.polarity === "monotone_nonincreasing")
         return bound.value - observed;
     if (bound.polarity === "floor" || bound.polarity === "monotone_nondecreasing")
         return observed - bound.value;
@@ -468,18 +616,54 @@ export function evaluateAssuranceAssertion(definition, measurement, options = {}
     return {
         assertion_id: definition.id,
         measurement_id: definition.measurement_id,
+        measurement_definition_fingerprint: measurement.definition_fingerprint,
         scope: definition.scope,
         population_size: measurement.population_size,
         observed: measurement.value,
         bound,
         distance: assertionDistance(measurement.value, bound),
-        verdict: retired ? "retired" : compareBound(measurement.value, bound) ? "pass" : "fail",
+        verdict: retired
+            ? "retired"
+            : compareBound(measurement.value, bound)
+                ? "pass"
+                : "fail",
         enforcement: definition.enforcement,
         negative_control_proven: proveNegativeControl(definition),
         cost: measurement.cost,
         contributors: measurement.contributors,
     };
 }
+function enforceGateProviderPolicy(gate, document, context, trigger) {
+    const providerIds = collectGateProviderIds(gate, document);
+    if (providerIds.size === 0)
+        return;
+    const policy = gate.provider_policy;
+    const triggerPolicy = policy?.triggers[trigger];
+    if (!policy || !triggerPolicy) {
+        throw new AssuranceEvaluationRefusalError(`assurance gate ${gate.id} refuses provider execution at trigger ${trigger} without an explicit provider policy`);
+    }
+    const allowedProviders = new Set(policy.allowed_providers);
+    const costRank = {
+        low: 0,
+        medium: 1,
+        high: 2,
+    };
+    for (const providerId of providerIds) {
+        if (!allowedProviders.has(providerId)) {
+            throw new AssuranceEvaluationRefusalError(`assurance gate ${gate.id} refuses provider ${providerId}`);
+        }
+        const capability = context.provider_capabilities?.[providerId];
+        if (!capability) {
+            throw new AssuranceEvaluationRefusalError(`assurance provider ${providerId} has no declared capabilities`);
+        }
+        if (costRank[capability.cost_class] > costRank[triggerPolicy.max_cost_class]) {
+            throw new AssuranceEvaluationRefusalError(`assurance gate ${gate.id} refuses ${capability.cost_class}-cost provider ${providerId} at trigger ${trigger}`);
+        }
+        if (capability.network && !triggerPolicy.allow_network) {
+            throw new AssuranceEvaluationRefusalError(`assurance gate ${gate.id} refuses network provider ${providerId} at trigger ${trigger}`);
+        }
+    }
+}
 /** Evaluate a named gate into one presentation-independent verdict document. */
 export async function evaluateAssuranceGate(gateId, document, context, options) {
     validateAssuranceDocument(document);
@@ -489,6 +673,7 @@ export async function evaluateAssuranceGate(gateId, document, context, options)
     if (!gateDefinition.triggers.includes(options.trigger)) {
         throw new TypeError(`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) => {
         const assertionDefinition = document.assertions.find((entry) => entry.id === id);
         const measurementDefinition = document.measurements.find((entry) => entry.id === assertionDefinition.measurement_id);
@@ -571,7 +756,11 @@ function validateForKind(kind, definition) {
 /** Read all declarations of one kind with a stable row selector receipt. */
 export async function listAssuranceDeclarations(pmRoot, kind) {
     const items = structuredClone(collectionFor(await readDocument(pmRoot), kind));
-    return { items, count: items.length, row_contract: { row_keys: ["items"], jq_selector: ".items[]" } };
+    return {
+        items,
+        count: items.length,
+        row_contract: { row_keys: ["items"], jq_selector: ".items[]" },
+    };
 }
 /** Read one named declaration or fail loudly. */
 export async function getAssuranceDeclaration(pmRoot, kind, id) {
@@ -583,7 +772,8 @@ export async function getAssuranceDeclaration(pmRoot, kind, id) {
 /** Create or update one declaration through audited singleton persistence. */
 export async function putAssuranceDeclaration(pmRoot, kind, definition, options = {}) {
     validateForKind(kind, definition);
-    const author = resolveAuthor(options.author, "unknown");
+    const settings = await readSettings(pmRoot);
+    const author = resolveAuthor(options.author, settings.author_default);
     const mutation = await mutateWorkspaceJsonWithHistory({
         pmRoot,
         filePath: assurancePath(pmRoot),
@@ -593,16 +783,20 @@ export async function putAssuranceDeclaration(pmRoot, kind, definition, options
         lockTtlSeconds: LOCK_TTL_SECONDS,
         lockWaitMs: LOCK_WAIT_MS,
         mutate: (beforeRaw) => {
-            const document = beforeRaw === null ? createEmptyAssuranceDocument() : parseAssuranceDocument(beforeRaw);
+            const document = beforeRaw === null
+                ? createEmptyAssuranceDocument()
+                : parseAssuranceDocument(beforeRaw);
             const collection = collectionFor(document, kind);
             const index = collection.findIndex((entry) => entry.id === definition.id);
             const action = index < 0 ? "created" : "updated";
             if (kind === "assertion" &&
                 index >= 0 &&
                 assuranceAssertionUpdateIsLoosening(collection[index], definition)) {
-                const decision = definition.authorization_decision;
-                if (!decision || !options.authorized_decision_ids?.includes(decision)) {
-                    throw new TypeError(`loosening assertion ${definition.id} requires a verified authorization_decision`);
+                const decision = definition
+                    .authorization_decision;
+                if (!decision ||
+                    !options.authorized_decision_ids?.includes(decision)) {
+                    throw new AssuranceMutationRefusalError(`loosening assertion ${definition.id} requires a verified authorization_decision`);
                 }
             }
             if (index < 0)
@@ -618,9 +812,63 @@ export async function putAssuranceDeclaration(pmRoot, kind, definition, options
     });
     return { ...mutation.result, changed: mutation.changed };
 }
+/** Apply a declaration bundle atomically, idempotently, and without replacing divergent ids. */
+export async function putAssuranceDeclarationBundle(pmRoot, bundle, options = {}) {
+    const candidate = createEmptyAssuranceDocument();
+    candidate.measurements = structuredClone(bundle.measurements);
+    candidate.assertions = structuredClone(bundle.assertions);
+    candidate.gates = structuredClone(bundle.gates);
+    validateAssuranceDocument(candidate);
+    const settings = await readSettings(pmRoot);
+    const author = resolveAuthor(options.author, settings.author_default);
+    const mutation = await mutateWorkspaceJsonWithHistory({
+        pmRoot,
+        filePath: assurancePath(pmRoot),
+        op: "assurance:bundle:apply",
+        author,
+        message: options.message,
+        lockTtlSeconds: LOCK_TTL_SECONDS,
+        lockWaitMs: LOCK_WAIT_MS,
+        mutate: (beforeRaw) => {
+            const document = beforeRaw === null
+                ? createEmptyAssuranceDocument()
+                : parseAssuranceDocument(beforeRaw);
+            const createdIds = [];
+            const unchangedIds = [];
+            const apply = (target, additions, kind) => {
+                for (const definition of additions) {
+                    const existing = target.find((entry) => entry.id === definition.id);
+                    if (!existing) {
+                        target.push(structuredClone(definition));
+                        createdIds.push(`${kind}:${definition.id}`);
+                        continue;
+                    }
+                    if (stableStringify(existing) !== stableStringify(definition)) {
+                        throw new AssuranceMutationRefusalError(`assurance bundle refuses to replace divergent ${kind} ${definition.id}`);
+                    }
+                    unchangedIds.push(`${kind}:${definition.id}`);
+                }
+            };
+            apply(document.measurements, candidate.measurements, "measurement");
+            apply(document.assertions, candidate.assertions, "assertion");
+            apply(document.gates, candidate.gates, "gate");
+            validateAssuranceDocument(document);
+            return {
+                raw: `${JSON.stringify(document, null, 2)}\n`,
+                result: {
+                    changed: createdIds.length > 0,
+                    created_ids: createdIds,
+                    unchanged_ids: unchangedIds,
+                },
+            };
+        },
+    });
+    return { ...mutation.result, changed: mutation.changed };
+}
 /** Remove an unreferenced declaration through audited singleton persistence. */
 export async function removeAssuranceDeclaration(pmRoot, kind, id, options = {}) {
-    const author = resolveAuthor(options.author, "unknown");
+    const settings = await readSettings(pmRoot);
+    const author = resolveAuthor(options.author, settings.author_default);
     const mutation = await mutateWorkspaceJsonWithHistory({
         pmRoot,
         filePath: assurancePath(pmRoot),
@@ -630,20 +878,24 @@ export async function removeAssuranceDeclaration(pmRoot, kind, id, options = {})
         lockTtlSeconds: LOCK_TTL_SECONDS,
         lockWaitMs: LOCK_WAIT_MS,
         mutate: (beforeRaw) => {
-            const document = beforeRaw === null ? createEmptyAssuranceDocument() : parseAssuranceDocument(beforeRaw);
+            const document = beforeRaw === null
+                ? createEmptyAssuranceDocument()
+                : parseAssuranceDocument(beforeRaw);
             if (kind === "measurement") {
                 const consumers = collectMeasurementReferences(document).get(id);
                 if (consumers && consumers.length > 0) {
-                    throw new TypeError(`assurance measurement ${id} is referenced by ${consumers.join(", ")}`);
+                    throw new AssuranceMutationRefusalError(`assurance measurement ${id} is referenced by ${consumers.join(", ")}`);
                 }
             }
-            if (kind === "assertion" && document.gates.some((entry) => entry.assertion_ids.includes(id))) {
-                throw new TypeError(`assurance assertion ${id} is referenced by gate`);
+            if (kind === "assertion" &&
+                document.gates.some((entry) => entry.assertion_ids.includes(id))) {
+                throw new AssuranceMutationRefusalError(`assurance assertion ${id} is referenced by gate`);
             }
             const collection = collectionFor(document, kind);
             const index = collection.findIndex((entry) => entry.id === id);
-            if (index < 0)
-                throw new TypeError(`assurance ${kind} ${id} not found`);
+            if (index < 0) {
+                throw new AssuranceMutationRefusalError(`assurance ${kind} ${id} not found`);
+            }
             collection.splice(index, 1);
             validateAssuranceDocument(document);
             return {
@@ -658,12 +910,14 @@ export async function removeAssuranceDeclaration(pmRoot, kind, id, options = {})
 export async function recordAssuranceVerdict(pmRoot, verdict, options = {}) {
     if (verdict.dry_run)
         throw new TypeError("dry-run assurance verdicts are not persisted");
+    const settings = await readSettings(pmRoot);
     await appendWorkspaceAuditEvent({
         pmRoot,
         op: "assurance:gate:verdict",
-        author: resolveAuthor(options.author, "unknown"),
+        author: resolveAuthor(options.author, settings.author_default),
         context: { assurance_verdict: verdict },
-        message: options.message ?? `Assurance gate ${verdict.gate_id} returned ${verdict.verdict}`,
+        message: options.message ??
+            `Assurance gate ${verdict.gate_id} returned ${verdict.verdict}`,
         lockTtlSeconds: LOCK_TTL_SECONDS,
         lockWaitMs: LOCK_WAIT_MS,
     });
@@ -686,4 +940,4 @@ export async function listAssuranceVerdicts(pmRoot, options = {}) {
         .slice(0, limit);
 }
 //# sourceMappingURL=assurance.js.map
-//# debugId=2c6c336c-abaa-53f7-94ac-ba4d5ab7c76a
+//# debugId=e491ddd9-60e7-51fd-b0c7-4f6e86ee56f9