@unbrained/pm-cli 2026.9.4 → 2026.9.6

package/dist/sdk/generated/generated-error-code-catalog-part-1.js

@@ -1,6 +1,6 @@
 /** Generated partition 1 of the exhaustive error-code catalog. */
 
-!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]="f9059953-1d3c-5c1c-b739-4ad6cc8815a3")}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]="35c194c8-a164-5c90-9baa-9f2fc25c9bfb")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_1 = [
     {
         code: "acceptance_criteria_mutation_conflict",
@@ -690,8 +690,8 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         exit_code: 4,
         class: "conflict",
         recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["sdk/similarity.ts"],
-        emitting_commands: ["*"],
+        sources: ["sdk/query/duplicate-candidates.ts"],
+        emitting_commands: ["duplicate-candidates"],
         canonical_code: "duplicate_sweep_cost_limit",
         aliases: [],
     },
@@ -1163,6 +1163,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "history_author_acknowledge_target_unreadable",
         aliases: [],
     },
+    {
+        code: "history_baseline_unavailable",
+        meaning: "History baseline unavailable condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/history/projection.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "history_baseline_unavailable",
+        aliases: [],
+    },
     {
         code: "history_drift_chain_mismatch",
         meaning: "History drift chain mismatch condition.",
@@ -1235,6 +1247,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "history_drift_version_skew",
         aliases: ["validate_history_drift_version_skews"],
     },
+    {
+        code: "history_json_invalid",
+        meaning: "History json invalid condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/history/read.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "history_json_invalid",
+        aliases: [],
+    },
     {
         code: "history_merge_conflict_markers_detected",
         meaning: "History merge conflict markers detected condition.",
@@ -1247,6 +1271,30 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "merge_conflict_markers_detected",
         aliases: [],
     },
+    {
+        code: "history_replay_invalid",
+        meaning: "History replay invalid condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/history/projection.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "history_replay_invalid",
+        aliases: [],
+    },
+    {
+        code: "history_salvage_refused",
+        meaning: "History salvage refused condition.",
+        stability: "provisional",
+        exit_code: 4,
+        class: "conflict",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/history/salvage.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "history_salvage_refused",
+        aliases: [],
+    },
     {
         code: "history_stream_over_compact_threshold",
         meaning: "History stream over compact threshold condition.",
@@ -1295,6 +1343,30 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "history_unknown_author_events",
         aliases: ["validate_history_unknown_author_events"],
     },
+    {
+        code: "history_version_mapping_unavailable",
+        meaning: "History version mapping unavailable condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/history/version-address.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "history_version_mapping_unavailable",
+        aliases: [],
+    },
+    {
+        code: "history_version_pruned",
+        meaning: "History version pruned condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/history/projection.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "history_version_pruned",
+        aliases: [],
+    },
     {
         code: "host_environment_capacity_fault",
         meaning: "Host environment capacity fault condition.",
@@ -1302,7 +1374,7 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         exit_code: 1,
         class: "generic_failure",
         recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["sdk/environment/host-environment-errors.ts"],
+        sources: ["core/fs/host-environment-errors.ts"],
         emitting_commands: ["*"],
         canonical_code: "host_environment_capacity_fault",
         aliases: [],
@@ -1314,7 +1386,7 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         exit_code: 2,
         class: "usage",
         recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["sdk/environment/host-environment-errors.ts"],
+        sources: ["core/fs/host-environment-errors.ts"],
         emitting_commands: ["*"],
         canonical_code: "host_environment_operation_invalid",
         aliases: [],
@@ -1326,7 +1398,7 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         exit_code: 1,
         class: "generic_failure",
         recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["sdk/environment/host-environment-errors.ts"],
+        sources: ["core/fs/host-environment-errors.ts"],
         emitting_commands: ["*"],
         canonical_code: "host_environment_permission_fault",
         aliases: [],
@@ -1338,7 +1410,7 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         exit_code: 1,
         class: "generic_failure",
         recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["sdk/environment/host-environment-errors.ts"],
+        sources: ["core/fs/host-environment-errors.ts"],
         emitting_commands: ["*"],
         canonical_code: "host_environment_resource_fault",
         aliases: [],
@@ -1797,6 +1869,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "item_already_active",
         aliases: [],
     },
+    {
+        code: "item_document_encoding_invalid",
+        meaning: "Item document encoding invalid condition.",
+        stability: "provisional",
+        exit_code: 4,
+        class: "conflict",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/store/item-store.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "item_document_encoding_invalid",
+        aliases: [],
+    },
     {
         code: "item_document_invalid",
         meaning: "Item document invalid condition.",
@@ -1833,6 +1917,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "item_id_collision",
         aliases: [],
     },
+    {
+        code: "item_identity_reserved",
+        meaning: "Item identity reserved condition.",
+        stability: "provisional",
+        exit_code: 4,
+        class: "conflict",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/history/history.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "item_identity_reserved",
+        aliases: [],
+    },
     {
         code: "item_not_found",
         meaning: "Item not found condition.",
@@ -2124,54 +2220,6 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "merge_reconcile_receipt_evidence_untrusted",
         aliases: [],
     },
-    {
-        code: "merge_root_not_found",
-        meaning: "Merge root not found condition.",
-        stability: "stable",
-        exit_code: 3,
-        class: "not_found",
-        recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["sdk/merge/install.ts"],
-        emitting_commands: ["*"],
-        canonical_code: "merge_root_not_found",
-        aliases: [],
-    },
-    {
-        code: "missing_allowed_values",
-        meaning: "Missing allowed values condition.",
-        stability: "provisional",
-        exit_code: 1,
-        class: "generic_failure",
-        recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["sdk/agent/refusal-closure.ts"],
-        emitting_commands: ["*"],
-        canonical_code: "missing_allowed_values",
-        aliases: [],
-    },
-    {
-        code: "missing_budget",
-        meaning: "Missing budget condition.",
-        stability: "provisional",
-        exit_code: 1,
-        class: "generic_failure",
-        recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["sdk/cli-contracts/flag-lexicon-contracts.ts"],
-        emitting_commands: ["*"],
-        canonical_code: "missing_budget",
-        aliases: [],
-    },
-    {
-        code: "missing_cli_flag",
-        meaning: "Missing cli flag condition.",
-        stability: "provisional",
-        exit_code: 1,
-        class: "generic_failure",
-        recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["sdk/cli-contracts/tool-option-contracts.ts"],
-        emitting_commands: ["*"],
-        canonical_code: "missing_cli_flag",
-        aliases: [],
-    },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-1.js.map
-//# debugId=f9059953-1d3c-5c1c-b739-4ad6cc8815a3
+//# debugId=35c194c8-a164-5c90-9baa-9f2fc25c9bfb

package/dist/sdk/generated/generated-error-code-catalog-part-2.js

@@ -1,7 +1,55 @@
 /** Generated partition 2 of the exhaustive error-code catalog. */
 
-!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]="f1a77960-6191-5e11-9622-4250be7b0e89")}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]="aa8f034d-d4b6-595b-af76-f7203d062971")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_2 = [
+    {
+        code: "merge_root_not_found",
+        meaning: "Merge root not found condition.",
+        stability: "stable",
+        exit_code: 3,
+        class: "not_found",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/merge/install.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "merge_root_not_found",
+        aliases: [],
+    },
+    {
+        code: "missing_allowed_values",
+        meaning: "Missing allowed values condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/agent/refusal-closure.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "missing_allowed_values",
+        aliases: [],
+    },
+    {
+        code: "missing_budget",
+        meaning: "Missing budget condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/cli-contracts/flag-lexicon-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "missing_budget",
+        aliases: [],
+    },
+    {
+        code: "missing_cli_flag",
+        meaning: "Missing cli flag condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/cli-contracts/tool-option-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "missing_cli_flag",
+        aliases: [],
+    },
     {
         code: "missing_destination",
         meaning: "Missing destination condition.",
@@ -2186,4 +2234,4 @@ export const PM_ERROR_CODE_CATALOG_PART_2 = [
     },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-2.js.map
-//# debugId=f1a77960-6191-5e11-9622-4250be7b0e89
+//# debugId=aa8f034d-d4b6-595b-af76-f7203d062971

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

@@ -3,8 +3,9 @@ import { type AssuranceBundleMutationReceipt, type AssuranceDeclaration, type As
 import { type AssuranceDerivedProposal, type AssurancePreset, type AssurancePresetId } from "./assurance-presets.js";
 import { type CreateAssuranceWorkspaceContextOptions } from "./assurance-runtime.js";
 import { type DefectChangeRiskReport } from "./defect-recurrence.js";
+import { type DefectRecurrenceCoverageReport } from "./defect-recurrence-coverage.js";
 /** Assurance registry and evaluation verbs shared by every transport. */
-export declare const ASSURANCE_ACTIONS: readonly ["list", "show", "put", "remove", "run", "verdicts", "presets", "apply", "derive", "promote", "risk"];
+export declare const ASSURANCE_ACTIONS: readonly ["list", "show", "put", "remove", "run", "verdicts", "presets", "apply", "derive", "promote", "risk", "lineages"];
 /** Assurance declaration kinds shared by every transport. */
 export declare const ASSURANCE_DECLARATION_KINDS: readonly ["measurement", "assertion", "gate"];
 /** Assurance action verb. */
@@ -52,7 +53,7 @@ export interface AssuranceActionRuntimeOptions {
     workspace?: Omit<CreateAssuranceWorkspaceContextOptions, "tree_id" | "trigger">;
 }
 /** Result union returned by transport-neutral assurance execution. */
-export type AssuranceActionResult = AssuranceDeclaration | AssuranceMutationReceipt | AssuranceGateVerdict | AssuranceBundleMutationReceipt | AssurancePreset | DefectChangeRiskReport | {
+export type AssuranceActionResult = AssuranceDeclaration | AssuranceMutationReceipt | AssuranceGateVerdict | AssuranceBundleMutationReceipt | AssurancePreset | DefectChangeRiskReport | DefectRecurrenceCoverageReport | {
     items: AssuranceDerivedProposal[];
     count: number;
     applied?: AssuranceBundleMutationReceipt;

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

@@ -4,7 +4,7 @@
  * Normalizes the assurance action vocabulary once for CLI, SDK, and MCP hosts.
  */
 
-!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]="f66a964d-1352-5523-ab91-5177d0d93ce8")}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]="811330eb-207d-5e27-9786-72c1fba7d4c9")}catch(e){}}();
 import { createHash } from "node:crypto";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
@@ -18,6 +18,8 @@ import { resolvePmRoot } from "../runtime-primitives.js";
 import { parseRuntimeInteger, readRuntimeString } from "../runtime-input.js";
 import { analyzeDefectChangeRisk, buildDefectRecurrenceIndex, parseDefectChangeRiskRequest, } from "./defect-recurrence.js";
 import { defectRecurrenceItemSignals } from "./defect-recurrence-signals.js";
+import { readDefectRecurrenceRecord } from "./defect-recurrence-graph.js";
+import { analyzeDefectRecurrenceCoverage, parseDefectRecurrenceCoverageRequest, } from "./defect-recurrence-coverage.js";
 import { createUnknownSubcommandError } from "../agent/subcommand-recovery.js";
 let riskIndexCache;
 /** Assurance registry and evaluation verbs shared by every transport. */
@@ -33,6 +35,7 @@ export const ASSURANCE_ACTIONS = [
     "derive",
     "promote",
     "risk",
+    "lineages",
 ];
 /** Assurance declaration kinds shared by every transport. */
 export const ASSURANCE_DECLARATION_KINDS = [
@@ -245,9 +248,9 @@ function throwRiskUsageError(error) {
         : "assurance risk request is invalid", EXIT_CODE.USAGE);
 }
 /** Parse JSON or object risk definitions without wrapping workspace failures. */
-function parseRiskActionRequest(input) {
+function parseRecurrenceActionRequest(input) {
     if (input.limit !== undefined) {
-        throw new PmCliError("assurance risk does not accept --limit; set limit inside the risk definition", EXIT_CODE.USAGE);
+        throw new PmCliError(`assurance ${input.action} does not accept --limit; set limit inside the definition`, EXIT_CODE.USAGE);
     }
     let definition = input.definition;
     if (typeof definition === "string") {
@@ -255,11 +258,13 @@ function parseRiskActionRequest(input) {
             definition = JSON.parse(definition);
         }
         catch (error) {
-            throw new PmCliError("assurance risk definition must be valid JSON", EXIT_CODE.USAGE, { reason: error instanceof Error ? error.message : "invalid_json" });
+            throw new PmCliError(`assurance ${input.action} definition must be valid JSON`, EXIT_CODE.USAGE, { reason: error instanceof Error ? error.message : "invalid_json" });
         }
     }
     try {
-        return parseDefectChangeRiskRequest(definition);
+        return input.action === "lineages"
+            ? parseDefectRecurrenceCoverageRequest(definition)
+            : parseDefectChangeRiskRequest(definition);
     }
     catch (error) {
         return throwRiskUsageError(error);
@@ -285,7 +290,10 @@ function buildCachedRiskIndex(pmRoot, request, items) {
     const itemFingerprints = new Map(items.map((item) => [
         item.id,
         createHash("sha256")
-            .update(stableStringify(defectRecurrenceItemSignals(item)))
+            .update(stableStringify([
+            defectRecurrenceItemSignals(item),
+            readDefectRecurrenceRecord(item),
+        ]))
             .digest("hex"),
     ]));
     const reusable = cached?.policy_serialized === policySerialized ? cached : undefined;
@@ -304,13 +312,17 @@ function buildCachedRiskIndex(pmRoot, request, items) {
     return index;
 }
 /** Evaluate one serialized change-risk request against authoritative PM metadata. */
-async function runRiskAction(input, pmRoot) {
-    const request = parseRiskActionRequest(input);
+async function runRecurrenceAction(input, pmRoot) {
+    const request = parseRecurrenceActionRequest(input);
     const context = await createAssuranceWorkspaceContext(pmRoot, {
+        strict_read: true,
         include_history: false,
         resolve_tree: false,
     });
     try {
+        if (!("change" in request)) {
+            return analyzeDefectRecurrenceCoverage(request.policy, context.items, request);
+        }
         return analyzeDefectChangeRisk(buildCachedRiskIndex(pmRoot, request, context.items), request.change, { cursor: request.cursor, limit: request.limit });
     }
     catch (error) {
@@ -333,8 +345,8 @@ export async function runAssuranceAction(input, global = {}, runtime = {}) {
     if (action === "run") {
         return runGateAction(input, pmRoot, runtime);
     }
-    if (action === "risk") {
-        return runRiskAction(input, pmRoot);
+    if (["risk", "lineages"].includes(action)) {
+        return runRecurrenceAction(input, pmRoot);
     }
     const kind = parseKind(input.kind);
     if (action === "list")
@@ -397,4 +409,4 @@ export function runAssuranceDispatch(args, options, global) {
     }, global);
 }
 //# sourceMappingURL=assurance-action.js.map
-//# debugId=f66a964d-1352-5523-ab91-5177d0d93ce8
+//# debugId=811330eb-207d-5e27-9786-72c1fba7d4c9

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

@@ -3,6 +3,8 @@ import type { AssuranceEvaluationContext, AssuranceExternalMeasurementResult, As
 export type AssuranceProviderResolver = (source: AssuranceProviderSource) => Promise<AssuranceExternalMeasurementResult>;
 /** Workspace binding options. */
 export interface CreateAssuranceWorkspaceContextOptions {
+    /** Refuse incomplete item or directory reads through the public strict-list contract. */
+    strict_read?: boolean;
     /** Explicit tree identity; otherwise the current Git commit is used. */
     tree_id?: string;
     /** Load immutable item history for history-backed measurements. */

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

@@ -5,12 +5,13 @@
  * 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]="f9c26dab-b2fb-5ca0-b575-682b4b0bb830")}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]="cdf52e5c-86cf-5540-bc08-bfc274a1fdf9")}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 { runList } from "../query/list.js";
 import { AssuranceSourceResolutionError } from "./assurance-mutation-error.js";
 import { getActiveExtensionRegistrations, resolvePortableWorkspaceContext, } from "../../core/extensions/index.js";
 import { resolveRegisteredAssuranceMeasurementProvider } from "../../core/extensions/runtime-registrations.js";
@@ -161,7 +162,9 @@ 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 metadata = options.strict_read === true
+        ? (await runList(undefined, { status: "all", full: true, noTruncate: true, strictRead: true }, { path: pmRoot })).items
+        : await listAllItemMetadata(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema);
     const items = metadata.map((item) => ({
         ...item,
         id: item.id,
@@ -233,4 +236,4 @@ export async function createAssuranceWorkspaceContext(pmRoot, options = {}) {
     };
 }
 //# sourceMappingURL=assurance-runtime.js.map
-//# debugId=f9c26dab-b2fb-5ca0-b575-682b4b0bb830
+//# debugId=cdf52e5c-86cf-5540-bc08-bfc274a1fdf9

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

@@ -0,0 +1,93 @@
+import type { AssuranceItemRecord } from "./assurance.js";
+import { type DefectEscapeClass, type DefectRecurrencePolicy } from "./defect-recurrence.js";
+/** Bounded recurrence-evidence selection shared by SDK and transport hosts. */
+export interface DefectRecurrenceCoverageOptions {
+    /** Maximum item rows returned, from 1 through 100; defaults to 25. */
+    limit?: number;
+    /** Continuation tied to the policy, complete recurrence evidence, and filter. */
+    cursor?: string;
+    /** Return only unregistered or missing items; totals always describe the full graph. */
+    uncoveredOnly?: boolean;
+}
+/** Serialized request for the shared assurance lineages action. */
+export interface DefectRecurrenceCoverageRequest extends DefectRecurrenceCoverageOptions {
+    /** Project- or package-owned versioned family policy. */
+    policy: DefectRecurrencePolicy;
+}
+/** Validate lineage-policy and paging input at the untrusted transport boundary. */
+export declare function parseDefectRecurrenceCoverageRequest(value: unknown): DefectRecurrenceCoverageRequest;
+/** One registered, unregistered, or missing member of a recorded recurrence lineage. */
+export interface DefectRecurrenceCoverageRow {
+    /** Recorded item id or missing local reference. */
+    item_id: string;
+    /** Current component identity, derived from its lexically first item id. */
+    lineage_id: string;
+    /** Full component size, independent of the returned page. */
+    lineage_item_count: number;
+    /** Explicitly registered families covering this component. */
+    family_ids: string[];
+    /** Whether the local item exists in the supplied authoritative corpus. */
+    present: boolean;
+    /** Stable named finding when registration or the target record is absent. */
+    finding?: "unregistered_recurrence_item" | "missing_recurrence_item";
+}
+/** Complete population counts and bounded recurrence-policy evidence. */
+export interface DefectRecurrenceCoverageReport {
+    /** False if any recorded recurrence member is unregistered or missing. */
+    ok: boolean;
+    /** Identity of policy, recurrence evidence, and selected filter. */
+    fingerprint: string;
+    /** Current page; every row remains connected to its complete lineage. */
+    items: DefectRecurrenceCoverageRow[];
+    /** Selected row count before pagination. */
+    total: number;
+    /** Whether another page remains. */
+    has_more: boolean;
+    /** Cursor for the next page when has_more is true. */
+    next_cursor?: string;
+    /** Independent denominator including covered, uncovered, and absent local references. */
+    population: {
+        /** Explicit statement that the denominator is not the family registry. */
+        scope: "all_recorded_recurrence_items";
+        /** Unique participating local ids, including missing references. */
+        item_count: number;
+        /** Connected recurrence components. */
+        lineage_count: number;
+        /** Unique directed local recurrence edges. */
+        edge_count: number;
+        /** Existing members with an explicitly seeded registered family. */
+        covered_item_count: number;
+        /** Existing or missing members without a seeded registered family. */
+        uncovered_item_count: number;
+        /** Referenced ids missing from the authoritative item corpus. */
+        missing_item_count: number;
+        /** Members with an explicit recognized escape classification. */
+        classified_item_count: number;
+        /** Members without a recognized classification; never counted as non-escapes. */
+        unclassified_item_count: number;
+        /** Recorded classification counts over the entire population. */
+        class_counts: Record<DefectEscapeClass, number>;
+        /** Production-defect fraction only when every participant is classified; null otherwise. */
+        escape_rate: number | null;
+        /** Known production defects divided by the entire population, explicitly a lower bound. */
+        escape_rate_lower_bound: number | null;
+    };
+    /** Budgets on the policy's families cannot certify uncovered or unclassified members. */
+    budget_scope: "registered_families_only";
+    /** Declared performance accounting; connectivity never uses a depth cutoff. */
+    cost: {
+        /** Input item records inspected. */
+        items_scanned: number;
+        /** Recurrence edges traversed. */
+        edges_scanned: number;
+        /** Maximum emitted item rows. */
+        row_limit: number;
+    };
+    /** Stable machine selector. */
+    row_contract: {
+        row_keys: ["items"];
+        jq_selector: ".items[]";
+    };
+}
+/** Evaluate all local recurs_from lineages before applying any result-row limit. */
+export declare function analyzeDefectRecurrenceCoverage(policy: DefectRecurrencePolicy, items: readonly AssuranceItemRecord[], options?: DefectRecurrenceCoverageOptions): DefectRecurrenceCoverageReport;