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

package/dist/mailbox/store.js

@@ -2,29 +2,163 @@ import { mkdirSync, existsSync, openSync, readSync, closeSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { createRequire } from 'node:module';
 import { ulid as makeUlid } from 'ulid';
-import { createEnvelope } from './envelope.js';
+import { createEnvelope, ENVELOPE_SCHEMA_VERSION, normalizePriority, sanitizePayload, specForType, } from './envelope.js';
 const nodeRequire = createRequire(import.meta.url);
 function isBunRuntime() {
     return typeof process.versions === 'object' && typeof process.versions.bun === 'string';
 }
-function openSqliteDatabase(path) {
+function openSqliteDatabase(path, options = {}) {
     if (isBunRuntime()) {
         const { Database } = nodeRequire('bun:sqlite');
-        return new Database(path);
+        return options.readOnly ? new Database(path, { readonly: true }) : new Database(path);
     }
     // node:sqlite is exposed only as `node:sqlite` (no bare `sqlite` alias). Load it through createRequire so
     // bundlers do not statically strip the prefix and break Vitest/Vite or Bun standalone builds.
     const { DatabaseSync } = nodeRequire('node:sqlite');
-    return new DatabaseSync(path);
+    return options.readOnly ? new DatabaseSync(path, { readOnly: true }) : new DatabaseSync(path);
 }
 export const MAX_ATTEMPTS = 5;
 export const DEFAULT_IMPORT_JSONL_MAX_LINE_BYTES = 16 * 1024 * 1024;
 const JSONL_READ_CHUNK_BYTES = 64 * 1024;
+export const MAILBOX_CLAIM_OWNER = Symbol('mailboxClaimOwner');
+export function mailboxClaimOwner(envelope) {
+    return envelope[MAILBOX_CLAIM_OWNER];
+}
 export function expBackoffMs(attempt) {
     return Math.min(4000 * 2 ** (attempt - 1), 5 * 60 * 1000); // 4s→8s→…→5min
 }
-function forEachJsonlRecord(path, onRecord) {
-    if (!existsSync(path))
+function asRow(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+/** Read one mailbox state value without creating, migrating, or taking write ownership of the database. */
+export function readMailboxState(path, key) {
+    const database = openSqliteDatabase(path, { readOnly: true });
+    try {
+        const row = database.prepare('SELECT v FROM kv WHERE k = ?').get(key);
+        return typeof row?.['v'] === 'string' ? row['v'] : undefined;
+    }
+    finally {
+        database.close();
+    }
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function finiteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function nullableTimestamp(value) {
+    if (value === null)
+        return null;
+    return finiteNumber(value);
+}
+function timestampField(record, ...keys) {
+    for (const key of keys) {
+        if (Object.prototype.hasOwnProperty.call(record, key))
+            return nullableTimestamp(record[key]);
+    }
+    return undefined;
+}
+function nullableStringField(record, ...keys) {
+    for (const key of keys) {
+        if (!Object.prototype.hasOwnProperty.call(record, key))
+            continue;
+        const value = record[key];
+        if (value === null)
+            return null;
+        if (typeof value === 'string')
+            return value;
+        return undefined;
+    }
+    return undefined;
+}
+function importedStatus(value) {
+    switch (value) {
+        case 'pending':
+        case 'in_flight':
+        case 'done':
+        case 'failed':
+        case 'expired':
+            return value;
+        case 'synced':
+        case 'delivered':
+            return 'done';
+        case 'rejected':
+            return 'failed';
+        default:
+            return undefined;
+    }
+}
+function recoverImportedStatus(type, requested) {
+    if (!specForType(type)) {
+        return requested === 'pending' || requested === 'in_flight' ? 'failed' : requested;
+    }
+    // A V1 worker and its lease cannot survive migration. Requeue in-flight work instead of creating a V2 row
+    // with status=in_flight and leasedUntil=NULL, which SQLite will never consider expired or claimable.
+    return requested === 'in_flight' ? 'pending' : requested;
+}
+function normalizeImportedEnvelope(record) {
+    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 spec = specForType(type);
+    const directionValue = record['direction'];
+    const direction = directionValue === 'outbound' || directionValue === 'inbound' || directionValue === 'local'
+        ? directionValue
+        : spec?.direction;
+    if (!direction)
+        return undefined;
+    const handlerValue = record['handler'];
+    const handler = handlerValue === 'core' || handlerValue === 'proxy' || handlerValue === 'agent'
+        ? handlerValue
+        : spec?.handler ?? (direction === 'outbound' ? 'proxy' : 'agent');
+    const originalStatus = importedStatus(record['status']) ?? 'pending';
+    // Preserve unknown V1 types for audit without dispatching a contract that V2 cannot handle.
+    const status = recoverImportedStatus(type, originalStatus);
+    // V1 `channel` names a transport (normally `evomap-hub`); V2 runtimeNamespace is an isolation boundary.
+    const runtimeNamespace = nonEmptyString(record['runtimeNamespace']) ?? 'default';
+    const correlationId = nonEmptyString(record['correlationId'])
+        ?? nonEmptyString(record['correlation_id'])
+        ?? nonEmptyString(record['ref_id'])
+        ?? id;
+    const attempts = Math.max(0, Math.floor(finiteNumber(record['attempts']) ?? finiteNumber(record['retry_count']) ?? 0));
+    const importedTtlAt = timestampField(record, 'ttlAt', 'expires_at');
+    const ttlAt = importedTtlAt === undefined
+        ? (spec?.ttlClass === 'control' ? createdAt + 60 * 60 * 1000 : createdAt + 7 * 24 * 60 * 60 * 1000)
+        : importedTtlAt;
+    const updatedAt = finiteNumber(record['updatedAt'])
+        ?? finiteNumber(record['updated_at'])
+        ?? finiteNumber(record['synced_at'])
+        ?? createdAt;
+    return {
+        id,
+        type,
+        direction,
+        status,
+        handler,
+        payload: sanitizePayload(record['payload'] ?? {}),
+        correlationId,
+        replyTo: nonEmptyString(record['replyTo']) ?? nonEmptyString(record['reply_to']) ?? null,
+        receiptId: nonEmptyString(record['receiptId']) ?? nonEmptyString(record['receipt_id']) ?? id,
+        idempotencyKey: nonEmptyString(record['idempotencyKey']) ?? nonEmptyString(record['idempotency_key']) ?? id,
+        sourceAgent: nonEmptyString(record['sourceAgent']) ?? nonEmptyString(record['source_agent']) ?? '',
+        targetAgent: nonEmptyString(record['targetAgent']) ?? nonEmptyString(record['target_agent']) ?? '',
+        runtimeNamespace,
+        priority: normalizePriority(record['priority']),
+        attempts,
+        nextRetryAt: timestampField(record, 'nextRetryAt', 'next_retry_at') ?? null,
+        ttlAt,
+        createdAt,
+        updatedAt,
+        schemaVersion: nonEmptyString(record['schemaVersion']) ?? ENVELOPE_SCHEMA_VERSION,
+        feedsMaterial: typeof record['feedsMaterial'] === 'boolean' ? record['feedsMaterial'] : spec?.feedsMaterial ?? false,
+        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
@@ -32,6 +166,8 @@ function forEachJsonlRecord(path, onRecord) {
         : DEFAULT_IMPORT_JSONL_MAX_LINE_BYTES;
     const buf = Buffer.allocUnsafe(JSONL_READ_CHUNK_BYTES);
     let fd;
+    let ownsFd = false;
+    let position = 0;
     let parts = [];
     let lineBytes = 0;
     let dropping = false;
@@ -56,17 +192,28 @@ function forEachJsonlRecord(path, onRecord) {
         reset();
         if (!text)
             return;
+        let record;
         try {
-            onRecord(JSON.parse(text));
+            record = JSON.parse(text);
         }
-        catch { /* skip corrupt rows */ }
+        catch {
+            return; /* skip corrupt JSON */
+        }
+        onRecord(record);
     };
     try {
-        fd = openSync(path, 'r');
+        if (typeof source === 'number') {
+            fd = source;
+        }
+        else {
+            fd = openSync(source, 'r');
+            ownsFd = true;
+        }
         for (;;) {
-            const bytes = readSync(fd, buf, 0, buf.length, null);
+            const bytes = readSync(fd, buf, 0, buf.length, position);
             if (bytes <= 0)
                 break;
+            position += bytes;
             let start = 0;
             for (let i = 0; i < bytes; i += 1) {
                 if (buf[i] !== 0x0a)
@@ -81,7 +228,7 @@ function forEachJsonlRecord(path, onRecord) {
         finish();
     }
     finally {
-        if (fd !== undefined)
+        if (ownsFd && fd !== undefined)
             closeSync(fd);
     }
 }
@@ -94,12 +241,20 @@ function rowToEnvelope(r) {
         receiptId: r['receiptId'], idempotencyKey: r['idempotencyKey'],
         sourceAgent: r['sourceAgent'], targetAgent: r['targetAgent'],
         runtimeNamespace: r['runtimeNamespace'],
+        priority: normalizePriority(r['priority']),
         attempts: r['attempts'], nextRetryAt: r['nextRetryAt'] ?? null,
         ttlAt: r['ttlAt'] ?? null,
         createdAt: r['createdAt'], updatedAt: r['updatedAt'],
         schemaVersion: r['schemaVersion'], feedsMaterial: Boolean(r['feedsMaterial']),
+        lastError: r['lastError'] ?? null,
     };
 }
+function ensureMessageColumn(db, name, definition) {
+    const columns = db.prepare('PRAGMA table_info(messages)').all();
+    if (!columns.some((column) => column['name'] === name)) {
+        db.exec(`ALTER TABLE messages ADD COLUMN ${definition}`);
+    }
+}
 /** mailbox sqlite 引擎 (WAL + busy_timeout). 状态机 pending→in_flight→done/failed/expired + 租约 + 重试/DLQ. */
 export class MailboxStore {
     db;
@@ -115,14 +270,19 @@ export class MailboxStore {
         this.db.exec(`CREATE TABLE IF NOT EXISTS messages (
       id TEXT PRIMARY KEY, type TEXT, direction TEXT, status TEXT, handler TEXT,
       payload TEXT, correlationId TEXT, replyTo TEXT, receiptId TEXT, idempotencyKey TEXT,
-      sourceAgent TEXT, targetAgent TEXT, runtimeNamespace TEXT,
+      sourceAgent TEXT, targetAgent TEXT, runtimeNamespace TEXT, priority TEXT NOT NULL DEFAULT 'normal',
       attempts INTEGER, nextRetryAt INTEGER, ttlAt INTEGER, createdAt INTEGER, updatedAt INTEGER,
-      schemaVersion TEXT, feedsMaterial INTEGER, dlq INTEGER DEFAULT 0, leasedUntil INTEGER, workerId TEXT, lastError TEXT)`);
+      schemaVersion TEXT, feedsMaterial INTEGER, dlq INTEGER DEFAULT 0, leasedUntil INTEGER, workerId TEXT,
+      lastError TEXT, claimCheckpoint TEXT)`);
+        ensureMessageColumn(this.db, 'priority', "priority TEXT NOT NULL DEFAULT 'normal'");
+        ensureMessageColumn(this.db, 'lastError', 'lastError TEXT');
+        ensureMessageColumn(this.db, 'claimCheckpoint', 'claimCheckpoint TEXT');
         this.db.exec('CREATE INDEX IF NOT EXISTS idx_status ON messages(status, handler)');
         this.db.exec('CREATE INDEX IF NOT EXISTS idx_corr ON messages(correlationId)');
         this.db.exec('CREATE INDEX IF NOT EXISTS idx_message_view ON messages(runtimeNamespace,type,direction,status,createdAt)');
         this.db.exec('CREATE TABLE IF NOT EXISTS idempotency (key TEXT PRIMARY KEY, result TEXT, at INTEGER)');
         this.db.exec('CREATE TABLE IF NOT EXISTS kv (k TEXT PRIMARY KEY, v TEXT)');
+        this.db.exec('CREATE TABLE IF NOT EXISTS v1_import_state (id TEXT PRIMARY KEY, snapshot TEXT NOT NULL)');
     }
     /** 通用 KV 状态(M6: sync 游标 inbound_cursor / lifecycle reauth 退避 / node_id 等). */
     getState(key) {
@@ -135,8 +295,8 @@ export class MailboxStore {
     /** 投递; 同 id 幂等(OR IGNORE). 返回 receiptId. */
     send(e) {
         const r = this.db.prepare(`INSERT OR IGNORE INTO messages
-      (id,type,direction,status,handler,payload,correlationId,replyTo,receiptId,idempotencyKey,sourceAgent,targetAgent,runtimeNamespace,attempts,nextRetryAt,ttlAt,createdAt,updatedAt,schemaVersion,feedsMaterial,dlq)
-      VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,0)`).run(e.id, e.type, e.direction, e.status, e.handler, JSON.stringify(e.payload), e.correlationId, e.replyTo, e.receiptId, e.idempotencyKey, e.sourceAgent, e.targetAgent, e.runtimeNamespace, e.attempts, e.nextRetryAt, e.ttlAt, e.createdAt, e.updatedAt, e.schemaVersion, e.feedsMaterial ? 1 : 0);
+      (id,type,direction,status,handler,payload,correlationId,replyTo,receiptId,idempotencyKey,sourceAgent,targetAgent,runtimeNamespace,priority,attempts,nextRetryAt,ttlAt,createdAt,updatedAt,schemaVersion,feedsMaterial,lastError,dlq)
+      VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,0)`).run(e.id, e.type, e.direction, e.status, e.handler, JSON.stringify(e.payload), e.correlationId, e.replyTo, e.receiptId, e.idempotencyKey, e.sourceAgent, e.targetAgent, e.runtimeNamespace, e.priority, e.attempts, e.nextRetryAt, e.ttlAt, e.createdAt, e.updatedAt, e.schemaVersion, e.feedsMaterial ? 1 : 0, e.lastError);
         return { receiptId: e.id, stored: Number(r.changes) > 0 };
     }
     getById(id) {
@@ -253,13 +413,17 @@ export class MailboxStore {
             const rows = this.db.prepare(`SELECT * FROM messages WHERE handler=? AND dlq=0
          AND (status='pending' OR (status='in_flight' AND leasedUntil < ?))
          AND (nextRetryAt IS NULL OR nextRetryAt <= ?)${nsClause}
-         ORDER BY createdAt LIMIT ?`).all(handler, now, now, ...nsArgs, limit);
+         ORDER BY CASE priority WHEN 'high' THEN 0 WHEN 'low' THEN 2 ELSE 1 END, createdAt LIMIT ?`).all(handler, now, now, ...nsArgs, limit);
             const workerId = makeUlid();
             const upd = this.db.prepare(`UPDATE messages SET status='in_flight', leasedUntil=?, workerId=?, updatedAt=? WHERE id=?`);
             for (const r of rows)
                 upd.run(now + leaseMs, workerId, now, r['id']);
             this.db.exec('COMMIT');
-            return rows.map((r) => ({ ...rowToEnvelope(r), status: 'in_flight' }));
+            return rows.map((r) => ({
+                ...rowToEnvelope(r),
+                status: 'in_flight',
+                [MAILBOX_CLAIM_OWNER]: workerId,
+            }));
         }
         catch (e) {
             this.db.exec('ROLLBACK');
@@ -267,7 +431,7 @@ export class MailboxStore {
         }
     }
     complete(id, now) {
-        this.db.prepare(`UPDATE messages SET status='done', leasedUntil=NULL, workerId=NULL, updatedAt=? WHERE id=?`).run(now, id);
+        this.db.prepare(`UPDATE messages SET status='done', dlq=0, lastError=NULL, leasedUntil=NULL, workerId=NULL, updatedAt=? WHERE id=?`).run(now, id);
     }
     /** 失败: attempts<N→退避回 pending; ≥N→DLQ(不自动丢). */
     fail(id, err, now, maxAttempts = MAX_ATTEMPTS) {
@@ -289,9 +453,101 @@ export class MailboxStore {
         this.db.prepare(`UPDATE messages SET status='pending', nextRetryAt=?, lastError=?, leasedUntil=NULL, workerId=NULL, updatedAt=? WHERE id=?`)
             .run(now + delay, err, now, id);
     }
+    deferUnlessProcessed(id, processedKey, err, now, retryAfterMs) {
+        return this.transitionUnlessProcessed(id, [processedKey], (current) => current.status === 'pending', () => this.defer(id, err, now, retryAfterMs));
+    }
+    failUnlessProcessed(id, processedKey, err, now, maxAttempts = 5) {
+        return this.transitionUnlessProcessed(id, [processedKey], (current) => current.status === 'pending', () => this.fail(id, err, now, maxAttempts));
+    }
+    completeClaimed(id, now, claimOwner) {
+        return this.transitionUnlessProcessed(id, [], (current) => current.status === 'in_flight', () => this.complete(id, now), claimOwner);
+    }
+    /** Atomically complete the current worker's lease and persist its idempotency result. */
+    completeClaimedAndMarkProcessed(id, processedKey, result, now, claimOwner) {
+        return this.transitionUnlessProcessed(id, [], (current) => current.status === 'in_flight', () => {
+            this.markProcessed(processedKey, result, now);
+            this.complete(id, now);
+        }, claimOwner);
+    }
+    renewClaim(id, now, leaseMs, claimOwner) {
+        const result = this.db.prepare(`UPDATE messages SET leasedUntil=?, updatedAt=?
+      WHERE id=? AND status='in_flight' AND workerId=?`).run(now + leaseMs, now, id, claimOwner);
+        return result.changes === 1;
+    }
+    setClaimedCheckpoint(id, checkpoint, now, claimOwner) {
+        const encoded = JSON.stringify(checkpoint);
+        return this.transitionUnlessProcessed(id, [], (current) => current.status === 'in_flight', () => {
+            this.db.prepare('UPDATE messages SET claimCheckpoint=?, updatedAt=? WHERE id=?').run(encoded, now, id);
+        }, claimOwner);
+    }
+    getClaimedCheckpoint(id) {
+        const row = this.db.prepare('SELECT claimCheckpoint FROM messages WHERE id=?').get(id);
+        const encoded = row?.['claimCheckpoint'];
+        if (typeof encoded !== 'string')
+            return undefined;
+        try {
+            return JSON.parse(encoded);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    deferClaimed(id, err, now, retryAfterMs, claimOwner) {
+        return this.transitionUnlessProcessed(id, [], (current) => current.status === 'in_flight', () => this.defer(id, err, now, retryAfterMs), claimOwner);
+    }
+    failClaimed(id, err, now, claimOwner, maxAttempts = MAX_ATTEMPTS) {
+        return this.transitionUnlessProcessed(id, [], (current) => current.status === 'in_flight', () => this.fail(id, err, now, maxAttempts), claimOwner);
+    }
+    /** Transition only the row held by the current worker, unless a concurrent success marker already exists. */
+    deferClaimedUnlessProcessed(id, processedKey, err, now, retryAfterMs, claimOwner) {
+        return this.transitionUnlessProcessed(id, [processedKey], (current) => current.status === 'in_flight', () => this.defer(id, err, now, retryAfterMs), claimOwner);
+    }
+    /** Transition only the row held by the current worker, unless a concurrent success marker already exists. */
+    failClaimedUnlessProcessed(id, processedKey, err, now, claimOwner, maxAttempts = MAX_ATTEMPTS) {
+        return this.transitionUnlessProcessed(id, [processedKey], (current) => current.status === 'in_flight', () => this.fail(id, err, now, maxAttempts), claimOwner);
+    }
+    /** Atomically fail a non-leased intent and persist the replayable terminal result. */
+    failAndMarkProcessedUnlessProcessed(id, blockingProcessedKeys, resultKey, result, err, now, maxAttempts = MAX_ATTEMPTS) {
+        return this.transitionUnlessProcessed(id, blockingProcessedKeys, (current) => current.status === 'pending', () => {
+            this.fail(id, err, now, maxAttempts);
+            this.markProcessed(resultKey, result, now);
+        });
+    }
+    /** Atomically fail the current worker's leased intent and persist the replayable terminal result. */
+    failClaimedAndMarkProcessedUnlessProcessed(id, blockingProcessedKeys, resultKey, result, err, now, claimOwner, maxAttempts = MAX_ATTEMPTS) {
+        return this.transitionUnlessProcessed(id, blockingProcessedKeys, (current) => current.status === 'in_flight', () => {
+            this.fail(id, err, now, maxAttempts);
+            this.markProcessed(resultKey, result, now);
+        }, claimOwner);
+    }
+    transitionUnlessProcessed(id, processedKeys, isEligible, transition, expectedClaimOwner) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const current = this.getById(id);
+            if (processedKeys.some((key) => this.isProcessed(key))
+                || !current
+                || !isEligible(current)
+                || (expectedClaimOwner !== undefined && this.messageClaimOwner(id) !== expectedClaimOwner)) {
+                this.db.exec('COMMIT');
+                return false;
+            }
+            transition();
+            this.db.exec('COMMIT');
+            return true;
+        }
+        catch (error) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch {
+                // Preserve the primary transaction error.
+            }
+            throw error;
+        }
+    }
     /** DLQ 重放(人工/agent 显式, 不自动丢). */
     replayDlq(id, now) {
-        this.db.prepare(`UPDATE messages SET status='pending', dlq=0, attempts=0, nextRetryAt=NULL, leasedUntil=NULL, updatedAt=? WHERE id=?`).run(now, id);
+        this.db.prepare(`UPDATE messages SET status='pending', dlq=0, attempts=0, nextRetryAt=NULL, lastError=NULL, leasedUntil=NULL, updatedAt=? WHERE id=?`).run(now, id);
     }
     dlq() { return this.db.prepare('SELECT * FROM messages WHERE dlq=1').all().map(rowToEnvelope); }
     /** TTL 扫描: ttlAt 过期且未 done/dlq → expired. */
@@ -326,13 +582,15 @@ export class MailboxStore {
     }
     /** M2-5 轻量状态视图(运维/IPC 查询用). */
     getStatus(id) {
-        const r = this.db.prepare('SELECT id,type,status,attempts,nextRetryAt,ttlAt,dlq FROM messages WHERE id=?').get(id);
+        const r = this.db.prepare('SELECT id,type,status,priority,attempts,nextRetryAt,ttlAt,dlq,lastError FROM messages WHERE id=?').get(id);
         if (!r)
             return undefined;
         return {
             id: r['id'], type: r['type'], status: r['status'],
+            priority: normalizePriority(r['priority']),
             attempts: Number(r['attempts']), nextRetryAt: r['nextRetryAt'] ?? null,
             ttlAt: r['ttlAt'] ?? null, dlq: Number(r['dlq']) === 1,
+            lastError: r['lastError'] ?? null,
         };
     }
     /** 幂等(A13): 副作用 handler 用 idempotencyKey 去重; 命中返缓存不重跑. */
@@ -344,17 +602,148 @@ export class MailboxStore {
     markProcessed(key, result, now) {
         this.db.prepare('INSERT OR IGNORE INTO idempotency (key,result,at) VALUES (?,?,?)').run(key, JSON.stringify(result ?? null), now);
     }
+    replaceProcessed(key, result, now) {
+        this.db.prepare(`INSERT INTO idempotency (key,result,at) VALUES (?,?,?)
+      ON CONFLICT(key) DO UPDATE SET result=excluded.result, at=excluded.at`).run(key, JSON.stringify(result ?? null), now);
+    }
+    /** Persist a monotonic outcome and its lightweight concurrency marker in one SQLite transaction. */
+    replaceProcessedWithMarker(key, result, markerKey, markerResult, now) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            this.replaceProcessed(key, result, now);
+            this.replaceProcessed(markerKey, markerResult, now);
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch {
+                // Preserve the primary transaction error.
+            }
+            throw error;
+        }
+    }
+    /** Backfill a concurrency marker only when the durable source result still satisfies the caller's predicate. */
+    markProcessedIf(sourceKey, markerKey, markerResult, now, matches) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const sourceResult = this.getProcessed(sourceKey);
+            if (sourceResult === undefined || !matches(sourceResult)) {
+                this.db.exec('COMMIT');
+                return false;
+            }
+            this.markProcessed(markerKey, markerResult, now);
+            this.db.exec('COMMIT');
+            return true;
+        }
+        catch (error) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch {
+                // Preserve the primary transaction error.
+            }
+            throw error;
+        }
+    }
+    deleteProcessed(keys) {
+        if (keys.length === 0)
+            return;
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const remove = this.db.prepare('DELETE FROM idempotency WHERE key=?');
+            for (const key of keys)
+                remove.run(key);
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch {
+                // Preserve the primary transaction error.
+            }
+            throw error;
+        }
+    }
+    messageClaimOwner(id) {
+        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(path) {
+    importJsonl(source) {
         let n = 0;
-        forEachJsonlRecord(path, (record) => {
-            try {
-                if (this.send(record).stored)
+        const eligibleIds = new Set();
+        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');
+        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 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));
             }
-            catch { /* skip */ }
-        });
-        return n;
+            this.db.exec('COMMIT');
+            return n;
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            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);
     }
     close() { this.db.close(); }
 }

package/dist/signals/curriculum.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Progressive curriculum signals, adapted from V1's curriculum producer.
+ *
+ * V2 keeps the policy pure and derives its history from the append-only root event log. This avoids V1's
+ * separate mutable curriculum_state.json sidecar while preserving the behavior that matters to selection:
+ * classify recent outcomes and add at most one capability-gap target plus one frontier target.
+ */
+export interface CurriculumOutcome {
+    key: string;
+    status: 'success' | 'failed';
+}
+export interface CurriculumBucket {
+    key: string;
+    success: number;
+    failed: number;
+    total: number;
+    rate: number;
+}
+export interface CurriculumClassification {
+    mastered: CurriculumBucket[];
+    failing: CurriculumBucket[];
+    frontier: CurriculumBucket[];
+}
+export interface CurriculumEventLike {
+    type: string;
+    payload?: unknown;
+}
+export interface GenerateCurriculumSignalsInput {
+    outcomes: readonly CurriculumOutcome[];
+    capabilityGaps?: readonly string[];
+}
+export declare const MAX_CAPABILITY_GAPS = 16;
+export declare const CAPABILITY_GAPS_STATE_KEY = "curriculum:capability_gaps";
+/** Normalize untrusted capability names before they cross adapter, persistence, or selection boundaries. */
+export declare function normalizeCapabilityGaps(value: unknown): string[];
+/** Versioned, bounded snapshot stored atomically in the lifecycle mailbox KV table. */
+export declare function serializeCapabilityGapsState(capabilityGaps: unknown, observedAt: number): string;
+/** Parse only the current bounded snapshot format. Unknown versions fail open without influencing selection. */
+export declare function capabilityGapsFromState(value: unknown): string[];
+/** Stable V2 equivalent of V1 computeSignalKey, excluding previously generated curriculum targets. */
+export declare function curriculumSignalKey(signals: readonly string[]): string;
+/** Classify signal-key outcomes using V1's thresholds. */
+export declare function classifyCurriculumOutcomes(outcomes: readonly CurriculumOutcome[]): CurriculumClassification;
+/** Generate no more than the two target families V1 produced: gap first, then closest frontier. */
+export declare function generateCurriculumSignals(input: GenerateCurriculumSignalsInput): string[];
+/**
+ * Map V2's capability signal conventions to concrete curriculum gaps. A bare cap:* tag is not sufficient by
+ * itself: it becomes a curriculum gap only when the same signal set explicitly declares capability_gap.
+ */
+export declare function capabilityGapsFromSignals(signals: readonly string[]): string[];
+/**
+ * Join cycle.signals_collected to terminal cycle events and retain the latest outcome window. `baseSignals`
+ * wins over `signals`, so history-derived meta-signals do not become a self-reinforcing curriculum key.
+ */
+export declare function curriculumOutcomesFromEvents(events: readonly CurriculumEventLike[], maxOutcomes?: number): CurriculumOutcome[];