@evomap/evolver-core 2.0.0-beta.1 → 2.0.0-beta.3

package/dist/exec/selfPrObfuscation.js

@@ -28,8 +28,10 @@ export function defaultReadManifest(repoRoot) {
         }
     };
 }
+const MANIFEST_TRANSIENT_RETRY_MS = 5 * 60 * 1000;
 // Resettable cache keyed by the reader identity, so distinct readers (e.g. per test) don't bleed into each other.
-// `null` = a load was attempted and FAILED (fail-closed); a Set = the loaded obfuscate paths.
+// Success is cached permanently for the reader. Failures remain fail-closed, but transient reads retry for a
+// short window before stabilizing to null for the process lifetime.
 const cache = new WeakMap();
 /** Test/maintenance hook: drop any cached load for a reader (or all readers) so the load path re-runs. */
 export function resetObfuscatedCache(reader) {
@@ -40,11 +42,15 @@ export function resetObfuscatedCache(reader) {
 /**
  * Load the obfuscated-file set from the manifest. Returns a normalized Set, or null when the manifest is
  * missing / unreadable / structurally invalid (NOT an `obfuscate` array of literal string paths). null is the
- * fail-closed signal: the caller must then reject all files. Result is cached per reader.
+ * fail-closed signal: the caller must then reject all files. Success is cached per reader; failures retry briefly
+ * so startup-time transient filesystem errors do not disable self-PR until process restart.
  */
 export function loadObfuscatedFiles(readManifest) {
-    if (cache.has(readManifest))
-        return cache.get(readManifest) ?? null;
+    const cached = cache.get(readManifest);
+    if (cached?.kind === 'loaded')
+        return cached.files;
+    if (cached?.kind === 'failed' && cached.stable)
+        return null;
     let result;
     try {
         const raw = readManifest();
@@ -63,9 +69,16 @@ export function loadObfuscatedFiles(readManifest) {
         result = new Set(manifest.obfuscate.map((f) => normalizeManifestPath(f)).filter(Boolean));
     }
     catch {
-        result = null; // fail-closed: an unreadable/invalid manifest rejects everything
+        const now = Date.now();
+        const firstFailedAt = cached?.kind === 'failed' ? cached.firstFailedAt : now;
+        cache.set(readManifest, {
+            kind: 'failed',
+            firstFailedAt,
+            stable: now - firstFailedAt >= MANIFEST_TRANSIENT_RETRY_MS,
+        });
+        return null; // fail-closed: an unreadable/invalid manifest rejects everything
     }
-    cache.set(readManifest, result);
+    cache.set(readManifest, { kind: 'loaded', files: result });
     return result;
 }
 /**

package/dist/hub/agentDirectory.d.ts

@@ -0,0 +1,90 @@
+export declare const AGENT_DIRECTORY_DEFAULT_LIMIT = 20;
+export declare const AGENT_DIRECTORY_MAX_LIMIT = 50;
+export declare const AGENT_DIRECTORY_DEFAULT_TIMEOUT_MS = 8000;
+export declare const AGENT_DIRECTORY_MAX_TIMEOUT_MS = 30000;
+export declare const AGENT_DIRECTORY_MAX_QUERY_LENGTH = 500;
+export declare const AGENT_DIRECTORY_MAX_SIGNAL_COUNT = 20;
+export declare const AGENT_DIRECTORY_MAX_SIGNAL_LENGTH = 64;
+export declare const AGENT_DIRECTORY_MAX_CURSOR_LENGTH = 256;
+export declare const AGENT_DIRECTORY_MAX_AGENT_ID_LENGTH = 128;
+export type AgentAvailability = 'online' | 'busy' | 'offline' | 'unknown';
+export type AgentDirectorySort = 'relevance' | 'reputation' | 'recent' | 'availability';
+export type SortOrder = 'asc' | 'desc';
+export interface AgentSearchRequest {
+    query?: string;
+    signals?: readonly string[];
+    availability?: AgentAvailability;
+    sort?: AgentDirectorySort;
+    order?: SortOrder;
+    cursor?: string;
+    limit?: number;
+    timeoutMs?: number;
+}
+export interface AgentTaskDiscoveryRequest {
+    title: string;
+    description?: string;
+    signals?: readonly string[];
+    availability?: AgentAvailability;
+    sort?: AgentDirectorySort;
+    order?: SortOrder;
+    cursor?: string;
+    limit?: number;
+    timeoutMs?: number;
+}
+export interface AgentDirectoryEntry {
+    agentId: string;
+    displayName?: string;
+    summary?: string;
+    capabilities?: string[];
+    domains?: string[];
+    score?: number;
+    reputation?: number;
+    completedTaskCount?: number;
+    availability?: AgentAvailability;
+    lastSeenAt?: number;
+}
+export interface AgentProfile {
+    agentId: string;
+    displayName?: string;
+    summary?: string;
+    capabilities?: string[];
+    domains?: string[];
+    reputation?: number;
+    completedTaskCount?: number;
+    availability?: AgentAvailability;
+    lastSeenAt?: number;
+}
+export interface AgentDirectoryPage {
+    items: AgentDirectoryEntry[];
+    nextCursor?: string;
+    hasMore: boolean;
+}
+export type AgentDirectoryFailureCode = 'capability_unavailable' | 'permission_denied' | 'hub_unavailable' | 'timeout' | 'invalid_request' | 'invalid_response';
+export interface AgentDirectoryFailure {
+    code: AgentDirectoryFailureCode;
+    retryable: boolean;
+    message?: string;
+}
+export type AgentDirectoryResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: AgentDirectoryFailure;
+};
+export interface AgentDirectoryCapability {
+    search(request: AgentSearchRequest): Promise<AgentDirectoryResult<AgentDirectoryPage>>;
+    getProfile(agentId: string, options?: {
+        timeoutMs?: number;
+    }): Promise<AgentDirectoryResult<AgentProfile | null>>;
+    discoverForTask(request: AgentTaskDiscoveryRequest): Promise<AgentDirectoryResult<AgentDirectoryPage>>;
+}
+export declare class AgentDirectoryInputError extends Error {
+    readonly code = "invalid_request";
+}
+export declare function normalizeAgentSearchRequest(input: AgentSearchRequest): Required<Pick<AgentSearchRequest, 'limit' | 'timeoutMs' | 'sort' | 'order'>> & AgentSearchRequest;
+export declare function normalizeAgentTaskDiscoveryRequest(input: AgentTaskDiscoveryRequest): AgentTaskDiscoveryRequest & Required<Pick<AgentTaskDiscoveryRequest, 'limit' | 'timeoutMs' | 'sort' | 'order'>>;
+export declare function normalizeAgentId(value: string): string;
+export declare function normalizeAgentDirectoryTimeout(value: number | undefined): number;
+export declare function capabilityUnavailable(message?: string): AgentDirectoryResult<never>;
+export declare function unsupportedAgentDirectoryCapability(message?: string): AgentDirectoryCapability;

package/dist/hub/agentDirectory.js

@@ -0,0 +1,104 @@
+export const AGENT_DIRECTORY_DEFAULT_LIMIT = 20;
+export const AGENT_DIRECTORY_MAX_LIMIT = 50;
+export const AGENT_DIRECTORY_DEFAULT_TIMEOUT_MS = 8_000;
+export const AGENT_DIRECTORY_MAX_TIMEOUT_MS = 30_000;
+export const AGENT_DIRECTORY_MAX_QUERY_LENGTH = 500;
+export const AGENT_DIRECTORY_MAX_SIGNAL_COUNT = 20;
+export const AGENT_DIRECTORY_MAX_SIGNAL_LENGTH = 64;
+export const AGENT_DIRECTORY_MAX_CURSOR_LENGTH = 256;
+export const AGENT_DIRECTORY_MAX_AGENT_ID_LENGTH = 128;
+export class AgentDirectoryInputError extends Error {
+    code = 'invalid_request';
+}
+export function normalizeAgentSearchRequest(input) {
+    const query = optionalText(input.query, 'query', AGENT_DIRECTORY_MAX_QUERY_LENGTH);
+    const signals = normalizeSignals(input.signals);
+    const availability = input.availability ? enumValue(input.availability, ['online', 'busy', 'offline', 'unknown'], 'availability') : undefined;
+    if (!query && signals.length === 0)
+        throw new AgentDirectoryInputError('query_or_signals_required');
+    return {
+        ...(query ? { query } : {}),
+        ...(signals.length > 0 ? { signals } : {}),
+        ...(availability ? { availability } : {}),
+        ...(input.cursor ? { cursor: requiredText(input.cursor, 'cursor', AGENT_DIRECTORY_MAX_CURSOR_LENGTH) } : {}),
+        limit: boundedInteger(input.limit, AGENT_DIRECTORY_DEFAULT_LIMIT, 1, AGENT_DIRECTORY_MAX_LIMIT, 'limit'),
+        timeoutMs: boundedInteger(input.timeoutMs, AGENT_DIRECTORY_DEFAULT_TIMEOUT_MS, 100, AGENT_DIRECTORY_MAX_TIMEOUT_MS, 'timeout_ms'),
+        sort: input.sort ? enumValue(input.sort, ['relevance', 'reputation', 'recent', 'availability'], 'sort') : 'relevance',
+        order: input.order ? enumValue(input.order, ['asc', 'desc'], 'order') : 'desc',
+    };
+}
+export function normalizeAgentTaskDiscoveryRequest(input) {
+    const title = requiredText(input.title, 'title', AGENT_DIRECTORY_MAX_QUERY_LENGTH);
+    const description = optionalText(input.description, 'description', AGENT_DIRECTORY_MAX_QUERY_LENGTH);
+    const search = normalizeAgentSearchRequest({
+        query: [title, description].filter(Boolean).join('\n'),
+        signals: input.signals,
+        availability: input.availability,
+        sort: input.sort,
+        order: input.order,
+        cursor: input.cursor,
+        limit: input.limit,
+        timeoutMs: input.timeoutMs,
+    });
+    return { ...search, title, ...(description ? { description } : {}) };
+}
+export function normalizeAgentId(value) {
+    return requiredText(value, 'agent_id', AGENT_DIRECTORY_MAX_AGENT_ID_LENGTH);
+}
+export function normalizeAgentDirectoryTimeout(value) {
+    return boundedInteger(value, AGENT_DIRECTORY_DEFAULT_TIMEOUT_MS, 100, AGENT_DIRECTORY_MAX_TIMEOUT_MS, 'timeout_ms');
+}
+export function capabilityUnavailable(message = 'agent_directory_not_supported') {
+    return { ok: false, error: { code: 'capability_unavailable', retryable: false, message } };
+}
+export function unsupportedAgentDirectoryCapability(message) {
+    return {
+        search: async () => capabilityUnavailable(message),
+        getProfile: async () => capabilityUnavailable(message),
+        discoverForTask: async () => capabilityUnavailable(message),
+    };
+}
+function normalizeSignals(input) {
+    if (input === undefined)
+        return [];
+    if (!Array.isArray(input))
+        throw new AgentDirectoryInputError('signals_must_be_array');
+    if (input.length > AGENT_DIRECTORY_MAX_SIGNAL_COUNT)
+        throw new AgentDirectoryInputError('too_many_signals');
+    const out = [];
+    for (const value of input) {
+        if (typeof value !== 'string')
+            throw new AgentDirectoryInputError('signal_must_be_string');
+        const signal = requiredText(value, 'signal', AGENT_DIRECTORY_MAX_SIGNAL_LENGTH);
+        if (!out.includes(signal))
+            out.push(signal);
+    }
+    return out;
+}
+function optionalText(value, field, maxLength) {
+    if (value === undefined)
+        return undefined;
+    return requiredText(value, field, maxLength);
+}
+function requiredText(value, field, maxLength) {
+    if (typeof value !== 'string')
+        throw new AgentDirectoryInputError(`${field}_must_be_string`);
+    const text = value.trim();
+    if (!text)
+        throw new AgentDirectoryInputError(`${field}_required`);
+    if (text.length > maxLength)
+        throw new AgentDirectoryInputError(`${field}_too_long`);
+    return text;
+}
+function boundedInteger(value, fallback, min, max, field) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || value < min || value > max)
+        throw new AgentDirectoryInputError(`${field}_out_of_range`);
+    return value;
+}
+function enumValue(value, allowed, field) {
+    if (!allowed.includes(value))
+        throw new AgentDirectoryInputError(`${field}_invalid`);
+    return value;
+}

package/dist/hub/bindings.js

@@ -19,7 +19,7 @@ function envelopeToAgentEvent(e) {
     const stableId = e.type === 'proxy_trace' && e.idempotencyKey ? e.idempotencyKey : e.id;
     return {
         id: stableId,
-        type: e.type,
+        type: e.type === 'dm_outbound' ? 'dm' : e.type,
         payload: e.payload,
         priority: 'medium',
         createdAt: e.createdAt,
@@ -59,10 +59,20 @@ export function makeHubBindings(cap, options = {}) {
                             throw new PublishRejectedError(r.status, r.terminal ?? true, r.reason);
                         return r;
                     }
-                    case 'task_claim': return cap.task.claim(String(e.payload.taskId ?? ''));
+                    case 'task_claim': {
+                        const p = e.payload;
+                        return cap.task.claim(firstString(p.taskId, p.task_id) ?? '');
+                    }
                     case 'task_complete': {
                         const p = e.payload;
-                        return cap.task.complete(String(p.claimId ?? ''), p.result);
+                        const taskId = firstString(p.taskId, p.task_id);
+                        const assetId = firstString(p.assetId, p.asset_id);
+                        const claimId = firstString(p.claimId, p.claim_id);
+                        if (!claimId) {
+                            throw new PublishRejectedError('invalid_task_complete', true, 'claim_id is required because task claim handles are opaque');
+                        }
+                        const context = taskId && assetId ? { taskId, assetId } : undefined;
+                        return cap.task.complete(claimId, p.result, context);
                     }
                     default:
                         // 其余 outbound(atp_*/heartbeat/...) 走 mailbox.push
@@ -87,4 +97,14 @@ export function makeHubBindings(cap, options = {}) {
             };
         },
     };
+}
+function firstString(...values) {
+    for (const value of values) {
+        if (typeof value !== 'string')
+            continue;
+        const trimmed = value.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return undefined;
 }

package/dist/hub/capability.d.ts

@@ -1,5 +1,6 @@
 import type { AssetRecord, AssetKind, SearchQuery, PutResult } from '../assetstore/provider.js';
 import type { Envelope } from '../mailbox/envelope.js';
+import type { AgentDirectoryCapability } from './agentDirectory.js';
 /** publish 投递回执. hub 侧做 gate(经济/治理/RBAC 全在 hub), core 只读 status+reason. */
 export interface PublishReceipt {
     /** hub 返回的回执 id(公版=AgentEvent/decision id; 私有=审计 id). */
@@ -34,6 +35,15 @@ export interface TaskEvent {
     priority: 'high' | 'medium' | 'low';
     createdAt: number;
 }
+/**
+ * Explicit task identity needed by hubs whose completion wire does not use their
+ * adapter-specific claim handle. claimId remains opaque and must never be parsed
+ * to recover either field.
+ */
+export interface TaskCompleteContext {
+    taskId: string;
+    assetId: string;
+}
 /** Proactive Hub question that a runtime may submit for ecosystem help. */
 export interface HubQuestion {
     question: string;
@@ -153,7 +163,7 @@ export interface RecipeCapability {
     get(recipeId: string): Promise<RecipeFetchReceipt>;
     express(recipeId: string, request?: RecipeExpressRequest): Promise<RecipeExpressionReceipt>;
 }
-export type HubCapabilityName = 'publish' | 'fetch' | 'search' | 'task' | 'mailbox' | 'auth' | 'audit' | 'air_gap' | 'tenant_isolation' | 'marketplace' | 'economy' | 'questions' | 'recipes';
+export type HubCapabilityName = 'publish' | 'fetch' | 'search' | 'task' | 'mailbox' | 'auth' | 'audit' | 'air_gap' | 'tenant_isolation' | 'marketplace' | 'economy' | 'questions' | 'recipes' | 'agent_directory';
 /** hub 能力清单(可选). core 据此动态适配 UI/行为, "按需耦合". */
 export interface HubManifest {
     capabilities: HubCapabilityName[] | string[];
@@ -232,7 +242,7 @@ export interface HubCapability {
         claim(taskId: string): Promise<{
             claimId: string;
         }>;
-        complete(claimId: string, result: unknown): Promise<{
+        complete(claimId: string, result: unknown, context?: TaskCompleteContext): Promise<{
             status: 'completed';
         }>;
         subscribe(filter: unknown): AsyncIterable<TaskEvent>;
@@ -243,6 +253,8 @@ export interface HubCapability {
     };
     /** Optional recipe/DNA seam. Recipe creation is draft-first; publishing remains explicit. */
     recipes?: RecipeCapability;
+    /** Optional agent discovery seam. Missing means the adapter does not support directory/profile discovery. */
+    agentDirectory?: AgentDirectoryCapability;
     /** mailbox 队列. poll/ack/push/status 四端点解耦(公版 /a2a/mailbox/*). */
     mailbox: {
         poll(): Promise<MailboxPollResult>;

package/dist/hub/fake.d.ts

@@ -1,4 +1,4 @@
-import type { HubCapability, PublishReceipt, AgentEvent, TaskEvent, AuthProvider, HubQuery, AssetRecord } from './capability.js';
+import type { HubCapability, PublishReceipt, AgentEvent, TaskEvent, AuthProvider, HubQuery, AssetRecord, TaskCompleteContext } from './capability.js';
 export interface FakeHubOptions {
     /** 脚本化 publish gate: 返回 reject/quarantine 以测 PublishReceipt 终态路径. */
     publishGate?: (asset: AssetRecord) => Pick<PublishReceipt, 'status' | 'reason' | 'terminal'>;
@@ -20,8 +20,10 @@ export declare class FakeHubCapability implements HubCapability {
     readonly completed: Array<{
         claimId: string;
         result: unknown;
+        context?: TaskCompleteContext;
     }>;
     readonly auth: AuthProvider;
+    agentDirectory?: import('./agentDirectory.js').AgentDirectoryCapability;
     nextPollAfterMs: number | undefined;
     constructor(opts?: FakeHubOptions);
     /** 测试注入: 排一条 inbound 事件供 poll 拉. */
@@ -33,7 +35,7 @@ export declare class FakeHubCapability implements HubCapability {
         claim: (taskId: string) => Promise<{
             claimId: string;
         }>;
-        complete: (claimId: string, result: unknown) => Promise<{
+        complete: (claimId: string, result: unknown, context?: TaskCompleteContext) => Promise<{
             status: "completed";
         }>;
         subscribe: (filter: unknown) => AsyncIterable<TaskEvent>;

package/dist/hub/fake.js

@@ -19,6 +19,7 @@ export class FakeHubCapability {
     claims = [];
     completed = [];
     auth = fakeAuth;
+    agentDirectory;
     nextPollAfterMs;
     constructor(opts = {}) {
         this.opts = opts;
@@ -42,8 +43,8 @@ export class FakeHubCapability {
             this.claims.push({ taskId, claimId });
             return { claimId };
         },
-        complete: async (claimId, result) => {
-            this.completed.push({ claimId, result });
+        complete: async (claimId, result, context) => {
+            this.completed.push({ claimId, result, ...(context ? { context } : {}) });
             return { status: 'completed' };
         },
         subscribe: async function* () {

package/dist/hub/index.d.ts

@@ -1,4 +1,5 @@
 export * from './capability.js';
+export * from './agentDirectory.js';
 export * from './fake.js';
 export * from './bindings.js';
 export * from './sanitize.js';

package/dist/hub/index.js

@@ -1,4 +1,5 @@
 export * from './capability.js';
+export * from './agentDirectory.js';
 export * from './fake.js';
 export * from './bindings.js';
 export * from './sanitize.js';

package/dist/mailbox/catalog.js

@@ -14,6 +14,7 @@ export const MESSAGE_CATALOG = {
     task_complete: { direction: 'outbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'default' },
     task_subscribe: { direction: 'outbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'control' },
     task_unsubscribe: { direction: 'outbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'control' },
+    dm_outbound: { direction: 'outbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'default' },
     atp_order: { direction: 'outbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'default' },
     atp_deliver: { direction: 'outbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'default' },
     atp_settle: { direction: 'outbound', handler: 'proxy', feedsMaterial: false, ttlClass: 'default' },
@@ -23,6 +24,8 @@ export const MESSAGE_CATALOG = {
     asset_publish_result: { direction: 'inbound', handler: 'core', feedsMaterial: false, ttlClass: 'default' }, // 拒绝进 Material 在 dispatch 决定
     pending_evomap_task: { direction: 'inbound', handler: 'agent', feedsMaterial: false, ttlClass: 'default' },
     task_available: { direction: 'inbound', handler: 'agent', feedsMaterial: false, ttlClass: 'default' },
+    task_claim_result: { direction: 'inbound', handler: 'agent', feedsMaterial: false, ttlClass: 'default' },
+    task_complete_result: { direction: 'inbound', handler: 'agent', feedsMaterial: false, ttlClass: 'default' },
     work_assigned: { direction: 'inbound', handler: 'agent', feedsMaterial: false, ttlClass: 'default' },
     dialog_message: { direction: 'inbound', handler: 'agent', feedsMaterial: true, ttlClass: 'default' },
     peer_review_request: { direction: 'inbound', handler: 'agent', feedsMaterial: true, ttlClass: 'default' },

package/dist/mailbox/ipcServer.js

@@ -69,7 +69,7 @@ export class MailboxIpcServer {
                     this.onAuthFailure?.();
                 }
                 catch { /* auth failure handling must never weaken fail-closed IPC auth */ }
-                return this.json(res, 401, { error: 'bad token' });
+                return this.json(res, 401, { error: 'Unauthorized', code: 'unauthorized' });
             }
             const url = new URL(req.url ?? '/', 'http://localhost');
             const route = `${req.method} ${url.pathname}`;
@@ -129,7 +129,7 @@ export class MailboxIpcServer {
             return this.json(res, 404, { error: 'unknown route' });
         }
         catch (e) {
-            return this.json(res, 400, { error: e instanceof Error ? e.message : String(e) });
+            return this.json(res, 400, { error: e instanceof Error ? e.message : String(e), code: 'invalid_request' });
         }
     }
     readJson(req) {

package/dist/mailbox/store.d.ts

@@ -22,8 +22,22 @@ export declare class MailboxStore {
         status?: Status;
         handler?: string;
         runtimeNamespace?: string;
+        type?: string;
+        direction?: Envelope['direction'];
+        typeDirections?: readonly {
+            type: string;
+            direction: Envelope['direction'];
+        }[];
+        newestFirst?: boolean;
+        offset?: number;
         limit?: number;
     }): Envelope[];
+    countMessages(opts?: {
+        status?: Status;
+        runtimeNamespace?: string;
+        type?: string;
+        direction?: Envelope['direction'];
+    }): number;
     countByStatus(status: Status): number;
     /** pending 计数(可按 handler/runtimeNamespace 分区), 用于 agent wake 去抖. */
     countPending(handler?: string, runtimeNamespace?: string): number;

package/dist/mailbox/store.js

@@ -120,6 +120,7 @@ export class MailboxStore {
       schemaVersion TEXT, feedsMaterial INTEGER, dlq INTEGER DEFAULT 0, leasedUntil INTEGER, workerId TEXT, lastError 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)');
     }
@@ -157,7 +158,21 @@ export class MailboxStore {
             where.push('runtimeNamespace = ?');
             args.push(opts.runtimeNamespace);
         }
-        const sql = `SELECT * FROM messages ${where.length ? `WHERE ${where.join(' AND ')}` : ''} ORDER BY createdAt LIMIT ?`;
+        if (opts.type) {
+            where.push('type = ?');
+            args.push(opts.type);
+        }
+        if (opts.direction) {
+            where.push('direction = ?');
+            args.push(opts.direction);
+        }
+        if (opts.typeDirections && opts.typeDirections.length > 0) {
+            const selectors = opts.typeDirections.slice(0, 20);
+            where.push(`(${selectors.map(() => '(type = ? AND direction = ?)').join(' OR ')})`);
+            for (const selector of selectors)
+                args.push(selector.type, selector.direction);
+        }
+        const sql = `SELECT * FROM messages ${where.length ? `WHERE ${where.join(' AND ')}` : ''} ORDER BY createdAt ${opts.newestFirst ? 'DESC' : 'ASC'} LIMIT ?`;
         // Clamp the LIMIT bind. The IPC list route feeds this `?limit=` straight from an external query string, so a
         // non-finite value (NaN from `?limit=abc`, Infinity from `?limit=1e400`) would bind as null/error and a huge
         // finite value is an unbounded read (memory DoS) even on the token-authed endpoint. Finite + positive + capped.
@@ -165,7 +180,34 @@ export class MailboxStore {
             ? Math.min(Math.floor(opts.limit), 10_000)
             : 1000;
         args.push(lim);
-        return this.db.prepare(sql).all(...args).map(rowToEnvelope);
+        const offset = Number.isFinite(opts.offset) && opts.offset > 0
+            ? Math.min(Math.floor(opts.offset), 10_000)
+            : 0;
+        const pagedSql = `${sql} OFFSET ?`;
+        args.push(offset);
+        return this.db.prepare(pagedSql).all(...args).map(rowToEnvelope);
+    }
+    countMessages(opts = {}) {
+        const where = [];
+        const args = [];
+        if (opts.status) {
+            where.push('status = ?');
+            args.push(opts.status);
+        }
+        if (opts.runtimeNamespace) {
+            where.push('runtimeNamespace = ?');
+            args.push(opts.runtimeNamespace);
+        }
+        if (opts.type) {
+            where.push('type = ?');
+            args.push(opts.type);
+        }
+        if (opts.direction) {
+            where.push('direction = ?');
+            args.push(opts.direction);
+        }
+        const row = this.db.prepare(`SELECT COUNT(*) c FROM messages ${where.length ? `WHERE ${where.join(' AND ')}` : ''}`).get(...args);
+        return Number(row['c']);
     }
     countByStatus(status) {
         return Number(this.db.prepare('SELECT COUNT(*) c FROM messages WHERE status = ?').get(status)['c']);

package/dist/material/consumer.js

@@ -11,9 +11,10 @@ export class ConsumerGroups {
         if (opts.path && existsSync(opts.path)) {
             try {
                 const o = JSON.parse(readFileSync(opts.path, 'utf8'));
-                for (const [k, v] of Object.entries(o))
-                    if (typeof v === 'number' && Number.isFinite(v))
+                for (const [k, v] of Object.entries(o)) {
+                    if (typeof v === 'number' && Number.isSafeInteger(v) && v >= 0)
                         this.committed.set(k, v);
+                }
             }
             catch { /* corrupt cursor → start from 0 (idempotent re-claim) */ }
         }
@@ -21,16 +22,18 @@ export class ConsumerGroups {
     cur(group) { return this.committed.get(group) ?? 0; }
     /** 取下一批未 ack 的 (不推进 committed → 崩溃重启再 claim 拿到同批). */
     claim(group, batchSize) {
-        const all = this.opts.store.readAll();
-        return all.slice(this.cur(group), this.cur(group) + batchSize);
+        return this.opts.store.readRange(this.cur(group), batchSize);
     }
     /** ack: 把 committed 推过 acked 的连续前缀. */
     ack(group, materialIds) {
         const ackSet = new Set(materialIds);
-        const all = this.opts.store.readAll();
         let c = this.cur(group);
-        while (c < all.length && ackSet.has(all[c].materialId))
+        const claimed = this.opts.store.readRange(c, ackSet.size);
+        for (const record of claimed) {
+            if (!ackSet.has(record.materialId))
+                break;
             c += 1;
+        }
         this.committed.set(group, c);
         this.persist();
     }

package/dist/material/index.d.ts

@@ -1,4 +1,5 @@
 export * from './materialStore.js';
+export * from './materialArchive.js';
 export * from './watermark.js';
 export * from './sources.js';
 export * from './consumer.js';

package/dist/material/index.js

@@ -1,4 +1,5 @@
 export * from './materialStore.js';
+export * from './materialArchive.js';
 export * from './watermark.js';
 export * from './sources.js';
 export * from './consumer.js';

package/dist/material/materialArchive.d.ts

@@ -0,0 +1,81 @@
+import { type Material } from '../schema/material.js';
+export declare const MATERIAL_ARCHIVE_DEFAULT_KEEP_RECORDS = 1000;
+export declare class InvalidMaterialLogError extends Error {
+    readonly line: number;
+    readonly code = "MATERIAL_ARCHIVE_INVALID_LOG";
+    constructor(line: number, reason: string);
+}
+export declare class InvalidMaterialArchiveError extends Error {
+    readonly segment: string;
+    readonly line: number;
+    readonly code = "MATERIAL_ARCHIVE_INVALID_ARCHIVE";
+    constructor(segment: string, line: number, reason: string);
+}
+export declare class MaterialArchiveRangeError extends Error {
+    readonly code = "MATERIAL_ARCHIVE_RANGE_INVALID";
+    constructor(reason: string);
+}
+export declare class MaterialArchiveSegmentConflictError extends Error {
+    readonly archiveId: string;
+    readonly code = "MATERIAL_ARCHIVE_SEGMENT_CONFLICT";
+    constructor(archiveId: string);
+}
+export declare class InvalidMaterialArchiveCursorError extends Error {
+    readonly code = "MATERIAL_ARCHIVE_CURSOR_INVALID";
+    constructor(reason: string);
+}
+export interface MaterialArchiveOptions {
+    path: string;
+    cursorPaths?: readonly string[];
+    keepRecords?: number;
+}
+export interface MaterialArchiveCursor {
+    group: string;
+    position: number;
+}
+export interface MaterialArchivePlan {
+    mode: 'preview';
+    activeRecords: number;
+    physicalActiveRecords: number;
+    archiveRecords: number;
+    historyRecords: number;
+    keepRecords: number;
+    minCursor: number;
+    cursors: MaterialArchiveCursor[];
+    overlapRecords: number;
+    wouldArchive: number;
+    retainedRecords: number;
+    archiveId: string | null;
+}
+export interface MaterialArchiveResult {
+    mode: 'write';
+    activeRecordsBefore: number;
+    physicalActiveRecordsBefore: number;
+    keepRecords: number;
+    minCursor: number;
+    cursors: MaterialArchiveCursor[];
+    archivedRecords: number;
+    retainedRecords: number;
+    archiveRecords: number;
+    historyRecords: number;
+    recoveredOverlap: number;
+    archiveId: string | null;
+}
+export interface MaterialArchiveStats {
+    exists: boolean;
+    segments: number;
+    bytes: number;
+    records: number;
+    invalidLines: number;
+    firstOffset: number | null;
+    lastOffset: number | null;
+}
+export declare function materialArchiveDir(path: string): string;
+export declare function materialArchiveSegmentName(start: number, end: number): string;
+export declare function planMaterialArchive(opts: MaterialArchiveOptions): MaterialArchivePlan;
+export declare function archiveMaterialStore(opts: MaterialArchiveOptions): MaterialArchiveResult;
+/** Operational, fail-soft full history reader. Strict archive writes validate every line and range. */
+export declare function readMaterialHistory(path: string): Material[];
+/** Absolute-offset range reader used by durable consumers after active records move into archive segments. */
+export declare function readMaterialRange(path: string, start: number, count: number): Material[];
+export declare function inspectMaterialArchive(path: string): MaterialArchiveStats;