@lqc123qwe/car-runtime 1.8.0 → 1.10.0

package/dist/security/secrets.js

@@ -0,0 +1,138 @@
+/**
+ * F12 · secrets 检测（完整版，M2-S7 实装加载期；运行期输出期挂点预留）
+ *
+ * 口径（M2 安全设计增补 T-6 + D-3 裁决）：
+ *  - 模式库 6 类（api-key 前缀族 / 私钥块 / 连接串 / 云凭据 / token-Bearer / 自定义正则）；
+ *  - 三层检测降误报：L1 精确前缀（Aho-Corasick 等价的朴素扫描，规模小不构成瓶颈）
+ *    → L2 Shannon 熵（≥3.5 才升级候选，排除 'aaaa' 类低熵误报）
+ *    → L3 上下文打分（键名共现 +1、代码引号内 +0、注释 -1；总分 ≥2 判命中）；
+ *  - 可验证交付（D-3）：漏报率 <1.5%、FPR ≤5%、precision ≥80%——基准集 1:9 正负比、CI 标定；
+ *  - 检测不可静默关闭：disable 仅允许显式配置且留痕（本层不提供总开关，红线 §6.3）。
+ */
+/** 6 类模式库（v1：30 条精选；自定义正则经 manifest 注入需过安全评审，M3） */
+export const PATTERN_LIBRARY = [
+    // ── api-key 前缀族 ──
+    { category: 'api-key', name: 'OpenAI', re: /sk-[A-Za-z0-9_-]{20,}/g, keyHints: ['openai', 'OPENAI_API_KEY'] },
+    { category: 'api-key', name: 'Anthropic', re: /sk-ant-[A-Za-z0-9_-]{20,}/g, keyHints: ['anthropic'] },
+    { category: 'api-key', name: 'GitHub PAT', re: /gh[pousr]_[A-Za-z0-9]{30,}/g, keyHints: ['github', 'GITHUB_TOKEN'] },
+    { category: 'api-key', name: 'Slack', re: /xox[baprs]-[A-Za-z0-9-]{10,}/g, keyHints: ['slack'] },
+    { category: 'api-key', name: 'AWS Access Key', re: /AKIA[0-9A-Z]{16}/g, keyHints: ['aws'] },
+    { category: 'api-key', name: 'Stripe', re: /[sr]k_(live|test)_[A-Za-z0-9]{20,}/g, keyHints: ['stripe'] },
+    { category: 'api-key', name: 'npm', re: /npm_[A-Za-z0-9]{30,}/g, keyHints: ['npm_token'] },
+    // ── 私钥块 ──
+    { category: 'private-key', name: 'PEM RSA/EC', re: /-----BEGIN (RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/g },
+    { category: 'private-key', name: 'PKCS8', re: /-----BEGIN PRIVATE KEY-----/g },
+    { category: 'private-key', name: 'PuTTY PPK', re: /PuTTY-User-Key-File-2:/g },
+    // ── 连接串 ──
+    { category: 'connection-string', name: 'postgres', re: /postgres(ql)?:\/\/[^:\s"']+:[^@\s"']+@[^\s"']+/g, keyHints: ['database_url'] },
+    { category: 'connection-string', name: 'mysql', re: /mysql:\/\/[^:\s"']+:[^@\s"']+@[^\s"']+/g },
+    { category: 'connection-string', name: 'mongodb', re: /mongodb(\+srv)?:\/\/[^:\s"']+:[^@\s"']+@[^\s"']+/g, keyHints: ['mongo'] },
+    { category: 'connection-string', name: 'redis', re: /redis:\/\/:[^@\s"']+@[^\s"']+/g },
+    { category: 'connection-string', name: 'jdbc', re: /jdbc:[a-z0-9]+:\/\/[^:\s"']+:[^@\s"']+@/g },
+    // ── 云凭据 ──
+    { category: 'cloud-credential', name: 'AWS Secret', re: /aws(.{0,20})?(?:secret[_-]?access[_-]?key|secret)(.{0,10})?['":= ]+[A-Za-z0-9/+=]{40}/gi },
+    { category: 'cloud-credential', name: 'GCP service account', re: /"type":\s*"service_account"/g },
+    { category: 'cloud-credential', name: 'Azure conn', re: /AccountKey=[A-Za-z0-9+/=]{60,}/g },
+    { category: 'cloud-credential', name: 'JWT', re: /eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g, keyHints: ['token', 'jwt'] },
+    // ── token-Bearer ──
+    { category: 'bearer-token', name: 'Authorization header', re: /Authorization['":= ]+Bearer\s+[A-Za-z0-9._-]{15,}/gi, keyHints: ['authorization'] },
+    { category: 'bearer-token', name: 'api_key kv', re: /['"]?api[_-]?key['"]?\s*[:=]\s*['"][A-Za-z0-9._-]{16,}['"]/gi, keyHints: ['api_key'] },
+    { category: 'bearer-token', name: 'secret kv', re: /['"]?(client[_-]?secret|access[_-]?token)['"]?\s*[:=]\s*['"][A-Za-z0-9._-]{12,}['"]/gi },
+    { category: 'bearer-token', name: 'password kv', re: /['"]?password['"]?\s*[:=]\s*['"][^\s'"]{8,}['"]/gi },
+];
+/** Shannon 熵（bit/char） */
+export function shannonEntropy(s) {
+    if (!s.length)
+        return 0;
+    const freq = new Map();
+    for (const ch of s)
+        freq.set(ch, (freq.get(ch) ?? 0) + 1);
+    let h = 0;
+    for (const n of freq.values()) {
+        const p = n / s.length;
+        h -= p * Math.log2(p);
+    }
+    return h;
+}
+const ENTROPY_FLOOR = 3.5;
+/** 已知占位/示例值（连接串口令降级用；仅 L3 减分，不提供总开关，红线 §6.3 不受影响） */
+const PLACEHOLDER_VALUES = new Set([
+    'password', 'changeme', 'example', 'demo', 'default', 'placeholder', 'sample',
+    'test', 'pass', 'secret', 'dummy', 'xxx', 'yourpassword', 'your_password', 'your-password',
+]);
+/**
+ * E-5 校准：熵口径修正——kv 形命中的熵只算引号内 value；无引号时只算尾部值串。
+ * 根因（run 基准集 FPR 27.2%）：键名（password=/api_key= 等）自身多样性抬高了弱值的整体熵。
+ */
+function entropyTarget(token) {
+    const quoted = /["']([^"']{1,256})["']/g;
+    let last = null;
+    let m;
+    while ((m = quoted.exec(token)) !== null)
+        last = m[1];
+    if (last !== null && last.length >= 4)
+        return last;
+    const run = /([A-Za-z0-9+/=._-]{12,})$/.exec(token);
+    return run ? run[1] : token;
+}
+function maskToken(t) {
+    if (t.length <= 8)
+        return '*'.repeat(t.length);
+    return t.slice(0, 4) + '****' + t.slice(-4);
+}
+/**
+ * 三层检测：前缀命中 → 熵过滤 → 上下文打分。
+ * 返回确认命中（score ≥2）；低分候选不返回但可通过 returnCandidates 观察（标定用）。
+ */
+export function scanSecrets(text, opts = {}) {
+    const hits = [];
+    const candidates = [];
+    for (const p of PATTERN_LIBRARY) {
+        p.re.lastIndex = 0;
+        let m;
+        while ((m = p.re.exec(text)) !== null) {
+            const token = m[0];
+            // L2 熵过滤：私钥块/连接串结构化模式豁免熵检查；其余需 ≥3.5（E-5 校准：熵算在 value 上）
+            const structured = p.category === 'private-key' || p.category === 'connection-string' || (p.category === 'cloud-credential' && p.name === 'GCP service account');
+            const ent = shannonEntropy(entropyTarget(token));
+            if (!structured && ent < ENTROPY_FLOOR)
+                continue;
+            // L3 上下文打分：L1 前缀 + L2 熵双过 = 高精度（基础 2）；上下文仅加成/降级
+            let score = 2;
+            // E-5 校准：连接串占位口令降级（postgres://user:password@ 类文档示例 → 仅候选不确认）
+            if (p.category === 'connection-string') {
+                const pm = /:\/\/(?:[^:/\s"']+)?:([^@\s"']+)@/.exec(token);
+                if (pm && PLACEHOLDER_VALUES.has(pm[1].toLowerCase()))
+                    score -= 2;
+            }
+            const before = text.slice(Math.max(0, m.index - 40), m.index).toLowerCase();
+            if (p.keyHints?.some(h => before.includes(h.toLowerCase())))
+                score += 1;
+            if (/\b(const|let|var|return|echo|export)\b/.test(before))
+                score += 1; // 赋值/输出语境
+            if (/^\s*(\/\/|#|\*)/.test(text.slice(0, m.index).split('\n').pop() ?? ''))
+                score -= 1; // 注释行降级
+            const hit = { category: p.category, name: p.name, start: m.index, end: m.index + token.length, masked: maskToken(token), score };
+            if (score >= 2)
+                hits.push(hit);
+            else if (opts.returnCandidates)
+                candidates.push(hit);
+            if (m.index === p.re.lastIndex)
+                p.re.lastIndex++; // 防零宽死循环
+        }
+    }
+    hits.sort((a, b) => a.start - b.start);
+    return { hits, candidates };
+}
+/** 脱敏钩子：确认命中全遮蔽后返回新文本（M8 redact 的 F12 升级实现） */
+export function redactSecrets(text) {
+    const { hits } = scanSecrets(text);
+    let out = '';
+    let cursor = 0;
+    for (const h of hits) {
+        out += text.slice(cursor, h.start) + h.masked;
+        cursor = h.end;
+    }
+    out += text.slice(cursor);
+    return { text: out, redacted: hits.length };
+}

package/dist/session/export.d.ts

@@ -0,0 +1,55 @@
+import type { SessionLog } from './log.ts';
+export interface ExportMeta {
+    sessionId: string;
+    exportedBy: string;
+    exportedAt: string;
+    runtimeVersion: string;
+    agentPreset?: string;
+    sessionRange: {
+        fromSeq: number;
+        toSeq: number;
+    };
+}
+export interface ForensicsBundle {
+    files: {
+        name: string;
+        content: string;
+        sha256: string;
+    }[];
+    manifest: {
+        format: 'car-forensics/1';
+        chainHead: string | null;
+        chainTail: string | null;
+        eventCount: number;
+        verifyChainAtExport: 'PASS';
+        meta: ExportMeta;
+        files: {
+            name: string;
+            sha256: string;
+        }[];
+        /** 物理布局登记（M7 存储增强）：zstd 落盘时写入；逻辑口径（files[].sha256）恒为明文自证 */
+        storage?: {
+            encoding: 'zstd';
+            storedAs: string;
+            physicalSha256: string;
+        };
+    };
+}
+/** 取证包导出：断链即中止（不产出"带病审计包"） */
+export declare function exportForensicsBundle(log: SessionLog, meta: ExportMeta): ForensicsBundle;
+/** 包完整性校验：逐文件 SHA-256 重算 + 链锚点一致 */
+export declare function verifyBundle(bundle: ForensicsBundle): {
+    ok: boolean;
+    brokenFile: string | null;
+};
+/** 13 项审计字段（安全设计 §7.2.2）；core9 = 不可裁剪核心字段 */
+export declare const AUDIT_FIELDS: readonly ['seq+sessionId', 'ts', 'actor', 'actorDetail', 'eventType', 'resource', 'payload(redacted)', 'result/status', 'authorizationId+decidedBy+reason', 'traceId', 'tenantId', 'hash+prevHash', 'runtimeVersion+agentPreset'];
+export type StandardId = 'soc2' | 'gdpr' | 'mlps';
+export declare const FIELD_STANDARD_MAP: Record<string, StandardId[]>;
+/** 分层声明：按标准输出字段集 + 合规声明骨架（合规问卷答复用） */
+export declare function complianceStatement(std: StandardId): {
+    standard: StandardId;
+    fields: string[];
+    coreMissing: string[];
+    statement: string;
+};

package/dist/session/export.js

@@ -0,0 +1,81 @@
+/**
+ * F15 基础增强 · 合规导出（M2-S9）：取证包完整性清单 + 三标分层声明
+ *
+ * 口径（安全设计 §7.2.4 Q-09 定稿 + 决议⑧三标并集）：
+ *  - 导出包 = 事件 JSONL + manifest 清单（逐文件 SHA-256 + 链头尾锚点 + 审计元数据）；
+ *    导出前强制 verifyHashChain（断链中止，SQ-06）；运行时无上传功能（端点归用户）；
+ *  - 三标分层声明（T-7 程序化版本）：13 项审计字段对 SOC 2 CC7.2 / GDPR Art.30 / 等保 2.0
+ *    三级的逐字段映射；对外按行业分层声明（合规问卷答复骨架）；9 核心字段不可裁剪。
+ */
+import { createHash } from 'node:crypto';
+function sha256(s) { return createHash('sha256').update(s).digest('hex'); }
+/** 取证包导出：断链即中止（不产出"带病审计包"） */
+export function exportForensicsBundle(log, meta) {
+    const broken = log.verifyChain();
+    if (broken !== null)
+        throw new Error(`CAR-E-EXPORT: hash chain broken at seq=${broken}——断链中止导出（禁止带病审计包外流）`);
+    const jsonl = log.exportJSONL();
+    const files = [{ name: `sessions/{sessionId}/events.jsonl`.replace('{sessionId}', meta.sessionId), content: jsonl, sha256: sha256(jsonl) }];
+    const events = log.events;
+    const manifest = {
+        format: 'car-forensics/1',
+        chainHead: log.stats().tailHash ? (events[0]?.hash ?? null) : null,
+        chainTail: log.stats().tailHash,
+        eventCount: events.length,
+        verifyChainAtExport: 'PASS',
+        meta,
+        files: files.map(f => ({ name: f.name, sha256: f.sha256 })),
+    };
+    const manifestJson = JSON.stringify(manifest, null, 2);
+    files.push({ name: 'manifest.json', content: manifestJson, sha256: sha256(manifestJson) });
+    return { files, manifest };
+}
+/** 包完整性校验：逐文件 SHA-256 重算 + 链锚点一致 */
+export function verifyBundle(bundle) {
+    for (const f of bundle.files) {
+        if (sha256(f.content) !== f.sha256)
+            return { ok: false, brokenFile: f.name };
+    }
+    for (const fm of bundle.manifest.files) {
+        const actual = bundle.files.find(f => f.name === fm.name);
+        if (!actual || actual.sha256 !== fm.sha256)
+            return { ok: false, brokenFile: fm.name };
+    }
+    return { ok: true, brokenFile: null };
+}
+// ── 三标分层声明（T-7）──────────────────────────────────────────────
+/** 13 项审计字段（安全设计 §7.2.2）；core9 = 不可裁剪核心字段 */
+export const AUDIT_FIELDS = [
+    'seq+sessionId', 'ts', 'actor', 'actorDetail', 'eventType', 'resource', 'payload(redacted)',
+    'result/status', 'authorizationId+decidedBy+reason', 'traceId', 'tenantId', 'hash+prevHash', 'runtimeVersion+agentPreset',
+];
+const CORE9 = new Set(['seq+sessionId', 'ts', 'actor', 'eventType', 'result/status', 'authorizationId+decidedBy+reason', 'hash+prevHash', 'tenantId', 'payload(redacted)']);
+/** 字段 → 标准条款映射（T-7 矩阵的程序化数据源；导出时按 standard 裁剪字段集） */
+// 9 核心字段三标全覆盖（核心公共底座，不可裁剪）；非核心为标准特有扩展（分层声明语义）
+const ALL = ['soc2', 'gdpr', 'mlps'];
+export const FIELD_STANDARD_MAP = {
+    'seq+sessionId': ALL, // 个体事件级（SOC2 CC7.2）
+    'ts': ALL, // 日期和时间（等保 8.1.4.3 b）
+    'actor': ALL, // 用户（GDPR Art.30 归因）
+    'actorDetail': ['gdpr'], // 处理活动主体细化（扩展）
+    'eventType': ALL, // 事件类型
+    'resource': ['soc2', 'mlps'], // 操作对象（扩展）
+    'payload(redacted)': ALL, // 完整参数与结果（脱敏后）
+    'result/status': ALL, // 事件是否成功
+    'authorizationId+decidedBy+reason': ALL, // 授权凭据链（US6 凭什么）
+    'traceId': ['mlps'], // 关联排查（扩展）
+    'tenantId': ALL, // 归属边界
+    'hash+prevHash': ALL, // 不可变自证
+    'runtimeVersion+agentPreset': ['gdpr'], // 处理环境快照（扩展）
+};
+/** 分层声明：按标准输出字段集 + 合规声明骨架（合规问卷答复用） */
+export function complianceStatement(std) {
+    const fields = AUDIT_FIELDS.filter(f => FIELD_STANDARD_MAP[f]?.includes(std));
+    const coreMissing = [...CORE9].filter(f => !fields.includes(f));
+    const lines = {
+        soc2: 'CAR 会话日志逐事件记录（actor/时间戳/工具名/脱敏后参数与结果/授权凭据），SHA-256 哈希链不可变；保留期默认永久（用户自管），建议 ≥1 年（CC7.2）。',
+        gdpr: '事件含 actor/actorDetail/eventType/runtimeVersion（GDPR 第 30 条处理活动可归因）；数据主体权利由部署方在自有环境行使；遥测默认关、零内容字段。',
+        mlps: '对应 GB/T 22239-2019 三级 8.1.4.3 安全审计 a)–d)——审计覆盖四类 actor 全量事件、记录含日期时间/用户/事件类型/是否成功、哈希链防未预期篡改、审计接口零写入；日志留存 ≥6 个月由用户环境承诺（运行时不自动清理）。',
+    };
+    return { standard: std, fields, coreMissing, statement: lines[std] };
+}

package/dist/session/fork.d.ts

@@ -0,0 +1,51 @@
+/**
+ * T-1④ 转正 · 跨宿主 fork/resume（M5 · DEC-4 预埋项 2/2，原 M3 §1.7 显式延后项）
+ *
+ * 口径（M3系统设计增补 §1.7 / M4 RC-3 / M5 DEC-4 用户裁决①）：
+ *  - 语义：宿主 A 发起的会话在宿主 B 续跑——fork 产出可迁移 JSONL 工件（链逐字节保留），
+ *    resume 侧装载校验（断链即拒绝）+ 归属校验（fork 标记 target 与装载宿主不匹配即拒绝）；
+ *  - 会话 id 确定性派生复用（deriveSessionId）：fork 目标会话 id = SH-(targetHostId|targetHostSessionId)，
+ *    resume 侧幂等重推导，不信任工件命名；
+ *  - fork 标记事件（kind='fork'）落链：fromSessionId/target/upToSeq 全量留痕，零静默；
+ *  - 哈希链与 sessionId 解耦（事件哈希不含会话 id）→ 链逐字节迁移后 verifyChain 仍完整。
+ */
+import { SessionLog } from './log.ts';
+export interface ForkTarget {
+    hostId: string;
+    hostSessionId: string;
+}
+export interface CrossHostFork {
+    /** 宿主 B 侧新会话 id（SH- 确定性派生） */
+    sessionId: string;
+    /** 可迁移工件（JSONL 全文——经取证通道传递给宿主 B） */
+    jsonl: string;
+    /** 迁移的事件数（不含 fork 标记） */
+    migrated: number;
+    /** fork 后内存态日志（同进程等价验证用；跨进程走 jsonl 工件） */
+    log: SessionLog;
+}
+/** fork 标记事件 payload（resume 侧归属校验数据源） */
+export interface ForkMarkerPayload {
+    fromSessionId: string;
+    targetHostId: string;
+    targetHostSessionId: string;
+    upToSeq: number;
+    fromTailHash: string;
+}
+/**
+ * 跨宿主 fork：源会话 [0, upToSeq) 事件逐字节迁移 + fork 标记落链。
+ * 源链断链即抛错（fail-visible：破损链不允许扩散为「合法」新会话）。
+ */
+export declare function forkCrossHost(source: SessionLog, target: ForkTarget, opts?: {
+    upToSeq?: number;
+}): CrossHostFork;
+export interface LoadedFork {
+    log: SessionLog;
+    sessionId: string;
+    marker: ForkMarkerPayload;
+}
+/**
+ * resume 侧装载：JSONL 工件 → 校验链完整性 → 提取 fork 标记 → 确定性重推导会话 id。
+ * 断链 / 无 fork 标记 / 标记畸形 = 抛错（不静默降级为普通会话）。
+ */
+export declare function loadForkedLog(jsonl: string, expected?: ForkTarget): LoadedFork;

package/dist/session/fork.js

@@ -0,0 +1,63 @@
+/**
+ * T-1④ 转正 · 跨宿主 fork/resume（M5 · DEC-4 预埋项 2/2，原 M3 §1.7 显式延后项）
+ *
+ * 口径（M3系统设计增补 §1.7 / M4 RC-3 / M5 DEC-4 用户裁决①）：
+ *  - 语义：宿主 A 发起的会话在宿主 B 续跑——fork 产出可迁移 JSONL 工件（链逐字节保留），
+ *    resume 侧装载校验（断链即拒绝）+ 归属校验（fork 标记 target 与装载宿主不匹配即拒绝）；
+ *  - 会话 id 确定性派生复用（deriveSessionId）：fork 目标会话 id = SH-(targetHostId|targetHostSessionId)，
+ *    resume 侧幂等重推导，不信任工件命名；
+ *  - fork 标记事件（kind='fork'）落链：fromSessionId/target/upToSeq 全量留痕，零静默；
+ *  - 哈希链与 sessionId 解耦（事件哈希不含会话 id）→ 链逐字节迁移后 verifyChain 仍完整。
+ */
+import { SessionLog } from './log.js';
+import { deriveSessionId } from '../host/mappings.js';
+/**
+ * 跨宿主 fork：源会话 [0, upToSeq) 事件逐字节迁移 + fork 标记落链。
+ * 源链断链即抛错（fail-visible：破损链不允许扩散为「合法」新会话）。
+ */
+export function forkCrossHost(source, target, opts) {
+    const brokenAt = source.verifyChain();
+    if (brokenAt !== null)
+        throw new Error(`CAR-E-FORK: source chain broken at seq ${brokenAt}（断链拒绝 fork）`);
+    const upToSeq = opts?.upToSeq ?? source.events.length;
+    if (!Number.isInteger(upToSeq) || upToSeq < 0 || upToSeq > source.events.length) {
+        throw new Error(`CAR-E-FORK: upToSeq ${upToSeq} out of range [0, ${source.events.length}]`);
+    }
+    const sessionId = deriveSessionId(target.hostId, target.hostSessionId);
+    const log = SessionLog.fromEvents(sessionId, source.events.slice(0, upToSeq));
+    const marker = {
+        fromSessionId: source.sessionId,
+        targetHostId: target.hostId,
+        targetHostSessionId: target.hostSessionId,
+        upToSeq,
+        fromTailHash: upToSeq > 0 ? source.events[upToSeq - 1].hash : 'GENESIS',
+    };
+    log.append('runtime', 'fork', 'F0', marker);
+    const brokenAfter = log.verifyChain();
+    if (brokenAfter !== null)
+        throw new Error(`CAR-E-FORK: post-fork chain broken at seq ${brokenAfter}（内部不变量违例）`);
+    return { sessionId, jsonl: log.exportJSONL(), migrated: upToSeq, log };
+}
+/**
+ * resume 侧装载：JSONL 工件 → 校验链完整性 → 提取 fork 标记 → 确定性重推导会话 id。
+ * 断链 / 无 fork 标记 / 标记畸形 = 抛错（不静默降级为普通会话）。
+ */
+export function loadForkedLog(jsonl, expected) {
+    const events = jsonl.split('\n').filter(l => l.trim()).map(l => JSON.parse(l));
+    const markerEvent = [...events].reverse().find(e => e.kind === 'fork');
+    if (!markerEvent)
+        throw new Error('CAR-E-FORK: no fork marker in artifact（非 fork 工件拒绝装载）');
+    const marker = markerEvent.payload;
+    if (!marker || typeof marker.targetHostId !== 'string' || typeof marker.targetHostSessionId !== 'string') {
+        throw new Error('CAR-E-FORK: fork marker malformed（标记缺 target 字段）');
+    }
+    if (expected && (marker.targetHostId !== expected.hostId || marker.targetHostSessionId !== expected.hostSessionId)) {
+        throw new Error(`CAR-E-FORK: artifact target mismatch（工件归属 ${marker.targetHostId}/${marker.targetHostSessionId}，装载方 ${expected.hostId}/${expected.hostSessionId}）`);
+    }
+    const sessionId = deriveSessionId(marker.targetHostId, marker.targetHostSessionId);
+    const log = SessionLog.fromEvents(sessionId, events);
+    const brokenAt = log.verifyChain();
+    if (brokenAt !== null)
+        throw new Error(`CAR-E-FORK: artifact chain broken at seq ${brokenAt}（断链拒绝装载）`);
+    return { log, sessionId, marker };
+}

package/dist/session/format.d.ts

@@ -0,0 +1,21 @@
+export declare const ZSTD_MAGIC: Buffer<ArrayBuffer>;
+/** zstd 编解码能力探测（22.15+ 原生内置，无 flag；更早版本缺席——显式化不静默） */
+export declare function zstdAvailable(): boolean;
+/** 全量压缩（单 frame；取证包/归档全量口径，append 热路径不用——见文件头口径） */
+export declare function compressJsonlZstd(text: string): Buffer;
+/** 物理解码：按 magic 嗅探，读取方不感知文件后缀（layout-blind） */
+export declare function decodeLogBuffer(buf: Buffer): {
+    text: string;
+    encoding: 'plain' | 'zstd';
+};
+export interface SplitJsonlResult {
+    lines: string[];
+    tornTail: boolean;
+    tornTailBytes: number;
+}
+/**
+ * 撕裂尾切分：写入方契约 = 每事件一行且行尾 '\n'（store.ts 单 write 原子）。
+ * 末段无 '\n' 结尾 = 撕裂尾（崩溃半行），无论其内容是否恰为合法 JSON——显式格式校验语义，
+ * 统一按「写入方契约未达成」处理，丢弃并报告字节数。
+ */
+export declare function splitJsonlLines(text: string): SplitJsonlResult;

package/dist/session/format.js

@@ -0,0 +1,49 @@
+/**
+ * 会话日志格式层（§3.2.M7.1 第 4 点——M7 存储增强选项落地）
+ *
+ * 口径（dsh format.ts:210-240 源码级已核实，对齐其「可选 zstd + 撕裂尾截断容错」语义）：
+ *  - 三种读取失败语义互斥可判：
+ *      撕裂尾 = 末尾无换行的残留（崩溃半行）→ 显式丢弃并报告（不静默、不算断链、不算格式错误）；
+ *      格式错误 = 完整行 JSON 解析失败 → CAR-E-FORMAT 拒绝装载（防带病日志静默收缩）；
+ *      断链     = 完整行哈希不连续 → brokenAt（既有语义不变，loadSessionLog 返回）。
+ *  - 物理编码 layout-blind：按 zstd magic bytes 嗅探解码，读取方不感知 .jsonl / .jsonl.zstd；
+ *    zstd 为 22.15+ 原生内置（无 CLI flag，Stability: 1 实验标记），更早版本无此能力——缺席 = 显式报错非静默。
+ *  - 运行时热路径恒为明文 append + fsync（fail-fast 优先，见 store.ts）；zstd 定位 = 归档/导出压缩。
+ */
+import * as zlib from 'node:zlib';
+export const ZSTD_MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
+/** zstd 编解码能力探测（22.15+ 原生内置，无 flag；更早版本缺席——显式化不静默） */
+export function zstdAvailable() {
+    return typeof zlib.zstdCompressSync === 'function' && typeof zlib.zstdDecompressSync === 'function';
+}
+function requireZstd() {
+    if (!zstdAvailable()) {
+        throw new Error('CAR-E-ZSTD: 当前 Node 无 zstd 编解码能力（22.15+/23.8+ 原生内置，更早版本无）——显式拒绝，不静默降级');
+    }
+}
+/** 全量压缩（单 frame；取证包/归档全量口径，append 热路径不用——见文件头口径） */
+export function compressJsonlZstd(text) {
+    requireZstd();
+    return zlib.zstdCompressSync(Buffer.from(text, 'utf-8'));
+}
+/** 物理解码：按 magic 嗅探，读取方不感知文件后缀（layout-blind） */
+export function decodeLogBuffer(buf) {
+    if (buf.length >= ZSTD_MAGIC.length && buf.subarray(0, ZSTD_MAGIC.length).equals(ZSTD_MAGIC)) {
+        requireZstd();
+        return { text: zlib.zstdDecompressSync(buf).toString('utf-8'), encoding: 'zstd' };
+    }
+    return { text: buf.toString('utf-8'), encoding: 'plain' };
+}
+/**
+ * 撕裂尾切分：写入方契约 = 每事件一行且行尾 '\n'（store.ts 单 write 原子）。
+ * 末段无 '\n' 结尾 = 撕裂尾（崩溃半行），无论其内容是否恰为合法 JSON——显式格式校验语义，
+ * 统一按「写入方契约未达成」处理，丢弃并报告字节数。
+ */
+export function splitJsonlLines(text) {
+    const body = text.endsWith('\n') ? text.slice(0, -1) : text;
+    const parts = body.split('\n');
+    const tornTail = !text.endsWith('\n') && parts[parts.length - 1] !== '';
+    const tail = tornTail ? parts.pop() : '';
+    const lines = parts.filter(l => l.trim() !== '');
+    return { lines, tornTail, tornTailBytes: tornTail ? Buffer.byteLength(tail, 'utf-8') : 0 };
+}

package/dist/session/indexStore.d.ts

@@ -0,0 +1,44 @@
+export interface SessionIndexRow {
+    sessionId: string;
+    file: string;
+    eventCount: number;
+    chainHead: string | null;
+    chainTail: string | null;
+    firstTs: number | null;
+    lastTs: number | null;
+    tornTail: boolean;
+    encoding: 'plain' | 'zstd';
+}
+export interface RebuildResult {
+    dbPath: string;
+    rows: SessionIndexRow[];
+    errors: {
+        file: string;
+        reason: string;
+    }[];
+}
+/** node:sqlite 能力探测（模块存在性；静态 import 在无能力 Node 上会崩模块加载，故动态） */
+export declare function sqliteAvailable(): Promise<boolean>;
+/** 单会话检索（1.2-S1 W3-1）：--session <id> 经索引解析 sessionId → 文件；未收录 = null（「可索引 = 可验证」口径——断链会话不入索引） */
+export declare function lookupSession(dbPath: string, sessionId: string): Promise<SessionIndexRow | null>;
+/** 单行增量 upsert（1.2-S2 W3-2「更新半边」）：库/表不存在则自举创建（活会话无需先 rebuild 即可入索引） */
+export declare function upsertSessionRow(dbPath: string, row: SessionIndexRow): Promise<void>;
+export declare class IndexUpdater {
+    #private;
+    constructor(opts: {
+        dbPath: string;
+        debounceMs?: number;
+        onError?: (e: Error) => void;
+    });
+    get stats(): {
+        updates: number;
+        failures: number;
+    };
+    /** append sink 链上调用（行 JSON）：seq 权威增量；非预期行防御性忽略 */
+    record(sessionId: string, line: string, file: string): void;
+    /** 立即落 pending（close/exit 时点调用；幂等——无 pending 即空转） */
+    flush(): Promise<void>;
+    /** 收口：取消未决 timer + 落 pending（car run 关句柄前调用） */
+    close(): Promise<void>;
+}
+export declare function rebuildIndex(root: string, dbPath: string): Promise<RebuildResult>;