@evomap/evolver-core 2.0.0-beta.8 → 2.0.0

package/dist/hub/questionGenerator.js

@@ -21,7 +21,7 @@ const EXPLORE_STOPWORDS = new Set([
     'agent', 'about', 'into', 'then', 'than', 'they', 'them', 'their', 'there',
     'here', 'will', 'would', 'could', 'should', 'been', 'were', 'using', 'used',
     'cycle', 'evolution', 'error', 'errors', 'failed', 'failure', 'null', 'undefined',
-    'true', 'false', 'console', 'return', 'function', 'const', 'value', 'result',
+    'true', 'false', 'console', 'return', 'function', 'const', 'value', 'result', 'redacted',
 ]);
 const SENSITIVE_TOPIC_RE = /secret|token|api[_-]?key|password|passwd|credential|bearer|authorization|cookie|session[_-]?id|private[_-]?key|oauth|refresh[_-]?token/i;
 const LONG_OPAQUE_RE = /^[a-z0-9_-]{32,}$/i;
@@ -106,8 +106,8 @@ function safeTopicToken(token) {
         return false;
     return true;
 }
-export function extractTopicKeywords(transcript, memory, max = 5) {
-    const text = `${String(transcript ?? '')} ${String(memory ?? '')}`.toLowerCase();
+export function extractTopicKeywords(transcript, memory, max = 5, opts = {}) {
+    const text = redactString(`${String(transcript ?? '')} ${String(memory ?? '')}`).toLowerCase();
     const words = text.match(/[a-z][a-z0-9_-]{4,}/g) ?? [];
     const freq = new Map();
     for (const word of words) {
@@ -115,9 +115,11 @@ export function extractTopicKeywords(transcript, memory, max = 5) {
             continue;
         freq.set(word, (freq.get(word) ?? 0) + 1);
     }
-    return [...freq.entries()]
-        .filter(([, count]) => count >= 2)
-        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    const entries = [...freq.entries()]
+        .filter(([, count]) => count >= Math.max(1, Math.trunc(opts.minOccurrences ?? 2)));
+    if (!opts.preserveSourceOrder)
+        entries.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+    return entries
         .map(([word]) => word)
         .slice(0, max);
 }

package/dist/hub/sanitize.js

@@ -16,11 +16,12 @@ const REDACT_PATTERNS = [
     /api[_-]?key[=:]\s*["']?[A-Za-z0-9-._~+/]{16,}["']?/gi,
     /secret[=:]\s*["']?[A-Za-z0-9-._~+/]{16,}["']?/gi,
     /password[=:]\s*["']?[^\s"',;)}\]]{6,}["']?/gi,
-    // GitHub tokens (ghp_, gho_, ghu_, ghs_, github_pat_)
+    // GitHub tokens (ghp_, gho_, ghu_, ghs_, ghr_, github_pat_)
     /ghp_[A-Za-z0-9]{36,}/g,
     /gho_[A-Za-z0-9]{36,}/g,
     /ghu_[A-Za-z0-9]{36,}/g,
     /ghs_[A-Za-z0-9]{36,}/g,
+    /ghr_[A-Za-z0-9]{36,}/g,
     /github_pat_[A-Za-z0-9_]{22,}/g,
     // AWS access keys
     /AKIA[0-9A-Z]{16}/g,
@@ -139,7 +140,7 @@ const LEAK_SCANNERS = [
     { type: 'api_key', pattern: /sk-proj-[A-Za-z0-9-_]{20,}/g, suggest: 'process.env.OPENAI_API_KEY' },
     { type: 'api_key', pattern: /sk-ant-[A-Za-z0-9-_]{20,}/g, suggest: 'process.env.ANTHROPIC_API_KEY' },
     { type: 'api_key', pattern: /AKIA[0-9A-Z]{16}/g, suggest: 'process.env.AWS_ACCESS_KEY_ID' },
-    { type: 'github_token', pattern: /ghp_[A-Za-z0-9]{36,}/g, suggest: 'process.env.GITHUB_TOKEN' },
+    { type: 'github_token', pattern: /gh(?:p|o|u|s|r)_[A-Za-z0-9]{36,}/g, suggest: 'process.env.GITHUB_TOKEN' },
     { type: 'github_token', pattern: /github_pat_[A-Za-z0-9_]{22,}/g, suggest: 'process.env.GITHUB_TOKEN' },
     { type: 'npm_token', pattern: /npm_[A-Za-z0-9]{36,}/g, suggest: 'process.env.NPM_TOKEN' },
     { type: 'slack_token', pattern: /xox[baprsv]-[A-Za-z0-9-]{10,}/g, suggest: 'process.env.SLACK_TOKEN' },

package/dist/index.d.ts

@@ -25,4 +25,6 @@ export * as shadow from './shadow/index.js';
 export * as ops from './ops/index.js';
 export * as util from './util/index.js';
 export * as trace from './trace/index.js';
-export * as issueReporter from './issueReporter/index.js';
+export * as issueReporter from './issueReporter/index.js';
+export * as feedback from './feedback/index.js';
+export { isValidationCommandAllowed } from './verify/validation.js';

package/dist/index.js

@@ -25,4 +25,7 @@ export * as shadow from './shadow/index.js';
 export * as ops from './ops/index.js';
 export * as util from './util/index.js';
 export * as trace from './trace/index.js';
-export * as issueReporter from './issueReporter/index.js';
+export * as issueReporter from './issueReporter/index.js';
+export * as feedback from './feedback/index.js';
+// Re-export commonly used validation functions at top level for convenience
+export { isValidationCommandAllowed } from './verify/validation.js';

package/dist/mailbox/dispatch.d.ts

@@ -1,6 +1,6 @@
 import type { Envelope } from './envelope.js';
 import type { Handler } from './catalog.js';
-import type { MailboxStore } from './store.js';
+import { type MailboxStore } from './store.js';
 export interface DispatchResult {
     id: string;
     handler: Handler;

package/dist/mailbox/dispatch.js

@@ -1,3 +1,4 @@
+import { mailboxClaimOwner } from './store.js';
 /**
  * 选择性 Material 判定(M2-7). 默认遵目录 feedsMaterial; 两类在 dispatch 决定:
  * - asset_publish_result: 仅 rejected 进(失败=养料 #40); 通过无需.
@@ -25,10 +26,16 @@ export class Dispatcher {
     }
     async dispatchOne(e) {
         const now = this.deps.now();
+        const claimOwner = mailboxClaimOwner(e);
+        if (!claimOwner) {
+            return { id: e.id, handler: e.handler, handled: false, fedMaterial: false, note: 'claim-owner-missing' };
+        }
         // 副作用幂等: 业务键(非默认=id)命中 → 跳过不二次执行, 直接 complete (money-safety A7/A13)
         const sideEffecting = e.handler !== 'agent' && e.idempotencyKey !== e.id;
         if (sideEffecting && this.deps.store.isProcessed(e.idempotencyKey)) {
-            this.deps.store.complete(e.id, now);
+            if (!this.deps.store.completeClaimed(e.id, now, claimOwner)) {
+                return { id: e.id, handler: e.handler, handled: false, fedMaterial: false, note: 'claim-lost' };
+            }
             return { id: e.id, handler: e.handler, handled: true, fedMaterial: false, note: 'idempotent-skip' };
         }
         try {
@@ -38,14 +45,23 @@ export class Dispatcher {
                 await this.deps.onMaterial(e);
                 fedMaterial = true;
             }
-            if (sideEffecting)
-                this.deps.store.markProcessed(e.idempotencyKey, result ?? null, now);
-            this.deps.store.complete(e.id, now);
+            const completed = sideEffecting
+                ? this.deps.store.completeClaimedAndMarkProcessed(e.id, e.idempotencyKey, result ?? null, now, claimOwner)
+                : this.deps.store.completeClaimed(e.id, now, claimOwner);
+            if (!completed) {
+                return { id: e.id, handler: e.handler, handled: false, fedMaterial, note: 'claim-lost' };
+            }
             return { id: e.id, handler: e.handler, handled: true, fedMaterial };
         }
         catch (err) {
-            this.deps.store.fail(e.id, err instanceof Error ? err.message : String(err), now);
-            return { id: e.id, handler: e.handler, handled: false, fedMaterial: false, note: 'failed' };
+            const failed = this.deps.store.failClaimed(e.id, err instanceof Error ? err.message : String(err), now, claimOwner);
+            return {
+                id: e.id,
+                handler: e.handler,
+                handled: false,
+                fedMaterial: false,
+                note: failed ? 'failed' : 'claim-lost',
+            };
         }
     }
     /** 拉一批并分派. 默认 daemon 侧 core+proxy; agent 由 runtime 经 IPC 拉取. */

package/dist/mailbox/envelope.d.ts

@@ -1,6 +1,8 @@
 import { specForType, type Direction, type Handler } from './catalog.js';
 export type Status = 'pending' | 'in_flight' | 'done' | 'failed' | 'expired';
-export declare const ENVELOPE_SCHEMA_VERSION = "1.0.0";
+export type Priority = 'high' | 'normal' | 'low';
+export declare const PRIORITIES: readonly ["high", "normal", "low"];
+export declare const ENVELOPE_SCHEMA_VERSION = "1.1.0";
 export interface Envelope {
     id: string;
     type: string;
@@ -15,6 +17,7 @@ export interface Envelope {
     sourceAgent: string;
     targetAgent: string;
     runtimeNamespace: string;
+    priority: Priority;
     attempts: number;
     nextRetryAt: number | null;
     ttlAt: number | null;
@@ -22,6 +25,7 @@ export interface Envelope {
     updatedAt: number;
     schemaVersion: string;
     feedsMaterial: boolean;
+    lastError: string | null;
 }
 /** 固定 envelope 字段集 (schema-snapshot 锁; 增删字段必须改此处). */
 export declare const ENVELOPE_FIELDS: readonly (keyof Envelope)[];
@@ -37,7 +41,9 @@ export interface CreateEnvelopeInput {
     sourceAgent?: string;
     targetAgent?: string;
     runtimeNamespace?: string;
+    priority?: unknown;
     now?: number;
 }
+export declare function normalizePriority(value: unknown): Priority;
 export declare function createEnvelope(input: CreateEnvelopeInput): Envelope;
 export { specForType };

package/dist/mailbox/envelope.js

@@ -1,11 +1,13 @@
 import { ulid as makeUlid } from 'ulid';
 import { specForType, assertKnownType } from './catalog.js';
-export const ENVELOPE_SCHEMA_VERSION = '1.0.0';
+export const PRIORITIES = Object.freeze(['high', 'normal', 'low']);
+export const ENVELOPE_SCHEMA_VERSION = '1.1.0';
 /** 固定 envelope 字段集 (schema-snapshot 锁; 增删字段必须改此处). */
 export const ENVELOPE_FIELDS = [
     'id', 'type', 'direction', 'status', 'handler', 'payload', 'correlationId', 'replyTo',
     'receiptId', 'idempotencyKey', 'sourceAgent', 'targetAgent', 'runtimeNamespace',
-    'attempts', 'nextRetryAt', 'ttlAt', 'createdAt', 'updatedAt', 'schemaVersion', 'feedsMaterial',
+    'priority', 'attempts', 'nextRetryAt', 'ttlAt', 'createdAt', 'updatedAt', 'schemaVersion', 'feedsMaterial',
+    'lastError',
 ];
 const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
 /** 防原型污染 (v1 GHSA). */
@@ -22,6 +24,9 @@ export function sanitizePayload(v) {
     return v;
 }
 const TTL_MS = { control: 60 * 60 * 1000, default: 7 * 24 * 60 * 60 * 1000 };
+export function normalizePriority(value) {
+    return value === 'high' || value === 'low' ? value : 'normal';
+}
 export function createEnvelope(input) {
     const spec = assertKnownType(input.type);
     const id = input.id ?? makeUlid();
@@ -40,6 +45,7 @@ export function createEnvelope(input) {
         sourceAgent: input.sourceAgent ?? '',
         targetAgent: input.targetAgent ?? '',
         runtimeNamespace: input.runtimeNamespace ?? 'default',
+        priority: normalizePriority(input.priority),
         attempts: 0,
         nextRetryAt: null,
         ttlAt: now + TTL_MS[spec.ttlClass],
@@ -47,6 +53,7 @@ export function createEnvelope(input) {
         updatedAt: now,
         schemaVersion: ENVELOPE_SCHEMA_VERSION,
         feedsMaterial: spec.feedsMaterial,
+        lastError: null,
     };
 }
 export { specForType };

package/dist/mailbox/ipcServer.d.ts

@@ -1,11 +1,13 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
 import { type Envelope } from './envelope.js';
-import type { MailboxStore } from './store.js';
+import { type MailboxStore } from './store.js';
 export interface IpcServerOptions {
     store: MailboxStore;
     token: string;
     host?: string;
     now?: () => number;
+    /** When set, every mailbox route is pinned to this daemon namespace. */
+    runtimeNamespace?: string;
     extraRoutes?: IpcRouteHandler[];
     onSend?: (envelope: Envelope, result: {
         receiptId: string;
@@ -34,6 +36,7 @@ export declare class MailboxIpcServer {
     private readonly token;
     private readonly host;
     private readonly now;
+    private readonly runtimeNamespace;
     private readonly extraRoutes;
     private readonly onSend;
     private readonly onAuthFailure;
@@ -42,5 +45,10 @@ export declare class MailboxIpcServer {
     close(): Promise<void>;
     private handle;
     private readJson;
+    private resolveSendNamespace;
+    private resolveRuntimeNamespace;
+    private messageInRuntime;
+    private canMutateMessage;
     private json;
-}
+}
+export declare function legacyMailboxMessage(message: Envelope): Record<string, unknown>;

package/dist/mailbox/ipcServer.js

@@ -1,8 +1,33 @@
 import { createServer } from 'node:http';
 import { timingSafeEqual } from 'node:crypto';
 import { createEnvelope } from './envelope.js';
+import { mailboxClaimOwner } from './store.js';
 const MAX_BODY = 256 * 1024; // 256KB 上限(防本机注入超大体)
 const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+const STATUSES = new Set(['pending', 'in_flight', 'done', 'failed', 'expired']);
+const DIRECTIONS = new Set(['outbound', 'inbound', 'local']);
+const PRIORITIES = new Set(['high', 'normal', 'low']);
+function serializeClaimedMessage(message) {
+    const claimToken = mailboxClaimOwner(message);
+    if (!claimToken)
+        throw new Error('claimed mailbox message is missing its claim token');
+    return { ...message, claimToken };
+}
+function requiredClaimToken(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        throw new Error('claimToken must be a non-empty string');
+    return value;
+}
+function optionalQueryInteger(url, name) {
+    const raw = url.searchParams.get(name);
+    if (raw === null)
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 0 || !Number.isInteger(value)) {
+        throw new Error(`${name} must be a non-negative integer`);
+    }
+    return value;
+}
 /** 定长常量时间比较(防 token 计时侧信道). */
 function tokenEq(a, b) {
     const ba = Buffer.from(a), bb = Buffer.from(b);
@@ -20,6 +45,7 @@ export class MailboxIpcServer {
     token;
     host;
     now;
+    runtimeNamespace;
     extraRoutes;
     onSend;
     onAuthFailure;
@@ -28,6 +54,7 @@ export class MailboxIpcServer {
         this.token = opts.token;
         this.host = opts.host ?? '127.0.0.1';
         this.now = opts.now ?? (() => Date.now());
+        this.runtimeNamespace = opts.runtimeNamespace;
         this.extraRoutes = opts.extraRoutes ?? [];
         this.onSend = opts.onSend;
         this.onAuthFailure = opts.onAuthFailure;
@@ -90,41 +117,98 @@ export class MailboxIpcServer {
             }
             if (route === 'POST /mailbox/send') {
                 const body = (await this.readJson(req));
-                const env = createEnvelope({ ...body, now });
+                if (body.priority !== undefined && !PRIORITIES.has(body.priority)) {
+                    throw new Error('priority must be high, normal, or low');
+                }
+                const legacyRef = typeof body.ref_id === 'string' && body.ref_id ? body.ref_id : undefined;
+                const runtimeNamespace = this.resolveSendNamespace(body);
+                let env = createEnvelope({
+                    ...body,
+                    runtimeNamespace,
+                    correlationId: body.correlationId ?? legacyRef,
+                    now,
+                });
+                if (body.expires_at !== undefined) {
+                    if (typeof body.expires_at !== 'number' || !Number.isFinite(body.expires_at)) {
+                        throw new Error('expires_at must be a finite epoch-millisecond number');
+                    }
+                    env = { ...env, ttlAt: body.expires_at };
+                }
                 const r = this.store.send(env);
                 if (r.stored)
                     this.onSend?.(env, r);
-                return this.json(res, 200, { id: env.id, receiptId: r.receiptId, stored: r.stored, correlationId: env.correlationId });
+                return this.json(res, 200, {
+                    id: env.id,
+                    receiptId: r.receiptId,
+                    stored: r.stored,
+                    correlationId: env.correlationId,
+                    message_id: env.id,
+                    status: env.status,
+                });
             }
             if (route === 'POST /mailbox/claim') {
                 const b = (await this.readJson(req));
-                const got = this.store.claim(b.handler, b.limit ?? 16, b.leaseMs ?? 30_000, now, b.runtimeNamespace);
-                return this.json(res, 200, { messages: got });
+                const runtimeNamespace = this.resolveRuntimeNamespace(b.runtimeNamespace);
+                const got = this.store.claim(b.handler, b.limit ?? 16, b.leaseMs ?? 30_000, now, runtimeNamespace);
+                return this.json(res, 200, { messages: got.map(serializeClaimedMessage) });
             }
             if (route === 'POST /mailbox/complete') {
                 const b = (await this.readJson(req));
-                this.store.complete(b.id, now);
+                if (!this.canMutateMessage(b.id))
+                    return this.json(res, 404, { error: 'not found' });
+                const claimToken = requiredClaimToken(b.claimToken);
+                if (!this.store.completeClaimed(b.id, now, claimToken)) {
+                    return this.json(res, 409, { error: 'mailbox claim is no longer owned by this worker', code: 'claim_conflict' });
+                }
                 return this.json(res, 200, { ok: true });
             }
             if (route === 'POST /mailbox/fail') {
                 const b = (await this.readJson(req));
-                this.store.fail(b.id, b.error ?? 'ipc fail', now);
+                if (!this.canMutateMessage(b.id))
+                    return this.json(res, 404, { error: 'not found' });
+                const claimToken = requiredClaimToken(b.claimToken);
+                if (!this.store.failClaimed(b.id, b.error ?? 'ipc fail', now, claimToken)) {
+                    return this.json(res, 409, { error: 'mailbox claim is no longer owned by this worker', code: 'claim_conflict' });
+                }
                 return this.json(res, 200, { ok: true });
             }
-            if (req.method === 'GET' && url.pathname === '/mailbox/status') {
-                const id = url.searchParams.get('id') ?? '';
+            const statusPathMatch = req.method === 'GET' ? /^\/mailbox\/status\/([^/]+)$/.exec(url.pathname) : null;
+            if (req.method === 'GET' && (url.pathname === '/mailbox/status' || statusPathMatch)) {
+                const id = statusPathMatch ? decodeURIComponent(statusPathMatch[1] ?? '') : url.searchParams.get('id') ?? '';
+                const message = this.messageInRuntime(id);
+                if (!message)
+                    return this.json(res, 404, { error: 'not found' });
+                if (statusPathMatch) {
+                    return this.json(res, 200, legacyMailboxMessage(message));
+                }
                 const s = this.store.getStatus(id);
                 return s ? this.json(res, 200, s) : this.json(res, 404, { error: 'not found' });
             }
             if (req.method === 'GET' && url.pathname === '/mailbox/list') {
-                const status = url.searchParams.get('status') ?? undefined;
+                const type = url.searchParams.get('type') ?? undefined;
+                const legacy = type !== undefined;
+                const rawStatus = url.searchParams.get('status') ?? undefined;
+                const statusValue = legacyMailboxStatus(rawStatus);
+                if (rawStatus !== undefined && statusValue === undefined)
+                    throw new Error('invalid status');
+                const directionValue = url.searchParams.get('direction') ?? undefined;
+                if (directionValue !== undefined && !DIRECTIONS.has(directionValue)) {
+                    throw new Error('invalid direction');
+                }
                 const got = this.store.list({
-                    status: status,
+                    status: statusValue,
                     handler: url.searchParams.get('handler') ?? undefined,
-                    runtimeNamespace: url.searchParams.get('runtimeNamespace') ?? undefined,
-                    limit: Number(url.searchParams.get('limit') ?? 200),
+                    runtimeNamespace: this.resolveRuntimeNamespace(url.searchParams.get('runtimeNamespace') ?? undefined),
+                    type,
+                    direction: directionValue,
+                    newestFirst: legacy,
+                    offset: optionalQueryInteger(url, 'offset'),
+                    limit: optionalQueryInteger(url, 'limit') ?? 200,
+                });
+                return this.json(res, 200, {
+                    messages: legacy ? got.map(legacyMailboxMessage) : got,
+                    count: got.length,
                 });
-                return this.json(res, 200, { messages: got });
             }
             return this.json(res, 404, { error: 'unknown route' });
         }
@@ -161,8 +245,74 @@ export class MailboxIpcServer {
             req.on('error', reject);
         });
     }
+    resolveSendNamespace(body) {
+        const bound = this.runtimeNamespace;
+        if (bound === undefined)
+            return body.runtimeNamespace;
+        const requested = body.runtimeNamespace;
+        if (requested !== undefined && (typeof requested !== 'string' || requested !== bound)) {
+            throw new Error('runtimeNamespace does not match the IPC server namespace');
+        }
+        const channel = body.channel;
+        if (channel !== undefined && (typeof channel !== 'string'
+            || (channel !== 'evomap-hub' && channel !== bound))) {
+            throw new Error('channel does not match the IPC server namespace');
+        }
+        return bound;
+    }
+    resolveRuntimeNamespace(requested) {
+        if (requested !== undefined && typeof requested !== 'string') {
+            throw new Error('runtimeNamespace must be a string');
+        }
+        const bound = this.runtimeNamespace;
+        if (bound === undefined)
+            return requested;
+        if (requested !== undefined && requested !== bound) {
+            throw new Error('runtimeNamespace does not match the IPC server namespace');
+        }
+        return bound;
+    }
+    messageInRuntime(id) {
+        const message = this.store.getById(id);
+        if (this.runtimeNamespace !== undefined && message?.runtimeNamespace !== this.runtimeNamespace)
+            return undefined;
+        return message;
+    }
+    canMutateMessage(id) {
+        return this.messageInRuntime(id) !== undefined;
+    }
     json(res, code, body) {
         res.writeHead(code, { 'content-type': 'application/json' });
         res.end(JSON.stringify(body));
     }
+}
+export function legacyMailboxMessage(message) {
+    return {
+        id: message.id,
+        message_id: message.id,
+        channel: message.runtimeNamespace === 'default' ? 'evomap-hub' : message.runtimeNamespace,
+        direction: message.direction,
+        type: message.type,
+        status: message.status === 'done' ? (message.direction === 'inbound' ? 'delivered' : 'synced') : message.status,
+        payload: message.payload,
+        priority: message.priority,
+        ref_id: message.replyTo ?? message.correlationId,
+        created_at: message.createdAt,
+        synced_at: message.status === 'done' ? message.updatedAt : null,
+        expires_at: message.ttlAt,
+        retry_count: message.attempts,
+        next_retry_at: message.nextRetryAt,
+        error: message.lastError,
+    };
+}
+function legacyMailboxStatus(value) {
+    if (value === undefined)
+        return undefined;
+    if (STATUSES.has(value))
+        return value;
+    if (value === 'delivered' || value === 'synced' || value === 'acked')
+        return 'done';
+    if (value === 'rejected')
+        return 'failed';
+    return undefined;
 }

package/dist/mailbox/store.d.ts

@@ -1,7 +1,59 @@
 import { type Envelope, type Status, type CreateEnvelopeInput } from './envelope.js';
 export declare const MAX_ATTEMPTS = 5;
 export declare const DEFAULT_IMPORT_JSONL_MAX_LINE_BYTES: number;
+export declare const DEFAULT_IMPORT_JSONL_MAX_BYTES: number;
+export declare const DEFAULT_IMPORT_JSONL_MAX_RECORDS = 100000;
+export declare const MAILBOX_CLAIM_OWNER: unique symbol;
+export type ClaimedEnvelope = Envelope & {
+    readonly [MAILBOX_CLAIM_OWNER]: string;
+};
+export type MailboxImportRecord = Readonly<{
+    kind: 'message';
+    envelope: Readonly<Envelope>;
+}> | Readonly<{
+    kind: 'update';
+    id: string;
+    fields: Readonly<Record<string, unknown>>;
+}>;
+export type PreparedMailboxImport = Readonly<{
+    records: readonly MailboxImportRecord[];
+    sourceRecords: number;
+    messageCandidates: number;
+    uniqueMessageCandidates: number;
+    updateCandidates: number;
+}>;
+export type MailboxImportPreview = Readonly<{
+    sourceRecords: number;
+    messageCandidates: number;
+    uniqueMessageCandidates: number;
+    updateCandidates: number;
+    insertedMessages: number;
+    updatedMessages: number;
+    managedMessages: number;
+    protectedMessages: number;
+}>;
+export type MailboxJsonlImportErrorCode = 'line_too_large' | 'journal_too_large' | 'too_many_records' | 'invalid_utf8' | 'invalid_json' | 'invalid_record' | 'invalid_update' | 'unsupported_operation' | 'invalid_message';
+export declare class MailboxJsonlImportError extends Error {
+    readonly code: MailboxJsonlImportErrorCode;
+    readonly line: number;
+    constructor(code: MailboxJsonlImportErrorCode, line: number, message: string);
+}
+export declare function mailboxClaimOwner(envelope: Envelope): string | undefined;
 export declare function expBackoffMs(attempt: number): number;
+/** Read one mailbox state value without creating, migrating, or taking write ownership of the database. */
+export declare function readMailboxState(path: string, key: string): string | undefined;
+/**
+ * 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 declare function prepareMailboxJsonlImport(source: string | number, options?: {
+    maxLineBytes?: number;
+    maxBytes?: number;
+    maxRecords?: number;
+    now?: number;
+}): PreparedMailboxImport;
+/** Preview a prepared import against an optional existing mailbox without creating or migrating it. */
+export declare function previewPreparedMailboxImport(batch: PreparedMailboxImport, mailboxPath?: string): MailboxImportPreview;
 /** mailbox sqlite 引擎 (WAL + busy_timeout). 状态机 pending→in_flight→done/failed/expired + 租约 + 重试/DLQ. */
 export declare class MailboxStore {
     private readonly db;
@@ -47,12 +99,31 @@ export declare class MailboxStore {
     hasMessageWithIdempotencyKey(idempotencyKey: string): boolean;
     hasMessageWithPayload(type: string, payload: unknown): boolean;
     /** 原子 claim: pending(或租约过期的 in_flight) → in_flight + 租约. 可按 runtimeNamespace 分区. */
-    claim(handler: string, limit: number, leaseMs: number, now: number, runtimeNamespace?: string): Envelope[];
+    claim(handler: string, limit: number, leaseMs: number, now: number, runtimeNamespace?: string): ClaimedEnvelope[];
     complete(id: string, now: number): void;
     /** 失败: attempts<N→退避回 pending; ≥N→DLQ(不自动丢). */
     fail(id: string, err: string, now: number, maxAttempts?: number): void;
     /** 暂缓: transient upstream outage 不消耗 attempts, 仅设置下次可 claim 时间. */
     defer(id: string, err: string, now: number, retryAfterMs: number): void;
+    deferUnlessProcessed(id: string, processedKey: string, err: string, now: number, retryAfterMs: number): boolean;
+    failUnlessProcessed(id: string, processedKey: string, err: string, now: number, maxAttempts?: number): boolean;
+    completeClaimed(id: string, now: number, claimOwner: string): boolean;
+    /** Atomically complete the current worker's lease and persist its idempotency result. */
+    completeClaimedAndMarkProcessed(id: string, processedKey: string, result: unknown, now: number, claimOwner: string): boolean;
+    renewClaim(id: string, now: number, leaseMs: number, claimOwner: string): boolean;
+    setClaimedCheckpoint(id: string, checkpoint: unknown, now: number, claimOwner: string): boolean;
+    getClaimedCheckpoint(id: string): unknown | undefined;
+    deferClaimed(id: string, err: string, now: number, retryAfterMs: number, claimOwner: string): boolean;
+    failClaimed(id: string, err: string, now: number, claimOwner: string, maxAttempts?: number): boolean;
+    /** Transition only the row held by the current worker, unless a concurrent success marker already exists. */
+    deferClaimedUnlessProcessed(id: string, processedKey: string, err: string, now: number, retryAfterMs: number, claimOwner: string): boolean;
+    /** Transition only the row held by the current worker, unless a concurrent success marker already exists. */
+    failClaimedUnlessProcessed(id: string, processedKey: string, err: string, now: number, claimOwner: string, maxAttempts?: number): boolean;
+    /** Atomically fail a non-leased intent and persist the replayable terminal result. */
+    failAndMarkProcessedUnlessProcessed(id: string, blockingProcessedKeys: readonly string[], resultKey: string, result: unknown, err: string, now: number, maxAttempts?: number): boolean;
+    /** Atomically fail the current worker's leased intent and persist the replayable terminal result. */
+    failClaimedAndMarkProcessedUnlessProcessed(id: string, blockingProcessedKeys: readonly string[], resultKey: string, result: unknown, err: string, now: number, claimOwner: string, maxAttempts?: number): boolean;
+    private transitionUnlessProcessed;
     /** DLQ 重放(人工/agent 显式, 不自动丢). */
     replayDlq(id: string, now: number): void;
     dlq(): Envelope[];
@@ -73,16 +144,31 @@ export declare class MailboxStore {
         id: string;
         type: string;
         status: Status;
+        priority: Envelope['priority'];
         attempts: number;
         nextRetryAt: number | null;
         ttlAt: number | null;
         dlq: boolean;
+        lastError: string | null;
     } | undefined;
     /** 幂等(A13): 副作用 handler 用 idempotencyKey 去重; 命中返缓存不重跑. */
     isProcessed(key: string): boolean;
     getProcessed(key: string): unknown;
     markProcessed(key: string, result: unknown, now: number): void;
-    /** v1 messages.jsonl → sqlite 迁移(幂等可重入). */
-    importJsonl(path: string): number;
+    replaceProcessed(key: string, result: unknown, now: number): void;
+    /** Persist a monotonic outcome and its lightweight concurrency marker in one SQLite transaction. */
+    replaceProcessedWithMarker(key: string, result: unknown, markerKey: string, markerResult: unknown, now: number): void;
+    /** Backfill a concurrency marker only when the durable source result still satisfies the caller's predicate. */
+    markProcessedIf(sourceKey: string, markerKey: string, markerResult: unknown, now: number, matches: (sourceResult: unknown) => boolean): boolean;
+    deleteProcessed(keys: readonly string[]): void;
+    private messageClaimOwner;
+    /** Build the target-aware plan shared by preview and apply. */
+    private buildPreparedImportPlan;
+    /** Preview the exact import result against the current mailbox snapshot without writing to it. */
+    previewPreparedImport(batch: PreparedMailboxImport): MailboxImportPreview;
+    private writeImportedEnvelopeFields;
+    /** Apply a parsed batch; planning and writes share one transaction and one normalized journal. */
+    importPrepared(batch: PreparedMailboxImport): number;
+    importJsonl(source: string | number): number;
     close(): void;
 }