@evomap/evolver-core 2.0.0-beta.0

package/dist/mailbox/store.js

@@ -0,0 +1,308 @@
+import { mkdirSync, existsSync, openSync, readSync, closeSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createRequire } from 'node:module';
+import { ulid as makeUlid } from 'ulid';
+import { createEnvelope } from './envelope.js';
+// node:sqlite 是较新内建，只暴露 `node:sqlite`（无 `sqlite` 裸别名）。
+// 经 createRequire 动态加载，避免打包器静态剥前缀成 `sqlite` 后解析失败（vitest/vite）。
+const nodeRequire = createRequire(import.meta.url);
+const { DatabaseSync } = nodeRequire('node:sqlite');
+export const MAX_ATTEMPTS = 5;
+export const DEFAULT_IMPORT_JSONL_MAX_LINE_BYTES = 16 * 1024 * 1024;
+const JSONL_READ_CHUNK_BYTES = 64 * 1024;
+export function expBackoffMs(attempt) {
+    return Math.min(4000 * 2 ** (attempt - 1), 5 * 60 * 1000); // 4s→8s→…→5min
+}
+function forEachJsonlRecord(path, onRecord) {
+    if (!existsSync(path))
+        return;
+    const maxLineBytes = Number.isFinite(Number(process.env['EVOLVER_IMPORT_JSONL_MAX_LINE_BYTES']))
+        && Number(process.env['EVOLVER_IMPORT_JSONL_MAX_LINE_BYTES']) > 0
+        ? Math.floor(Number(process.env['EVOLVER_IMPORT_JSONL_MAX_LINE_BYTES']))
+        : DEFAULT_IMPORT_JSONL_MAX_LINE_BYTES;
+    const buf = Buffer.allocUnsafe(JSONL_READ_CHUNK_BYTES);
+    let fd;
+    let parts = [];
+    let lineBytes = 0;
+    let dropping = false;
+    const reset = () => { parts = []; lineBytes = 0; dropping = false; };
+    const append = (segment) => {
+        if (dropping || segment.length === 0)
+            return;
+        if (lineBytes + segment.length > maxLineBytes) {
+            reset();
+            dropping = true;
+            return;
+        }
+        parts.push(Buffer.from(segment));
+        lineBytes += segment.length;
+    };
+    const finish = () => {
+        if (dropping || lineBytes === 0) {
+            reset();
+            return;
+        }
+        const text = Buffer.concat(parts, lineBytes).toString('utf8').trim();
+        reset();
+        if (!text)
+            return;
+        try {
+            onRecord(JSON.parse(text));
+        }
+        catch { /* skip corrupt rows */ }
+    };
+    try {
+        fd = openSync(path, 'r');
+        for (;;) {
+            const bytes = readSync(fd, buf, 0, buf.length, null);
+            if (bytes <= 0)
+                break;
+            let start = 0;
+            for (let i = 0; i < bytes; i += 1) {
+                if (buf[i] !== 0x0a)
+                    continue;
+                append(buf.subarray(start, i));
+                finish();
+                start = i + 1;
+            }
+            if (start < bytes)
+                append(buf.subarray(start, bytes));
+        }
+        finish();
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function rowToEnvelope(r) {
+    return {
+        id: r['id'], type: r['type'], direction: r['direction'],
+        status: r['status'], handler: r['handler'],
+        payload: r['payload'] ? JSON.parse(r['payload']) : {},
+        correlationId: r['correlationId'], replyTo: r['replyTo'] ?? null,
+        receiptId: r['receiptId'], idempotencyKey: r['idempotencyKey'],
+        sourceAgent: r['sourceAgent'], targetAgent: r['targetAgent'],
+        runtimeNamespace: r['runtimeNamespace'],
+        attempts: r['attempts'], nextRetryAt: r['nextRetryAt'] ?? null,
+        ttlAt: r['ttlAt'] ?? null,
+        createdAt: r['createdAt'], updatedAt: r['updatedAt'],
+        schemaVersion: r['schemaVersion'], feedsMaterial: Boolean(r['feedsMaterial']),
+    };
+}
+/** mailbox sqlite 引擎 (WAL + busy_timeout). 状态机 pending→in_flight→done/failed/expired + 租约 + 重试/DLQ. */
+export class MailboxStore {
+    db;
+    constructor(opts) {
+        mkdirSync(dirname(opts.path), { recursive: true });
+        this.db = new DatabaseSync(opts.path);
+        this.db.exec('PRAGMA journal_mode = WAL');
+        // PRAGMA can't be parameterized, so the value is string-interpolated — sanitize to a non-negative integer
+        // first so a non-numeric busyTimeoutMs can never become SQL injection (defense-in-depth; #196).
+        const rawBusy = Number(opts.busyTimeoutMs ?? 5000);
+        const busyTimeoutMs = Number.isFinite(rawBusy) ? Math.max(0, Math.floor(rawBusy)) : 5000;
+        this.db.exec(`PRAGMA busy_timeout = ${busyTimeoutMs}`);
+        this.db.exec(`CREATE TABLE IF NOT EXISTS messages (
+      id TEXT PRIMARY KEY, type TEXT, direction TEXT, status TEXT, handler TEXT,
+      payload TEXT, correlationId TEXT, replyTo TEXT, receiptId TEXT, idempotencyKey TEXT,
+      sourceAgent TEXT, targetAgent TEXT, runtimeNamespace TEXT,
+      attempts INTEGER, nextRetryAt INTEGER, ttlAt INTEGER, createdAt INTEGER, updatedAt INTEGER,
+      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 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)');
+    }
+    /** 通用 KV 状态(M6: sync 游标 inbound_cursor / lifecycle reauth 退避 / node_id 等). */
+    getState(key) {
+        const r = this.db.prepare('SELECT v FROM kv WHERE k=?').get(key);
+        return r ? r['v'] : undefined;
+    }
+    setState(key, value) {
+        this.db.prepare('INSERT INTO kv (k,v) VALUES (?,?) ON CONFLICT(k) DO UPDATE SET v=excluded.v').run(key, value);
+    }
+    /** 投递; 同 id 幂等(OR IGNORE). 返回 receiptId. */
+    send(e) {
+        const r = this.db.prepare(`INSERT OR IGNORE INTO messages
+      (id,type,direction,status,handler,payload,correlationId,replyTo,receiptId,idempotencyKey,sourceAgent,targetAgent,runtimeNamespace,attempts,nextRetryAt,ttlAt,createdAt,updatedAt,schemaVersion,feedsMaterial,dlq)
+      VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,0)`).run(e.id, e.type, e.direction, e.status, e.handler, JSON.stringify(e.payload), e.correlationId, e.replyTo, e.receiptId, e.idempotencyKey, e.sourceAgent, e.targetAgent, e.runtimeNamespace, e.attempts, e.nextRetryAt, e.ttlAt, e.createdAt, e.updatedAt, e.schemaVersion, e.feedsMaterial ? 1 : 0);
+        return { receiptId: e.id, stored: Number(r.changes) > 0 };
+    }
+    getById(id) {
+        const r = this.db.prepare('SELECT * FROM messages WHERE id = ?').get(id);
+        return r ? rowToEnvelope(r) : undefined;
+    }
+    list(opts = {}) {
+        const where = [];
+        const args = [];
+        if (opts.status) {
+            where.push('status = ?');
+            args.push(opts.status);
+        }
+        if (opts.handler) {
+            where.push('handler = ?');
+            args.push(opts.handler);
+        }
+        if (opts.runtimeNamespace) {
+            where.push('runtimeNamespace = ?');
+            args.push(opts.runtimeNamespace);
+        }
+        const sql = `SELECT * FROM messages ${where.length ? `WHERE ${where.join(' AND ')}` : ''} ORDER BY createdAt 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.
+        const lim = Number.isFinite(opts.limit) && opts.limit > 0
+            ? Math.min(Math.floor(opts.limit), 10_000)
+            : 1000;
+        args.push(lim);
+        return this.db.prepare(sql).all(...args).map(rowToEnvelope);
+    }
+    countByStatus(status) {
+        return Number(this.db.prepare('SELECT COUNT(*) c FROM messages WHERE status = ?').get(status)['c']);
+    }
+    /** pending 计数(可按 handler/runtimeNamespace 分区), 用于 agent wake 去抖. */
+    countPending(handler, runtimeNamespace) {
+        const where = ["status='pending'", 'dlq=0'];
+        const args = [];
+        if (handler !== undefined) {
+            where.push('handler=?');
+            args.push(handler);
+        }
+        if (runtimeNamespace !== undefined) {
+            where.push('runtimeNamespace=?');
+            args.push(runtimeNamespace);
+        }
+        return Number(this.db.prepare(`SELECT COUNT(*) c FROM messages WHERE ${where.join(' AND ')}`).get(...args)['c']);
+    }
+    /** 只统计「现在就能 claim」的出站, 供 cadence 判定, 避免 deferred 拉低 idle 退避.
+     *  谓词须与 claim() 对齐: 到点 pending + 租约过期的 in_flight 孤儿; 否则孤儿出站(claim 能回收却不被计)会被误判 idle, 恢复最多慢一个 idle 周期. */
+    countClaimable(handler, now, runtimeNamespace) {
+        const where = ['dlq=0', 'handler=?', "(status='pending' OR (status='in_flight' AND leasedUntil < ?))", '(nextRetryAt IS NULL OR nextRetryAt <= ?)'];
+        const args = [handler, now, now];
+        if (runtimeNamespace !== undefined) {
+            where.push('runtimeNamespace=?');
+            args.push(runtimeNamespace);
+        }
+        return Number(this.db.prepare(`SELECT COUNT(*) c FROM messages WHERE ${where.join(' AND ')}`).get(...args)['c']);
+    }
+    hasMessageWithIdempotencyKey(idempotencyKey) {
+        return this.db.prepare('SELECT 1 FROM messages WHERE idempotencyKey = ? LIMIT 1').get(idempotencyKey) !== undefined;
+    }
+    hasMessageWithPayload(type, payload) {
+        return this.db.prepare('SELECT 1 FROM messages WHERE type = ? AND payload = ? LIMIT 1')
+            .get(type, JSON.stringify(payload)) !== undefined;
+    }
+    /** 原子 claim: pending(或租约过期的 in_flight) → in_flight + 租约. 可按 runtimeNamespace 分区. */
+    claim(handler, limit, leaseMs, now, runtimeNamespace) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const nsClause = runtimeNamespace !== undefined ? ' AND runtimeNamespace=?' : '';
+            const nsArgs = runtimeNamespace !== undefined ? [runtimeNamespace] : [];
+            const rows = this.db.prepare(`SELECT * FROM messages WHERE handler=? AND dlq=0
+         AND (status='pending' OR (status='in_flight' AND leasedUntil < ?))
+         AND (nextRetryAt IS NULL OR nextRetryAt <= ?)${nsClause}
+         ORDER BY createdAt LIMIT ?`).all(handler, now, now, ...nsArgs, limit);
+            const workerId = makeUlid();
+            const upd = this.db.prepare(`UPDATE messages SET status='in_flight', leasedUntil=?, workerId=?, updatedAt=? WHERE id=?`);
+            for (const r of rows)
+                upd.run(now + leaseMs, workerId, now, r['id']);
+            this.db.exec('COMMIT');
+            return rows.map((r) => ({ ...rowToEnvelope(r), status: 'in_flight' }));
+        }
+        catch (e) {
+            this.db.exec('ROLLBACK');
+            throw e;
+        }
+    }
+    complete(id, now) {
+        this.db.prepare(`UPDATE messages SET status='done', leasedUntil=NULL, workerId=NULL, updatedAt=? WHERE id=?`).run(now, id);
+    }
+    /** 失败: attempts<N→退避回 pending; ≥N→DLQ(不自动丢). */
+    fail(id, err, now, maxAttempts = MAX_ATTEMPTS) {
+        const m = this.getById(id);
+        if (!m)
+            return;
+        const attempts = m.attempts + 1;
+        if (attempts >= maxAttempts) {
+            this.db.prepare(`UPDATE messages SET status='failed', dlq=1, attempts=?, lastError=?, leasedUntil=NULL, updatedAt=? WHERE id=?`).run(attempts, err, now, id);
+        }
+        else {
+            this.db.prepare(`UPDATE messages SET status='pending', attempts=?, nextRetryAt=?, lastError=?, leasedUntil=NULL, workerId=NULL, updatedAt=? WHERE id=?`)
+                .run(attempts, now + expBackoffMs(attempts), err, now, id);
+        }
+    }
+    /** 暂缓: transient upstream outage 不消耗 attempts, 仅设置下次可 claim 时间. */
+    defer(id, err, now, retryAfterMs) {
+        const delay = Math.max(0, Number.isFinite(retryAfterMs) ? retryAfterMs : 0);
+        this.db.prepare(`UPDATE messages SET status='pending', nextRetryAt=?, lastError=?, leasedUntil=NULL, workerId=NULL, updatedAt=? WHERE id=?`)
+            .run(now + delay, err, now, id);
+    }
+    /** DLQ 重放(人工/agent 显式, 不自动丢). */
+    replayDlq(id, now) {
+        this.db.prepare(`UPDATE messages SET status='pending', dlq=0, attempts=0, nextRetryAt=NULL, leasedUntil=NULL, updatedAt=? WHERE id=?`).run(now, id);
+    }
+    dlq() { return this.db.prepare('SELECT * FROM messages WHERE dlq=1').all().map(rowToEnvelope); }
+    /** TTL 扫描: ttlAt 过期且未 done/dlq → expired. */
+    expireOld(now) {
+        const r = this.db.prepare(`UPDATE messages SET status='expired', updatedAt=? WHERE ttlAt < ? AND status NOT IN ('done','expired') AND dlq=0`).run(now, now);
+        return Number(r.changes);
+    }
+    /** M2-5 关联线程: 同 correlationId 全部消息(请求+应答), 按 createdAt 排序. */
+    findByCorrelation(correlationId) {
+        return this.db.prepare('SELECT * FROM messages WHERE correlationId=? ORDER BY createdAt').all(correlationId).map(rowToEnvelope);
+    }
+    /** 关联线程中除 requestId 外最新一条 = 应答(durable, 跨重启/进程). */
+    getReply(correlationId, requestId) {
+        const r = this.db.prepare('SELECT * FROM messages WHERE correlationId=? AND id<>? ORDER BY createdAt DESC LIMIT 1').get(correlationId, requestId);
+        return r ? rowToEnvelope(r) : undefined;
+    }
+    /** 构造并投递一条对 `to` 的应答(继承 correlationId, 收发方对调, replyTo 清空). */
+    reply(to, replyType, payload, now, over = {}) {
+        const env = createEnvelope({
+            type: replyType,
+            payload,
+            correlationId: to.correlationId,
+            sourceAgent: to.targetAgent,
+            targetAgent: to.sourceAgent,
+            runtimeNamespace: to.runtimeNamespace,
+            replyTo: null,
+            now,
+            ...over,
+        });
+        const res = this.send(env);
+        return { envelope: env, ...res };
+    }
+    /** M2-5 轻量状态视图(运维/IPC 查询用). */
+    getStatus(id) {
+        const r = this.db.prepare('SELECT id,type,status,attempts,nextRetryAt,ttlAt,dlq FROM messages WHERE id=?').get(id);
+        if (!r)
+            return undefined;
+        return {
+            id: r['id'], type: r['type'], status: r['status'],
+            attempts: Number(r['attempts']), nextRetryAt: r['nextRetryAt'] ?? null,
+            ttlAt: r['ttlAt'] ?? null, dlq: Number(r['dlq']) === 1,
+        };
+    }
+    /** 幂等(A13): 副作用 handler 用 idempotencyKey 去重; 命中返缓存不重跑. */
+    isProcessed(key) { return this.db.prepare('SELECT 1 FROM idempotency WHERE key=?').get(key) !== undefined; }
+    getProcessed(key) {
+        const r = this.db.prepare('SELECT result FROM idempotency WHERE key=?').get(key);
+        return r ? JSON.parse(r['result']) : undefined;
+    }
+    markProcessed(key, result, now) {
+        this.db.prepare('INSERT OR IGNORE INTO idempotency (key,result,at) VALUES (?,?,?)').run(key, JSON.stringify(result ?? null), now);
+    }
+    /** v1 messages.jsonl → sqlite 迁移(幂等可重入). */
+    importJsonl(path) {
+        let n = 0;
+        forEachJsonlRecord(path, (record) => {
+            try {
+                if (this.send(record).stored)
+                    n += 1;
+            }
+            catch { /* skip */ }
+        });
+        return n;
+    }
+    close() { this.db.close(); }
+}

package/dist/mailbox/wake.d.ts

@@ -0,0 +1,45 @@
+import type { MailboxStore } from './store.js';
+export type WakeMode = 'resident' | 'one-shot';
+export type WakeAction = 'signal' | 'spawn' | 'none';
+/** 一个 runtime 实例的唤醒目标(常驻 vs 一次性). */
+export interface WakeTarget {
+    runtimeNamespace: string;
+    mode: WakeMode;
+    /** resident: 唤醒已跑进程(本地信号/写 wake 文件/HTTP poke). */
+    signal?: () => Promise<void> | void;
+    /** one-shot 或 resident 已死: 拉起进程(spawn `claude` 等). */
+    spawn?: () => Promise<void> | void;
+    /** resident 存活探测; 返回 false → 回退到 spawn. 默认视为存活. */
+    isAlive?: () => boolean;
+}
+export interface AgentWakerDeps {
+    store: MailboxStore;
+    /** 静态列表或每次 tick 动态求值(runtime 注册/注销). */
+    targets: WakeTarget[] | (() => WakeTarget[]);
+    /** 同 namespace 最小唤醒间隔(去抖, 默认 2s). */
+    cooldownMs?: number;
+    now: () => number;
+}
+export interface WakeOutcome {
+    runtimeNamespace: string;
+    action: WakeAction;
+    pending: number;
+    reason?: string;
+}
+/**
+ * Agent 唤醒器(M2-8). 监视各 namespace 的 pending agent 消息, 去抖后唤醒 runtime:
+ * - resident 且存活 → signal(轻量 poke).
+ * - one-shot 或 resident 已死 → spawn(拉起进程).
+ * runtime 起来后经 IPC(M2-6) claim('agent') 自取消息.
+ */
+export declare class AgentWaker {
+    private readonly deps;
+    private readonly lastWake;
+    private readonly cooldownMs;
+    constructor(deps: AgentWakerDeps);
+    private resolveTargets;
+    /** 扫一轮: 对有 pending agent 工作且过了冷却的 namespace 触发唤醒. */
+    tick(): Promise<WakeOutcome[]>;
+    /** 测试/强制: 清冷却(下次 tick 必唤醒). */
+    resetCooldown(runtimeNamespace?: string): void;
+}

package/dist/mailbox/wake.js

@@ -0,0 +1,60 @@
+/**
+ * Agent 唤醒器(M2-8). 监视各 namespace 的 pending agent 消息, 去抖后唤醒 runtime:
+ * - resident 且存活 → signal(轻量 poke).
+ * - one-shot 或 resident 已死 → spawn(拉起进程).
+ * runtime 起来后经 IPC(M2-6) claim('agent') 自取消息.
+ */
+export class AgentWaker {
+    deps;
+    lastWake = new Map();
+    cooldownMs;
+    constructor(deps) {
+        this.deps = deps;
+        this.cooldownMs = deps.cooldownMs ?? 2000;
+    }
+    resolveTargets() {
+        return typeof this.deps.targets === 'function' ? this.deps.targets() : this.deps.targets;
+    }
+    /** 扫一轮: 对有 pending agent 工作且过了冷却的 namespace 触发唤醒. */
+    async tick() {
+        const now = this.deps.now();
+        const out = [];
+        for (const t of this.resolveTargets()) {
+            const pending = this.deps.store.countPending('agent', t.runtimeNamespace);
+            if (pending === 0) {
+                out.push({ runtimeNamespace: t.runtimeNamespace, action: 'none', pending, reason: 'idle' });
+                continue;
+            }
+            const last = this.lastWake.get(t.runtimeNamespace) ?? -Infinity;
+            if (now - last < this.cooldownMs) {
+                out.push({ runtimeNamespace: t.runtimeNamespace, action: 'none', pending, reason: 'cooldown' });
+                continue;
+            }
+            const alive = t.mode === 'resident' && (t.isAlive ? t.isAlive() : true);
+            let action = 'none';
+            if (alive && t.signal) {
+                await t.signal();
+                action = 'signal';
+            }
+            else if (t.spawn) {
+                await t.spawn();
+                action = 'spawn';
+            }
+            else if (t.signal) {
+                await t.signal();
+                action = 'signal';
+            } // 无 spawn 回退 signal
+            if (action !== 'none')
+                this.lastWake.set(t.runtimeNamespace, now);
+            out.push({ runtimeNamespace: t.runtimeNamespace, action, pending });
+        }
+        return out;
+    }
+    /** 测试/强制: 清冷却(下次 tick 必唤醒). */
+    resetCooldown(runtimeNamespace) {
+        if (runtimeNamespace)
+            this.lastWake.delete(runtimeNamespace);
+        else
+            this.lastWake.clear();
+    }
+}

package/dist/material/boundary.d.ts

@@ -0,0 +1,7 @@
+export declare class MaterialBoundaryError extends Error {
+    constructor(msg: string);
+}
+export declare function assertMaterialSource(m: {
+    sourcePath: string;
+    kind: string;
+}): void;

package/dist/material/boundary.js

@@ -0,0 +1,14 @@
+/** 来源边界 (批注#37): Material 只来自 session/tool log, 杜绝 root_events/asset/MV 回灌. */
+const FORBIDDEN = [
+    /root_events\.jsonl/, /genes\.jsonl/, /capsules\.jsonl/, /\bevents\.jsonl/,
+    /[/\\]mv[/\\]/, /[/\\]assets[/\\]/,
+];
+export class MaterialBoundaryError extends Error {
+    constructor(msg) { super(`来源边界违规: ${msg}`); this.name = 'MaterialBoundaryError'; }
+}
+export function assertMaterialSource(m) {
+    if (m.kind !== 'session_log' && m.kind !== 'tool_event' && m.kind !== 'llm_trace')
+        throw new MaterialBoundaryError(`非法 kind: ${m.kind} (只允许 session_log/tool_event/llm_trace)`);
+    if (FORBIDDEN.some((re) => re.test(m.sourcePath)))
+        throw new MaterialBoundaryError(`禁止把资产/事件层回灌为 Material: ${m.sourcePath}`);
+}

package/dist/material/consumer.d.ts

@@ -0,0 +1,21 @@
+import type { MaterialStore } from './materialStore.js';
+import type { Material } from '../schema/material.js';
+export interface ConsumerOptions {
+    store: MaterialStore;
+    path?: string;
+}
+/** consumer group + 进度游标 (at-least-once): committed 仅 ack 后推进, 防重复消费. */
+export declare class ConsumerGroups {
+    private readonly opts;
+    private readonly committed;
+    constructor(opts: ConsumerOptions);
+    private cur;
+    /** 取下一批未 ack 的 (不推进 committed → 崩溃重启再 claim 拿到同批). */
+    claim(group: string, batchSize: number): Material[];
+    /** ack: 把 committed 推过 acked 的连续前缀. */
+    ack(group: string, materialIds: string[]): void;
+    /** reset: 'earliest' 重放全部历史 / 指定 index. */
+    reset(group: string, to: 'earliest' | number): void;
+    position(group: string): number;
+    private persist;
+}

package/dist/material/consumer.js

@@ -0,0 +1,52 @@
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+/** consumer group + 进度游标 (at-least-once): committed 仅 ack 后推进, 防重复消费. */
+export class ConsumerGroups {
+    opts;
+    committed = new Map();
+    constructor(opts) {
+        this.opts = opts;
+        // A corrupt cursor (a crash mid-persist) must NOT crash the resident daemon at startup: degrade to empty
+        // (re-claim from 0). At-least-once + idempotent downstream make re-processing safe, far better than a crash loop.
+        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))
+                        this.committed.set(k, v);
+            }
+            catch { /* corrupt cursor → start from 0 (idempotent re-claim) */ }
+        }
+    }
+    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);
+    }
+    /** 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))
+            c += 1;
+        this.committed.set(group, c);
+        this.persist();
+    }
+    /** reset: 'earliest' 重放全部历史 / 指定 index. */
+    reset(group, to) {
+        this.committed.set(group, to === 'earliest' ? 0 : to);
+        this.persist();
+    }
+    position(group) { return this.cur(group); }
+    persist() {
+        if (!this.opts.path)
+            return;
+        mkdirSync(dirname(this.opts.path), { recursive: true });
+        // Atomic write: a crash mid-write must leave the OLD cursor intact, not a truncated/corrupt file.
+        const tmp = `${this.opts.path}.tmp`;
+        writeFileSync(tmp, JSON.stringify(Object.fromEntries(this.committed)));
+        renameSync(tmp, this.opts.path);
+    }
+}

package/dist/material/emit.d.ts

@@ -0,0 +1,55 @@
+import type { Material } from '../schema/material.js';
+export interface MailboxEnvelope {
+    type: string;
+    payload: unknown;
+}
+/** M2 mailbox 引擎的最小接口; M1 用 jsonl 兜底, M2 替换(接口不变). */
+export interface MailboxSink {
+    enqueue(e: MailboxEnvelope): Promise<{
+        receiptId: string;
+    }>;
+}
+/** material 事件 payload (批注#40). source_agent 仅 runtime_session 有 (proxy trace agent-无关, #95). */
+export interface MaterialEventPayload {
+    material_id: string;
+    source_agent?: string;
+    source_kind: string;
+    source_path: string;
+    kind: string;
+    size: number;
+    hash: string;
+    discovered_at: string;
+}
+export declare function toMaterialEventPayload(m: Material): MaterialEventPayload;
+/** jsonl 兜底 MailboxSink (M2 落地后替换为真引擎). */
+export declare class JsonlMailboxSink implements MailboxSink {
+    private readonly path;
+    constructor(path: string);
+    enqueue(e: MailboxEnvelope): Promise<{
+        receiptId: string;
+    }>;
+    readAll(): Array<{
+        receiptId: string;
+        type: string;
+        payload: unknown;
+    }>;
+}
+/** 攒批 + 投递 pending_materials (批注#40, mailbox 草案 §4). */
+export declare class MaterialEmitter {
+    private readonly sink;
+    private readonly batchSize;
+    private readonly buffer;
+    constructor(sink: MailboxSink, batchSize?: number);
+    add(m: Material): void;
+    size(): number;
+    flush(): Promise<{
+        receiptId: string;
+        batchId: string;
+        count: number;
+    } | null>;
+    addAndMaybeFlush(m: Material): Promise<{
+        receiptId: string;
+        batchId: string;
+        count: number;
+    } | null>;
+}

package/dist/material/emit.js

@@ -0,0 +1,52 @@
+import { appendFileSync, existsSync, readFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { ulid as makeUlid } from 'ulid';
+export function toMaterialEventPayload(m) {
+    return {
+        material_id: m.materialId, ...(m.sourceAgent ? { source_agent: m.sourceAgent } : {}), source_kind: m.sourceKind,
+        source_path: m.sourcePath,
+        kind: m.kind, size: m.watermark.size, hash: m.watermark.contentHash ?? '', discovered_at: m.capturedAt,
+    };
+}
+/** jsonl 兜底 MailboxSink (M2 落地后替换为真引擎). */
+export class JsonlMailboxSink {
+    path;
+    constructor(path) {
+        this.path = path;
+        mkdirSync(dirname(path), { recursive: true });
+    }
+    async enqueue(e) {
+        const receiptId = makeUlid();
+        appendFileSync(this.path, `${JSON.stringify({ receiptId, ...e })}\n`);
+        return { receiptId };
+    }
+    readAll() {
+        if (!existsSync(this.path))
+            return [];
+        return readFileSync(this.path, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+    }
+}
+/** 攒批 + 投递 pending_materials (批注#40, mailbox 草案 §4). */
+export class MaterialEmitter {
+    sink;
+    batchSize;
+    buffer = [];
+    constructor(sink, batchSize = 20) {
+        this.sink = sink;
+        this.batchSize = batchSize;
+    }
+    add(m) { this.buffer.push(toMaterialEventPayload(m)); }
+    size() { return this.buffer.length; }
+    async flush() {
+        if (this.buffer.length === 0)
+            return null;
+        const batchId = makeUlid();
+        const materials = this.buffer.splice(0);
+        const { receiptId } = await this.sink.enqueue({ type: 'pending_materials', payload: { batchId, materials } });
+        return { receiptId, batchId, count: materials.length };
+    }
+    async addAndMaybeFlush(m) {
+        this.add(m);
+        return this.buffer.length >= this.batchSize ? this.flush() : null;
+    }
+}

package/dist/material/factory.d.ts

@@ -0,0 +1,27 @@
+import { type Material } from '../schema/material.js';
+import type { SourceAgent } from '../schema/common.js';
+import type { Watermark } from '../schema/material.js';
+/** Fresh ULID for a Material record. Kept in core so the ULID constraint lives next to the schema. */
+export declare function newMaterialId(): string;
+export interface BuildMaterialInput {
+    /** Runtime agent for a session/tool source. Omit for an agent-agnostic origin (proxy trace), #95. */
+    sourceAgent?: SourceAgent;
+    /** Origin class (#95). Defaults to runtime_session (the only pre-#95 origin). */
+    sourceKind?: 'runtime_session' | 'proxy_trace';
+    sourcePath: string;
+    kind: 'session_log' | 'tool_event' | 'llm_trace';
+    watermark: Watermark;
+    consumerGroup: string;
+    payload?: unknown;
+    /** Injected for determinism in tests; defaults to a fresh ULID. */
+    materialId?: string;
+    /** Injected for determinism in tests; defaults to wall-clock ISO time. */
+    capturedAt?: string;
+}
+/**
+ * Build a schema-valid Material from a recording event. The composition layer (CLI) owns the source content;
+ * core owns the record shape + id/clock generation. Re-record idempotency is the caller's concern (see the
+ * file watermark cursor): identical content yields a fresh materialId here, so dedup must gate the call, not
+ * the build (a Material's identity is its ULID, not its content — that is the M1 substrate's design).
+ */
+export declare function buildMaterial(input: BuildMaterialInput): Material;