@unbrained/pm-cli 2026.8.24 → 2026.8.26

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]="f7b3ff92-1fc7-55e9-aa76-af956714998f")}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]="652d1b49-f9d1-55a7-84b5-ff3cf57648ad")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
@@ -41,11 +41,13 @@ import { scanHistoryAuthorAttribution, } from "../author-attribution.js";
 import { readManagedExtensionState } from "../extension.js";
 import { scanProvenanceResolverHealth } from "./provenance-health.js";
 import { applyStoredExtensionMigrationState } from "../extension/migrations.js";
+import { inspectExtensionAuthorManifest } from "../extension/author-manifest.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, partitionMergeReceipts, } from "../merge/receipts.js";
+import { inspectMergeReceiptEvidence, partitionMergeReceipts, } from "../merge/receipts.js";
+import { runHistoryRepair } from "../history-repair.js";
 import { resolveWorkspaceRelationshipKindRegistry } from "../graph/assembly.js";
 import { analyzeHierarchyIntegrity, } from "../graph/hierarchy-integrity.js";
 const PM_TELEMETRY_SOURCE_CONTEXT_SET = new Set(PM_TELEMETRY_SOURCE_CONTEXT_VALUES);
@@ -333,6 +335,11 @@ function buildHierarchyIntegrityWarnings(analysis) {
             : `integrity_hierarchy_divergence:${finding.child_id}`),
     ];
 }
+function buildMergeReceiptEvidenceWarnings(invalidEvidenceCount) {
+    return invalidEvidenceCount === 0
+        ? []
+        : [`merge_receipt_evidence_invalid:${invalidEvidenceCount}`];
+}
 async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDrivers, items) {
     const itemScan = await scanItemIntegrity(pmRoot, typeToFolder, schema);
     const historyScan = await scanHistoryIntegrity(pmRoot);
@@ -344,12 +351,11 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
     const mergeDriverAudit = gitWorkspaceRoot === null
         ? null
         : await auditMergeDriverConfiguration(gitWorkspaceRoot);
-    const pendingMergeReceipts = gitWorkspaceRoot === null
-        ? []
-        : await listMergeReceipts(gitWorkspaceRoot, {
-            includeLossless: true,
-            pmRoot,
-        });
+    const mergeReceiptEvidence = await inspectMergeReceiptEvidence(gitWorkspaceRoot ?? pmRoot, {
+        includeLossless: true,
+        pmRoot,
+    });
+    const pendingMergeReceipts = mergeReceiptEvidence.receipts;
     const { pendingDecisions: pendingMergeDecisions, lossless: losslessMergeReceipts, } = partitionMergeReceipts(pendingMergeReceipts);
     const mergeDriverInstallationMissing = mergeDriverAudit?.status === "missing" &&
         mergeDriverAudit.missing_keys.length === 5 &&
@@ -379,6 +385,10 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
         ...(pendingMergeDecisions.length > 0
             ? [`merge_decisions_unreviewed:${pendingMergeDecisions.length}`]
             : []),
+        ...(losslessMergeReceipts.length > 0
+            ? [`merge_receipts_pending:${losslessMergeReceipts.length}`]
+            : []),
+        ...buildMergeReceiptEvidenceWarnings(mergeReceiptEvidence.invalid_evidence_count),
     ];
     const normalizedWarnings = [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
     const actionableWarnings = normalizedWarnings.filter((warning) => !warning.startsWith("integrity_legacy_hierarchy_"));
@@ -409,6 +419,7 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
                             mergeDriverAudit.drifted_keys.length,
                     pending_merge_decisions: pendingMergeDecisions.length,
                     lossless_merge_receipts: losslessMergeReceipts.length,
+                    invalid_merge_receipt_evidence: mergeReceiptEvidence.invalid_evidence_count,
                 },
                 item_unreadable: itemScan.unreadable,
                 item_conflict_markers: itemScan.conflictMarkers,
@@ -443,6 +454,8 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
             },
         },
         warnings: normalizedWarnings,
+        gitWorkspaceRoot,
+        pendingMergeReceipts,
     };
 }
 /* c8 ignore start -- activate export shape variants are exercised through integration load tests */
@@ -637,6 +650,7 @@ function buildExtensionHealthTriageSummary(warnings, loadFailureCount, activatio
     };
 }
 async function buildExtensionCheck(pmRoot, settings, noExtensionsFlag) {
+    const authorManifest = await inspectExtensionAuthorManifest(resolveWorkspaceRoot(pmRoot));
     const loadResult = await loadExtensions({
         pmRoot,
         settings,
@@ -723,6 +737,7 @@ async function buildExtensionCheck(pmRoot, settings, noExtensionsFlag) {
         ]
         : [];
     const extensionWarnings = [
+        ...authorManifest.warnings,
         ...loadResult.warnings,
         ...activationDetails.warnings,
         ...migrationStatus.warnings,
@@ -745,6 +760,7 @@ async function buildExtensionCheck(pmRoot, settings, noExtensionsFlag) {
                 loaded: loadedSummaries,
                 warnings: extensionWarnings,
                 activation: activationDetails,
+                author_manifest: authorManifest,
                 triage: extensionTriage,
                 ...(migrationStatus.summary.pending_count > 0
                     ? {
@@ -890,6 +906,7 @@ const HEALTH_DETAIL_SUMMARIZERS = {
                 registration_counts: activation.registration_counts,
                 migration_status: summarizeActivationMigrationStatus(activation.migration_status),
             },
+            author_manifest: details.author_manifest,
             triage: details.triage,
             capability_contract: details.capability_contract,
             capability_guidance: summarizeRecordList(details.capability_guidance, limit),
@@ -949,6 +966,7 @@ const HEALTH_DETAIL_SUMMARIZERS = {
         checked_items: details.checked_items,
         counts: details.counts,
         drifted_items: summarizeStringList(details.drifted_items, limit),
+        merge_receipt_attributed_items: summarizeStringList(details.merge_receipt_attributed_items, limit),
         missing_streams: summarizeStringList(details.missing_streams, limit),
         unreadable_streams: summarizeStringList(details.unreadable_streams, limit),
         hash_mismatches: summarizeStringList(details.hash_mismatches, limit),
@@ -1922,7 +1940,9 @@ function buildHealthFindings(params) {
 function rewriteBulkHealthRemediation(params) {
     if (params.check.name === "history_drift" && params.historyDriftedCount > 1) {
         for (const code of Object.keys(params.remediationMap)) {
-            params.remediationMap[code] = "pm history-repair --all";
+            if (code !== "history_drift_merge_receipt") {
+                params.remediationMap[code] = "pm history-repair --all";
+            }
         }
     }
     if (params.check.name === "storage" && params.overThresholdCount > 1) {
@@ -1945,6 +1965,67 @@ function attachHealthRemediationMaps(params) {
         }
     }
 }
+async function correlateMergeReceiptHistoryDriftItems(params) {
+    if (params.gitWorkspaceRoot === null ||
+        params.pendingMergeReceipts.length === 0) {
+        return [];
+    }
+    const details = params.historyDriftCheck.check.details;
+    const hashMismatches = Array.isArray(details.hash_mismatches)
+        ? details.hash_mismatches.filter((entry) => typeof entry === "string")
+        : [];
+    const unsafeStreamIds = new Set([
+        details.missing_streams,
+        details.unreadable_streams,
+        details.chain_mismatches,
+    ].flatMap((value) => (Array.isArray(value) ? value : [])));
+    const cloneLocalReceiptsByItem = new Map();
+    for (const receipt of params.pendingMergeReceipts) {
+        if (receipt.evidence_source !== "clone_local")
+            continue;
+        const receipts = cloneLocalReceiptsByItem.get(receipt.item_id) ?? [];
+        receipts.push(receipt);
+        cloneLocalReceiptsByItem.set(receipt.item_id, receipts);
+    }
+    const attributed = [];
+    for (const id of hashMismatches) {
+        if (unsafeStreamIds.has(id))
+            continue;
+        const receipts = cloneLocalReceiptsByItem.get(id);
+        if (!receipts || receipts.length === 0)
+            continue;
+        try {
+            const repair = await runHistoryRepair(id, {
+                dryRun: true,
+                mergeReceiptProof: {
+                    gitWorkspaceRoot: params.gitWorkspaceRoot,
+                    receipts,
+                },
+            }, params.global);
+            if (repair.merge_receipt_proof?.trusted)
+                attributed.push(id);
+        }
+        catch {
+            // Fail closed: generic history-repair guidance remains authoritative.
+        }
+    }
+    return [...new Set(attributed)].sort((left, right) => left.localeCompare(right));
+}
+function applyMergeReceiptHistoryDriftAttribution(historyDriftCheck, attributedItems) {
+    const attributed = new Set(attributedItems);
+    historyDriftCheck.warnings = [
+        ...historyDriftCheck.warnings.filter((warning) => {
+            if (!warning.startsWith("history_drift_hash_mismatch:"))
+                return true;
+            return !attributed.has(warning.slice(warning.indexOf(":") + 1));
+        }),
+        ...attributedItems.map((id) => `history_drift_merge_receipt:${id}`),
+    ].sort((left, right) => left.localeCompare(right));
+    historyDriftCheck.check.details = {
+        ...historyDriftCheck.check.details,
+        merge_receipt_attributed_items: attributedItems,
+    };
+}
 function projectHealthResult(result, options, summaryMode) {
     const warningCount = result.warning_count ?? result.warnings.length;
     const boundedResult = {
@@ -2030,11 +2111,22 @@ export async function runHealth(global, options = {}) {
     const provenanceWarnings = provenanceResolverHealth.warnings;
     const locksCheck = await buildLocksCheck(pmRoot);
     const integrityCheck = skipPolicy.skipIntegrity
-        ? buildSkippedHealthCheck("integrity")
+        ? {
+            ...buildSkippedHealthCheck("integrity"),
+            gitWorkspaceRoot: null,
+            pendingMergeReceipts: [],
+        }
         : await buildIntegrityCheck(pmRoot, typeRegistry.type_to_folder, settings.schema, options.requireMergeDrivers === true, items);
     const historyDriftCheck = skipPolicy.skipDrift
         ? buildSkippedHealthCheck("history_drift")
         : await buildHistoryDriftCheck(pmRoot, itemsWithBody);
+    const mergeReceiptAttributedHistoryDriftItems = await correlateMergeReceiptHistoryDriftItems({
+        gitWorkspaceRoot: integrityCheck.gitWorkspaceRoot,
+        pendingMergeReceipts: integrityCheck.pendingMergeReceipts,
+        historyDriftCheck,
+        global,
+    });
+    applyMergeReceiptHistoryDriftAttribution(historyDriftCheck, mergeReceiptAttributedHistoryDriftItems);
     const vectorizationCheck = skipPolicy.skipVectors
         ? buildSkippedHealthCheck("vectorization")
         : await buildVectorizationCheck(pmRoot, settings, itemsWithBody, refreshPolicy, options.verboseStaleItems === true);
@@ -2142,4 +2234,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=f7b3ff92-1fc7-55e9-aa76-af956714998f
+//# debugId=652d1b49-f9d1-55a7-84b5-ff3cf57648ad

package/dist/sdk/governance/validate.js

@@ -4,7 +4,7 @@
  * Implements the pm validate 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]="aca69fd7-c47a-5424-b58f-f305f690edd9")}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]="3d7d6f15-7587-5c22-8deb-373bfd063d2b")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import { realpathSync } from "node:fs";
@@ -34,7 +34,7 @@ import { buildMissingLinkedPathRows, summarizeMissingLinkedPathRows, } from "../
 import { assertProjectionModeChoice, } from "../output-projection.js";
 import { collectDanglingDependencyReferences } from "../graph/assembly.js";
 import { auditMergeAttributeFence, auditMergeDriverConfiguration, findGitWorkspaceRoot, resolveProjectMergeTypeFolders, } from "../merge/install.js";
-import { listMergeReceipts, partitionMergeReceipts, } from "../merge/receipts.js";
+import { inspectMergeReceiptEvidence, partitionMergeReceipts, } from "../merge/receipts.js";
 import { scanStorageIntegrity } from "./storage-integrity.js";
 import { scanTrackedRuntimeCache } from "./tracked-runtime-cache.js";
 import { scanHistoryAuthorAttribution } from "../author-attribution.js";
@@ -1991,6 +1991,11 @@ export const _testOnlyValidateCommand = {
     summarizeDuplicateIssueCodes,
     toMeaningfulString,
 };
+function appendInvalidMergeReceiptEvidenceWarning(warnings, invalidEvidenceCount) {
+    if (invalidEvidenceCount > 0) {
+        warnings.push(`merge_receipt_evidence_invalid:${invalidEvidenceCount}`);
+    }
+}
 /** Build the post-merge storage-integrity check (GH-603/GH-607/GH-609/GH-611): provably corrupted storage — unreadable item documents, on-disk-vs-parsed census mismatches, history conflict markers, resurrected deletes, and unparseable config/schema files — fails validate as an error instead of hiding behind ok:true. The `history_repair_reconciliations` count is informational: it surfaces post-repair divergence without permanently failing repaired workspaces. */
 async function buildStorageIntegrityCheck(pmRoot, items, typeToFolder, settings) {
     const scan = await scanStorageIntegrity(pmRoot, new Set(items.map((item) => item.id)), typeToFolder, {
@@ -2032,16 +2037,16 @@ async function buildStorageIntegrityCheck(pmRoot, items, typeToFolder, settings)
     if (mergeDriverAudit !== null && mergeDriverAudit.status !== "ok") {
         warnings.push(`validate_merge_driver_configuration:${mergeDriverAudit.missing_keys.length + mergeDriverAudit.drifted_keys.length}`);
     }
-    const pendingMergeReceipts = gitWorkspaceRoot === null
-        ? []
-        : await listMergeReceipts(gitWorkspaceRoot, {
-            includeLossless: true,
-            pmRoot,
-        });
+    const mergeReceiptEvidence = await inspectMergeReceiptEvidence(gitWorkspaceRoot ?? pmRoot, {
+        includeLossless: true,
+        pmRoot,
+    });
+    const pendingMergeReceipts = mergeReceiptEvidence.receipts;
     const { pendingDecisions: pendingMergeDecisions, lossless: losslessMergeReceipts, } = partitionMergeReceipts(pendingMergeReceipts);
     if (pendingMergeDecisions.length > 0) {
         warnings.push(`validate_merge_decisions_unreviewed:${pendingMergeDecisions.length}`);
     }
+    appendInvalidMergeReceiptEvidenceWarning(warnings, mergeReceiptEvidence.invalid_evidence_count);
     const status = errorCount > 0 ? "error" : warnings.length > 0 ? "warn" : "ok";
     return {
         check: {
@@ -2060,6 +2065,7 @@ async function buildStorageIntegrityCheck(pmRoot, items, typeToFolder, settings)
                     ...new Set(pendingMergeDecisions.map((receipt) => receipt.item_id)),
                 ].sort((left, right) => left.localeCompare(right)),
                 lossless_merge_receipt_count: losslessMergeReceipts.length,
+                invalid_merge_receipt_evidence_count: mergeReceiptEvidence.invalid_evidence_count,
                 lossless_merge_receipt_items: [
                     ...new Set(losslessMergeReceipts.map((receipt) => receipt.item_id)),
                 ].sort((left, right) => left.localeCompare(right)),
@@ -2280,4 +2286,4 @@ export async function runValidate(options, global, services = {}) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=validate.js.map
-//# debugId=aca69fd7-c47a-5424-b58f-f305f690edd9
+//# debugId=3d7d6f15-7587-5c22-8deb-373bfd063d2b

package/dist/sdk/history-repair.d.ts

@@ -1,6 +1,7 @@
 import { type ReplayDocument } from "../core/history/replay.js";
 import type { GlobalOptions } from "../core/shared/command-types.js";
 import type { HistoryEntry } from "../types/index.js";
+import { type MergeDecisionReceipt } from "./merge/receipts.js";
 import { type ProvenanceNormalizationReceipt } from "./governance/provenance-health.js";
 /** Documents the history repair command options payload exchanged by command, SDK, and package integrations. */
 export interface HistoryRepairCommandOptions {
@@ -22,6 +23,16 @@ export interface HistoryRepairCommandOptions {
     forceAuditEntry?: boolean;
     /** Remove bounded-domain-invalid provenance observations and record an aggregate privacy-safe audit receipt. */
     normalizeProvenance?: boolean;
+    /** Internal receipt evidence revalidated against the exact item snapshot used by this repair. */
+    mergeReceiptProof?: {
+        gitWorkspaceRoot: string | null;
+        receipts: MergeDecisionReceipt[];
+    };
+    /** Internal per-item receipt proof index used by bounded bulk reconciliation. */
+    mergeReceiptProofById?: Record<string, {
+        gitWorkspaceRoot: string | null;
+        receipts: MergeDecisionReceipt[];
+    }>;
 }
 /** Documents the history repair result payload exchanged by command, SDK, and package integrations. */
 export interface HistoryRepairResult {
@@ -60,11 +71,22 @@ export interface HistoryRepairResult {
     };
     /** Present when reconciling the chain with the on-disk item discards the replayed effect of earlier history events (GH-603): names the reverted fields and the authors whose mutations the reconciliation overwrites, so cross-author data loss after a lossy merge is loud instead of silent. */
     reconciliation?: HistoryRepairReconciliationReport;
+    /** Present when merge reconciliation supplied receipt evidence for this item. */
+    merge_receipt_proof?: MergeReceiptProofResult;
     /** Value that configures or reports warnings for this contract. */
     warnings: string[];
     /** ISO 8601 timestamp recording when generated occurred. */
     generated_at: string;
 }
+/** Fail-closed proof that clone-local driver receipts exactly cover the current reconciliation fields and values. */
+export interface MergeReceiptProofResult {
+    /** Whether exact receipt identity, path, field, and value-hash evidence proves the snapshot. */
+    trusted: boolean;
+    /** Stable explanation for the trust decision. */
+    reason: "trusted_clone_local_driver_evidence" | "git_workspace_unavailable" | "item_path_unavailable" | "no_item_receipts" | "no_receipt_set_proves_snapshot";
+    /** Exact receipt identities accepted as proof; empty when proof is refused. */
+    receipt_ids: string[];
+}
 /** Documents one history event attributed to fields changed by reconciliation. */
 export interface HistoryRepairDiscardedEvent {
     /** 1-based index of the event in the (re-anchored) history stream. */
@@ -121,6 +143,8 @@ export interface HistoryRepairAllStreamResult {
     reconciled_with_item?: boolean;
     /** Cross-author data-loss detail when reconciliation overwrites replayed mutations. */
     reconciliation?: HistoryRepairReconciliationReport;
+    /** Exact receipt proof used to authorize this stream, when supplied. */
+    merge_receipt_proof?: MergeReceiptProofResult;
     /** Stream-specific repair warnings retained by the bulk workflow. */
     warnings?: string[];
     /** Value that configures or reports error for this contract. */

package/dist/sdk/history-repair.js

@@ -4,8 +4,10 @@
  * Implements the pm history repair 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]="d201aa9f-1ed3-5655-8c06-e5729557b86a")}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]="7a21ee76-ed53-57a0-9776-c787297ed7b6")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
+import { realpath } from "node:fs/promises";
+import path from "node:path";
 import jsonPatch from "fast-json-patch";
 import { patchPathToChangedField } from "../core/history/history-diff.js";
 import { pathExists, readFileIfExists } from "../core/fs/fs-utils.js";
@@ -19,11 +21,13 @@ import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { resolveAuthor } from "../core/shared/author.js";
 import { nowIso } from "../core/shared/time.js";
+import { sha256Hex, stableStringify } from "../core/shared/serialization.js";
 import { getActiveExtensionRegistrations, runActiveOnWriteHooks, } from "../core/extensions/index.js";
 import { listAllItemMetadataWithBody, readLocatedItem, } from "../core/store/item-store.js";
 import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 import { resolveHistorySubject } from "./history-redact.js";
+import { summarizeMergeReceipt, } from "./merge/receipts.js";
 import { listInvalidProvenanceHistoryStreamIds, normalizeInvalidHistoryProvenance, } from "./governance/provenance-health.js";
 function replayFieldValue(document, field) {
     return field === "body"
@@ -135,6 +139,130 @@ export function analyzeReconciliationDiscard(entries, finalReplay, currentItemRe
             : null,
     };
 }
+async function canonicalRealPath(value) {
+    try {
+        return await realpath(value);
+    }
+    catch {
+        return null;
+    }
+}
+async function verifyReceiptAgainstSnapshot(params) {
+    if (params.receipt.evidence_source !== "clone_local")
+        return null;
+    const receiptPath = await canonicalRealPath(path.resolve(params.gitWorkspaceRoot, params.receipt.item_path));
+    if (receiptPath !== params.currentPath)
+        return null;
+    const declaredFields = [
+        ...new Set([
+            ...params.receipt.fields_from_theirs,
+            ...params.receipt.union_fields,
+            ...params.receipt.decisions.map((decision) => decision.field),
+        ]),
+    ].sort((left, right) => left.localeCompare(right));
+    const hashes = params.receipt.merged_field_hashes;
+    if (!hashes || declaredFields.length === 0)
+        return null;
+    const hashFields = Object.keys(hashes).sort((left, right) => left.localeCompare(right));
+    if (declaredFields.length !== hashFields.length ||
+        declaredFields.some((field, index) => field !== hashFields[index])) {
+        return null;
+    }
+    const currentMetadata = params.currentItemReplay.metadata;
+    const valuesMatch = declaredFields.every((field) => {
+        const value = field === "body" ? params.currentItemReplay.body : currentMetadata[field];
+        return hashes[field] === sha256Hex(stableStringify(value));
+    });
+    return valuesMatch ? { receipt: params.receipt, declaredFields } : null;
+}
+async function verifyMergeReceiptProof(params) {
+    if (params.proof.gitWorkspaceRoot === null) {
+        return {
+            trusted: false,
+            reason: "git_workspace_unavailable",
+            receipt_ids: [],
+        };
+    }
+    if (params.itemPath === null || params.currentItemReplay === null) {
+        return {
+            trusted: false,
+            reason: "item_path_unavailable",
+            receipt_ids: [],
+        };
+    }
+    const itemReceipts = params.proof.receipts.filter((receipt) => receipt.item_id === params.id);
+    if (itemReceipts.length === 0) {
+        return { trusted: false, reason: "no_item_receipts", receipt_ids: [] };
+    }
+    const currentPath = await realpath(params.itemPath);
+    const trustedReceipts = [];
+    for (const receipt of itemReceipts) {
+        const trusted = await verifyReceiptAgainstSnapshot({
+            receipt,
+            gitWorkspaceRoot: params.proof.gitWorkspaceRoot,
+            currentPath,
+            currentItemReplay: params.currentItemReplay,
+        });
+        if (trusted)
+            trustedReceipts.push(trusted);
+    }
+    const trustedFields = new Set(trustedReceipts.flatMap(({ declaredFields }) => declaredFields));
+    const reconciliationFields = params.reconciliation?.reconciled_fields;
+    if (trustedReceipts.length > 0 &&
+        (reconciliationFields === undefined ||
+            (reconciliationFields.length > 0 &&
+                reconciliationFields.every((field) => trustedFields.has(field))))) {
+        return {
+            trusted: true,
+            reason: "trusted_clone_local_driver_evidence",
+            receipt_ids: trustedReceipts.map(({ receipt }) => receipt.id),
+        };
+    }
+    return {
+        trusted: false,
+        reason: "no_receipt_set_proves_snapshot",
+        receipt_ids: [],
+    };
+}
+async function resolveHistoryRepairMergeEvidence(params) {
+    const subjectMergeReceipts = params.options.mergeReceiptProof?.receipts.filter((receipt) => receipt.item_id === params.subjectId) ?? [];
+    const mergeReceiptProof = params.options.mergeReceiptProof
+        ? await verifyMergeReceiptProof({
+            proof: {
+                ...params.options.mergeReceiptProof,
+                receipts: subjectMergeReceipts,
+            },
+            id: params.subjectId,
+            itemPath: params.itemReplayContext.currentItemPath,
+            currentItemReplay: params.itemReplayContext.currentItemReplay,
+            reconciliation: params.reconciliation,
+        })
+        : undefined;
+    if (mergeReceiptProof &&
+        !mergeReceiptProof.trusted &&
+        params.options.dryRun !== true &&
+        params.options.force !== true) {
+        throw new PmCliError(`Merge receipt evidence for ${params.subjectId} does not prove the exact item snapshot (${mergeReceiptProof.reason}).`, EXIT_CODE.CONFLICT, {
+            code: "merge_reconcile_receipt_evidence_untrusted",
+            required: "Use clone-local driver evidence whose canonical path, declared fields, and merged-value hashes match the current item, or review the mismatch and rerun with --force.",
+            recovery: { suggested_retry: "pm merge reconcile --dry-run" },
+        });
+    }
+    const provenMergeReceipts = mergeReceiptProof?.trusted
+        ? subjectMergeReceipts.filter((receipt) => mergeReceiptProof.receipt_ids.includes(receipt.id))
+        : [];
+    return {
+        mergeReceiptProof,
+        effectiveAuditContext: provenMergeReceipts.length > 0 && params.options.force !== true
+            ? {
+                ...params.options.auditContext,
+                merge: {
+                    receipts: provenMergeReceipts.map(summarizeMergeReceipt),
+                },
+            }
+            : params.options.auditContext,
+    };
+}
 async function loadHistoryRepairItemReplay(subject, settings, historyEntries, itemHashVersion) {
     const currentItemPath = subject.located?.itemPath ?? null;
     const loadedItem = subject.located
@@ -275,6 +403,12 @@ export async function runHistoryRepair(id, options, global) {
     const reconciliation = reconcileNeeded && itemReplayContext.currentItemReplay
         ? analyzeReconciliationDiscard(reanchor.entries, finalReplay, itemReplayContext.currentItemReplay)
         : undefined;
+    const { mergeReceiptProof, effectiveAuditContext } = await resolveHistoryRepairMergeEvidence({
+        options,
+        subjectId: subject.id,
+        itemReplayContext,
+        reconciliation,
+    });
     const changed = [
         reanchor.entriesRehashed > 0,
         reanchor.entriesPatchRepaired > 0,
@@ -301,10 +435,10 @@ export async function runHistoryRepair(id, options, global) {
         auditOperation: options.auditOperation ?? "history_repair",
         auditContext: provenanceNormalization.receipt.changed
             ? {
-                ...options.auditContext,
+                ...effectiveAuditContext,
                 provenance_normalization: provenanceNormalization.receipt,
             }
-            : options.auditContext,
+            : effectiveAuditContext,
         itemHashVersion,
         explicitItemHashVersion: reanchor.explicitItemHashVersion,
     });
@@ -360,6 +494,7 @@ export async function runHistoryRepair(id, options, global) {
             ...provenanceNormalization.receipt,
         },
         ...(reconciliation ? { reconciliation } : {}),
+        ...(mergeReceiptProof ? { merge_receipt_proof: mergeReceiptProof } : {}),
         warnings: [...new Set(warnings)].sort((left, right) => left.localeCompare(right)),
         generated_at: nowIso(),
     };
@@ -397,6 +532,9 @@ export async function runHistoryRepairAll(options, global) {
                 ...options,
                 auditContext: options.auditContextById?.[driftedId],
                 auditContextById: undefined,
+                mergeReceiptProof: options.mergeReceiptProofById?.[driftedId] ??
+                    options.mergeReceiptProof,
+                mergeReceiptProofById: undefined,
             }, global);
             /* c8 ignore next -- mixed repaired/clean outcomes depend on live drift composition. */
             const outcome = result.changed ? "repaired" : "skipped_clean";
@@ -411,6 +549,9 @@ export async function runHistoryRepairAll(options, global) {
                 ...(result.reconciliation
                     ? { reconciliation: result.reconciliation }
                     : {}),
+                ...(result.merge_receipt_proof
+                    ? { merge_receipt_proof: result.merge_receipt_proof }
+                    : {}),
                 warnings: result.warnings,
             });
         }
@@ -440,4 +581,4 @@ export async function runHistoryRepairAll(options, global) {
     };
 }
 //# sourceMappingURL=history-repair.js.map
-//# debugId=d201aa9f-1ed3-5655-8c06-e5729557b86a
+//# debugId=7a21ee76-ed53-57a0-9776-c787297ed7b6

package/dist/sdk/index.d.ts

@@ -4,6 +4,12 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 export { PM_COMMAND_CAPABILITY_CONTRACTS, PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForFamily, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandCapabilityFamily, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
+export * from "./mcp/protocol.js";
+export * from "./mcp/interactions.js";
+export * from "./mcp/tasks.js";
+export * from "./mcp/subscriptions.js";
+export * from "./mcp/transport.js";
+export * from "./mcp/authorization.js";
 export * from "./cli-contracts/grammar-contracts.js";
 export * from "./agent-session-context.js";
 export type { PmCommandCapabilityContract, PmCommandCapabilityFamily, PmCommandVisibilityContract, PmCommandVisibilityTier, PmMcpPromptArgumentContract, PmMcpPromptContract, PmMcpResourceContract, PmMcpToolProfile, } from "./agent-capability-contracts.js";

package/dist/sdk/index.js

@@ -4,8 +4,14 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 
-!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]="805c081a-a781-50c3-8919-81492208913b")}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]="bfa96f97-ffdf-54f9-b632-006f5dfe2ee3")}catch(e){}}();
 export { PM_COMMAND_CAPABILITY_CONTRACTS, PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForFamily, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandCapabilityFamily, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
+export * from "./mcp/protocol.js";
+export * from "./mcp/interactions.js";
+export * from "./mcp/tasks.js";
+export * from "./mcp/subscriptions.js";
+export * from "./mcp/transport.js";
+export * from "./mcp/authorization.js";
 export * from "./cli-contracts/grammar-contracts.js";
 export * from "./agent-session-context.js";
 export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, normalizeAnnotationTransportOptions, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, } from "./annotations.js";
@@ -167,4 +173,4 @@ export * from "./governance.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=805c081a-a781-50c3-8919-81492208913b
+//# debugId=bfa96f97-ffdf-54f9-b632-006f5dfe2ee3