@unbrained/pm-cli 2026.9.3 → 2026.9.5

package/dist/sdk/history-repair.js

@@ -4,8 +4,9 @@
  * 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]="d397bc22-d0ae-5c3d-a1bf-7f4c38ca31be")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
+import { salvageHistoryTail } from "./history/salvage.js";
 import { realpath } from "node:fs/promises";
 import path from "node:path";
 import jsonPatch from "fast-json-patch";
@@ -13,21 +14,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 +173,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 +323,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 +339,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) {
@@ -379,6 +390,14 @@ export async function runHistoryRepair(id, options, global) {
     const settings = await readSettings(pmRoot);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const subject = await resolveHistorySubject(pmRoot, id, settings, typeRegistry.type_to_folder);
+    if (options.salvageTail === true) {
+        return salvageHistoryTail({ pmRoot, subject, settings, typeRegistry, options, author: resolveAuthor(options.author, settings.author_default) });
+    }
+    return repairHistorySubject({ pmRoot, subject, settings, typeRegistry, options });
+}
+/** Reanchor or reconcile one resolved subject, separately from byte-preserving salvage. */
+async function repairHistorySubject(params) {
+    const { pmRoot, subject, settings, typeRegistry, options } = params;
     if (!(await pathExists(subject.historyPath))) {
         throw new PmCliError(`No history stream exists for ${subject.id}.`, EXIT_CODE.NOT_FOUND);
     }
@@ -527,6 +546,9 @@ export function assertHistoryRepairTarget(id, all) {
 }
 /** Bulk drift repair: scan every item's history stream with the same drift scan `pm health` uses, then run the audited single-stream repair (ownership check, lock, no-drift verification, audit marker) for each drifted stream. One failing stream never aborts the rest; failures are collected per row and the caller decides the exit code from `totals.failed`. */
 export async function runHistoryRepairAll(options, global) {
+    if (options.salvageTail === true) {
+        throw new PmCliError("Tail salvage requires one explicit item ID; --all is not supported.", EXIT_CODE.USAGE);
+    }
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
     await assertInitializedTracker(pmRoot);
     const settings = await readSettings(pmRoot);
@@ -598,4 +620,4 @@ export async function runHistoryRepairAll(options, global) {
     };
 }
 //# sourceMappingURL=history-repair.js.map
-//# debugId=151e5d26-d6f5-5fcf-84ab-ce89e2b7664e
+//# debugId=d397bc22-d0ae-5c3d-a1bf-7f4c38ca31be

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/lifecycle/claim.d.ts

@@ -62,6 +62,10 @@ export interface ReleaseResult {
     previous_assignee: string | null;
     /** Value that configures or reports forced for this contract. */
     forced: boolean;
+    /** Stable handoff diagnostics shared by CLI and MCP consumers. */
+    warnings?: string[];
+    /** Concrete recovery commands when releasing ownership leaves work in progress. */
+    suggestions?: string[];
 }
 /** Documents the claim mutation options payload exchanged by command, SDK, and package integrations. */
 export interface ClaimMutationOptions {

package/dist/sdk/lifecycle/claim.js

@@ -4,9 +4,9 @@
  * Implements the pm claim 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]="1a61bf25-e320-5adc-8f5a-a427bc89af1a")}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]="a4d95016-05b9-5272-8044-2649da644e98")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
-import { resolveRuntimeStatusRegistry, statusIsTerminal, EXIT_CODE, PmCliError, toItemRecord, mutateItem, resolvePmRoot, readSettings, resolveAuthor, resolveClaimPrincipal, } from "../runtime-primitives.js";
+import { resolveRuntimeStatusRegistry, statusIsTerminal, EXIT_CODE, PmCliError, toItemRecord, mutateItem, resolvePmRoot, readSettings, resolveAuthor, resolveClaimPrincipal, normalizeStatusForRegistry, } from "../runtime-primitives.js";
 import { wrapOwnershipConflict } from "../annotations.js";
 import { describeItemOwnershipConflict } from "../ownership-source.js";
 import { runNext, } from "../query/next.js";
@@ -226,12 +226,18 @@ export async function runRelease(id, force, global, options = {}) {
         principal: claimPrincipal,
         itemId: result.item.id,
     });
+    const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
+    const stillInProgress = normalizeStatusForRegistry(result.item.status, statusRegistry) === normalizeStatusForRegistry(statusRegistry.in_progress_status, statusRegistry);
     return {
         item: toItemRecord(result.item),
         released_by: author,
         previous_assignee: previousAssignee,
         forced: force,
+        ...(stillInProgress ? {
+            warnings: ["released_unclaimed_in_progress"],
+            suggestions: [`${result.item.id} remains ${result.item.status} and unclaimed. If work is paused, run pm pause-task ${result.item.id} to move it to ${statusRegistry.open_status}.`],
+        } : {}),
     };
 }
 //# sourceMappingURL=claim.js.map
-//# debugId=1a61bf25-e320-5adc-8f5a-a427bc89af1a
+//# debugId=a4d95016-05b9-5272-8044-2649da644e98

package/dist/sdk/lifecycle/restore.d.ts

@@ -25,6 +25,7 @@ export interface RestoreResult {
         kind: "version" | "timestamp";
         target: string;
         history_index: number;
+        version: number | null;
         entry_ts: string;
         entry_op: string;
     };

package/dist/sdk/lifecycle/restore.js

@@ -4,13 +4,22 @@
  * Implements the SDK-owned restore lifecycle operation shared by every surface.
  */
 
-!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]="db5f3a6d-9ae5-5f9b-bedf-766b2b79324c")}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]="7a3effef-6ba8-51ba-ae99-436d4ef69813")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import jsonPatch from "fast-json-patch";
 import fs from "node:fs/promises";
-import { pathExists, readFileIfExists, writeFileAtomic, appendHistoryEntry, createHistoryEntry, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, enforceHistoryStreamPolicyForItem, normalizeItemId, normalizeRawItemId, canonicalDocument, serializeItemDocument, resolveItemTypeRegistry, acquireLock, EXIT_CODE, PmCliError, nowIso, getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnWriteHooks, runActiveBeforeMutationHooks, locateItem, createMutationGuardSdk, readLocatedItem, getHistoryPath, getItemPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
+import { readLocatedItemSnapshot } from "../../core/store/item-store.js";
+import { historyVersionOffset } from "../../core/history/version-address.js";
+import { pathExists, readFileIfExists, writeFileAtomic, appendHistoryEntry, createHistoryEntry, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, enforceHistoryStreamPolicyForItem, normalizeItemId, normalizeRawItemId, canonicalDocument, serializeItemDocument, resolveItemTypeRegistry, acquireLock, EXIT_CODE, PmCliError, nowIso, getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnWriteHooks, runActiveBeforeMutationHooks, locateItem, createMutationGuardSdk, getHistoryPath, getItemPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { applyHistoryPatch, ensureMaterializedHistoryTarget as ensureMaterializedRestoreTarget, extractPatchFailureContext, readHistoryEntries, replayHistoryToTarget as replayToTarget, resolveHistoryTarget, } from "../history-read.js";
 import { acquireItemMetadataDerivedIndexLock, refreshItemMetadataDerivedIndex, } from "../item-metadata-index.js";
+/** Read a restore input without discarding unreadable bytes needed for rollback. */
+async function readRestoreItem(located, settings, history) {
+    const snapshot = await readLocatedItemSnapshot(located, { schema: settings.schema });
+    return snapshot.error === null
+        ? { raw: snapshot.raw, document: snapshot.document }
+        : { raw: snapshot.raw, document: replayCurrentDocument(history), recovered: true };
+}
 /** Resolve restore targets with the command's established wording and at-or-before timestamp semantics. */
 function ensureReplayTarget(target, history) {
     return resolveHistoryTarget(target, history, {
@@ -82,6 +91,7 @@ function changedFields(beforeDocument, afterDocument) {
     }
     return Array.from(fields).sort((a, b) => a.localeCompare(b));
 }
+/** Reload item and history under the caller's lock, refusing changes since the recovery snapshot. */
 async function loadRestoreStateUnderLock(params) {
     const historyRawUnderLock = await readFileIfExists(params.subject.historyPath);
     if (historyRawUnderLock !== params.historyRawBeforeLock) {
@@ -89,9 +99,7 @@ async function loadRestoreStateUnderLock(params) {
     }
     const locatedUnderLock = await locateItem(params.pmRoot, params.resolvedId, params.settings.id_prefix, params.settings.item_format, params.typeToFolder);
     const loadedItemUnderLock = locatedUnderLock
-        ? await readLocatedItem(locatedUnderLock, {
-            schema: params.settings.schema,
-        })
+        ? await readRestoreItem(locatedUnderLock, params.settings, params.history)
         : null;
     if ((loadedItemUnderLock?.raw ?? null) !== params.currentItemRawBeforeLock) {
         throw new PmCliError(`Item ${params.resolvedId} changed while waiting for lock; retry restore.`, EXIT_CODE.CONFLICT);
@@ -183,7 +191,7 @@ export async function runRestore(id, target, options, global) {
         throw new PmCliError(`Restore target resolved to item ${restoredDocument.metadata.id}, expected ${resolvedId}.`, EXIT_CODE.GENERIC_FAILURE);
     }
     const loadedItemBeforeLock = subject.located
-        ? await readLocatedItem(subject.located, { schema: settings.schema })
+        ? await readRestoreItem(subject.located, settings, history)
         : null;
     const currentItemRawBeforeLock = loadedItemBeforeLock?.raw ?? null;
     const author = resolveAuthor(options.author, settings.author_default);
@@ -197,6 +205,7 @@ export async function runRestore(id, target, options, global) {
             typeToFolder: typeRegistry.type_to_folder,
             historyRawBeforeLock,
             currentItemRawBeforeLock,
+            history,
         });
         const itemFormat = "toon";
         const currentState = resolveRestoreCurrentState(loadedItemUnderLock, history);
@@ -282,17 +291,20 @@ export async function runRestore(id, target, options, global) {
             changed_fields: restoreChangedFields,
         });
         const targetEntry = history[resolvedTarget.historyIndex];
+        const offset = historyVersionOffset(history, true);
         return {
             item: restoredDocument.metadata,
             restored_from: {
                 kind: resolvedTarget.kind,
                 target: resolvedTarget.raw,
                 history_index: resolvedTarget.historyIndex + 1,
+                version: offset === null ? null : offset + resolvedTarget.historyIndex + 1,
                 entry_ts: targetEntry.ts,
                 entry_op: targetEntry.op,
             },
             changed_fields: restoreChangedFields,
             warnings: [
+                ...(loadedItemUnderLock?.recovered ? ["restore_unreadable_item_recovered"] : []),
                 ...subject.historyPolicyWarnings,
                 ...ownershipWarnings,
                 ...derivedIndexWarnings,
@@ -316,4 +328,4 @@ export const _testOnlyRestoreCommand = {
     resolveRestoreSubject,
 };
 //# sourceMappingURL=restore.js.map
-//# debugId=db5f3a6d-9ae5-5f9b-bedf-766b2b79324c
+//# debugId=7a3effef-6ba8-51ba-ae99-436d4ef69813

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

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

@@ -6,7 +6,7 @@
  * merge-configuration installer. The CLI `pm merge` command is a shim over
  * this module so packages and hosts can reuse the same merge behavior.
  */
-export { ITEM_LATEST_TIMESTAMP_FIELDS, ITEM_UNION_COLLECTION_FIELDS, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, mergeRelationshipEventStreams, type HistoryMergeResult, type HistoryMergeStrategy, type ItemDocumentMergeResult, type JsonDocumentMergeResult, type ItemMergeConflictDecision, type MergePreferredSide, type RelationshipStreamMergeResult, } from "./three-way.js";
+export { ITEM_SCALAR_MISSING_VALUE, ITEM_LATEST_TIMESTAMP_FIELDS, ITEM_UNION_COLLECTION_FIELDS, encodeItemScalarDecisionValue, hashItemScalarDecisionValue, isItemScalarMissingValue, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, mergeRelationshipEventStreams, type HistoryMergeResult, type HistoryMergeStrategy, type ItemDocumentMergeResult, type JsonDocumentMergeResult, type ItemMergeConflictDecision, type ItemScalarConflictResolution, type ItemScalarResolutionBasis, type MergePreferredSide, type RelationshipStreamMergeResult, } from "./three-way.js";
 export { inspectMergeReceiptEvidence, listMergeReceipts, markMergeReceiptReconciled, runMergeReceiptEvidenceReport, runMergeReceiptReport, summarizeMergeReceipt, type MergeDecisionReceipt, type MergeDecisionReceiptSummary, type MergeReceiptEvidenceReport, type MergeReceiptEvidenceScan, type MergeReceiptInvalidEvidence, type MergeReceiptReport, } from "./receipts.js";
 export { MERGE_DRIVER_ARTIFACT_VALUES, runMergeDriver, type MergeDriverArtifact, type MergeDriverOptions, type MergeDriverResult, } from "./driver.js";
 export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, PM_GITATTRIBUTES_V2_END, PM_GITATTRIBUTES_V2_START, refreshMergeAttributeFenceIfInstalled, resolveMergeInstallContext, runMergeInstall, type MergeFenceAuditResult, type MergeDriverConfigurationAuditResult, type MergeFenceRefreshOutcome, type MergeInstallOptions, type MergeInstallContextResolution, type MergeInstallResult, } from "./install.js";

package/dist/sdk/merge/index.js

@@ -7,11 +7,11 @@
  * this module so packages and hosts can reuse the same merge 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]="0a17e896-d54a-5796-8be3-535179c4d6e0")}catch(e){}}();
-export { ITEM_LATEST_TIMESTAMP_FIELDS, ITEM_UNION_COLLECTION_FIELDS, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, mergeRelationshipEventStreams, } from "./three-way.js";
+!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]="925be497-bdd3-527b-9a88-cf9c9f682ab2")}catch(e){}}();
+export { ITEM_SCALAR_MISSING_VALUE, ITEM_LATEST_TIMESTAMP_FIELDS, ITEM_UNION_COLLECTION_FIELDS, encodeItemScalarDecisionValue, hashItemScalarDecisionValue, isItemScalarMissingValue, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, mergeRelationshipEventStreams, } from "./three-way.js";
 export { inspectMergeReceiptEvidence, listMergeReceipts, markMergeReceiptReconciled, runMergeReceiptEvidenceReport, runMergeReceiptReport, summarizeMergeReceipt, } from "./receipts.js";
 export { MERGE_DRIVER_ARTIFACT_VALUES, runMergeDriver, } from "./driver.js";
 export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, PM_GITATTRIBUTES_V2_END, PM_GITATTRIBUTES_V2_START, refreshMergeAttributeFenceIfInstalled, resolveMergeInstallContext, runMergeInstall, } from "./install.js";
 export { runMergeReconcile, } from "./reconcile.js";
 //# sourceMappingURL=index.js.map
-//# debugId=0a17e896-d54a-5796-8be3-535179c4d6e0
+//# debugId=925be497-bdd3-527b-9a88-cf9c9f682ab2

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

@@ -1,7 +1,8 @@
 import type { Stats } from "node:fs";
-import type { ItemMergeConflictDecision, MergePreferredSide } from "./three-way.js";
+import { type ItemMergeConflictDecision, type ItemScalarConflictResolution, type MergePreferredSide } from "./three-way.js";
 /** Return whether a receipt id is safe to expose in cleartext diagnostics. */
 export declare function isSafeReceiptId(value: string): boolean;
+declare const DURABLE_VALUE_POLICY: "bounded_non_sensitive_scalars_v1";
 /** One clone-local merge receipt with recoverable branch values. */
 export interface MergeDecisionReceipt {
     /** Receipt schema version. */
@@ -14,10 +15,12 @@ export interface MergeDecisionReceipt {
     item_id: string;
     /** Side requested by the caller; stable-value decisions can retain either side. */
     requested_preference?: MergePreferredSide;
+    /** Whether requested preference participates in item scalar selection. */
+    requested_preference_applied?: boolean;
     /** Legacy schema-v1 key accepted while reading older clone-local receipts. */
     preferred?: MergePreferredSide;
     /** Scalar-conflict selection contract used by the item driver. */
-    conflict_resolution: "preferred_side" | "stable_value_order";
+    conflict_resolution: ItemScalarConflictResolution;
     /** Fields selected cleanly from the other branch. */
     fields_from_theirs: string[];
     /** Collections combined from both branches. */
@@ -33,7 +36,9 @@ export interface MergeDecisionReceipt {
     /** Reconciliation timestamp, when consumed. */
     reconciled_at?: string;
     /** Whether decision values are recoverable locally or represented by hashes only. */
-    value_availability?: "clone_local" | "hash_only";
+    value_availability?: "clone_local" | "hash_only" | "bounded_inline" | "mixed";
+    /** Versioned rule governing which durable scalar previews may be committed. */
+    value_policy?: typeof DURABLE_VALUE_POLICY;
     /** Runtime-only provenance assigned by the reader; serialized values are ignored. */
     evidence_source?: "clone_local" | "durable";
 }
@@ -53,8 +58,10 @@ export interface MergeDecisionReceiptSummary {
     union_fields: string[];
     /** Side requested by the caller; decision hashes prove the actual retained values. */
     requested_preference: MergePreferredSide;
+    /** Whether requested preference participated in item scalar selection. */
+    requested_preference_applied: boolean;
     /** Scalar-conflict selection contract used by the item driver. */
-    conflict_resolution: "preferred_side" | "stable_value_order";
+    conflict_resolution: ItemScalarConflictResolution;
     /** Hashes proving the retained and discarded values without publishing them. */
     decisions: Array<{
         field: string;
@@ -112,12 +119,15 @@ export interface MergeReceiptInvalidEvidence {
     /** Evidence store that produced the rejected candidate. */
     evidence_source: "clone_local" | "durable" | "clone_local_and_durable";
     /** Stable failure class suitable for remediation routing and graph analytics. */
-    reason: "directory_unreadable" | "candidate_not_bounded_regular_file" | "candidate_unreadable" | "candidate_invalid_json" | "schema_or_identity_invalid" | "copy_provenance_mismatch";
+    reason: "directory_unreadable" | "candidate_not_bounded_regular_file" | "candidate_unreadable" | "candidate_invalid_json" | "schema_or_identity_invalid" | "schema_invalid" | "identity_invalid" | "copy_provenance_mismatch";
+    /** Exact validation boundary when schema or identity evidence is rejected. */
+    validation_error?: "required_fields" | "receipt_id" | "item_id" | "item_path" | "filename" | "collections" | "enums" | "timestamps" | "durable_decisions";
     /** Receipt identity when the bounded filename itself is a valid receipt id. */
     receipt_id?: string;
     /** SHA-256 locator for an unsafe or malformed candidate filename. */
     candidate_name_hash?: string;
 }
+/** Revalidate one receipt and stage its atomic reconciled-state replacement. */
 declare function prepareReceiptSettlement(params: {
     receiptPath: string;
     receiptId: string;
@@ -136,12 +146,13 @@ export declare function writeMergeReceipt(params: {
     cwd: string;
     itemPath: string;
     preferred: MergePreferredSide;
-    conflictResolution?: "preferred_side" | "stable_value_order";
+    conflictResolution?: ItemScalarConflictResolution;
     fieldsFromTheirs: string[];
     unionFields: string[];
     mergedFieldHashes?: Record<string, string>;
     decisions: ItemMergeConflictDecision[];
 }): Promise<MergeDecisionReceipt | null>;
+/** Distinguish a missing optional receipt store from an unreadable one. */
 declare function receiptDirectoryFailureMeansAbsent(directory: string, error: unknown, inspectAncestor?: (ancestor: string) => Promise<Pick<Stats, "isDirectory">>): Promise<boolean>;
 /** Inspect valid receipts and count invalid evidence without returning untrusted file contents. */
 export declare function inspectMergeReceiptEvidence(cwd: string, options?: {