@unbrained/pm-cli 2026.8.24 → 2026.8.25

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/merge/driver.js

@@ -9,14 +9,16 @@
  * merge never corrupts tracker storage the way raw conflict markers do.
  */
 
-!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]="8d79e3a4-6104-5855-837f-69a041b87b27")}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]="2c8046a5-06aa-58f8-b347-e757086082d1")}catch(e){}}();
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
 import { collectRegisteredItemFieldNames } from "../../core/extensions/item-fields.js";
 import { pathExists } from "../../core/fs/fs-utils.js";
+import { parseItemDocument } from "../../core/item/item-format.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
+import { sha256Hex, stableStringify } from "../../core/shared/serialization.js";
 import { nowIso } from "../../core/shared/time.js";
 import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
@@ -122,10 +124,12 @@ export async function runMergeDriver(options, global) {
     }
     else if (artifact === "item") {
         const settings = await loadOptionalSettings(global);
+        const itemFormat = itemFormatForPath(options.itemPath ?? outputPath, settings);
+        const extensionFieldNames = collectRegisteredItemFieldNames(getActiveExtensionRegistrations());
         const itemMerge = mergeItemDocuments(baseRaw, oursRaw, theirsRaw, {
-            format: itemFormatForPath(options.itemPath ?? outputPath, settings),
+            format: itemFormat,
             schema: settings?.schema,
-            extensionFieldNames: collectRegisteredItemFieldNames(getActiveExtensionRegistrations()),
+            extensionFieldNames,
             preferred,
             conflictResolution: "stable_value_order",
         });
@@ -137,6 +141,19 @@ export async function runMergeDriver(options, global) {
             conflict_resolution: "stable_value_order",
         };
         if (options.itemPath !== undefined) {
+            const mergedDocument = parseItemDocument(merged, {
+                format: itemFormat,
+                schema: settings?.schema,
+                extensionFieldNames,
+            });
+            const mergedMetadata = mergedDocument.metadata;
+            const receiptFields = [
+                ...new Set([
+                    ...itemMerge.fields_from_theirs,
+                    ...itemMerge.union_fields,
+                    ...itemMerge.conflict_decisions.map((decision) => decision.field),
+                ]),
+            ];
             receiptInput = {
                 cwd: process.cwd(),
                 itemPath: options.itemPath,
@@ -144,6 +161,10 @@ export async function runMergeDriver(options, global) {
                 conflictResolution: "stable_value_order",
                 fieldsFromTheirs: itemMerge.fields_from_theirs,
                 unionFields: itemMerge.union_fields,
+                mergedFieldHashes: Object.fromEntries(receiptFields.map((field) => [
+                    field,
+                    sha256Hex(stableStringify(field === "body" ? mergedDocument.body : mergedMetadata[field])),
+                ])),
                 decisions: itemMerge.conflict_decisions,
             };
         }
@@ -187,4 +208,4 @@ export async function runMergeDriver(options, global) {
     };
 }
 //# sourceMappingURL=driver.js.map
-//# debugId=8d79e3a4-6104-5855-837f-69a041b87b27
+//# debugId=2c8046a5-06aa-58f8-b347-e757086082d1

package/dist/sdk/merge/receipt-file-boundary.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @module sdk/merge/receipt-file-boundary
+ *
+ * Reads untrusted receipt candidates through a bounded, no-follow file
+ * boundary whose race and short-read behavior can be exercised directly.
+ */
+import { type Stats } from "node:fs";
+import { type FileHandle } from "node:fs/promises";
+/** Minimal filesystem operations required by the receipt reader. */
+export interface ReceiptFileBoundary {
+    /** Inspect the path without following its final symbolic link. */
+    lstat(receiptPath: string): Promise<Stats>;
+    /** Open the candidate and return the handle used for verified reads. */
+    open(receiptPath: string, flags: number): Promise<FileHandle>;
+}
+/** Resolve the platform no-follow flag, falling back only where Node omits it. */
+export declare function resolveReceiptNoFollowFlag(constants: {
+    O_NOFOLLOW?: number;
+}): number;
+/** Read one regular file only when its opened identity remains bounded and stable. */
+export declare function readBoundedRegularFile(receiptPath: string, maximumBytes: number, boundary?: ReceiptFileBoundary): Promise<string | null>;

package/dist/sdk/merge/receipt-file-boundary.js

@@ -0,0 +1,47 @@
+/**
+ * @module sdk/merge/receipt-file-boundary
+ *
+ * Reads untrusted receipt candidates through a bounded, no-follow file
+ * boundary whose race and short-read behavior can be exercised directly.
+ */
+
+!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]="6ece0e15-aff5-5e2d-b18a-16ffaa0fe2ea")}catch(e){}}();
+import { constants as fsConstants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+const NODE_RECEIPT_FILE_BOUNDARY = { lstat, open };
+/** Resolve the platform no-follow flag, falling back only where Node omits it. */
+export function resolveReceiptNoFollowFlag(constants) {
+    return constants.O_NOFOLLOW ?? 0;
+}
+/** Read one regular file only when its opened identity remains bounded and stable. */
+export async function readBoundedRegularFile(receiptPath, maximumBytes, boundary = NODE_RECEIPT_FILE_BOUNDARY) {
+    const pathStats = await boundary.lstat(receiptPath);
+    if (pathStats.isSymbolicLink() ||
+        !pathStats.isFile() ||
+        pathStats.size > maximumBytes) {
+        return null;
+    }
+    const handle = await boundary.open(receiptPath, fsConstants.O_RDONLY | resolveReceiptNoFollowFlag(fsConstants));
+    try {
+        const openedStats = await handle.stat();
+        if (!openedStats.isFile() || openedStats.size > maximumBytes)
+            return null;
+        const buffer = Buffer.alloc(openedStats.size);
+        let offset = 0;
+        while (offset < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
+            if (bytesRead === 0)
+                break;
+            offset += bytesRead;
+        }
+        const finalStats = await handle.stat();
+        return finalStats.size === openedStats.size && offset === openedStats.size
+            ? buffer.toString("utf8", 0, offset)
+            : null;
+    }
+    finally {
+        await handle.close();
+    }
+}
+//# sourceMappingURL=receipt-file-boundary.js.map
+//# debugId=6ece0e15-aff5-5e2d-b18a-16ffaa0fe2ea

package/dist/sdk/merge/receipts.d.ts

@@ -19,6 +19,8 @@ export interface MergeDecisionReceipt {
     fields_from_theirs: string[];
     /** Collections combined from both branches. */
     union_fields: string[];
+    /** SHA-256 hashes of the merged values for every field represented by this receipt. Absent on legacy receipts, which cannot prove drift attribution. */
+    merged_field_hashes?: Record<string, string>;
     /** Full recoverable scalar decisions, retained only in the clone. */
     decisions: ItemMergeConflictDecision[];
     /** Whether a merge reconciliation history event consumed this receipt. */
@@ -29,6 +31,8 @@ export interface MergeDecisionReceipt {
     reconciled_at?: string;
     /** Whether decision values are recoverable locally or represented by hashes only. */
     value_availability?: "clone_local" | "hash_only";
+    /** Runtime-only provenance assigned by the reader; serialized values are ignored. */
+    evidence_source?: "clone_local" | "durable";
 }
 /** Privacy-safe receipt summary suitable for committed history context. */
 export interface MergeDecisionReceiptSummary {
@@ -66,6 +70,13 @@ export interface MergeReceiptReport {
     /** ISO timestamp for the report. */
     generated_at: string;
 }
+/** Internal integrity scan result used by health without exposing malformed receipt contents. */
+export interface MergeReceiptEvidenceScan {
+    /** Valid receipts that passed bounded-file, schema, and identity validation. */
+    receipts: MergeDecisionReceipt[];
+    /** Number of JSON receipt candidates that could not be validated safely. */
+    invalid_evidence_count: number;
+}
 /** Convert a raw receipt into privacy-safe history context. */
 export declare function summarizeMergeReceipt(receipt: MergeDecisionReceipt): MergeDecisionReceiptSummary;
 /** Persist one item-driver outcome in the clone-local Git directory. */
@@ -76,8 +87,18 @@ export declare function writeMergeReceipt(params: {
     conflictResolution?: "preferred_side" | "stable_value_order";
     fieldsFromTheirs: string[];
     unionFields: string[];
+    mergedFieldHashes?: Record<string, string>;
     decisions: ItemMergeConflictDecision[];
 }): Promise<MergeDecisionReceipt | null>;
+/** Inspect valid receipts and count invalid evidence without returning untrusted file contents. */
+export declare function inspectMergeReceiptEvidence(cwd: string, options?: {
+    /** Include receipts whose reconciliation state is already settled. */
+    includeReconciled?: boolean;
+    /** Include receipts that contain no discarded scalar values. */
+    includeLossless?: boolean;
+    /** Explicit tracker root used to locate durable receipt evidence. */
+    pmRoot?: string;
+}): Promise<MergeReceiptEvidenceScan>;
 /** Read clone-local receipts with explicit reconciled/lossless classification controls. */
 export declare function listMergeReceipts(cwd: string, options?: {
     includeReconciled?: boolean;
@@ -92,7 +113,9 @@ export declare function partitionMergeReceipts(receipts: MergeDecisionReceipt[])
     lossless: MergeDecisionReceipt[];
 };
 /** Mark a receipt as represented by a committed merge history event. */
-export declare function markMergeReceiptReconciled(cwd: string, receipt: MergeDecisionReceipt): Promise<void>;
+export declare function markMergeReceiptReconciled(cwd: string, receipt: MergeDecisionReceipt, options?: {
+    requireExisting?: boolean;
+}): Promise<void>;
 /** Report pending or historical clone-local merge decisions. */
 export declare function runMergeReceiptReport(options: {
     /** Include receipts already represented by merge history events. */