@unbrained/pm-cli 2026.8.9 → 2026.8.11

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

@@ -0,0 +1,432 @@
+/** Current serialized assurance registry format. */
+export declare const ASSURANCE_DOCUMENT_VERSION: 1;
+/** Supported lifecycle points that can evaluate a gate. */
+export declare const ASSURANCE_GATE_TRIGGERS: readonly ["pre-commit", "pre-push", "pre-merge", "ci", "pre-release", "post-release", "scheduled", "on-claim", "on-close"];
+/** Gate lifecycle trigger. */
+export type AssuranceGateTrigger = (typeof ASSURANCE_GATE_TRIGGERS)[number];
+/** Assertion enforcement strength. */
+export type AssuranceEnforcement = "block" | "warn" | "observe";
+/** Assertion lifetime after its owning work item becomes terminal. */
+export type AssuranceLifetime = "hold" | "retire";
+/** Numeric or labelled-set value produced by a measurement. */
+export type AssuranceValue = number | string[];
+/** Minimal dependency row used by built-in relationship measurements. */
+export interface AssuranceDependencyRecord {
+    /** Target item id. */
+    id: string;
+    /** Typed relationship kind. */
+    kind: string;
+}
+/** Minimal item projection consumed by built-in measurement sources. */
+export interface AssuranceItemRecord {
+    /** Stable item id. */
+    id: string;
+    /** Lifecycle status. */
+    status: string;
+    /** Item type. */
+    type: string;
+    /** Optional tags. */
+    tags?: string[];
+    /** Optional priority. */
+    priority?: string | number;
+    /** Typed relationships. */
+    dependencies?: AssuranceDependencyRecord[];
+    /** Linked files. */
+    files?: Array<Record<string, unknown>>;
+    /** Linked tests. */
+    tests?: Array<Record<string, unknown>>;
+    /** Linked docs. */
+    docs?: Array<Record<string, unknown>>;
+    /** Extension-owned metadata remains filterable. */
+    [key: string]: unknown;
+}
+/** Minimal immutable-history row consumed by history measurements. */
+export interface AssuranceHistoryRecord {
+    /** Mutation operation. */
+    op: string;
+    /** Mutation author. */
+    author: string;
+    /** Optional detected harness. */
+    agent_harness?: string;
+    /** Optional detected model. */
+    agent_model?: string;
+    /** Extensible history metadata. */
+    [key: string]: unknown;
+}
+/** Item-population measurement source. */
+export interface AssuranceItemsSource {
+    /** Source discriminant. */
+    kind: "items";
+    /** Allowed statuses. */
+    statuses?: string[];
+    /** Allowed item types. */
+    types?: string[];
+    /** Tags that must all be present. */
+    tags?: string[];
+    /** Optional metadata field. */
+    field?: string;
+    /** Required exact value for field. */
+    equals?: string | number | boolean | null;
+}
+/** Typed relationship-count source. */
+export interface AssuranceDependencyKindSource {
+    /** Source discriminant. */
+    kind: "dependency_kind";
+    /** Relationship kind to count. */
+    dependency_kind: string;
+}
+/** Graph-analytics source delegated to a host adapter. */
+export interface AssuranceGraphSource {
+    /** Source discriminant. */
+    kind: "graph";
+    /** Graph analytic to execute. */
+    operation: string;
+    /** Numeric or labelled-set field to select. */
+    field: string;
+    /** Optional analytic arguments. */
+    parameters?: Record<string, string | number | boolean>;
+}
+/** Validator source delegated to a host adapter. */
+export interface AssuranceValidateSource {
+    /** Source discriminant. */
+    kind: "validate";
+    /** Stable validator check id. */
+    check: string;
+    /** Numeric field within the check result. */
+    field: string;
+}
+/** Health-check source delegated to a host adapter. */
+export interface AssuranceHealthSource {
+    /** Source discriminant. */
+    kind: "health";
+    /** Stable health check id. */
+    check: string;
+    /** Numeric field within the check result. */
+    field: string;
+}
+/** Immutable-history population source. */
+export interface AssuranceHistorySource {
+    /** Source discriminant. */
+    kind: "history";
+    /** Optional operation filter. */
+    op?: string;
+    /** Optional author filter. */
+    author?: string;
+    /** Optional harness filter. */
+    harness?: string;
+    /** Optional model filter. */
+    model?: string;
+}
+/** Linked evidence population source. */
+export interface AssuranceLinksSource {
+    /** Source discriminant. */
+    kind: "links";
+    /** Evidence collection to inspect. */
+    link: "files" | "tests" | "docs";
+    /** Count items with or without at least one link. */
+    state: "present" | "missing";
+}
+/** Extension- or host-contributed measurement source. */
+export interface AssuranceProviderSource {
+    /** Source discriminant. */
+    kind: "provider";
+    /** Stable provider id. */
+    provider: string;
+    /** Provider-owned measurement key. */
+    key: string;
+    /** Provider-owned JSON-compatible parameters. */
+    parameters?: Record<string, string | number | boolean | null>;
+}
+/** Reference to another measurement inside a derived expression. */
+export interface AssuranceMeasurementReference {
+    /** Referenced measurement id. */
+    measurement: string;
+}
+/** Literal numeric term inside a derived expression. */
+export interface AssuranceLiteralExpression {
+    /** Literal number. */
+    literal: number;
+}
+/** Arithmetic expression over measurement references and literals. */
+export interface AssuranceArithmeticExpression {
+    /** Deterministic arithmetic operation. */
+    operator: "add" | "subtract" | "multiply" | "divide" | "min" | "max";
+    /** Ordered operands. */
+    operands: AssuranceDerivedExpression[];
+}
+/** Recursive derived-measurement expression. */
+export type AssuranceDerivedExpression = AssuranceMeasurementReference | AssuranceLiteralExpression | AssuranceArithmeticExpression;
+/** Derived arithmetic source. */
+export interface AssuranceDerivedSource {
+    /** Source discriminant. */
+    kind: "derived";
+    /** Arithmetic expression. */
+    expression: AssuranceDerivedExpression;
+}
+/** Complete measurement source vocabulary. */
+export type AssuranceMeasurementSource = AssuranceItemsSource | AssuranceDependencyKindSource | AssuranceGraphSource | AssuranceValidateSource | AssuranceHealthSource | AssuranceHistorySource | AssuranceLinksSource | AssuranceProviderSource | AssuranceDerivedSource;
+/** Persisted measurement declaration. */
+export interface AssuranceMeasurementDefinition {
+    /** Stable registry id. */
+    id: string;
+    /** Optional intent description. */
+    description?: string;
+    /** Measurement source. */
+    source: AssuranceMeasurementSource;
+    /** Maximum abstract compute units accepted for one evaluation. */
+    max_cost?: number;
+}
+/** Explicit population scope asserted by a bound. */
+export type AssuranceScope = {
+    kind: "all";
+} | {
+    kind: "active";
+} | {
+    /** Scope discriminant. */
+    kind: "filter";
+    /** Saved measurement whose population defines the scope. */
+    measurement_id: string;
+};
+/** One assertion negative-control case. */
+export interface AssuranceNegativeControlCase {
+    /** Synthetic observation. */
+    observed: AssuranceValue;
+    /** Expected comparator result. */
+    expected: "pass" | "fail";
+}
+/** Required negative-control suite proving a bound can both pass and fail. */
+export interface AssuranceNegativeControl {
+    /** Synthetic comparator cases. */
+    cases: AssuranceNegativeControlCase[];
+}
+/** Persisted assertion declaration. Exactly one polarity field is valid. */
+export interface AssuranceAssertionDefinition {
+    /** Stable registry id. */
+    id: string;
+    /** Registry key of the observation constrained by this guarantee. */
+    measurement_id: string;
+    /** pm item that owns this guarantee. */
+    owner_item_id: string;
+    /** Explicit asserted population scope. */
+    scope: AssuranceScope;
+    /** Maximum permitted value. */
+    ceiling?: number;
+    /** Minimum permitted value. */
+    floor?: number;
+    /** Exact permitted scalar or labelled set. */
+    equals?: AssuranceValue;
+    /** Require numeric zero. */
+    zero?: true;
+    /** Require no decrease from the numeric baseline. */
+    monotone_nondecreasing?: number;
+    /** Require no increase from the numeric baseline. */
+    monotone_nonincreasing?: number;
+    /** Require the observed labelled set to be a subset. */
+    subset_of?: string[];
+    /** Behavior after owner termination. */
+    lifetime?: AssuranceLifetime;
+    /** Required explanation when lifetime retires. */
+    retire_reason?: string;
+    /** Enforcement strength. */
+    enforcement: AssuranceEnforcement;
+    /** Required proof that the comparator distinguishes good and bad values. */
+    negative_control: AssuranceNegativeControl;
+    /** Decision item authorizing a loosening update. */
+    authorization_decision?: string;
+}
+/** Persisted gate declaration. */
+export interface AssuranceGateDefinition {
+    /** Stable registry id. */
+    id: string;
+    /** Assertion ids evaluated by this gate. */
+    assertion_ids: string[];
+    /** Lifecycle triggers allowed to run it. */
+    triggers: AssuranceGateTrigger[];
+    /** Optional description. */
+    description?: string;
+}
+/** Complete persisted assurance registry. */
+export interface AssuranceDocument {
+    /** Storage format version. */
+    version: typeof ASSURANCE_DOCUMENT_VERSION;
+    /** Measurement declarations. */
+    measurements: AssuranceMeasurementDefinition[];
+    /** Assertion declarations. */
+    assertions: AssuranceAssertionDefinition[];
+    /** Gate declarations. */
+    gates: AssuranceGateDefinition[];
+}
+/** Host adapter result for graph, validate, health, or provider sources. */
+export interface AssuranceExternalMeasurementResult {
+    /** Observed value. */
+    value: AssuranceValue;
+    /** Population denominator. */
+    population_size: number;
+    /** Abstract compute units charged by the adapter. */
+    cost: number;
+    /** Optional contributors that moved the value. */
+    contributors?: string[];
+}
+/** SDK evaluation inputs supplied by a host. */
+export interface AssuranceEvaluationContext {
+    /** Commit, tree, snapshot, or workspace identity being judged. */
+    tree_id: string;
+    /** Item rows for built-in sources. */
+    items: AssuranceItemRecord[];
+    /** Immutable history rows for built-in history sources. */
+    history: AssuranceHistoryRecord[];
+    /** Status ids that make an assertion owner terminal. */
+    terminal_statuses?: string[];
+    /** External source adapter. Implementations must enforce an appropriate timeout. */
+    external: (source: AssuranceGraphSource | AssuranceValidateSource | AssuranceHealthSource | AssuranceProviderSource) => Promise<AssuranceExternalMeasurementResult>;
+}
+/** Compute receipt for one measurement. */
+export interface AssuranceMeasurementCost {
+    /** Total abstract units. */
+    units: number;
+    /** Item rows scanned. */
+    items_scanned: number;
+    /** History rows scanned. */
+    history_entries: number;
+    /** External provider calls. */
+    provider_calls: number;
+    /** Wall-clock duration. */
+    duration_ms: number;
+}
+/** Evaluated measurement receipt. */
+export interface AssuranceMeasurementResult {
+    /** Measurement id. */
+    id: string;
+    /** Observed value. */
+    value: AssuranceValue;
+    /** Population denominator. */
+    population_size: number;
+    /** Compute receipt. */
+    cost: AssuranceMeasurementCost;
+    /** Optional contributors. */
+    contributors: string[];
+}
+/** Structured assertion bound. */
+export interface AssuranceBound {
+    /** Comparator applied to the observed value and declared bound. */
+    polarity: "ceiling" | "floor" | "equals" | "zero" | "monotone_nondecreasing" | "monotone_nonincreasing" | "subset_of";
+    /** Declared bound value. */
+    value: AssuranceValue;
+}
+/** One assertion row inside a gate verdict. */
+export interface AssuranceAssertionVerdict {
+    /** Stable guarantee key that produced this evaluation row. */
+    assertion_id: string;
+    /** Stable observation key used to obtain the evaluated value. */
+    measurement_id: string;
+    /** Explicit scope. */
+    scope: AssuranceScope;
+    /** Population denominator. */
+    population_size: number;
+    /** Numeric or labelled-set value captured for the judged population. */
+    observed: AssuranceValue;
+    /** Structured bound. */
+    bound: AssuranceBound;
+    /** Signed numeric distance when applicable. */
+    distance: number | null;
+    /** Assertion result. */
+    verdict: "pass" | "fail" | "retired";
+    /** Enforcement strength. */
+    enforcement: AssuranceEnforcement;
+    /** Whether negative controls proved the comparator. */
+    negative_control_proven: boolean;
+    /** Compute receipt. */
+    cost: AssuranceMeasurementCost;
+    /** Optional contributors. */
+    contributors: string[];
+}
+/** Complete gate verdict shared by every presentation and execution surface. */
+export interface AssuranceGateVerdict {
+    /** Stable lifecycle-policy key that produced this verdict. */
+    gate_id: string;
+    /** Judged tree identity. */
+    tree_id: string;
+    /** Evaluation trigger. */
+    trigger: AssuranceGateTrigger;
+    /** Whether history persistence was intentionally skipped. */
+    dry_run: boolean;
+    /** ISO timestamp. */
+    evaluated_at: string;
+    /** Overall result. */
+    verdict: "pass" | "warn" | "block";
+    /** Stable process exit code. */
+    exit_code: 0 | 1;
+    /** Per-assertion receipts. */
+    assertions: AssuranceAssertionVerdict[];
+    /** Aggregate compute receipt. */
+    cost: AssuranceMeasurementCost;
+}
+/** Mutation attribution accepted by registry and verdict writes. */
+export interface AssuranceMutationOptions {
+    /** Explicit author override; normal callers omit it for harness detection. */
+    author?: string;
+    /** Optional audited rationale. */
+    message?: string;
+    /** Decision item ids the caller has verified as authorization. */
+    authorized_decision_ids?: string[];
+}
+/** Declaration collection kind. */
+export type AssuranceDeclarationKind = "measurement" | "assertion" | "gate";
+/** Declaration union accepted by persistence helpers. */
+export type AssuranceDeclaration = AssuranceMeasurementDefinition | AssuranceAssertionDefinition | AssuranceGateDefinition;
+/** Registry mutation receipt. */
+export interface AssuranceMutationReceipt {
+    /** Whether serialized state changed. */
+    changed: boolean;
+    /** Mutation outcome. */
+    action: "created" | "updated" | "removed";
+    /** Declaration kind. */
+    kind: AssuranceDeclarationKind;
+    /** Declaration id. */
+    id: string;
+}
+/** Return true when an assertion update weakens scope, bound, lifetime, or enforcement. */
+export declare function assuranceAssertionUpdateIsLoosening(before: AssuranceAssertionDefinition, after: AssuranceAssertionDefinition): boolean;
+/** Validate and return one measurement declaration. */
+export declare function validateMeasurementDefinition(definition: AssuranceMeasurementDefinition): AssuranceMeasurementDefinition;
+/** Validate and return one assertion declaration. */
+export declare function validateAssertionDefinition(definition: AssuranceAssertionDefinition): AssuranceAssertionDefinition;
+/** Validate and return one gate declaration. */
+export declare function validateGateDefinition(definition: AssuranceGateDefinition): AssuranceGateDefinition;
+/** Validate registry references, uniqueness, and declaration-local contracts. */
+export declare function validateAssuranceDocument(document: AssuranceDocument): AssuranceDocument;
+/** Create an empty, valid assurance registry. */
+export declare function createEmptyAssuranceDocument(): AssuranceDocument;
+/** Evaluate one measurement with cycle detection and a complete cost receipt. */
+export declare function evaluateMeasurement(definition: AssuranceMeasurementDefinition, context: AssuranceEvaluationContext, definitions?: AssuranceMeasurementDefinition[]): Promise<AssuranceMeasurementResult>;
+/** Evaluate one assertion against a precomputed measurement receipt. */
+export declare function evaluateAssuranceAssertion(definition: AssuranceAssertionDefinition, measurement: AssuranceMeasurementResult, options?: {
+    owner_terminal?: boolean;
+}): AssuranceAssertionVerdict;
+/** Evaluate a named gate into one presentation-independent verdict document. */
+export declare function evaluateAssuranceGate(gateId: string, document: AssuranceDocument, context: AssuranceEvaluationContext, options: {
+    trigger: AssuranceGateTrigger; /** Skip persistence in the caller. */
+    dry_run?: boolean;
+}): Promise<AssuranceGateVerdict>;
+/** Read all declarations of one kind with a stable row selector receipt. */
+export declare function listAssuranceDeclarations(pmRoot: string, kind: AssuranceDeclarationKind): Promise<{
+    items: AssuranceDeclaration[];
+    count: number;
+    row_contract: {
+        row_keys: ["items"];
+        jq_selector: ".items[]";
+    };
+}>;
+/** Read one named declaration or fail loudly. */
+export declare function getAssuranceDeclaration(pmRoot: string, kind: AssuranceDeclarationKind, id: string): Promise<AssuranceDeclaration>;
+/** Create or update one declaration through audited singleton persistence. */
+export declare function putAssuranceDeclaration(pmRoot: string, kind: AssuranceDeclarationKind, definition: AssuranceDeclaration, options?: AssuranceMutationOptions): Promise<AssuranceMutationReceipt>;
+/** Remove an unreferenced declaration through audited singleton persistence. */
+export declare function removeAssuranceDeclaration(pmRoot: string, kind: AssuranceDeclarationKind, id: string, options?: AssuranceMutationOptions): Promise<AssuranceMutationReceipt>;
+/** Append one immutable gate verdict without changing registry state. */
+export declare function recordAssuranceVerdict(pmRoot: string, verdict: AssuranceGateVerdict, options?: AssuranceMutationOptions): Promise<void>;
+/** Query durable assurance verdicts from the verified workspace stream. */
+export declare function listAssuranceVerdicts(pmRoot: string, options?: {
+    /** Optional gate filter. */ gate_id?: string;
+    /** Maximum newest matching verdicts returned. */ limit?: number;
+}): Promise<AssuranceGateVerdict[]>;