@lqc123qwe/car-runtime 1.8.0 → 1.10.0

package/dist/host/mappings.js

@@ -0,0 +1,52 @@
+/**
+ * T-1 · 多宿主归一化 schema（host-mappings-v1，M3-S11）
+ *
+ * 口径（M3系统设计增补 T-1 / 决议⑤）：
+ *  - session id 归一化：确定性派生 SH- + sha256(hostId|hostSessionId)——幂等免映射表存储；
+ *    首次映射落哈希链登记事件（调用方职责）；显式拒绝解析宿主 id 语义（对闭源漂移免疫）；
+ *  - 事件归一化：版本化映射表数据驱动（HOST_MAPPINGS），pattern 命中 → CAR EventKind + actor；
+ *    **未命中一律降级 hostRaw 留痕（零静默，机器可断言）**；
+ *  - 宿主标识字符串只允许出现在本数据文件（静态架构断言红线，测试强制）。
+ */
+import { createHash } from 'node:crypto';
+/** 跨宿主会话 id：SH- 前缀 + 24 hex（sha256 前 12 字节） */
+export function deriveSessionId(hostId, hostSessionId) {
+    return 'SH-' + createHash('sha256').update(`${hostId}|${hostSessionId}`).digest('hex').slice(0, 24);
+}
+/** host-mappings-v1：Claude Code / Codex 等价映射（同一接入面，两份纯数据 profile） */
+export const HOST_MAPPINGS = [
+    {
+        hostId: 'claude-code',
+        schemaVersion: 'host-mappings-v1',
+        mappings: [
+            { hostEvent: 'user_message', kind: 'user', actor: 'user', payloadMap: { content: 'text' } },
+            { hostEvent: 'assistant_message', kind: 'assistant', actor: 'model', payloadMap: { content: 'text' } },
+            { hostEvent: 'tool_use', kind: 'toolCall', actor: 'model', payloadMap: { tool_name: 'tool', tool_call_id: 'id' } },
+            { hostEvent: 'tool_result', kind: 'toolResult', actor: 'model', payloadMap: { tool_call_id: 'id' } },
+            { hostEvent: 'turn_complete', kind: 'turnEnd', actor: 'runtime' },
+        ],
+    },
+    {
+        hostId: 'codex',
+        schemaVersion: 'host-mappings-v1',
+        mappings: [
+            { hostEvent: 'input_item', kind: 'user', actor: 'user', payloadMap: { text: 'text' } },
+            { hostEvent: 'agent_message', kind: 'assistant', actor: 'model', payloadMap: { message: 'text' } },
+            { hostEvent: 'function_call', kind: 'toolCall', actor: 'model', payloadMap: { name: 'tool', call_id: 'id' } },
+            { hostEvent: 'function_call_output', kind: 'toolResult', actor: 'model', payloadMap: { call_id: 'id' } },
+            { hostEvent: 'task_complete', kind: 'turnEnd', actor: 'runtime' },
+        ],
+    },
+];
+/** 事件归一化：命中映射 → 转写；未命中 → hostRaw 降级（payload 原样保留，零静默） */
+export function normalizeHostEvent(profile, hostEvent, payload = {}) {
+    const m = profile.mappings.find(x => x.hostEvent === hostEvent);
+    if (!m) {
+        return { kind: 'hostRaw', actor: 'runtime', payload: { hostId: profile.hostId, hostEvent, raw: payload }, degraded: true };
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(payload)) {
+        out[m.payloadMap?.[k] ?? k] = v;
+    }
+    return { kind: m.kind, actor: m.actor, payload: out, degraded: false };
+}

package/dist/host/stdio.d.ts

@@ -0,0 +1,14 @@
+export interface StdioDispatcher {
+    (tool: string, args: Record<string, unknown>, meta?: {
+        traceparent?: string;
+    }): Promise<{
+        ok: boolean;
+        result?: unknown;
+        error?: string;
+    }>;
+}
+export interface StdioServer {
+    /** 消费 stdin 行直到结束；返回处理请求数（供测试断言） */
+    serve(input: NodeJS.ReadableStream, output: NodeJS.WritableStream): Promise<number>;
+}
+export declare function createStdioServer(dispatch: StdioDispatcher): StdioServer;

package/dist/host/stdio.js

@@ -0,0 +1,83 @@
+/**
+ * T-1 · stdio ServerTransport 实装（M3-S12）：宿主 → CAR 的 JSON-RPC over stdin/stdout
+ *
+ * 口径（M3系统设计增补 T-1 / M3部署设计增补 §4 多宿主拓扑：stdio 为 M3 主形态）：
+ *  - 换行分隔 JSON-RPC 2.0（与 M1 client 侧 gateway 同帧格式）；
+ *  - 方法面：initialize/notifications 握手（MCP 协议兼容）+ tools/list（10 tool 能力发现）+ tools/call（分发到 HostGateway.handle）；
+ *  - 所有到达请求与响应均经 HostGateway 审计（无旁路）；未登记宿主在 handle 层拒绝；
+ *  - stdin 结束（宿主退出）→ 通道关闭，进程内状态由审计日志承载（BD-02 等价：不静默丢数据）。
+ *
+ * 1.8（D-30 W3C traceparent server 侧提取）：tools/call params._meta 原样透传 dispatch 第三参——
+ * 解析/校验归装配层（trace.ts parseTraceparent fail-open），传输层保持无协议语义；未知键对端
+ * 忽略（MCP `_meta` 保留扩展点），缺席 = meta 缺省 undefined（既有调用方零改动）。
+ */
+import { createInterface } from 'node:readline';
+import { HOST_TOOLS } from './hostGateway.js';
+export function createStdioServer(dispatch) {
+    let nextId = 0;
+    // 1.6-S2：tools/call 按请求序串行派发（会话态依赖 + 响应序确定性——JSON-RPC 允许乱序，
+    // 但 stdio 宿主与测试按序解析；tools/list 等同步方法不受此链影响）
+    let callChain = Promise.resolve();
+    return {
+        async serve(input, output) {
+            let count = 0;
+            const rl = createInterface({ input });
+            const done = new Promise(resolve => rl.on('close', resolve));
+            rl.on('line', line => {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    return;
+                count++;
+                let req;
+                try {
+                    req = JSON.parse(trimmed);
+                }
+                catch {
+                    output.write(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } }) + '\n');
+                    return;
+                }
+                nextId++;
+                const respond = (result, error) => {
+                    output.write(JSON.stringify({ jsonrpc: '2.0', id: req.id ?? nextId, ...(error ? { error } : { result }) }) + '\n');
+                };
+                // MCP 协议握手（E-6 实连前置）：真实宿主客户端先发 initialize → 回 serverInfo；
+                // notifications/initialized 为无 id 通知，不响应（协议规定）
+                if (req.method === 'initialize') {
+                    respond({
+                        protocolVersion: req.params?.protocolVersion ?? '2024-11-05',
+                        capabilities: { tools: { listChanged: false } },
+                        serverInfo: { name: 'car-runtime', version: '0.3.0' },
+                    });
+                    return;
+                }
+                if (req.method === 'notifications/initialized' || (req.method ?? '').startsWith('notifications/')) {
+                    return; // 通知无响应
+                }
+                if (req.method === 'tools/list') {
+                    respond({ tools: HOST_TOOLS.map((t) => ({ name: t })) });
+                    return;
+                }
+                if (req.method === 'tools/call') {
+                    const name = req.params?.name ?? '';
+                    const args = req.params?.arguments ?? {};
+                    // 1.8-D30：_meta 原样透传（解析归装配层）；缺席 = undefined
+                    const meta = req.params?._meta;
+                    callChain = callChain
+                        .then(() => dispatch(name, args, meta))
+                        .then(r => {
+                        if (r.ok)
+                            respond({ content: [{ type: 'text', text: JSON.stringify(r.result ?? {}) }], carOk: true });
+                        else
+                            respond(undefined, { code: -32000, message: r.error ?? 'host call failed' });
+                    })
+                        .catch(e => respond(undefined, { code: -32000, message: String(e) }));
+                    return;
+                }
+                respond(undefined, { code: -32601, message: `unknown method "${req.method}"（支持 initialize / tools/list / tools/call）` });
+            });
+            await done;
+            await callChain; // 串行链收口：进程退出前最后一批调用响应写完（win32 退出断言同源教训）
+            return count;
+        },
+    };
+}

package/dist/kernel/context.d.ts

@@ -0,0 +1,76 @@
+/**
+ * CAR 微内核骨架（F1 可逆注册+依赖注入 / F9 加载-运行两阶段 / ADR-002 双模式卸载）
+ *
+ * 设计口径（《系统设计》v1.1）：
+ *  - 自研实现，范式借鉴 dsh/Cordis（inject 依赖推导、ctx.effect 可逆注册），代码不复用
+ *  - 卸载双模式（ADR-002）：strict-topo = 消费者先于提供者逐层排空（依赖计数屏障）；
+ *    concurrent = 跨 fiber Promise.all 并发。fiber 内一律注册逆序串行（确定性回卷）
+ *  - 加载期错误必须显式（冲突链定位），禁止静默覆盖（US-7/N2）
+ */
+export type Disposer = () => void | Promise<void>;
+export interface PluginDef {
+    name: string;
+    /** 声明所需服务依赖；加载顺序由依赖推导（缺依赖 = PENDING 等待，不手工编排） */
+    inject?: string[];
+    apply(ctx: PluginContext): void | Promise<void>;
+}
+export interface DisposeReport {
+    unloaded: string[];
+    /** 实际卸载顺序（strict-topo = 消费者→提供者；供治理视图审计，M2） */
+    order: string[];
+    errors: {
+        plugin: string;
+        label: string;
+        error: unknown;
+    }[];
+}
+export declare class Context {
+    private fibers;
+    private services;
+    private pending;
+    /** 提供服务（provider 侧）；重复 provide 同名服务 = 加载期显式报错（禁静默覆盖） */
+    provide(name: string, impl: unknown, provider?: string): void;
+    /** 读取服务（consumer 侧，仅限已 inject 的插件 apply 内） */
+    get(name: string): unknown;
+    /** 根作用域副作用登记（宿主 SDK 面，§3.2.M8 SDK 行）——与插件 fiber Effect 同纪律：body 即执行，disposer 入回卷清单 */
+    private rootDisposables;
+    /** 根作用域 Effect：宿主侧注册（RuntimeCore.registerLlmAdapter 等）入 disposeRuntime 回卷范围 */
+    effect(body: () => Disposer | Disposer[], label?: string): void;
+    /** 注册插件：依赖就绪即挂载，否则进入 PENDING 队列 */
+    plugin(def: PluginDef): void;
+    private mount;
+    private tryMountPending;
+    private defs;
+    /** 卸载单个插件（回卷其全部副作用；fiber 内注册逆序） */
+    unload(name: string): Promise<void>;
+    /** 运行时整体卸载（ADR-002 双模式） */
+    disposeRuntime(opts?: {
+        order?: 'strict-topo' | 'concurrent';
+    }): Promise<DisposeReport>;
+    /** 治理视图（F14）：装配配置树快照（插件/依赖/服务/副作用计数/状态）——只读，不改运行时 */
+    governanceSnapshot(): {
+        plugins: {
+            name: string;
+            inject: string[];
+            state: "ACTIVE" | "DISPOSED" | "DISPOSING" | "PENDING";
+            effects: number;
+            effectLabels: string[];
+            provides: string[];
+        }[];
+        services: {
+            name: string;
+            provider: string;
+        }[];
+        pending: string[];
+    };
+    /** 依赖图拓扑分层（Kahn 分层；环 = 加载期显式报错） */
+    private topoOrder;
+}
+/** 插件作用域上下文（effect 注册绑定到插件 fiber —— POC-2 实证的约束：不得透传根 ctx） */
+export interface PluginContext {
+    pluginName: string;
+    /** 可逆注册：body 返回 disposer 或 disposer 数组；卸载时按注册逆序回卷 */
+    effect(body: () => Disposer | Disposer[], label?: string): void;
+    provide(name: string, impl: unknown): void;
+    get(name: string): unknown;
+}

package/dist/kernel/context.js

@@ -0,0 +1,203 @@
+const DEP_CYCLE = 'CAR-E-DEPCYCLE';
+export class Context {
+    fibers = new Map();
+    services = new Map();
+    pending = [];
+    /** 提供服务（provider 侧）；重复 provide 同名服务 = 加载期显式报错（禁静默覆盖） */
+    provide(name, impl, provider = '<root>') {
+        if (this.services.has(name)) {
+            throw new Error(`${DEP_CYCLE}: service "${name}" already provided by "${this.services.get(name).provider}" (conflict chain: ${provider})`);
+        }
+        this.services.set(name, { impl, provider });
+        this.tryMountPending();
+    }
+    /** 读取服务（consumer 侧，仅限已 inject 的插件 apply 内） */
+    get(name) {
+        const s = this.services.get(name);
+        if (!s)
+            throw new Error(`${DEP_CYCLE}: service "${name}" not provided (inject 声明缺失或 provider 未就绪)`);
+        return s.impl;
+    }
+    /** 根作用域副作用登记（宿主 SDK 面，§3.2.M8 SDK 行）——与插件 fiber Effect 同纪律：body 即执行，disposer 入回卷清单 */
+    rootDisposables = [];
+    /** 根作用域 Effect：宿主侧注册（RuntimeCore.registerLlmAdapter 等）入 disposeRuntime 回卷范围 */
+    effect(body, label = 'anonymous') {
+        const res = body();
+        const disposers = typeof res === 'function' ? [res] : [...res];
+        for (const d of disposers)
+            this.rootDisposables.push({ label, disposer: d });
+    }
+    /** 注册插件：依赖就绪即挂载，否则进入 PENDING 队列 */
+    plugin(def) {
+        if (this.fibers.has(def.name)) {
+            throw new Error(`${DEP_CYCLE}: plugin "${def.name}" already registered (duplicate registration is blocked)`);
+        }
+        const fiber = { name: def.name, inject: def.inject ?? [], disposables: [], state: 'PENDING' };
+        this.fibers.set(def.name, fiber);
+        this.defs.set(def.name, def);
+        if (fiber.inject.every(d => this.services.has(d)))
+            this.mount(def, fiber);
+        else
+            this.pending.push(def.name);
+    }
+    mount(def, fiber) {
+        fiber.state = 'ACTIVE';
+        const pluginCtx = {
+            effect: (body, label = 'anonymous') => {
+                const res = body();
+                const disposers = typeof res === 'function' ? [res] : [...res];
+                for (const d of disposers)
+                    fiber.disposables.push({ label, disposer: d });
+            },
+            provide: (name, impl) => this.provide(name, impl, def.name),
+            get: (name) => this.get(name),
+            pluginName: def.name,
+        };
+        const ret = def.apply(pluginCtx);
+        if (ret && typeof ret.then === 'function')
+            throw new Error(`${DEP_CYCLE}: async apply 不被 S1 骨架支持（启动期必须同步完成注册，异步初始化请走 effect）`);
+        // 新提供的服务可能解锁 PENDING 插件
+        this.tryMountPending();
+    }
+    tryMountPending() {
+        let progressed = true;
+        while (progressed) {
+            progressed = false;
+            for (let i = this.pending.length - 1; i >= 0; i--) {
+                const name = this.pending[i];
+                const fiber = this.fibers.get(name);
+                const def = this.defs.get(name);
+                if (fiber.inject.every(d => this.services.has(d))) {
+                    this.pending.splice(i, 1);
+                    this.mount(def, fiber);
+                    progressed = true;
+                }
+            }
+        }
+    }
+    defs = new Map();
+    /** 卸载单个插件（回卷其全部副作用；fiber 内注册逆序） */
+    async unload(name) {
+        const fiber = this.fibers.get(name);
+        if (!fiber || fiber.state === 'DISPOSED')
+            return;
+        fiber.state = 'DISPOSING';
+        for (const { label, disposer } of [...fiber.disposables].reverse()) {
+            await disposer();
+        }
+        fiber.disposables = [];
+        fiber.state = 'DISPOSED';
+    }
+    /** 运行时整体卸载（ADR-002 双模式） */
+    async disposeRuntime(opts = {}) {
+        const order = this.topoOrder();
+        const report = { unloaded: [], order: [], errors: [] };
+        // 根作用域（宿主 SDK 注册面，§3.2.M8）先于插件回卷：创建序的逆 = 根最后建、最先撤
+        for (const { label, disposer } of [...this.rootDisposables].reverse()) {
+            try {
+                await disposer();
+            }
+            catch (error) {
+                report.errors.push({ plugin: '<root>', label, error });
+            }
+        }
+        this.rootDisposables = [];
+        if ((opts.order ?? 'strict-topo') === 'strict-topo') {
+            // 逐层排空：Kahn 分层为 provider→consumer 方向，卸载需反转（消费者层先于提供者层）
+            for (const layer of [...order.layers].reverse()) {
+                await Promise.all(layer.map(async (name) => {
+                    const fiber = this.fibers.get(name);
+                    if (fiber.state !== 'ACTIVE')
+                        return;
+                    fiber.state = 'DISPOSING';
+                    for (const { label, disposer } of [...fiber.disposables].reverse()) {
+                        try {
+                            await disposer();
+                        }
+                        catch (error) {
+                            report.errors.push({ plugin: name, label, error });
+                        }
+                    }
+                    fiber.disposables = [];
+                    fiber.state = 'DISPOSED';
+                    report.unloaded.push(name);
+                    report.order.push(name);
+                }));
+            }
+        }
+        else {
+            // concurrent：全部 fiber 并发（对应 dsh Fiber._unload 行为——作为降级/对照模式保留）
+            await Promise.all(order.all.map(async (name) => {
+                const fiber = this.fibers.get(name);
+                if (fiber.state !== 'ACTIVE')
+                    return;
+                fiber.state = 'DISPOSING';
+                await Promise.all([...fiber.disposables].reverse().map(async ({ label, disposer }) => {
+                    try {
+                        await disposer();
+                    }
+                    catch (error) {
+                        report.errors.push({ plugin: name, label, error });
+                    }
+                }));
+                fiber.disposables = [];
+                fiber.state = 'DISPOSED';
+                report.unloaded.push(name);
+                report.order.push(name);
+            }));
+        }
+        return report;
+    }
+    /** 治理视图（F14）：装配配置树快照（插件/依赖/服务/副作用计数/状态）——只读，不改运行时 */
+    governanceSnapshot() {
+        return {
+            plugins: [...this.fibers.values()].map(f => ({
+                name: f.name,
+                inject: [...f.inject],
+                state: f.state,
+                effects: f.disposables.length,
+                effectLabels: f.disposables.map(d => d.label),
+                provides: [...this.services.entries()].filter(([, s]) => s.provider === f.name).map(([n]) => n),
+            })),
+            services: [...this.services.entries()].map(([name, s]) => ({ name, provider: s.provider })),
+            pending: [...this.pending],
+        };
+    }
+    /** 依赖图拓扑分层（Kahn 分层；环 = 加载期显式报错） */
+    topoOrder() {
+        const active = [...this.fibers.values()].filter(f => f.state === 'ACTIVE');
+        // provider 关系：插件 P provide 了服务 s，Q inject s => Q 依赖 P（Q 先卸载）
+        const depsOf = new Map(); // name -> 依赖的 provider 集合
+        for (const f of active)
+            depsOf.set(f.name, new Set());
+        for (const [name, s] of this.services) {
+            if (depsOf.has(s.provider) && depsOf.has(name)) {
+                // name 是 inject s 的插件（近似：以插件名=服务名匹配 inject 声明）
+            }
+        }
+        for (const f of active) {
+            for (const d of f.inject) {
+                const s = this.services.get(d);
+                if (s && s.provider !== '<root>' && depsOf.has(s.provider) && s.provider !== f.name) {
+                    depsOf.get(f.name).add(s.provider);
+                }
+            }
+        }
+        // Kahn 分层
+        const remaining = new Map(depsOf);
+        const layers = [];
+        while (remaining.size) {
+            const layer = [...remaining.entries()].filter(([, deps]) => deps.size === 0).map(([n]) => n);
+            if (!layer.length)
+                throw new Error(`${DEP_CYCLE}: dependency cycle among [${[...remaining.keys()].join(', ')}]`);
+            layers.push(layer);
+            for (const n of layer)
+                remaining.delete(n);
+            for (const deps of remaining.values()) {
+                for (const n of layer)
+                    deps.delete(n);
+            }
+        }
+        return { layers, all: layers.flat() };
+    }
+}

package/dist/kernel/events.d.ts

@@ -0,0 +1,37 @@
+/**
+ * F7 · 事件分发契约（@mode 声明 + 启动期机器校验）
+ *
+ * 设计口径（《系统设计》F7：五种分发模式可裁剪起步）：
+ *  - S2 实装全部五模式：emit（广播）/ serial（有序检查点）/ bail（首断即止）/
+ *    waterfall（环绕中间件 next()）/ parallel（扇出）
+ *  - 分发模式是事件的公开契约：未声明的事件禁止注册与分发（启动期静态报错 A010003，US-7 AC2）
+ *  - 短路易错点（D3 §4.1 警示）：waterfall 观察型监听器忘调 next() 会静默截断——
+ *    文档红线 + validateWaterfallUsage 辅助检测
+ */
+export type DispatchMode = 'emit' | 'serial' | 'bail' | 'waterfall' | 'parallel';
+export declare function declareEvent(name: string, mode: DispatchMode): void;
+export declare function declaredMode(name: string): DispatchMode | undefined;
+/** 启动期机器校验：目录自洽性（声明与分发点一致性由 EventBus.dispatch 强制） */
+export declare function verifyContracts(): {
+    ok: true;
+    declared: number;
+};
+type Handler<P, R> = (payload: P, next: () => R) => R;
+export interface HandlerOpts {
+    label?: string; /** 优先级：升序小先（内核约定负值）；同优先级保持注册序（稳定排序，ES2019） */
+    priority?: number;
+}
+export declare class EventBus {
+    #private;
+    /** 注册处理器：事件未声明 = 启动期静态报错；label 与 HandlerOpts 双形态向后兼容（M1 兼容） */
+    on<P = unknown, R = unknown>(event: string, fn: Handler<P, R>, labelOrOpts?: string | HandlerOpts): void;
+    /** 治理视图（M2 F14）：返回某事件的处理器链（label+priority，按实际执行序） */
+    handlerChain(event: string): Array<{
+        label: string;
+        priority: number;
+    }>;
+    handlerCount(event: string): number;
+    /** 分发：严格按声明模式执行（声明与分发点不一致 = 契约违例） */
+    dispatch<P, R = unknown>(event: string, payload: P, init?: () => R): Promise<R | undefined>;
+}
+export {};

package/dist/kernel/events.js

@@ -0,0 +1,82 @@
+/** 事件契约目录（对应 dsh typert 生成目录的 CAR 自研等价物） */
+const catalog = new Map();
+export function declareEvent(name, mode) {
+    if (catalog.has(name) && catalog.get(name) !== mode) {
+        throw new Error(`CAR-E-CONTRACT: event "${name}" re-declared with mode "${mode}" (was "${catalog.get(name)}")`);
+    }
+    catalog.set(name, mode);
+}
+export function declaredMode(name) {
+    return catalog.get(name);
+}
+/** 启动期机器校验：目录自洽性（声明与分发点一致性由 EventBus.dispatch 强制） */
+export function verifyContracts() {
+    return { ok: true, declared: catalog.size };
+}
+export class EventBus {
+    #handlers = new Map();
+    #seq = 0;
+    /** 注册处理器：事件未声明 = 启动期静态报错；label 与 HandlerOpts 双形态向后兼容（M1 兼容） */
+    on(event, fn, labelOrOpts = 'anonymous') {
+        if (!catalog.has(event)) {
+            throw new Error(`CAR-E-CONTRACT: cannot subscribe to undeclared event "${event}"（@mode 契约缺失，先 declareEvent）`);
+        }
+        const opts = typeof labelOrOpts === 'string' ? { label: labelOrOpts } : labelOrOpts;
+        const list = this.#handlers.get(event) ?? [];
+        list.push({ fn: fn, label: opts.label ?? 'anonymous', priority: opts.priority ?? 0, seq: this.#seq++ });
+        // F11：优先级升序稳定排序（同 priority 保持注册序）
+        list.sort((a, b) => a.priority - b.priority || a.seq - b.seq);
+        this.#handlers.set(event, list);
+    }
+    /** 治理视图（M2 F14）：返回某事件的处理器链（label+priority，按实际执行序） */
+    handlerChain(event) {
+        return (this.#handlers.get(event) ?? []).map(h => ({ label: h.label, priority: h.priority }));
+    }
+    handlerCount(event) {
+        return this.#handlers.get(event)?.length ?? 0;
+    }
+    /** 分发：严格按声明模式执行（声明与分发点不一致 = 契约违例） */
+    async dispatch(event, payload, init) {
+        const mode = catalog.get(event);
+        if (!mode)
+            throw new Error(`CAR-E-CONTRACT: dispatch of undeclared event "${event}"`);
+        const handlers = [...(this.#handlers.get(event) ?? [])]; // 已按 priority 稳定排序
+        const fallback = init ?? (() => undefined);
+        switch (mode) {
+            case 'emit': // 广播：不等待、无返回值（同步通知语义）
+                for (const h of handlers) {
+                    const r = h.fn(payload, () => undefined);
+                    void r;
+                }
+                return undefined;
+            case 'serial': { // 有序检查点：await 串行，链式传值
+                let acc = fallback();
+                for (const h of handlers)
+                    acc = await h.fn(payload, () => acc);
+                return acc;
+            }
+            case 'bail': { // 首断即止：首个非 undefined 返回即终止（短路是设计意图）
+                for (const h of handlers) {
+                    const r = await h.fn(payload, () => undefined);
+                    if (r !== undefined)
+                        return r;
+                }
+                return fallback();
+            }
+            case 'waterfall': { // 环绕中间件：next() 前后均可介入，不调 next() = 短路整条链
+                let index = -1;
+                const run = async (i) => {
+                    if (i === handlers.length)
+                        return fallback();
+                    index = i;
+                    return handlers[i].fn(payload, () => run(i + 1));
+                };
+                return await run(0);
+            }
+            case 'parallel': { // 扇出：全部并发，聚合数组
+                const results = await Promise.all(handlers.map(h => h.fn(payload, () => undefined)));
+                return results;
+            }
+        }
+    }
+}

package/dist/load/config.d.ts

@@ -0,0 +1,79 @@
+export declare const CONFIG_FILENAME = "car.config.json";
+export declare const CONFIG_TS_FILENAME = "car.config.ts";
+export interface SandboxSigConfig {
+    unsignedAllow?: boolean;
+    sigEnforce?: boolean;
+    sigTrustRoot?: string;
+}
+export interface LlmConfig {
+    baseUrl?: string;
+    model?: string;
+    adapterId?: string;
+    maxTokens?: number;
+    allowEnvFallback?: boolean;
+}
+export interface McpServerSpec {
+    /** stdio 通道启动命令（与 url 互斥——1.5-S2 起二选一显式登记） */
+    command?: string;
+    args?: string[];
+    /** 启动环境变量（禁明文凭据——gateway.containsPlaintextCredential 注册时强制检查；仅 command 通道适用） */
+    env?: Record<string, string>;
+    /** 1.5-S2（D-21）：远程 Streamable HTTP 通道（与 command 互斥） */
+    url?: string;
+    /** 1.5-S2（D-21）：远程请求头；值支持 ${ENV_VAR} 引用（凭据禁令 CR-05；仅 url 通道适用） */
+    headers?: Record<string, string>;
+}
+export interface CarConfig {
+    sandbox?: SandboxSigConfig;
+    /** 1.4-S3（D-16）：模型接入配置键位空间；凭据禁入（CR-05）——只放端点/模型名/开关 */
+    llm?: LlmConfig;
+    /** 1.4-S7（D-18）：MCP server 登记面（--mcp <id> 显式启用） */
+    mcp?: {
+        servers: Record<string, McpServerSpec>;
+    };
+}
+export interface ConfigLoadResult {
+    /** 实际读取的配置文件路径（cwd 未发现时缺省——未发现是正常态非错误） */
+    path?: string;
+    config: CarConfig;
+    /** fail-visible：显式路径不存在 / 坏 JSON / 坏 TS / 未登记键 / 类型错的原因（非空 = 调用方必须中止） */
+    error?: string;
+}
+/**
+ * 1.5-S3（D-22）→ 1.6-S3（D-24）：car.config.ts 载体预热。
+ * jiti 自包含转译（每 epoch 新实例 + moduleCache 关 = 击穿语义与 1.5 等价）——
+ * Node 22.19+ 无需 --experimental-transform-types；直接调用 loadCarConfig 的库方
+ * 在存在 car.config.ts 时须先 await 本函数（CLI 入口统一预热，协议不变）。
+ */
+export declare function warmCarConfig(opts?: {
+    explicitPath?: string;
+    cwd?: string;
+}): Promise<void>;
+/** 加载配置：显式路径（必须存在，否则报错）或 cwd 发现（未发现 = 正常态返回空配置） */
+export declare function loadCarConfig(opts?: {
+    explicitPath?: string;
+    cwd?: string;
+}): ConfigLoadResult;
+/** 合并产出（mode/unsignedAllow 恒有值——比 SignatureGateOptions 的可选字段更窄，doctor 等消费方免缺省分支） */
+export interface ResolvedSignatureGate {
+    mode: 'warn' | 'enforce';
+    trustRootPublicKey?: string;
+    unsignedAllow: boolean;
+}
+/**
+ * 1.4-S3（D-16）：模型接入配置合并（flag > env > 配置 > 缺省）。
+ * env 已定义为显式意见（压过配置），未定义落配置层——与 mergeSignatureGate 同纪律。
+ * 凭据不在此层（CR-05）：走 CredentialService（keychain → env OPENAI_API_KEY/ANTHROPIC_API_KEY/
+ * CAR_LLM_API_KEY，env fallback 需显式开启 = CAR_ALLOW_ENV_CREDENTIALS=1 或 llm.allowEnvFallback）。
+ */
+export declare function mergeLlmConfig(env: NodeJS.ProcessEnv, cfg: CarConfig, flags?: {
+    baseUrl?: string;
+    model?: string;
+    adapterId?: string;
+    maxTokens?: number;
+}): LlmConfig;
+/**
+ * 优先级合并（flag > env > 配置 > 缺省）：产出装载签名门选项。
+ * flagEnforce = CLI --sig-enforce；env 已定义即为显式意见（压过配置），未定义落配置层。
+ */
+export declare function mergeSignatureGate(env: NodeJS.ProcessEnv, cfg: CarConfig, flagEnforce?: boolean): ResolvedSignatureGate;