@unbrained/pm-cli 2026.8.8 → 2026.8.10

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

@@ -4,10 +4,34 @@
  * Generated by scripts/generate-error-code-catalog.mjs. Do not edit manually.
  */
 
-!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]="8a086b83-e46b-5694-be66-9114b0d87e12")}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]="94952ea0-bfe7-5d64-9ac4-101c483b4c55")}catch(e){}}();
 import { definePmErrorCodeCatalog } from "./error-code-catalog.js";
 /** Exhaustive catalog generated from literal error guidance declarations. */
 export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
+    {
+        code: "acceptance_criteria_mutation_conflict",
+        meaning: "Acceptance criteria mutation conflict condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/lifecycle/update.ts"],
+        emitting_commands: ["update", "update-many"],
+        canonical_code: "acceptance_criteria_mutation_conflict",
+        aliases: [],
+    },
+    {
+        code: "acceptance_criteria_remove_unmatched",
+        meaning: "Acceptance criteria remove unmatched condition.",
+        stability: "provisional",
+        exit_code: 3,
+        class: "not_found",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/lifecycle/update-many.ts", "sdk/lifecycle/update.ts"],
+        emitting_commands: ["update", "update-many"],
+        canonical_code: "acceptance_criteria_remove_unmatched",
+        aliases: [],
+    },
     {
         code: "acceptance_criteria_semicolon_forbidden",
         meaning: "Acceptance criteria semicolon forbidden condition.",
@@ -308,6 +332,42 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         canonical_code: "conflicting_lifecycle_owner",
         aliases: [],
     },
+    {
+        code: "context_signal_store_invalid",
+        meaning: "Context signal store invalid condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/context-signal-store.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "context_signal_store_invalid",
+        aliases: [],
+    },
+    {
+        code: "context_signal_store_stale",
+        meaning: "Context signal store stale condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/context-signal-store.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "context_signal_store_stale",
+        aliases: [],
+    },
+    {
+        code: "context_signal_store_write_failed",
+        meaning: "Context signal store write failed condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/context-signal-store.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "context_signal_store_write_failed",
+        aliases: [],
+    },
     {
         code: "context_takes_no_item_argument",
         meaning: "Context takes no item argument condition.",
@@ -356,6 +416,18 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         canonical_code: "dependency_edge_not_allowed",
         aliases: [],
     },
+    {
+        code: "dependency_target_not_found",
+        meaning: "Dependency target not found condition.",
+        stability: "provisional",
+        exit_code: 3,
+        class: "not_found",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/dependency-flag-validation.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "dependency_target_not_found",
+        aliases: [],
+    },
     {
         code: "duplicate_command",
         meaning: "Duplicate command condition.",
@@ -1469,6 +1541,18 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         canonical_code: "merge_conflict_markers_detected",
         aliases: ["history_merge_conflict_markers_detected"],
     },
+    {
+        code: "merge_decisions_unreviewed",
+        meaning: "Merge decisions unreviewed condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/diagnostics/remediation.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "merge_decisions_unreviewed",
+        aliases: [],
+    },
     {
         code: "merge_git_config_unwritable",
         meaning: "Merge git config unwritable condition.",
@@ -1481,6 +1565,18 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         canonical_code: "merge_git_config_unwritable",
         aliases: [],
     },
+    {
+        code: "merge_reconcile_discards_require_acceptance",
+        meaning: "Merge reconcile discards require acceptance condition.",
+        stability: "provisional",
+        exit_code: 4,
+        class: "conflict",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/merge/reconcile.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "merge_reconcile_discards_require_acceptance",
+        aliases: [],
+    },
     {
         code: "merge_root_not_found",
         meaning: "Merge root not found condition.",
@@ -2587,6 +2683,18 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         canonical_code: "validate_lifecycle_stale_blockers",
         aliases: [],
     },
+    {
+        code: "validate_merge_decisions_unreviewed",
+        meaning: "Validate merge decisions unreviewed condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/diagnostics/remediation.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "validate_merge_decisions_unreviewed",
+        aliases: [],
+    },
     {
         code: "validate_merge_fence_drift",
         meaning: "Validate merge fence drift condition.",
@@ -3021,4 +3129,4 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
     },
 ]);
 //# sourceMappingURL=generated-error-code-catalog.js.map
-//# debugId=8a086b83-e46b-5694-be66-9114b0d87e12
+//# debugId=94952ea0-bfe7-5d64-9ac4-101c483b4c55

package/dist/sdk/governance/health.js

@@ -4,7 +4,7 @@
  * Implements the pm health command surface and its agent-facing runtime behavior.
  */
 
-!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]="4efa3db2-6be7-5650-b1c7-d80e125694aa")}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]="539b0cb4-5e20-51e2-a33e-1a43ca961f05")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
@@ -28,19 +28,20 @@ import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
 import { nowIso } from "../../core/shared/time.js";
 import { parseItemDocument } from "../../core/item/item-format.js";
 import { effectiveItemFormatVersion, scanItemFormatVersions, } from "../../core/item/item-format-version.js";
-import { listAllItemMetadata, listAllItemMetadataWithBody, } from "../../core/store/item-store.js";
+import { listAllItemMetadataLight, listAllItemMetadataWithBody, } from "../../core/store/item-store.js";
 import { PM_TELEMETRY_SOURCE_CONTEXT_VALUES, TELEMETRY_MAX_QUEUE_ENTRY_ATTEMPTS, TELEMETRY_SCHEMA_VERSION, } from "../../core/telemetry/runtime.js";
 import { getItemFormatFromPath, getSettingsPath, ITEM_FILE_EXTENSIONS, resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
 import { readSettingsWithMetadata } from "../../core/store/settings.js";
 import { buildRemediationMap } from "../../core/diagnostics/remediation.js";
 import { scanHistoryAuthorAttribution, } from "../author-attribution.js";
 import { readManagedExtensionState } from "../extension.js";
+import { scanProvenanceResolverHealth } from "./provenance-health.js";
 import { applyStoredExtensionMigrationState } from "../extension/migrations.js";
 import { buildCapabilityContractMetadata, buildRegistrationCollisionRemediation, collectUnknownCapabilityGuidance, } from "../extension/doctor.js";
 import { scanStaleInProgressItems, } from "./stale-work.js";
 import { scanTrackedRuntimeCache } from "./tracked-runtime-cache.js";
 import { auditMergeDriverConfiguration, findGitWorkspaceRoot, } from "../merge/install.js";
-import { listMergeReceipts } from "../merge/receipts.js";
+import { listMergeReceipts, partitionMergeReceipts, } from "../merge/receipts.js";
 const PM_TELEMETRY_SOURCE_CONTEXT_SET = new Set(PM_TELEMETRY_SOURCE_CONTEXT_VALUES);
 const STALE_VECTORIZATION_SUMMARY_LIMIT = 25;
 const BRIEF_HEALTH_DETAIL_LIMIT = 8;
@@ -58,6 +59,7 @@ function isAdvisoryHealthWarning(warning, requireMergeDrivers = false) {
     return (warning.startsWith("telemetry_") ||
         warning.startsWith("history_stream_over_compact_threshold:") ||
         warning.startsWith("stale_in_progress_items:") ||
+        warning.startsWith("provenance_resolver_zero_success:") ||
         (!requireMergeDrivers &&
             warning.startsWith("merge_driver_configuration_missing:")));
 }
@@ -318,7 +320,13 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
     const mergeDriverAudit = gitWorkspaceRoot === null
         ? null
         : await auditMergeDriverConfiguration(gitWorkspaceRoot);
-    const pendingMergeReceipts = gitWorkspaceRoot === null ? [] : await listMergeReceipts(gitWorkspaceRoot);
+    const pendingMergeReceipts = gitWorkspaceRoot === null
+        ? []
+        : await listMergeReceipts(gitWorkspaceRoot, {
+            includeLossless: true,
+            pmRoot,
+        });
+    const { pendingDecisions: pendingMergeDecisions, lossless: losslessMergeReceipts, } = partitionMergeReceipts(pendingMergeReceipts);
     const mergeDriverInstallationMissing = mergeDriverAudit?.status === "missing" &&
         mergeDriverAudit.missing_keys.length === 5 &&
         mergeDriverAudit.drifted_keys.length === 0;
@@ -343,8 +351,8 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
                 `merge_driver_configuration_${mergeDriverInstallationMissing ? "missing" : "drift"}:${mergeDriverAudit.missing_keys.length + mergeDriverAudit.drifted_keys.length}`,
             ]
             : []),
-        ...(pendingMergeReceipts.length > 0
-            ? [`merge_decisions_unreviewed:${pendingMergeReceipts.length}`]
+        ...(pendingMergeDecisions.length > 0
+            ? [`merge_decisions_unreviewed:${pendingMergeDecisions.length}`]
             : []),
     ];
     const normalizedWarnings = [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
@@ -369,7 +377,8 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
                         ? 0
                         : mergeDriverAudit.missing_keys.length +
                             mergeDriverAudit.drifted_keys.length,
-                    pending_merge_decisions: pendingMergeReceipts.length,
+                    pending_merge_decisions: pendingMergeDecisions.length,
+                    lossless_merge_receipts: losslessMergeReceipts.length,
                 },
                 item_unreadable: itemScan.unreadable,
                 item_conflict_markers: itemScan.conflictMarkers,
@@ -392,7 +401,10 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
                         required: requireMergeDrivers,
                     },
                 pending_merge_decision_items: [
-                    ...new Set(pendingMergeReceipts.map((receipt) => receipt.item_id)),
+                    ...new Set(pendingMergeDecisions.map((receipt) => receipt.item_id)),
+                ].sort((left, right) => left.localeCompare(right)),
+                lossless_merge_receipt_items: [
+                    ...new Set(losslessMergeReceipts.map((receipt) => receipt.item_id)),
                 ].sort((left, right) => left.localeCompare(right)),
             },
         },
@@ -1643,7 +1655,7 @@ function resolveHealthSkipPolicy(options) {
 }
 async function readHealthItems(params) {
     if (params.skipPolicy.skipDrift && params.skipPolicy.skipVectors) {
-        return listAllItemMetadata(params.pmRoot, params.settings.item_format, params.typeRegistry.type_to_folder, params.itemReadWarnings, params.settings.schema);
+        return listAllItemMetadataLight(params.pmRoot, params.settings.item_format, params.typeRegistry.type_to_folder, params.itemReadWarnings, params.settings.schema);
     }
     return listAllItemMetadataWithBody(params.pmRoot, params.settings.item_format, params.typeRegistry.type_to_folder, params.itemReadWarnings, params.settings.schema);
 }
@@ -1693,7 +1705,7 @@ const resolveUnknownAuthorEventCount = (authorAttribution) => authorAttribution.
 /** Preserve actionable-author semantics for current and legacy scan payloads. */
 const resolveActionableUnknownAuthorEventCount = (authorAttribution) => authorAttribution.actionable_unknown_event_count ??
     resolveUnknownAuthorEventCount(authorAttribution);
-function buildStorageHealthCheck(items, settings, historySummary, authorAttribution, staleInProgress) {
+function buildStorageHealthCheck(items, settings, historySummary, authorAttribution, staleInProgress, provenanceResolverOutcomes, provenanceInvalidValues) {
     const unknownAuthorEventCount = resolveUnknownAuthorEventCount(authorAttribution);
     const actionableUnknownAuthorEventCount = resolveActionableUnknownAuthorEventCount(authorAttribution);
     const hasAuthorEvents = unknownAuthorEventCount > 0;
@@ -1726,6 +1738,12 @@ function buildStorageHealthCheck(items, settings, historySummary, authorAttribut
             ...(hasStaleInProgressItems
                 ? { stale_in_progress: staleInProgress }
                 : {}),
+            ...(provenanceResolverOutcomes.length > 0
+                ? { provenance_resolver_outcomes: provenanceResolverOutcomes }
+                : {}),
+            ...(provenanceInvalidValues.length > 0
+                ? { provenance_invalid_values: provenanceInvalidValues }
+                : {}),
             ...(historySummary.max_entries !== null
                 ? {
                     compact_policy: {
@@ -1756,6 +1774,7 @@ function collectHealthWarnings(params) {
         ...params.historySummary.warnings,
         ...params.authorAttributionWarnings,
         ...params.staleInProgressWarnings,
+        ...params.provenanceWarnings,
         ...params.locksCheck.warnings,
         ...params.integrityCheck.warnings,
         ...params.historyDriftCheck.warnings,
@@ -1779,6 +1798,7 @@ function buildHealthRemediationSources(params) {
             ...params.historySummary.over_threshold.map((id) => `history_stream_over_compact_threshold:${id}`),
             ...params.authorAttributionWarnings,
             ...params.staleInProgressWarnings,
+            ...params.provenanceWarnings,
         ],
         locks: params.locksCheck.warnings,
         integrity: params.integrityCheck.warnings,
@@ -1865,6 +1885,10 @@ export async function runHealth(global, options = {}) {
         in_progress_status: settings.schema.workflow.in_progress_status,
         threshold_hours: settings.mutation_guard.stale_in_progress_hours,
     }));
+    const provenanceResolverHealth = await scanProvenanceResolverHealth(pmRoot);
+    const provenanceResolverOutcomes = provenanceResolverHealth.outcomes;
+    const provenanceInvalidValues = provenanceResolverHealth.invalid_values;
+    const provenanceWarnings = provenanceResolverHealth.warnings;
     const locksCheck = await buildLocksCheck(pmRoot);
     const integrityCheck = skipPolicy.skipIntegrity
         ? buildSkippedHealthCheck("integrity")
@@ -1881,7 +1905,7 @@ export async function runHealth(global, options = {}) {
         buildSettingsValuesHealthCheck(settingWarnings),
         telemetryCheck.check,
         extensionCheck.check,
-        buildStorageHealthCheck(items, settings, historySummary, authorAttribution, staleInProgress.scan),
+        buildStorageHealthCheck(items, settings, historySummary, authorAttribution, staleInProgress.scan, provenanceResolverOutcomes, provenanceInvalidValues),
         locksCheck.check,
         integrityCheck.check,
         historyDriftCheck.check,
@@ -1898,6 +1922,7 @@ export async function runHealth(global, options = {}) {
         historySummary,
         authorAttributionWarnings,
         staleInProgressWarnings: staleInProgress.warnings,
+        provenanceWarnings,
         locksCheck,
         integrityCheck,
         historyDriftCheck,
@@ -1914,6 +1939,7 @@ export async function runHealth(global, options = {}) {
             historySummary,
             authorAttributionWarnings,
             staleInProgressWarnings: staleInProgress.warnings,
+            provenanceWarnings,
             locksCheck,
             integrityCheck,
             historyDriftCheck,
@@ -1964,4 +1990,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=4efa3db2-6be7-5650-b1c7-d80e125694aa
+//# debugId=539b0cb4-5e20-51e2-a33e-1a43ca961f05

package/dist/sdk/governance/provenance-health.d.ts

@@ -0,0 +1,39 @@
+/** Aggregated resolver attempts for one harness provenance dimension. */
+export interface ProvenanceResolverHealthOutcome {
+    /** Detected harness namespace. */
+    harness: string;
+    /** Provenance dimension resolved by the bounded resolver. */
+    dimension: string;
+    /** Built-in resolver name. */
+    resolver: string;
+    /** Events on which the resolver was actually attempted. */
+    attempts: number;
+    /** Attempted events that produced a bounded value. */
+    successes: number;
+}
+/** Aggregate for legacy provenance values that violate the bounded domain. */
+export interface ProvenanceValueHealthFinding {
+    /** Detected harness namespace. */
+    harness: string;
+    /** Provenance dimension containing the invalid value. */
+    dimension: string;
+    /** Privacy-safe invalid-value class. */
+    kind: "boolean" | "single_digit";
+    /** Events containing this invalid value class. */
+    count: number;
+}
+/** Bounded provenance health result suitable for `pm health` adapters. */
+export interface ProvenanceResolverHealthScan {
+    /** Stable resolver outcome aggregates. */
+    outcomes: ProvenanceResolverHealthOutcome[];
+    /** Aggregated invalid legacy values without retaining the values themselves. */
+    invalid_values: ProvenanceValueHealthFinding[];
+    /** Advisory warnings for attempted resolvers with no success. */
+    warnings: string[];
+    /** Number of nonblank history events inspected. */
+    events_read: number;
+    /** Whether an event or byte ceiling omitted history input. */
+    truncated: boolean;
+}
+/** Scan immutable history without failing over malformed streams owned by integrity checks. */
+export declare function scanProvenanceResolverHealth(pmRoot: string, eventLimit?: number): Promise<ProvenanceResolverHealthScan>;

package/dist/sdk/governance/provenance-health.js

@@ -0,0 +1,185 @@
+/**
+ * @module sdk/governance/provenance-health
+ *
+ * Reads bounded, privacy-safe provenance resolver outcomes for health checks.
+ */
+
+!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]="60154e1b-8348-5b6b-badf-e76bba43bef8")}catch(e){}}();
+import fs from "node:fs/promises";
+import path from "node:path";
+const DEFAULT_PROVENANCE_HISTORY_BYTE_LIMIT = 8_388_608;
+const ATTEMPTED_PROVENANCE_OUTCOME_STATUSES = new Set(["resolved", "failed"]);
+const INVALID_PROVENANCE_VALUE_CLASSIFIERS = [
+    {
+        kind: "boolean",
+        matches: (value) => typeof value === "boolean" ||
+            (typeof value === "string" && /^(?:true|false)$/iu.test(value.trim())),
+    },
+    {
+        kind: "single_digit",
+        matches: (value) => (typeof value === "number" &&
+            Number.isInteger(value) &&
+            value >= 0 &&
+            value <= 9) ||
+            (typeof value === "string" && /^\d$/u.test(value.trim())),
+    },
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function listHistoryFiles(pmRoot) {
+    try {
+        return (await fs.readdir(path.join(pmRoot, "history")))
+            .filter((file) => file.endsWith(".jsonl"))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+async function readHistoryFile(pmRoot, file, byteLimit) {
+    let handle;
+    try {
+        handle = await fs.open(path.join(pmRoot, "history", file), "r");
+        const size = (await handle.stat()).size;
+        const length = Math.min(size, Math.max(0, byteLimit));
+        const buffer = Buffer.alloc(length);
+        const { bytesRead } = await handle.read(buffer, 0, length, 0);
+        const decoded = buffer.subarray(0, bytesRead).toString("utf8");
+        const complete = bytesRead >= size;
+        const finalNewline = decoded.lastIndexOf("\n");
+        let content = decoded;
+        if (!complete) {
+            content = finalNewline === -1 ? "" : decoded.slice(0, finalNewline + 1);
+        }
+        return {
+            content,
+            bytesRead,
+            complete,
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+function parseHistoryEntry(line) {
+    try {
+        const value = JSON.parse(line);
+        return isRecord(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function collectResolverOutcomes(entry, aggregates, invalidValues) {
+    const harness = typeof entry.agent_harness === "string" ? entry.agent_harness : undefined;
+    if (harness === undefined)
+        return;
+    const provenance = isRecord(entry.agent_provenance)
+        ? entry.agent_provenance
+        : {};
+    Object.entries(provenance).forEach(([dimension, observation]) => {
+        if (!isRecord(observation))
+            return;
+        const kind = INVALID_PROVENANCE_VALUE_CLASSIFIERS.find((classifier) => classifier.matches(observation.value))?.kind;
+        if (!kind)
+            return;
+        const key = `${harness}\0${dimension}\0${kind}`;
+        const aggregate = invalidValues.get(key) ?? {
+            harness,
+            dimension,
+            kind,
+            count: 0,
+        };
+        aggregate.count += 1;
+        invalidValues.set(key, aggregate);
+    });
+    if (!isRecord(entry.context))
+        return;
+    const outcomes = entry.context.agent_provenance_outcomes;
+    if (!isRecord(outcomes))
+        return;
+    Object.entries(outcomes).forEach(([dimension, rawOutcome]) => {
+        if (!isRecord(rawOutcome) || typeof rawOutcome.resolver !== "string") {
+            return;
+        }
+        if (!ATTEMPTED_PROVENANCE_OUTCOME_STATUSES.has(String(rawOutcome.status))) {
+            return;
+        }
+        const key = `${harness}\0${dimension}\0${rawOutcome.resolver}`;
+        const aggregate = aggregates.get(key) ?? {
+            harness,
+            dimension,
+            resolver: rawOutcome.resolver,
+            attempts: 0,
+            successes: 0,
+        };
+        aggregate.attempts += 1;
+        if (rawOutcome.status === "resolved")
+            aggregate.successes += 1;
+        aggregates.set(key, aggregate);
+    });
+}
+function collectHistoryContent(content, aggregates, invalidValues, eventLimit, initialEventsRead) {
+    let eventsRead = initialEventsRead;
+    for (const line of content.split("\n")) {
+        if (line.trim().length === 0)
+            continue;
+        if (eventsRead >= eventLimit)
+            return { eventsRead, truncated: true };
+        eventsRead += 1;
+        const entry = parseHistoryEntry(line);
+        if (entry)
+            collectResolverOutcomes(entry, aggregates, invalidValues);
+    }
+    return { eventsRead, truncated: false };
+}
+/** Scan immutable history without failing over malformed streams owned by integrity checks. */
+export async function scanProvenanceResolverHealth(pmRoot, eventLimit = 10_000) {
+    const aggregates = new Map();
+    const invalidValues = new Map();
+    let eventsRead = 0;
+    let bytesRead = 0;
+    let truncated = false;
+    for (const file of await listHistoryFiles(pmRoot)) {
+        const history = await readHistoryFile(pmRoot, file, Math.max(0, DEFAULT_PROVENANCE_HISTORY_BYTE_LIMIT - bytesRead));
+        if (history === null)
+            continue;
+        bytesRead += history.bytesRead;
+        const collected = collectHistoryContent(history.content, aggregates, invalidValues, eventLimit, eventsRead);
+        eventsRead = collected.eventsRead;
+        if (collected.truncated) {
+            truncated = true;
+            break;
+        }
+        if (!history.complete) {
+            truncated = true;
+            break;
+        }
+    }
+    const outcomes = [...aggregates.values()].sort((left, right) => left.harness.localeCompare(right.harness) ||
+        left.dimension.localeCompare(right.dimension) ||
+        left.resolver.localeCompare(right.resolver));
+    const invalidValueFindings = [...invalidValues.values()].sort((left, right) => left.harness.localeCompare(right.harness) ||
+        left.dimension.localeCompare(right.dimension) ||
+        left.kind.localeCompare(right.kind));
+    return {
+        outcomes,
+        invalid_values: invalidValueFindings,
+        warnings: truncated
+            ? []
+            : [
+                ...outcomes
+                    .filter((outcome) => outcome.attempts > 0 && outcome.successes === 0)
+                    .map((outcome) => `provenance_resolver_zero_success:${outcome.harness}:${outcome.dimension}:${outcome.resolver}:${String(outcome.attempts)}`),
+                ...invalidValueFindings.map((finding) => `provenance_value_domain_invalid:${finding.harness}:${finding.dimension}:${finding.kind}:${String(finding.count)}`),
+            ],
+        events_read: eventsRead,
+        truncated,
+    };
+}
+//# sourceMappingURL=provenance-health.js.map
+//# debugId=60154e1b-8348-5b6b-badf-e76bba43bef8

package/dist/sdk/governance/validate-item-reader.d.ts

@@ -0,0 +1,13 @@
+import type { ItemMetadata, PmSettings } from "../../types/index.js";
+/** Item projection accepted by validate checks; body is read only for strict drift verification. */
+export type ValidateItem = ItemMetadata & {
+    body: string;
+};
+/** Load collections for normal checks and add bodies only when history hashes must be verified. */
+export declare function readValidateItems(params: {
+    includeBody: boolean;
+    pmRoot: string;
+    settings: PmSettings;
+    typeToFolder: Record<string, string>;
+    warnings: string[];
+}): Promise<ValidateItem[]>;

package/dist/sdk/governance/validate-item-reader.js

@@ -0,0 +1,18 @@
+/**
+ * @module sdk/governance/validate-item-reader
+ *
+ * Selects the least expensive authoritative item projection required by a
+ * validation run.
+ */
+
+!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]="896ffe11-2cf1-5de0-8d07-5585d4f30c94")}catch(e){}}();
+import { listAllItemMetadata, listAllItemMetadataWithBody, } from "../../core/store/item-store.js";
+/** Load collections for normal checks and add bodies only when history hashes must be verified. */
+export async function readValidateItems(params) {
+    if (params.includeBody) {
+        return listAllItemMetadataWithBody(params.pmRoot, params.settings.item_format, params.typeToFolder, params.warnings, params.settings.schema);
+    }
+    return listAllItemMetadata(params.pmRoot, params.settings.item_format, params.typeToFolder, params.warnings, params.settings.schema);
+}
+//# sourceMappingURL=validate-item-reader.js.map
+//# debugId=896ffe11-2cf1-5de0-8d07-5585d4f30c94

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

@@ -1,17 +1,17 @@
 import { type RuntimeStatusRegistry } from "../../core/schema/runtime-schema.js";
 import type { GlobalOptions } from "../../core/shared/command-types.js";
-import { listAllItemMetadataWithBody } from "../../core/store/item-store.js";
 import { type CloseReasonBackfillRow, type EstimateBackfillRow, type StaleLinkPruneRow, type TerminalParentFixRow, type ValidateFixRecord } from "../../core/validate/fix-planning.js";
 import { type DuplicateIssueCode } from "../../core/governance/issue-codes.js";
 import { type MissingFieldOccurrence } from "../../core/validate/missing-by-type.js";
 import type { ValidateMetadataProfile, ValidateMetadataRequiredField } from "../../types/index.js";
 import { type OutputProjectionDeclaration } from "../output-projection.js";
 import { type RelationshipKindRegistry } from "../relationships.js";
+import { type ValidateItem } from "./validate-item-reader.js";
 type ValidateCheckName = "metadata" | "resolution" | "lifecycle" | "dependency_references" | "files" | "command_references" | "history_drift" | "format_version" | "storage_integrity";
 type ValidateStatus = "ok" | "warn" | "error";
 type ValidateDependencyCycleSeverity = "off" | "warn" | "error";
 type ValidateFileScanMode = "default" | "tracked-all" | "tracked-all-strict";
-type ItemWithBody = Awaited<ReturnType<typeof listAllItemMetadataWithBody>>[number];
+type ItemWithBody = ValidateItem;
 type OrphanedPathClassification = "docs_unowned" | "tests_unowned" | "source_unowned" | "unlinked_existing";
 declare const LIFECYCLE_PATTERN_FIELD_KEYS: readonly ["blocked_reason", "resolution", "actual_result"];
 type LifecyclePatternFieldKey = (typeof LIFECYCLE_PATTERN_FIELD_KEYS)[number];