@lqc123qwe/car-runtime 1.9.0 → 1.11.0

package/dist/session/indexStore.js

@@ -0,0 +1,265 @@
+/**
+ * C-02 会话索引（§3.2.M7.2 索引行 + §3.2.M7.5 Step 3「异步可容忍，丢失可 rebuild」）
+ *
+ * 口径：
+ *  - node:sqlite 能力探测（22.5+ 需 --experimental-sqlite / 23.4+ 原生）；不可用 = CAR-E-SQLITE 显式拒绝，非静默；
+ *  - rebuild 语义：全量从 JSONL 重建，单事务幂等覆盖（DELETE + INSERT），任何时刻盘上索引自洽；
+ *  - 损坏面不吞错：断链 / CAR-E-FORMAT / zstd 能力缺失的文件不入索引，逐条进 errors 报告——
+ *    索引只收录链完整会话（审计面口径：可索引 = 可验证）；
+ *  - 物理编码 layout-blind：plain / zstd 统一经 format.ts 装载，索引记录 encoding 供检索。
+ */
+import { readdirSync, existsSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { loadSessionLog } from './log.js';
+const CAR_E_SQLITE = 'CAR-E-SQLITE: 当前 Node 无 node:sqlite 能力（22.5+ 需 --experimental-sqlite，23.4+ 原生）——显式拒绝，不静默降级';
+/** node:sqlite 能力探测（模块存在性；静态 import 在无能力 Node 上会崩模块加载，故动态） */
+export async function sqliteAvailable() {
+    try {
+        await import('node:sqlite');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 打开索引库（db 文件必须已存在——lookup 不产生建文件副作用；open 失败 = 索引文件无效显式报错） */
+async function openExistingDb(dbPath) {
+    if (!existsSync(dbPath)) {
+        throw new Error(`CAR-E-INDEX: 会话索引不存在：${dbPath}——先执行 car session rebuild-index 建立索引`);
+    }
+    const mod = await import('node:sqlite').catch(() => null);
+    if (!mod)
+        throw new Error(CAR_E_SQLITE);
+    const DatabaseSync = mod.DatabaseSync;
+    try {
+        return new DatabaseSync(dbPath);
+    }
+    catch (e) {
+        throw new Error(`CAR-E-INDEX: 索引文件无效（打开失败：${e.message}）：${dbPath}`);
+    }
+}
+/** 单会话检索（1.2-S1 W3-1）：--session <id> 经索引解析 sessionId → 文件；未收录 = null（「可索引 = 可验证」口径——断链会话不入索引） */
+export async function lookupSession(dbPath, sessionId) {
+    const db = await openExistingDb(dbPath);
+    try {
+        const table = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='sessions'").get();
+        if (!table)
+            throw new Error(`CAR-E-INDEX: 索引文件无效（无 sessions 表）：${dbPath}`);
+        const row = db.prepare('SELECT * FROM sessions WHERE sessionId = ?').get(sessionId);
+        if (!row)
+            return null;
+        return {
+            sessionId: String(row.sessionId),
+            file: String(row.file),
+            eventCount: Number(row.eventCount),
+            chainHead: row.chainHead == null ? null : String(row.chainHead),
+            chainTail: row.chainTail == null ? null : String(row.chainTail),
+            firstTs: row.firstTs == null ? null : Number(row.firstTs),
+            lastTs: row.lastTs == null ? null : Number(row.lastTs),
+            tornTail: Number(row.tornTail) === 1,
+            encoding: row.encoding === 'zstd' ? 'zstd' : 'plain',
+        };
+    }
+    catch (e) {
+        const msg = e.message;
+        if (msg.startsWith('CAR-E-'))
+            throw e; // 本层显式错误原样透传
+        // SQLite 惰性校验：非索引文件 open 不报错、query 才报（file is not a database）——统一收口为显式口径
+        throw new Error(`CAR-E-INDEX: 索引文件无效（${msg}）：${dbPath}`);
+    }
+    finally {
+        db.close();
+    }
+}
+const CREATE_SESSIONS_SQL = `CREATE TABLE IF NOT EXISTS sessions (
+  sessionId TEXT PRIMARY KEY,
+  file TEXT NOT NULL,
+  eventCount INTEGER NOT NULL,
+  chainHead TEXT,
+  chainTail TEXT,
+  firstTs INTEGER,
+  lastTs INTEGER,
+  tornTail INTEGER NOT NULL DEFAULT 0,
+  encoding TEXT NOT NULL DEFAULT 'plain',
+  rebuiltAt TEXT NOT NULL
+)`;
+/** 单行增量 upsert（1.2-S2 W3-2「更新半边」）：库/表不存在则自举创建（活会话无需先 rebuild 即可入索引） */
+export async function upsertSessionRow(dbPath, row) {
+    const mod = await import('node:sqlite').catch(() => null);
+    if (!mod)
+        throw new Error(CAR_E_SQLITE);
+    const DatabaseSync = mod.DatabaseSync;
+    try {
+        const db = new DatabaseSync(dbPath);
+        try {
+            db.exec(CREATE_SESSIONS_SQL);
+            db.prepare('INSERT OR REPLACE INTO sessions (sessionId, file, eventCount, chainHead, chainTail, firstTs, lastTs, tornTail, encoding, rebuiltAt) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').run(row.sessionId, row.file, row.eventCount, row.chainHead, row.chainTail, row.firstTs, row.lastTs, row.tornTail ? 1 : 0, row.encoding, new Date().toISOString());
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (e) {
+        const msg = e.message;
+        if (msg.startsWith('CAR-E-'))
+            throw e;
+        throw new Error(`CAR-E-INDEX: 索引更新失败（${msg}）：${dbPath}`);
+    }
+}
+export class IndexUpdater {
+    #dbPath;
+    #debounceMs;
+    #onError;
+    #state = null;
+    #timer = null;
+    #capabilityMissing = false;
+    #updates = 0;
+    #failures = 0;
+    constructor(opts) {
+        this.#dbPath = opts.dbPath;
+        this.#debounceMs = opts.debounceMs ?? 2_000;
+        this.#onError = opts.onError ?? (e => { try {
+            console.error(`[index-updater] ${e.message}`);
+        }
+        catch { /* 收口期 stderr 不可用 */ } });
+    }
+    get stats() {
+        return { updates: this.#updates, failures: this.#failures };
+    }
+    /** append sink 链上调用（行 JSON）：seq 权威增量；非预期行防御性忽略 */
+    record(sessionId, line, file) {
+        if (this.#capabilityMissing)
+            return;
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        const seq = Number(e.seq);
+        const ts = Number(e.ts);
+        const hash = typeof e.hash === 'string' ? e.hash : '';
+        if (!Number.isFinite(seq) || !Number.isFinite(ts) || !hash)
+            return;
+        // realpath 规范化（1.2-BUG-4）：macOS tmpdir 为 symlink（/var → /private/var），子进程 cwd 由
+        // OS 返回物理路径——resolve() 不解析符号链接，父子进程会产出同一文件的两个别名形态；
+        // 入库统一为 realpath（文件刚被 append 过必存在；异常回退 resolve）
+        const canonical = (() => {
+            try {
+                return realpathSync(file);
+            }
+            catch {
+                return resolve(file);
+            }
+        })();
+        const s = this.#state;
+        if (!s || s.sessionId !== sessionId || s.file !== canonical) {
+            this.#state = { sessionId, file: canonical, eventCount: seq + 1, chainHead: hash, chainTail: hash, firstTs: ts, lastTs: ts };
+        }
+        else {
+            s.eventCount = Math.max(s.eventCount, seq + 1);
+            s.chainTail = hash;
+            s.lastTs = ts;
+        }
+        this.#timer ??= setTimeout(() => { void this.flush(); }, this.#debounceMs);
+    }
+    /** 立即落 pending（close/exit 时点调用；幂等——无 pending 即空转） */
+    async flush() {
+        if (this.#timer) {
+            clearTimeout(this.#timer);
+            this.#timer = null;
+        }
+        if (!this.#state)
+            return;
+        const s = this.#state;
+        const row = { ...s, tornTail: false, encoding: 'plain' };
+        try {
+            await upsertSessionRow(this.#dbPath, row);
+            this.#updates++;
+        }
+        catch (e) {
+            this.#failures++;
+            const msg = e.message;
+            if (msg.startsWith('CAR-E-SQLITE')) {
+                // 能力缺席：登记一次后停用（后续 record 不再调度——禁每窗口重复刷屏）
+                this.#capabilityMissing = true;
+            }
+            this.#onError(e);
+        }
+    }
+    /** 收口：取消未决 timer + 落 pending（car run 关句柄前调用） */
+    async close() {
+        await this.flush();
+    }
+}
+function scanLogFiles(root) {
+    const rels = readdirSync(root, { recursive: true });
+    return rels
+        .filter(f => f.endsWith('.jsonl') || f.endsWith('.jsonl.zstd'))
+        .sort()
+        .map(f => join(root, f));
+}
+/** 装载 + 校验 + 抽取索引行（格式/断链/zstd 能力问题以 throw 上抛 → errors 通道） */
+function buildRow(file) {
+    const { log, brokenAt, encoding, tornTail } = loadSessionLog(file);
+    if (brokenAt !== null)
+        throw new Error(`哈希链断裂 @ seq=${brokenAt}`);
+    const events = log.events;
+    const first = events[0];
+    const last = events[events.length - 1];
+    return {
+        sessionId: log.sessionId,
+        file,
+        eventCount: events.length,
+        chainHead: first?.hash ?? null,
+        chainTail: last?.hash ?? null,
+        firstTs: first?.ts ?? null,
+        lastTs: last?.ts ?? null,
+        tornTail,
+        encoding,
+    };
+}
+export async function rebuildIndex(root, dbPath) {
+    const mod = await import('node:sqlite').catch(() => null);
+    if (!mod)
+        throw new Error('CAR-E-SQLITE: 当前 Node 无 node:sqlite 能力（22.5+ 需 --experimental-sqlite，23.4+ 原生）——显式拒绝，不静默降级');
+    const DatabaseSync = mod.DatabaseSync;
+    const rows = [];
+    const errors = [];
+    for (const file of scanLogFiles(root)) {
+        try {
+            rows.push(buildRow(file));
+        }
+        catch (e) {
+            errors.push({ file, reason: e.message });
+        }
+    }
+    const db = new DatabaseSync(dbPath);
+    try {
+        db.exec(`CREATE TABLE IF NOT EXISTS sessions (
+      sessionId TEXT PRIMARY KEY,
+      file TEXT NOT NULL,
+      eventCount INTEGER NOT NULL,
+      chainHead TEXT,
+      chainTail TEXT,
+      firstTs INTEGER,
+      lastTs INTEGER,
+      tornTail INTEGER NOT NULL DEFAULT 0,
+      encoding TEXT NOT NULL DEFAULT 'plain',
+      rebuiltAt TEXT NOT NULL
+    )`);
+        const rebuiltAt = new Date().toISOString();
+        db.exec('BEGIN');
+        db.exec('DELETE FROM sessions');
+        const insert = db.prepare('INSERT INTO sessions (sessionId, file, eventCount, chainHead, chainTail, firstTs, lastTs, tornTail, encoding, rebuiltAt) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)');
+        for (const r of rows) {
+            insert.run(r.sessionId, r.file, r.eventCount, r.chainHead, r.chainTail, r.firstTs, r.lastTs, r.tornTail ? 1 : 0, r.encoding, rebuiltAt);
+        }
+        db.exec('COMMIT');
+    }
+    finally {
+        db.close();
+    }
+    return { dbPath, rows, errors };
+}

package/dist/session/log.d.ts

@@ -0,0 +1,79 @@
+export type EventKind = 'user' | 'assistant' | 'toolCall' | 'toolResult' | 'turnEnd' | 'goalUpdate' | 'hostRaw' | 'fork' | 'system' | 'usage';
+export type Actor = 'user' | 'model' | 'plugin' | 'runtime';
+export interface SessionEvent {
+    seq: number;
+    ts: number;
+    actor: Actor;
+    kind: EventKind;
+    turnId: string;
+    payload: unknown;
+    meta?: Record<string, unknown>;
+    prevHash: string;
+    hash: string;
+}
+declare const sha: (s: string) => string;
+export interface ModelSnapshot {
+    /** 快照对应日志前缀边界（事件数），断言时逐字节比对前缀投影 */
+    atSeq: number;
+    request: unknown[];
+}
+export declare class SessionLog {
+    #private;
+    readonly sessionId: string;
+    events: readonly SessionEvent[];
+    constructor(sessionId?: string);
+    /**
+     * 挂载落盘 sink（§3.2.M7.5 Step 1-2「先落日志后放行」）：append 时同步写盘，
+     * sink 成功后才入内存；sink throw = 写失败 fail-fast（事件不入内存、不推进链尾，
+     * 调用方当前 turn 以 error 收口——内存与盘面永不失配）。
+     */
+    attachSink(sink: (line: string) => void): void;
+    /** 唯一写入路径（append-only；无 update/delete API） */
+    append(actor: Actor, kind: EventKind, turnId: string, payload: unknown, meta?: Record<string, unknown>): SessionEvent;
+    /** 模型请求发起时调用（agent-loop 集成点）：登记「请求时快照」 */
+    snapshotModelRequest(): ModelSnapshot;
+    /** 逐链校验；返回 null=完整，否则断链事件序号（审计导出前置，断链即中止） */
+    verifyChain(): number | null;
+    /**
+     * 投影：从日志前缀重建模型可见消息流（不依赖模型运行时状态）。
+     * 1.6-S1（D-23）同 id toolResult 收敛 last-wins：写类工具授权决策（runtime/toolResult）
+     * 与执行结果（plugin/toolResult）成对落链（M4 既有语义冻结——审计全量留痕不动），
+     * 模型可见流只保留最终结果（真实 provider 对重复 tool_call_id/tool_use_id 拒绝或未定义，
+     * 1.4 观察项经真实适配器落地升级为缺陷面）。id 缺席不收敛（hostRaw/无 id 载荷形态不变，
+     * golden ④ 投影语义兼容）；授权拒绝单条即唯一结果原样保留。适配器侧零改动（消费已收敛上游）。
+     */
+    deriveMessages(upTo?: number): Array<{
+        role: string;
+        [k: string]: unknown;
+    }>;
+    /** N1 不变量断言（CI 门禁雏形）：全部快照必须与当前日志前缀投影逐字节一致 */
+    assertModelVisibleLogged(): {
+        ok: boolean;
+        failedAt?: number;
+    };
+    /** 只读统计（供监控/测试） */
+    stats(): {
+        events: number;
+        snapshots: number;
+        tailHash: string;
+    };
+    /** 从已校验事件数组重建（恢复 #tail，续跑 append 不断链——跨宿主 fork/resume 装载入口） */
+    static fromEvents(sessionId: string, events: readonly SessionEvent[]): SessionLog;
+    /** 导出取证数据（MVP 基础导出：JSONL 全量 + 审计元数据；F15 完整包为 M2） */
+    exportJSONL(): string;
+}
+/** 文件路径 → sessionId 推导：`session-<id>.jsonl[.zstd]` 去前缀后缀；`events.jsonl` 取父目录名（审计定位口径） */
+export declare function deriveSessionId(file: string): string;
+/**
+ * 从 JSONL 文件装载（审计回放/跨机迁移入口）。格式层语义见 format.ts：
+ * 撕裂尾显式报告（丢弃崩溃半行，不静默）；完整行解析失败 CAR-E-FORMAT 拒绝装载；
+ * 断链 = brokenAt 返回（由调用方决定中止口径）。zstd 文件按 magic 嗅探直读。
+ */
+export declare function loadSessionLog(file: string): {
+    log: SessionLog;
+    brokenAt: number | null;
+    encoding: 'plain' | 'zstd';
+    tornTail: boolean;
+    tornTailBytes: number;
+};
+export { sha as sha256Hex };

package/dist/session/log.js

@@ -0,0 +1,157 @@
+/**
+ * append-only 会话日志层（F2 / N1 —— POC-3 断言框架的产品化）
+ *
+ * 设计口径：
+ *  - 哈希链（SHA-256）为 CAR 自研增强（dsh 无此物，源码级核实）——合规卖点落地
+ *  - 「Model-visible means logged」：断言口径 = 请求时快照 === 日志前缀 [0, atSeq) 投影
+ *  - 1.6-S1（D-23）：投影对同 id toolResult 收敛 last-wins——事件面/审计面不动，模型可见流去冗余
+ *  - append-only：本层仅暴露 append/verifyChain/deriveMessages/assertModelVisibleLogged
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { decodeLogBuffer, splitJsonlLines } from './format.js';
+const sha = (s) => createHash('sha256').update(s).digest('hex');
+const canonical = (e) => sha(JSON.stringify({ seq: e.seq, ts: e.ts, actor: e.actor, kind: e.kind, turnId: e.turnId, payload: e.payload, meta: e.meta ?? null, prevHash: e.prevHash }));
+export class SessionLog {
+    sessionId;
+    events = [];
+    #tail = 'GENESIS';
+    #snapshots = [];
+    #sink = null;
+    constructor(sessionId = 'S-' + Date.now().toString(36)) {
+        this.sessionId = sessionId;
+    }
+    /**
+     * 挂载落盘 sink（§3.2.M7.5 Step 1-2「先落日志后放行」）：append 时同步写盘，
+     * sink 成功后才入内存；sink throw = 写失败 fail-fast（事件不入内存、不推进链尾，
+     * 调用方当前 turn 以 error 收口——内存与盘面永不失配）。
+     */
+    attachSink(sink) {
+        this.#sink = sink;
+    }
+    /** 唯一写入路径（append-only；无 update/delete API） */
+    append(actor, kind, turnId, payload, meta) {
+        const e = {
+            seq: this.events.length, ts: Date.now(), actor, kind, turnId, payload, meta, prevHash: this.#tail,
+        };
+        const full = { ...e, hash: canonical(e) };
+        if (this.#sink)
+            this.#sink(JSON.stringify(full));
+        this.events = [...this.events, full];
+        this.#tail = full.hash;
+        return full;
+    }
+    /** 模型请求发起时调用（agent-loop 集成点）：登记「请求时快照」 */
+    snapshotModelRequest() {
+        const snap = { atSeq: this.events.length, request: structuredClone(this.deriveMessages(this.events.length)) };
+        this.#snapshots.push(snap);
+        return snap;
+    }
+    /** 逐链校验；返回 null=完整，否则断链事件序号（审计导出前置，断链即中止） */
+    verifyChain() {
+        let prev = 'GENESIS';
+        for (const e of this.events) {
+            if (e.prevHash !== prev || e.hash !== canonical(e))
+                return e.seq;
+            prev = e.hash;
+        }
+        return null;
+    }
+    /**
+     * 投影：从日志前缀重建模型可见消息流（不依赖模型运行时状态）。
+     * 1.6-S1（D-23）同 id toolResult 收敛 last-wins：写类工具授权决策（runtime/toolResult）
+     * 与执行结果（plugin/toolResult）成对落链（M4 既有语义冻结——审计全量留痕不动），
+     * 模型可见流只保留最终结果（真实 provider 对重复 tool_call_id/tool_use_id 拒绝或未定义，
+     * 1.4 观察项经真实适配器落地升级为缺陷面）。id 缺席不收敛（hostRaw/无 id 载荷形态不变，
+     * golden ④ 投影语义兼容）；授权拒绝单条即唯一结果原样保留。适配器侧零改动（消费已收敛上游）。
+     */
+    deriveMessages(upTo) {
+        const scoped = upTo !== undefined ? this.events.slice(0, upTo) : this.events;
+        const lastSeqById = new Map();
+        for (const e of scoped) {
+            if (e.kind !== 'toolResult')
+                continue;
+            const id = e.payload?.id;
+            if (typeof id === 'string')
+                lastSeqById.set(id, e.seq);
+        }
+        const out = [];
+        for (const e of scoped) {
+            if (e.kind === 'system')
+                out.push({ role: 'system', content: e.payload });
+            else if (e.kind === 'user')
+                out.push({ role: 'user', content: e.payload });
+            else if (e.kind === 'assistant')
+                out.push({ role: 'assistant', content: e.payload });
+            else if (e.kind === 'toolCall')
+                out.push({ role: 'assistant', toolCall: e.payload });
+            else if (e.kind === 'toolResult') {
+                const id = e.payload?.id;
+                if (typeof id === 'string' && lastSeqById.get(id) !== e.seq)
+                    continue; // D-23：后续有同 id 最终结果，本条为授权中间记录
+                out.push({ role: 'toolResult', content: e.payload });
+            }
+        }
+        return out;
+    }
+    /** N1 不变量断言（CI 门禁雏形）：全部快照必须与当前日志前缀投影逐字节一致 */
+    assertModelVisibleLogged() {
+        for (const s of this.#snapshots) {
+            if (JSON.stringify(s.request) !== JSON.stringify(this.deriveMessages(s.atSeq))) {
+                return { ok: false, failedAt: s.atSeq };
+            }
+        }
+        return { ok: true };
+    }
+    /** 只读统计（供监控/测试） */
+    stats() {
+        return { events: this.events.length, snapshots: this.#snapshots.length, tailHash: this.#tail };
+    }
+    /** 从已校验事件数组重建（恢复 #tail，续跑 append 不断链——跨宿主 fork/resume 装载入口） */
+    static fromEvents(sessionId, events) {
+        const log = new SessionLog(sessionId);
+        log.events = [...events];
+        const last = events[events.length - 1];
+        if (last)
+            log.#tail = last.hash;
+        return log;
+    }
+    /** 导出取证数据（MVP 基础导出：JSONL 全量 + 审计元数据；F15 完整包为 M2） */
+    exportJSONL() {
+        return this.events.map(e => JSON.stringify(e)).join('\n') + '\n';
+    }
+}
+/** 文件路径 → sessionId 推导：`session-<id>.jsonl[.zstd]` 去前缀后缀；`events.jsonl` 取父目录名（审计定位口径） */
+export function deriveSessionId(file) {
+    const base = file.replace(/.*[/\\]/, '');
+    let id = base.replace(/\.jsonl\.zstd$/, '').replace(/\.jsonl$/, '');
+    if (id === 'events') {
+        const dir = file.replace(/[\\/][^/\\]*$/, '');
+        const name = dir.replace(/.*[/\\]/, '');
+        if (name && name !== dir)
+            id = name; // 有父目录才取父目录名，否则保留 'events'
+    }
+    else if (id.startsWith('session-'))
+        id = id.slice('session-'.length);
+    return id;
+}
+/**
+ * 从 JSONL 文件装载（审计回放/跨机迁移入口）。格式层语义见 format.ts：
+ * 撕裂尾显式报告（丢弃崩溃半行，不静默）；完整行解析失败 CAR-E-FORMAT 拒绝装载；
+ * 断链 = brokenAt 返回（由调用方决定中止口径）。zstd 文件按 magic 嗅探直读。
+ */
+export function loadSessionLog(file) {
+    const { text, encoding } = decodeLogBuffer(readFileSync(file));
+    const { lines, tornTail, tornTailBytes } = splitJsonlLines(text);
+    const events = lines.map((l, i) => {
+        try {
+            return JSON.parse(l);
+        }
+        catch (e) {
+            throw new Error(`CAR-E-FORMAT: ${file} 第 ${i + 1} 行非法 JSON——拒绝装载带病日志（${e.message}）`);
+        }
+    });
+    const log = SessionLog.fromEvents(deriveSessionId(file), events);
+    return { log, brokenAt: log.verifyChain(), encoding, tornTail, tornTailBytes };
+}
+export { sha as sha256Hex };

package/dist/session/store.d.ts

@@ -0,0 +1,9 @@
+export declare class SessionFileStore {
+    #private;
+    readonly path: string;
+    constructor(path: string);
+    /** 唯一写入路径：单 write 原子 + fsync；失败即 throw（fail-fast，事件不入内存） */
+    append(line: string): void;
+    /** 收口关闭（幂等）；关闭后续写 = CAR-E-STORE 拒绝 */
+    close(): void;
+}

package/dist/session/store.js

@@ -0,0 +1,37 @@
+/**
+ * C-01 落盘存储层（§3.2.M7.5 Step 1-2 兑现——「先落日志后放行」的物理承载）
+ *
+ * 口径：
+ *  - 单行原子：O_APPEND 句柄上单 write 系统调用写完整一行（事件 JSON + '\n'），杜绝交错与半行交错面；
+ *  - fsync 同步刷盘：append 返回 = 该事件已过掉电窗口，kill -9 不丢已返回事件；
+ *  - fail-fast：任何写失败向上 throw → 调用方（agent loop）当前 turn 以 error 收口，
+ *    禁止继续产生模型可见内容（防不变量破坏，L0 不降级——SessionLog.attachSink 的 throw 传播即此语义）；
+ *  - 物理编码恒明文 JSONL（zstd 属归档/导出压缩，见 format.ts 文件头口径）。
+ */
+import { closeSync, fsyncSync, openSync, writeSync } from 'node:fs';
+export class SessionFileStore {
+    #fd = -1;
+    path;
+    constructor(path) {
+        this.path = path;
+        this.#fd = openSync(path, 'a');
+    }
+    /** 唯一写入路径：单 write 原子 + fsync；失败即 throw（fail-fast，事件不入内存） */
+    append(line) {
+        if (this.#fd < 0)
+            throw new Error(`CAR-E-STORE: store 已关闭（${this.path}）——fail-fast 拒绝续写`);
+        const buf = Buffer.from(line.endsWith('\n') ? line : line + '\n', 'utf-8');
+        let off = 0;
+        while (off < buf.length)
+            off += writeSync(this.#fd, buf, off);
+        fsyncSync(this.#fd);
+    }
+    /** 收口关闭（幂等）；关闭后续写 = CAR-E-STORE 拒绝 */
+    close() {
+        if (this.#fd >= 0) {
+            const fd = this.#fd;
+            this.#fd = -1;
+            closeSync(fd);
+        }
+    }
+}

package/dist/telemetry/metrics.d.ts

@@ -0,0 +1,25 @@
+/**
+ * S17 · 采集面（D-2 enforce 数据窗口 S18–S20 前置）：零内容计数器
+ *
+ * 口径（M4系统设计增补 S17 采集面 / Q-08 遥测三原则 / D-3）：
+ *  - 3 个 Counter：car_load_total{result} / car_unsigned_confirmed{confirmed} / car_registry_decision{source}；
+ *    labels 仅枚举值（来源/结果/模式）——**零内容字段**（无代码/提示词/路径/会话 id 明文），Q-08 兼容可机器断言；
+ *  - 双通道：遥测显式开（OTel 端点归用户）+ 登记表人工填报兜底（snapshot() 导出计数快照）；
+ *    未开启遥测时仅进程内累计，不落地不缓存出站（BD-05 语义）；
+ *  - 本层是可插拔计数钩子（onCount 注入面），非完整 OTel Metrics——完整面显式排除在 S17 外。
+ */
+export type CounterName = 'car_load_total' | 'car_unsigned_confirmed' | 'car_registry_decision';
+/** labels 仅枚举值——零内容红线由 AllowedLabels 类型约束 */
+export type AllowedLabels = {
+    result?: 'ok' | 'failed';
+    confirmed?: 'yes' | 'no';
+    source?: 'registry' | 'npm-fallback' | 'rejected' | 'git' | 'path';
+};
+export interface Counters {
+    onCount(name: CounterName, labels?: AllowedLabels): void;
+    /** 计数快照（登记表人工填报兜底通道的数据源；不含任何内容字段） */
+    snapshot(): Record<string, number>;
+}
+export declare function createCounters(): Counters;
+/** 零内容红线自检：snapshot 键不得包含内容型模式（sk-/路径分隔/空格长串） */
+export declare function assertZeroContent(snapshot: Record<string, number>): boolean;

package/dist/telemetry/metrics.js

@@ -0,0 +1,26 @@
+/**
+ * S17 · 采集面（D-2 enforce 数据窗口 S18–S20 前置）：零内容计数器
+ *
+ * 口径（M4系统设计增补 S17 采集面 / Q-08 遥测三原则 / D-3）：
+ *  - 3 个 Counter：car_load_total{result} / car_unsigned_confirmed{confirmed} / car_registry_decision{source}；
+ *    labels 仅枚举值（来源/结果/模式）——**零内容字段**（无代码/提示词/路径/会话 id 明文），Q-08 兼容可机器断言；
+ *  - 双通道：遥测显式开（OTel 端点归用户）+ 登记表人工填报兜底（snapshot() 导出计数快照）；
+ *    未开启遥测时仅进程内累计，不落地不缓存出站（BD-05 语义）；
+ *  - 本层是可插拔计数钩子（onCount 注入面），非完整 OTel Metrics——完整面显式排除在 S17 外。
+ */
+export function createCounters() {
+    const store = new Map();
+    return {
+        onCount(name, labels = {}) {
+            const key = name + Object.entries(labels).sort().map(([k, v]) => `|${k}=${v}`).join('');
+            store.set(key, (store.get(key) ?? 0) + 1);
+        },
+        snapshot() {
+            return Object.fromEntries([...store.entries()].sort());
+        },
+    };
+}
+/** 零内容红线自检：snapshot 键不得包含内容型模式（sk-/路径分隔/空格长串） */
+export function assertZeroContent(snapshot) {
+    return Object.keys(snapshot).every(k => !/sk-|ghp_|\/|\\|.{60,}/.test(k));
+}

package/package.json

@@ -1,12 +1,27 @@
 {
   "name": "@lqc123qwe/car-runtime",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "Composable Agent Runtime (CAR) - microkernel plugin system with sandboxed PTC, append-only hashed session log, and MCP host bridge",
   "license": "MIT",
   "type": "module",
   "engines": {
     "node": ">=22.19.0"
   },
+  "main": "./dist/seam.js",
+  "types": "./dist/seam.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/seam.d.ts",
+      "import": "./dist/seam.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lqc624/car-runtime.git"
@@ -16,6 +31,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
+    "build": "tsc -p tsconfig.build.json",
     "test": "node --experimental-transform-types --test test/",
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },

package/src/authz/authz.ts

@@ -61,6 +61,18 @@ export class AuthzService {
     return this.#commit(decision)
   }
 
+  /** 会话策略直判（「会话内始终允许」粒度）：decidedBy=policy 幂等落链，不入人审通道（审批回调 scope=session 写入 grants 后走此路） */
+  decideBySessionPolicy(req: AuthzRequest): AuthzDecision {
+    return this.#commit({
+      authorizationId: req.authorizationId,
+      decision: 'APPROVED',
+      decidedBy: 'policy',
+      reason: `session policy grant (always-allow): ${req.resource}`,
+      degraded: this.#degraded,
+      ts: Date.now(),
+    })
+  }
+
   /** 人审（confirm 模式）：120s 超时默认拒绝（timeout-default-deny） */
   async decideByUser(req: AuthzRequest, approve: (req: AuthzRequest) => Promise<boolean>): Promise<AuthzDecision> {
     const cached = this.#decisions.get(req.authorizationId)