@unbrained/pm-cli 2026.8.10 → 2026.8.12

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

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

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

@@ -0,0 +1,5 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="443beddb-37c9-5244-a157-e07624e4a6d2")}catch(e){}}();
+export {};
+//# sourceMappingURL=assurance-action-contracts.js.map
+//# debugId=443beddb-37c9-5244-a157-e07624e4a6d2

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

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

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

@@ -0,0 +1,200 @@
+
+!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]="d7b8bd03-cd67-5f3f-9ac9-74808a03c2c7")}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 { MAX_ASSURANCE_VERDICT_LIMIT } from "./assurance-limits.js";
+import { normalizeAssuranceMutation } from "./assurance-mutation-error.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. */
+export const ASSURANCE_ACTIONS = [
+    "list",
+    "show",
+    "put",
+    "remove",
+    "run",
+    "verdicts",
+];
+/** Assurance declaration kinds shared by every transport. */
+export const ASSURANCE_DECLARATION_KINDS = [
+    "measurement",
+    "assertion",
+    "gate",
+];
+function parseAction(value) {
+    if (ASSURANCE_ACTIONS.includes(value)) {
+        return value;
+    }
+    throw new PmCliError(`Unknown assurance action ${value}. Expected: ${ASSURANCE_ACTIONS.join(", ")}`, EXIT_CODE.USAGE);
+}
+function parseKind(value) {
+    if (value &&
+        ASSURANCE_DECLARATION_KINDS.includes(value)) {
+        return value;
+    }
+    throw new PmCliError(`Assurance declaration kind is required. Expected: ${ASSURANCE_DECLARATION_KINDS.join(", ")}`, EXIT_CODE.USAGE);
+}
+function parseDefinition(kind, value) {
+    let parsed = value;
+    if (typeof value === "string") {
+        if (!value.trim())
+            parsed = undefined;
+        else {
+            try {
+                parsed = JSON.parse(value);
+            }
+            catch (error) {
+                throw new PmCliError("assurance definition must be valid JSON", EXIT_CODE.USAGE, { reason: error instanceof Error ? error.message : "invalid_json" });
+            }
+        }
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new PmCliError("assurance put requires a JSON object definition", EXIT_CODE.USAGE);
+    }
+    if (kind === "measurement")
+        return parsed;
+    if (kind === "assertion")
+        return parsed;
+    return parsed;
+}
+async function readDocument(pmRoot) {
+    const [measurements, assertions, gates] = await Promise.all([
+        listAssuranceDeclarations(pmRoot, "measurement"),
+        listAssuranceDeclarations(pmRoot, "assertion"),
+        listAssuranceDeclarations(pmRoot, "gate"),
+    ]);
+    return {
+        version: 1,
+        measurements: measurements.items,
+        assertions: assertions.items,
+        gates: gates.items,
+    };
+}
+/** Apply the common id-only projection without weakening the full audit receipt. */
+function projectMutationReceipt(receipt, idOnly) {
+    return idOnly === true ? { id: receipt.id } : receipt;
+}
+async function authorizedDecisionIds(pmRoot, definition) {
+    const decisionId = definition.authorization_decision;
+    if (!decisionId)
+        return [];
+    const context = await createAssuranceWorkspaceContext(pmRoot, {
+        include_history: false,
+        resolve_tree: false,
+    });
+    const decision = context.items.find((item) => item.id === decisionId);
+    const terminalStatuses = new Set(context.terminal_statuses);
+    if (!decision ||
+        decision.type.toLowerCase() !== "decision" ||
+        !terminalStatuses.has(decision.status)) {
+        throw new PmCliError(`Assurance authorization ${decisionId} must name a terminal Decision item`, EXIT_CODE.USAGE);
+    }
+    return [decision.id];
+}
+/** Validate and execute the bounded durable-verdict listing transport. */
+async function runVerdictsAction(input, pmRoot) {
+    const limit = parseRuntimeInteger(input.limit, "assurance verdict limit");
+    if (limit !== undefined &&
+        (limit < 1 || limit > MAX_ASSURANCE_VERDICT_LIMIT)) {
+        throw new PmCliError(`assurance verdict limit must be an integer from 1 through ${MAX_ASSURANCE_VERDICT_LIMIT}`, EXIT_CODE.USAGE);
+    }
+    const items = await listAssuranceVerdicts(pmRoot, {
+        gate_id: input.id ?? input.gate,
+        limit,
+    });
+    return {
+        items,
+        count: items.length,
+        row_contract: { row_keys: ["items"], jq_selector: ".items[]" },
+    };
+}
+/** Execute one assurance request through the public assurance SDK primitives. */
+export async function runAssuranceAction(input, global = {}) {
+    const action = parseAction(input.action);
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    if (action === "verdicts") {
+        return runVerdictsAction(input, pmRoot);
+    }
+    if (action === "run") {
+        if (!input.id) {
+            throw new PmCliError("assurance run requires a gate id", EXIT_CODE.USAGE);
+        }
+        if (!input.trigger) {
+            throw new PmCliError("assurance run requires a trigger", EXIT_CODE.USAGE);
+        }
+        if (!ASSURANCE_GATE_TRIGGERS.includes(input.trigger)) {
+            throw new PmCliError(`Unknown assurance trigger ${input.trigger}. Expected: ${ASSURANCE_GATE_TRIGGERS.join(", ")}`, EXIT_CODE.USAGE);
+        }
+        const [document, workspaceContext] = await Promise.all([
+            readDocument(pmRoot),
+            createAssuranceWorkspaceContext(pmRoot, { tree_id: input.tree }),
+        ]);
+        const verdict = await evaluateAssuranceGate(input.id, document, workspaceContext, {
+            trigger: input.trigger,
+            dry_run: input.dry_run === true,
+        });
+        if (!verdict.dry_run) {
+            await recordAssuranceVerdict(pmRoot, verdict, {
+                author: input.author,
+                message: input.message,
+            });
+        }
+        return verdict;
+    }
+    const kind = parseKind(input.kind);
+    if (action === "list")
+        return listAssuranceDeclarations(pmRoot, kind);
+    if (!input.id) {
+        throw new PmCliError(`assurance ${action} requires an id`, EXIT_CODE.USAGE);
+    }
+    const id = input.id;
+    if (action === "show") {
+        return getAssuranceDeclaration(pmRoot, kind, id);
+    }
+    if (action === "remove") {
+        const receipt = await normalizeAssuranceMutation(() => removeAssuranceDeclaration(pmRoot, kind, id, { author: input.author, message: input.message }));
+        return projectMutationReceipt(receipt, input.idOnly);
+    }
+    const definition = parseDefinition(kind, input.definition);
+    if (definition.id !== id) {
+        throw new PmCliError(`Assurance definition id ${definition.id} does not match requested id ${id}`, EXIT_CODE.USAGE);
+    }
+    const mutationOptions = {
+        author: input.author,
+        message: input.message,
+        ...(kind === "assertion"
+            ? {
+                authorized_decision_ids: await authorizedDecisionIds(pmRoot, definition),
+            }
+            : {}),
+    };
+    const receipt = await normalizeAssuranceMutation(() => putAssuranceDeclaration(pmRoot, kind, definition, mutationOptions));
+    return projectMutationReceipt(receipt, input.idOnly);
+}
+/** Normalize a generic SDK or MCP argument envelope into one assurance request. */
+export function runAssuranceDispatch(args, options, global) {
+    const merged = { ...args, ...options };
+    return runAssuranceAction({
+        action: readRuntimeString(merged, "subcommand") ??
+            readRuntimeString(merged, "assuranceAction") ??
+            readRuntimeString(merged, "operation") ??
+            "",
+        kind: readRuntimeString(merged, "kind"),
+        id: readRuntimeString(merged, "id"),
+        definition: merged.definition,
+        trigger: readRuntimeString(merged, "trigger"),
+        tree: readRuntimeString(merged, "treeId") ??
+            readRuntimeString(merged, "tree"),
+        gate: readRuntimeString(merged, "gate"),
+        limit: parseRuntimeInteger(merged.limit, "assurance verdict limit"),
+        dry_run: merged.dryRun === true || merged.dry_run === true,
+        fullChangedFields: merged.fullChangedFields === true,
+        idOnly: merged.idOnly === true,
+        author: readRuntimeString(merged, "author"),
+        message: readRuntimeString(merged, "message"),
+    }, global);
+}
+//# sourceMappingURL=assurance-action.js.map
+//# debugId=d7b8bd03-cd67-5f3f-9ac9-74808a03c2c7

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

@@ -0,0 +1,7 @@
+/**
+ * @module sdk/governance/assurance-limits
+ *
+ * Shares bounded assurance transport limits without expanding the public SDK.
+ */
+/** Largest verdict-history page accepted by SDK and transport boundaries. */
+export declare const MAX_ASSURANCE_VERDICT_LIMIT = 1000;

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

@@ -0,0 +1,11 @@
+/**
+ * @module sdk/governance/assurance-limits
+ *
+ * Shares bounded assurance transport limits without expanding the public SDK.
+ */
+/** Largest verdict-history page accepted by SDK and transport boundaries. */
+
+!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]="b911b43d-d14d-5e4f-a35e-5020b1a84542")}catch(e){}}();
+export const MAX_ASSURANCE_VERDICT_LIMIT = 1_000;
+//# sourceMappingURL=assurance-limits.js.map
+//# debugId=b911b43d-d14d-5e4f-a35e-5020b1a84542

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

@@ -0,0 +1,7 @@
+/** Expected declaration-validation or mutation-policy refusal. */
+export declare class AssuranceMutationRefusalError extends TypeError {
+    /** Create one typed refusal while retaining TypeError compatibility for SDK callers. */
+    constructor(message: string);
+}
+/** 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

@@ -0,0 +1,35 @@
+/**
+ * @module sdk/assurance-mutation-error
+ *
+ * Distinguishes expected assurance mutation refusals from unexpected runtime
+ * 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]="255eee6e-f6bb-5fd2-8a73-545e672d205d")}catch(e){}}();
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+/** Expected declaration-validation or mutation-policy refusal. */
+export class AssuranceMutationRefusalError extends TypeError {
+    /** Create one typed refusal while retaining TypeError compatibility for SDK callers. */
+    constructor(message) {
+        super(message);
+        this.name = "AssuranceMutationRefusalError";
+    }
+}
+/** Normalize only expected assurance mutation refusals for CLI and MCP hosts. */
+export async function normalizeAssuranceMutation(operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (error instanceof AssuranceMutationRefusalError) {
+            throw new PmCliError(error.message, EXIT_CODE.USAGE, {
+                code: "invalid_argument_value",
+                reason: "assurance_mutation_refused",
+            });
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=assurance-mutation-error.js.map
+//# debugId=255eee6e-f6bb-5fd2-8a73-545e672d205d

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

@@ -0,0 +1,20 @@
+import type { AssuranceEvaluationContext, AssuranceExternalMeasurementResult, AssuranceProviderSource } from "./assurance.js";
+/** Resolver contributed by an embedding host or extension package. */
+export type AssuranceProviderResolver = (source: AssuranceProviderSource) => Promise<AssuranceExternalMeasurementResult>;
+/** Workspace binding options. */
+export interface CreateAssuranceWorkspaceContextOptions {
+    /** Explicit tree identity; otherwise the current Git commit is used. */
+    tree_id?: string;
+    /** Load immutable item history for history-backed measurements. */
+    include_history?: boolean;
+    /** Resolve a Git identity; item-only callers can skip this subprocess. */
+    resolve_tree?: boolean;
+    /** Provider resolvers keyed by stable provider id. */
+    providers?: Readonly<Record<string, AssuranceProviderResolver>>;
+}
+/**
+ * Build an assurance context from authoritative workspace data and public SDK
+ * operations. Graph, validate, and health selectors run through their existing
+ * SDK implementations, so presentation surfaces cannot acquire divergent rules.
+ */
+export declare function createAssuranceWorkspaceContext(pmRoot: string, options?: CreateAssuranceWorkspaceContextOptions): Promise<AssuranceEvaluationContext>;

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

@@ -0,0 +1,134 @@
+/**
+ * @module sdk/assurance-runtime
+ *
+ * Binds assurance evaluation to a real pm workspace while leaving declaration
+ * 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]="abb3946c-ec68-52af-8521-ae0389f31f54")}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, listAllItemMetadata, readHistoryEntries, readSettings, resolveItemTypeRegistry, resolveRuntimeStatusRegistry, } from "../runtime-primitives.js";
+const execFileAsync = promisify(execFile);
+const HISTORY_READ_CONCURRENCY = 16;
+function valueAtPath(input, field) {
+    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`);
+        }
+        current = current[segment];
+    }
+    if (typeof current === "number" && Number.isFinite(current))
+        return current;
+    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`);
+}
+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" || field === "ok"
+        ? check.ok
+            ? 0
+            : 1
+        : valueAtPath(check.details, field);
+    return { value, population_size: 1, cost: result.checks.length };
+}
+async function resolveTreeId(pmRoot, explicit) {
+    if (explicit?.trim())
+        return explicit.trim();
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD^{commit}"], {
+            cwd: pmRoot,
+            encoding: "utf8",
+            timeout: 5_000,
+            windowsHide: true,
+        });
+        return stdout.trim();
+    }
+    catch {
+        return "working-copy";
+    }
+}
+async function readWorkspaceHistory(pmRoot, items) {
+    const streams = new Array(items.length);
+    let nextIndex = 0;
+    const workers = Array.from({ length: Math.min(HISTORY_READ_CONCURRENCY, items.length) }, async () => {
+        while (nextIndex < items.length) {
+            const index = nextIndex;
+            nextIndex += 1;
+            const item = items[index];
+            const entries = await readHistoryEntries(getHistoryPath(pmRoot, item.id), item.id);
+            streams[index] = entries.map((entry) => ({
+                op: entry.op,
+                author: entry.author,
+                agent_harness: entry.agent_harness,
+                agent_model: entry.agent_model,
+            }));
+        }
+    });
+    await Promise.all(workers);
+    return streams.flat();
+}
+/**
+ * Build an assurance context from authoritative workspace data and public SDK
+ * operations. Graph, validate, and health selectors run through their existing
+ * SDK implementations, so presentation surfaces cannot acquire divergent rules.
+ */
+export async function createAssuranceWorkspaceContext(pmRoot, options = {}) {
+    const settings = await readSettings(pmRoot);
+    const typeRegistry = resolveItemTypeRegistry(settings);
+    const statusRegistry = resolveRuntimeStatusRegistry(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,
+        status: item.status,
+        type: item.type,
+    }));
+    const global = { path: pmRoot };
+    return {
+        tree_id: options.resolve_tree === false
+            ? (options.tree_id ?? "working-copy")
+            : await resolveTreeId(pmRoot, options.tree_id),
+        items,
+        history: options.include_history === false
+            ? []
+            : await readWorkspaceHistory(pmRoot, items),
+        terminal_statuses: [...statusRegistry.terminal_statuses],
+        external: async (source) => {
+            if (source.kind === "graph") {
+                const result = await runGraph(source.operation, undefined, undefined, { ...source.parameters, full: true }, global);
+                return {
+                    value: valueAtPath(result, source.field),
+                    population_size: items.length,
+                    cost: items.length,
+                };
+            }
+            if (source.kind === "validate") {
+                const result = await runValidate({ counts: true }, global);
+                return checkValue(result, source.check, source.field);
+            }
+            if (source.kind === "health") {
+                const result = await runHealth(global, { checkOnly: true, full: true });
+                return checkValue(result, source.check, source.field);
+            }
+            const provider = options.providers?.[source.provider];
+            if (!provider) {
+                throw new TypeError(`assurance provider ${source.provider} is not registered`);
+            }
+            return provider(source);
+        },
+    };
+}
+//# sourceMappingURL=assurance-runtime.js.map
+//# debugId=abb3946c-ec68-52af-8521-ae0389f31f54