@evomap/evolver-core 2.0.0-beta.0

package/dist/mailbox/dispatch.js

@@ -0,0 +1,62 @@
+/**
+ * 选择性 Material 判定(M2-7). 默认遵目录 feedsMaterial; 两类在 dispatch 决定:
+ * - asset_publish_result: 仅 rejected 进(失败=养料 #40); 通过无需.
+ * - swarm.*: 仅带结论的进; 中间消息不进.
+ */
+export function shouldFeedMaterial(e) {
+    if (e.type === 'asset_publish_result') {
+        return e.payload?.status === 'rejected';
+    }
+    if (e.type.startsWith('swarm.')) {
+        const p = e.payload;
+        return p?.conclusion !== undefined || p?.final === true;
+    }
+    return e.feedsMaterial;
+}
+/**
+ * 三-handler 分派器(M2-7). 谁 claim 谁 complete:
+ * - daemon 侧 pump core+proxy(确定性/hub 往返).
+ * - agent 类常由外部 runtime 经 IPC(M2-6) claim+complete; 嵌入式可显式 pump ['agent'].
+ */
+export class Dispatcher {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async dispatchOne(e) {
+        const now = this.deps.now();
+        // 副作用幂等: 业务键(非默认=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);
+            return { id: e.id, handler: e.handler, handled: true, fedMaterial: false, note: 'idempotent-skip' };
+        }
+        try {
+            const result = await this.deps.handlers[e.handler](e);
+            let fedMaterial = false;
+            if (this.deps.onMaterial && shouldFeedMaterial(e)) {
+                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);
+            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' };
+        }
+    }
+    /** 拉一批并分派. 默认 daemon 侧 core+proxy; agent 由 runtime 经 IPC 拉取. */
+    async pump(opts = {}) {
+        const kinds = opts.handlers ?? ['core', 'proxy'];
+        const out = [];
+        for (const k of kinds) {
+            const batch = this.deps.store.claim(k, opts.limit ?? 16, opts.leaseMs ?? 30_000, this.deps.now(), opts.runtimeNamespace);
+            for (const e of batch)
+                out.push(await this.dispatchOne(e));
+        }
+        return out;
+    }
+}

package/dist/mailbox/envelope.d.ts

@@ -0,0 +1,43 @@
+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 interface Envelope {
+    id: string;
+    type: string;
+    direction: Direction;
+    status: Status;
+    handler: Handler;
+    payload: unknown;
+    correlationId: string;
+    replyTo: string | null;
+    receiptId: string;
+    idempotencyKey: string;
+    sourceAgent: string;
+    targetAgent: string;
+    runtimeNamespace: string;
+    attempts: number;
+    nextRetryAt: number | null;
+    ttlAt: number | null;
+    createdAt: number;
+    updatedAt: number;
+    schemaVersion: string;
+    feedsMaterial: boolean;
+}
+/** 固定 envelope 字段集 (schema-snapshot 锁; 增删字段必须改此处). */
+export declare const ENVELOPE_FIELDS: readonly (keyof Envelope)[];
+/** 防原型污染 (v1 GHSA). */
+export declare function sanitizePayload(v: unknown): unknown;
+export interface CreateEnvelopeInput {
+    id?: string;
+    type: string;
+    payload?: unknown;
+    correlationId?: string;
+    replyTo?: string | null;
+    idempotencyKey?: string;
+    sourceAgent?: string;
+    targetAgent?: string;
+    runtimeNamespace?: string;
+    now?: number;
+}
+export declare function createEnvelope(input: CreateEnvelopeInput): Envelope;
+export { specForType };

package/dist/mailbox/envelope.js

@@ -0,0 +1,52 @@
+import { ulid as makeUlid } from 'ulid';
+import { specForType, assertKnownType } from './catalog.js';
+export const ENVELOPE_SCHEMA_VERSION = '1.0.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',
+];
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+/** 防原型污染 (v1 GHSA). */
+export function sanitizePayload(v) {
+    if (Array.isArray(v))
+        return v.map(sanitizePayload);
+    if (v && typeof v === 'object') {
+        const out = {};
+        for (const [k, val] of Object.entries(v))
+            if (!FORBIDDEN_KEYS.has(k))
+                out[k] = sanitizePayload(val);
+        return out;
+    }
+    return v;
+}
+const TTL_MS = { control: 60 * 60 * 1000, default: 7 * 24 * 60 * 60 * 1000 };
+export function createEnvelope(input) {
+    const spec = assertKnownType(input.type);
+    const id = input.id ?? makeUlid();
+    const now = input.now ?? Date.now();
+    return {
+        id,
+        type: input.type,
+        direction: spec.direction,
+        status: 'pending',
+        handler: spec.handler,
+        payload: sanitizePayload(input.payload ?? {}),
+        correlationId: input.correlationId ?? id,
+        replyTo: input.replyTo ?? null,
+        receiptId: id, // 投递即返(异步不变量)
+        idempotencyKey: input.idempotencyKey ?? id, // 副作用类型应传业务键(硬化 A13)
+        sourceAgent: input.sourceAgent ?? '',
+        targetAgent: input.targetAgent ?? '',
+        runtimeNamespace: input.runtimeNamespace ?? 'default',
+        attempts: 0,
+        nextRetryAt: null,
+        ttlAt: now + TTL_MS[spec.ttlClass],
+        createdAt: now,
+        updatedAt: now,
+        schemaVersion: ENVELOPE_SCHEMA_VERSION,
+        feedsMaterial: spec.feedsMaterial,
+    };
+}
+export { specForType };

package/dist/mailbox/index.d.ts

@@ -0,0 +1,8 @@
+export * from './catalog.js';
+export * from './envelope.js';
+export * from './store.js';
+export * from './requestReply.js';
+export * from './ipcServer.js';
+export * from './dispatch.js';
+export * from './wake.js';
+export * from './daemon.js';

package/dist/mailbox/index.js

@@ -0,0 +1,8 @@
+export * from './catalog.js';
+export * from './envelope.js';
+export * from './store.js';
+export * from './requestReply.js';
+export * from './ipcServer.js';
+export * from './dispatch.js';
+export * from './wake.js';
+export * from './daemon.js';

package/dist/mailbox/ipcServer.d.ts

@@ -0,0 +1,46 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import { type Envelope } from './envelope.js';
+import type { MailboxStore } from './store.js';
+export interface IpcServerOptions {
+    store: MailboxStore;
+    token: string;
+    host?: string;
+    now?: () => number;
+    extraRoutes?: IpcRouteHandler[];
+    onSend?: (envelope: Envelope, result: {
+        receiptId: string;
+        stored: boolean;
+    }) => void;
+    onAuthFailure?: () => void;
+}
+export interface IpcRouteContext {
+    req: IncomingMessage;
+    res: ServerResponse;
+    url: URL;
+    route: string;
+    now: number;
+    store: MailboxStore;
+    readJson: () => Promise<unknown>;
+    json: (code: number, body: unknown) => void;
+}
+export type IpcRouteHandler = (ctx: IpcRouteContext) => boolean | void | Promise<boolean | void>;
+/**
+ * 本地 HTTP IPC(M2-6): runtime adapter ↔ mailbox 的进程间通道.
+ * 仅绑 127.0.0.1 + Bearer token; runtimeNamespace 分区, 不同 runtime 实例互不串信箱.
+ */
+export declare class MailboxIpcServer {
+    private readonly server;
+    private readonly store;
+    private readonly token;
+    private readonly host;
+    private readonly now;
+    private readonly extraRoutes;
+    private readonly onSend;
+    private readonly onAuthFailure;
+    constructor(opts: IpcServerOptions);
+    listen(port?: number): Promise<number>;
+    close(): Promise<void>;
+    private handle;
+    private readJson;
+    private json;
+}

package/dist/mailbox/ipcServer.js

@@ -0,0 +1,168 @@
+import { createServer } from 'node:http';
+import { timingSafeEqual } from 'node:crypto';
+import { createEnvelope } from './envelope.js';
+const MAX_BODY = 256 * 1024; // 256KB 上限(防本机注入超大体)
+const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+/** 定长常量时间比较(防 token 计时侧信道). */
+function tokenEq(a, b) {
+    const ba = Buffer.from(a), bb = Buffer.from(b);
+    if (ba.length !== bb.length)
+        return false;
+    return timingSafeEqual(ba, bb);
+}
+/**
+ * 本地 HTTP IPC(M2-6): runtime adapter ↔ mailbox 的进程间通道.
+ * 仅绑 127.0.0.1 + Bearer token; runtimeNamespace 分区, 不同 runtime 实例互不串信箱.
+ */
+export class MailboxIpcServer {
+    server;
+    store;
+    token;
+    host;
+    now;
+    extraRoutes;
+    onSend;
+    onAuthFailure;
+    constructor(opts) {
+        this.store = opts.store;
+        this.token = opts.token;
+        this.host = opts.host ?? '127.0.0.1';
+        this.now = opts.now ?? (() => Date.now());
+        this.extraRoutes = opts.extraRoutes ?? [];
+        this.onSend = opts.onSend;
+        this.onAuthFailure = opts.onAuthFailure;
+        this.server = createServer((req, res) => { void this.handle(req, res); });
+    }
+    listen(port = 0) {
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                this.server.off('error', onError);
+                this.server.off('listening', onListening);
+            };
+            const onError = (err) => {
+                cleanup();
+                reject(err);
+            };
+            const onListening = () => {
+                cleanup();
+                const addr = this.server.address();
+                resolve(addr && typeof addr === 'object' ? addr.port : port);
+            };
+            this.server.once('error', onError);
+            this.server.once('listening', onListening);
+            this.server.listen(port, this.host);
+        });
+    }
+    close() {
+        return new Promise((resolve, reject) => this.server.close((e) => (e ? reject(e) : resolve())));
+    }
+    async handle(req, res) {
+        try {
+            const ra = req.socket.remoteAddress ?? '';
+            if (!LOOPBACK.has(ra))
+                return this.json(res, 403, { error: 'non-loopback' });
+            const auth = req.headers['authorization'] ?? '';
+            // Fail closed on an empty configured token: tokenEq('', '') is true, so without this guard a blank token
+            // would authenticate any `Authorization: Bearer ` request. An empty token never authenticates anyone.
+            if (!this.token || !auth.startsWith('Bearer ') || !tokenEq(auth.slice(7), this.token)) {
+                try {
+                    this.onAuthFailure?.();
+                }
+                catch { /* auth failure handling must never weaken fail-closed IPC auth */ }
+                return this.json(res, 401, { error: 'bad token' });
+            }
+            const url = new URL(req.url ?? '/', 'http://localhost');
+            const route = `${req.method} ${url.pathname}`;
+            const now = this.now();
+            for (const extra of this.extraRoutes) {
+                const handled = await extra({
+                    req,
+                    res,
+                    url,
+                    route,
+                    now,
+                    store: this.store,
+                    readJson: () => this.readJson(req),
+                    json: (code, body) => this.json(res, code, body),
+                });
+                if (handled)
+                    return;
+            }
+            if (route === 'POST /mailbox/send') {
+                const body = (await this.readJson(req));
+                const env = createEnvelope({ ...body, now });
+                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 });
+            }
+            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 });
+            }
+            if (route === 'POST /mailbox/complete') {
+                const b = (await this.readJson(req));
+                this.store.complete(b.id, now);
+                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);
+                return this.json(res, 200, { ok: true });
+            }
+            if (req.method === 'GET' && url.pathname === '/mailbox/status') {
+                const id = url.searchParams.get('id') ?? '';
+                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 got = this.store.list({
+                    status: status,
+                    handler: url.searchParams.get('handler') ?? undefined,
+                    runtimeNamespace: url.searchParams.get('runtimeNamespace') ?? undefined,
+                    limit: Number(url.searchParams.get('limit') ?? 200),
+                });
+                return this.json(res, 200, { messages: got });
+            }
+            return this.json(res, 404, { error: 'unknown route' });
+        }
+        catch (e) {
+            return this.json(res, 400, { error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    readJson(req) {
+        return new Promise((resolve, reject) => {
+            let size = 0;
+            let overflow = false;
+            const chunks = [];
+            req.on('data', (c) => {
+                size += c.length;
+                if (size > MAX_BODY) {
+                    overflow = true;
+                    return;
+                } // 不 destroy socket: 继续 drain 以保证能回 400
+                if (!overflow)
+                    chunks.push(c);
+            });
+            req.on('end', () => {
+                if (overflow) {
+                    reject(new Error('body too large'));
+                    return;
+                }
+                try {
+                    resolve(chunks.length ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : {});
+                }
+                catch {
+                    reject(new Error('invalid json'));
+                }
+            });
+            req.on('error', reject);
+        });
+    }
+    json(res, code, body) {
+        res.writeHead(code, { 'content-type': 'application/json' });
+        res.end(JSON.stringify(body));
+    }
+}

package/dist/mailbox/requestReply.d.ts

@@ -0,0 +1,40 @@
+import type { Envelope } from './envelope.js';
+import type { MailboxStore } from './store.js';
+/** 应答超时. correlationId 保留以便审计/重试. */
+export declare class ReplyTimeoutError extends Error {
+    readonly correlationId: string;
+    constructor(correlationId: string, reason?: string);
+}
+/**
+ * 进程内应答等待器(M2-5). 一个 daemon 生命周期内: request 注册 waiter, dispatch 收到 inbound 即 notify 唤醒.
+ * 不持有定时器(由 sweep(now) 推进 deadline), 测试可确定性驱动; durable 兜底走 store.getReply.
+ */
+export declare class ReplyRegistry {
+    private readonly waiters;
+    /** 注册等待 correlationId 的应答; 由 notify 解决, 由 sweep/expire 拒绝. */
+    await(correlationId: string, requestId: string, deadline: number): Promise<Envelope>;
+    /** 收到 envelope: 若是匹配关联的应答(非请求自身)则唤醒对应 waiter. */
+    notify(e: Envelope): boolean;
+    /** 推进时钟: deadline 已过的 waiter 全部超时拒绝. 返回过期数. */
+    sweep(now: number): number;
+    /** 显式过期单个关联(如收到 failed/expired 终态). */
+    expire(correlationId: string, reason?: string): boolean;
+    pending(): number;
+}
+/**
+ * 请求-应答门面: 绑定 store(durable) + registry(live).
+ * request 投递并注册 waiter; 应答既可经 notify 实时唤醒, 也可经 store.getReply durable 兜底.
+ */
+export declare class RequestReply {
+    private readonly store;
+    readonly registry: ReplyRegistry;
+    constructor(store: MailboxStore, registry?: ReplyRegistry);
+    /** 投递请求, 返回 correlationId/requestId; 应答到达前先查 durable 已存(幂等重入). */
+    request(env: Envelope, timeoutMs: number, now: number): {
+        correlationId: string;
+        requestId: string;
+        reply: Promise<Envelope>;
+    };
+    /** dispatch 收到 inbound 时调用: 唤醒等待者. */
+    deliver(e: Envelope): boolean;
+}

package/dist/mailbox/requestReply.js

@@ -0,0 +1,77 @@
+/** 应答超时. correlationId 保留以便审计/重试. */
+export class ReplyTimeoutError extends Error {
+    correlationId;
+    constructor(correlationId, reason = 'reply timeout') {
+        super(`关联 ${correlationId} 应答超时: ${reason}`);
+        this.correlationId = correlationId;
+        this.name = 'ReplyTimeoutError';
+    }
+}
+/**
+ * 进程内应答等待器(M2-5). 一个 daemon 生命周期内: request 注册 waiter, dispatch 收到 inbound 即 notify 唤醒.
+ * 不持有定时器(由 sweep(now) 推进 deadline), 测试可确定性驱动; durable 兜底走 store.getReply.
+ */
+export class ReplyRegistry {
+    waiters = new Map();
+    /** 注册等待 correlationId 的应答; 由 notify 解决, 由 sweep/expire 拒绝. */
+    await(correlationId, requestId, deadline) {
+        return new Promise((resolve, reject) => {
+            const prev = this.waiters.get(correlationId);
+            if (prev)
+                prev.reject(new ReplyTimeoutError(correlationId, '被同关联新等待覆盖'));
+            this.waiters.set(correlationId, { resolve, reject, requestId, deadline });
+        });
+    }
+    /** 收到 envelope: 若是匹配关联的应答(非请求自身)则唤醒对应 waiter. */
+    notify(e) {
+        const w = this.waiters.get(e.correlationId);
+        if (!w || e.id === w.requestId)
+            return false; // 没人等 / 是请求自身
+        this.waiters.delete(e.correlationId);
+        w.resolve(e);
+        return true;
+    }
+    /** 推进时钟: deadline 已过的 waiter 全部超时拒绝. 返回过期数. */
+    sweep(now) {
+        let n = 0;
+        for (const [cid, w] of this.waiters) {
+            if (w.deadline <= now) {
+                this.waiters.delete(cid);
+                w.reject(new ReplyTimeoutError(cid));
+                n += 1;
+            }
+        }
+        return n;
+    }
+    /** 显式过期单个关联(如收到 failed/expired 终态). */
+    expire(correlationId, reason) {
+        const w = this.waiters.get(correlationId);
+        if (!w)
+            return false;
+        this.waiters.delete(correlationId);
+        w.reject(new ReplyTimeoutError(correlationId, reason));
+        return true;
+    }
+    pending() { return this.waiters.size; }
+}
+/**
+ * 请求-应答门面: 绑定 store(durable) + registry(live).
+ * request 投递并注册 waiter; 应答既可经 notify 实时唤醒, 也可经 store.getReply durable 兜底.
+ */
+export class RequestReply {
+    store;
+    registry;
+    constructor(store, registry = new ReplyRegistry()) {
+        this.store = store;
+        this.registry = registry;
+    }
+    /** 投递请求, 返回 correlationId/requestId; 应答到达前先查 durable 已存(幂等重入). */
+    request(env, timeoutMs, now) {
+        this.store.send(env);
+        const existing = this.store.getReply(env.correlationId, env.id);
+        const reply = existing ? Promise.resolve(existing) : this.registry.await(env.correlationId, env.id, now + timeoutMs);
+        return { correlationId: env.correlationId, requestId: env.id, reply };
+    }
+    /** dispatch 收到 inbound 时调用: 唤醒等待者. */
+    deliver(e) { return this.registry.notify(e); }
+}

package/dist/mailbox/store.d.ts

@@ -0,0 +1,74 @@
+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 function expBackoffMs(attempt: number): number;
+/** mailbox sqlite 引擎 (WAL + busy_timeout). 状态机 pending→in_flight→done/failed/expired + 租约 + 重试/DLQ. */
+export declare class MailboxStore {
+    private readonly db;
+    constructor(opts: {
+        path: string;
+        busyTimeoutMs?: number;
+    });
+    /** 通用 KV 状态(M6: sync 游标 inbound_cursor / lifecycle reauth 退避 / node_id 等). */
+    getState(key: string): string | undefined;
+    setState(key: string, value: string): void;
+    /** 投递; 同 id 幂等(OR IGNORE). 返回 receiptId. */
+    send(e: Envelope): {
+        receiptId: string;
+        stored: boolean;
+    };
+    getById(id: string): Envelope | undefined;
+    list(opts?: {
+        status?: Status;
+        handler?: string;
+        runtimeNamespace?: string;
+        limit?: number;
+    }): Envelope[];
+    countByStatus(status: Status): number;
+    /** pending 计数(可按 handler/runtimeNamespace 分区), 用于 agent wake 去抖. */
+    countPending(handler?: string, runtimeNamespace?: string): number;
+    /** 只统计「现在就能 claim」的出站, 供 cadence 判定, 避免 deferred 拉低 idle 退避.
+     *  谓词须与 claim() 对齐: 到点 pending + 租约过期的 in_flight 孤儿; 否则孤儿出站(claim 能回收却不被计)会被误判 idle, 恢复最多慢一个 idle 周期. */
+    countClaimable(handler: string, now: number, runtimeNamespace?: string): number;
+    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[];
+    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;
+    /** DLQ 重放(人工/agent 显式, 不自动丢). */
+    replayDlq(id: string, now: number): void;
+    dlq(): Envelope[];
+    /** TTL 扫描: ttlAt 过期且未 done/dlq → expired. */
+    expireOld(now: number): number;
+    /** M2-5 关联线程: 同 correlationId 全部消息(请求+应答), 按 createdAt 排序. */
+    findByCorrelation(correlationId: string): Envelope[];
+    /** 关联线程中除 requestId 外最新一条 = 应答(durable, 跨重启/进程). */
+    getReply(correlationId: string, requestId: string): Envelope | undefined;
+    /** 构造并投递一条对 `to` 的应答(继承 correlationId, 收发方对调, replyTo 清空). */
+    reply(to: Envelope, replyType: string, payload: unknown, now: number, over?: Partial<CreateEnvelopeInput>): {
+        envelope: Envelope;
+        receiptId: string;
+        stored: boolean;
+    };
+    /** M2-5 轻量状态视图(运维/IPC 查询用). */
+    getStatus(id: string): {
+        id: string;
+        type: string;
+        status: Status;
+        attempts: number;
+        nextRetryAt: number | null;
+        ttlAt: number | null;
+        dlq: boolean;
+    } | 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;
+    close(): void;
+}