@unbrained/pm-cli 2026.9.3 → 2026.9.4

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?: {

package/dist/sdk/merge/receipts.js

@@ -7,7 +7,7 @@
  * value for the coordinator that performed the merge.
  */
 
-!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]="df7d5bd9-8381-5961-bda1-9e8ed335afc9")}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]="dfdd6f10-e11f-59e8-a16f-507dc40d5b31")}catch(e){}}();
 import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { readdir, stat } from "node:fs/promises";
@@ -16,6 +16,7 @@ import { promisify } from "node:util";
 import { ensureDir, isFileAbsentError, isFileMissingError, pathExists, writeFileAtomic, } from "../../core/fs/fs-utils.js";
 import { sha256Hex, stableStringify } from "../../core/shared/serialization.js";
 import { isRfc3339DateTime, nowIso } from "../../core/shared/time.js";
+import { hashItemScalarDecisionValue, isItemScalarMissingValue, } from "./three-way.js";
 import { readBoundedRegularFile } from "./receipt-file-boundary.js";
 const execFileAsync = promisify(execFile);
 const RECEIPT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/u;
@@ -31,6 +32,7 @@ const RECEIPT_KEYS = new Set([
     "item_path",
     "item_id",
     "requested_preference",
+    "requested_preference_applied",
     "preferred",
     "conflict_resolution",
     "fields_from_theirs",
@@ -41,6 +43,7 @@ const RECEIPT_KEYS = new Set([
     "created_at",
     "reconciled_at",
     "value_availability",
+    "value_policy",
     "evidence_source",
 ]);
 /** Return whether a receipt id is safe to expose in cleartext diagnostics. */
@@ -54,7 +57,33 @@ const RECEIPT_DECISION_KEYS = new Set([
     "theirs",
     "retained",
     "discarded",
+    "retained_side",
+    "resolution_basis",
 ]);
+const DURABLE_VALUE_POLICY = "bounded_non_sensitive_scalars_v1";
+const REVIEWABLE_BUILTIN_STATUSES = new Set([
+    "open",
+    "in_progress",
+    "blocked",
+    "closed",
+    "canceled",
+]);
+const REVIEWABLE_ORDINAL_FIELDS = new Set(["risk", "confidence", "severity"]);
+const REVIEWABLE_ORDINAL_VALUES = new Set([
+    "low",
+    "medium",
+    "high",
+    "critical",
+]);
+const REVIEWABLE_DURABLE_VALUES_BY_FIELD = new Map([
+    ["priority", new Set([0, 1, 2, 3, 4].map(stableStringify))],
+    ["status", new Set([...REVIEWABLE_BUILTIN_STATUSES].map(stableStringify))],
+    ...[...REVIEWABLE_ORDINAL_FIELDS].map((field) => [
+        field,
+        new Set([...REVIEWABLE_ORDINAL_VALUES].map(stableStringify)),
+    ]),
+]);
+/** Resolve the clone-local receipt store without crossing a Git worktree boundary. */
 async function resolveReceiptDirectory(cwd) {
     try {
         const { stdout } = await execFileAsync("git", [
@@ -69,6 +98,7 @@ async function resolveReceiptDirectory(cwd) {
         return null;
     }
 }
+/** Derive the tracker root only when the merged item belongs to this workspace. */
 async function resolveTrackerRootFromItemPath(cwd, itemPath) {
     let directory = path.dirname(path.resolve(cwd, itemPath));
     for (let depth = 0; depth < 12; depth += 1) {
@@ -81,23 +111,29 @@ async function resolveTrackerRootFromItemPath(cwd, itemPath) {
     }
     return null;
 }
+/** Locate the tracked durable receipt sidecar directory. */
 function durableReceiptDirectory(pmRoot) {
     return path.join(pmRoot, "merge-receipts");
 }
+/** Map a validated opaque receipt identifier to its canonical filename. */
 function receiptFileName(id) {
     return `${id}.json`;
 }
+/** Narrow untrusted JSON to a non-array object before schema inspection. */
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+/** Refuse receipt extensions outside the versioned schema key set. */
 function hasOnlyKeys(value, allowed) {
     return Object.keys(value).every((key) => allowed.has(key));
 }
+/** Validate bounded dense string collections used in receipt coordinates. */
 function isStringArray(value) {
     return (Array.isArray(value) &&
         value.length <= RECEIPT_FIELD_MAX &&
         value.every((entry) => typeof entry === "string" && entry.length > 0 && entry.length <= 256));
 }
+/** Bound JSON depth and node count before retaining untrusted decision values. */
 function hasBoundedJsonStructure(value) {
     const pending = [
         { value, depth: 0 },
@@ -123,23 +159,37 @@ function hasBoundedJsonStructure(value) {
     }
     return true;
 }
+/** Validate one clone-local scalar decision and its optional resolution evidence. */
 function isMergeDecision(value) {
-    return (isRecord(value) &&
-        hasOnlyKeys(value, RECEIPT_DECISION_KEYS) &&
-        typeof value.field === "string" &&
-        value.field.length > 0 &&
-        value.field.length <= 256 &&
-        Object.hasOwn(value, "base") &&
-        Object.hasOwn(value, "ours") &&
-        Object.hasOwn(value, "theirs") &&
-        Object.hasOwn(value, "retained") &&
-        Object.hasOwn(value, "discarded") &&
-        hasBoundedJsonStructure(value.base) &&
-        hasBoundedJsonStructure(value.ours) &&
-        hasBoundedJsonStructure(value.theirs) &&
-        hasBoundedJsonStructure(value.retained) &&
-        hasBoundedJsonStructure(value.discarded));
-}
+    if (!isRecord(value))
+        return false;
+    const retainedSides = [undefined, "ours", "theirs"];
+    const resolutionBases = [
+        undefined,
+        "requested_preference",
+        "document_updated_at",
+        "stable_value_tiebreak",
+    ];
+    return [
+        hasOnlyKeys(value, RECEIPT_DECISION_KEYS),
+        typeof value.field === "string",
+        typeof value.field === "string" && value.field.length > 0,
+        typeof value.field === "string" && value.field.length <= 256,
+        Object.hasOwn(value, "base"),
+        Object.hasOwn(value, "ours"),
+        Object.hasOwn(value, "theirs"),
+        Object.hasOwn(value, "retained"),
+        Object.hasOwn(value, "discarded"),
+        hasBoundedJsonStructure(value.base),
+        hasBoundedJsonStructure(value.ours),
+        hasBoundedJsonStructure(value.theirs),
+        hasBoundedJsonStructure(value.retained),
+        hasBoundedJsonStructure(value.discarded),
+        retainedSides.includes(value.retained_side),
+        resolutionBases.includes(value.resolution_basis),
+    ].every(Boolean);
+}
+/** Validate the complete field-to-SHA-256 proof map used during repair. */
 function isMergedFieldHashes(value) {
     if (!isRecord(value))
         return false;
@@ -150,6 +200,7 @@ function isMergedFieldHashes(value) {
             typeof hash === "string" &&
             /^[a-f0-9]{64}$/u.test(hash)));
 }
+/** Require a normalized tracker item path whose basename matches the receipt item. */
 function isSafeReceiptItemPath(value, itemId) {
     if (typeof value !== "string" ||
         value.length === 0 ||
@@ -164,15 +215,7 @@ function isSafeReceiptItemPath(value, itemId) {
         !normalized.startsWith("../") &&
         path.posix.basename(normalized, path.posix.extname(normalized)) === itemId);
 }
-function hasValidReceiptIdentity(value) {
-    return !hasOnlyKeys(value, RECEIPT_KEYS) || value.version !== 1
-        ? false
-        : typeof value.id === "string" &&
-            isSafeReceiptId(value.id) &&
-            typeof value.item_id === "string" &&
-            RECEIPT_ITEM_ID_PATTERN.test(value.item_id) &&
-            isSafeReceiptItemPath(value.item_path, value.item_id);
-}
+/** Validate receipt arrays and optional merged-field proof coverage. */
 function hasValidReceiptCollections(value) {
     return !isStringArray(value.fields_from_theirs) ||
         !isStringArray(value.union_fields) ||
@@ -183,18 +226,35 @@ function hasValidReceiptCollections(value) {
         : value.merged_field_hashes === undefined ||
             isMergedFieldHashes(value.merged_field_hashes);
 }
+/** Validate every closed-domain lifecycle and merge-policy field. */
 function hasValidReceiptEnums(value) {
     const preferences = [undefined, "ours", "theirs"];
-    const resolutions = [undefined, "preferred_side", "stable_value_order"];
-    const availabilities = [undefined, "clone_local", "hash_only"];
+    const resolutions = [
+        undefined,
+        "preferred_side",
+        "stable_value_order",
+        "latest_document_update",
+    ];
+    const availabilities = [
+        undefined,
+        "clone_local",
+        "hash_only",
+        "bounded_inline",
+        "mixed",
+    ];
     const sources = [undefined, "clone_local", "durable"];
     return (preferences.includes(value.requested_preference) &&
         preferences.includes(value.preferred) &&
+        (value.requested_preference_applied === undefined ||
+            typeof value.requested_preference_applied === "boolean") &&
         resolutions.includes(value.conflict_resolution) &&
         (value.state === "pending" || value.state === "reconciled") &&
         availabilities.includes(value.value_availability) &&
+        (value.value_policy === undefined ||
+            value.value_policy === DURABLE_VALUE_POLICY) &&
         sources.includes(value.evidence_source));
 }
+/** Validate creation and optional settlement timestamps as RFC 3339 values. */
 function hasValidReceiptTimestamps(value) {
     return (typeof value.created_at === "string" &&
         isRfc3339DateTime(value.created_at) &&
@@ -202,28 +262,99 @@ function hasValidReceiptTimestamps(value) {
             (typeof value.reconciled_at === "string" &&
                 isRfc3339DateTime(value.reconciled_at))));
 }
-function hasHashOnlyDurableDecisions(receipt) {
-    return (receipt.value_availability === "hash_only" &&
-        receipt.decisions.every((decision) => decision.base === null &&
-            decision.ours === null &&
-            decision.theirs === null &&
-            isExactPrehashedValue(decision.retained) &&
-            isExactPrehashedValue(decision.discarded)));
-}
-function isMergeDecisionReceipt(value, evidenceSource) {
-    if (!isRecord(value) ||
-        !hasValidReceiptIdentity(value) ||
-        !hasValidReceiptCollections(value) ||
-        !hasValidReceiptEnums(value) ||
-        !hasValidReceiptTimestamps(value)) {
+/** Validate one hash-only or policy-bounded durable decision value. */
+function hasDurableDecisionValue(field, value) {
+    if (!isRecord(value) || isPrehashedValue(value) === undefined)
+        return false;
+    const keys = Object.keys(value);
+    if (!keys.every((key) => key === "pm_value_hash" || key === "pm_value")) {
+        return false;
+    }
+    if (!Object.hasOwn(value, "pm_value"))
+        return keys.length === 1;
+    const preview = value.pm_value;
+    const allowed = preview === null ||
+        REVIEWABLE_DURABLE_VALUES_BY_FIELD.get(field)?.has(stableStringify(preview)) === true;
+    return (allowed && hashItemScalarDecisionValue(preview) === value.pm_value_hash);
+}
+/** Validate durable decision redaction and the declared availability summary. */
+function hasValidDurableDecisions(receipt) {
+    if (!receipt.decisions.every((decision) => decision.base === null &&
+        decision.ours === null &&
+        decision.theirs === null &&
+        hasDurableDecisionValue(decision.field, decision.retained) &&
+        hasDurableDecisionValue(decision.field, decision.discarded))) {
         return false;
     }
-    const receipt = value;
-    return evidenceSource !== "durable" || hasHashOnlyDurableDecisions(receipt);
+    const inlineValueCount = receipt.decisions.reduce((count, decision) => count +
+        (isRecord(decision.retained) &&
+            Object.hasOwn(decision.retained, "pm_value")
+            ? 1
+            : 0) +
+        (isRecord(decision.discarded) &&
+            Object.hasOwn(decision.discarded, "pm_value")
+            ? 1
+            : 0), 0);
+    const expectedAvailability = inlineValueCount === 0
+        ? "hash_only"
+        : inlineValueCount === receipt.decisions.length * 2
+            ? "bounded_inline"
+            : "mixed";
+    return (receipt.value_availability === expectedAvailability &&
+        (inlineValueCount === 0 || receipt.value_policy === DURABLE_VALUE_POLICY));
+}
+/** Return the narrowest validation class for untrusted receipt evidence. */
+function receiptValidationError(value, evidenceSource) {
+    if (!isRecord(value))
+        return "required_fields";
+    for (const key of [
+        "version",
+        "id",
+        "item_path",
+        "item_id",
+        "fields_from_theirs",
+        "union_fields",
+        "decisions",
+        "state",
+        "created_at",
+    ]) {
+        if (!Object.hasOwn(value, key))
+            return "required_fields";
+    }
+    if (value.version !== 1 || !hasOnlyKeys(value, RECEIPT_KEYS)) {
+        return "required_fields";
+    }
+    if (typeof value.id !== "string" || !isSafeReceiptId(value.id)) {
+        return "receipt_id";
+    }
+    if (typeof value.item_id !== "string" ||
+        !RECEIPT_ITEM_ID_PATTERN.test(value.item_id)) {
+        return "item_id";
+    }
+    if (!isSafeReceiptItemPath(value.item_path, value.item_id)) {
+        return "item_path";
+    }
+    if (!hasValidReceiptCollections(value))
+        return "collections";
+    if (!hasValidReceiptEnums(value))
+        return "enums";
+    if (!hasValidReceiptTimestamps(value))
+        return "timestamps";
+    if (evidenceSource === "durable" &&
+        !hasValidDurableDecisions(value)) {
+        return "durable_decisions";
+    }
+    return null;
 }
+/** Validate a complete receipt against its clone-local or durable evidence policy. */
+function isMergeDecisionReceipt(value, evidenceSource) {
+    return receiptValidationError(value, evidenceSource) === null;
+}
+/** Read one receipt through the no-follow bounded regular-file guard. */
 async function readBoundedRegularReceiptFile(receiptPath) {
     return readBoundedRegularFile(receiptPath, RECEIPT_FILE_MAX_BYTES);
 }
+/** Revalidate one receipt and stage its atomic reconciled-state replacement. */
 async function prepareReceiptSettlement(params) {
     let raw;
     try {
@@ -260,6 +391,7 @@ async function prepareReceiptSettlement(params) {
         }, null, 2)}\n`,
     };
 }
+/** Fingerprint immutable receipt provenance while excluding lifecycle state. */
 function receiptProvenanceFingerprint(receipt) {
     return sha256Hex(stableStringify({
         id: receipt.id,
@@ -274,6 +406,7 @@ function receiptProvenanceFingerprint(receipt) {
         decisions: summarizeMergeReceipt(receipt).decisions,
     }));
 }
+/** Merge clone-local and durable lifecycle state without losing pending work. */
 function mergeReceiptCopyLifecycle(local, durable) {
     if (local.state === "reconciled" && durable.state === "reconciled") {
         return local;
@@ -291,16 +424,23 @@ export function summarizeMergeReceipt(receipt) {
         fields_from_theirs: receipt.fields_from_theirs,
         union_fields: receipt.union_fields,
         requested_preference: receipt.requested_preference ?? receipt.preferred ?? "ours",
+        requested_preference_applied: receipt.requested_preference_applied ??
+            (receipt.conflict_resolution ?? "preferred_side") === "preferred_side",
         conflict_resolution: receipt.conflict_resolution,
         decisions: receipt.decisions.map((decision) => ({
             field: decision.field,
             retained_hash: isPrehashedValue(decision.retained) ??
-                sha256Hex(stableStringify(decision.retained)),
+                hashItemScalarDecisionValue(isItemScalarMissingValue(decision.retained)
+                    ? undefined
+                    : decision.retained),
             discarded_hash: isPrehashedValue(decision.discarded) ??
-                sha256Hex(stableStringify(decision.discarded)),
+                hashItemScalarDecisionValue(isItemScalarMissingValue(decision.discarded)
+                    ? undefined
+                    : decision.discarded),
         })),
     };
 }
+/** Extract a structurally valid precomputed SHA-256 decision hash. */
 function isPrehashedValue(value) {
     if (typeof value !== "object" ||
         value === null ||
@@ -313,10 +453,16 @@ function isPrehashedValue(value) {
         ? hash
         : undefined;
 }
-function isExactPrehashedValue(value) {
-    return (isRecord(value) &&
-        Object.keys(value).length === 1 &&
-        isPrehashedValue(value) !== undefined);
+/** Convert a raw scalar into hashed evidence with an allowlisted preview. */
+function durableValueEvidence(field, value) {
+    const missing = isItemScalarMissingValue(value);
+    const pmValueHash = hashItemScalarDecisionValue(missing ? undefined : value);
+    const reviewable = !missing &&
+        (value === null ||
+            REVIEWABLE_DURABLE_VALUES_BY_FIELD.get(field)?.has(stableStringify(value)) === true);
+    return reviewable
+        ? { pm_value_hash: pmValueHash, pm_value: value }
+        : { pm_value_hash: pmValueHash };
 }
 /** Persist one item-driver outcome in the clone-local Git directory. */
 export async function writeMergeReceipt(params) {
@@ -325,11 +471,7 @@ export async function writeMergeReceipt(params) {
         return null;
     }
     const trimmedItemPath = params.itemPath.trim();
-    const itemPath = trimmedItemPath.length >= 2 &&
-        ((trimmedItemPath.startsWith("'") && trimmedItemPath.endsWith("'")) ||
-            (trimmedItemPath.startsWith('"') && trimmedItemPath.endsWith('"')))
-        ? trimmedItemPath.slice(1, -1)
-        : trimmedItemPath;
+    const itemPath = /^(['"])(.*)\1$/su.exec(trimmedItemPath)?.[2] ?? trimmedItemPath;
     const itemId = path.basename(itemPath, path.extname(itemPath));
     const receipt = {
         version: 1,
@@ -337,6 +479,7 @@ export async function writeMergeReceipt(params) {
         item_path: itemPath.replaceAll("\\", "/"),
         item_id: itemId,
         requested_preference: params.preferred,
+        requested_preference_applied: (params.conflictResolution ?? "preferred_side") === "preferred_side",
         conflict_resolution: params.conflictResolution ?? "preferred_side",
         fields_from_theirs: [...params.fieldsFromTheirs],
         union_fields: [...params.unionFields],
@@ -353,24 +496,35 @@ export async function writeMergeReceipt(params) {
     const trackerRoot = await resolveTrackerRootFromItemPath(params.cwd, receipt.item_path);
     if (trackerRoot !== null) {
         const durableDirectory = durableReceiptDirectory(trackerRoot);
-        const summary = summarizeMergeReceipt(receipt);
+        const durableDecisions = receipt.decisions.map((decision) => ({
+            field: decision.field,
+            base: null,
+            ours: null,
+            theirs: null,
+            retained: durableValueEvidence(decision.field, decision.retained),
+            discarded: durableValueEvidence(decision.field, decision.discarded),
+            retained_side: decision.retained_side,
+            resolution_basis: decision.resolution_basis,
+        }));
+        const inlineValueCount = durableDecisions.reduce((count, decision) => count +
+            (Object.hasOwn(decision.retained, "pm_value") ? 1 : 0) +
+            (Object.hasOwn(decision.discarded, "pm_value") ? 1 : 0), 0);
         const durableReceipt = {
             ...receipt,
-            decisions: summary.decisions.map((decision) => ({
-                field: decision.field,
-                base: null,
-                ours: null,
-                theirs: null,
-                retained: { pm_value_hash: decision.retained_hash },
-                discarded: { pm_value_hash: decision.discarded_hash },
-            })),
-            value_availability: "hash_only",
+            decisions: durableDecisions,
+            value_availability: inlineValueCount === 0
+                ? "hash_only"
+                : inlineValueCount === durableDecisions.length * 2
+                    ? "bounded_inline"
+                    : "mixed",
+            value_policy: DURABLE_VALUE_POLICY,
         };
         await ensureDir(durableDirectory);
         await writeFileAtomic(path.join(durableDirectory, receiptFileName(receipt.id)), `${JSON.stringify(durableReceipt, null, 2)}\n`);
     }
     return receipt;
 }
+/** Scan one receipt directory with bounded per-candidate failure evidence. */
 async function readReceiptsFromDirectory(directory, evidenceSource) {
     let names;
     try {
@@ -390,14 +544,17 @@ async function readReceiptsFromDirectory(directory, evidenceSource) {
     const receipts = [];
     let invalidEvidenceCount = 0;
     const invalidEvidence = [];
-    const recordInvalidEvidence = (name, reason) => {
+    const recordInvalidEvidence = (name, candidate) => {
         invalidEvidenceCount += 1;
         if (invalidEvidence.length >= RECEIPT_INVALID_EVIDENCE_DETAIL_LIMIT)
             return;
         const receiptId = name.slice(0, -".json".length);
         invalidEvidence.push({
             evidence_source: evidenceSource,
-            reason,
+            reason: candidate.reason,
+            ...(candidate.validation_error === undefined
+                ? {}
+                : { validation_error: candidate.validation_error }),
             ...(isSafeReceiptId(receiptId)
                 ? { receipt_id: receiptId }
                 : { candidate_name_hash: sha256Hex(name) }),
@@ -411,7 +568,7 @@ async function readReceiptsFromDirectory(directory, evidenceSource) {
             receipts.push(candidate.receipt);
         }
         else {
-            recordInvalidEvidence(name, candidate.reason);
+            recordInvalidEvidence(name, candidate);
         }
     }
     return {
@@ -421,6 +578,7 @@ async function readReceiptsFromDirectory(directory, evidenceSource) {
         invalid_evidence_truncated: invalidEvidenceCount > invalidEvidence.length,
     };
 }
+/** Distinguish a missing optional receipt store from an unreadable one. */
 async function receiptDirectoryFailureMeansAbsent(directory, error, inspectAncestor = stat) {
     if (!isFileMissingError(error))
         return false;
@@ -439,6 +597,7 @@ async function receiptDirectoryFailureMeansAbsent(directory, error, inspectAnces
         }
     }
 }
+/** Inspect one candidate without exposing rejected file contents. */
 async function inspectReceiptCandidate(directory, name, evidenceSource) {
     let raw;
     try {
@@ -456,16 +615,28 @@ async function inspectReceiptCandidate(directory, name, evidenceSource) {
     catch {
         return { reason: "candidate_invalid_json" };
     }
-    if (!isMergeDecisionReceipt(parsed, evidenceSource) ||
-        name !== receiptFileName(parsed.id)) {
-        return { reason: "schema_or_identity_invalid" };
+    const validationError = receiptValidationError(parsed, evidenceSource);
+    if (validationError !== null) {
+        const identityErrors = new Set(["receipt_id", "item_id", "item_path"]);
+        return {
+            reason: identityErrors.has(validationError)
+                ? "identity_invalid"
+                : "schema_invalid",
+            validation_error: validationError,
+        };
+    }
+    const receipt = parsed;
+    if (name !== receiptFileName(receipt.id)) {
+        return { reason: "identity_invalid", validation_error: "filename" };
     }
-    const { preferred: legacyPreference, evidence_source: _serializedEvidenceSource, ...receiptWithoutRuntimeKeys } = parsed;
+    const { preferred: legacyPreference, evidence_source: _serializedEvidenceSource, ...receiptWithoutRuntimeKeys } = receipt;
     return {
         receipt: {
             ...receiptWithoutRuntimeKeys,
-            requested_preference: parsed.requested_preference ?? legacyPreference ?? "ours",
-            conflict_resolution: parsed.conflict_resolution ?? "preferred_side",
+            requested_preference: receipt.requested_preference ?? legacyPreference ?? "ours",
+            requested_preference_applied: receipt.requested_preference_applied ??
+                (receipt.conflict_resolution ?? "preferred_side") === "preferred_side",
+            conflict_resolution: receipt.conflict_resolution ?? "preferred_side",
             evidence_source: evidenceSource,
         },
     };
@@ -638,4 +809,4 @@ export const _testOnlyMergeReceipts = {
     receiptDirectoryFailureMeansAbsent,
 };
 //# sourceMappingURL=receipts.js.map
-//# debugId=df7d5bd9-8381-5961-bda1-9e8ed335afc9
+//# debugId=dfdd6f10-e11f-59e8-a16f-507dc40d5b31