@unbrained/pm-cli 2026.8.10 → 2026.8.11

package/dist/sdk/governance/assurance.js

@@ -0,0 +1,689 @@
+/**
+ * @module sdk/assurance
+ *
+ * Declares, persists, evaluates, and audits project assurance contracts. The
+ * module deliberately owns semantics while hosts inject workspace data and
+ * external measurement adapters, keeping CLI, MCP, CI, and embedded callers on
+ * 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){}}();
+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 { MAX_ASSURANCE_VERDICT_LIMIT } from "./assurance-limits.js";
+/** Current serialized assurance registry format. */
+export const ASSURANCE_DOCUMENT_VERSION = 1;
+/** Supported lifecycle points that can evaluate a gate. */
+export const ASSURANCE_GATE_TRIGGERS = [
+    "pre-commit",
+    "pre-push",
+    "pre-merge",
+    "ci",
+    "pre-release",
+    "post-release",
+    "scheduled",
+    "on-claim",
+    "on-close",
+];
+const POLARITY_KEYS = [
+    "ceiling",
+    "floor",
+    "equals",
+    "zero",
+    "monotone_nondecreasing",
+    "monotone_nonincreasing",
+    "subset_of",
+];
+const ID_PATTERN = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;
+const LOCK_TTL_SECONDS = 30;
+const LOCK_WAIT_MS = 5_000;
+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`);
+    }
+}
+function requireFiniteNonNegative(value, field) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new TypeError(`${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`);
+    }
+    const polarity = present[0];
+    const raw = assertion[polarity];
+    return {
+        polarity,
+        value: polarity === "zero" ? 0 : raw,
+    };
+}
+function valuesEqual(left, right) {
+    return stableStringify(left) === stableStringify(right);
+}
+function compareBound(observed, bound) {
+    if (bound.polarity === "equals")
+        return valuesEqual(observed, bound.value);
+    if (bound.polarity === "subset_of") {
+        if (!Array.isArray(observed) || !Array.isArray(bound.value))
+            return false;
+        const allowed = bound.value;
+        return observed.every((entry) => allowed.includes(entry));
+    }
+    if (typeof observed !== "number") {
+        return false;
+    }
+    const numericBound = bound.value;
+    if (bound.polarity === "ceiling" || bound.polarity === "monotone_nonincreasing") {
+        return observed <= numericBound;
+    }
+    if (bound.polarity === "floor" || bound.polarity === "monotone_nondecreasing") {
+        return observed >= numericBound;
+    }
+    return observed === 0;
+}
+function proveNegativeControl(assertion) {
+    const bound = boundFor(assertion);
+    const cases = assertion.negative_control.cases;
+    return (cases.some((entry) => entry.expected === "pass") &&
+        cases.some((entry) => entry.expected === "fail") &&
+        cases.every((entry) => compareBound(entry.observed, bound) === (entry.expected === "pass")));
+}
+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"
+            ? afterBound.value > beforeBound.value
+            : beforeBound.polarity === "floor" || beforeBound.polarity === "monotone_nondecreasing"
+                ? afterBound.value < beforeBound.value
+                : afterBound.value !== beforeBound.value);
+    }
+    if (beforeBound.polarity === "subset_of") {
+        const beforeValues = beforeBound.value;
+        const afterValues = afterBound.value;
+        return (!Array.isArray(beforeValues) ||
+            !Array.isArray(afterValues) ||
+            afterValues.some((entry) => !beforeValues.includes(entry)));
+    }
+    return !valuesEqual(beforeBound.value, afterBound.value);
+}
+/** Return true when an assertion update weakens scope, bound, lifetime, or enforcement. */
+export function assuranceAssertionUpdateIsLoosening(before, after) {
+    if (before.measurement_id !== after.measurement_id ||
+        before.owner_item_id !== after.owner_item_id ||
+        stableStringify(before.scope) !== stableStringify(after.scope)) {
+        return true;
+    }
+    const enforcementRank = {
+        observe: 0,
+        warn: 1,
+        block: 2,
+    };
+    const lifetimeLoosened = (before.lifetime ?? "hold") === "hold" && (after.lifetime ?? "hold") === "retire";
+    return (boundUpdateIsLoosening(boundFor(before), boundFor(after)) ||
+        enforcementRank[after.enforcement] < enforcementRank[before.enforcement] ||
+        lifetimeLoosened);
+}
+/** Validate and return one measurement declaration. */
+export function validateMeasurementDefinition(definition) {
+    requireStableId(definition.id, "measurement.id");
+    if (definition.max_cost !== undefined) {
+        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 === "dependency_kind" && source.dependency_kind.trim().length === 0) {
+        throw new TypeError("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 === "provider") {
+        requireStableId(source.provider, "provider source provider");
+        requireStableId(source.key, "provider source key");
+    }
+    return definition;
+}
+/** Validate and return one assertion declaration. */
+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");
+    }
+    const bound = boundFor(definition);
+    if (typeof bound.value === "number" && !Number.isFinite(bound.value)) {
+        throw new TypeError(`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.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 (!proveNegativeControl(definition)) {
+        throw new TypeError(`assertion ${definition.id} negative control does not prove its bound`);
+    }
+    return definition;
+}
+/** 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");
+    }
+    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");
+    }
+    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)}`);
+    }
+    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}`);
+        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}`);
+        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}`);
+        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}`);
+        }
+    }
+    return document;
+}
+function collectExpressionMeasurementReferences(expression, references) {
+    if ("measurement" in expression) {
+        references.push(expression.measurement);
+        return;
+    }
+    if ("operator" in expression) {
+        for (const operand of expression.operands) {
+            collectExpressionMeasurementReferences(operand, references);
+        }
+    }
+}
+function collectMeasurementReferences(document) {
+    const references = new Map();
+    const add = (measurementId, consumer) => {
+        const consumers = references.get(measurementId) ?? [];
+        consumers.push(consumer);
+        references.set(measurementId, consumers);
+    };
+    for (const assertionDefinition of document.assertions) {
+        add(assertionDefinition.measurement_id, `assertion ${assertionDefinition.id}`);
+        if (assertionDefinition.scope.kind === "filter") {
+            add(assertionDefinition.scope.measurement_id, `assertion ${assertionDefinition.id} scope`);
+        }
+    }
+    for (const measurementDefinition of document.measurements) {
+        if (measurementDefinition.source.kind !== "derived")
+            continue;
+        const derivedReferences = [];
+        collectExpressionMeasurementReferences(measurementDefinition.source.expression, derivedReferences);
+        for (const measurementId of derivedReferences) {
+            add(measurementId, `derived measurement ${measurementDefinition.id}`);
+        }
+    }
+    return references;
+}
+/** Create an empty, valid assurance registry. */
+export function createEmptyAssuranceDocument() {
+    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)) &&
+        (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)));
+    return {
+        value: matches.length,
+        population_size: context.items.length,
+        cost: context.items.length,
+        contributors: matches.map((item) => item.id),
+    };
+}
+function dependencyKindSourceResult(source, context) {
+    const contributors = [];
+    for (const item of context.items) {
+        for (const dependency of item.dependencies ?? []) {
+            if (dependency.kind === source.dependency_kind) {
+                contributors.push(`${item.id}->${dependency.id}`);
+            }
+        }
+    }
+    return {
+        value: contributors.length,
+        population_size: context.items.length,
+        cost: context.items.length,
+        contributors,
+    };
+}
+function historySourceResult(source, context) {
+    const matches = context.history.filter((entry) => (source.op === undefined || entry.op === source.op) &&
+        (source.author === undefined || entry.author === source.author) &&
+        (source.harness === undefined ||
+            entry.agent_harness === source.harness) &&
+        (source.model === undefined || entry.agent_model === source.model));
+    return {
+        value: matches.length,
+        population_size: context.history.length,
+        cost: context.history.length,
+    };
+}
+function linksSourceResult(source, context) {
+    const matches = context.items.filter((item) => {
+        const links = item[source.link];
+        const present = Array.isArray(links) && links.length > 0;
+        return source.state === "present" ? present : !present;
+    });
+    return {
+        value: matches.length,
+        population_size: context.items.length,
+        cost: context.items.length,
+        contributors: matches.map((item) => item.id),
+    };
+}
+function sourceResult(definition, context) {
+    const source = definition.source;
+    if (source.kind === "items")
+        return itemsSourceResult(source, context);
+    if (source.kind === "dependency_kind") {
+        return dependencyKindSourceResult(source, context);
+    }
+    if (source.kind === "history")
+        return historySourceResult(source, context);
+    if (source.kind === "links")
+        return linksSourceResult(source, context);
+    return null;
+}
+function sumCosts(costs, durationMs) {
+    return costs.reduce((total, cost) => ({
+        units: total.units + cost.units,
+        items_scanned: total.items_scanned + cost.items_scanned,
+        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 });
+}
+function arithmeticValue(operator, values) {
+    if (values.length === 0)
+        throw new TypeError(`derived ${operator} requires operands`);
+    if (operator === "add")
+        return values.reduce((sum, value) => sum + value, 0);
+    if (operator === "subtract")
+        return values.slice(1).reduce((result, value) => result - value, values[0]);
+    if (operator === "multiply")
+        return values.reduce((result, value) => result * value, 1);
+    if (operator === "divide") {
+        if (values.slice(1).includes(0))
+            throw new TypeError("derived divide cannot divide by zero");
+        return values.slice(1).reduce((result, value) => result / value, values[0]);
+    }
+    return operator === "min" ? Math.min(...values) : Math.max(...values);
+}
+async function mapWithConcurrency(values, limit, transform) {
+    const results = new Array(values.length);
+    let nextIndex = 0;
+    const workers = Array.from({ length: Math.min(limit, values.length) }, async () => {
+        while (nextIndex < values.length) {
+            const index = nextIndex;
+            nextIndex += 1;
+            results[index] = await transform(values[index], index);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+async function evaluateExpression(expression, context, definitions, stack, state) {
+    if ("literal" in expression)
+        return { value: expression.literal, costs: [], population_size: 0, contributors: [] };
+    if ("measurement" in expression) {
+        const definition = definitions.find((entry) => entry.id === expression.measurement);
+        if (!definition)
+            throw new TypeError(`derived measurement references missing ${expression.measurement}`);
+        const result = await evaluateMeasurementCached(definition, context, definitions, stack, state);
+        if (typeof result.value !== "number")
+            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 };
+    }
+    const operands = await mapWithConcurrency(expression.operands, EVALUATION_CONCURRENCY, (operand) => evaluateExpression(operand, context, definitions, stack, state));
+    return {
+        value: arithmeticValue(expression.operator, operands.map((entry) => entry.value)),
+        costs: operands.flatMap((entry) => entry.costs),
+        population_size: Math.max(0, ...operands.map((entry) => entry.population_size)),
+        contributors: [...new Set(operands.flatMap((entry) => entry.contributors))],
+    };
+}
+async function evaluateMeasurementInternal(definition, context, definitions, stack, state) {
+    validateMeasurementDefinition(definition);
+    const startedAt = Date.now();
+    let result;
+    let nestedCosts = [];
+    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 };
+        nestedCosts = derived.costs;
+    }
+    else {
+        const builtin = sourceResult(definition, context);
+        if (builtin !== null) {
+            result = builtin;
+        }
+        else if (definition.source.kind === "graph" ||
+            definition.source.kind === "validate" ||
+            definition.source.kind === "health" ||
+            definition.source.kind === "provider") {
+            result = await context.external(definition.source);
+            providerCalls = 1;
+        }
+        else {
+            throw new TypeError(`unsupported assurance source ${definition.source.kind}`);
+        }
+    }
+    const ownCost = {
+        units: result.cost,
+        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}`);
+    }
+    return { id: definition.id, value: result.value, population_size: result.population_size, cost, contributors: result.contributors ?? [] };
+}
+function evaluateMeasurementCached(definition, context, definitions, stack, state) {
+    if (stack.includes(definition.id)) {
+        throw new TypeError(`derived measurement cycle: ${[...stack, definition.id].join(" -> ")}`);
+    }
+    const cached = state.cache.get(definition.id);
+    if (cached)
+        return cached;
+    const evaluation = evaluateMeasurementInternal(definition, context, definitions, stack, state);
+    state.cache.set(definition.id, evaluation);
+    return evaluation;
+}
+/** Evaluate one measurement with cycle detection and a complete cost receipt. */
+export async function evaluateMeasurement(definition, context, definitions = [definition]) {
+    return evaluateMeasurementCached(definition, context, definitions, [], {
+        cache: new Map(),
+        charged: new Set(),
+    });
+}
+function assertionDistance(observed, bound) {
+    if (typeof observed !== "number" || typeof bound.value !== "number")
+        return null;
+    if (bound.polarity === "ceiling" || bound.polarity === "monotone_nonincreasing")
+        return bound.value - observed;
+    if (bound.polarity === "floor" || bound.polarity === "monotone_nondecreasing")
+        return observed - bound.value;
+    return observed - bound.value;
+}
+/** Evaluate one assertion against a precomputed measurement receipt. */
+export function evaluateAssuranceAssertion(definition, measurement, options = {}) {
+    validateAssertionDefinition(definition);
+    const bound = boundFor(definition);
+    const retired = definition.lifetime === "retire" && options.owner_terminal === true;
+    return {
+        assertion_id: definition.id,
+        measurement_id: definition.measurement_id,
+        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",
+        enforcement: definition.enforcement,
+        negative_control_proven: proveNegativeControl(definition),
+        cost: measurement.cost,
+        contributors: measurement.contributors,
+    };
+}
+/** 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`);
+    if (!gateDefinition.triggers.includes(options.trigger)) {
+        throw new TypeError(`assurance gate ${gateId} does not declare trigger ${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);
+        let scopedContext = context;
+        if (assertionDefinition.scope.kind === "active") {
+            const terminalStatuses = new Set(context.terminal_statuses ?? ["closed", "canceled"]);
+            scopedContext = {
+                ...context,
+                items: context.items.filter((item) => !terminalStatuses.has(item.status)),
+            };
+        }
+        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 contributorIds = new Set(scope.contributors);
+            scopedContext = {
+                ...context,
+                items: context.items.filter((item) => contributorIds.has(item.id)),
+            };
+        }
+        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 });
+    });
+    const blocking = assertions.some((entry) => entry.verdict === "fail" && entry.enforcement === "block");
+    const warning = assertions.some((entry) => entry.verdict === "fail" && entry.enforcement === "warn");
+    return {
+        gate_id: gateDefinition.id,
+        tree_id: context.tree_id,
+        trigger: options.trigger,
+        dry_run: options.dry_run === true,
+        evaluated_at: new Date().toISOString(),
+        verdict: blocking ? "block" : warning ? "warn" : "pass",
+        exit_code: blocking ? 1 : 0,
+        assertions,
+        cost: sumCosts(assertions.map((entry) => entry.cost), Math.max(0, ...assertions.map((entry) => entry.cost.duration_ms))),
+    };
+}
+function assurancePath(pmRoot) {
+    return path.join(pmRoot, "assurance.json");
+}
+async function readDocument(pmRoot) {
+    const raw = await readFileIfExists(assurancePath(pmRoot));
+    if (raw === null)
+        return createEmptyAssuranceDocument();
+    return parseAssuranceDocument(raw);
+}
+function parseAssuranceDocument(raw) {
+    try {
+        return validateAssuranceDocument(JSON.parse(raw));
+    }
+    catch (error) {
+        throw new PmCliError("The assurance registry is invalid. Repair or restore .agents/pm/assurance.json and retry.", EXIT_CODE.GENERIC_FAILURE, {
+            code: "assurance_registry_invalid",
+            reason: String(error),
+            nextSteps: [
+                "Restore a valid assurance.json from version control or repair its declaration references.",
+                "Run pm assurance list measurement after the repair.",
+            ],
+        });
+    }
+}
+function collectionFor(document, kind) {
+    if (kind === "measurement")
+        return document.measurements;
+    if (kind === "assertion")
+        return document.assertions;
+    return document.gates;
+}
+function validateForKind(kind, definition) {
+    if (kind === "measurement")
+        validateMeasurementDefinition(definition);
+    else if (kind === "assertion")
+        validateAssertionDefinition(definition);
+    else
+        validateGateDefinition(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[]" } };
+}
+/** Read one named declaration or fail loudly. */
+export async function getAssuranceDeclaration(pmRoot, kind, id) {
+    const found = collectionFor(await readDocument(pmRoot), kind).find((entry) => entry.id === id);
+    if (!found)
+        throw new TypeError(`assurance ${kind} ${id} not found`);
+    return structuredClone(found);
+}
+/** 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 mutation = await mutateWorkspaceJsonWithHistory({
+        pmRoot,
+        filePath: assurancePath(pmRoot),
+        op: `assurance:${kind}:put`,
+        author,
+        message: options.message,
+        lockTtlSeconds: LOCK_TTL_SECONDS,
+        lockWaitMs: LOCK_WAIT_MS,
+        mutate: (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`);
+                }
+            }
+            if (index < 0)
+                collection.push(structuredClone(definition));
+            else
+                collection[index] = structuredClone(definition);
+            validateAssuranceDocument(document);
+            return {
+                raw: `${JSON.stringify(document, null, 2)}\n`,
+                result: { changed: true, action, kind, id: definition.id },
+            };
+        },
+    });
+    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 mutation = await mutateWorkspaceJsonWithHistory({
+        pmRoot,
+        filePath: assurancePath(pmRoot),
+        op: `assurance:${kind}:remove`,
+        author,
+        message: options.message,
+        lockTtlSeconds: LOCK_TTL_SECONDS,
+        lockWaitMs: LOCK_WAIT_MS,
+        mutate: (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(", ")}`);
+                }
+            }
+            if (kind === "assertion" && document.gates.some((entry) => entry.assertion_ids.includes(id))) {
+                throw new TypeError(`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`);
+            collection.splice(index, 1);
+            validateAssuranceDocument(document);
+            return {
+                raw: `${JSON.stringify(document, null, 2)}\n`,
+                result: { changed: true, action: "removed", kind, id },
+            };
+        },
+    });
+    return { ...mutation.result, changed: mutation.changed };
+}
+/** Append one immutable gate verdict without changing registry state. */
+export async function recordAssuranceVerdict(pmRoot, verdict, options = {}) {
+    if (verdict.dry_run)
+        throw new TypeError("dry-run assurance verdicts are not persisted");
+    await appendWorkspaceAuditEvent({
+        pmRoot,
+        op: "assurance:gate:verdict",
+        author: resolveAuthor(options.author, "unknown"),
+        context: { assurance_verdict: verdict },
+        message: options.message ?? `Assurance gate ${verdict.gate_id} returned ${verdict.verdict}`,
+        lockTtlSeconds: LOCK_TTL_SECONDS,
+        lockWaitMs: LOCK_WAIT_MS,
+    });
+}
+/** Query durable assurance verdicts from the verified workspace stream. */
+export async function listAssuranceVerdicts(pmRoot, options = {}) {
+    const limit = options.limit ?? DEFAULT_VERDICT_LIMIT;
+    if (!Number.isInteger(limit) ||
+        limit < 1 ||
+        limit > MAX_ASSURANCE_VERDICT_LIMIT) {
+        throw new TypeError(`assurance verdict limit must be an integer from 1 through ${MAX_ASSURANCE_VERDICT_LIMIT}`);
+    }
+    const entries = await readHistoryEntries(getWorkspaceHistoryPath(pmRoot), WORKSPACE_HISTORY_ID);
+    return entries
+        .reverse()
+        .filter((entry) => entry.op === "assurance:gate:verdict")
+        .map((entry) => entry.context?.assurance_verdict)
+        .filter((value) => typeof value === "object" && value !== null && "gate_id" in value)
+        .filter((verdict) => options.gate_id === undefined || verdict.gate_id === options.gate_id)
+        .slice(0, limit);
+}
+//# sourceMappingURL=assurance.js.map
+//# debugId=2c6c336c-abaa-53f7-94ac-ba4d5ab7c76a