@lqc123qwe/car-runtime 1.0.0-rc.1

package/src/host/hostGateway.ts

@@ -0,0 +1,98 @@
+/**
+ * T-1 · HostGateway（M3-S11 骨架）：CAR-as-MCP-Server 接入面
+ *
+ * 口径（M3系统设计增补 T-1 / 决议⑤ MCP 统一边界双宿主等价）：
+ *  - 9 tool 粗粒度会话级能力 + 工具面透传：session_start/turn/stop/status/replay/verify/export
+ *    + tool_list/tool_call——step 循环不暴露（「统一边界而非统一内部」）；
+ *  - hostId 登记制（A050001 语义扩展）：未登记宿主拒绝连接；
+ *  - ServerTransport 对偶（gateway.ts）：宿主作为 MCP client 经 tools/call 调用；
+ *  - tool handlers 由注入的 RuntimeFacade 提供（S12 接线 Claude Code、S13 Codex + 契约测试）；
+ *  - 所有宿主调用 100% 落审计（audit 钩子，复用 SessionLog）。
+ */
+import type { JsonRpcResponse, ServerTransport } from '../mcp/gateway.ts'
+import { deriveSessionId, normalizeHostEvent, type HostProfile } from './mappings.ts'
+
+export const HOST_TOOLS = [
+  'session_start', 'session_turn', 'session_stop', 'session_status',
+  'session_replay', 'session_verify', 'session_export', 'tool_list', 'tool_call',
+] as const
+export type HostTool = (typeof HOST_TOOLS)[number]
+
+export interface RuntimeFacade {
+  sessionStart(args: { hostSessionId: string }): Promise<{ sessionId: string }>
+  sessionTurn(args: { sessionId: string; input: unknown }): Promise<{ reason: string; steps: number }>
+  sessionStop(args: { sessionId: string }): Promise<{ reason: string }>
+  sessionStatus(args: { sessionId: string }): Promise<{ state: string; lastReason?: string }>
+  sessionReplay(args: { sessionId: string }): Promise<{ messages: unknown[] }>
+  sessionVerify(args: { sessionId: string }): Promise<{ ok: boolean; brokenAt: number | null }>
+  sessionExport(args: { sessionId: string }): Promise<{ bundle: unknown }>
+  toolList(args: Record<string, never>): Promise<{ tools: string[] }>
+  toolCall(args: { sessionId: string; tool: string; arguments?: Record<string, unknown> }): Promise<{ ok: boolean; result?: unknown; error?: string }>
+}
+
+export interface HostRegistration { hostId: string; profile: HostProfile; transport: ServerTransport }
+
+export class HostGateway {
+  #hosts = new Map<string, HostRegistration>()
+  #audit: (event: { kind: string; detail: Record<string, unknown>; ts: number }) => void
+
+  constructor(opts: { facade: RuntimeFacade; audit: (event: { kind: string; detail: Record<string, unknown>; ts: number }) => void }) {
+    this.#facade = opts.facade
+    this.#audit = opts.audit
+  }
+  #facade: RuntimeFacade
+
+  /** 宿主登记（A050001 语义扩展：重复登记显式报错） */
+  registerHost(reg: HostRegistration): void {
+    if (this.#hosts.has(reg.hostId)) throw new Error(`CAR-E-HOST: hostId "${reg.hostId}" already registered（登记制）`)
+    this.#hosts.set(reg.hostId, reg)
+  }
+
+  listHosts(): string[] { return [...this.#hosts.keys()] }
+
+  /** 暴露给宿主的 tool 面（契约测试数据源：两宿主调用此方法结果必须等价） */
+  listTools(): HostTool[] { return [...HOST_TOOLS] }
+
+  /** 宿主到达调用分发：登记检查 → tool 分发 → 归一化 → 审计（无旁路） */
+  async handle(hostId: string, tool: string, args: Record<string, unknown>): Promise<{ ok: boolean; result?: unknown; error?: string }> {
+    const host = this.#hosts.get(hostId)
+    if (!host) {
+      this.#audit({ kind: 'host-rejected', detail: { hostId, tool, reason: 'A050001' }, ts: Date.now() })
+      return { ok: false, error: 'CAR-A050001: unregistered host connection rejected（登记制）' }
+    }
+    if (!(HOST_TOOLS as readonly string[]).includes(tool)) {
+      return { ok: false, error: `unknown host tool "${tool}"（9 tool 面，step 循环不暴露）` }
+    }
+    // tool 名（snake_case MCP 约定）→ facade 方法（camelCase TS 约定）
+    const camel = tool.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase())
+    const fn = (this.#facade as unknown as Record<string, (a: Record<string, unknown>) => Promise<unknown>>)[camel]
+    if (typeof fn !== 'function') return { ok: false, error: `host tool "${tool}" not wired in RuntimeFacade（S12 接线）` }
+    try {
+      const result = await fn.call(this.#facade, { ...args, __hostId: hostId })
+      this.#audit({ kind: 'host-call', detail: { hostId, tool, normalized: tool !== 'session_start' ? undefined : deriveSessionId(hostId, String((args as { hostSessionId: string }).hostSessionId)) }, ts: Date.now() })
+      return { ok: true, result }
+    } catch (e) {
+      this.#audit({ kind: 'host-call-error', detail: { hostId, tool, error: String(e) }, ts: Date.now() })
+      return { ok: false, error: String(e) }
+    }
+  }
+
+  /** ServerTransport 装配：把 JSON-RPC tools/call 桥到 handle（S12 接 Claude Code stdio） */
+  bindTransport(hostId: string): void {
+    const host = this.#hosts.get(hostId)
+    if (!host) throw new Error('CAR-A050001: cannot bind unregistered host')
+    void (host.transport as ServerTransport & { __bind?: unknown })
+  }
+}
+
+/** 归一化便捷入口：宿主事件 → CAR 事件（mappings.ts 的 gateway 侧封装，供 S12 数据流接线） */
+export function ingestHostEvent(hostId: string, hostEvent: string, payload: Record<string, unknown>): ReturnType<typeof normalizeHostEvent> {
+  const profile = HOST_MAPPINGS_BY_ID.get(hostId)
+  if (!profile) throw new Error(`CAR-A050001: host "${hostId}" not registered（归一化前必须登记）`)
+  return normalizeHostEvent(profile, hostEvent, payload)
+}
+
+import { HOST_MAPPINGS } from './mappings.ts'
+const HOST_MAPPINGS_BY_ID = new Map(HOST_MAPPINGS.map(h => [h.hostId, h]))
+
+void (0 as unknown as JsonRpcResponse) // 类型锚：ServerTransport 响应契约

package/src/host/mappings.ts

@@ -0,0 +1,74 @@
+/**
+ * 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'
+import type { EventKind } from '../session/log.ts'
+
+/** 跨宿主会话 id：SH- 前缀 + 24 hex（sha256 前 12 字节） */
+export function deriveSessionId(hostId: string, hostSessionId: string): string {
+  return 'SH-' + createHash('sha256').update(`${hostId}|${hostSessionId}`).digest('hex').slice(0, 24)
+}
+
+export interface HostEventMapping {
+  /** 宿主事件名（精确匹配 v1；glob/regex v2 评估） */
+  hostEvent: string
+  kind: EventKind
+  actor: 'user' | 'model' | 'plugin' | 'runtime'
+  /** 宿主 payload 字段 → CAR payload 字段（浅拷贝重命名） */
+  payloadMap?: Record<string, string>
+}
+
+export interface HostProfile {
+  hostId: string
+  /** 映射表版本（契约变更须升版本 + 双轨过渡一个迭代） */
+  schemaVersion: 'host-mappings-v1'
+  mappings: HostEventMapping[]
+}
+
+/** host-mappings-v1：Claude Code / Codex 等价映射（同一接入面，两份纯数据 profile） */
+export const HOST_MAPPINGS: HostProfile[] = [
+  {
+    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' },
+    ],
+  },
+]
+
+export interface NormalizedEvent { kind: EventKind; actor: string; payload: Record<string, unknown>; degraded: boolean }
+
+/** 事件归一化：命中映射 → 转写；未命中 → hostRaw 降级（payload 原样保留，零静默） */
+export function normalizeHostEvent(profile: HostProfile, hostEvent: string, payload: Record<string, unknown> = {}): NormalizedEvent {
+  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: Record<string, unknown> = {}
+  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/src/host/stdio.ts

@@ -0,0 +1,74 @@
+/**
+ * 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（9 tool 能力发现）+ tools/call（分发到 HostGateway.handle）；
+ *  - 所有到达请求与响应均经 HostGateway 审计（无旁路）；未登记宿主在 handle 层拒绝；
+ *  - stdin 结束（宿主退出）→ 通道关闭，进程内状态由审计日志承载（BD-02 等价：不静默丢数据）。
+ */
+import { createInterface } from 'node:readline'
+import { HOST_TOOLS, type HostTool } from './hostGateway.ts'
+
+export interface StdioDispatcher {
+  (tool: string, args: Record<string, unknown>): Promise<{ ok: boolean; result?: unknown; error?: string }>
+}
+
+export interface StdioServer {
+  /** 消费 stdin 行直到结束；返回处理请求数（供测试断言） */
+  serve(input: NodeJS.ReadableStream, output: NodeJS.WritableStream): Promise<number>
+}
+
+export function createStdioServer(dispatch: StdioDispatcher): StdioServer {
+  let nextId = 0
+  return {
+    async serve(input, output) {
+      let count = 0
+      const rl = createInterface({ input })
+      const done = new Promise<void>(resolve => rl.on('close', resolve))
+      rl.on('line', line => {
+        const trimmed = line.trim()
+        if (!trimmed) return
+        count++
+        let req: { id?: number; method?: string; params?: { name?: string; arguments?: Record<string, unknown> } }
+        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: unknown, error?: { code: number; message: string }) => {
+          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 as { protocolVersion?: string } | undefined)?.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: HostTool) => ({ name: t })) })
+          return
+        }
+        if (req.method === 'tools/call') {
+          const name = req.params?.name ?? ''
+          const args = req.params?.arguments ?? {}
+          void dispatch(name, args).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
+      return count
+    },
+  }
+}

package/src/kernel/context.ts

@@ -0,0 +1,208 @@
+/**
+ * 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 }[]
+}
+interface Fiber {
+  name: string
+  inject: string[]
+  disposables: { label: string; disposer: Disposer }[]
+  state: 'PENDING' | 'ACTIVE' | 'DISPOSING' | 'DISPOSED'
+}
+
+const DEP_CYCLE = 'CAR-E-DEPCYCLE'
+
+export class Context {
+  private fibers = new Map<string, Fiber>()
+  private services = new Map<string, { impl: unknown; provider: string }>()
+  private pending: string[] = []
+
+  /** 提供服务（provider 侧）；重复 provide 同名服务 = 加载期显式报错（禁静默覆盖） */
+  provide(name: string, impl: unknown, provider = '<root>'): void {
+    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: string): unknown {
+    const s = this.services.get(name)
+    if (!s) throw new Error(`${DEP_CYCLE}: service "${name}" not provided (inject 声明缺失或 provider 未就绪)`)
+    return s.impl
+  }
+
+  /** 注册插件：依赖就绪即挂载，否则进入 PENDING 队列 */
+  plugin(def: PluginDef): void {
+    if (this.fibers.has(def.name)) {
+      throw new Error(`${DEP_CYCLE}: plugin "${def.name}" already registered (duplicate registration is blocked)`)
+    }
+    const fiber: 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)
+  }
+
+  private mount(def: PluginDef, fiber: Fiber): void {
+    fiber.state = 'ACTIVE'
+    const pluginCtx: PluginContext = {
+      effect: (body: () => Disposer | Disposer[], label = 'anonymous') => {
+        const disposers = typeof body === 'function' ? [body()] : [...body()]
+        for (const d of disposers) fiber.disposables.push({ label, disposer: d as Disposer })
+      },
+      provide: (name: string, impl: unknown) => this.provide(name, impl, def.name),
+      get: (name: string) => this.get(name),
+      pluginName: def.name,
+    }
+    const ret = def.apply(pluginCtx)
+    if (ret && typeof (ret as any).then === 'function') throw new Error(`${DEP_CYCLE}: async apply 不被 S1 骨架支持（启动期必须同步完成注册，异步初始化请走 effect）`)
+    // 新提供的服务可能解锁 PENDING 插件
+    this.tryMountPending()
+  }
+
+  private tryMountPending(): void {
+    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
+        }
+      }
+    }
+  }
+
+  private defs = new Map<string, PluginDef>()
+
+  /** 卸载单个插件（回卷其全部副作用；fiber 内注册逆序） */
+  async unload(name: string): Promise<void> {
+    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: { order?: 'strict-topo' | 'concurrent' } = {}): Promise<DisposeReport> {
+    const order = this.topoOrder()
+    const report: DisposeReport = { unloaded: [], order: [], errors: [] }
+    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 分层；环 = 加载期显式报错） */
+  private topoOrder(): { layers: string[][]; all: string[] } {    const active = [...this.fibers.values()].filter(f => f.state === 'ACTIVE')
+    // provider 关系：插件 P provide 了服务 s，Q inject s => Q 依赖 P（Q 先卸载）
+    const depsOf = new Map<string, Set<string>>() // 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: string[][] = []
+    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() }
+  }
+}
+
+/** 插件作用域上下文（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/src/kernel/events.ts

@@ -0,0 +1,99 @@
+/**
+ * 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'
+
+/** 事件契约目录（对应 dsh typert 生成目录的 CAR 自研等价物） */
+const catalog = new Map<string, DispatchMode>()
+
+export function declareEvent(name: string, mode: DispatchMode): void {
+  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: string): DispatchMode | undefined {
+  return catalog.get(name)
+}
+
+/** 启动期机器校验：目录自洽性（声明与分发点一致性由 EventBus.dispatch 强制） */
+export function verifyContracts(): { ok: true; declared: number } {
+  return { ok: true, declared: catalog.size }
+}
+
+type Handler<P, R> = (payload: P, next: () => R) => R
+
+export interface HandlerOpts { label?: string; /** 优先级：升序小先（内核约定负值）；同优先级保持注册序（稳定排序，ES2019） */ priority?: number }
+
+export class EventBus {
+  #handlers = new Map<string, Array<{ fn: Handler<any, any>; label: string; priority: number; seq: number }>>()
+  #seq = 0
+
+  /** 注册处理器：事件未声明 = 启动期静态报错；label 与 HandlerOpts 双形态向后兼容（M1 兼容） */
+  on<P = unknown, R = unknown>(event: string, fn: Handler<P, R>, labelOrOpts: string | HandlerOpts = 'anonymous'): void {
+    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 as Handler<any, any>, 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: string): Array<{ label: string; priority: number }> {
+    return (this.#handlers.get(event) ?? []).map(h => ({ label: h.label, priority: h.priority }))
+  }
+
+  handlerCount(event: string): number {
+    return this.#handlers.get(event)?.length ?? 0
+  }
+
+  /** 分发：严格按声明模式执行（声明与分发点不一致 = 契约违例） */
+  async dispatch<P, R = unknown>(event: string, payload: P, init?: () => R): Promise<R | undefined> {
+    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 as R)
+    switch (mode) {
+      case 'emit': // 广播：不等待、无返回值（同步通知语义）
+        for (const h of handlers) { const r = h.fn(payload, () => undefined as R); 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 as R)
+          if (r !== undefined) return r
+        }
+        return fallback()
+      }
+      case 'waterfall': { // 环绕中间件：next() 前后均可介入，不调 next() = 短路整条链
+        let index = -1
+        const run = async (i: number): Promise<R> => {
+          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 as R)))
+        return results as unknown as R
+      }
+    }
+  }
+}