@evomap/evolver-core 2.0.0-beta.19 → 2.0.0-beta.22

package/dist/mailbox/store.js

@@ -1,5 +1,7 @@
-import { mkdirSync, existsSync, openSync, readSync, closeSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+import { chmodSync, closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, mkdtempSync, openSync, readSync, rmSync, writeSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
 import { createRequire } from 'node:module';
 import { ulid as makeUlid } from 'ulid';
 import { createEnvelope, ENVELOPE_SCHEMA_VERSION, normalizePriority, sanitizePayload, specForType, } from './envelope.js';
@@ -17,10 +19,231 @@ function openSqliteDatabase(path, options = {}) {
     const { DatabaseSync } = nodeRequire('node:sqlite');
     return options.readOnly ? new DatabaseSync(path, { readOnly: true }) : new DatabaseSync(path);
 }
+const MAILBOX_PREVIEW_MAX_FILE_BYTES = 256 * 1024 * 1024;
+const MAILBOX_PREVIEW_MAX_TOTAL_BYTES = 512 * 1024 * 1024;
+const MAILBOX_PREVIEW_COPY_BUFFER_BYTES = 64 * 1024;
+function mailboxPreviewError(code) {
+    return new Error(`mailbox_preview_${code}`);
+}
+function mailboxPreviewNoFollowFlag() {
+    return constants['O_NOFOLLOW'] ?? 0;
+}
+function mailboxPreviewStat(path) {
+    let stat;
+    try {
+        stat = lstatSync(path, { bigint: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw mailboxPreviewError('target_unsafe');
+    }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink > 1n) {
+        throw mailboxPreviewError('target_unsafe');
+    }
+    return stat;
+}
+function sameMailboxPreviewSnapshot(left, right) {
+    const hasStableFileId = left.dev !== 0n || left.ino !== 0n || right.dev !== 0n || right.ino !== 0n;
+    const sameIdentity = hasStableFileId
+        ? left.dev === right.dev && left.ino === right.ino
+        : left.birthtimeNs === right.birthtimeNs && left.mode === right.mode;
+    return sameIdentity
+        && left.mode === right.mode
+        && left.size === right.size
+        && left.mtimeNs === right.mtimeNs
+        && left.ctimeNs === right.ctimeNs;
+}
+function assertMailboxPreviewSize(stat) {
+    if (stat.size > BigInt(MAILBOX_PREVIEW_MAX_FILE_BYTES)
+        || stat.size > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw mailboxPreviewError('target_too_large');
+    }
+    return Number(stat.size);
+}
+function writeMailboxPreviewChunk(fd, chunk, position) {
+    let offset = 0;
+    while (offset < chunk.length) {
+        const written = writeSync(fd, chunk, offset, chunk.length - offset, position + offset);
+        if (written <= 0)
+            throw mailboxPreviewError('snapshot_write_failed');
+        offset += written;
+    }
+}
+function copyStableMailboxPreviewFile(sourcePath, destinationPath, expected) {
+    const expectedBytes = assertMailboxPreviewSize(expected);
+    let sourceFd;
+    let destinationFd;
+    try {
+        sourceFd = openSync(sourcePath, constants.O_RDONLY | mailboxPreviewNoFollowFlag());
+        const opened = fstatSync(sourceFd, { bigint: true });
+        if (!opened.isFile() || !sameMailboxPreviewSnapshot(expected, opened)) {
+            throw mailboxPreviewError('target_changed');
+        }
+        destinationFd = openSync(destinationPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | mailboxPreviewNoFollowFlag(), 0o600);
+        const digest = createHash('sha256');
+        const buffer = Buffer.allocUnsafe(MAILBOX_PREVIEW_COPY_BUFFER_BYTES);
+        let total = 0;
+        for (;;) {
+            const bytesRead = readSync(sourceFd, buffer, 0, buffer.length, null);
+            if (bytesRead === 0)
+                break;
+            if (total > MAILBOX_PREVIEW_MAX_FILE_BYTES - bytesRead) {
+                throw mailboxPreviewError('target_too_large');
+            }
+            const chunk = buffer.subarray(0, bytesRead);
+            digest.update(chunk);
+            writeMailboxPreviewChunk(destinationFd, chunk, total);
+            total += bytesRead;
+        }
+        fsyncSync(destinationFd);
+        const afterDescriptor = fstatSync(sourceFd, { bigint: true });
+        const afterPath = mailboxPreviewStat(sourcePath);
+        if (total !== expectedBytes
+            || !sameMailboxPreviewSnapshot(opened, afterDescriptor)
+            || !afterPath
+            || !sameMailboxPreviewSnapshot(afterDescriptor, afterPath)) {
+            throw mailboxPreviewError('target_changed');
+        }
+        return Object.freeze({ stat: afterDescriptor, digest: digest.digest('hex'), bytes: total });
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('mailbox_preview_'))
+            throw error;
+        throw mailboxPreviewError('snapshot_failed');
+    }
+    finally {
+        if (sourceFd !== undefined)
+            closeSync(sourceFd);
+        if (destinationFd !== undefined)
+            closeSync(destinationFd);
+    }
+}
+function hashStableMailboxPreviewFile(path, expected) {
+    const before = mailboxPreviewStat(path);
+    if (!before || !sameMailboxPreviewSnapshot(expected.stat, before)) {
+        throw mailboxPreviewError('target_changed');
+    }
+    assertMailboxPreviewSize(before);
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY | mailboxPreviewNoFollowFlag());
+        const opened = fstatSync(fd, { bigint: true });
+        if (!opened.isFile() || !sameMailboxPreviewSnapshot(before, opened)) {
+            throw mailboxPreviewError('target_changed');
+        }
+        const digest = createHash('sha256');
+        const buffer = Buffer.allocUnsafe(MAILBOX_PREVIEW_COPY_BUFFER_BYTES);
+        let total = 0;
+        for (;;) {
+            const bytesRead = readSync(fd, buffer, 0, buffer.length, null);
+            if (bytesRead === 0)
+                break;
+            if (total > MAILBOX_PREVIEW_MAX_FILE_BYTES - bytesRead) {
+                throw mailboxPreviewError('target_too_large');
+            }
+            digest.update(buffer.subarray(0, bytesRead));
+            total += bytesRead;
+        }
+        const afterDescriptor = fstatSync(fd, { bigint: true });
+        const afterPath = mailboxPreviewStat(path);
+        if (total !== expected.bytes
+            || digest.digest('hex') !== expected.digest
+            || !sameMailboxPreviewSnapshot(opened, afterDescriptor)
+            || !afterPath
+            || !sameMailboxPreviewSnapshot(afterDescriptor, afterPath)) {
+            throw mailboxPreviewError('target_changed');
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('mailbox_preview_'))
+            throw error;
+        throw mailboxPreviewError('target_changed');
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function assertMailboxRollbackJournalAbsent(mailboxPath) {
+    try {
+        lstatSync(`${mailboxPath}-journal`);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw mailboxPreviewError('target_unsafe');
+    }
+    throw mailboxPreviewError('hot_rollback_journal');
+}
+function assertMailboxPreviewTargetAbsent(mailboxPath) {
+    for (const suffix of ['-wal', '-shm', '-journal']) {
+        try {
+            lstatSync(`${mailboxPath}${suffix}`);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            throw mailboxPreviewError('target_unsafe');
+        }
+        throw mailboxPreviewError('target_unsafe');
+    }
+    if (mailboxPreviewStat(mailboxPath))
+        throw mailboxPreviewError('target_changed');
+}
+function stableMailboxPreviewCopy(mailboxPath) {
+    const databaseStat = mailboxPreviewStat(mailboxPath);
+    if (!databaseStat)
+        throw mailboxPreviewError('target_changed');
+    assertMailboxRollbackJournalAbsent(mailboxPath);
+    const walPath = `${mailboxPath}-wal`;
+    const walStat = mailboxPreviewStat(walPath);
+    const totalBytes = databaseStat.size + (walStat?.size ?? 0n);
+    if (totalBytes > BigInt(MAILBOX_PREVIEW_MAX_TOTAL_BYTES)) {
+        throw mailboxPreviewError('target_too_large');
+    }
+    const snapshotDir = mkdtempSync(join(tmpdir(), 'evolver-mailbox-preview-'));
+    const snapshotPath = join(snapshotDir, basename(mailboxPath));
+    try {
+        chmodSync(snapshotDir, 0o700);
+        const databaseSnapshot = copyStableMailboxPreviewFile(mailboxPath, snapshotPath, databaseStat);
+        const walSnapshot = walStat
+            ? copyStableMailboxPreviewFile(walPath, `${snapshotPath}-wal`, walStat)
+            : null;
+        assertMailboxRollbackJournalAbsent(mailboxPath);
+        const currentWal = mailboxPreviewStat(walPath);
+        if ((walSnapshot === null) !== (currentWal === null)) {
+            throw mailboxPreviewError('target_changed');
+        }
+        hashStableMailboxPreviewFile(mailboxPath, databaseSnapshot);
+        if (walSnapshot)
+            hashStableMailboxPreviewFile(walPath, walSnapshot);
+        return { dir: snapshotDir, path: snapshotPath };
+    }
+    catch (error) {
+        try {
+            rmSync(snapshotDir, { recursive: true, force: true });
+        }
+        catch { /* preserve primary error */ }
+        throw error;
+    }
+}
 export const MAX_ATTEMPTS = 5;
 export const DEFAULT_IMPORT_JSONL_MAX_LINE_BYTES = 16 * 1024 * 1024;
+export const DEFAULT_IMPORT_JSONL_MAX_BYTES = 128 * 1024 * 1024;
+export const DEFAULT_IMPORT_JSONL_MAX_RECORDS = 100_000;
 const JSONL_READ_CHUNK_BYTES = 64 * 1024;
 export const MAILBOX_CLAIM_OWNER = Symbol('mailboxClaimOwner');
+export class MailboxJsonlImportError extends Error {
+    code;
+    line;
+    constructor(code, line, message) {
+        super(`Mailbox JSONL line ${line}: ${message}`);
+        this.name = 'MailboxJsonlImportError';
+        this.code = code;
+        this.line = line;
+    }
+}
 export function mailboxClaimOwner(envelope) {
     return envelope[MAILBOX_CLAIM_OWNER];
 }
@@ -97,12 +320,12 @@ function recoverImportedStatus(type, requested) {
     // with status=in_flight and leasedUntil=NULL, which SQLite will never consider expired or claimable.
     return requested === 'in_flight' ? 'pending' : requested;
 }
-function normalizeImportedEnvelope(record) {
+function normalizeImportedEnvelope(record, now = Date.now()) {
     const id = nonEmptyString(record['id']);
     const type = nonEmptyString(record['type']);
     if (!id || !type)
         return undefined;
-    const createdAt = finiteNumber(record['createdAt']) ?? finiteNumber(record['created_at']) ?? Date.now();
+    const createdAt = finiteNumber(record['createdAt']) ?? finiteNumber(record['created_at']) ?? now;
     const spec = specForType(type);
     const directionValue = record['direction'];
     const direction = directionValue === 'outbound' || directionValue === 'inbound' || directionValue === 'local'
@@ -157,49 +380,120 @@ function normalizeImportedEnvelope(record) {
         lastError: nullableStringField(record, 'lastError', 'last_error', 'error') ?? null,
     };
 }
-function forEachJsonlRecord(source, onRecord) {
-    if (typeof source === 'string' && !existsSync(source))
-        return;
-    const maxLineBytes = Number.isFinite(Number(process.env['EVOLVER_IMPORT_JSONL_MAX_LINE_BYTES']))
-        && Number(process.env['EVOLVER_IMPORT_JSONL_MAX_LINE_BYTES']) > 0
-        ? Math.floor(Number(process.env['EVOLVER_IMPORT_JSONL_MAX_LINE_BYTES']))
-        : DEFAULT_IMPORT_JSONL_MAX_LINE_BYTES;
+function positiveInteger(value, fallback) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+        for (const nested of Object.values(value))
+            deepFreeze(nested);
+        Object.freeze(value);
+    }
+    return value;
+}
+const mailboxFatalUtf8Decoder = new TextDecoder('utf-8', { fatal: true });
+function decodeMailboxImportLine(bytes, line) {
+    try {
+        return mailboxFatalUtf8Decoder.decode(bytes);
+    }
+    catch {
+        throw new MailboxJsonlImportError('invalid_utf8', line, 'invalid UTF-8');
+    }
+}
+/**
+ * Parse and normalize a V1 mailbox journal without opening or mutating a V2 mailbox.
+ * The returned batch is sealed so dry-run and apply can consume the exact same records.
+ */
+export function prepareMailboxJsonlImport(source, options = {}) {
+    if (typeof source === 'string' && !existsSync(source)) {
+        return Object.freeze({
+            records: Object.freeze([]),
+            sourceRecords: 0,
+            messageCandidates: 0,
+            uniqueMessageCandidates: 0,
+            updateCandidates: 0,
+        });
+    }
+    const maxLineBytes = positiveInteger(options.maxLineBytes ?? process.env['EVOLVER_IMPORT_JSONL_MAX_LINE_BYTES'], DEFAULT_IMPORT_JSONL_MAX_LINE_BYTES);
+    const maxRecords = positiveInteger(options.maxRecords ?? process.env['EVOLVER_IMPORT_JSONL_MAX_RECORDS'], DEFAULT_IMPORT_JSONL_MAX_RECORDS);
+    const maxBytes = positiveInteger(options.maxBytes ?? process.env['EVOLVER_IMPORT_JSONL_MAX_BYTES'], DEFAULT_IMPORT_JSONL_MAX_BYTES);
+    const now = Number.isFinite(options.now) ? Number(options.now) : Date.now();
     const buf = Buffer.allocUnsafe(JSONL_READ_CHUNK_BYTES);
+    const records = [];
+    const messageIds = new Set();
+    let sourceRecords = 0;
+    let messageCandidates = 0;
+    let updateCandidates = 0;
     let fd;
     let ownsFd = false;
     let position = 0;
     let parts = [];
     let lineBytes = 0;
-    let dropping = false;
-    const reset = () => { parts = []; lineBytes = 0; dropping = false; };
+    let lineNumber = 1;
+    let overlong = false;
+    const reset = () => { parts = []; lineBytes = 0; overlong = false; };
     const append = (segment) => {
-        if (dropping || segment.length === 0)
+        if (overlong || segment.length === 0)
             return;
         if (lineBytes + segment.length > maxLineBytes) {
             reset();
-            dropping = true;
+            overlong = true;
             return;
         }
         parts.push(Buffer.from(segment));
         lineBytes += segment.length;
     };
     const finish = () => {
-        if (dropping || lineBytes === 0) {
+        const currentLine = lineNumber;
+        lineNumber += 1;
+        if (overlong) {
+            reset();
+            throw new MailboxJsonlImportError('line_too_large', currentLine, `record exceeds ${maxLineBytes} bytes`);
+        }
+        if (lineBytes === 0) {
             reset();
             return;
         }
-        const text = Buffer.concat(parts, lineBytes).toString('utf8').trim();
+        const text = decodeMailboxImportLine(Buffer.concat(parts, lineBytes), currentLine).trim();
         reset();
         if (!text)
             return;
+        sourceRecords += 1;
+        if (sourceRecords > maxRecords) {
+            throw new MailboxJsonlImportError('too_many_records', currentLine, `journal exceeds ${maxRecords} records`);
+        }
         let record;
         try {
             record = JSON.parse(text);
         }
         catch {
-            return; /* skip corrupt JSON */
+            throw new MailboxJsonlImportError('invalid_json', currentLine, 'invalid JSON');
+        }
+        const row = asRow(record);
+        if (!row) {
+            throw new MailboxJsonlImportError('invalid_record', currentLine, 'record must be a JSON object');
         }
-        onRecord(record);
+        if (Object.prototype.hasOwnProperty.call(row, '_op')) {
+            if (row['_op'] !== 'update') {
+                throw new MailboxJsonlImportError('unsupported_operation', currentLine, 'unsupported _op value');
+            }
+            const id = nonEmptyString(row['id']);
+            const fields = asRow(row['fields']);
+            if (!id || !fields) {
+                throw new MailboxJsonlImportError('invalid_update', currentLine, 'update requires a non-empty id and object fields');
+            }
+            records.push(deepFreeze({ kind: 'update', id, fields }));
+            updateCandidates += 1;
+            return;
+        }
+        const envelope = normalizeImportedEnvelope(row, now);
+        if (!envelope) {
+            throw new MailboxJsonlImportError('invalid_message', currentLine, 'message requires a non-empty id, type, and valid direction');
+        }
+        records.push(deepFreeze({ kind: 'message', envelope }));
+        messageCandidates += 1;
+        messageIds.add(envelope.id);
     };
     try {
         if (typeof source === 'number') {
@@ -214,6 +508,9 @@ function forEachJsonlRecord(source, onRecord) {
             if (bytes <= 0)
                 break;
             position += bytes;
+            if (position > maxBytes) {
+                throw new MailboxJsonlImportError('journal_too_large', lineNumber, `journal exceeds ${maxBytes} bytes`);
+            }
             let start = 0;
             for (let i = 0; i < bytes; i += 1) {
                 if (buf[i] !== 0x0a)
@@ -231,6 +528,13 @@ function forEachJsonlRecord(source, onRecord) {
         if (ownsFd && fd !== undefined)
             closeSync(fd);
     }
+    return Object.freeze({
+        records: Object.freeze(records),
+        sourceRecords,
+        messageCandidates,
+        uniqueMessageCandidates: messageIds.size,
+        updateCandidates,
+    });
 }
 function rowToEnvelope(r) {
     return {
@@ -249,6 +553,172 @@ function rowToEnvelope(r) {
         lastError: r['lastError'] ?? null,
     };
 }
+function applyImportedV1UpdateToEnvelope(current, fields) {
+    const requestedStatus = importedStatus(fields['status']) ?? current.status;
+    const status = recoverImportedStatus(current.type, requestedStatus);
+    const attempts = Math.max(0, Math.floor(finiteNumber(fields['attempts']) ?? finiteNumber(fields['retry_count']) ?? current.attempts));
+    const importedNextRetryAt = timestampField(fields, 'nextRetryAt', 'next_retry_at');
+    const nextRetryAt = importedNextRetryAt === undefined ? current.nextRetryAt : importedNextRetryAt;
+    const importedTtlAt = timestampField(fields, 'ttlAt', 'expires_at');
+    const ttlAt = importedTtlAt === undefined ? current.ttlAt : importedTtlAt;
+    const updatedAt = finiteNumber(fields['updatedAt'])
+        ?? finiteNumber(fields['updated_at'])
+        ?? finiteNumber(fields['synced_at'])
+        ?? current.updatedAt;
+    const payload = Object.prototype.hasOwnProperty.call(fields, 'payload')
+        ? sanitizePayload(fields['payload'])
+        : current.payload;
+    const priority = Object.prototype.hasOwnProperty.call(fields, 'priority')
+        ? normalizePriority(fields['priority'])
+        : current.priority;
+    const importedLastError = nullableStringField(fields, 'lastError', 'last_error', 'error');
+    const lastError = importedLastError === undefined ? current.lastError : importedLastError;
+    return {
+        ...current,
+        status,
+        payload,
+        priority,
+        attempts,
+        nextRetryAt,
+        ttlAt,
+        updatedAt,
+        lastError,
+    };
+}
+function buildMailboxPreparedImportPlan(batch, getById, getBaseline) {
+    const eligibleIds = new Set();
+    const insertedIds = new Set();
+    const managedIds = new Set();
+    const protectedIds = new Set();
+    const updatedIds = new Set();
+    const finalById = new Map();
+    for (const record of batch.records) {
+        if (record.kind === 'update') {
+            if (!eligibleIds.has(record.id))
+                continue;
+            const current = finalById.get(record.id);
+            if (!current)
+                continue;
+            const updated = applyImportedV1UpdateToEnvelope(current, record.fields);
+            if (JSON.stringify(updated) !== JSON.stringify(current))
+                updatedIds.add(record.id);
+            finalById.set(record.id, updated);
+            continue;
+        }
+        const envelope = { ...record.envelope };
+        if (eligibleIds.has(envelope.id))
+            continue;
+        let current = finalById.get(envelope.id);
+        if (!current) {
+            current = getById(envelope.id);
+            if (current)
+                finalById.set(envelope.id, current);
+        }
+        if (!current) {
+            finalById.set(envelope.id, envelope);
+            insertedIds.add(envelope.id);
+            eligibleIds.add(envelope.id);
+            protectedIds.delete(envelope.id);
+            continue;
+        }
+        const baseline = getBaseline(envelope.id);
+        if (baseline !== undefined && JSON.stringify(current) === baseline) {
+            eligibleIds.add(envelope.id);
+            managedIds.add(envelope.id);
+            protectedIds.delete(envelope.id);
+        }
+        else {
+            protectedIds.add(envelope.id);
+        }
+    }
+    return {
+        preview: Object.freeze({
+            sourceRecords: batch.sourceRecords,
+            messageCandidates: batch.messageCandidates,
+            uniqueMessageCandidates: batch.uniqueMessageCandidates,
+            updateCandidates: batch.updateCandidates,
+            insertedMessages: insertedIds.size,
+            updatedMessages: updatedIds.size,
+            managedMessages: managedIds.size,
+            protectedMessages: protectedIds.size,
+        }),
+        finalById,
+        insertedIds,
+        managedIds,
+        eligibleIds,
+    };
+}
+function previewPreparedMailboxDatabase(batch, database) {
+    try {
+        database.exec('BEGIN');
+        const hasMessages = database.prepare("SELECT 1 present FROM sqlite_master WHERE type='table' AND name='messages'").get() !== undefined;
+        const hasImportState = database.prepare("SELECT 1 present FROM sqlite_master WHERE type='table' AND name='v1_import_state'").get() !== undefined;
+        const readMessage = hasMessages
+            ? database.prepare('SELECT * FROM messages WHERE id=?')
+            : undefined;
+        const readBaseline = hasImportState
+            ? database.prepare('SELECT snapshot FROM v1_import_state WHERE id=?')
+            : undefined;
+        const plan = buildMailboxPreparedImportPlan(batch, (id) => {
+            const row = readMessage?.get(id);
+            return row ? rowToEnvelope(row) : undefined;
+        }, (id) => {
+            const snapshot = readBaseline?.get(id)?.['snapshot'];
+            return typeof snapshot === 'string' ? snapshot : undefined;
+        });
+        database.exec('COMMIT');
+        return plan.preview;
+    }
+    catch (error) {
+        try {
+            database.exec('ROLLBACK');
+        }
+        catch {
+            // Preserve the primary preview error.
+        }
+        throw error;
+    }
+}
+/** Preview a prepared import against an optional existing mailbox without creating or migrating it. */
+export function previewPreparedMailboxImport(batch, mailboxPath) {
+    if (!mailboxPath) {
+        return buildMailboxPreparedImportPlan(batch, () => undefined, () => undefined).preview;
+    }
+    const databaseStat = mailboxPreviewStat(mailboxPath);
+    if (!databaseStat) {
+        assertMailboxPreviewTargetAbsent(mailboxPath);
+        return buildMailboxPreparedImportPlan(batch, () => undefined, () => undefined).preview;
+    }
+    const snapshot = stableMailboxPreviewCopy(mailboxPath);
+    let database;
+    let preview;
+    let operationError;
+    try {
+        database = openSqliteDatabase(snapshot.path, { readOnly: true });
+        preview = previewPreparedMailboxDatabase(batch, database);
+    }
+    catch (error) {
+        operationError = error;
+    }
+    try {
+        database?.close();
+    }
+    catch (error) {
+        operationError ??= error;
+    }
+    let cleanupError;
+    try {
+        rmSync(snapshot.dir, { recursive: true, force: true });
+    }
+    catch (error) {
+        cleanupError = error;
+    }
+    if (operationError !== undefined)
+        throw operationError;
+    if (cleanupError !== undefined)
+        throw mailboxPreviewError('cleanup_failed');
+    return preview;
+}
 function ensureMessageColumn(db, name, definition) {
     const columns = db.prepare('PRAGMA table_info(messages)').all();
     if (!columns.some((column) => column['name'] === name)) {
@@ -671,79 +1141,74 @@ export class MailboxStore {
         const row = this.db.prepare('SELECT workerId FROM messages WHERE id=?').get(id);
         return typeof row?.['workerId'] === 'string' ? row['workerId'] : undefined;
     }
-    /** v1 messages.jsonl → sqlite 迁移(幂等可重入). */
-    importJsonl(source) {
-        let n = 0;
-        const eligibleIds = new Set();
+    /** Build the target-aware plan shared by preview and apply. */
+    buildPreparedImportPlan(batch) {
         const readImportState = this.db.prepare('SELECT snapshot FROM v1_import_state WHERE id=?');
-        const writeImportState = this.db.prepare('INSERT INTO v1_import_state (id,snapshot) VALUES (?,?) ON CONFLICT(id) DO UPDATE SET snapshot=excluded.snapshot');
+        return buildMailboxPreparedImportPlan(batch, (id) => this.getById(id), (id) => {
+            const snapshot = readImportState.get(id)?.['snapshot'];
+            return typeof snapshot === 'string' ? snapshot : undefined;
+        });
+    }
+    /** Preview the exact import result against the current mailbox snapshot without writing to it. */
+    previewPreparedImport(batch) {
+        this.db.exec('BEGIN');
+        try {
+            const preview = this.buildPreparedImportPlan(batch).preview;
+            this.db.exec('COMMIT');
+            return preview;
+        }
+        catch (error) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch {
+                // Preserve the primary preview error.
+            }
+            throw error;
+        }
+    }
+    writeImportedEnvelopeFields(current) {
+        this.db.prepare(`UPDATE messages
+      SET status=?, payload=?, priority=?, attempts=?, nextRetryAt=?, ttlAt=?, updatedAt=?, lastError=?
+      WHERE id=?`).run(current.status, JSON.stringify(current.payload), current.priority, current.attempts, current.nextRetryAt, current.ttlAt, current.updatedAt, current.lastError, current.id);
+    }
+    /** Apply a parsed batch; planning and writes share one transaction and one normalized journal. */
+    importPrepared(batch) {
         this.db.exec('BEGIN IMMEDIATE');
         try {
-            forEachJsonlRecord(source, (record) => {
-                const row = asRow(record);
-                if (!row)
-                    return;
-                if (row['_op'] === 'update') {
-                    const id = nonEmptyString(row['id']);
-                    const fields = asRow(row['fields']);
-                    if (id && fields && eligibleIds.has(id))
-                        this.applyImportedV1Update(id, fields);
-                    return;
+            const plan = this.buildPreparedImportPlan(batch);
+            for (const id of plan.insertedIds) {
+                const envelope = plan.finalById.get(id);
+                if (!envelope || !this.send(envelope).stored) {
+                    throw new Error(`Mailbox import plan became stale for ${id}`);
                 }
-                const envelope = normalizeImportedEnvelope(row);
-                if (!envelope)
-                    return;
-                const inserted = this.send(envelope).stored;
-                if (inserted) {
-                    n += 1;
-                    eligibleIds.add(envelope.id);
-                    return;
-                }
-                const baseline = readImportState.get(envelope.id)?.['snapshot'];
-                const current = this.getById(envelope.id);
-                if (typeof baseline === 'string' && current && JSON.stringify(current) === baseline) {
-                    eligibleIds.add(envelope.id);
-                }
-            });
-            for (const id of eligibleIds) {
-                const current = this.getById(id);
-                if (current)
-                    writeImportState.run(id, JSON.stringify(current));
+            }
+            for (const id of plan.managedIds) {
+                const envelope = plan.finalById.get(id);
+                if (envelope)
+                    this.writeImportedEnvelopeFields(envelope);
+            }
+            const writeImportState = this.db.prepare('INSERT INTO v1_import_state (id,snapshot) VALUES (?,?) ON CONFLICT(id) DO UPDATE SET snapshot=excluded.snapshot');
+            for (const id of plan.eligibleIds) {
+                const envelope = plan.finalById.get(id);
+                if (envelope)
+                    writeImportState.run(id, JSON.stringify(envelope));
             }
             this.db.exec('COMMIT');
-            return n;
+            return plan.preview.insertedMessages;
         }
         catch (error) {
-            this.db.exec('ROLLBACK');
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch {
+                // Preserve the primary import error.
+            }
             throw error;
         }
     }
-    applyImportedV1Update(id, fields) {
-        const current = this.getById(id);
-        if (!current)
-            return;
-        const requestedStatus = importedStatus(fields['status']) ?? current.status;
-        const status = recoverImportedStatus(current.type, requestedStatus);
-        const attempts = Math.max(0, Math.floor(finiteNumber(fields['attempts']) ?? finiteNumber(fields['retry_count']) ?? current.attempts));
-        const importedNextRetryAt = timestampField(fields, 'nextRetryAt', 'next_retry_at');
-        const nextRetryAt = importedNextRetryAt === undefined ? current.nextRetryAt : importedNextRetryAt;
-        const importedTtlAt = timestampField(fields, 'ttlAt', 'expires_at');
-        const ttlAt = importedTtlAt === undefined ? current.ttlAt : importedTtlAt;
-        const updatedAt = finiteNumber(fields['updatedAt'])
-            ?? finiteNumber(fields['updated_at'])
-            ?? finiteNumber(fields['synced_at'])
-            ?? current.updatedAt;
-        const payload = Object.prototype.hasOwnProperty.call(fields, 'payload')
-            ? sanitizePayload(fields['payload'])
-            : current.payload;
-        const priority = Object.prototype.hasOwnProperty.call(fields, 'priority')
-            ? normalizePriority(fields['priority'])
-            : current.priority;
-        const importedLastError = nullableStringField(fields, 'lastError', 'last_error', 'error');
-        const lastError = importedLastError === undefined ? current.lastError : importedLastError;
-        this.db.prepare(`UPDATE messages
-      SET status=?, payload=?, priority=?, attempts=?, nextRetryAt=?, ttlAt=?, updatedAt=?, lastError=?
-      WHERE id=?`).run(status, JSON.stringify(payload), priority, attempts, nextRetryAt, ttlAt, updatedAt, lastError, id);
+    importJsonl(source) {
+        return this.importPrepared(prepareMailboxJsonlImport(source));
     }
     close() { this.db.close(); }
 }