@unbrained/pm-cli 2026.9.2 → 2026.9.4

package/dist/sdk/environment/project-runtime-compatibility.js

@@ -5,7 +5,7 @@
  * leaving diagnosis reads available.
  */
 
-!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]="962636b0-ed3b-5ad0-ae0c-904435025986")}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]="f9737b75-b285-5fe9-a9ce-63e7c07626cb")}catch(e){}}();
 import fs from "node:fs";
 import path from "node:path";
 import { EXIT_CODE } from "../../core/shared/constants.js";
@@ -80,6 +80,8 @@ const GLOBAL_VALUE_FLAGS = new Set([
     "--pm-path",
 ]);
 const VERSION_PATTERN = /\b(\d{4})\.(\d{1,2})\.(\d{1,2})(?:-(\d+))?\b/u;
+/** First pm release whose history writer and reader support item-hash epoch 3. */
+export const HISTORY_ITEM_HASH_VERSION_3_INTRODUCED_IN = "2026.8.31";
 /** Return whether an invocation includes one of the exact mutation switches. */
 function hasAnyToken(argv, tokens) {
     return argv.some((token) => tokens.includes(token.split("=", 1)[0]));
@@ -194,6 +196,21 @@ export function comparePmDateVersions(left, right) {
     }
     return 0;
 }
+/** Resolve the item-hash epoch written by a known pm runtime release. */
+export function historyItemHashVersionForRuntime(version) {
+    return comparePmDateVersions(version, HISTORY_ITEM_HASH_VERSION_3_INTRODUCED_IN) !== -1
+        ? 3
+        : 2;
+}
+/** Find the oldest declaration that cannot select a reader for the executing writer epoch. */
+function findIncompatibleHistoryEpochPin(pins, writerItemHashVersion) {
+    if (writerItemHashVersion !== 3)
+        return undefined;
+    return pins
+        .filter((pin) => pin.history_epoch_compatible === false)
+        .map((pin) => ({ ...pin, declaration: pin.declaration ?? pin.version }))
+        .sort((left, right) => comparePmDateVersions(left.version, right.version))[0];
+}
 /** Read one optional JSON object without turning absence or corruption into startup failure. */
 function readJsonRecord(filePath) {
     try {
@@ -208,27 +225,61 @@ function readJsonRecord(filePath) {
         return null;
     }
 }
-/** Extract the highest explicit lower-bound pm date version from dependency declarations. */
-function dependencyPin(packageJson) {
-    const versions = [];
-    for (const field of [
+/** Extract explicit comparator and hyphen upper bounds from one range branch. */
+function rangeUpperBounds(alternative) {
+    const comparators = [
+        ...alternative.matchAll(/(<=|<)\s*v?(\d{4}\.\d{1,2}\.\d{1,2}(?:-\d+)?)/gu),
+    ].map((match) => ({ inclusive: match[1] === "<=", version: match[2] }));
+    const hyphen = alternative.match(/\b\d{4}\.\d{1,2}\.\d{1,2}(?:-\d+)?\s+-\s+v?(\d{4}\.\d{1,2}\.\d{1,2}(?:-\d+)?)/u);
+    return hyphen
+        ? [...comparators, { inclusive: true, version: hyphen[1] }]
+        : comparators;
+}
+/** Classify whether a range is bounded and can select an epoch-3 reader. */
+function analyzeHistoryEpochRange(specification) {
+    const alternativeBounds = specification
+        .split("||")
+        .map((alternative) => rangeUpperBounds(alternative));
+    return {
+        bounded: alternativeBounds.some((bounds) => bounds.length > 0),
+        compatible: alternativeBounds.some((bounds) => bounds.every((bound) => {
+            const comparison = comparePmDateVersions(HISTORY_ITEM_HASH_VERSION_3_INTRODUCED_IN, bound.version);
+            return (comparison !== null &&
+                (bound.inclusive ? comparison !== 1 : comparison === -1));
+        })),
+    };
+}
+/** Extract every supported pm declaration without letting one section hide another. */
+function dependencyPins(packageJson) {
+    return [
         "dependencies",
         "devDependencies",
         "optionalDependencies",
         "peerDependencies",
-    ]) {
+    ].flatMap((field) => {
         const dependencies = packageJson[field];
         if (typeof dependencies !== "object" || dependencies === null)
-            continue;
+            return [];
         const value = dependencies[PACKAGE_NAME];
         const specification = typeof value === "string" ? value.trim() : "";
         const version = /^[<!]/u.test(specification)
             ? undefined
             : specification.match(VERSION_PATTERN)?.[0];
-        if (version)
-            versions.push(version);
-    }
-    return versions.sort((left, right) => comparePmDateVersions(right, left))[0];
+        if (!version)
+            return [];
+        const exact = /^(?:=|v)?\d{4}\.\d{1,2}\.\d{1,2}(?:-\d+)?$/u.test(specification);
+        const range = analyzeHistoryEpochRange(specification);
+        return [
+            {
+                version,
+                constraint: exact ? "exact" : range.bounded ? "range" : "minimum",
+                ...(exact ? {} : { declaration: specification }),
+                history_epoch_compatible: exact
+                    ? comparePmDateVersions(version, HISTORY_ITEM_HASH_VERSION_3_INTRODUCED_IN) !== -1
+                    : range.compatible,
+            },
+        ];
+    });
 }
 /** Read npm's exact installed package coordinate from package-lock.json. */
 function packageLockPin(projectRoot) {
@@ -273,23 +324,42 @@ function textLockPin(projectRoot, file) {
 export function discoverProjectRuntimeVersionPins(projectRoot) {
     const pins = [];
     const projectPackage = readJsonRecord(path.join(projectRoot, "package.json"));
-    const declared = projectPackage ? dependencyPin(projectPackage) : undefined;
-    if (declared)
-        pins.push({ version: declared, source: "package.json" });
+    if (projectPackage) {
+        pins.push(...dependencyPins(projectPackage).map((pin) => ({
+            ...pin,
+            source: "package.json",
+        })));
+    }
     const installedPackage = readJsonRecord(path.join(projectRoot, "node_modules", "@unbrained", "pm-cli", "package.json"));
     const installedVersion = installedPackage?.version;
     if (typeof installedVersion === "string" &&
         parseDateVersion(installedVersion)) {
-        pins.push({ version: installedVersion, source: "installed-package" });
+        pins.push({
+            version: installedVersion,
+            source: "installed-package",
+            constraint: "exact",
+            history_epoch_compatible: historyItemHashVersionForRuntime(installedVersion) === 3,
+        });
     }
     const packageLockVersion = packageLockPin(projectRoot);
     if (packageLockVersion && parseDateVersion(packageLockVersion)) {
-        pins.push({ version: packageLockVersion, source: "package-lock.json" });
+        pins.push({
+            version: packageLockVersion,
+            source: "package-lock.json",
+            constraint: "exact",
+            history_epoch_compatible: historyItemHashVersionForRuntime(packageLockVersion) === 3,
+        });
     }
     for (const file of ["pnpm-lock.yaml", "yarn.lock"]) {
         const version = textLockPin(projectRoot, file);
-        if (version)
-            pins.push({ version, source: file });
+        if (version) {
+            pins.push({
+                version,
+                source: file,
+                constraint: "exact",
+                history_epoch_compatible: historyItemHashVersionForRuntime(version) === 3,
+            });
+        }
     }
     return pins;
 }
@@ -339,6 +409,9 @@ export function inspectProjectRuntimeCompatibility(options) {
     const newest = pins[0];
     const stale = newest !== undefined &&
         comparePmDateVersions(options.executingVersion, newest.version) === -1;
+    const writerItemHashVersion = historyItemHashVersionForRuntime(options.executingVersion);
+    const incompatibleEpochPin = findIncompatibleHistoryEpochPin(pins, writerItemHashVersion);
+    const historyEpochIncompatible = mutating && incompatibleEpochPin !== undefined;
     const warning = stale && !mutating
         ? {
             code: "project_runtime_stale_read",
@@ -353,7 +426,9 @@ export function inspectProjectRuntimeCompatibility(options) {
         }
         : undefined;
     return {
-        compatible: !mutating || !stale || options.allowStale === true,
+        compatible: !mutating ||
+            (!stale && !historyEpochIncompatible) ||
+            options.allowStale === true,
         executing_version: options.executingVersion,
         ...(newest
             ? { project_version: newest.version, source: newest.source }
@@ -361,8 +436,18 @@ export function inspectProjectRuntimeCompatibility(options) {
         ...(command ? { command } : {}),
         mutating,
         stale,
+        history_epoch_incompatible: historyEpochIncompatible,
+        writer_item_hash_version: writerItemHashVersion,
+        ...(incompatibleEpochPin
+            ? {
+                incompatible_project_version: incompatibleEpochPin.declaration,
+                incompatible_source: incompatibleEpochPin.source,
+            }
+            : {}),
         ...(warning ? { warning } : {}),
-        override_applied: stale && mutating && options.allowStale === true,
+        override_applied: mutating &&
+            (stale || historyEpochIncompatible) &&
+            options.allowStale === true,
     };
 }
 /** Refuse stale mutations with a stable SDK error and package-neutral recovery. */
@@ -370,6 +455,18 @@ export function assertProjectRuntimeCompatibility(options) {
     const result = inspectProjectRuntimeCompatibility(options);
     if (result.compatible)
         return result;
+    if (result.history_epoch_incompatible) {
+        throw new PmCliError(`pm ${result.executing_version} cannot write item-hash epoch ${result.writer_item_hash_version} into a project pinned to pm ${result.incompatible_project_version}.`, EXIT_CODE.CONFLICT, {
+            code: "project_runtime_history_epoch_incompatible",
+            reason: result.incompatible_source,
+            why: `The pinned runtime cannot read item_hash_version ${result.writer_item_hash_version}; allowing the write would break its health and validation gates.`,
+            nextSteps: [
+                `Upgrade the project's ${PACKAGE_NAME} pin to ${HISTORY_ITEM_HASH_VERSION_3_INTRODUCED_IN} or newer before mutating tracker history.`,
+                "For an intentional coordinated migration only, set PM_ALLOW_STALE_CLI=1 for this invocation and record why.",
+                "Read-only commands remain available without an override.",
+            ],
+        });
+    }
     throw new PmCliError(`pm ${result.executing_version} cannot mutate a project pinned to newer pm ${result.project_version}.`, EXIT_CODE.CONFLICT, {
         code: "project_runtime_stale_mutation",
         reason: result.source,
@@ -382,4 +479,4 @@ export function assertProjectRuntimeCompatibility(options) {
     });
 }
 //# sourceMappingURL=project-runtime-compatibility.js.map
-//# debugId=962636b0-ed3b-5ad0-ae0c-904435025986
+//# debugId=f9737b75-b285-5fe9-a9ce-63e7c07626cb

package/dist/sdk/generated/generated-error-code-catalog-part-1.js

@@ -1,6 +1,6 @@
 /** Generated partition 1 of the exhaustive error-code catalog. */
 
-!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]="4734edf6-c174-50d0-b4e9-1003bc8a20bf")}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]="f9059953-1d3c-5c1c-b739-4ad6cc8815a3")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_1 = [
     {
         code: "acceptance_criteria_mutation_conflict",
@@ -1271,6 +1271,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "history_target_out_of_range",
         aliases: [],
     },
+    {
+        code: "history_timestamp_invalid",
+        meaning: "History timestamp invalid condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/history/event-index.ts", "core/history/history.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "history_timestamp_invalid",
+        aliases: [],
+    },
     {
         code: "history_unknown_author_events",
         meaning: "History unknown author events condition.",
@@ -2162,4 +2174,4 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
     },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-1.js.map
-//# debugId=4734edf6-c174-50d0-b4e9-1003bc8a20bf
+//# debugId=f9059953-1d3c-5c1c-b739-4ad6cc8815a3

package/dist/sdk/generated/generated-error-code-catalog-part-2.js

@@ -1,6 +1,6 @@
 /** Generated partition 2 of the exhaustive error-code catalog. */
 
-!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]="41e6f81d-ccb5-546c-9b26-3b78027528b5")}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]="f1a77960-6191-5e11-9622-4250be7b0e89")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_2 = [
     {
         code: "missing_destination",
@@ -487,6 +487,18 @@ export const PM_ERROR_CODE_CATALOG_PART_2 = [
         canonical_code: "profile_title_empty",
         aliases: [],
     },
+    {
+        code: "project_runtime_history_epoch_incompatible",
+        meaning: "Project runtime history epoch incompatible condition.",
+        stability: "provisional",
+        exit_code: 4,
+        class: "conflict",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/environment/project-runtime-compatibility.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "project_runtime_history_epoch_incompatible",
+        aliases: [],
+    },
     {
         code: "project_runtime_stale_mutation",
         meaning: "Project runtime stale mutation condition.",
@@ -2174,4 +2186,4 @@ export const PM_ERROR_CODE_CATALOG_PART_2 = [
     },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-2.js.map
-//# debugId=41e6f81d-ccb5-546c-9b26-3b78027528b5
+//# debugId=f1a77960-6191-5e11-9622-4250be7b0e89

package/dist/sdk/governance/health.js

@@ -4,7 +4,7 @@
  * Implements the pm health 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]="f27cb24d-f2c8-5034-b655-84c577de7a16")}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]="9f0077a4-4f0a-540f-9951-2e8a640629c9")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
@@ -28,7 +28,6 @@ import { EXIT_CODE, PM_CORE_REQUIRED_SUBDIRS, TYPE_TO_FOLDER, } from "../../core
 import { findFirstMergeConflictMarker } from "../../core/shared/conflict-markers.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
-import { sha256Hex } from "../../core/shared/serialization.js";
 import { nowIso } from "../../core/shared/time.js";
 import { parseItemDocument } from "../../core/item/item-format.js";
 import { effectiveItemFormatVersion, scanItemFormatVersions, } from "../../core/item/item-format-version.js";
@@ -47,7 +46,8 @@ import { buildCapabilityContractMetadata, buildRegistrationCollisionRemediation,
 import { scanStaleInProgressItems, } from "./stale-work.js";
 import { scanTrackedRuntimeCache } from "./tracked-runtime-cache.js";
 import { auditMergeDriverConfiguration, findGitWorkspaceRoot, } from "../merge/install.js";
-import { inspectMergeReceiptEvidence, isSafeReceiptId, partitionMergeReceipts, } from "../merge/receipts.js";
+import { inspectMergeReceiptEvidence, partitionMergeReceipts, } from "../merge/receipts.js";
+import { classifyHistoryMergeReceiptReferences, extractHistoryMergeReceiptDispositions, extractHistoryMergeReceiptReferences, } from "./merge-receipt-history.js";
 import { runHistoryRepair } from "../history-repair.js";
 import { resolveWorkspaceRelationshipKindRegistry } from "../graph/assembly.js";
 import { analyzeHierarchyIntegrity, } from "../graph/hierarchy-integrity.js";
@@ -279,41 +279,13 @@ async function scanItemIntegrity(pmRoot, typeToFolder, schema) {
     }
     return { paths, unreadable, conflictMarkers, parseFailures, formatVersions };
 }
-function mergeReceiptIdsFromHistoryEntry(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        return [];
-    }
-    const context = value.context;
-    if (typeof context !== "object" ||
-        context === null ||
-        Array.isArray(context)) {
-        return [];
-    }
-    const merge = context.merge;
-    if (typeof merge !== "object" || merge === null || Array.isArray(merge)) {
-        return [];
-    }
-    const receipts = merge.receipts;
-    if (!Array.isArray(receipts))
-        return [];
-    return receipts.flatMap((receipt) => {
-        if (typeof receipt !== "object" ||
-            receipt === null ||
-            Array.isArray(receipt)) {
-            return [];
-        }
-        const receiptId = receipt.receipt_id;
-        return typeof receiptId === "string" && receiptId.length > 0
-            ? [receiptId]
-            : [];
-    });
-}
 async function scanHistoryIntegrity(pmRoot) {
     const historyDir = path.join(pmRoot, "history");
     const unreadable = [];
     const conflictMarkers = [];
     const invalidJson = [];
     const mergeReceiptReferences = [];
+    const mergeReceiptDispositions = [];
     let files = [];
     try {
         files = (await fs.readdir(historyDir))
@@ -346,11 +318,12 @@ async function scanHistoryIntegrity(pmRoot) {
                 return;
             try {
                 const parsed = JSON.parse(line);
-                mergeReceiptReferences.push(...mergeReceiptIdsFromHistoryEntry(parsed).map((receiptId) => ({
+                mergeReceiptReferences.push(...extractHistoryMergeReceiptReferences(parsed, itemId).map((reference) => ({
                     itemId,
                     line: index + 1,
-                    receiptId,
+                    ...reference,
                 })));
+                mergeReceiptDispositions.push(...extractHistoryMergeReceiptDispositions(parsed, itemId, index + 1));
             }
             catch {
                 invalidJson.push({ id: itemId, line: index + 1 });
@@ -363,6 +336,7 @@ async function scanHistoryIntegrity(pmRoot) {
         conflictMarkers,
         invalidJson,
         mergeReceiptReferences,
+        mergeReceiptDispositions,
     };
 }
 function buildHierarchyIntegrityWarnings(analysis) {
@@ -405,15 +379,8 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
         pmRoot,
     });
     const availableMergeReceiptIds = new Set(mergeReceiptEvidence.receipts.map((receipt) => receipt.id));
-    const missingMergeReceiptReferences = historyScan.mergeReceiptReferences
-        .filter((reference) => !availableMergeReceiptIds.has(reference.receiptId))
-        .map((reference) => ({
-        item_id: reference.itemId,
-        history_line: reference.line,
-        ...(isSafeReceiptId(reference.receiptId)
-            ? { receipt_id: reference.receiptId }
-            : { receipt_reference_hash: sha256Hex(reference.receiptId) }),
-    }));
+    const historyReceiptClassification = classifyHistoryMergeReceiptReferences(historyScan.mergeReceiptReferences, availableMergeReceiptIds, historyScan.mergeReceiptDispositions);
+    const missingMergeReceiptReferences = historyReceiptClassification.missing;
     const pendingMergeReceipts = mergeReceiptEvidence.receipts.filter((receipt) => receipt.state === "pending");
     const { pendingDecisions: pendingMergeDecisions, lossless: losslessMergeReceipts, } = partitionMergeReceipts(pendingMergeReceipts);
     const mergeDriverInstallationMissing = mergeDriverAudit?.status === "missing" &&
@@ -483,6 +450,8 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
                     lossless_merge_receipts: losslessMergeReceipts.length,
                     invalid_merge_receipt_evidence: mergeReceiptEvidence.invalid_evidence_count,
                     missing_merge_receipt_history_references: missingMergeReceiptReferences.length,
+                    accepted_legacy_merge_receipt_references: historyReceiptClassification.acceptedLegacyCount,
+                    accepted_missing_merge_receipt_dispositions: historyReceiptClassification.acceptedDispositionCount,
                 },
                 item_unreadable: itemScan.unreadable,
                 item_conflict_markers: itemScan.conflictMarkers,
@@ -2375,4 +2344,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=f27cb24d-f2c8-5034-b655-84c577de7a16
+//# debugId=9f0077a4-4f0a-540f-9951-2e8a640629c9

package/dist/sdk/governance/merge-receipt-history.d.ts

@@ -0,0 +1,62 @@
+/** First commit timestamp at which merge receipts gained a tracked durable copy. */
+export declare const DURABLE_MERGE_RECEIPT_INTRODUCED_AT = "2026-08-09T16:15:18.000Z";
+/** One receipt reference discovered at an immutable history coordinate. */
+export interface HistoryMergeReceiptReference {
+    /** Item whose history contains the summary. */
+    itemId: string;
+    /** One-based history line containing the summary. */
+    line: number;
+    /** Privacy-safe receipt identifier. */
+    receiptId: string;
+    /** Whether the summary is a complete supported preferred-era record. */
+    legacySummaryAccepted: boolean;
+    /** Timestamp of the history event that introduced the reference, when valid. */
+    eventTimestamp?: string;
+}
+/** Audited disposition for one receipt that a pre-durable writer could never publish. */
+export interface HistoryMergeReceiptDisposition {
+    /** Item whose history contains both the original reference and disposition. */
+    itemId: string;
+    /** Receipt identity explicitly accepted as unrecoverable. */
+    receiptId: string;
+    /** One-based coordinate of the original merge event. */
+    originalHistoryLine: number;
+    /** Timestamp copied from the original merge event for exact matching. */
+    originalEventTimestamp: string;
+    /** One-based coordinate of the later audit event that records this disposition. */
+    auditHistoryLine: number;
+    /** Closed reason vocabulary for this exceptional compatibility path. */
+    reason: "legacy_clone_local_only";
+}
+/** Missing-reference coordinate returned to bounded integrity diagnostics. */
+export interface MissingHistoryMergeReceiptReference {
+    /** Item whose history contains the unresolved reference. */
+    item_id: string;
+    /** One-based history line containing the unresolved reference. */
+    history_line: number;
+    /** Safe identifier when the source value is suitable for diagnostics. */
+    receipt_id?: string;
+    /** Digest used instead of an unsafe identifier. */
+    receipt_reference_hash?: string;
+}
+/** Partitioned compatibility outcome for all scanned history references. */
+export interface HistoryMergeReceiptReferenceClassification {
+    /** References requiring authoritative external evidence. */
+    missing: MissingHistoryMergeReceiptReference[];
+    /** Complete preferred-era summaries accepted without impossible migration. */
+    acceptedLegacyCount: number;
+    /** Pre-durable references accepted by a later explicit audited disposition. */
+    acceptedDispositionCount: number;
+}
+/** Return whether one summary is a complete, self-contained preferred-era receipt. */
+export declare function isLegacyMergeReceiptSummary(value: Record<string, unknown>, historyItemId: string): boolean;
+/** Return whether a summary matches the final clone-local-only schema before durable receipts. */
+export declare function isPreDurableCloneLocalReceiptSummary(value: Record<string, unknown>, historyItemId: string): boolean;
+/** Return whether an extracted reference carried a validated pre-durable summary. */
+export declare function isPreDurableDispositionEligibleReference(reference: Omit<HistoryMergeReceiptReference, "itemId" | "line">): boolean;
+/** Extract receipt ids and legacy compatibility disposition from one history entry. */
+export declare function extractHistoryMergeReceiptReferences(value: unknown, historyItemId: string): Array<Omit<HistoryMergeReceiptReference, "itemId" | "line">>;
+/** Extract validated explicit missing-receipt dispositions from one merge audit event. */
+export declare function extractHistoryMergeReceiptDispositions(value: unknown, historyItemId: string, historyLine: number): HistoryMergeReceiptDisposition[];
+/** Classify scanned references without treating complete legacy summaries as absent. */
+export declare function classifyHistoryMergeReceiptReferences(references: readonly HistoryMergeReceiptReference[], availableReceiptIds: ReadonlySet<string>, dispositions?: readonly HistoryMergeReceiptDisposition[]): HistoryMergeReceiptReferenceClassification;