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

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,14 @@
 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 MAILBOX_CLAIM_OWNER: unique symbol;
+export type ClaimedEnvelope = Envelope & {
+    readonly [MAILBOX_CLAIM_OWNER]: 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;
 /** mailbox sqlite 引擎 (WAL + busy_timeout). 状态机 pending→in_flight→done/failed/expired + 租约 + 重试/DLQ. */
 export declare class MailboxStore {
     private readonly db;
@@ -47,12 +54,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 +99,26 @@ 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;
+    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;
     /** v1 messages.jsonl → sqlite 迁移(幂等可重入). */
-    importJsonl(path: string): number;
+    importJsonl(source: string | number): number;
+    private applyImportedV1Update;
     close(): void;
 }