@unbrained/pm-cli 2026.8.15 → 2026.8.17

package/dist/sdk/governance/defect-recurrence.d.ts

@@ -0,0 +1,242 @@
+import type { AssuranceItemRecord } from "./assurance.js";
+/** Stable defect escape taxonomy used by project policy and PM metadata. */
+export declare const DEFECT_ESCAPE_CLASSES: readonly ["production_defect", "nightly_regression", "scanner_finding", "review_caught_late"];
+/** Evidence dispositions accepted by the fail-closed defect gate. */
+export declare const DEFECT_GATE_EVIDENCE_DISPOSITIONS: readonly ["gate_added", "gate_strengthened", "explicit_waiver"];
+/** Defect escape classification. */
+export type DefectEscapeClass = (typeof DEFECT_ESCAPE_CLASSES)[number];
+/** Distinguishes a concrete assurance improvement from a reviewed exception. */
+export type DefectGateEvidenceDisposition = (typeof DEFECT_GATE_EVIDENCE_DISPOSITIONS)[number];
+/** Structured proof attached to a terminal defect item. */
+export interface DefectGateEvidence {
+    /** Whether a gate was added, strengthened, or explicitly waived. */
+    disposition: DefectGateEvidenceDisposition;
+    /** Stable gate identifier, except for an explicit waiver. */
+    gate_id?: string;
+    /** Runnable negative-control command that proves the gate can fail. */
+    negative_control?: string;
+    /** Local checks selected by the same recurrence policy as hosted checks. */
+    local_checks?: string[];
+    /** Hosted checks selected by the same recurrence policy as local checks. */
+    hosted_checks?: string[];
+    /** Accountable owner of the gate or waiver. */
+    owner: string;
+    /** Concrete reason for an explicit waiver. */
+    waiver_reason?: string;
+    /** ISO timestamp after which an explicit waiver is invalid. */
+    waiver_expires_at?: string;
+}
+/** Signals that associate a family with source changes or PM context. */
+export interface DefectRecurrenceTriggers {
+    /** Repository-relative glob patterns. */
+    file_patterns?: string[];
+    /** Package names or workspace package paths. */
+    package_names?: string[];
+    /** Canonical PM item ids. */
+    item_ids?: string[];
+    /** PM tags. */
+    tags?: string[];
+    /** Stable error-code contracts. */
+    error_codes?: string[];
+}
+/** Local and hosted checks selected together for one recurrence family. */
+export interface DefectRecurrenceChecks {
+    /** Fast checks suitable for local development. */
+    local: string[];
+    /** Hosted checks that add independent or environment-specific evidence. */
+    hosted: string[];
+}
+/** Budget that makes an assurance family measurable over time. */
+export interface DefectRecurrenceBudget {
+    /** Maximum accepted escaped-defect rate. */
+    max_escape_rate: number;
+    /** Maximum accepted false-positive rate. */
+    max_false_positive_rate: number;
+}
+/** Versioned recurrence policy for one historically observed defect family. */
+export interface DefectRecurrenceFamily {
+    /** Stable family identifier. */
+    id: string;
+    /** Monotonic family contract version. */
+    version: number;
+    /** Concise human-readable title. */
+    title: string;
+    /** PM item accountable for maintaining this family. */
+    owner_item_id: string;
+    /** Escape class represented by the historical examples. */
+    escape_class: DefectEscapeClass;
+    /** Signals that select this family. */
+    triggers: DefectRecurrenceTriggers;
+    /** Shared local and hosted assurance policy. */
+    checks: DefectRecurrenceChecks;
+    /** Input that must select this family during policy validation. */
+    negative_control: DefectChangeRiskInput;
+    /** Historical items that justify the family. */
+    historical_item_ids: string[];
+    /** Quantitative escape and false-positive budgets. */
+    budget: DefectRecurrenceBudget;
+}
+/** Repository recurrence policy serialized by a project or extension. */
+export interface DefectRecurrencePolicy {
+    /** Serialized policy format version. */
+    version: 1;
+    /** ISO instant after which terminal defects require structured evidence. */
+    evidence_epoch: string;
+    /** Versioned recurrence families. */
+    families: DefectRecurrenceFamily[];
+}
+/** Input used to explain assurance requirements for a proposed change. */
+export interface DefectChangeRiskInput {
+    /** Changed repository-relative files. */
+    files?: string[];
+    /** Changed package names or workspace package paths. */
+    package_names?: string[];
+    /** PM items in the change lineage. */
+    item_ids?: string[];
+    /** PM tags in the change lineage. */
+    tags?: string[];
+    /** Error-code contracts touched by the change. */
+    error_codes?: string[];
+}
+/** Options for a full or incremental recurrence-index build. */
+export interface BuildDefectRecurrenceIndexOptions {
+    /** Previous index whose unaffected item mappings can be reused. */
+    previous_index?: DefectRecurrenceIndex;
+    /** Item ids replaced by the supplied item projection. */
+    changed_item_ids?: string[];
+}
+/** Deterministic recurrence index shared by CLI, SDK, MCP, and CI. */
+export interface DefectRecurrenceIndex {
+    /** Index format version. */
+    version: 1;
+    /** Hash of the policy used to build the index. */
+    policy_fingerprint: string;
+    /** Hash of policy plus deterministic item-to-family contributions. */
+    index_fingerprint: string;
+    /** Stable family definitions. */
+    families: DefectRecurrenceFamily[];
+    /** Sparse PM item-to-family index. */
+    item_families: Record<string, string[]>;
+    /** Build-cost receipt. */
+    build: {
+        /** Items inspected during this build. */
+        items_scanned: number;
+        /** Unchanged item mappings reused from a previous index. */
+        items_reused: number;
+        /** Items with at least one recurrence family. */
+        items_indexed: number;
+    };
+}
+/** One explainable reason that selected an assurance family. */
+export interface DefectChangeRiskReason {
+    /** Signal category that matched. */
+    signal: "file" | "package" | "item" | "tag" | "error_code";
+    /** Submitted signal value. */
+    value: string;
+    /** Policy trigger or indexed item that matched. */
+    matched: string;
+}
+/** One selected recurrence family and its evidence requirements. */
+export interface DefectChangeRiskMatch {
+    /** Stable family identifier. */
+    family_id: string;
+    /** Family contract version. */
+    family_version: number;
+    /** Accountable PM item. */
+    owner_item_id: string;
+    /** Historical escape class. */
+    escape_class: DefectEscapeClass;
+    /** Exact selection reasons. */
+    reasons: DefectChangeRiskReason[];
+    /** Required local checks. */
+    local_checks: string[];
+    /** Required hosted checks. */
+    hosted_checks: string[];
+    /** Quantitative policy budget. */
+    budget: DefectRecurrenceBudget;
+}
+/** Pagination controls for bounded change-risk output. */
+export interface AnalyzeDefectChangeRiskOptions {
+    /** Opaque cursor returned by a previous report. */
+    cursor?: string;
+    /** Maximum family rows returned, from 1 through 100. */
+    limit?: number;
+}
+/** Serialized assurance-risk request shared by CLI, SDK, and MCP transports. */
+export interface DefectChangeRiskRequest {
+    /** Project- or package-owned recurrence policy. */
+    policy: DefectRecurrencePolicy;
+    /** Proposed source and PM-context changes. */
+    change: DefectChangeRiskInput;
+    /** Opaque cursor returned by a previous report. */
+    cursor?: string;
+    /** Maximum family rows returned, from 1 through 100. */
+    limit?: number;
+}
+/** Bounded and explainable change-risk report. */
+export interface DefectChangeRiskReport {
+    /** Whether at least one historical family was selected. */
+    risk_detected: boolean;
+    /** Stable recurrence-index identity. */
+    index_fingerprint: string;
+    /** Current page of selected families. */
+    items: DefectChangeRiskMatch[];
+    /** Total selected families before pagination. */
+    total: number;
+    /** Opaque continuation cursor when rows remain. */
+    next_cursor?: string;
+    /** Deduplicated local checks across every selected family. */
+    required_local_checks: string[];
+    /** Deduplicated hosted checks across every selected family. */
+    required_hosted_checks: string[];
+    /** Deterministic analysis-cost receipt. */
+    cost: {
+        /** Families evaluated. */
+        families_evaluated: number;
+        /** Submitted signals evaluated against the policy. */
+        signals_evaluated: number;
+        /** Selected families before pagination. */
+        families_selected: number;
+        /** Approximate JSON-token cost of the bounded response. */
+        estimated_output_tokens: number;
+    };
+    /** Stable collection selector for agent consumers. */
+    row_contract: {
+        row_keys: ["items"];
+        jq_selector: ".items[]";
+    };
+}
+/** One fail-closed defect-evidence finding. */
+export interface DefectGateEvidenceFinding {
+    /** PM item missing or carrying invalid evidence. */
+    item_id: string;
+    /** Stable machine-readable finding kind. */
+    kind: "missing_escape_class" | "invalid_escape_class" | "invalid_completion_timestamp" | "missing_gate_evidence" | "invalid_gate_evidence" | "expired_waiver";
+    /** Actionable explanation. */
+    detail: string;
+}
+/** Fail-closed governance report for terminal defects after the policy epoch. */
+export interface DefectGateEvidenceReport {
+    /** Whether every governed defect carried valid evidence. */
+    ok: boolean;
+    /** Terminal defect items governed by the epoch. */
+    governed_item_count: number;
+    /** Terminal defects carrying a recognized historical escape classification. */
+    classified_item_count: number;
+    /** Historical and epoch-governed counts by required escape class. */
+    class_counts: Record<DefectEscapeClass, number>;
+    /** Historical and epoch-governed counts by evidence disposition. */
+    evidence_disposition_counts: Record<DefectGateEvidenceDisposition, number>;
+    /** Stable sorted findings. */
+    findings: DefectGateEvidenceFinding[];
+}
+/** Compile deterministic policy and PM metadata into a sparse incremental index. */
+export declare function buildDefectRecurrenceIndex(policy: DefectRecurrencePolicy, items: readonly AssuranceItemRecord[], options?: BuildDefectRecurrenceIndexOptions): DefectRecurrenceIndex;
+/** Explain recurrence families and shared local/hosted checks for one change. */
+export declare function analyzeDefectChangeRisk(index: DefectRecurrenceIndex, input: DefectChangeRiskInput, options?: AnalyzeDefectChangeRiskOptions): DefectChangeRiskReport;
+/** Enforce structured escape classification and gate evidence on new terminal defects. */
+export declare function evaluateDefectGateEvidence(items: readonly AssuranceItemRecord[], policy: DefectRecurrencePolicy, terminalStatuses: readonly string[], now?: Date): DefectGateEvidenceReport;
+/** Parse an untrusted serialized policy without weakening runtime validation. */
+export declare function parseDefectRecurrencePolicy(value: unknown): DefectRecurrencePolicy;
+/** Parse an untrusted cross-transport change-risk request. */
+export declare function parseDefectChangeRiskRequest(value: unknown): DefectChangeRiskRequest;