@murphai/murph 1.2.0 → 1.2.4

package/node_modules/@murphai/core/dist/mutations.js

@@ -1,14 +1,14 @@
 import { createHash } from "node:crypto";
-import { assertContractId, deviceDataOriginSchema, experimentFrontmatterSchema, externalRefSchema, journalDayFrontmatterSchema, eventRecordSchema, safeParseContract, sampleRecordSchema, } from "@murphai/contracts";
+import { assertContractId, compareIsoTimestampsAscending, COMPANION_HRV_RMSSD_METHOD_VERSION, deviceDataOriginSchema, experimentFrontmatterSchema, externalRefSchema, journalDayFrontmatterSchema, eventRecordSchema, eventImportDecisionSchema, isWritableIsoDateTime, safeParseContract, sampleRecordSchema, } from "@murphai/contracts";
 import { BASELINE_EVENT_KINDS, BASELINE_SAMPLE_STREAMS, EVENT_SCHEMA_VERSION, EVENT_SOURCES, FRONTMATTER_SCHEMA_VERSIONS, ID_PREFIXES, SAMPLE_QUALITIES, SAMPLE_SCHEMA_VERSION, SAMPLE_SOURCES, VAULT_LAYOUT, } from "./constants.js";
 import { emitAuditRecord } from "./audit.js";
 import { prepareEventAttachments, stagePreparedEventAttachmentsInBatch, } from "./event-attachments.js";
 import { assertNoLegacyRelatedIds, normalizeCanonicalEventLinks, } from "./event-links.js";
 import { VaultError } from "./errors.js";
-import { pathExists, readUtf8File, walkVaultFiles, writeVaultTextFile } from "./fs.js";
+import { pathExists, readUtf8File, walkVaultFiles, walkVaultFilesInterruptible, writeVaultTextFile, } from "./fs.js";
 import { parseFrontmatterDocument, stringifyFrontmatterDocument } from "./frontmatter.js";
 import { deterministicContractId, generateRecordId } from "./ids.js";
-import { readJsonlRecords, toMonthlyShardRelativePath } from "./jsonl.js";
+import { readJsonlRecords, toMonthlyShardRelativePath, visitJsonlRecordsInterruptible, } from "./jsonl.js";
 import { buildEventSpineLifecycle, collapseEventSpineEntries, compareEventSpineEntries, eventSpineRevision, isDeletedEventSpineRecord, selectLatestEventSpineEntry, } from "./history/event-spine.js";
 import { buildPublicEventImportRecord, loadEventLedgerShardsById, selectLatestMatchedEvent, toEventLedgerFile, } from "./domains/events/ledger.js";
 import { normalizeMealNutrition, } from "./nutrition.js";
@@ -18,7 +18,7 @@ import { assertCanonicalWriteLockScope } from "./operations/canonical-write-lock
 import { resolveVaultPath } from "./path-safety.js";
 import { sanitizePathSegment } from "./path-safety.js";
 import { prepareInlineRawArtifact, prepareRawArtifact, resolveRawAssetDirectory } from "./raw.js";
-import { buildIntegrationEvidencePart, buildIntegrationIngestAppendPlan, buildIntegrationIngestRecord, stageIntegrationIngestAppendPlan, compactIntegrationIngestReceipt, } from "./integration-ingests.js";
+import { buildIntegrationEvidencePart, buildIntegrationIngestAppendPlan, buildIntegrationIngestAppendPlanFromInspection, buildIntegrationIngestRecord, stageIntegrationIngestAppendPlan, compactIntegrationIngestReceipt, inspectIntegrationIngestIdsForImportedAt, selectNovelIntegrationIngestEvidence, } from "./integration-ingests.js";
 import { normalizeUniqueTextList } from "./bank/shared.js";
 import { defaultTimeZone, normalizeTimeZone, toIsoTimestamp, toLocalDayKey, } from "./time.js";
 import { loadVault } from "./vault.js";
@@ -450,18 +450,24 @@ function buildSampleRecord({ recordId, ...input }) {
         recordId: recordId ?? generateRecordId(ID_PREFIXES.sample),
     });
 }
-async function readExistingRecordIds(vaultRoot, relativePath) {
+async function readExistingRecordIds(vaultRoot, relativePath, signal) {
+    signal?.throwIfAborted();
     const resolved = resolveVaultPath(vaultRoot, relativePath);
     if (!(await pathExists(resolved.absolutePath))) {
         return new Set();
     }
-    const records = await readJsonlRecords({
+    const ids = new Set();
+    await visitJsonlRecordsInterruptible({
         vaultRoot,
         relativePath,
+        signal,
+        visit(record) {
+            if (typeof record.id === "string") {
+                ids.add(record.id);
+            }
+        },
     });
-    return new Set(records
-        .map((record) => (typeof record.id === "string" ? record.id : null))
-        .filter((id) => id !== null));
+    return ids;
 }
 async function buildJsonlAppendPlan(vaultRoot, entries, options = {}) {
     assertCanonicalWriteLockScope(vaultRoot);
@@ -470,8 +476,9 @@ async function buildJsonlAppendPlan(vaultRoot, entries, options = {}) {
     const targetShardPaths = [...new Set(entries.map((entry) => entry.relativePath))].sort();
     const appendedRecordIds = [];
     for (const entry of entries) {
+        options.signal?.throwIfAborted();
         const existingIds = existingIdsByShard.get(entry.relativePath) ??
-            (await readExistingRecordIds(vaultRoot, entry.relativePath));
+            (await readExistingRecordIds(vaultRoot, entry.relativePath, options.signal));
         existingIdsByShard.set(entry.relativePath, existingIds);
         if (existingIds.has(entry.record.id) && !options.forceAppendIds?.has(entry.record.id)) {
             continue;
@@ -514,13 +521,22 @@ function normalizeDeviceEventInputs(eventInputs, context) {
             errorMessage: `Device event ${index + 1} relatedIds is no longer supported; use links.`,
         });
         const normalizedLegacyExternalRefs = normalizeLegacyExternalRefs(eventInput.legacyExternalRefs, index);
+        const externalRefUpdatePolicy = eventInput.externalRefUpdatePolicy;
+        if (externalRefUpdatePolicy !== undefined && externalRefUpdatePolicy !== "immutable") {
+            throw new VaultError("VAULT_INVALID_EXTERNAL_REF", `Device event ${index + 1} externalRefUpdatePolicy must be "immutable" when provided.`);
+        }
+        const inputDayKey = typeof eventInput.dayKey === "string" ? eventInput.dayKey : undefined;
+        const inputTimeZone = typeof eventInput.timeZone === "string" ? eventInput.timeZone : undefined;
+        const preservesProviderDayWithoutTimeZone = Boolean(inputDayKey &&
+            !inputTimeZone &&
+            isJunctionSleepStageExternalRefInput(eventInput.externalRef));
         const seed = buildNormalizedEventSeed({
             kind,
             occurredAt: eventInput.occurredAt ?? eventInput.recordedAt ?? context.importedAt,
             recordedAt: eventInput.recordedAt ?? eventInput.occurredAt,
-            dayKey: typeof eventInput.dayKey === "string" ? eventInput.dayKey : undefined,
-            timeZone: typeof eventInput.timeZone === "string" ? eventInput.timeZone : undefined,
-            defaultTimeZone: context.defaultTimeZone,
+            dayKey: inputDayKey,
+            timeZone: inputTimeZone,
+            defaultTimeZone: preservesProviderDayWithoutTimeZone ? undefined : context.defaultTimeZone,
             source: eventInput.source ?? context.source,
             title: typeof eventInput.title === "string" ? eventInput.title : undefined,
             note: eventInput.note,
@@ -536,9 +552,13 @@ function normalizeDeviceEventInputs(eventInputs, context) {
         if (legacyExternalRefs.length > 0 && !seed.externalRef) {
             throw new VaultError("VAULT_INVALID_EXTERNAL_REF", `Device event ${index + 1} legacyExternalRefs require externalRef.`);
         }
+        if (externalRefUpdatePolicy === "immutable" && !seed.externalRef) {
+            throw new VaultError("VAULT_INVALID_EXTERNAL_REF", `Device event ${index + 1} immutable externalRefUpdatePolicy requires externalRef.`);
+        }
         return {
             seed,
             evidenceRoles,
+            ...(externalRefUpdatePolicy === "immutable" ? { externalRefUpdatePolicy } : {}),
             legacyExternalRefs,
             recordId: deterministicContractId(ID_PREFIXES.event, stableStringify({
                 provider: context.provider,
@@ -630,7 +650,8 @@ function normalizeDeviceBatchInputs({ provider, accountId, importedAt = new Date
     const normalizedSource = normalizeSource(source, EVENT_SOURCE_SET, "device");
     const defaultTimeZone = normalizeTimeZone(fallbackTimeZone);
     const normalizedProvenance = normalizeLooseRecord(provenance, "VAULT_INVALID_DEVICE_PROVENANCE", "Device import provenance must be a plain object.") ?? {};
-    const normalizedIngestReceipt = normalizeLooseRecord(ingestReceipt, "INTEGRATION_INGEST_RECEIPT_INVALID", "Device ingest receipt must be a plain object.");
+    const legacyIngestReceipt = normalizeLooseRecord(ingestReceipt, "INTEGRATION_INGEST_RECEIPT_INVALID", "Device ingest receipt must be a plain object.");
+    const normalizedIngestReceipt = compactIntegrationIngestReceipt(legacyIngestReceipt);
     const eventInputs = normalizeDeviceBatchObjectArray({
         value: events,
         code: "VAULT_INVALID_DEVICE_EVENTS",
@@ -666,6 +687,7 @@ function normalizeDeviceBatchInputs({ provider, accountId, importedAt = new Date
         defaultTimeZone,
         provenance: normalizedProvenance,
         ingestReceipt: normalizedIngestReceipt,
+        legacyIngestReceipt,
         events: normalizeDeviceEventInputs(eventInputs, {
             provider: normalizedProvider,
             accountId: normalizedAccountId,
@@ -713,6 +735,9 @@ function prepareDeviceEventEntries(events, evidenceParts) {
         evidenceRolesByPreparedRecordId.set(event.recordId, uniqueRoles);
         return {
             ...prepareStoredEventLedgerEntry(event.seed, event.recordId),
+            ...(event.externalRefUpdatePolicy
+                ? { externalRefUpdatePolicy: event.externalRefUpdatePolicy }
+                : {}),
             legacyExternalRefs: event.legacyExternalRefs,
         };
     });
@@ -736,6 +761,17 @@ function eventExternalRefKey(externalRef) {
         facet: externalRef.facet ?? null,
     });
 }
+function compareIncomingExternalRefVersion(existing, incoming) {
+    const existingVersion = existing.version;
+    const incomingVersion = incoming.version;
+    if (!existingVersion
+        || !incomingVersion
+        || !isWritableIsoDateTime(existingVersion)
+        || !isWritableIsoDateTime(incomingVersion)) {
+        return null;
+    }
+    return compareIsoTimestampsAscending(incomingVersion, existingVersion);
+}
 // Device-sync content equality ignores per-import identity (id, lifecycle,
 // recordedAt) AND rawRefs, because device imports mint fresh raw-artifact
 // paths on every sync run.
@@ -743,59 +779,178 @@ function deviceEventContentKey(record) {
     const { id: _id, rawRefs: _rawRefs, lifecycle: _lifecycle, recordedAt: _recordedAt, ...content } = record;
     return stableStringify(content);
 }
+function isWhoopCompanionHrvRmssdAdmissionEvent(record) {
+    const externalRef = record.externalRef;
+    const admissionId = externalRef?.resourceId;
+    return record.kind === "observation"
+        && externalRef?.system === "whoop"
+        && externalRef.resourceType === "ble-hrv-rmssd"
+        && externalRef.facet === "hrv-rmssd"
+        && typeof admissionId === "string"
+        && /^[a-f0-9]{64}$/u.test(admissionId)
+        && externalRef.version === `${COMPANION_HRV_RMSSD_METHOD_VERSION}:${admissionId}`
+        && record.dataOrigin?.aggregatorProvider === "murph-companion"
+        && record.dataOrigin.sourceProviderSlug === "whoop"
+        && record.dataOrigin.sourceType === "ble-pulse-interval"
+        && record.dataOrigin.normalizerVersion === "companion-hrv-rmssd-normalizer.v1";
+}
+function isWhoopCompanionHrvRmssdTemporalReplay(existing, incoming) {
+    if (!isWhoopCompanionHrvRmssdAdmissionEvent(existing)
+        || !isWhoopCompanionHrvRmssdAdmissionEvent(incoming)) {
+        return false;
+    }
+    const { id: _existingId, rawRefs: _existingRawRefs, lifecycle: _existingLifecycle, recordedAt: _existingRecordedAt, dayKey: _existingDayKey, timeZone: _existingTimeZone, ...existingContent } = existing;
+    const { id: _incomingId, rawRefs: _incomingRawRefs, lifecycle: _incomingLifecycle, recordedAt: _incomingRecordedAt, dayKey: _incomingDayKey, timeZone: _incomingTimeZone, ...incomingContent } = incoming;
+    return stableStringify(existingContent) === stableStringify(incomingContent);
+}
+function deviceEventContentFingerprint(record) {
+    return createHash("sha256").update(deviceEventContentKey(record)).digest("hex");
+}
 // Public bulk-import content equality also ignores per-import identity (id,
 // lifecycle, and recordedAt, which defaults to the import wall clock), but it
-// keeps rawRefs: import payloads carry caller-supplied provenance there, so a
-// rawRefs-only correction must supersede the stored event instead of being
-// skipped as identical.
+// keeps rawRefs. For unversioned rows, a rawRefs-only correction supersedes the
+// stored event. Comparable versioned rows are ordered by source revision:
+// older revisions are skipped, equal revisions must replay-match or the batch
+// is rejected as a conflict, and newer revisions supersede.
 function eventImportContentKey(record) {
     const { id: _id, lifecycle: _lifecycle, recordedAt: _recordedAt, ...content } = record;
     return stableStringify(content);
 }
-async function indexLatestEventsByExternalRef(vaultRoot, relativePaths) {
+// Equal source revisions must compare caller-supplied provenance while
+// ignoring vault-local day placement and equivalent version lexemes.
+function eventImportVersionedReplayContentKey(record) {
+    const { id: _id, dayKey: _dayKey, lifecycle: _lifecycle, recordedAt: _recordedAt, externalRef, ...content } = record;
+    const semanticExternalRef = externalRef
+        ? {
+            system: externalRef.system,
+            resourceType: externalRef.resourceType,
+            resourceId: externalRef.resourceId,
+            facet: externalRef.facet,
+        }
+        : undefined;
+    return stableStringify({ ...content, externalRef: semanticExternalRef });
+}
+// Comparable source revisions describe the provider resource, not the local
+// retrieval that happened to carry it. Ignore capture-local provenance, the
+// vault-timezone-derived day key, and the version lexeme while deciding
+// whether an equal revision is a replay.
+function eventImportSourceSemanticContentKey(record) {
+    const { id: _id, dayKey: _dayKey, lifecycle: _lifecycle, recordedAt: _recordedAt, rawRefs: _rawRefs, evidence: _evidence, externalRef, ...content } = record;
+    const semanticExternalRef = externalRef
+        ? {
+            system: externalRef.system,
+            resourceType: externalRef.resourceType,
+            resourceId: externalRef.resourceId,
+            facet: externalRef.facet,
+        }
+        : undefined;
+    return stableStringify({ ...content, externalRef: semanticExternalRef });
+}
+const EVENT_IMPORT_RETRACTION_MARKER_NOTE_TYPE = "event_import_retraction_marker";
+function preparedEventImportDecisionExternalRef(decision) {
+    return decision.action === "retract"
+        ? decision.externalRef
+        : decision.entry.record.externalRef;
+}
+function orderEventImportDecisionsBySourceVersion(decisions) {
+    const ordered = [...decisions];
+    const groups = new Map();
+    decisions.forEach((decision, index) => {
+        const externalRef = preparedEventImportDecisionExternalRef(decision);
+        const isExplicitDecision = decision.action === "retract" || decision.allowsKindReplacement;
+        if (!isExplicitDecision
+            || !externalRef?.version
+            || !isWritableIsoDateTime(externalRef.version)) {
+            return;
+        }
+        const refKey = eventExternalRefKey(externalRef);
+        const group = groups.get(refKey) ?? [];
+        group.push({ decision, index });
+        groups.set(refKey, group);
+    });
+    for (const group of groups.values()) {
+        const sortedDecisions = group
+            .map(({ decision }) => decision)
+            .sort((left, right) => {
+            const leftRef = preparedEventImportDecisionExternalRef(left);
+            const rightRef = preparedEventImportDecisionExternalRef(right);
+            return compareIsoTimestampsAscending(leftRef?.version ?? "", rightRef?.version ?? "");
+        });
+        group.forEach(({ index }, groupIndex) => {
+            ordered[index] = sortedDecisions[groupIndex];
+        });
+    }
+    return ordered;
+}
+async function indexLatestEventsByExternalRef(vaultRoot, relativePaths, signal) {
+    const deviceOwnerRevisionsByRefKeyAndFingerprint = new Map();
     const latestByRefKey = new Map();
+    const latestById = new Map();
     const maxRevisionById = new Map();
+    const revisionsById = new Map();
     const entriesById = new Map();
     for (const relativePath of relativePaths) {
+        signal?.throwIfAborted();
         const resolved = resolveVaultPath(vaultRoot, relativePath);
         if (!(await pathExists(resolved.absolutePath))) {
             continue;
         }
-        for (const raw of await readJsonlRecords({ vaultRoot, relativePath })) {
-            const parsed = safeParseContract(eventRecordSchema, raw);
-            if (!parsed.success) {
-                continue;
-            }
-            const entry = { relativePath, record: parsed.data };
-            maxRevisionById.set(entry.record.id, Math.max(maxRevisionById.get(entry.record.id) ?? 0, eventSpineRevision(entry.record)));
-            const state = entriesById.get(entry.record.id);
-            const latestDeviceExternalRefEntryByRefKey = state?.latestDeviceExternalRefEntryByRefKey ?? new Map();
-            if (entry.record.source === "device" && entry.record.externalRef) {
-                const refKey = eventExternalRefKey(entry.record.externalRef);
-                const latestDeviceExternalRefEntry = latestDeviceExternalRefEntryByRefKey.get(refKey);
-                if (!latestDeviceExternalRefEntry || compareEventSpineEntries(latestDeviceExternalRefEntry, entry) < 0) {
-                    latestDeviceExternalRefEntryByRefKey.set(refKey, entry);
+        await visitJsonlRecordsInterruptible({
+            vaultRoot,
+            relativePath,
+            signal,
+            visit(raw) {
+                signal?.throwIfAborted();
+                const parsed = safeParseContract(eventRecordSchema, raw);
+                if (!parsed.success) {
+                    return;
                 }
-            }
-            const latestExternalRefEntry = entry.record.externalRef &&
-                (!state?.latestExternalRefEntry || compareEventSpineEntries(state.latestExternalRefEntry, entry) < 0)
-                ? entry
-                : state?.latestExternalRefEntry ?? null;
-            entriesById.set(entry.record.id, {
-                latestDeviceExternalRefEntryByRefKey,
-                latestEntry: !state || compareEventSpineEntries(state.latestEntry, entry) < 0
+                const entry = { relativePath, record: parsed.data };
+                maxRevisionById.set(entry.record.id, Math.max(maxRevisionById.get(entry.record.id) ?? 0, eventSpineRevision(entry.record)));
+                const revisions = revisionsById.get(entry.record.id) ?? new Set();
+                revisions.add(eventSpineRevision(entry.record));
+                revisionsById.set(entry.record.id, revisions);
+                const state = entriesById.get(entry.record.id);
+                const latestDeviceExternalRefEntryByRefKey = state?.latestDeviceExternalRefEntryByRefKey ?? new Map();
+                if (entry.record.source === "device" && entry.record.externalRef) {
+                    const refKey = eventExternalRefKey(entry.record.externalRef);
+                    const ownersByFingerprint = deviceOwnerRevisionsByRefKeyAndFingerprint.get(refKey)
+                        ?? new Map();
+                    const fingerprint = deviceEventContentFingerprint(entry.record);
+                    const revisionsByOwnerId = ownersByFingerprint.get(fingerprint)
+                        ?? new Map();
+                    const ownerRevisions = revisionsByOwnerId.get(entry.record.id) ?? new Set();
+                    ownerRevisions.add(eventSpineRevision(entry.record));
+                    revisionsByOwnerId.set(entry.record.id, ownerRevisions);
+                    ownersByFingerprint.set(fingerprint, revisionsByOwnerId);
+                    deviceOwnerRevisionsByRefKeyAndFingerprint.set(refKey, ownersByFingerprint);
+                    const latestDeviceExternalRefEntry = latestDeviceExternalRefEntryByRefKey.get(refKey);
+                    if (!latestDeviceExternalRefEntry || compareEventSpineEntries(latestDeviceExternalRefEntry, entry) < 0) {
+                        latestDeviceExternalRefEntryByRefKey.set(refKey, entry);
+                    }
+                }
+                const latestExternalRefEntry = entry.record.externalRef &&
+                    (!state?.latestExternalRefEntry || compareEventSpineEntries(state.latestExternalRefEntry, entry) < 0)
                     ? entry
-                    : state.latestEntry,
-                latestExternalRefEntry,
-            });
-        }
+                    : state?.latestExternalRefEntry ?? null;
+                entriesById.set(entry.record.id, {
+                    latestDeviceExternalRefEntryByRefKey,
+                    latestEntry: !state || compareEventSpineEntries(state.latestEntry, entry) < 0
+                        ? entry
+                        : state.latestEntry,
+                    latestExternalRefEntry,
+                });
+            },
+        });
     }
     const groupedByRefKey = new Map();
     for (const state of entriesById.values()) {
+        signal?.throwIfAborted();
         // Collapse each event id globally before indexing external refs. An event
         // whose latest revision moved to a corrected ref must not remain
         // discoverable through an older historical ref.
         const latestForId = state.latestEntry;
+        latestById.set(latestForId.record.id, latestForId.record);
         const externalRefEntry = latestForId.record.externalRef
             ? latestForId
             : state.latestExternalRefEntry;
@@ -814,6 +969,7 @@ async function indexLatestEventsByExternalRef(vaultRoot, relativePaths) {
         groupedByRefKey.set(refKey, refGroup);
     }
     for (const [refKey, group] of groupedByRefKey) {
+        signal?.throwIfAborted();
         // Preserve the prior duplicate-ref behavior: if multiple live ids still
         // claim one external ref, reconcile against the latest comparable spine.
         const latest = selectLatestIndexedEventExternalRefMatch(group);
@@ -821,7 +977,13 @@ async function indexLatestEventsByExternalRef(vaultRoot, relativePaths) {
             latestByRefKey.set(refKey, latest);
         }
     }
-    return { latestByRefKey, maxRevisionById };
+    return {
+        deviceOwnerRevisionsByRefKeyAndFingerprint,
+        latestByRefKey,
+        latestById,
+        maxRevisionById,
+        revisionsById,
+    };
 }
 function isSameObservationFacet(existing, incoming) {
     return existing.kind === "observation" &&
@@ -836,6 +998,14 @@ function isSameObservationValue(existing, incoming) {
         incoming.kind === "observation" &&
         existing.value === incoming.value;
 }
+const JUNCTION_SLEEP_STAGE_METRIC_FACETS = new Set([
+    "sleep-awake-minutes",
+    "sleep-light-minutes",
+    "sleep-deep-minutes",
+    "sleep-rem-minutes",
+]);
+const JUNCTION_SLEEP_STAGE_SUMMARY_NORMALIZER_VERSION = "junction-sleep-stage-summary.v1";
+const JUNCTION_SLEEP_STAGE_CYCLE_FALLBACK_NORMALIZER_VERSION = "junction-sleep-stage-cycle-fallback.v1";
 function deviceDataOriginSourceMatches(existing, incoming) {
     if (!existing || !incoming) {
         return false;
@@ -869,6 +1039,78 @@ function isWhoopBodyMeasurementDateOnlyLegacyRef(legacyExternalRef, incoming) {
         incoming.externalRef.resourceType === "body-measurement" &&
         isScopedDateLikeWhoopBodyMeasurementResourceId(incoming.externalRef.resourceId);
 }
+function isJunctionSleepStageExternalRefInput(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const externalRef = value;
+    return externalRef.system === "junction" &&
+        typeof externalRef.resourceType === "string" &&
+        /^junction-[a-z0-9-]+-sleep$/u.test(externalRef.resourceType) &&
+        typeof externalRef.facet === "string" &&
+        JUNCTION_SLEEP_STAGE_METRIC_FACETS.has(externalRef.facet);
+}
+function isJunctionSleepStageObservation(record) {
+    return record.kind === "observation" &&
+        isJunctionSleepStageExternalRefInput(record.externalRef);
+}
+function isJunctionSleepStageSummaryObservation(record) {
+    return isJunctionSleepStageObservation(record) &&
+        record.dataOrigin?.normalizerVersion === JUNCTION_SLEEP_STAGE_SUMMARY_NORMALIZER_VERSION;
+}
+function isJunctionSleepStageCycleFallbackObservation(record) {
+    return isJunctionSleepStageObservation(record) &&
+        record.dataOrigin?.normalizerVersion === JUNCTION_SLEEP_STAGE_CYCLE_FALLBACK_NORMALIZER_VERSION;
+}
+function isJunctionSleepStageSummaryLegacyRef(legacyExternalRef, incoming) {
+    return isJunctionSleepStageSummaryObservation(incoming) &&
+        legacyExternalRef.system === "junction" &&
+        incoming.externalRef?.system === "junction" &&
+        legacyExternalRef.resourceType === incoming.externalRef.resourceType &&
+        /^junction-[a-z0-9-]+-sleep$/u.test(legacyExternalRef.resourceType) &&
+        legacyExternalRef.facet !== undefined &&
+        legacyExternalRef.facet === incoming.externalRef.facet &&
+        JUNCTION_SLEEP_STAGE_METRIC_FACETS.has(legacyExternalRef.facet);
+}
+function hasStableJunctionSleepStageSummaryLegacyProof(existing, incoming) {
+    if (!isSameObservationFacet(existing.record, incoming)) {
+        return false;
+    }
+    const existingDataOrigin = existing.indexedRecord.dataOrigin ?? existing.record.dataOrigin;
+    return existing.record.occurredAt === incoming.occurredAt &&
+        deviceDataOriginSourceMatches(existingDataOrigin, incoming.dataOrigin);
+}
+function shouldKeepExistingJunctionSleepStageSummaryObservation(existing, incoming) {
+    if (!isSameObservationFacet(existing, incoming)) {
+        return false;
+    }
+    return isJunctionSleepStageSummaryObservation(existing) &&
+        isJunctionSleepStageCycleFallbackObservation(incoming);
+}
+const JUNCTION_COMPANION_HEALTH_METADATA_SOURCE_TYPE = "companion-whoop-metadata-unverified";
+function parseJunctionCompanionSyncVersion(version) {
+    if (!version || !/^(?:0|[1-9]\d*)$/u.test(version)) {
+        return undefined;
+    }
+    const parsed = Number(version);
+    return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+function shouldKeepExistingJunctionCompanionHealthMetadata(existing, incoming) {
+    if (existing.kind !== "observation"
+        || incoming.kind !== "observation"
+        || existing.externalRef?.system !== "junction"
+        || incoming.externalRef?.system !== "junction"
+        || existing.dataOrigin?.sourceType !== JUNCTION_COMPANION_HEALTH_METADATA_SOURCE_TYPE
+        || incoming.dataOrigin?.sourceType !== JUNCTION_COMPANION_HEALTH_METADATA_SOURCE_TYPE) {
+        return false;
+    }
+    const existingVersion = parseJunctionCompanionSyncVersion(existing.externalRef.version);
+    if (existingVersion === undefined) {
+        return false;
+    }
+    const incomingVersion = parseJunctionCompanionSyncVersion(incoming.externalRef.version);
+    return incomingVersion === undefined || incomingVersion <= existingVersion;
+}
 function hasStableLegacyOccurrenceProof(existing, incoming, legacyExternalRef) {
     if (isWhoopBodyMeasurementDateOnlyLegacyRef(legacyExternalRef, incoming)) {
         return existing.record.recordedAt === incoming.recordedAt &&
@@ -900,6 +1142,9 @@ function isCompatibleLegacyExternalRefMatch(existing, incoming, legacyExternalRe
         return isSameObservationFacet(existing.record, incoming) &&
             hasStableLegacyOccurrenceProof(existing, incoming, legacyExternalRef);
     }
+    if (isJunctionSleepStageSummaryLegacyRef(legacyExternalRef, incoming)) {
+        return hasStableJunctionSleepStageSummaryLegacyProof(existing, incoming);
+    }
     return existing.record.dayKey === incoming.dayKey ||
         (isSameObservationFacet(existing.record, incoming) &&
             hasStableLegacyOccurrenceProof(existing, incoming, legacyExternalRef));
@@ -908,6 +1153,30 @@ function selectLatestIndexedEventExternalRefMatch(entries) {
     if (entries.length === 0) {
         return null;
     }
+    const hasOrderedImportSourceVersions = entries.every((entry) => entry.record.source === "import"
+        && entry.indexedExternalRef.version !== undefined
+        && isWritableIsoDateTime(entry.indexedExternalRef.version));
+    if (hasOrderedImportSourceVersions) {
+        return entries.reduce((latest, candidate) => {
+            const sourceVersionComparison = compareIncomingExternalRefVersion(latest.indexedExternalRef, candidate.indexedExternalRef);
+            if (sourceVersionComparison !== null && sourceVersionComparison !== 0) {
+                return sourceVersionComparison > 0 ? candidate : latest;
+            }
+            const latestDeleted = isDeletedEventSpineRecord(latest.record);
+            const candidateDeleted = isDeletedEventSpineRecord(candidate.record);
+            if (latestDeleted !== candidateDeleted) {
+                return candidateDeleted ? latest : candidate;
+            }
+            const recordedAtComparison = compareIsoTimestampsAscending(candidate.record.recordedAt, latest.record.recordedAt);
+            if (recordedAtComparison !== 0) {
+                return recordedAtComparison > 0 ? candidate : latest;
+            }
+            if (candidate.relativePath !== latest.relativePath) {
+                return candidate.relativePath > latest.relativePath ? candidate : latest;
+            }
+            return candidate.record.id > latest.record.id ? candidate : latest;
+        });
+    }
     const liveEntries = entries.filter((entry) => !isDeletedEventSpineRecord(entry.record));
     const candidates = liveEntries.length > 0 ? liveEntries : entries;
     return candidates.reduce((latest, candidate) => compareEventSpineEntries(latest, candidate) >= 0 ? latest : candidate);
@@ -959,87 +1228,282 @@ function buildLegacyExternalRefReservations(entries, index) {
     }
     return reservations;
 }
+async function buildDeviceEventIdentityContext(vaultRoot, entries) {
+    if (entries.length === 0) {
+        return {
+            index: {
+                deviceOwnerRevisionsByRefKeyAndFingerprint: new Map(),
+                latestByRefKey: new Map(),
+                latestById: new Map(),
+                maxRevisionById: new Map(),
+                revisionsById: new Map(),
+            },
+            legacyReservations: new Map(),
+        };
+    }
+    const shardPaths = await walkVaultFiles(vaultRoot, VAULT_LAYOUT.eventLedgerDirectory, {
+        extension: ".jsonl",
+    });
+    const index = await indexLatestEventsByExternalRef(vaultRoot, shardPaths);
+    return {
+        index,
+        legacyReservations: buildLegacyExternalRefReservations(entries, index),
+    };
+}
+function cloneDeviceEventIdentityContext(context) {
+    return {
+        index: {
+            deviceOwnerRevisionsByRefKeyAndFingerprint: context.index.deviceOwnerRevisionsByRefKeyAndFingerprint,
+            latestByRefKey: new Map(context.index.latestByRefKey),
+            latestById: new Map(context.index.latestById),
+            maxRevisionById: new Map(context.index.maxRevisionById),
+            revisionsById: new Map(context.index.revisionsById),
+        },
+        legacyReservations: new Map(context.legacyReservations),
+    };
+}
+function buildEmptyDeviceEventIdentityContext(entries) {
+    const index = {
+        deviceOwnerRevisionsByRefKeyAndFingerprint: new Map(),
+        latestByRefKey: new Map(),
+        latestById: new Map(),
+        maxRevisionById: new Map(),
+        revisionsById: new Map(),
+    };
+    return {
+        index,
+        legacyReservations: buildLegacyExternalRefReservations(entries, index),
+    };
+}
+function eventSpineRevisionsAreComplete(index, eventId) {
+    const maxRevision = index.maxRevisionById.get(eventId) ?? 0;
+    const revisions = index.revisionsById.get(eventId);
+    return Number.isSafeInteger(maxRevision)
+        && maxRevision > 0
+        && revisions !== undefined
+        && revisions.size === maxRevision;
+}
+function resolveDeviceEventIdentity(entry, context, options = {}) {
+    const externalRef = entry.record.externalRef;
+    if (!externalRef) {
+        return null;
+    }
+    const { index, legacyReservations } = context;
+    const refKey = eventExternalRefKey(externalRef);
+    const reservedForLegacyClaim = legacyReservations.get(refKey);
+    const primaryMatch = reservedForLegacyClaim && reservedForLegacyClaim.entry !== entry
+        ? undefined
+        : index.latestByRefKey.get(refKey);
+    const legacyMatchedEntries = entry.legacyExternalRefs
+        .map((legacyExternalRef) => ({
+        legacyExternalRef,
+        refKey: eventExternalRefKey(legacyExternalRef),
+    }))
+        .filter((match) => match.refKey !== refKey)
+        .map(({ legacyExternalRef, refKey: legacyRefKey }) => {
+        const reservation = legacyReservations.get(legacyRefKey);
+        return {
+            legacyExternalRef,
+            refKey: legacyRefKey,
+            indexedMatch: reservation?.entry === entry
+                ? reservation.indexedMatch
+                : index.latestByRefKey.get(legacyRefKey),
+        };
+    })
+        .filter((match) => {
+        if (!match.indexedMatch) {
+            return false;
+        }
+        const reservation = legacyReservations.get(match.refKey);
+        return (!reservation || reservation.entry === entry)
+            && isCompatibleLegacyExternalRefMatch(match.indexedMatch, entry.record, match.legacyExternalRef);
+    });
+    const matchedEntries = [
+        ...(primaryMatch ? [{ refKey, indexedMatch: primaryMatch }] : []),
+        ...legacyMatchedEntries,
+    ];
+    const selectedPrimaryMatch = matchedEntries.find((match) => match.refKey === refKey);
+    const latest = selectedPrimaryMatch?.indexedMatch.record ?? matchedEntries[0]?.indexedMatch.record;
+    let associationSafe = true;
+    for (const match of matchedEntries) {
+        if (match.indexedMatch.record.kind !== entry.record.kind) {
+            associationSafe = false;
+            if (options.strict) {
+                throw new VaultError("EVENT_KIND_MISMATCH", `Event externalRef "${externalRef.system}/${externalRef.resourceType}/${externalRef.resourceId}` +
+                    `${externalRef.facet ? `#${externalRef.facet}` : ""}" already belongs to kind ` +
+                    `"${match.indexedMatch.record.kind}" and cannot be rewritten as "${entry.record.kind}"; nothing was imported.`);
+            }
+        }
+    }
+    const matchedIds = new Set(matchedEntries.map((match) => match.indexedMatch.record.id));
+    if (matchedIds.size > 1) {
+        associationSafe = false;
+        if (options.strict) {
+            throw new VaultError("EVENT_EXTERNAL_REF_ALIAS_CONFLICT", `Event externalRef "${externalRef.system}/${externalRef.resourceType}/${externalRef.resourceId}` +
+                `${externalRef.facet ? `#${externalRef.facet}` : ""}" matched multiple live event IDs; ` +
+                "ambiguous legacy cleanup must be repaired explicitly.");
+        }
+    }
+    return { associationSafe, latest, matchedEntries, refKey };
+}
+function mapCurrentDeviceEventOwners(entries, context) {
+    const associationSafePreparedIds = new Set();
+    const canonicalIdByPreparedId = new Map();
+    const currentRecordByPreparedId = new Map();
+    const historicalContentOwnerRevisionsByPreparedId = new Map();
+    const historicallyDeliveredPreparedIds = new Set();
+    const incomingNewerPreparedIds = new Set();
+    const physicallyExistingPreparedIds = new Set();
+    let allExist = true;
+    for (const entry of entries) {
+        if (context.index.latestById.has(entry.record.id)) {
+            physicallyExistingPreparedIds.add(entry.record.id);
+        }
+        const incomingContentFingerprint = deviceEventContentFingerprint(entry.record);
+        const historicalContentOwnerRevisions = new Map();
+        for (const externalRef of [entry.record.externalRef, ...entry.legacyExternalRefs]) {
+            if (!externalRef) {
+                continue;
+            }
+            const refKey = eventExternalRefKey(externalRef);
+            const ownersByFingerprint = context.index.deviceOwnerRevisionsByRefKeyAndFingerprint.get(refKey);
+            for (const [ownerId, revisions] of ownersByFingerprint?.get(incomingContentFingerprint) ?? []) {
+                const ownerRevisions = historicalContentOwnerRevisions.get(ownerId) ?? new Set();
+                for (const revision of revisions) {
+                    ownerRevisions.add(revision);
+                }
+                historicalContentOwnerRevisions.set(ownerId, ownerRevisions);
+            }
+        }
+        if (historicalContentOwnerRevisions.size > 0) {
+            historicalContentOwnerRevisionsByPreparedId.set(entry.record.id, new Map(historicalContentOwnerRevisions));
+        }
+        const resolved = resolveDeviceEventIdentity(entry, context);
+        if (!resolved) {
+            const current = context.index.latestById.get(entry.record.id);
+            canonicalIdByPreparedId.set(entry.record.id, entry.record.id);
+            allExist = current !== undefined && allExist;
+            if (!current) {
+                associationSafePreparedIds.add(entry.record.id);
+            }
+            else {
+                currentRecordByPreparedId.set(entry.record.id, current);
+                if (!isDeletedEventSpineRecord(current)
+                    && deviceEventContentKey(current) === deviceEventContentKey(entry.record)) {
+                    associationSafePreparedIds.add(entry.record.id);
+                }
+            }
+            continue;
+        }
+        let current = resolved.latest;
+        if (!current) {
+            const historicalOwners = [...historicalContentOwnerRevisions.keys()]
+                .map((ownerId) => context.index.latestById.get(ownerId))
+                .filter((record) => record !== undefined);
+            if (historicalOwners.length === 1) {
+                [current] = historicalOwners;
+                historicallyDeliveredPreparedIds.add(entry.record.id);
+            }
+            else if (historicalOwners.length > 1) {
+                canonicalIdByPreparedId.set(entry.record.id, entry.record.id);
+                historicallyDeliveredPreparedIds.add(entry.record.id);
+                allExist = false;
+                continue;
+            }
+        }
+        canonicalIdByPreparedId.set(entry.record.id, current?.id ?? entry.record.id);
+        allExist = current !== undefined && allExist;
+        if (!current) {
+            if (resolved.associationSafe) {
+                associationSafePreparedIds.add(entry.record.id);
+            }
+            continue;
+        }
+        currentRecordByPreparedId.set(entry.record.id, current);
+        const incomingContentKey = deviceEventContentKey(entry.record);
+        const wasPreviouslyDelivered = historicalContentOwnerRevisions.size > 0;
+        const incomingExternalRef = entry.record.externalRef;
+        const sourceVersionComparisons = incomingExternalRef === undefined
+            ? []
+            : resolved.matchedEntries.map(({ indexedMatch }) => compareIncomingExternalRefVersion(indexedMatch.indexedExternalRef, incomingExternalRef)).filter((comparison) => comparison !== null);
+        const incomingHasEqualOrNewerComparableVersion = sourceVersionComparisons.some((comparison) => comparison >= 0);
+        if (sourceVersionComparisons.some((comparison) => comparison > 0)) {
+            incomingNewerPreparedIds.add(entry.record.id);
+        }
+        if (wasPreviouslyDelivered
+            && !incomingHasEqualOrNewerComparableVersion
+            && deviceEventContentKey(current) !== incomingContentKey) {
+            historicallyDeliveredPreparedIds.add(entry.record.id);
+        }
+        if (resolved.associationSafe
+            && !isDeletedEventSpineRecord(current)
+            && deviceEventContentKey(current) === deviceEventContentKey(entry.record)) {
+            associationSafePreparedIds.add(entry.record.id);
+        }
+    }
+    return {
+        allExist,
+        associationSafePreparedIds,
+        canonicalIdByPreparedId,
+        currentRecordByPreparedId,
+        historicalContentOwnerRevisionsByPreparedId,
+        historicallyDeliveredPreparedIds,
+        incomingNewerPreparedIds,
+        physicallyExistingPreparedIds,
+    };
+}
 // Device-sync ingestion invariant 4: merge is idempotent on the record's own
 // externalRef, so overlapping push/pull re-imports of the same provider record
 // must not mint new events. Re-imports with identical content (ignoring
 // per-import identity such as id, rawRefs, lifecycle, and recordedAt) are
-// skipped; changed content appends an event-spine revision onto the existing
-// event id instead of a new event.
-async function reconcileDeviceEventEntriesByExternalRef(vaultRoot, entries) {
+// skipped; changed content normally appends an event-spine revision onto the
+// existing event id instead of a new event. Callers may mark a capture's
+// externalRef immutable when changed content must be rejected instead.
+async function reconcileDeviceEventEntriesByExternalRef(vaultRoot, entries, existingContext, preferredCanonicalIdByPreparedId = new Map()) {
     assertCanonicalWriteLockScope(vaultRoot);
-    const shardPaths = await walkVaultFiles(vaultRoot, VAULT_LAYOUT.eventLedgerDirectory, {
-        extension: ".jsonl",
-    });
-    const index = await indexLatestEventsByExternalRef(vaultRoot, shardPaths);
+    const context = existingContext ?? await buildDeviceEventIdentityContext(vaultRoot, entries);
+    const { index } = context;
     const appendEntries = [];
+    const appendRecordIdByPreparedRecordId = new Map();
     const records = [];
     const forceAppendIds = new Set();
-    const legacyReservations = buildLegacyExternalRefReservations(entries, index);
+    const retainedPreparedIds = new Set();
     let skippedDuplicateCount = 0;
     let supersededCount = 0;
     for (const entry of entries) {
         const externalRef = entry.record.externalRef;
         if (!externalRef) {
-            appendEntries.push(entry);
-            records.push(entry.record);
-            continue;
-        }
-        const refKey = eventExternalRefKey(externalRef);
-        const reservedForLegacyClaim = legacyReservations.get(refKey);
-        const primaryMatch = reservedForLegacyClaim && reservedForLegacyClaim.entry !== entry
-            ? undefined
-            : index.latestByRefKey.get(refKey);
-        const legacyMatchedEntries = entry.legacyExternalRefs
-            .map((legacyExternalRef) => ({
-            legacyExternalRef,
-            refKey: eventExternalRefKey(legacyExternalRef),
-        }))
-            .filter((match) => match.refKey !== refKey)
-            .map(({ legacyExternalRef, refKey }) => {
-            const reservation = legacyReservations.get(refKey);
-            return {
-                legacyExternalRef,
-                refKey,
-                indexedMatch: reservation?.entry === entry
-                    ? reservation.indexedMatch
-                    : index.latestByRefKey.get(refKey),
-            };
-        })
-            .filter((match) => {
-            if (!match.indexedMatch) {
-                return false;
+            const current = index.latestById.get(entry.record.id);
+            if (current
+                && !isDeletedEventSpineRecord(current)
+                && deviceEventContentKey(current) === deviceEventContentKey(entry.record)) {
+                skippedDuplicateCount += 1;
+                retainedPreparedIds.add(entry.record.id);
+                records.push(current);
+                continue;
             }
-            const reservation = legacyReservations.get(match.refKey);
-            return (!reservation || reservation.entry === entry) &&
-                isCompatibleLegacyExternalRefMatch(match.indexedMatch, entry.record, match.legacyExternalRef);
-        });
-        const matchedEntries = [
-            ...(primaryMatch ? [{ refKey, indexedMatch: primaryMatch }] : []),
-            ...legacyMatchedEntries,
-        ];
-        const selectedPrimaryMatch = matchedEntries.find((match) => match.refKey === refKey);
-        const latest = selectedPrimaryMatch?.indexedMatch.record ?? matchedEntries[0]?.indexedMatch.record;
-        if (!latest) {
-            index.latestByRefKey.set(refKey, toIndexedExternalRefMatch(entry.record, externalRef));
             appendEntries.push(entry);
+            appendRecordIdByPreparedRecordId.set(entry.record.id, entry.record.id);
             records.push(entry.record);
             continue;
         }
-        for (const match of matchedEntries) {
-            // externalRef identity does not include kind. Event spines are kind-stable,
-            // so device reconciliation must reject under-faceted provider refs instead
-            // of rewriting an existing event id as a different event kind.
-            if (match.indexedMatch.record.kind !== entry.record.kind) {
-                throw new VaultError("EVENT_KIND_MISMATCH", `Event externalRef "${externalRef.system}/${externalRef.resourceType}/${externalRef.resourceId}` +
-                    `${externalRef.facet ? `#${externalRef.facet}` : ""}" already belongs to kind ` +
-                    `"${match.indexedMatch.record.kind}" and cannot be rewritten as "${entry.record.kind}"; nothing was imported.`);
-            }
+        const resolved = resolveDeviceEventIdentity(entry, context, { strict: true });
+        if (!resolved) {
+            throw new VaultError("EVENT_EXTERNAL_REF_ALIAS_CONFLICT", "Device event identity unexpectedly lost its externalRef during reconciliation.");
         }
-        const matchedIds = new Set(matchedEntries.map((match) => match.indexedMatch.record.id));
-        if (matchedIds.size > 1) {
-            throw new VaultError("EVENT_EXTERNAL_REF_ALIAS_CONFLICT", `Event externalRef "${externalRef.system}/${externalRef.resourceType}/${externalRef.resourceId}` +
-                `${externalRef.facet ? `#${externalRef.facet}` : ""}" matched multiple live event IDs; ` +
-                "ambiguous legacy cleanup must be repaired explicitly.");
+        const { matchedEntries, refKey } = resolved;
+        let latest = resolved.latest;
+        if (!latest) {
+            const canonicalRecordId = preferredCanonicalIdByPreparedId.get(entry.record.id)
+                ?? entry.record.id;
+            const canonicalRecord = canonicalRecordId === entry.record.id
+                ? entry.record
+                : { ...entry.record, id: canonicalRecordId };
+            index.latestByRefKey.set(refKey, toIndexedExternalRefMatch(canonicalRecord, externalRef));
+            appendEntries.push({ relativePath: entry.relativePath, record: canonicalRecord });
+            appendRecordIdByPreparedRecordId.set(entry.record.id, canonicalRecord.id);
+            records.push(canonicalRecord);
+            continue;
         }
         // externalRef identity does not include kind. Event spines are kind-stable,
         // so device reconciliation must reject under-faceted provider refs instead
@@ -1051,15 +1515,75 @@ async function reconcileDeviceEventEntriesByExternalRef(vaultRoot, entries) {
         }
         if (deviceEventContentKey(latest) === deviceEventContentKey(entry.record)) {
             skippedDuplicateCount += 1;
+            retainedPreparedIds.add(entry.record.id);
+            records.push(latest);
+            continue;
+        }
+        const indexedProviderMatch = matchedEntries.find((match) => match.indexedMatch.record.id === latest.id)?.indexedMatch ?? matchedEntries[0]?.indexedMatch;
+        if (indexedProviderMatch
+            && deviceEventContentKey(indexedProviderMatch.indexedRecord)
+                === deviceEventContentKey(entry.record)) {
+            skippedDuplicateCount += 1;
+            retainedPreparedIds.add(entry.record.id);
+            records.push(latest);
+            continue;
+        }
+        if (entry.externalRefUpdatePolicy === "immutable") {
+            // The admission digest owns this observation's immutable identity. Vault
+            // timezone metadata is mutable, so an at-least-once replay must preserve
+            // the first canonical placement rather than turning the retained payload
+            // into a permanent immutable-reference conflict. Compare with the stored
+            // provider delivery when available so later user-authored revisions stay
+            // intact while an exact provider replay remains a no-op.
+            if (isWhoopCompanionHrvRmssdTemporalReplay(indexedProviderMatch?.indexedRecord ?? latest, entry.record)) {
+                skippedDuplicateCount += 1;
+                records.push(latest);
+                continue;
+            }
+            throw new VaultError("EVENT_IMMUTABLE_EXTERNAL_REF_CONFLICT", "Immutable device event externalRef already exists with different content; nothing was imported.");
+        }
+        if (indexedProviderMatch
+            && indexedProviderMatch.indexedExternalRef.system === "whoop"
+            && externalRef.system === "whoop") {
+            const sourceVersionComparison = compareIncomingExternalRefVersion(indexedProviderMatch.indexedExternalRef, externalRef);
+            if (sourceVersionComparison !== null && sourceVersionComparison < 0) {
+                skippedDuplicateCount += 1;
+                if (eventSpineRevisionsAreComplete(index, latest.id)) {
+                    retainedPreparedIds.add(entry.record.id);
+                }
+                records.push(latest);
+                continue;
+            }
+            if (sourceVersionComparison === 0) {
+                throw new VaultError("EVENT_SOURCE_REVISION_CONFLICT", `Event externalRef "${externalRef.system}/${externalRef.resourceType}/${externalRef.resourceId}` +
+                    `${externalRef.facet ? `#${externalRef.facet}` : ""}" has conflicting content for source revision ` +
+                    `"${externalRef.version}"; nothing was imported.`);
+            }
+        }
+        // Companion HealthKit sync versions are nonnegative monotonic integers.
+        // Keep this comparison scoped to that closed source type: other providers
+        // use timestamp-shaped versions whose ordering semantics are not universal.
+        if (shouldKeepExistingJunctionCompanionHealthMetadata(latest, entry.record)) {
+            if (eventSpineRevisionsAreComplete(index, latest.id)) {
+                retainedPreparedIds.add(entry.record.id);
+            }
             records.push(latest);
             continue;
         }
         if (isDeletedEventSpineRecord(latest)) {
             index.latestByRefKey.set(refKey, toIndexedExternalRefMatch(entry.record, externalRef));
             appendEntries.push(entry);
+            appendRecordIdByPreparedRecordId.set(entry.record.id, entry.record.id);
             records.push(entry.record);
             continue;
         }
+        if (shouldKeepExistingJunctionSleepStageSummaryObservation(latest, entry.record)) {
+            if (eventSpineRevisionsAreComplete(index, latest.id)) {
+                retainedPreparedIds.add(entry.record.id);
+            }
+            records.push(latest);
+            continue;
+        }
         const historicalUserEditMatch = matchedEntries.find((match) => hasHistoricalExternalRefUserAuthoredChanges(match.indexedMatch));
         if (historicalUserEditMatch) {
             throw new VaultError("EVENT_EXTERNAL_REF_ALIAS_CONFLICT", `Event externalRef "${externalRef.system}/${externalRef.resourceType}/${externalRef.resourceId}` +
@@ -1084,13 +1608,16 @@ async function reconcileDeviceEventEntriesByExternalRef(vaultRoot, entries) {
         }
         index.maxRevisionById.set(latest.id, revision);
         appendEntries.push({ relativePath: entry.relativePath, record: superseding });
+        appendRecordIdByPreparedRecordId.set(entry.record.id, superseding.id);
         records.push(superseding);
         supersededCount += 1;
     }
     return {
         appendEntries,
+        appendRecordIdByPreparedRecordId,
         records,
         forceAppendIds,
+        retainedPreparedIds,
         skippedDuplicateCount,
         supersededCount,
     };
@@ -1101,51 +1628,163 @@ async function reconcileDeviceEventEntriesByExternalRef(vaultRoot, entries) {
 // minting a duplicate. This mirrors upsertEvent, which resolves an event id
 // across every shard and writes the new revision into the shard for the new
 // occurredAt, so an event spine may span shards and readers collapse it by id.
-async function reconcileEventImportEntriesByExternalRef(vaultRoot, entries) {
+async function reconcileEventImportDecisionsByExternalRef(vaultRoot, decisions, signal) {
     assertCanonicalWriteLockScope(vaultRoot);
-    const shardPaths = await walkVaultFiles(vaultRoot, VAULT_LAYOUT.eventLedgerDirectory, {
+    const { relativePaths: shardPaths } = await walkVaultFilesInterruptible(vaultRoot, VAULT_LAYOUT.eventLedgerDirectory, {
         extension: ".jsonl",
+        signal,
     });
-    const index = await indexLatestEventsByExternalRef(vaultRoot, shardPaths);
+    const index = await indexLatestEventsByExternalRef(vaultRoot, shardPaths, signal);
     const appendEntries = [];
-    const records = [];
     const forceAppendIds = new Set();
-    let skippedDuplicateCount = 0;
+    const eventIds = [];
+    const retractedEventIds = [];
+    const eventShardPaths = new Set();
+    const orderedDecisions = orderEventImportDecisionsBySourceVersion(decisions);
+    let createdCount = 0;
+    let skippedExistingCount = 0;
     let supersededCount = 0;
-    for (const entry of entries) {
+    let retractedCount = 0;
+    for (const decision of orderedDecisions) {
+        signal?.throwIfAborted();
+        if (decision.action === "retract") {
+            const refKey = eventExternalRefKey(decision.externalRef);
+            const latestMatch = index.latestByRefKey.get(refKey);
+            const latest = latestMatch?.record;
+            if (!latestMatch || !latest) {
+                const marker = {
+                    ...decision.markerEntry.record,
+                    lifecycle: buildEventSpineLifecycle(1, "deleted"),
+                };
+                eventShardPaths.add(decision.markerEntry.relativePath);
+                index.latestByRefKey.set(refKey, toIndexedExternalRefMatch(marker, decision.externalRef, decision.markerEntry.relativePath));
+                index.maxRevisionById.set(marker.id, 1);
+                appendEntries.push({ relativePath: decision.markerEntry.relativePath, record: marker });
+                retractedEventIds.push(marker.id);
+                retractedCount += 1;
+                continue;
+            }
+            const latestPath = latestMatch?.relativePath || toEventLedgerFile(latest.occurredAt);
+            eventShardPaths.add(latestPath);
+            const sourceVersionComparison = compareIncomingExternalRefVersion(latestMatch.indexedExternalRef, decision.externalRef);
+            if (sourceVersionComparison === null) {
+                throw new VaultError("EVENT_SOURCE_REVISION_UNORDERED", `Event externalRef "${decision.externalRef.system}/${decision.externalRef.resourceType}/` +
+                    `${decision.externalRef.resourceId}${decision.externalRef.facet ? `#${decision.externalRef.facet}` : ""}" ` +
+                    "cannot be retracted without comparable source revisions; nothing was imported.");
+            }
+            if (sourceVersionComparison < 0 || (sourceVersionComparison === 0 && isDeletedEventSpineRecord(latest))) {
+                skippedExistingCount += 1;
+                continue;
+            }
+            if (sourceVersionComparison === 0) {
+                throw new VaultError("EVENT_SOURCE_REVISION_CONFLICT", `Event externalRef "${decision.externalRef.system}/${decision.externalRef.resourceType}/` +
+                    `${decision.externalRef.resourceId}${decision.externalRef.facet ? `#${decision.externalRef.facet}` : ""}" ` +
+                    `has conflicting content for source revision "${decision.externalRef.version}"; nothing was imported.`);
+            }
+            const revision = Math.max(eventSpineRevision(latest), index.maxRevisionById.get(latest.id) ?? 0) + 1;
+            const tombstone = {
+                ...latest,
+                recordedAt: decision.markerEntry.record.recordedAt,
+                externalRef: decision.externalRef,
+                ...(decision.evidence ? { evidence: decision.evidence } : {}),
+                ...(latest.kind === "note" && latest.noteType === EVENT_IMPORT_RETRACTION_MARKER_NOTE_TYPE
+                    ? { note: decision.reason }
+                    : {}),
+                lifecycle: buildEventSpineLifecycle(revision, "deleted"),
+            };
+            forceAppendIds.add(latest.id);
+            index.latestByRefKey.set(refKey, toIndexedExternalRefMatch(tombstone, decision.externalRef, latestPath));
+            index.maxRevisionById.set(latest.id, revision);
+            appendEntries.push({ relativePath: latestPath, record: tombstone });
+            retractedEventIds.push(latest.id);
+            retractedCount += 1;
+            continue;
+        }
+        const entry = decision.entry;
+        eventShardPaths.add(entry.relativePath);
         const externalRef = entry.record.externalRef;
         if (!externalRef) {
             appendEntries.push(entry);
-            records.push(entry.record);
+            eventIds.push(entry.record.id);
+            createdCount += 1;
             continue;
         }
         const refKey = eventExternalRefKey(externalRef);
-        const latest = index.latestByRefKey.get(refKey)?.record;
+        const latestMatch = index.latestByRefKey.get(refKey);
+        const latest = latestMatch?.record;
         if (!latest) {
-            index.latestByRefKey.set(refKey, toIndexedExternalRefMatch(entry.record, externalRef));
+            index.latestByRefKey.set(refKey, toIndexedExternalRefMatch(entry.record, externalRef, entry.relativePath));
             appendEntries.push(entry);
-            records.push(entry.record);
+            eventIds.push(entry.record.id);
+            createdCount += 1;
             continue;
         }
-        // externalRef identity does not include kind, so an under-faceted or
-        // malformed row could otherwise rewrite an existing event into a
-        // different kind. Event spines are kind-stable (upsertEvent enforces the
-        // same invariant per id), so reject the whole batch before anything is
-        // staged instead of superseding across kinds.
-        if (latest.kind !== entry.record.kind) {
+        const sourceVersionComparison = compareIncomingExternalRefVersion(latestMatch.indexedExternalRef, externalRef);
+        if (sourceVersionComparison !== null) {
+            if (sourceVersionComparison < 0) {
+                skippedExistingCount += 1;
+                continue;
+            }
+            if (sourceVersionComparison === 0) {
+                const existingContentKey = decision.allowsKindReplacement
+                    ? eventImportSourceSemanticContentKey(latest)
+                    : eventImportVersionedReplayContentKey(latest);
+                const incomingContentKey = decision.allowsKindReplacement
+                    ? eventImportSourceSemanticContentKey(entry.record)
+                    : eventImportVersionedReplayContentKey(entry.record);
+                if (existingContentKey === incomingContentKey) {
+                    skippedExistingCount += 1;
+                    continue;
+                }
+                throw new VaultError("EVENT_SOURCE_REVISION_CONFLICT", `Event externalRef "${externalRef.system}/${externalRef.resourceType}/${externalRef.resourceId}` +
+                    `${externalRef.facet ? `#${externalRef.facet}` : ""}" has conflicting content for source revision ` +
+                    `"${externalRef.version}"; nothing was imported.`);
+            }
+        }
+        else {
+            // Preserve the legacy public-import contract for unversioned or
+            // non-temporal sources: provenance changes remain content changes and a
+            // kind mismatch remains invalid.
+            if (latest.kind !== entry.record.kind) {
+                throw new VaultError("EVENT_KIND_MISMATCH", `Event externalRef "${externalRef.system}/${externalRef.resourceType}/${externalRef.resourceId}` +
+                    `${externalRef.facet ? `#${externalRef.facet}` : ""}" already belongs to kind ` +
+                    `"${latest.kind}" and cannot be rewritten as "${entry.record.kind}"; nothing was imported.`);
+            }
+            if (eventImportContentKey(latest) === eventImportContentKey(entry.record)) {
+                skippedExistingCount += 1;
+                continue;
+            }
+        }
+        if (latest.kind !== entry.record.kind && !decision.allowsKindReplacement) {
             throw new VaultError("EVENT_KIND_MISMATCH", `Event externalRef "${externalRef.system}/${externalRef.resourceType}/${externalRef.resourceId}` +
                 `${externalRef.facet ? `#${externalRef.facet}` : ""}" already belongs to kind ` +
                 `"${latest.kind}" and cannot be rewritten as "${entry.record.kind}"; nothing was imported.`);
         }
-        if (eventImportContentKey(latest) === eventImportContentKey(entry.record)) {
-            skippedDuplicateCount += 1;
-            records.push(latest);
-            continue;
-        }
         if (isDeletedEventSpineRecord(latest)) {
-            index.latestByRefKey.set(refKey, toIndexedExternalRefMatch(entry.record, externalRef));
+            index.latestByRefKey.set(refKey, toIndexedExternalRefMatch(entry.record, externalRef, entry.relativePath));
             appendEntries.push(entry);
-            records.push(entry.record);
+            eventIds.push(entry.record.id);
+            createdCount += 1;
+            continue;
+        }
+        if (latest.kind !== entry.record.kind) {
+            const latestPath = latestMatch?.relativePath || toEventLedgerFile(latest.occurredAt);
+            const revision = Math.max(eventSpineRevision(latest), index.maxRevisionById.get(latest.id) ?? 0) + 1;
+            const tombstone = {
+                ...latest,
+                recordedAt: entry.record.recordedAt,
+                externalRef,
+                ...(entry.record.evidence ? { evidence: entry.record.evidence } : {}),
+                lifecycle: buildEventSpineLifecycle(revision, "deleted"),
+            };
+            forceAppendIds.add(latest.id);
+            index.maxRevisionById.set(latest.id, revision);
+            index.latestByRefKey.set(refKey, toIndexedExternalRefMatch(entry.record, externalRef, entry.relativePath));
+            appendEntries.push({ relativePath: latestPath, record: tombstone }, entry);
+            eventShardPaths.add(latestPath);
+            eventIds.push(entry.record.id);
+            createdCount += 1;
+            supersededCount += 1;
             continue;
         }
         const revision = Math.max(eventSpineRevision(latest), index.maxRevisionById.get(latest.id) ?? 0) + 1;
@@ -1155,18 +1794,22 @@ async function reconcileEventImportEntriesByExternalRef(vaultRoot, entries) {
             lifecycle: buildEventSpineLifecycle(revision),
         };
         forceAppendIds.add(latest.id);
-        index.latestByRefKey.set(refKey, toIndexedExternalRefMatch(superseding, externalRef));
+        index.latestByRefKey.set(refKey, toIndexedExternalRefMatch(superseding, externalRef, entry.relativePath));
         index.maxRevisionById.set(latest.id, revision);
         appendEntries.push({ relativePath: entry.relativePath, record: superseding });
-        records.push(superseding);
+        eventIds.push(superseding.id);
         supersededCount += 1;
     }
     return {
         appendEntries,
-        records,
         forceAppendIds,
-        skippedDuplicateCount,
+        createdCount,
+        skippedExistingCount,
         supersededCount,
+        retractedCount,
+        eventIds,
+        retractedEventIds,
+        eventShardPaths: [...eventShardPaths].sort(),
     };
 }
 const AUDIT_TARGET_ID_LIMIT = 50;
@@ -1297,29 +1940,13 @@ export async function dedupeDeviceEventsByExternalRef({ vaultRoot, apply = false
     });
 }
 function mapPreparedDeviceEventsToCanonicalIds(preparedEntries, reconciledRecords) {
-    const canonicalIdByIdentity = new Map();
-    for (const record of reconciledRecords) {
-        const identity = record.externalRef
-            ? `external:${eventExternalRefKey(record.externalRef)}`
-            : `id:${record.id}`;
-        const existing = canonicalIdByIdentity.get(identity);
-        if (existing && existing !== record.id) {
-            throw new VaultError("INTEGRATION_INGEST_EVENT_MAPPING_AMBIGUOUS", `Device import produced multiple canonical event ids for identity "${identity}".`);
-        }
-        canonicalIdByIdentity.set(identity, record.id);
+    if (preparedEntries.length !== reconciledRecords.length) {
+        throw new VaultError("INTEGRATION_INGEST_EVENT_MAPPING_MISSING", "Device event reconciliation did not return one canonical result per prepared event.");
     }
-    const result = new Map();
-    for (const entry of preparedEntries) {
-        const identity = entry.record.externalRef
-            ? `external:${eventExternalRefKey(entry.record.externalRef)}`
-            : `id:${entry.record.id}`;
-        const canonicalId = canonicalIdByIdentity.get(identity);
-        if (!canonicalId) {
-            throw new VaultError("INTEGRATION_INGEST_EVENT_MAPPING_MISSING", `No reconciled canonical event matched prepared device event "${entry.record.id}".`);
-        }
-        result.set(entry.record.id, canonicalId);
-    }
-    return result;
+    return new Map(preparedEntries.map((entry, index) => [
+        entry.record.id,
+        reconciledRecords[index]?.id ?? entry.record.id,
+    ]));
 }
 function buildIntegrationEventOutputs(preparedEntries, canonicalIdByPreparedId, evidenceRolesByPreparedId) {
     const rolesByCanonicalId = new Map();
@@ -1394,17 +2021,27 @@ function prepareDeviceBatchPlan({ provider, accountId, importedAt = new Date(),
         ...normalizedInputs.events.map(({ seed }) => seed.occurredAt),
         ...normalizedInputs.samples.map(({ seed }) => seed.recordedAt),
     ], normalizedInputs.importedAt);
-    const legacyRawArtifactFingerprint = [
+    const rawArtifactFingerprint = [
         ...normalizedInputs.evidenceParts.map((part) => ({
             role: part.role,
             fileName: part.fileName,
             mediaType: part.mediaType ?? null,
             sha256: part.sha256,
+            ...(part.metadata === undefined ? {} : { metadata: part.metadata }),
         })),
         ...buildLegacyReceiptFingerprint(normalizedInputs.ingestReceipt, normalizedInputs.provider),
     ];
+    const legacyRawArtifactFingerprint = [
+        ...normalizedInputs.evidenceParts.map((part) => ({
+            role: part.role,
+            fileName: part.fileName,
+            mediaType: part.mediaType ?? null,
+            sha256: part.sha256,
+        })),
+        ...buildLegacyReceiptFingerprint(normalizedInputs.legacyIngestReceipt, normalizedInputs.provider),
+    ];
     const compactedIngestReceipt = compactIntegrationIngestReceipt(normalizedInputs.ingestReceipt);
-    const importId = deterministicContractId(ID_PREFIXES.transform, stableStringify({
+    const buildImportId = (fingerprint) => deterministicContractId(ID_PREFIXES.transform, stableStringify({
         provider: normalizedInputs.provider,
         accountId: normalizedInputs.accountId ?? null,
         source: normalizedInputs.source,
@@ -1413,19 +2050,22 @@ function prepareDeviceBatchPlan({ provider, accountId, importedAt = new Date(),
         receipt: compactedIngestReceipt ?? null,
         eventIds: normalizedInputs.events.map(({ recordId }) => recordId),
         sampleIds: normalizedInputs.samples.map(({ recordId }) => recordId),
-        evidenceParts: legacyRawArtifactFingerprint,
+        evidenceParts: fingerprint,
     }));
+    const importId = buildImportId(rawArtifactFingerprint);
+    const legacyImportId = buildImportId(legacyRawArtifactFingerprint);
     const preparedEvidenceParts = prepareDeviceEvidenceParts(normalizedInputs.evidenceParts);
     const eventPlan = prepareDeviceEventEntries(normalizedInputs.events, preparedEvidenceParts);
     const preparedSamples = prepareDeviceSampleEntries(normalizedInputs.samples);
     return {
         importId,
+        legacyImportId,
         provider: normalizedInputs.provider,
         accountId: normalizedInputs.accountId,
         importedAt: normalizedInputs.importedAt,
         source: normalizedInputs.source,
         provenance: normalizedInputs.provenance,
-        ingestReceipt: normalizedInputs.ingestReceipt,
+        ingestReceipt: compactedIngestReceipt,
         effectiveOccurredAt,
         preparedEvents: eventPlan.entries,
         evidenceRolesByPreparedRecordId: eventPlan.evidenceRolesByPreparedRecordId,
@@ -1830,6 +2470,294 @@ export async function importSamples({ vaultRoot, stream, unit, samples, sourcePa
         },
     });
 }
+function integrationEvidencePartIdentity(part) {
+    return stableStringify({
+        role: part.role,
+        fileName: part.fileName,
+        mediaType: part.mediaType,
+        sha256: part.sha256,
+        metadata: part.metadata ?? null,
+    });
+}
+function storedIntegrationIngestMatchesDeviceDeliveryBase(record, plan) {
+    return record.provider === plan.provider
+        && (record.accountId ?? null) === (plan.accountId ?? null)
+        && record.source === plan.source
+        && record.importedAt === plan.importedAt
+        && stableStringify(record.provenance ?? {}) === stableStringify(plan.provenance)
+        && stableStringify(record.receipt ?? null) === stableStringify(plan.ingestReceipt ?? null);
+}
+function storedIntegrationIngestIsDeviceDeliveryCandidate(record, plan) {
+    if (!storedIntegrationIngestMatchesDeviceDeliveryBase(record, plan)) {
+        return false;
+    }
+    const incomingPartIdentities = new Set(plan.preparedEvidenceParts.map(integrationEvidencePartIdentity));
+    return record.parts.every((part) => incomingPartIdentities.has(integrationEvidencePartIdentity(part)));
+}
+function storedIntegrationIngestMatchesDeviceDelivery(record, plan) {
+    return storedIntegrationIngestMatchesDeviceDeliveryBase(record, plan)
+        && stableStringify(record.parts.map(integrationEvidencePartIdentity))
+            === stableStringify(plan.preparedEvidenceParts.map(integrationEvidencePartIdentity));
+}
+function hasAuthorizedCurrentDeviceEventOutput(currentEventOwners, preparedId) {
+    return currentEventOwners.associationSafePreparedIds.has(preparedId)
+        && currentEventOwners.currentRecordByPreparedId.has(preparedId);
+}
+function buildPreparedDeviceEventOutputOwners(input) {
+    const baselineCanonicalIdByPreparedId = mapPreparedDeviceEventsToCanonicalIds(input.deviceBatchPlan.preparedEvents, input.baselineEventReconciliation.records);
+    const preparedIdsByBaselineCanonicalId = new Map();
+    for (const entry of input.deviceBatchPlan.preparedEvents) {
+        const baselineCanonicalId = baselineCanonicalIdByPreparedId.get(entry.record.id);
+        if (!baselineCanonicalId) {
+            throw new VaultError("INTEGRATION_INGEST_EVENT_MAPPING_MISSING", `No baseline canonical event id was recorded for prepared event "${entry.record.id}".`);
+        }
+        const preparedIds = preparedIdsByBaselineCanonicalId.get(baselineCanonicalId)
+            ?? new Set();
+        preparedIds.add(entry.record.id);
+        preparedIdsByBaselineCanonicalId.set(baselineCanonicalId, preparedIds);
+    }
+    const ownerByBaselineCanonicalId = new Map([...preparedIdsByBaselineCanonicalId].map(([canonicalId, preparedIds]) => [
+        canonicalId,
+        {
+            preparedIds: new Set(preparedIds),
+        },
+    ]));
+    const byPreparedId = new Map();
+    const byOutputId = new Map();
+    const claimOutputId = (outputId, owner) => {
+        const existingOwner = byOutputId.get(outputId);
+        if (existingOwner && existingOwner !== owner) {
+            throw new VaultError("INTEGRATION_INGEST_EVENT_MAPPING_AMBIGUOUS", `Stored canonical event "${outputId}" was claimed by multiple prepared device event spines.`);
+        }
+        byOutputId.set(outputId, owner);
+    };
+    for (const entry of input.deviceBatchPlan.preparedEvents) {
+        const baselineCanonicalId = baselineCanonicalIdByPreparedId.get(entry.record.id);
+        const owner = baselineCanonicalId
+            ? ownerByBaselineCanonicalId.get(baselineCanonicalId)
+            : undefined;
+        if (!owner) {
+            throw new VaultError("INTEGRATION_INGEST_EVENT_MAPPING_MISSING", `No event-spine owner was recorded for prepared event "${entry.record.id}".`);
+        }
+        byPreparedId.set(entry.record.id, owner);
+        claimOutputId(entry.record.id, owner);
+        const canonicalId = input.currentEventOwners.canonicalIdByPreparedId.get(entry.record.id);
+        if (canonicalId) {
+            claimOutputId(canonicalId, owner);
+        }
+        for (const ownerId of input.currentEventOwners.historicalContentOwnerRevisionsByPreparedId.get(entry.record.id)?.keys() ?? []) {
+            claimOutputId(ownerId, owner);
+        }
+    }
+    return { byOutputId, byPreparedId };
+}
+function storedEventOutputMatchesPreparedOwner(input) {
+    return input.preparedEventOutputOwners.byOutputId.get(input.output.id);
+}
+function preparedIdsRetainedByStoredEventOutput(input) {
+    const outputRoles = new Set(input.output.roles);
+    const preparedRolesById = [...input.owner.preparedIds]
+        .map((preparedId) => ({
+        preparedId,
+        roles: input.evidenceRolesByPreparedRecordId.get(preparedId),
+    }))
+        .filter((entry) => entry.roles !== undefined);
+    if (outputRoles.size === 0) {
+        const emptyRoleOwners = preparedRolesById.filter((entry) => entry.roles.length === 0);
+        return emptyRoleOwners.length === 1
+            ? [emptyRoleOwners[0].preparedId]
+            : undefined;
+    }
+    const preparedIdsByRole = new Map();
+    for (const { preparedId, roles } of preparedRolesById) {
+        if (roles.length === 0 || roles.some((role) => !outputRoles.has(role))) {
+            continue;
+        }
+        for (const role of roles) {
+            const preparedIds = preparedIdsByRole.get(role) ?? [];
+            preparedIds.push(preparedId);
+            preparedIdsByRole.set(role, preparedIds);
+        }
+    }
+    const retainedPreparedIds = new Set();
+    for (const role of outputRoles) {
+        const preparedIds = preparedIdsByRole.get(role);
+        if (preparedIds?.length !== 1) {
+            return undefined;
+        }
+        retainedPreparedIds.add(preparedIds[0]);
+    }
+    return [...retainedPreparedIds];
+}
+function storedEventOutputRolesBelongToPreparedOwner(input) {
+    if (input.output.roles.length === 0) {
+        return [...input.owner.preparedIds].some((preparedId) => (input.evidenceRolesByPreparedRecordId.get(preparedId) ?? []).length === 0);
+    }
+    return input.output.roles.every((role) => [...input.owner.preparedIds].some((preparedId) => input.evidenceRolesByPreparedRecordId.get(preparedId)?.includes(role)));
+}
+function storedOutputIdsByPreparedId(input) {
+    const ownedOutputIds = new Set();
+    const outputIdByPreparedId = new Map();
+    const unresolvedOutputIds = new Set();
+    for (const storedDelivery of input.storedDeliveries) {
+        for (const output of storedDelivery.outputs.events) {
+            const owner = input.preparedEventOutputOwners.byOutputId.get(output.id);
+            const retainedPreparedIds = owner
+                ? preparedIdsRetainedByStoredEventOutput({
+                    evidenceRolesByPreparedRecordId: input.evidenceRolesByPreparedRecordId,
+                    output,
+                    owner,
+                })
+                : undefined;
+            if (!owner) {
+                unresolvedOutputIds.add(output.id);
+                continue;
+            }
+            ownedOutputIds.add(output.id);
+            if (!retainedPreparedIds) {
+                unresolvedOutputIds.add(output.id);
+                continue;
+            }
+            for (const preparedId of retainedPreparedIds) {
+                const storedOutputId = outputIdByPreparedId.get(preparedId);
+                if (storedOutputId && storedOutputId !== output.id) {
+                    throw new VaultError("INTEGRATION_INGEST_EVENT_MAPPING_AMBIGUOUS", `Prepared device event "${preparedId}" maps to conflicting stored canonical events.`);
+                }
+                outputIdByPreparedId.set(preparedId, output.id);
+            }
+        }
+    }
+    return { ownedOutputIds, outputIdByPreparedId, unresolvedOutputIds };
+}
+function outputOwnerHasAuthorizedCurrentEvent(currentEventOwners, owner) {
+    return [...owner.preparedIds].some((preparedId) => hasAuthorizedCurrentDeviceEventOutput(currentEventOwners, preparedId));
+}
+function preparedDeviceEventRetainsCurrentOutput(input) {
+    const preparedId = input.entry.record.id;
+    if (hasAuthorizedCurrentDeviceEventOutput(input.currentEventOwners, preparedId)
+        || input.currentEventOwners.historicallyDeliveredPreparedIds.has(preparedId)) {
+        return true;
+    }
+    const current = input.currentEventOwners.currentRecordByPreparedId.get(preparedId);
+    return current !== undefined && (isDeletedEventSpineRecord(current)
+        || (eventSpineRevision(current) > eventSpineRevision(input.entry.record)
+            && userAuthoredEventStateKey(current) !== userAuthoredEventStateKey(input.entry.record)));
+}
+function storedIntegrationIngestRetainsCurrentOutputs(input) {
+    if (!input.allSamplesExist) {
+        return false;
+    }
+    const associationPreparedEvents = input.deviceBatchPlan.preparedEvents.filter((entry) => input.associationEvidenceRolesByPreparedRecordId.has(entry.record.id));
+    if (input.storedDelivery.outputs.events.length > 0
+        && associationPreparedEvents.some((entry) => !input.currentEventOwners.currentRecordByPreparedId.has(entry.record.id)
+            && !input.currentEventOwners.physicallyExistingPreparedIds.has(entry.record.id))) {
+        return false;
+    }
+    const currentlyOwnedAssociationEvents = associationPreparedEvents.filter((entry) => {
+        const owner = input.preparedEventOutputOwners.byPreparedId.get(entry.record.id);
+        return owner
+            ? outputOwnerHasAuthorizedCurrentEvent(input.currentEventOwners, owner)
+            : false;
+    });
+    const expectedEventIds = new Set(currentlyOwnedAssociationEvents
+        .map((entry) => input.currentEventOwners.canonicalIdByPreparedId.get(entry.record.id))
+        .filter((eventId) => eventId !== undefined));
+    const expectedSampleIds = input.sampleRecords.map((record) => record.id).sort();
+    const preparedEventById = new Map(input.deviceBatchPlan.preparedEvents.map((entry) => [entry.record.id, entry]));
+    for (const output of input.storedDelivery.outputs.events) {
+        const owner = storedEventOutputMatchesPreparedOwner({
+            output,
+            preparedEventOutputOwners: input.preparedEventOutputOwners,
+        });
+        if (!owner) {
+            return false;
+        }
+        const ownerEntries = [...owner.preparedIds]
+            .map((preparedId) => preparedEventById.get(preparedId))
+            .filter((entry) => entry !== undefined);
+        const outputRolesBelongToOwner = storedEventOutputRolesBelongToPreparedOwner({
+            evidenceRolesByPreparedRecordId: input.deviceBatchPlan.evidenceRolesByPreparedRecordId,
+            output,
+            owner,
+        });
+        const retainedOwnerEntries = ownerEntries.filter((entry) => input.baselineRetainedPreparedIds.has(entry.record.id));
+        const retainsOutput = outputRolesBelongToOwner
+            && retainedOwnerEntries.length > 0
+            && retainedOwnerEntries.every((entry) => input.replayRetainedPreparedIds.has(entry.record.id));
+        if (!retainsOutput) {
+            return false;
+        }
+    }
+    return input.storedDelivery.outputs.eventIdsComplete
+        && input.storedDelivery.outputs.sampleIdsComplete
+        && [...expectedEventIds].every((eventId) => input.storedDelivery.outputs.events.some((output) => output.id === eventId))
+        && stableStringify([...input.storedDelivery.outputs.sampleIds].sort()) === stableStringify(expectedSampleIds);
+}
+function buildStoredEventRepairIds(input) {
+    const result = new Map();
+    const storedOutputRoles = new Set(input.storedDeliveries.flatMap((storedDelivery) => storedDelivery.outputs.events.flatMap((output) => output.roles)));
+    for (const entry of input.deviceBatchPlan.preparedEvents) {
+        if ((input.currentEventOwners.currentRecordByPreparedId.has(entry.record.id)
+            && input.currentEventOwners.associationSafePreparedIds.has(entry.record.id))
+            || input.currentEventOwners.historicalContentOwnerRevisionsByPreparedId.has(entry.record.id)) {
+            continue;
+        }
+        const storedOutputId = input.storedOutputIdByPreparedId.get(entry.record.id);
+        if (storedOutputId) {
+            result.set(entry.record.id, storedOutputId);
+            continue;
+        }
+        const deliveryRoles = input.deviceBatchPlan.evidenceRolesByPreparedRecordId
+            .get(entry.record.id) ?? [];
+        const owner = input.preparedEventOutputOwners.byPreparedId.get(entry.record.id);
+        const ownerHasStoredOutput = owner !== undefined
+            && [...owner.preparedIds].some((preparedId) => input.storedOutputIdByPreparedId.has(preparedId));
+        if ((deliveryRoles.length === 0 && ownerHasStoredOutput)
+            || deliveryRoles.some((role) => storedOutputRoles.has(role))) {
+            throw new VaultError("INTEGRATION_INGEST_EVENT_MAPPING_AMBIGUOUS", "Missing device event member shares evidence with a different stored output.");
+        }
+    }
+    return result;
+}
+function buildStoredDeviceDeliveryNoopResult(input) {
+    const eventsById = new Map();
+    for (const output of input.storedDelivery.outputs.events) {
+        const owner = storedEventOutputMatchesPreparedOwner({
+            output,
+            preparedEventOutputOwners: input.preparedEventOutputOwners,
+        });
+        if (!owner) {
+            continue;
+        }
+        for (const preparedId of owner.preparedIds) {
+            if (!hasAuthorizedCurrentDeviceEventOutput(input.currentEventOwners, preparedId)) {
+                continue;
+            }
+            const current = input.currentEventOwners.currentRecordByPreparedId.get(preparedId);
+            if (current?.id === output.id) {
+                eventsById.set(current.id, current);
+                break;
+            }
+        }
+    }
+    return {
+        applied: false,
+        ingestId: null,
+        ingestShardPath: null,
+        provider: input.deviceBatchPlan.provider,
+        accountId: input.deviceBatchPlan.accountId,
+        importedAt: input.deviceBatchPlan.importedAt,
+        events: [...eventsById.values()],
+        samples: [...input.sampleRecords],
+        eventShardPaths: [...input.eventTargetShardPaths],
+        sampleShardPaths: [
+            ...new Set(input.deviceBatchPlan.preparedSamples.map((entry) => entry.relativePath)),
+        ].sort(),
+        evidencePartCount: input.deviceBatchPlan.preparedEvidenceParts.length,
+        persistedEvidencePartCount: 0,
+        auditPath: null,
+    };
+}
 export async function importDeviceBatch({ vaultRoot, provider, accountId, importedAt = new Date(), source = "device", events = [], samples = [], evidenceParts = [], ingestReceipt, provenance, }) {
     assertDeviceSampleRowLimit(Array.isArray(samples) ? samples.length : 0);
     const vault = await loadVault({ vaultRoot });
@@ -1845,29 +2773,494 @@ export async function importDeviceBatch({ vaultRoot, provider, accountId, import
         ingestReceipt,
         provenance,
     });
-    const eventReconciliation = await reconcileDeviceEventEntriesByExternalRef(vaultRoot, deviceBatchPlan.preparedEvents);
-    const eventAppendPlan = await buildJsonlAppendPlan(vaultRoot, eventReconciliation.appendEntries, {
-        dedupeWithinPlan: true,
-        forceAppendIds: eventReconciliation.forceAppendIds,
-    });
-    const sampleAppendPlan = await buildJsonlAppendPlan(vaultRoot, deviceBatchPlan.preparedSamples, {
-        dedupeWithinPlan: true,
-    });
-    const eventRecords = eventReconciliation.records;
     const eventTargetShardPaths = [
         ...new Set(deviceBatchPlan.preparedEvents.map((entry) => entry.relativePath)),
     ].sort();
     const sampleRecords = deviceBatchPlan.preparedSamples.map((entry) => entry.record);
-    const canonicalIdByPreparedId = mapPreparedDeviceEventsToCanonicalIds(deviceBatchPlan.preparedEvents, eventRecords);
-    const eventOutputs = buildIntegrationEventOutputs(deviceBatchPlan.preparedEvents, canonicalIdByPreparedId, deviceBatchPlan.evidenceRolesByPreparedRecordId);
+    const sampleAppendPlan = await buildJsonlAppendPlan(vaultRoot, deviceBatchPlan.preparedSamples, {
+        dedupeWithinPlan: true,
+    });
+    const eventIdentityContext = await buildDeviceEventIdentityContext(vaultRoot, deviceBatchPlan.preparedEvents);
+    const currentEventOwners = mapCurrentDeviceEventOwners(deviceBatchPlan.preparedEvents, eventIdentityContext);
+    const baselineEventReconciliation = await reconcileDeviceEventEntriesByExternalRef(vaultRoot, deviceBatchPlan.preparedEvents, buildEmptyDeviceEventIdentityContext(deviceBatchPlan.preparedEvents));
+    const baselineRetainedPreparedIds = new Set(baselineEventReconciliation.appendRecordIdByPreparedRecordId.keys());
+    const baselineRecordByPreparedId = new Map(deviceBatchPlan.preparedEvents.map((entry, index) => [
+        entry.record.id,
+        baselineEventReconciliation.records[index] ?? entry.record,
+    ]));
+    const preparedEventOutputOwners = buildPreparedDeviceEventOutputOwners({
+        baselineEventReconciliation,
+        currentEventOwners,
+        deviceBatchPlan,
+    });
+    const protectedPreparedEventIds = new Set(deviceBatchPlan.preparedEvents
+        .filter((entry) => baselineRetainedPreparedIds.has(entry.record.id)
+        && (currentEventOwners.historicallyDeliveredPreparedIds.has(entry.record.id)
+            || (entry.record.externalRef === undefined
+                && currentEventOwners.currentRecordByPreparedId.has(entry.record.id)
+                && !currentEventOwners.associationSafePreparedIds.has(entry.record.id)
+                && preparedDeviceEventRetainsCurrentOutput({ currentEventOwners, entry }))))
+        .map((entry) => entry.record.id));
+    const ordinaryReconciliationEntries = deviceBatchPlan.preparedEvents.filter((entry) => baselineRetainedPreparedIds.has(entry.record.id)
+        && !protectedPreparedEventIds.has(entry.record.id));
+    const currentEventReconciliation = await reconcileDeviceEventEntriesByExternalRef(vaultRoot, ordinaryReconciliationEntries, cloneDeviceEventIdentityContext(eventIdentityContext));
+    const replayRetainedPreparedIds = new Set([
+        ...protectedPreparedEventIds,
+        ...currentEventReconciliation.retainedPreparedIds,
+    ]);
+    const unresolvedBaselinePreparedIds = new Set([...baselineRetainedPreparedIds].filter((preparedId) => !replayRetainedPreparedIds.has(preparedId)));
+    const associationEvidenceRolesByPreparedRecordId = new Map(deviceBatchPlan.preparedEvents
+        .filter((entry) => baselineRetainedPreparedIds.has(entry.record.id) && (currentEventOwners.allExist
+        ? preparedDeviceEventRetainsCurrentOutput({ currentEventOwners, entry })
+        : currentEventOwners.associationSafePreparedIds.has(entry.record.id)))
+        .map((entry) => [
+        entry.record.id,
+        deviceBatchPlan.evidenceRolesByPreparedRecordId.get(entry.record.id) ?? [],
+    ]));
+    const associationPreparedEvents = deviceBatchPlan.preparedEvents.filter((entry) => associationEvidenceRolesByPreparedRecordId.has(entry.record.id));
+    const currentEventOutputs = buildIntegrationEventOutputs(associationPreparedEvents, currentEventOwners.canonicalIdByPreparedId, associationEvidenceRolesByPreparedRecordId);
+    const buildAssociationImportId = (eventOutputs) => deterministicContractId(ID_PREFIXES.transform, stableStringify({
+        associationRevisionOfDeviceImportId: deviceBatchPlan.importId,
+        eventOutputs,
+        sampleIds: sampleRecords.map((record) => record.id).sort(),
+    }));
+    const associationImportId = buildAssociationImportId(currentEventOutputs);
+    const candidateImportIds = new Set([
+        deviceBatchPlan.importId,
+        deviceBatchPlan.legacyImportId,
+        associationImportId,
+    ]);
+    let ingestIdInspection = await inspectIntegrationIngestIdsForImportedAt(vaultRoot, deviceBatchPlan.importedAt, candidateImportIds);
+    const orderedCandidateImportIds = [
+        deviceBatchPlan.importId,
+        associationImportId,
+        deviceBatchPlan.legacyImportId,
+    ];
+    const candidateStoredDeliveries = () => orderedCandidateImportIds
+        .map((id) => ingestIdInspection.invalidIds.has(id)
+        ? undefined
+        : ingestIdInspection.entriesById.get(id))
+        .filter((record) => record !== undefined && storedIntegrationIngestIsDeviceDeliveryCandidate(record, deviceBatchPlan));
+    const matchingStoredDeliveries = () => candidateStoredDeliveries().filter((record) => storedIntegrationIngestMatchesDeviceDelivery(record, deviceBatchPlan));
+    const authorizedStoredDelivery = () => ingestIdInspection.unsafe
+        ? undefined
+        : matchingStoredDeliveries().find((storedDelivery) => (currentEventOwners.allExist || storedDelivery.outputs.events.length === 0)
+            &&
+                storedIntegrationIngestRetainsCurrentOutputs({
+                    allSamplesExist: sampleAppendPlan.appendedRecordIds.length === 0,
+                    associationEvidenceRolesByPreparedRecordId,
+                    baselineRetainedPreparedIds,
+                    currentEventOwners,
+                    deviceBatchPlan,
+                    preparedEventOutputOwners,
+                    replayRetainedPreparedIds,
+                    sampleRecords,
+                    storedDelivery,
+                }));
+    const hasInvalidCandidateId = () => orderedCandidateImportIds.some((id) => ingestIdInspection.invalidIds.has(id));
+    const assertNoCurrentImportIdConflict = () => {
+        const current = ingestIdInspection.entriesById.get(deviceBatchPlan.importId);
+        if (current && !storedIntegrationIngestIsDeviceDeliveryCandidate(current, deviceBatchPlan)) {
+            throw new VaultError("INTEGRATION_INGEST_ID_CONFLICT", `Device ingest id "${deviceBatchPlan.importId}" already belongs to a different delivery.`, { ingestId: deviceBatchPlan.importId });
+        }
+    };
+    const buildExactNoopResult = (storedDelivery) => buildStoredDeviceDeliveryNoopResult({
+        associationEvidenceRolesByPreparedRecordId,
+        currentEventOwners,
+        deviceBatchPlan,
+        eventTargetShardPaths,
+        preparedEventOutputOwners,
+        sampleRecords,
+        storedDelivery,
+    });
+    let fullInspectionAttempted = false;
+    const ensureFullInspection = async () => {
+        if (fullInspectionAttempted || (ingestIdInspection.historyComplete && !ingestIdInspection.unsafe)) {
+            return;
+        }
+        fullInspectionAttempted = true;
+        ingestIdInspection = await inspectIntegrationIngestIdsForImportedAt(vaultRoot, deviceBatchPlan.importedAt, candidateImportIds, { fullScan: true });
+    };
+    const inspectExactDeliveryState = () => {
+        assertNoCurrentImportIdConflict();
+        const retainedDelivery = authorizedStoredDelivery();
+        if (retainedDelivery) {
+            return {
+                authorizedStoredDelivery: retainedDelivery,
+                evidenceRepairRequired: false,
+                untrustedExactIdentityObserved: false,
+            };
+        }
+        const candidateDeliveries = candidateStoredDeliveries();
+        const hasCompleteRetainedDelivery = matchingStoredDeliveries().some((storedDelivery) => (currentEventOwners.allExist || storedDelivery.outputs.events.length === 0)
+            && storedIntegrationIngestRetainsCurrentOutputs({
+                allSamplesExist: sampleAppendPlan.appendedRecordIds.length === 0,
+                associationEvidenceRolesByPreparedRecordId,
+                baselineRetainedPreparedIds,
+                currentEventOwners,
+                deviceBatchPlan,
+                preparedEventOutputOwners,
+                replayRetainedPreparedIds,
+                sampleRecords,
+                storedDelivery,
+            }));
+        return {
+            evidenceRepairRequired: hasInvalidCandidateId()
+                || (candidateDeliveries.length > 0 && !hasCompleteRetainedDelivery),
+            untrustedExactIdentityObserved: hasInvalidCandidateId()
+                || candidateDeliveries.length > 0,
+        };
+    };
+    const preparePersistence = async (exactState) => {
+        const { evidenceRepairRequired } = exactState;
+        if (exactState.untrustedExactIdentityObserved) {
+            const owners = new Set(deviceBatchPlan.preparedEvents
+                .filter((entry) => baselineRetainedPreparedIds.has(entry.record.id))
+                .map((entry) => preparedEventOutputOwners.byPreparedId.get(entry.record.id))
+                .filter((owner) => owner !== undefined));
+            const ownerWithoutSurvivingRevision = [...owners].some((owner) => ![...owner.preparedIds].some((preparedId) => currentEventOwners.currentRecordByPreparedId.has(preparedId)));
+            if (ownerWithoutSurvivingRevision) {
+                throw new VaultError("INTEGRATION_INGEST_EVENT_MAPPING_AMBIGUOUS", "Observed exact device delivery has no surviving event owner revision.");
+            }
+        }
+        const exactStoredDeliveries = matchingStoredDeliveries();
+        for (const storedDelivery of exactStoredDeliveries) {
+            for (const output of storedDelivery.outputs.events) {
+                const owner = preparedEventOutputOwners.byOutputId.get(output.id);
+                if (!owner) {
+                    continue;
+                }
+                if (!storedEventOutputRolesBelongToPreparedOwner({
+                    evidenceRolesByPreparedRecordId: deviceBatchPlan.evidenceRolesByPreparedRecordId,
+                    output,
+                    owner,
+                })) {
+                    throw new VaultError("INTEGRATION_INGEST_EVENT_MAPPING_AMBIGUOUS", `Stored canonical event "${output.id}" has evidence roles outside its owner.`);
+                }
+            }
+        }
+        const storedOutputProof = storedOutputIdsByPreparedId({
+            evidenceRolesByPreparedRecordId: deviceBatchPlan.evidenceRolesByPreparedRecordId,
+            preparedEventOutputOwners,
+            storedDeliveries: exactStoredDeliveries,
+        });
+        const unresolvedPreparedIdWithoutStoredProof = [...unresolvedBaselinePreparedIds].find((preparedId) => !storedOutputProof.outputIdByPreparedId.has(preparedId));
+        if (evidenceRepairRequired && unresolvedPreparedIdWithoutStoredProof !== undefined) {
+            throw new VaultError("INTEGRATION_INGEST_EVENT_MAPPING_AMBIGUOUS", `Unresolved device event member "${unresolvedPreparedIdWithoutStoredProof}" has no exact stored-output proof.`);
+        }
+        const retainedStoredEvidenceRoles = new Map([...storedOutputProof.outputIdByPreparedId.keys()].map((preparedId) => [
+            preparedId,
+            deviceBatchPlan.evidenceRolesByPreparedRecordId.get(preparedId) ?? [],
+        ]));
+        const acceptedEvidenceRolesByPreparedRecordId = evidenceRepairRequired
+            && exactStoredDeliveries.length > 0
+            ? retainedStoredEvidenceRoles
+            : deviceBatchPlan.evidenceRolesByPreparedRecordId;
+        const persistenceProtectedPreparedEventIds = new Set([
+            ...protectedPreparedEventIds,
+            ...deviceBatchPlan.preparedEvents
+                .filter((entry) => evidenceRepairRequired
+                && baselineRetainedPreparedIds.has(entry.record.id)
+                && currentEventOwners.currentRecordByPreparedId.has(entry.record.id)
+                && !currentEventOwners.associationSafePreparedIds.has(entry.record.id)
+                && !currentEventOwners.incomingNewerPreparedIds.has(entry.record.id))
+                .map((entry) => entry.record.id),
+        ]);
+        const reconciliationEntries = deviceBatchPlan.preparedEvents.filter((entry) => baselineRetainedPreparedIds.has(entry.record.id)
+            && !persistenceProtectedPreparedEventIds.has(entry.record.id)
+            && (!evidenceRepairRequired
+                || acceptedEvidenceRolesByPreparedRecordId.has(entry.record.id)));
+        const storedEventOutputs = exactStoredDeliveries.flatMap((storedDelivery) => storedDelivery.outputs.events);
+        const eventRepairRequired = evidenceRepairRequired
+            && storedEventOutputs.length > 0
+            && (storedEventOutputs.some((output) => !storedOutputProof.ownedOutputIds.has(output.id))
+                || unresolvedBaselinePreparedIds.size > 0);
+        const unresolvedStoredOutputId = storedOutputProof.unresolvedOutputIds.values().next().value;
+        if (eventRepairRequired && unresolvedStoredOutputId !== undefined) {
+            throw new VaultError("INTEGRATION_INGEST_EVENT_MAPPING_AMBIGUOUS", `Stored canonical event "${unresolvedStoredOutputId}" is not owned by the prepared device event.`);
+        }
+        const storedEventRepairIds = eventRepairRequired
+            ? buildStoredEventRepairIds({
+                currentEventOwners,
+                deviceBatchPlan,
+                preparedEventOutputOwners,
+                storedOutputIdByPreparedId: storedOutputProof.outputIdByPreparedId,
+                storedDeliveries: exactStoredDeliveries,
+            })
+            : new Map();
+        for (const [preparedId, repairId] of storedEventRepairIds) {
+            const owner = preparedEventOutputOwners.byPreparedId.get(preparedId);
+            const hasSurvivingOwnerRevision = owner !== undefined
+                && [...owner.preparedIds].some((ownerPreparedId) => currentEventOwners.currentRecordByPreparedId.get(ownerPreparedId)?.id === repairId);
+            if (!hasSurvivingOwnerRevision) {
+                throw new VaultError("INTEGRATION_INGEST_EVENT_MAPPING_AMBIGUOUS", "Missing device event spine has no surviving owner revision.");
+            }
+        }
+        const historicalRepairEntryByPreparedId = new Map();
+        const historicalRepairRevision = (preparedId, owner, repairId) => {
+            const baselineRecord = baselineRecordByPreparedId.get(preparedId);
+            const current = currentEventOwners.currentRecordByPreparedId.get(preparedId);
+            if (!baselineRecord || !current) {
+                throw new VaultError("INTEGRATION_INGEST_EVENT_MAPPING_AMBIGUOUS", "Missing historical device event revision has no surviving delivery anchor.");
+            }
+            if (currentEventOwners.incomingNewerPreparedIds.has(preparedId)) {
+                throw new VaultError("INTEGRATION_INGEST_EVENT_MAPPING_AMBIGUOUS", "Accepted device event revision has no owner-issued historical placement proof.");
+            }
+            let candidateOffsets;
+            for (const anchorPreparedId of owner.preparedIds) {
+                if (!baselineRetainedPreparedIds.has(anchorPreparedId)
+                    || storedOutputProof.outputIdByPreparedId.get(anchorPreparedId) !== repairId) {
+                    continue;
+                }
+                const anchorBaselineRecord = baselineRecordByPreparedId.get(anchorPreparedId);
+                const matchedRevisions = currentEventOwners.historicalContentOwnerRevisionsByPreparedId
+                    .get(anchorPreparedId)
+                    ?.get(repairId);
+                if (!anchorBaselineRecord || !matchedRevisions || matchedRevisions.size === 0) {
+                    continue;
+                }
+                const offsets = new Set([...matchedRevisions]
+                    .map((revision) => revision - eventSpineRevision(anchorBaselineRecord))
+                    .filter((offset) => offset >= 0));
+                candidateOffsets = candidateOffsets === undefined
+                    ? offsets
+                    : new Set([...candidateOffsets].filter((offset) => offsets.has(offset)));
+            }
+            if (candidateOffsets?.size !== 1) {
+                throw new VaultError("INTEGRATION_INGEST_EVENT_MAPPING_AMBIGUOUS", "Missing historical device event revision has no unique surviving delivery anchor.");
+            }
+            return eventSpineRevision(baselineRecord) + [...candidateOffsets][0];
+        };
+        for (const entry of deviceBatchPlan.preparedEvents) {
+            const repairId = storedEventRepairIds.get(entry.record.id);
+            const current = currentEventOwners.currentRecordByPreparedId.get(entry.record.id);
+            const owner = preparedEventOutputOwners.byPreparedId.get(entry.record.id);
+            const baselineRecord = baselineRecordByPreparedId.get(entry.record.id);
+            if (!repairId
+                || !current
+                || current.id !== repairId
+                || isDeletedEventSpineRecord(current)
+                || !owner
+                || !baselineRecord) {
+                continue;
+            }
+            const repairRevision = historicalRepairRevision(entry.record.id, owner, repairId);
+            if (!Number.isSafeInteger(repairRevision)
+                || repairRevision < 1
+                || repairRevision >= eventSpineRevision(current)
+                || eventIdentityContext.index.revisionsById.get(repairId)?.has(repairRevision)) {
+                throw new VaultError("INTEGRATION_INGEST_EVENT_MAPPING_AMBIGUOUS", "Missing historical device event revision conflicts with the surviving event spine.");
+            }
+            const repairedRecord = {
+                ...baselineRecord,
+                id: repairId,
+                lifecycle: buildEventSpineLifecycle(repairRevision),
+            };
+            historicalRepairEntryByPreparedId.set(entry.record.id, {
+                relativePath: entry.relativePath,
+                record: repairedRecord,
+            });
+        }
+        for (const preparedId of storedEventRepairIds.keys()) {
+            if (!historicalRepairEntryByPreparedId.has(preparedId)) {
+                throw new VaultError("INTEGRATION_INGEST_EVENT_MAPPING_AMBIGUOUS", "Missing historical device event revision could not be restored safely.");
+            }
+        }
+        const persistenceReconciliationEntries = reconciliationEntries.filter((entry) => !storedEventRepairIds.has(entry.record.id));
+        const repairedProtectedPreparedEventCount = [...historicalRepairEntryByPreparedId.keys()].filter((preparedId) => persistenceProtectedPreparedEventIds.has(preparedId)).length;
+        const reconciled = evidenceRepairRequired
+            ? await reconcileDeviceEventEntriesByExternalRef(vaultRoot, persistenceReconciliationEntries, cloneDeviceEventIdentityContext(eventIdentityContext))
+            : currentEventReconciliation;
+        const reconciledRecordByPreparedId = new Map(persistenceReconciliationEntries.map((entry, index) => [
+            entry.record.id,
+            reconciled.records[index] ?? entry.record,
+        ]));
+        const eventReconciliation = {
+            ...reconciled,
+            appendEntries: [
+                ...reconciled.appendEntries,
+                ...historicalRepairEntryByPreparedId.values(),
+            ],
+            appendRecordIdByPreparedRecordId: new Map([
+                ...reconciled.appendRecordIdByPreparedRecordId,
+                ...[...historicalRepairEntryByPreparedId].map(([preparedId, repairEntry]) => [
+                    preparedId,
+                    repairEntry.record.id,
+                ]),
+            ]),
+            forceAppendIds: new Set([
+                ...reconciled.forceAppendIds,
+                ...[...historicalRepairEntryByPreparedId.values()].map((repairEntry) => repairEntry.record.id),
+            ]),
+            records: deviceBatchPlan.preparedEvents.map((entry) => {
+                const historicalRepair = historicalRepairEntryByPreparedId.get(entry.record.id);
+                if (historicalRepair) {
+                    return historicalRepair.record;
+                }
+                const current = currentEventOwners.currentRecordByPreparedId.get(entry.record.id);
+                if (current && persistenceProtectedPreparedEventIds.has(entry.record.id)) {
+                    return current;
+                }
+                return reconciledRecordByPreparedId.get(entry.record.id) ?? entry.record;
+            }),
+            retainedPreparedIds: new Set([
+                ...reconciled.retainedPreparedIds,
+                ...persistenceProtectedPreparedEventIds,
+            ]),
+            skippedDuplicateCount: reconciled.skippedDuplicateCount
+                + persistenceProtectedPreparedEventIds.size
+                - repairedProtectedPreparedEventCount,
+        };
+        const eventAppendPlan = await buildJsonlAppendPlan(vaultRoot, eventReconciliation.appendEntries, {
+            dedupeWithinPlan: true,
+            forceAppendIds: eventReconciliation.forceAppendIds,
+        });
+        const eventRecords = eventReconciliation.records;
+        const canonicalIdByPreparedId = mapPreparedDeviceEventsToCanonicalIds(deviceBatchPlan.preparedEvents, eventRecords);
+        const appendedEventRecordIds = new Set(eventAppendPlan.appendedRecordIds);
+        const appendedPreparedEventIds = new Set([...eventReconciliation.appendRecordIdByPreparedRecordId.entries()]
+            .filter(([, recordId]) => appendedEventRecordIds.has(recordId))
+            .map(([preparedRecordId]) => preparedRecordId));
+        const associablePreparedEventIds = new Set([
+            ...deviceBatchPlan.preparedEvents
+                .filter((entry) => baselineRetainedPreparedIds.has(entry.record.id)
+                && hasAuthorizedCurrentDeviceEventOutput(currentEventOwners, entry.record.id))
+                .map((entry) => entry.record.id),
+            ...[...appendedPreparedEventIds].filter((preparedId) => baselineRetainedPreparedIds.has(preparedId)),
+        ]);
+        const canonicalEventRecords = eventRecords.filter((_, index) => {
+            const preparedId = deviceBatchPlan.preparedEvents[index]?.record.id;
+            return preparedId !== undefined && associablePreparedEventIds.has(preparedId);
+        });
+        const persistenceEvidenceRolesByPreparedRecordId = new Map(deviceBatchPlan.preparedEvents
+            .filter((entry) => associablePreparedEventIds.has(entry.record.id)
+            && acceptedEvidenceRolesByPreparedRecordId.has(entry.record.id))
+            .map((entry) => [
+            entry.record.id,
+            acceptedEvidenceRolesByPreparedRecordId.get(entry.record.id) ?? [],
+        ]));
+        const persistencePreparedEvents = deviceBatchPlan.preparedEvents.filter((entry) => associablePreparedEventIds.has(entry.record.id)
+            && persistenceEvidenceRolesByPreparedRecordId.has(entry.record.id));
+        const hasAppendedOutputs = appendedPreparedEventIds.size > 0
+            || sampleAppendPlan.appendedRecordIds.length > 0;
+        const eventIdsByEvidenceRole = new Map();
+        for (const entry of deviceBatchPlan.preparedEvents) {
+            const canonicalEventId = canonicalIdByPreparedId.get(entry.record.id);
+            if (!canonicalEventId) {
+                continue;
+            }
+            for (const role of persistenceEvidenceRolesByPreparedRecordId.get(entry.record.id) ?? []) {
+                const eventIds = eventIdsByEvidenceRole.get(role) ?? new Set();
+                eventIds.add(canonicalEventId);
+                eventIdsByEvidenceRole.set(role, eventIds);
+            }
+        }
+        const shouldCheckReceiptNovelty = !hasAppendedOutputs;
+        const novelty = deviceBatchPlan.preparedEvidenceParts.length > 0 || (shouldCheckReceiptNovelty && deviceBatchPlan.ingestReceipt)
+            ? await selectNovelIntegrationIngestEvidence({
+                vaultRoot,
+                provider: deviceBatchPlan.provider,
+                accountId: deviceBatchPlan.accountId,
+                importedAt: deviceBatchPlan.importedAt,
+                parts: deviceBatchPlan.preparedEvidenceParts,
+                receipt: shouldCheckReceiptNovelty ? deviceBatchPlan.ingestReceipt : undefined,
+                eventIdsByRole: eventIdsByEvidenceRole,
+                sampleIds: new Set(sampleRecords.map((record) => record.id)),
+            })
+            : { parts: [], receiptIsNovel: false };
+        const shouldPersistDelivery = hasAppendedOutputs
+            || novelty.parts.length > 0
+            || novelty.receiptIsNovel
+            || evidenceRepairRequired;
+        const retainedEvidenceParts = shouldPersistDelivery
+            ? deviceBatchPlan.preparedEvidenceParts
+            : [];
+        const retainedEvidenceRoles = new Set(retainedEvidenceParts.map((part) => part.role));
+        const retainedEvidenceRolesByPreparedRecordId = new Map();
+        for (const entry of deviceBatchPlan.preparedEvents) {
+            retainedEvidenceRolesByPreparedRecordId.set(entry.record.id, (persistenceEvidenceRolesByPreparedRecordId.get(entry.record.id) ?? []).filter((role) => retainedEvidenceRoles.has(role)));
+        }
+        const eventOutputs = buildIntegrationEventOutputs(shouldPersistDelivery ? persistencePreparedEvents : [], canonicalIdByPreparedId, retainedEvidenceRolesByPreparedRecordId);
+        const buildNoopResult = () => ({
+            applied: false,
+            ingestId: null,
+            ingestShardPath: null,
+            provider: deviceBatchPlan.provider,
+            accountId: deviceBatchPlan.accountId,
+            importedAt: deviceBatchPlan.importedAt,
+            events: canonicalEventRecords,
+            samples: sampleRecords,
+            eventShardPaths: eventTargetShardPaths,
+            sampleShardPaths: sampleAppendPlan.targetShardPaths,
+            evidencePartCount: deviceBatchPlan.preparedEvidenceParts.length,
+            persistedEvidencePartCount: 0,
+            auditPath: null,
+        });
+        return {
+            buildNoopResult,
+            eventAppendPlan,
+            eventOutputs,
+            eventReconciliation,
+            canonicalEventRecords,
+            retainedEvidenceParts,
+            shouldPersistDelivery,
+        };
+    };
+    let exactState = inspectExactDeliveryState();
+    if (exactState.authorizedStoredDelivery) {
+        return buildExactNoopResult(exactState.authorizedStoredDelivery);
+    }
+    let persistence;
+    try {
+        persistence = await preparePersistence(exactState);
+    }
+    catch (error) {
+        await ensureFullInspection();
+        exactState = inspectExactDeliveryState();
+        if (exactState.authorizedStoredDelivery) {
+            return buildExactNoopResult(exactState.authorizedStoredDelivery);
+        }
+        if (!exactState.evidenceRepairRequired) {
+            throw error;
+        }
+        persistence = await preparePersistence(exactState);
+    }
+    const unresolvedBaselineMember = unresolvedBaselinePreparedIds.size > 0;
+    const assertInspectionCanAuthorizeNoop = () => {
+        if (unresolvedBaselineMember
+            && (!ingestIdInspection.historyComplete || ingestIdInspection.unsafe)) {
+            throw new VaultError("INTEGRATION_INGEST_EVENT_MAPPING_AMBIGUOUS", "Unresolved device event member has no authoritative exact-delivery inspection.");
+        }
+    };
+    const incompleteInspectionCannotAuthorizeNoop = unresolvedBaselineMember
+        && (!ingestIdInspection.historyComplete || ingestIdInspection.unsafe);
+    if (persistence.shouldPersistDelivery || incompleteInspectionCannotAuthorizeNoop) {
+        await ensureFullInspection();
+        const authoritativeExactState = inspectExactDeliveryState();
+        if (authoritativeExactState.authorizedStoredDelivery) {
+            return buildExactNoopResult(authoritativeExactState.authorizedStoredDelivery);
+        }
+        persistence = await preparePersistence(authoritativeExactState);
+    }
+    if (!persistence.shouldPersistDelivery) {
+        assertInspectionCanAuthorizeNoop();
+        return persistence.buildNoopResult();
+    }
+    const { buildNoopResult, eventAppendPlan, eventOutputs, eventReconciliation, canonicalEventRecords, retainedEvidenceParts, } = persistence;
+    const currentImportIdOccupied = ingestIdInspection.entriesById.has(deviceBatchPlan.importId)
+        || ingestIdInspection.invalidIds.has(deviceBatchPlan.importId);
+    const finalAssociationImportId = buildAssociationImportId(eventOutputs);
+    const persistedImportId = currentImportIdOccupied
+        ? finalAssociationImportId
+        : deviceBatchPlan.importId;
     const ingestRecord = buildIntegrationIngestRecord({
-        id: deviceBatchPlan.importId,
+        id: persistedImportId,
         provider: deviceBatchPlan.provider,
         accountId: deviceBatchPlan.accountId,
         source: deviceBatchPlan.source,
         importedAt: deviceBatchPlan.importedAt,
         receipt: deviceBatchPlan.ingestReceipt,
-        parts: deviceBatchPlan.preparedEvidenceParts,
+        parts: retainedEvidenceParts,
         eventOutputs,
         eventIdsComplete: true,
         sampleIds: sampleRecords.map((record) => record.id),
@@ -1876,15 +3269,29 @@ export async function importDeviceBatch({ vaultRoot, provider, accountId, import
         sampleCount: sampleRecords.length,
         provenance: deviceBatchPlan.provenance,
     });
-    const ingestAppendPlan = await buildIntegrationIngestAppendPlan(vaultRoot, [ingestRecord]);
+    const persistedImportIdWasInspected = ingestIdInspection.requestedIds.has(persistedImportId);
+    const ingestAppendPlan = !persistedImportIdWasInspected
+        || (ingestIdInspection.unsafe && !ingestIdInspection.failOpenAppendAllowed)
+        ? await buildIntegrationIngestAppendPlan(vaultRoot, [ingestRecord], {
+            allowArchivedShardAmendments: true,
+        })
+        : buildIntegrationIngestAppendPlanFromInspection([ingestRecord], ingestIdInspection, {
+            allowArchivedShardAmendments: true,
+        });
     const [ingestShardPath] = ingestAppendPlan.targetShardPaths;
     if (!ingestShardPath) {
         throw new VaultError("INTEGRATION_INGEST_SHARD_INVALID", `No integration ingest shard was prepared for "${ingestRecord.id}".`);
     }
+    if (ingestAppendPlan.appendedIds.length === 0
+        && eventAppendPlan.appendedRecordIds.length === 0
+        && sampleAppendPlan.appendedRecordIds.length === 0) {
+        assertInspectionCanAuthorizeNoop();
+        return buildNoopResult();
+    }
     return runCanonicalWrite({
         vaultRoot,
         operationType: "device_batch_import",
-        summary: `Import ${deviceBatchPlan.provider} device batch ${deviceBatchPlan.importId}`,
+        summary: `Import ${deviceBatchPlan.provider} device batch ${persistedImportId}`,
         occurredAt: deviceBatchPlan.effectiveOccurredAt,
         mutate: async ({ batch }) => {
             await stageIntegrationIngestAppendPlan(batch, ingestAppendPlan);
@@ -1902,26 +3309,28 @@ export async function importDeviceBatch({ vaultRoot, provider, accountId, import
                 commandName: "core.importDeviceBatch",
                 summary: buildDeviceBatchAuditSummary({
                     provider: deviceBatchPlan.provider,
-                    eventCount: eventRecords.length,
+                    eventCount: eventOutputs.length,
                     sampleCount: sampleRecords.length,
                     skippedDuplicateCount: eventReconciliation.skippedDuplicateCount,
                     supersededCount: eventReconciliation.supersededCount,
                 }),
                 occurredAt: deviceBatchPlan.importedAt,
                 files: touchedPaths,
-                targetIds: [deviceBatchPlan.importId],
+                targetIds: [persistedImportId],
             });
             return {
-                ingestId: deviceBatchPlan.importId,
+                applied: true,
+                ingestId: persistedImportId,
                 ingestShardPath,
                 provider: deviceBatchPlan.provider,
                 accountId: deviceBatchPlan.accountId,
                 importedAt: deviceBatchPlan.importedAt,
-                events: eventRecords,
+                events: canonicalEventRecords,
                 samples: sampleRecords,
                 eventShardPaths: eventTargetShardPaths,
                 sampleShardPaths: sampleAppendPlan.targetShardPaths,
                 evidencePartCount: deviceBatchPlan.preparedEvidenceParts.length,
+                persistedEvidencePartCount: retainedEvidenceParts.length,
                 auditPath: audit.relativePath,
             };
         },
@@ -1931,14 +3340,29 @@ const EVENT_BATCH_FAILURE_REPORT_LIMIT = 20;
 // importEventBatch is public API surface, so the batch-shape invariants live
 // here rather than in CLI adapters: payloads must be a non-empty array of
 // plain objects.
-function normalizeImportEventBatchPayloads(value) {
+function normalizeImportEventBatchPayloads(value, signal) {
     if (!Array.isArray(value)) {
         throw new VaultError("EVENT_BATCH_INVALID", "Event batch payloads must be an array.");
     }
     if (value.length === 0) {
         throw new VaultError("EVENT_BATCH_EMPTY", "Event batch payloads must not be empty.");
     }
-    return value.map((entry, index) => assertPlainObject(entry, "EVENT_BATCH_INVALID", `Event batch payload ${index + 1} must be a plain object.`));
+    return value.map((entry, index) => {
+        signal?.throwIfAborted();
+        return assertPlainObject(entry, "EVENT_BATCH_INVALID", `Event batch payload ${index + 1} must be a plain object.`);
+    });
+}
+function normalizeImportEventBatchDecisions(value, signal) {
+    if (!Array.isArray(value)) {
+        throw new VaultError("EVENT_BATCH_INVALID", "Event batch decisions must be an array.");
+    }
+    if (value.length === 0) {
+        throw new VaultError("EVENT_BATCH_EMPTY", "Event batch decisions must not be empty.");
+    }
+    return value.map((entry, index) => {
+        signal?.throwIfAborted();
+        return assertPlainObject(entry, "EVENT_BATCH_INVALID", `Event batch decision ${index + 1} must be a plain object.`);
+    });
 }
 // Bulk canonical event import: every payload is validated through the same
 // strict contract path as the single-event upsert before anything is staged,
@@ -1947,15 +3371,68 @@ function normalizeImportEventBatchPayloads(value) {
 // resourceType + resourceId + facet, even when a corrected occurredAt moves
 // the row to another monthly shard) and land in one canonical write with one
 // audit record. Dry-run by default; `apply` commits.
-export async function importEventBatch({ vaultRoot, payloads, apply = false, }) {
-    const normalizedPayloads = normalizeImportEventBatchPayloads(payloads);
+export async function importEventBatch(input) {
+    const { vaultRoot, apply = false, signal } = input;
+    signal?.throwIfAborted();
+    const usesPayloads = "payloads" in input && input.payloads !== undefined;
+    const usesDecisions = "decisions" in input && input.decisions !== undefined;
+    if (usesPayloads === usesDecisions) {
+        throw new VaultError("EVENT_BATCH_INVALID", "Event batch must define exactly one of payloads or decisions.");
+    }
+    const normalizedRows = usesDecisions
+        ? normalizeImportEventBatchDecisions(input.decisions, signal)
+        : normalizeImportEventBatchPayloads(input.payloads, signal);
     const vault = await loadVault({ vaultRoot });
-    const entries = [];
+    const decisions = [];
     const failures = [];
-    normalizedPayloads.forEach((payload, index) => {
+    const recordedAt = new Date().toISOString();
+    normalizedRows.forEach((row, index) => {
+        signal?.throwIfAborted();
         try {
-            const record = buildPublicEventImportRecord(payload, vault.metadata.timezone);
-            entries.push({ relativePath: toEventLedgerFile(record.occurredAt), record });
+            if (!usesDecisions) {
+                const record = buildPublicEventImportRecord(row, vault.metadata.timezone);
+                decisions.push({
+                    action: "upsert",
+                    allowsKindReplacement: false,
+                    entry: { relativePath: toEventLedgerFile(record.occurredAt), record },
+                });
+                return;
+            }
+            const parsed = safeParseContract(eventImportDecisionSchema, row);
+            if (!parsed.success) {
+                throw new Error(parsed.errors.join("; "));
+            }
+            const decision = parsed.data;
+            if (decision.action === "retract") {
+                const markerRecord = buildPublicEventImportRecord({
+                    kind: "note",
+                    occurredAt: decision.externalRef.version,
+                    recordedAt,
+                    source: "import",
+                    title: "Retracted imported source record",
+                    note: decision.reason,
+                    noteType: EVENT_IMPORT_RETRACTION_MARKER_NOTE_TYPE,
+                    ...(decision.evidence ? { evidence: decision.evidence } : {}),
+                    externalRef: decision.externalRef,
+                }, vault.metadata.timezone);
+                decisions.push({
+                    action: "retract",
+                    externalRef: decision.externalRef,
+                    evidence: decision.evidence,
+                    reason: decision.reason,
+                    markerEntry: {
+                        relativePath: toEventLedgerFile(markerRecord.occurredAt),
+                        record: markerRecord,
+                    },
+                });
+                return;
+            }
+            const record = buildPublicEventImportRecord({ ...decision.payload }, vault.metadata.timezone);
+            decisions.push({
+                action: "upsert",
+                allowsKindReplacement: true,
+                entry: { relativePath: toEventLedgerFile(record.occurredAt), record },
+            });
         }
         catch (error) {
             failures.push({
@@ -1965,45 +3442,46 @@ export async function importEventBatch({ vaultRoot, payloads, apply = false, })
         }
     });
     if (failures.length > 0) {
-        throw new VaultError("EVENT_BATCH_INVALID", `${failures.length} of ${normalizedPayloads.length} event payload(s) failed validation; nothing was imported.`, {
+        throw new VaultError("EVENT_BATCH_INVALID", `${failures.length} of ${normalizedRows.length} event import decision(s) failed validation; nothing was imported.`, {
             failureCount: failures.length,
             failures: failures.slice(0, EVENT_BATCH_FAILURE_REPORT_LIMIT),
         });
     }
-    const reconciliation = await reconcileEventImportEntriesByExternalRef(vaultRoot, entries);
+    signal?.throwIfAborted();
+    const reconciliation = await reconcileEventImportDecisionsByExternalRef(vaultRoot, decisions, signal);
     const appendPlan = await buildJsonlAppendPlan(vaultRoot, reconciliation.appendEntries, {
         dedupeWithinPlan: true,
         forceAppendIds: reconciliation.forceAppendIds,
+        signal,
     });
+    signal?.throwIfAborted();
     // Target shards come from the prepared rows (pre-reconcile), matching
     // importDeviceBatch: an all-skipped batch still reports the shards it
     // evaluated.
-    const eventTargetShardPaths = [
-        ...new Set(entries.map((entry) => entry.relativePath)),
-    ].sort();
     const appendedCount = appendPlan.appendedRecordIds.length;
-    const eventIds = appendPlan.appendedRecordIds;
-    const supersededCount = reconciliation.supersededCount;
     const counts = {
-        receivedCount: normalizedPayloads.length,
-        createdCount: appendedCount - supersededCount,
-        skippedExistingCount: normalizedPayloads.length - appendedCount,
-        supersededCount,
-        eventIds,
+        receivedCount: normalizedRows.length,
+        createdCount: reconciliation.createdCount,
+        skippedExistingCount: reconciliation.skippedExistingCount,
+        supersededCount: reconciliation.supersededCount,
+        retractedCount: reconciliation.retractedCount,
+        eventIds: reconciliation.eventIds,
+        retractedEventIds: reconciliation.retractedEventIds,
     };
     if (!apply || appendedCount === 0) {
         return {
             applied: false,
             ...counts,
-            eventShardPaths: eventTargetShardPaths,
+            eventShardPaths: reconciliation.eventShardPaths,
             auditPath: null,
         };
     }
-    const occurredAt = earliestTimestamp(entries.map((entry) => entry.record.occurredAt));
+    const occurredAt = earliestTimestamp(reconciliation.appendEntries.map((entry) => entry.record.occurredAt));
+    signal?.throwIfAborted();
     return runCanonicalWrite({
         vaultRoot,
         operationType: "event_batch_import",
-        summary: `Import event batch with ${appendedCount} appended event(s)`,
+        summary: `Import event batch with ${normalizedRows.length} decision(s)`,
         occurredAt,
         mutate: async ({ batch }) => {
             await stageJsonlAppendPlan(batch, appendPlan);
@@ -2013,16 +3491,17 @@ export async function importEventBatch({ vaultRoot, payloads, apply = false, })
                 action: "event_upsert",
                 commandName: "core.importEventBatch",
                 summary: `Imported event batch: ${counts.createdCount} created, ` +
-                    `${counts.supersededCount} updated in place, ` +
+                    `${counts.supersededCount} superseded, ` +
+                    `${counts.retractedCount} retracted, ` +
                     `${counts.skippedExistingCount} skipped existing of ${counts.receivedCount} received.`,
                 occurredAt,
                 files: appendPlan.appendedShardPaths,
-                targetIds: appendPlan.appendedRecordIds.slice(0, AUDIT_TARGET_ID_LIMIT),
+                targetIds: [...new Set(appendPlan.appendedRecordIds)].slice(0, AUDIT_TARGET_ID_LIMIT),
             });
             return {
                 applied: true,
                 ...counts,
-                eventShardPaths: eventTargetShardPaths,
+                eventShardPaths: reconciliation.eventShardPaths,
                 auditPath: audit.relativePath,
             };
         },