@unbrained/pm-cli 2026.9.3 → 2026.9.4

package/dist/sdk/governance/merge-receipt-history.js

@@ -0,0 +1,207 @@
+/**
+ * @module sdk/governance/merge-receipt-history
+ *
+ * Classifies privacy-safe merge receipt references embedded in history.
+ */
+
+!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]="1e73338f-221a-580f-85a8-6f2a488fb89d")}catch(e){}}();
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { compareTimestampStrings, isRfc3339DateTime, } from "../../core/shared/time.js";
+import { isSafeReceiptId } from "../merge/receipts.js";
+/** First commit timestamp at which merge receipts gained a tracked durable copy. */
+export const DURABLE_MERGE_RECEIPT_INTRODUCED_AT = "2026-08-09T16:15:18.000Z";
+const PRE_DURABLE_DISPOSITION_ELIGIBLE = Symbol("pre-durable-disposition-eligible");
+/** Return whether an unknown value is a non-array record. */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Return a bounded dense list of unique, non-empty field names. */
+function isFieldArray(value) {
+    if (!Array.isArray(value) || value.length > 256)
+        return false;
+    const fields = new Set();
+    for (let index = 0; index < value.length; index += 1) {
+        const field = value[index];
+        if (!(index in value) ||
+            typeof field !== "string" ||
+            field.length === 0 ||
+            field.length > 256 ||
+            field.includes("\0") ||
+            fields.has(field)) {
+            return false;
+        }
+        fields.add(field);
+    }
+    return true;
+}
+/** Return whether an unknown value is one complete legacy field decision. */
+function isLegacyDecision(value) {
+    if (!isRecord(value))
+        return false;
+    return (typeof value.field === "string" &&
+        value.field.length > 0 &&
+        value.field.length <= 256 &&
+        !value.field.includes("\0") &&
+        typeof value.retained_hash === "string" &&
+        /^[a-f0-9]{64}$/u.test(value.retained_hash) &&
+        typeof value.discarded_hash === "string" &&
+        /^[a-f0-9]{64}$/u.test(value.discarded_hash));
+}
+/** Return whether a legacy item path is normalized, bounded, and item-scoped. */
+function isLegacyItemPath(value, historyItemId) {
+    if (typeof value !== "string")
+        return false;
+    const normalized = path.posix.normalize(value);
+    return (value.length <= 4_096 &&
+        !value.includes("\\") &&
+        !value.includes("\0") &&
+        !path.posix.isAbsolute(value) &&
+        normalized === value &&
+        !normalized.startsWith("../") &&
+        (path.posix.basename(normalized) === `${historyItemId}.toon` ||
+            path.posix.basename(normalized) === `${historyItemId}.md`));
+}
+/** Return whether a preferred-era summary has one safe canonical identity. */
+function hasLegacyReceiptIdentity(value, historyItemId) {
+    return (typeof value.receipt_id === "string" &&
+        isSafeReceiptId(value.receipt_id) &&
+        (value.preferred === "ours" || value.preferred === "theirs") &&
+        value.requested_preference === undefined &&
+        value.conflict_resolution === undefined &&
+        value.item_id === historyItemId &&
+        isLegacyItemPath(value.item_path, historyItemId));
+}
+/** Return whether preferred-era summary collections are dense and self-consistent. */
+function hasLegacyReceiptCollections(value) {
+    const conflictFields = value.conflict_fields;
+    const fieldsFromTheirs = value.fields_from_theirs;
+    const unionFields = value.union_fields;
+    const decisions = value.decisions;
+    const decisionFields = Array.isArray(decisions)
+        ? new Set(decisions.flatMap((decision) => isLegacyDecision(decision) ? [decision.field] : []))
+        : new Set();
+    return (isFieldArray(conflictFields) &&
+        isFieldArray(fieldsFromTheirs) &&
+        isFieldArray(unionFields) &&
+        Array.isArray(decisions) &&
+        decisions.length > 0 &&
+        decisions.length <= 256 &&
+        Object.keys(decisions).length === decisions.length &&
+        decisions.every(isLegacyDecision) &&
+        decisionFields.size === decisions.length &&
+        conflictFields.length === decisionFields.size &&
+        conflictFields.every((field) => decisionFields.has(field)));
+}
+/** Return whether one summary is a complete, self-contained preferred-era receipt. */
+export function isLegacyMergeReceiptSummary(value, historyItemId) {
+    return (hasLegacyReceiptIdentity(value, historyItemId) &&
+        hasLegacyReceiptCollections(value));
+}
+/** Return whether a summary matches the final clone-local-only schema before durable receipts. */
+export function isPreDurableCloneLocalReceiptSummary(value, historyItemId) {
+    return (typeof value.receipt_id === "string" &&
+        isSafeReceiptId(value.receipt_id) &&
+        (value.preferred === "ours" || value.preferred === "theirs") &&
+        value.requested_preference === undefined &&
+        (value.conflict_resolution === "preferred_side" ||
+            value.conflict_resolution === "stable_value_order") &&
+        value.item_id === historyItemId &&
+        isLegacyItemPath(value.item_path, historyItemId) &&
+        hasLegacyReceiptCollections(value));
+}
+/** Return whether an extracted reference carried a validated pre-durable summary. */
+export function isPreDurableDispositionEligibleReference(reference) {
+    return (reference[PRE_DURABLE_DISPOSITION_ELIGIBLE] === true);
+}
+/** Extract receipt ids and legacy compatibility disposition from one history entry. */
+export function extractHistoryMergeReceiptReferences(value, historyItemId) {
+    if (!isRecord(value) || !isRecord(value.context))
+        return [];
+    const merge = value.context.merge;
+    if (!isRecord(merge) || !Array.isArray(merge.receipts))
+        return [];
+    return merge.receipts.flatMap((receipt) => {
+        if (!isRecord(receipt) ||
+            typeof receipt.receipt_id !== "string" ||
+            receipt.receipt_id.trim().length === 0) {
+            return [];
+        }
+        const reference = {
+            receiptId: receipt.receipt_id,
+            legacySummaryAccepted: isLegacyMergeReceiptSummary(receipt, historyItemId),
+            [PRE_DURABLE_DISPOSITION_ELIGIBLE]: isPreDurableCloneLocalReceiptSummary(receipt, historyItemId),
+            ...(typeof value.ts === "string" && isRfc3339DateTime(value.ts)
+                ? { eventTimestamp: value.ts }
+                : {}),
+        };
+        return [reference];
+    });
+}
+/** Extract validated explicit missing-receipt dispositions from one merge audit event. */
+export function extractHistoryMergeReceiptDispositions(value, historyItemId, historyLine) {
+    if (!isRecord(value) || value.op !== "merge_reconcile")
+        return [];
+    if (!isRecord(value.context) || !isRecord(value.context.merge))
+        return [];
+    const dispositions = value.context.merge.missing_receipt_dispositions;
+    if (!Array.isArray(dispositions) || dispositions.length > 256)
+        return [];
+    return dispositions.flatMap((disposition) => {
+        if (!isRecord(disposition) ||
+            typeof disposition.receipt_id !== "string" ||
+            !isSafeReceiptId(disposition.receipt_id) ||
+            typeof disposition.original_history_line !== "number" ||
+            !Number.isSafeInteger(disposition.original_history_line) ||
+            disposition.original_history_line < 1 ||
+            typeof disposition.original_event_ts !== "string" ||
+            !isRfc3339DateTime(disposition.original_event_ts) ||
+            disposition.reason !== "legacy_clone_local_only") {
+            return [];
+        }
+        return [
+            {
+                itemId: historyItemId,
+                receiptId: disposition.receipt_id,
+                originalHistoryLine: disposition.original_history_line,
+                originalEventTimestamp: disposition.original_event_ts,
+                auditHistoryLine: historyLine,
+                reason: disposition.reason,
+            },
+        ];
+    });
+}
+/** Classify scanned references without treating complete legacy summaries as absent. */
+export function classifyHistoryMergeReceiptReferences(references, availableReceiptIds, dispositions = []) {
+    const dispositionAuditLineByCoordinate = new Map();
+    for (const disposition of dispositions) {
+        const coordinate = `${disposition.itemId}\0${disposition.originalHistoryLine}\0${disposition.receiptId}\0${disposition.originalEventTimestamp}`;
+        dispositionAuditLineByCoordinate.set(coordinate, Math.max(dispositionAuditLineByCoordinate.get(coordinate) ?? 0, disposition.auditHistoryLine));
+    }
+    const dispositionAccepts = (reference) => isPreDurableDispositionEligibleReference(reference) &&
+        reference.eventTimestamp !== undefined &&
+        compareTimestampStrings(reference.eventTimestamp, DURABLE_MERGE_RECEIPT_INTRODUCED_AT) < 0 &&
+        (dispositionAuditLineByCoordinate.get(`${reference.itemId}\0${reference.line}\0${reference.receiptId}\0${reference.eventTimestamp}`) ?? 0) > reference.line;
+    const missing = references
+        .filter((reference) => !reference.legacySummaryAccepted &&
+        !availableReceiptIds.has(reference.receiptId) &&
+        !dispositionAccepts(reference))
+        .map((reference) => ({
+        item_id: reference.itemId,
+        history_line: reference.line,
+        ...(isSafeReceiptId(reference.receiptId)
+            ? { receipt_id: reference.receiptId }
+            : {
+                receipt_reference_hash: createHash("sha256")
+                    .update(reference.receiptId)
+                    .digest("hex"),
+            }),
+    }));
+    return {
+        missing,
+        acceptedLegacyCount: references.filter((reference) => reference.legacySummaryAccepted).length,
+        acceptedDispositionCount: references.filter(dispositionAccepts).length,
+    };
+}
+//# sourceMappingURL=merge-receipt-history.js.map
+//# debugId=1e73338f-221a-580f-85a8-6f2a488fb89d

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

@@ -4,9 +4,10 @@
  * 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]="6efed404-acd2-5c3a-a008-856df67c8b77")}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]="cb3bf7ee-808f-5ff6-af84-edb034760c54")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
+import { resealHistoryRewrite, verifyHistoryRecordHash, } from "../../core/history/history.js";
 const DEFAULT_PROVENANCE_HISTORY_BYTE_LIMIT = 8_388_608;
 const ATTEMPTED_PROVENANCE_OUTCOME_STATUSES = new Set(["resolved", "failed"]);
 const INVALID_PROVENANCE_VALUE_CLASSIFIERS = [
@@ -45,6 +46,8 @@ export function normalizeInvalidHistoryProvenance(entries) {
             : undefined;
         if (provenance === undefined)
             return entry;
+        if (!verifyHistoryRecordHash(entry).ok)
+            return entry;
         const retained = {};
         let eventChanged = false;
         for (const [dimension, observation] of Object.entries(provenance)) {
@@ -78,7 +81,10 @@ export function normalizeInvalidHistoryProvenance(entries) {
         else {
             next.agent_provenance = retained;
         }
-        return next;
+        return resealHistoryRewrite(entry, next, {
+            retainPriorRecord: true,
+            retainPriorRecordHash: false,
+        });
     });
     return {
         entries: normalized,
@@ -274,4 +280,4 @@ export async function scanProvenanceResolverHealth(pmRoot, eventLimit = 10_000)
     };
 }
 //# sourceMappingURL=provenance-health.js.map
-//# debugId=6efed404-acd2-5c3a-a008-856df67c8b77
+//# debugId=cb3bf7ee-808f-5ff6-af84-edb034760c54

package/dist/sdk/history-compact.js

@@ -4,11 +4,11 @@
  * Implements the pm history compact 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]="31152621-df59-54a5-a28d-63119e734e6e")}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]="7570ecac-7f15-5a1b-9b2d-2f1744a00720")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { createHistoryEntry } from "../core/history/history.js";
+import { createHistoryEntry, hashHistoryStream, resealHistoryRewrite, } from "../core/history/history.js";
 import { selectHistoryCompactBulkTargets, } from "../core/history/history-compact-bulk.js";
 import { executeHistoryRewrite, writeHistoryRawWithRollback, } from "../core/history/history-rewrite.js";
 import { cloneEmptyReplayDocument, historyEntriesToRaw, replayHash, replayToItemDocument, toReplayDocument, verifyHistoryChain, } from "../core/history/replay.js";
@@ -106,11 +106,11 @@ function reanchorRetainedEntries(retainedEntries, seed, retainedEntryOffset) {
     for (const [index, entry] of retainedEntries.entries()) {
         const beforeHash = replayHash(replay);
         replay = applyHistoryPatch(replay, entry.patch, retainedEntryOffset + index + 1, entry.op);
-        rewritten.push({
+        rewritten.push(resealHistoryRewrite(entry, {
             ...entry,
             before_hash: beforeHash,
             after_hash: replayHash(replay),
-        });
+        }));
     }
     return {
         entries: rewritten,
@@ -169,6 +169,15 @@ function buildHistoryCompactEntries(params) {
         before: replayToItemDocument(cloneEmptyReplayDocument()),
         after: replayToItemDocument(checkpoint),
         message: buildHistoryCompactBaselineMessage(params.boundary),
+        context: {
+            history_compaction: {
+                contract_version: 1,
+                pruned_entry_count: params.boundary.compactCount,
+                pruned_stream_digest: hashHistoryStream(params.historyEntries.slice(0, params.boundary.compactCount)),
+                retained_proof: "stream_digest_and_checkpoint",
+                limitation: "individual_pruned_entries_require_pre_compaction_stream",
+            },
+        },
     });
     const rewrittenEntries = [baselineEntry, ...reanchored.entries];
     if (!params.dryRun) {
@@ -521,4 +530,4 @@ export async function runHistoryCompactBulk(options, global) {
     };
 }
 //# sourceMappingURL=history-compact.js.map
-//# debugId=31152621-df59-54a5-a28d-63119e734e6e
+//# debugId=7570ecac-7f15-5a1b-9b2d-2f1744a00720

package/dist/sdk/history-redact.js

@@ -4,11 +4,11 @@
  * Implements the pm history redact 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]="05b945f2-4f96-5f88-98ff-84cc856d0d57")}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]="bd1e86b0-6696-5fba-8dd4-b9636bf3ee60")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import { pathExists, readFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
-import { createHistoryEntry } from "../core/history/history.js";
+import { createHistoryEntry, resealHistoryRewrite, verifyHistoryRecordHash, } from "../core/history/history.js";
 import { invalidateHistoryDriftCacheForPath } from "../core/history/drift-cache.js";
 import { executeHistoryRewrite } from "../core/history/history-rewrite.js";
 import { EMPTY_REPLAY_DOCUMENT, historyEntriesToRaw, replayHash, replayToItemDocument, verifyHistoryChain, } from "../core/history/replay.js";
@@ -189,6 +189,22 @@ function redactUnknownValue(value, rules, replacement) {
         replacements: 0,
     };
 }
+function redactHistoryPatch(patch, rules, replacement) {
+    let replacements = 0;
+    const redactedPatch = patch.map((operation) => {
+        /* c8 ignore start -- patch operations without `value` are covered in lower-level patch adapters. */
+        if (!Object.prototype.hasOwnProperty.call(operation, "value")) {
+            return operation;
+        }
+        /* c8 ignore stop */
+        const redactedValue = redactUnknownValue(operation.value, rules, replacement);
+        replacements += redactedValue.replacements;
+        return redactedValue.replacements > 0
+            ? { ...operation, value: redactedValue.value }
+            : operation;
+    });
+    return { patch: redactedPatch, replacements };
+}
 function inspectHistoryIntegrity(entries) {
     let replay = structuredClone(EMPTY_REPLAY_DOCUMENT);
     let hashMismatchesBefore = 0;
@@ -214,6 +230,7 @@ function inspectHistoryIntegrity(entries) {
 function redactHistoryEntry(entry, rules, replacement) {
     let replacements = 0;
     let changed = false;
+    let reanchorEvidenceRedacted = false;
     let nextMessage = entry.message;
     if (typeof entry.message === "string") {
         const redactedMessage = redactStringValue(entry.message, rules, replacement);
@@ -223,31 +240,41 @@ function redactHistoryEntry(entry, rules, replacement) {
             changed = true;
         }
     }
-    const nextPatch = entry.patch.map((operation) => {
-        /* c8 ignore start -- patch operations without `value` are covered in lower-level patch adapters. */
-        if (!Object.prototype.hasOwnProperty.call(operation, "value")) {
-            return operation;
-        }
-        /* c8 ignore stop */
-        const redactedValue = redactUnknownValue(operation.value, rules, replacement);
-        replacements += redactedValue.replacements;
-        if (redactedValue.replacements > 0) {
-            changed = true;
-            return {
-                ...operation,
-                value: redactedValue.value,
-            };
-        }
-        return operation;
+    const redactedPatch = redactHistoryPatch(entry.patch, rules, replacement);
+    replacements += redactedPatch.replacements;
+    changed ||= redactedPatch.replacements > 0;
+    const nextReanchorEvidence = entry.reanchor_evidence?.map((evidence) => {
+        const redactedEvidencePatch = evidence.patch
+            ? redactHistoryPatch(evidence.patch, rules, replacement)
+            : { patch: undefined, replacements: 0 };
+        const redactedEvidenceRecord = evidence.record
+            ? redactUnknownValue(evidence.record, rules, replacement)
+            : { value: undefined, replacements: 0 };
+        replacements += redactedEvidencePatch.replacements;
+        replacements += redactedEvidenceRecord.replacements;
+        const evidenceChanged = redactedEvidencePatch.replacements > 0 ||
+            redactedEvidenceRecord.replacements > 0;
+        changed ||= evidenceChanged;
+        if (!evidenceChanged)
+            return evidence;
+        reanchorEvidenceRedacted = true;
+        const { patch: _sensitivePatch, record: _sensitiveRecord, record_hash: _priorRecordHash, record_hash_version: _priorRecordHashVersion, ...digestOnlyEvidence } = evidence;
+        return redactedEvidencePatch.replacements > 0
+            ? digestOnlyEvidence
+            : { ...digestOnlyEvidence, patch: evidence.patch };
     });
     return {
         entry: {
             ...entry,
             message: nextMessage,
-            patch: nextPatch,
+            patch: redactedPatch.patch,
+            ...(nextReanchorEvidence
+                ? { reanchor_evidence: nextReanchorEvidence }
+                : {}),
         },
         replacements,
         changed,
+        reanchorEvidenceRedacted,
     };
 }
 function rewriteHistoryEntries(entries, rules, replacement) {
@@ -256,7 +283,12 @@ function rewriteHistoryEntries(entries, rules, replacement) {
     let replacements = 0;
     const rewrittenEntries = [];
     for (let index = 0; index < entries.length; index += 1) {
-        const redacted = redactHistoryEntry(entries[index], rules, replacement);
+        const original = entries[index];
+        const recordVerification = verifyHistoryRecordHash(original);
+        if (!recordVerification.ok) {
+            throw new PmCliError(`history-redact refuses invalid immutable record ${index + 1} (${recordVerification.error}).`, EXIT_CODE.GENERIC_FAILURE);
+        }
+        const redacted = redactHistoryEntry(original, rules, replacement);
         replacements += redacted.replacements;
         if (redacted.changed) {
             entriesChanged += 1;
@@ -264,11 +296,14 @@ function rewriteHistoryEntries(entries, rules, replacement) {
         const beforeHash = replayHash(replay);
         replay = applyHistoryPatch(replay, redacted.entry.patch, index + 1, redacted.entry.op);
         const afterHash = replayHash(replay);
-        rewrittenEntries.push({
+        rewrittenEntries.push(resealHistoryRewrite(original, {
             ...redacted.entry,
             before_hash: beforeHash,
             after_hash: afterHash,
-        });
+        }, {
+            retainPriorRecord: redacted.changed,
+            retainPriorRecordHash: !redacted.changed,
+        }));
     }
     return {
         entries: rewrittenEntries,
@@ -606,4 +641,4 @@ export const _testOnly = {
     redactUnknownValue,
 };
 //# sourceMappingURL=history-redact.js.map
-//# debugId=05b945f2-4f96-5f88-98ff-84cc856d0d57
+//# debugId=bd1e86b0-6696-5fba-8dd4-b9636bf3ee60

package/dist/sdk/history-repair.js

@@ -4,7 +4,7 @@
  * 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]="151e5d26-d6f5-5fcf-84ab-ce89e2b7664e")}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]="cb0b0e36-3135-5fc4-a0ae-f4e5b974e57f")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import { realpath } from "node:fs/promises";
 import path from "node:path";
@@ -13,21 +13,24 @@ import { patchPathToChangedField } from "../core/history/history-diff.js";
 import { pathExists, readFileIfExists } from "../core/fs/fs-utils.js";
 import { executeHistoryRewrite, writeHistoryRawWithRollback, } from "../core/history/history-rewrite.js";
 import { historyEntriesToRaw, normalizeReplayPatchOps, reanchorHistoryEntries, replayHashVerificationCandidates, resolveHistoryRepairItemHashVersion, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
+import { sealHistoryRecord, } from "../core/history/history.js";
+import { classifyHistoryEvent } from "../core/history/event-classification.js";
 import { scanHistoryDrift } from "../core/history/drift-scan.js";
 import { invalidateHistoryDriftCache } from "../core/history/drift-cache.js";
 import { readHistoryEntries } from "../core/history/read.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.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 { 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 { inspectMergeReceiptEvidence, summarizeMergeReceipt, } from "./merge/receipts.js";
+import { encodeItemScalarDecisionValue, hashItemScalarDecisionValue, } from "./merge/three-way.js";
 import { listInvalidProvenanceHistoryStreamIds, normalizeInvalidHistoryProvenance, } from "./governance/provenance-health.js";
 function replayFieldValue(document, field) {
     return field === "body"
@@ -169,7 +172,10 @@ async function verifyReceiptAgainstSnapshot(params) {
     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 [
+            hashItemScalarDecisionValue(value),
+            sha256Hex(stableStringify(encodeItemScalarDecisionValue(value))),
+        ].includes(hashes[field]);
     });
     return valuesMatch ? { receipt: params.receipt, declaredFields } : null;
 }
@@ -316,7 +322,7 @@ function buildHistoryRepairEntries(params) {
     const previousAfterHash = params.reanchorEntries[params.reanchorEntries.length - 1].after_hash;
     const semanticIndex = beforeHashes.indexOf(previousAfterHash);
     const afterHashes = replayHashVerificationCandidates(afterReplay, params.itemHashVersion);
-    rewrittenEntries.push({
+    const auditEntry = {
         ts: nowIso(),
         author: params.author,
         op: params.auditOperation,
@@ -332,7 +338,11 @@ function buildHistoryRepairEntries(params) {
         ...(params.auditContext === undefined
             ? {}
             : { context: params.auditContext }),
-    });
+    };
+    rewrittenEntries.push(sealHistoryRecord({
+        ...auditEntry,
+        event_class: classifyHistoryEvent(auditEntry),
+    }));
     return { rewrittenEntries, auditEntryAdded: true };
 }
 function collectHistoryRepairWarnings(changed, skippedOps, reconciliation) {
@@ -598,4 +608,4 @@ export async function runHistoryRepairAll(options, global) {
     };
 }
 //# sourceMappingURL=history-repair.js.map
-//# debugId=151e5d26-d6f5-5fcf-84ab-ce89e2b7664e
+//# debugId=cb0b0e36-3135-5fc4-a0ae-f4e5b974e57f

package/dist/sdk/index.d.ts

@@ -14,6 +14,7 @@ export * from "./mcp/apps.js";
 export * from "./mcp/skills.js";
 export * from "./cli-contracts/grammar-contracts.js";
 export * from "./agent-session-context.js";
+export * from "./environment/agent-environment.js";
 export type { PmCommandCapabilityContract, PmCommandCapabilityFamily, PmCommandVisibilityContract, PmCommandVisibilityTier, PmMcpPromptArgumentContract, PmMcpPromptContract, PmMcpResourceContract, PmMcpToolProfile, } from "./agent-capability-contracts.js";
 export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, normalizeAnnotationTransportOptions, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, type AnnotationCommandConfig, type AnnotationCommandOptions, type AnnotationCommandResult, type AnnotationEntry, type AnnotationInput, type AnnotationHistoryRestoration, type AnnotationMutationReceipt, type AnnotationOmissionReceipt, type AnnotationSourceOptions, type OwnershipConflictGuidance, } from "./annotations.js";
 export { acknowledgeUnknownAuthorHistoryEvents, acknowledgeUnknownAuthorHistoryEventsFromTransport, inspectHistoryAuthorStream, parseUnknownAuthorHistoryEventCoordinates, planUnknownAuthorHistoryAcknowledgment, resolveUnknownAuthorAcknowledgmentSelector, scanHistoryAuthorAttribution, type AcknowledgeUnknownAuthorEventsOptions, type HistoryAuthorAttributionScan, type UnknownAuthorAcknowledgmentPlan, type UnknownAuthorAcknowledgmentPlanCoordinate, type UnknownAuthorAcknowledgmentResult, type UnknownAuthorHistoryEvent, } from "./author-attribution.js";
@@ -75,6 +76,7 @@ export * from "./governance/assurance-runtime.js";
 export * from "./governance/assurance-presets.js";
 export * from "./governance/boundary-fixtures.js";
 export * from "./governance/defect-recurrence.js";
+export * from "./governance/merge-receipt-history.js";
 export * from "./compile-cache.js";
 export * from "./environment/project-runtime-compatibility.js";
 export * from "./environment/source-context.js";

package/dist/sdk/index.js

@@ -4,7 +4,7 @@
  * 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]="62e450f7-9ed9-5855-923a-7b2ffb8b49f4")}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]="ea74fa78-184f-55e7-8c8e-fb912f4d26d8")}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";
@@ -16,6 +16,7 @@ export * from "./mcp/apps.js";
 export * from "./mcp/skills.js";
 export * from "./cli-contracts/grammar-contracts.js";
 export * from "./agent-session-context.js";
+export * from "./environment/agent-environment.js";
 export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, normalizeAnnotationTransportOptions, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, } from "./annotations.js";
 export { acknowledgeUnknownAuthorHistoryEvents, acknowledgeUnknownAuthorHistoryEventsFromTransport, inspectHistoryAuthorStream, parseUnknownAuthorHistoryEventCoordinates, planUnknownAuthorHistoryAcknowledgment, resolveUnknownAuthorAcknowledgmentSelector, scanHistoryAuthorAttribution, } from "./author-attribution.js";
 export { BUILTIN_CORPUS_SHAPES, PM_CORPUS_SHAPE_SCHEMA, buildCorpusShapeItemPlan, createCorpusShapeMeasurement, defineCorpusShape, listBuiltinCorpusShapes, measureCorpusShapePlan, resolveBuiltinCorpusShape, } from "./corpus-shape.js";
@@ -72,6 +73,7 @@ export * from "./governance/assurance-runtime.js";
 export * from "./governance/assurance-presets.js";
 export * from "./governance/boundary-fixtures.js";
 export * from "./governance/defect-recurrence.js";
+export * from "./governance/merge-receipt-history.js";
 export * from "./compile-cache.js";
 export * from "./environment/project-runtime-compatibility.js";
 export * from "./environment/source-context.js";
@@ -179,4 +181,4 @@ export * from "./mcp/discovery.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=62e450f7-9ed9-5855-923a-7b2ffb8b49f4
+//# debugId=ea74fa78-184f-55e7-8c8e-fb912f4d26d8

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

@@ -56,7 +56,9 @@ export interface MergeDriverResult {
     item?: {
         fields_from_theirs: string[];
         union_fields: string[];
-        conflict_resolution: "stable_value_order";
+        conflict_resolution: "latest_document_update";
+        /** Item scalars ignore branch-direction preference under the convergent recency policy. */
+        requested_preference_applied: false;
     };
     /** JSON-merge key accounting; present only for the json artifact. */
     json?: {

package/dist/sdk/merge/driver.js

@@ -9,7 +9,7 @@
  * 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]="2c8046a5-06aa-58f8-b347-e757086082d1")}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]="5dc5f70c-0b04-51bb-983b-49b15be11587")}catch(e){}}();
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
@@ -18,11 +18,10 @@ 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";
-import { mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, mergeRelationshipEventStreams, } from "./three-way.js";
+import { hashItemScalarDecisionValue, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, mergeRelationshipEventStreams, } from "./three-way.js";
 import { summarizeMergeReceipt, writeMergeReceipt, } from "./receipts.js";
 /** Supported values accepted by the merge driver artifact contract across CLI, SDK, and MCP surfaces. */
 export const MERGE_DRIVER_ARTIFACT_VALUES = [
@@ -131,14 +130,15 @@ export async function runMergeDriver(options, global) {
             schema: settings?.schema,
             extensionFieldNames,
             preferred,
-            conflictResolution: "stable_value_order",
+            conflictResolution: "latest_document_update",
         });
         merged = itemMerge.merged;
         conflicts.push(...itemMerge.conflict_fields);
         result.item = {
             fields_from_theirs: itemMerge.fields_from_theirs,
             union_fields: itemMerge.union_fields,
-            conflict_resolution: "stable_value_order",
+            conflict_resolution: "latest_document_update",
+            requested_preference_applied: false,
         };
         if (options.itemPath !== undefined) {
             const mergedDocument = parseItemDocument(merged, {
@@ -158,12 +158,12 @@ export async function runMergeDriver(options, global) {
                 cwd: process.cwd(),
                 itemPath: options.itemPath,
                 preferred,
-                conflictResolution: "stable_value_order",
+                conflictResolution: "latest_document_update",
                 fieldsFromTheirs: itemMerge.fields_from_theirs,
                 unionFields: itemMerge.union_fields,
                 mergedFieldHashes: Object.fromEntries(receiptFields.map((field) => [
                     field,
-                    sha256Hex(stableStringify(field === "body" ? mergedDocument.body : mergedMetadata[field])),
+                    hashItemScalarDecisionValue(field === "body" ? mergedDocument.body : mergedMetadata[field]),
                 ])),
                 decisions: itemMerge.conflict_decisions,
             };
@@ -191,7 +191,7 @@ export async function runMergeDriver(options, global) {
         const receiptGuidance = result.receipt === undefined
             ? 'Run "pm merge report" to inspect clone-local merge evidence.'
             : `Run "pm merge report" and correlate receipt ${result.receipt.receipt_id} with item ${result.receipt.item_id}; clone-local discarded values are never copied into this result.`;
-        guidance.push(`Both branches changed ${conflicts.join(", ")}; the item driver kept the direction-independent stable value. ${receiptGuidance} Review the merged file, re-apply the discarded change if needed, then "git add" it.`);
+        guidance.push(`Both branches changed ${conflicts.join(", ")}; the item driver kept the value from the later document update, with stable value order only as an equal-timestamp tie-break. --prefer does not apply to convergent item scalar conflicts. ${receiptGuidance} Review the merged file, re-apply the discarded change if needed, then "git add" it.`);
     }
     if (artifact === "history" && result.history?.reanchored) {
         guidance.push('The merged history chain was re-anchored. Run "pm merge reconcile --dry-run" to inspect the complete post-merge repair, then "pm merge reconcile" to apply it; use --force only after explicitly accepting reported discards.');
@@ -208,4 +208,4 @@ export async function runMergeDriver(options, global) {
     };
 }
 //# sourceMappingURL=driver.js.map
-//# debugId=2c8046a5-06aa-58f8-b347-e757086082d1
+//# debugId=5dc5f70c-0b04-51bb-983b-49b15be11587