@unbrained/pm-cli 2026.9.3 → 2026.9.4

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

@@ -1,12 +1,6 @@
-/**
- * @module sdk/merge/reconcile
- *
- * Provides the post-merge SDK workflow that previews or repairs every drifted
- * item-history stream, then verifies history and storage integrity in one call.
- */
 import type { GlobalOptions } from "../../core/shared/command-types.js";
-import { type HistoryRepairAllResult } from "../history-repair.js";
 import { type ValidateResult } from "../governance/validate.js";
+import { type HistoryRepairAllResult } from "../history-repair.js";
 import { type MergeDecisionReceiptSummary } from "./receipts.js";
 /** Options for the audited post-merge reconciliation workflow. */
 export interface MergeReconcileOptions {
@@ -36,6 +30,14 @@ export interface MergeReconcileResult {
         pending_before: number;
         reconciled: number;
         summaries: MergeDecisionReceiptSummary[];
+        /** Missing durable references discovered before this reconciliation. */
+        missing_history_references_before: number;
+        /** Pre-durable references eligible for explicit audited disposition. */
+        legacy_disposition_eligible: number;
+        /** Eligible references dispositioned by this apply pass. */
+        legacy_disposition_recorded: number;
+        /** Missing durable references still blocking health after this pass. */
+        missing_history_references_after: number;
     };
     /** Post-operation history-drift and storage-integrity validation. */
     validation: ValidateResult;

package/dist/sdk/merge/reconcile.js

@@ -1,14 +1,135 @@
+/**
+ * @module sdk/merge/reconcile
+ *
+ * Provides the post-merge SDK workflow that previews or repairs every drifted
+ * item-history stream, then verifies history and storage integrity in one call.
+ */
 
-!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]="8d85d220-dad2-5234-8819-65632275eb47")}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]="3a3372be-37e4-578a-8be9-9ad7bc585dbd")}catch(e){}}();
+import { readFile } from "node:fs/promises";
+import path from "node:path";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
+import { compareTimestampStrings } from "../../core/shared/time.js";
 import { resolvePmRoot } from "../../core/store/paths.js";
-import { runHistoryRepair, runHistoryRepairAll, } from "../history-repair.js";
+import { mapWithFixedConcurrency } from "../extension/concurrency.js";
+import { runHealth } from "../governance/health.js";
+import { DURABLE_MERGE_RECEIPT_INTRODUCED_AT, extractHistoryMergeReceiptReferences, isPreDurableDispositionEligibleReference, } from "../governance/merge-receipt-history.js";
 import { runValidate } from "../governance/validate.js";
-import { inspectMergeReceiptEvidence, markMergeReceiptReconciled, summarizeMergeReceipt, } from "./receipts.js";
+import { runHistoryRepair, runHistoryRepairAll, } from "../history-repair.js";
 import { findGitWorkspaceRoot } from "./install.js";
-import { mapWithFixedConcurrency } from "../extension/concurrency.js";
+import { inspectMergeReceiptEvidence, markMergeReceiptReconciled, summarizeMergeReceipt, } from "./receipts.js";
 const RECEIPT_ONLY_REPAIR_CONCURRENCY = 4;
+/** Extract bounded item, line, and receipt coordinates from health evidence. */
+function missingReceiptCoordinates(health) {
+    const integrity = health.checks.find((check) => check.name === "integrity");
+    const counts = integrity?.details.counts;
+    const count = typeof counts === "object" &&
+        counts !== null &&
+        !Array.isArray(counts) &&
+        typeof counts
+            .missing_merge_receipt_history_references === "number"
+        ? counts
+            .missing_merge_receipt_history_references
+        : 0;
+    const details = integrity?.details.missing_merge_receipt_history_reference_details;
+    const truncated = integrity?.details
+        .missing_merge_receipt_history_reference_details_truncated === true;
+    const coordinates = Array.isArray(details)
+        ? details.flatMap((detail) => {
+            if (typeof detail !== "object" ||
+                detail === null ||
+                Array.isArray(detail)) {
+                return [];
+            }
+            const record = detail;
+            return typeof record.item_id === "string" &&
+                typeof record.history_line === "number" &&
+                Number.isSafeInteger(record.history_line) &&
+                typeof record.receipt_id === "string"
+                ? [
+                    {
+                        item_id: record.item_id,
+                        history_line: record.history_line,
+                        receipt_id: record.receipt_id,
+                    },
+                ]
+                : [];
+        })
+        : [];
+    return { count, truncated, coordinates };
+}
+/** Re-read history and retain only exact pre-durable clone-local references. */
+async function identifyLegacyDispositionCandidates(pmRoot, coordinates) {
+    const candidates = [];
+    for (const coordinate of coordinates) {
+        let raw;
+        try {
+            raw = await readFile(path.join(pmRoot, "history", `${coordinate.item_id}.jsonl`), "utf8");
+        }
+        catch {
+            continue;
+        }
+        const line = raw.split(/\r?\n/)[coordinate.history_line - 1];
+        if (line === undefined || line.trim().length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const reference = extractHistoryMergeReceiptReferences(parsed, coordinate.item_id).find((entry) => entry.receiptId === coordinate.receipt_id);
+        if (reference === undefined ||
+            !isPreDurableDispositionEligibleReference(reference) ||
+            reference.eventTimestamp === undefined ||
+            compareTimestampStrings(reference.eventTimestamp, DURABLE_MERGE_RECEIPT_INTRODUCED_AT) >= 0) {
+            continue;
+        }
+        candidates.push({
+            ...coordinate,
+            original_event_ts: reference.eventTimestamp,
+        });
+    }
+    return candidates;
+}
+/** Append auditable dispositions for eligible receipts that cannot be restored. */
+async function recordLegacyReceiptDispositions(params) {
+    if (params.options.dryRun === true ||
+        params.options.force !== true ||
+        params.candidates.length === 0) {
+        return 0;
+    }
+    const byItem = new Map();
+    for (const candidate of params.candidates) {
+        const itemCandidates = byItem.get(candidate.item_id) ?? [];
+        itemCandidates.push(candidate);
+        byItem.set(candidate.item_id, itemCandidates);
+    }
+    for (const [itemId, itemCandidates] of byItem) {
+        await runHistoryRepair(itemId, {
+            author: params.options.author ?? params.global.author,
+            message: params.options.message ??
+                "accept unrecoverable pre-durable merge receipt references",
+            force: true,
+            auditOperation: "merge_reconcile",
+            forceAuditEntry: true,
+            auditContext: {
+                merge: {
+                    missing_receipt_dispositions: itemCandidates.map((candidate) => ({
+                        receipt_id: candidate.receipt_id,
+                        original_history_line: candidate.history_line,
+                        original_event_ts: candidate.original_event_ts,
+                        reason: "legacy_clone_local_only",
+                    })),
+                },
+            },
+        }, params.global);
+    }
+    return params.candidates.length;
+}
+/** Execute one receipt-backed repair while preserving its settled result. */
 async function runReceiptOnlyRepair(params) {
     try {
         return {
@@ -30,6 +151,7 @@ async function runReceiptOnlyRepair(params) {
         return { status: "rejected", reason };
     }
 }
+/** Fold settled receipt repairs into the aggregate reconciliation result. */
 function appendReceiptOnlyResults(params) {
     params.results.forEach((settled, index) => {
         const id = params.receiptOnlyIds[index];
@@ -59,15 +181,14 @@ function appendReceiptOnlyResults(params) {
         params.repair.totals.failed += 1;
     });
 }
+/** Settle only receipts named by successful trusted repair evidence. */
 async function settleProvenReceipts(params) {
     if (params.dryRun || params.repair.totals.failed > 0)
         return 0;
     const trustedReceiptIds = new Set(params.repair.streams.flatMap((stream) => stream.merge_receipt_proof?.trusted
         ? stream.merge_receipt_proof.receipt_ids
         : []));
-    const receiptsToSettle = params.force
-        ? params.pendingReceipts
-        : params.pendingReceipts.filter((receipt) => trustedReceiptIds.has(receipt.id));
+    const receiptsToSettle = params.pendingReceipts.filter((receipt) => trustedReceiptIds.has(receipt.id));
     await Promise.all(receiptsToSettle.map((receipt) => markMergeReceiptReconciled(params.gitWorkspaceRoot ?? process.cwd(), receipt, { requireExisting: true })));
     return receiptsToSettle.length;
 }
@@ -80,6 +201,14 @@ async function settleProvenReceipts(params) {
 export async function runMergeReconcile(options, global) {
     const dryRun = options.dryRun === true;
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    const preflightHealth = await runHealth(global, {
+        checkOnly: true,
+        full: true,
+        skipVectors: true,
+        skipDrift: true,
+    });
+    const missingBefore = missingReceiptCoordinates(preflightHealth);
+    const legacyDispositionCandidates = await identifyLegacyDispositionCandidates(pmRoot, missingBefore.coordinates);
     const gitWorkspaceRoot = await findGitWorkspaceRoot(pmRoot);
     const receiptEvidence = await inspectMergeReceiptEvidence(gitWorkspaceRoot ?? process.cwd(), {
         includeLossless: true,
@@ -94,6 +223,11 @@ export async function runMergeReconcile(options, global) {
             },
         });
     }
+    const recordedLegacyDispositionCount = await recordLegacyReceiptDispositions({
+        candidates: legacyDispositionCandidates,
+        options,
+        global,
+    });
     const pendingReceipts = receiptEvidence.receipts;
     const receiptsByItem = new Map();
     for (const receipt of pendingReceipts) {
@@ -140,20 +274,38 @@ export async function runMergeReconcile(options, global) {
     });
     const reconciledReceiptCount = await settleProvenReceipts({
         dryRun,
-        force: options.force === true,
         pendingReceipts,
         repair,
         gitWorkspaceRoot,
     });
     const validation = await runValidate({ checkHistoryDrift: true, checkStorageIntegrity: true }, global);
+    const postflightHealth = recordedLegacyDispositionCount === 0
+        ? preflightHealth
+        : await runHealth(global, {
+            checkOnly: true,
+            full: true,
+            skipVectors: true,
+            skipDrift: true,
+        });
+    const missingAfter = missingReceiptCoordinates(postflightHealth);
     const mergeChecksGreen = validation.checks.every((check) => check.status === "ok");
     const receiptSettlementComplete = dryRun
         ? pendingReceipts.length === 0
         : reconciledReceiptCount === pendingReceipts.length;
-    const ok = repair.totals.failed === 0 && mergeChecksGreen && receiptSettlementComplete;
-    const guidance = dryRun
+    const ok = [
+        repair.totals.failed === 0,
+        mergeChecksGreen,
+        receiptSettlementComplete,
+        missingAfter.count === 0,
+        !missingAfter.truncated,
+    ].every(Boolean);
+    const boundedBatchGuidance = missingBefore.truncated || missingAfter.truncated
+        ? "Missing receipt coordinates exceed the bounded detail response; each reviewed --force pass can disposition only the reported eligible batch. Repeat dry-run and --force passes until receipts.missing_history_references_after=0 and pm merge reconcile returns ok=true."
+        : undefined;
+    const guidance = (dryRun
         ? [
             "Review repair.streams, then rerun pm merge reconcile without --dry-run to apply audited repairs.",
+            boundedBatchGuidance,
             "No Git hook is installed automatically; invoke this command from an explicit post-merge hook only when your repository policy opts in.",
         ]
         : ok
@@ -163,8 +315,15 @@ export async function runMergeReconcile(options, global) {
             ]
             : [
                 "Reconciliation remains incomplete; inspect repair failures and non-green validation checks before retrying.",
+                boundedBatchGuidance,
+                ...(legacyDispositionCandidates.length > 0 &&
+                    recordedLegacyDispositionCount === 0
+                    ? [
+                        "Pre-durable clone-local-only receipt references are eligible for an audited disposition; rerun with --force after reviewing receipts.legacy_disposition_eligible.",
+                    ]
+                    : []),
                 "Do not commit repaired history streams as reconciled until pm merge reconcile returns ok=true.",
-            ];
+            ]).filter((message) => message !== undefined);
     return {
         ok,
         dry_run: dryRun,
@@ -173,6 +332,10 @@ export async function runMergeReconcile(options, global) {
             pending_before: pendingReceipts.length,
             reconciled: reconciledReceiptCount,
             summaries: pendingReceipts.map(summarizeMergeReceipt),
+            missing_history_references_before: missingBefore.count,
+            legacy_disposition_eligible: legacyDispositionCandidates.length,
+            legacy_disposition_recorded: recordedLegacyDispositionCount,
+            missing_history_references_after: missingAfter.count,
         },
         validation,
         guidance,
@@ -180,4 +343,4 @@ export async function runMergeReconcile(options, global) {
     };
 }
 //# sourceMappingURL=reconcile.js.map
-//# debugId=8d85d220-dad2-5234-8819-65632275eb47
+//# debugId=3a3372be-37e4-578a-8be9-9ad7bc585dbd

package/dist/sdk/merge/three-way.d.ts

@@ -1,6 +1,20 @@
 import { type ItemDocumentFormatOptions } from "../../core/item/item-format.js";
 /** Restricts which side of a three-way merge wins an unresolvable conflict. */
 export type MergePreferredSide = "ours" | "theirs";
+/** Declares how competing item scalar writes select their retained value. */
+export type ItemScalarConflictResolution = "preferred_side" | "stable_value_order" | "latest_document_update";
+/** Explains the exact evidence used to select one conflicting item scalar. */
+export type ItemScalarResolutionBasis = "requested_preference" | "document_updated_at" | "stable_value_tiebreak";
+/** JSON-stable marker used when a conflict decision refers to an absent scalar. */
+export declare const ITEM_SCALAR_MISSING_VALUE: Readonly<{
+    readonly pm_item_scalar_missing: true;
+}>;
+/** Return whether receipt evidence represents an absent item scalar. */
+export declare function isItemScalarMissingValue(value: unknown): value is typeof ITEM_SCALAR_MISSING_VALUE;
+/** Encode an absent scalar so every decision property survives JSON serialization. */
+export declare function encodeItemScalarDecisionValue(value: unknown): unknown;
+/** Hash scalars in disjoint present/missing domains for collision-free evidence. */
+export declare function hashItemScalarDecisionValue(value: unknown): string;
 /** Restricts the strategy labels reported by the history stream merge. */
 export type HistoryMergeStrategy = "identical" | "fast_forward_ours" | "fast_forward_theirs" | "union_reanchor";
 /** Documents the history stream merge result payload exchanged by command, SDK, and package integrations. */
@@ -87,6 +101,10 @@ export interface ItemMergeConflictDecision {
     retained: unknown;
     /** Value not retained in the merged item. */
     discarded: unknown;
+    /** Branch coordinate whose value was retained. */
+    retained_side?: MergePreferredSide;
+    /** Evidence class that selected the retained value. */
+    resolution_basis?: ItemScalarResolutionBasis;
 }
 /** Documents the item document merge result payload exchanged by command, SDK, and package integrations. */
 export interface ItemDocumentMergeResult {
@@ -102,8 +120,10 @@ export interface ItemDocumentMergeResult {
     conflict_decisions: ItemMergeConflictDecision[];
     /** Side requested by the caller; stable-value decisions can retain either side. */
     requested_preference: MergePreferredSide;
+    /** Whether the requested side participates in item scalar selection under the declared policy. */
+    requested_preference_applied: boolean;
     /** Scalar-conflict selection contract used for this merge. */
-    conflict_resolution: "preferred_side" | "stable_value_order";
+    conflict_resolution: ItemScalarConflictResolution;
 }
 /**
  * Field-aware three-way merge of one tracker item document. Commutative
@@ -121,7 +141,7 @@ export declare function mergeItemDocuments(baseRaw: string, oursRaw: string, the
     /** Side that wins unresolvable conflicts (default "ours"). */
     preferred?: MergePreferredSide;
     /** Direction-independent scalar selection used by the Git driver. */
-    conflictResolution?: "preferred_side" | "stable_value_order";
+    conflictResolution?: ItemScalarConflictResolution;
 }): ItemDocumentMergeResult;
 /** Documents the JSON document merge result payload exchanged by command, SDK, and package integrations. */
 export interface JsonDocumentMergeResult {

package/dist/sdk/merge/three-way.js

@@ -9,14 +9,37 @@
  * definition for multi-branch agent workflows.
  */
 
-!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]="7e8fcddf-09fe-5979-b23a-78915bf7f896")}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]="4d5434c7-544b-5061-89eb-6e4074e58e30")}catch(e){}}();
 import { historyEntriesToRaw, reanchorHistoryEntries, } from "../../core/history/replay.js";
 import { canonicalDocument, parseItemDocument, serializeItemDocument, } from "../../core/item/item-format.js";
+import { splitAcceptanceCriteria } from "../../core/item/parse.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { findFirstMergeConflictMarker } from "../../core/shared/conflict-markers.js";
 import { PmCliError } from "../../core/shared/errors.js";
-import { stableStringify } from "../../core/shared/serialization.js";
+import { sha256Hex, stableStringify } from "../../core/shared/serialization.js";
 import { compareTimestampStrings } from "../../core/shared/time.js";
+/** JSON-stable marker used when a conflict decision refers to an absent scalar. */
+export const ITEM_SCALAR_MISSING_VALUE = Object.freeze({
+    pm_item_scalar_missing: true,
+});
+/** Return whether receipt evidence represents an absent item scalar. */
+export function isItemScalarMissingValue(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.keys(value).length === 1 &&
+        value.pm_item_scalar_missing === true);
+}
+/** Encode an absent scalar so every decision property survives JSON serialization. */
+export function encodeItemScalarDecisionValue(value) {
+    return value === undefined ? ITEM_SCALAR_MISSING_VALUE : value;
+}
+/** Hash scalars in disjoint present/missing domains for collision-free evidence. */
+export function hashItemScalarDecisionValue(value) {
+    return sha256Hex(stableStringify(value === undefined
+        ? { pm_item_scalar_presence: "missing" }
+        : { pm_item_scalar_presence: "present", value }));
+}
 function parseHistoryJsonl(raw, label) {
     const conflictMarker = findFirstMergeConflictMarker(raw);
     if (conflictMarker) {
@@ -294,10 +317,15 @@ export const ITEM_UNION_COLLECTION_FIELDS = [
     "reminders",
     "events",
 ];
+/** Delimiter-backed list fields that use the same lossless element merge as native metadata collections while retaining their legacy scalar storage shape. */
+const ITEM_UNION_DELIMITED_FIELDS = ["acceptance_criteria"];
 /** Item metadata fields resolved by deterministic latest-timestamp-wins instead of three-way conflict, so disjoint-field edits never conflict on the shared freshness scalar every mutation rewrites. */
 export const ITEM_LATEST_TIMESTAMP_FIELDS = ["updated_at"];
 function jsonEquals(left, right) {
-    return stableStringify(left ?? null) === stableStringify(right ?? null);
+    if (left === undefined || right === undefined) {
+        return left === undefined && right === undefined;
+    }
+    return stableStringify(left) === stableStringify(right);
 }
 function unionCollection(base, ours, theirs) {
     const toEntries = (value) => Array.isArray(value) ? value : [];
@@ -393,24 +421,51 @@ function mergeScalarThreeWay(base, ours, theirs, preferred) {
         conflict: true,
     };
 }
-function mergeItemScalarThreeWay(base, ours, theirs, preferred, conflictResolution) {
+/** Resolve one item scalar with explicit recency and deterministic tie evidence. */
+function mergeItemScalarThreeWay(base, ours, theirs, preferred, conflictResolution, oursUpdatedAt, theirsUpdatedAt) {
     const outcome = mergeScalarThreeWay(base, ours, theirs, preferred);
-    if (!outcome.conflict || conflictResolution === "preferred_side") {
-        return outcome;
+    if (!outcome.conflict) {
+        return { ...outcome, conflict: false };
+    }
+    if (conflictResolution === "preferred_side") {
+        return {
+            ...outcome,
+            resolution_basis: "requested_preference",
+            retained_side: outcome.from_theirs ? "theirs" : "ours",
+        };
+    }
+    const timestampOrder = compareTimestampStrings(oursUpdatedAt, theirsUpdatedAt);
+    if (conflictResolution === "latest_document_update" && timestampOrder !== 0) {
+        const retainTheirs = timestampOrder < 0;
+        return {
+            value: retainTheirs ? theirs : ours,
+            from_theirs: retainTheirs,
+            conflict: true,
+            resolution_basis: "document_updated_at",
+            retained_side: retainTheirs ? "theirs" : "ours",
+        };
     }
-    const retainTheirs = stableStringify(theirs).localeCompare(stableStringify(ours)) < 0;
+    const retainTheirs = stableStringify(encodeItemScalarDecisionValue(theirs)).localeCompare(stableStringify(encodeItemScalarDecisionValue(ours))) < 0;
     return {
         value: retainTheirs ? theirs : ours,
         from_theirs: retainTheirs,
         conflict: true,
+        resolution_basis: "stable_value_tiebreak",
+        retained_side: retainTheirs ? "theirs" : "ours",
     };
 }
 function toMetadataRecord(document) {
     return { ...document.metadata };
 }
+/** Parse one merge side and reject values reserved for internal absence evidence. */
 function parseItemMergeSide(raw, label, options) {
     try {
-        return canonicalDocument(parseItemDocument(raw, options), options);
+        const document = canonicalDocument(parseItemDocument(raw, options), options);
+        const reservedField = Object.entries(document.metadata).find(([, value]) => isItemScalarMissingValue(value))?.[0];
+        if (reservedField !== undefined) {
+            throw new TypeError(`metadata field ${reservedField} uses the reserved missing-scalar evidence marker`);
+        }
+        return document;
     }
     catch (error) {
         throw new PmCliError(`Item merge input (${label}) is not a readable item document: ${String(error)}`, EXIT_CODE.GENERIC_FAILURE);
@@ -422,7 +477,9 @@ function mergeItemUnionField(params) {
         return false;
     const union = params.field === "tests"
         ? unionLinkedTests(params.baseValue, params.oursValue, params.theirsValue)
-        : unionCollection(params.baseValue, params.oursValue, params.theirsValue);
+        : params.field === "acceptance_criteria"
+            ? unionCollection(splitAcceptanceCriteria(params.baseValue), splitAcceptanceCriteria(params.oursValue), splitAcceptanceCriteria(params.theirsValue)).join("; ")
+            : unionCollection(params.baseValue, params.oursValue, params.theirsValue);
     params.accumulator.merged[params.field] = union;
     if (!jsonEquals(union, params.oursValue)) {
         params.accumulator.unionFields.push(params.field);
@@ -431,7 +488,7 @@ function mergeItemUnionField(params) {
 }
 /** Merge one scalar field while preserving conflict evidence. */
 function mergeItemScalarField(params) {
-    const outcome = mergeItemScalarThreeWay(params.baseValue, params.oursValue, params.theirsValue, params.preferred, params.conflictResolution);
+    const outcome = mergeItemScalarThreeWay(params.baseValue, params.oursValue, params.theirsValue, params.preferred, params.conflictResolution, params.oursUpdatedAt, params.theirsUpdatedAt);
     if (outcome.value !== undefined) {
         params.accumulator.merged[params.field] = outcome.value;
     }
@@ -439,19 +496,24 @@ function mergeItemScalarField(params) {
         params.accumulator.conflictFields.push(params.field);
         params.accumulator.conflictDecisions.push({
             field: params.field,
-            base: params.baseValue,
-            ours: params.oursValue,
-            theirs: params.theirsValue,
-            retained: outcome.value,
-            discarded: outcome.from_theirs ? params.oursValue : params.theirsValue,
+            base: encodeItemScalarDecisionValue(params.baseValue),
+            ours: encodeItemScalarDecisionValue(params.oursValue),
+            theirs: encodeItemScalarDecisionValue(params.theirsValue),
+            retained: encodeItemScalarDecisionValue(outcome.value),
+            discarded: encodeItemScalarDecisionValue(outcome.from_theirs ? params.oursValue : params.theirsValue),
+            retained_side: outcome.retained_side,
+            resolution_basis: outcome.resolution_basis,
         });
     }
     else if (outcome.from_theirs) {
         params.accumulator.fieldsFromTheirs.push(params.field);
     }
 }
-function mergeItemMetadataRecords(baseRecord, oursRecord, theirsRecord, preferred, conflictResolution) {
-    const unionFieldSet = new Set(ITEM_UNION_COLLECTION_FIELDS);
+function mergeItemMetadataRecords(baseRecord, oursRecord, theirsRecord, preferred, conflictResolution, oursUpdatedAt, theirsUpdatedAt) {
+    const unionFieldSet = new Set([
+        ...ITEM_UNION_COLLECTION_FIELDS,
+        ...ITEM_UNION_DELIMITED_FIELDS,
+    ]);
     const latestFieldSet = new Set(ITEM_LATEST_TIMESTAMP_FIELDS);
     const fieldNames = [
         ...new Set([...Object.keys(oursRecord), ...Object.keys(theirsRecord)]),
@@ -491,6 +553,8 @@ function mergeItemMetadataRecords(baseRecord, oursRecord, theirsRecord, preferre
             theirsValue,
             preferred,
             conflictResolution,
+            oursUpdatedAt,
+            theirsUpdatedAt,
             accumulator,
         });
     }
@@ -523,17 +587,19 @@ export function mergeItemDocuments(baseRaw, oursRaw, theirsRaw, options = {}) {
         : {};
     const oursRecord = toMetadataRecord(ours);
     const theirsRecord = toMetadataRecord(theirs);
-    const { merged, conflictFields, fieldsFromTheirs, unionFields, conflictDecisions, } = mergeItemMetadataRecords(baseRecord, oursRecord, theirsRecord, preferred, conflictResolution);
-    const bodyOutcome = mergeItemScalarThreeWay(hasBase ? base.body : "", ours.body, theirs.body, preferred, conflictResolution);
+    const { merged, conflictFields, fieldsFromTheirs, unionFields, conflictDecisions, } = mergeItemMetadataRecords(baseRecord, oursRecord, theirsRecord, preferred, conflictResolution, ours.metadata.updated_at, theirs.metadata.updated_at);
+    const bodyOutcome = mergeItemScalarThreeWay(hasBase ? base.body : "", ours.body, theirs.body, preferred, conflictResolution, ours.metadata.updated_at, theirs.metadata.updated_at);
     if (bodyOutcome.conflict) {
         conflictFields.push("body");
         conflictDecisions.push({
             field: "body",
-            base: hasBase ? base.body : "",
-            ours: ours.body,
-            theirs: theirs.body,
-            retained: bodyOutcome.value,
-            discarded: bodyOutcome.from_theirs ? ours.body : theirs.body,
+            base: encodeItemScalarDecisionValue(hasBase ? base.body : ""),
+            ours: encodeItemScalarDecisionValue(ours.body),
+            theirs: encodeItemScalarDecisionValue(theirs.body),
+            retained: encodeItemScalarDecisionValue(bodyOutcome.value),
+            discarded: encodeItemScalarDecisionValue(bodyOutcome.from_theirs ? ours.body : theirs.body),
+            retained_side: bodyOutcome.retained_side,
+            resolution_basis: bodyOutcome.resolution_basis,
         });
     }
     else if (bodyOutcome.from_theirs) {
@@ -550,6 +616,7 @@ export function mergeItemDocuments(baseRaw, oursRaw, theirsRaw, options = {}) {
         union_fields: unionFields,
         conflict_decisions: conflictDecisions,
         requested_preference: preferred,
+        requested_preference_applied: conflictResolution === "preferred_side",
         conflict_resolution: conflictResolution,
     };
 }
@@ -706,4 +773,4 @@ export function mergeJsonDocuments(baseRaw, oursRaw, theirsRaw, options = {}) {
     };
 }
 //# sourceMappingURL=three-way.js.map
-//# debugId=7e8fcddf-09fe-5979-b23a-78915bf7f896
+//# debugId=4d5434c7-544b-5061-89eb-6e4074e58e30

package/dist/sdk/runtime-primitives.d.ts

@@ -17,10 +17,10 @@ export { isFileMissingError, pathExists, readFileIfExists, removeFileIfExists, w
 export { normalizeBulkIdsValue, parseBulkIdsText, resolveCliBulkIdsInput, type BulkIdsFileReader, type BulkIdsInputReaders, type BulkIdsStdinReader, type BulkIdsValue, } from "../core/io/bulk-ids-input.js";
 export { type HistoryDiffValueEntry, computeHistoryDiff, patchPathToChangedField, } from "../core/history/history-diff.js";
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
-export { appendHistoryEntry, CURRENT_HISTORY_ITEM_HASH_VERSION, createHistoryEntry, hashDocument, hashDocumentForVersion, hashEmptyDocument, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, type HistoryItemHashVersion, } from "../core/history/history.js";
+export { appendHistoryEntry, CURRENT_HISTORY_ITEM_HASH_VERSION, CURRENT_HISTORY_RECORD_HASH_VERSION, createHistoryEntry, hashDocument, hashDocumentForVersion, hashEmptyDocument, hashHistoryPatch, hashHistoryRecord, hashHistoryStream, resealHistoryRewrite, sealHistoryRecord, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, SUPPORTED_HISTORY_RECORD_HASH_VERSIONS, verifyHistoryRecordHash, verifyHistoryRewriteEvidence, type HistoryItemHashVersion, type HistoryRecordHashVersion, } from "../core/history/history.js";
 export { readHistoryEntries } from "../core/history/read.js";
 export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, inspectWorkspaceHistoryState, mutateWorkspaceJsonWithHistory, reconcileWorkspaceJsonHistory, restoreWorkspaceJsonFromHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, type WorkspaceAuditEventOptions, type WorkspaceHistoryChange, type WorkspaceHistoryStateAgreement, type WorkspaceJsonMutation, type WorkspaceJsonMutationOptions, type WorkspaceJsonReconciliationOptions, type WorkspaceJsonRestoreOptions, type WorkspaceJsonRestoreResult, type WorkspaceJsonWriteOptions, } from "../core/history/workspace-history.js";
-export { normalizeReplayPatchOps, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
+export { normalizeReplayPatchOps, reanchorHistoryEntries, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
 export { resolveBodyFileContent } from "../core/io/body-file.js";
 export { generateItemId, normalizeItemId, normalizeRawItemId, } from "../core/item/id.js";
 export { canonicalDocument, normalizeItemMetadata, parseItemDocument, serializeItemDocument, } from "../core/item/item-format.js";

package/dist/sdk/runtime-primitives.js

@@ -7,7 +7,7 @@
  * prefer the typed operations exported by the main SDK barrel.
  */
 
-!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]="d45775e5-6826-521b-80b3-429ed22947d9")}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]="aba5403c-0694-5c51-95a8-ae7e7575347b")}catch(e){}}();
 export { createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, } from "../core/checkpoint/mutation-checkpoint.js";
 export { flattenFlagListValue, resolveFlagValueKind, } from "../core/extensions/flag-value-types.js";
 export { createUnknownSubcommandError, } from "./agent/subcommand-recovery.js";
@@ -19,10 +19,10 @@ export { isFileMissingError, pathExists, readFileIfExists, removeFileIfExists, w
 export { normalizeBulkIdsValue, parseBulkIdsText, resolveCliBulkIdsInput, } from "../core/io/bulk-ids-input.js";
 export { computeHistoryDiff, patchPathToChangedField, } from "../core/history/history-diff.js";
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
-export { appendHistoryEntry, CURRENT_HISTORY_ITEM_HASH_VERSION, createHistoryEntry, hashDocument, hashDocumentForVersion, hashEmptyDocument, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, } from "../core/history/history.js";
+export { appendHistoryEntry, CURRENT_HISTORY_ITEM_HASH_VERSION, CURRENT_HISTORY_RECORD_HASH_VERSION, createHistoryEntry, hashDocument, hashDocumentForVersion, hashEmptyDocument, hashHistoryPatch, hashHistoryRecord, hashHistoryStream, resealHistoryRewrite, sealHistoryRecord, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, SUPPORTED_HISTORY_RECORD_HASH_VERSIONS, verifyHistoryRecordHash, verifyHistoryRewriteEvidence, } from "../core/history/history.js";
 export { readHistoryEntries } from "../core/history/read.js";
 export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, inspectWorkspaceHistoryState, mutateWorkspaceJsonWithHistory, reconcileWorkspaceJsonHistory, restoreWorkspaceJsonFromHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, } from "../core/history/workspace-history.js";
-export { normalizeReplayPatchOps, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
+export { normalizeReplayPatchOps, reanchorHistoryEntries, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
 export { resolveBodyFileContent } from "../core/io/body-file.js";
 export { generateItemId, normalizeItemId, normalizeRawItemId, } from "../core/item/id.js";
 export { canonicalDocument, normalizeItemMetadata, parseItemDocument, serializeItemDocument, } from "../core/item/item-format.js";
@@ -82,4 +82,4 @@ export { maybeRunFirstUseTelemetryPrompt } from "../core/telemetry/consent.js";
 export { deriveTelemetryCommandResolution, } from "../core/telemetry/observability.js";
 export { emitTelemetryErrorEvent, finishTelemetryCommand, startTelemetryCommand, } from "../core/telemetry/runtime.js";
 //# sourceMappingURL=runtime-primitives.js.map
-//# debugId=d45775e5-6826-521b-80b3-429ed22947d9
+//# debugId=aba5403c-0694-5c51-95a8-ae7e7575347b

package/dist/types.d.ts

@@ -789,6 +789,25 @@ export interface HistoryPatchOp {
     /** Value that configures or reports value for this contract. */
     value?: unknown;
 }
+/** Immutable evidence retained whenever history maintenance replaces anchors or patch operations. */
+export interface HistoryReanchorEvidence {
+    /** Before-state anchor present on the record before re-anchoring. */
+    before_hash: string;
+    /** After-state anchor present on the record before re-anchoring. */
+    after_hash: string;
+    /** Item hash epoch present before re-anchoring. */
+    item_hash_version?: number;
+    /** Hash of the original patch, retained even when redaction forbids retaining its values. */
+    patch_hash: string;
+    /** Original patch operations when repair replaced or skipped recorded intent. */
+    patch?: HistoryPatchOp[];
+    /** Record-integrity epoch protecting the pre-re-anchor record. */
+    record_hash_version?: number;
+    /** Record hash protecting the pre-re-anchor attribution and operation metadata. */
+    record_hash?: string;
+    /** Exact prior sealed record when maintenance can retain its non-sensitive payload. */
+    record?: HistoryEntry;
+}
 /** Documents the history entry payload exchanged by command, SDK, and package integrations. */
 export interface HistoryEntry {
     /** Value that configures or reports ts for this contract. */
@@ -839,6 +858,12 @@ export interface HistoryEntry {
     after_hash: string;
     /** Version of the item canonicalization used by before_hash and after_hash. Absent on legacy streams. */
     item_hash_version?: number;
+    /** Version of the canonical immutable-record envelope. Absent on legacy entries whose coverage is item-state-only. */
+    record_hash_version?: number;
+    /** SHA-256 hash covering this event's immutable metadata, patch, and item anchors. */
+    record_hash?: string;
+    /** Append-only evidence for every prior anchor or patch representation replaced by maintenance. */
+    reanchor_evidence?: HistoryReanchorEvidence[];
     /** Human-readable explanation suitable for logs and agent-facing output. */
     message?: string;
     /** Structured audit metadata that does not alter replayed item state. */