@lqc123qwe/car-runtime 1.0.0 → 1.1.0

package/src/load/sign.ts

@@ -0,0 +1,60 @@
+/**
+ * 1.1-S1 · plugin-sign 签名原语（keygen / sign 纯函数；verify 复用 sigGate.verifyPluginFile）
+ *
+ * 口径（与 M2-S6 verifier / M5-S28 sigGate 签验同源，逐字对齐签名强制启用指南 §2）：
+ *  - 被签物 = 插件入口 .ts 文件裸字节 sha256 的 hex 串；被签消息 = hex 字符串的 UTF-8 字节
+ *    （sigGate.ts 头注释同源；哈希对裸字节求——G-11 教训：禁止对编码文本求哈希）
+ *  - 私钥 = ed25519 PKCS8 DER 文件（<前缀>.priv）；公钥 = SPKI DER base64（<前缀>.pub，
+ *    即 CAR_TRUST_ROOT 信任根值）；sidecar = `<file>.minisig` 单段 base64（sigGate 读取口径）
+ *  - 本模块只产出密钥与签名；门禁判定（warn/enforce 分级、fail-closed 分级）在 verifier/sigGate——
+ *    sign 不判门。边界登记（1.1 规划 W2-1）：minisign 离线单轨；sigstore keyless 主轨延后（1.2 候选）
+ */
+import { createHash, generateKeyPairSync, sign as cryptoSign } from 'node:crypto'
+import { readFileSync, writeFileSync } from 'node:fs'
+
+export interface SigningKeypair {
+  /** PKCS8 DER 私钥字节（写 <前缀>.priv；离线保管不入仓库——secrets 红线） */
+  privateKeyDer: Buffer
+  /** SPKI DER base64 公钥（写 <前缀>.pub；即 CAR_TRUST_ROOT 信任根值） */
+  publicKeyBase64: string
+}
+
+/** ed25519 签名密钥对生成（指南 §2 第 1 步 node -e 流程固化） */
+export function generateSigningKeypair(): SigningKeypair {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519')
+  return {
+    privateKeyDer: privateKey.export({ type: 'pkcs8', format: 'der' }) as Buffer,
+    publicKeyBase64: publicKey.export({ type: 'spki', format: 'der' }).toString('base64'),
+  }
+}
+
+export interface SignResult {
+  file: string
+  sidecar: string
+  /** 文件裸字节 sha256 hex（横幅指纹与审计留痕口径同 sigGate.manifestHash） */
+  manifestHash: string
+}
+
+/** 对单文件签名并写 sidecar `<file>.minisig`（指南 §2 第 2 步 node -e 流程固化） */
+export function signPluginFile(file: string, privateKeyDer: Buffer): SignResult {
+  const manifestHash = createHash('sha256').update(readFileSync(file)).digest('hex')
+  const minisig = cryptoSign(null, Buffer.from(manifestHash), { key: privateKeyDer, format: 'der', type: 'pkcs8' }).toString('base64')
+  const sidecar = `${file}.minisig`
+  writeFileSync(sidecar, minisig)
+  return { file, sidecar, manifestHash }
+}
+
+/** 信任根解析（plugin-sign verify 用）：显式 flag > CAR_TRUST_ROOT env > <前缀>.pub 文件 */
+export function resolveTrustRoot(opts: { flag?: string; env?: NodeJS.ProcessEnv; pubFilePath?: string }): { value?: string; source: 'flag' | 'env' | 'pubfile' | 'none' } {
+  if (opts.flag) return { value: opts.flag, source: 'flag' }
+  const envVal = opts.env?.CAR_TRUST_ROOT
+  if (envVal) return { value: envVal, source: 'env' }
+  const pub = opts.pubFilePath
+  if (pub) {
+    try {
+      const v = readFileSync(pub, 'utf-8').trim()
+      if (v) return { value: v, source: 'pubfile' }
+    } catch { /* pub 文件不可读 → 视同未提供，由调用方显式报错 */ }
+  }
+  return { value: undefined, source: 'none' }
+}

package/src/runtime-core/chatStep.ts

@@ -0,0 +1,121 @@
+/**
+ * M8 · SQ-07 模型接入集成（chat → 流式消费 → assistant 落 M7 → ModelStep 交 M4 状态机）
+ *
+ * 时序对齐（§3.2.M8.4 SQ-07 逐行）：
+ *  1. 请求前断言：assertModelVisibleLogged（配合 M7，N1 不变量前置）；
+ *  2. 请求消息 = log.deriveMessages() 投影——Model-visible means logged 由构造保证
+ *     （本层不引入任何未落链的模型可见输入：新增可见输入必须新增事件类型，§3.5.5 红线；
+ *     system prompt 组装属 M4/M2 职责，v1 不在本层旁路）；
+ *  3. 凭据解析在适配器内（resolve→reveal，A080001 在首块前抛出 → runTurn catch → turn error，
+ *     用户文案引导 car doctor）；
+ *  4. 流式消费：delta 过 StreamRedactor（跨 chunk 命中不泄漏）+ toolCallDelta 聚合
+ *     （半截 JSON 不解析——ADR-001 同纪律，length 时只交 truncatedTools）；
+ *  5. assistant 文本事件落 M7（脱敏后 + secretsRedacted 计数留痕 meta）；
+ *  6. finishReason 不可变透传为 ModelStep.stopReason（error/aborted → 'error'，BD-04 收口
+ *     由 runTurn 落 turnEnd）；工具调用事件由 runTurn executeBatch 落（本层不重复）。
+ */
+import type { SessionLog } from '../session/log.ts'
+import type { ModelStep, ToolCall } from '../loop/stop.ts'
+import type { RuntimeCore } from './llm.ts'
+import type { ToolDefinition } from './types.ts'
+import { StreamRedactor } from './redaction.ts'
+import { scanSecrets } from '../security/secrets.ts'
+import { providerUnreachable } from './errors.ts'
+
+export interface ChatStepOptions {
+  core: RuntimeCore
+  log: SessionLog
+  turnId: string
+  /** 模型名（provider 侧路由） */
+  model: string
+  /** 工具声明面（ToolDefinition 含 declaredSideEffect；不出站权限面仅 schema） */
+  tools: ToolDefinition[]
+  maxTokens?: number
+  adapterId?: string
+}
+
+/** ModelStep 加法扩展：脱敏计数留痕（S15 secretsRedacted 同名口径） */
+export type ChatStepResult = ModelStep & { secretsRedacted: number }
+
+export async function chatStep(opts: ChatStepOptions): Promise<ChatStepResult> {
+  const { core, log, turnId, model, tools, maxTokens, adapterId } = opts
+
+  // 1. 请求前断言（SQ-07 #2）：N1 失守 = 带病请求，显式拒绝
+  const asserted = log.assertModelVisibleLogged()
+  if (!asserted.ok) {
+    throw new Error(`CAR-E-N1: 模型请求前快照与日志投影失配 @ atSeq=${asserted.failedAt}（Model-visible means logged 违规）`)
+  }
+
+  // 2. 请求消息 = 投影（角色系统：user/assistant/toolResult 与 LlmRequest 对齐；
+  //    assistant 工具调用以 { toolCall } content 形态原样透传——deriveMessages 投影即模型可见流）
+  const messages = log.deriveMessages().map(m => ({
+    role: m.role as 'user' | 'assistant' | 'toolResult',
+    content: m.content,
+  }))
+
+  // 4. 流式消费（3. 凭据解析在适配器首块前，A080001 由此传播）
+  const redactor = new StreamRedactor()
+  let text = ''
+  const calls = new Map<number, { id?: string; name?: string; argsBuf: string }>()
+  let stopReason: ModelStep['stopReason'] | undefined
+  let errorDetail: string | undefined
+
+  const stream = core.chat({
+    model,
+    messages,
+    tools,
+    ...(maxTokens != null ? { maxTokens } : {}),
+    ...(adapterId ? { adapterId } : {}),
+    ...(opts.log.sessionId ? { metadata: { sessionId: opts.log.sessionId, turnId, traceId: `${opts.log.sessionId}:${turnId}` } } : {}),
+  })
+  for await (const chunk of stream) {
+    if (chunk.delta !== undefined) text += redactor.push(chunk.delta)
+    if (chunk.toolCallDelta) {
+      const idx = chunk.toolCallDelta.index ?? 0
+      const cur = calls.get(idx) ?? { argsBuf: '' }
+      if (chunk.toolCallDelta.id) cur.id = chunk.toolCallDelta.id
+      if (chunk.toolCallDelta.name) cur.name = chunk.toolCallDelta.name
+      if (chunk.toolCallDelta.argumentsDelta) cur.argsBuf += chunk.toolCallDelta.argumentsDelta
+      calls.set(idx, cur)
+    }
+    if (chunk.error) errorDetail = chunk.error.message
+    if (chunk.finishReason !== undefined) stopReason = chunk.finishReason === 'aborted' ? 'error' : chunk.finishReason
+  }
+  if (stopReason === undefined) {
+    // 适配器层已保证首 finishReason（AL-05）；防御性兜底显式化
+    throw new Error('CAR-E-LLM-FINISH: 流结束无 finishReason（适配器契约违规）')
+  }
+  text += redactor.flush()
+
+  // 5. assistant 文本落 M7（脱敏后 + 计数留痕；空文本不产事件）
+  //    flush 后兜底复扫只计数不复写：流式遮蔽已生效，>0 即流式边界逃逸的审计信号
+  let secretsRedacted = 0
+  if (text.length) {
+    secretsRedacted = scanSecrets(text).hits.length
+    log.append('model', 'assistant', turnId, text, { secretsRedacted })
+  }
+
+  // 6. finishReason → ModelStep（不可变透传；length 不解析 args——ADR-001 解析前收口）
+  if (stopReason === 'length') {
+    const truncated = [...calls.values()].filter(c => c.id || c.name).map(c => ({ id: c.id ?? `tc-${c.name ?? 'unknown'}`, tool: c.name ?? 'unknown' }))
+    return { stopReason: 'length', ...(text ? { text } : {}), truncatedTools: truncated, secretsRedacted }
+  }
+  if (stopReason === 'toolUse') {
+    const toolCalls: ToolCall[] = []
+    for (const [idx, c] of [...calls.entries()].sort((a, b) => a[0] - b[0])) {
+      if (!c.name) continue
+      let args: Record<string, unknown>
+      try { args = c.argsBuf ? JSON.parse(c.argsBuf) as Record<string, unknown> : {} } catch {
+        // toolUse 声明下 args 非法 JSON = 协议违规显式化（非 length 场景无 truncatedTools 口径）
+        throw new Error(`CAR-E-LLM-PROTO: 工具调用 ${c.name} 参数非法 JSON（finishReason=${stopReason}，${errorDetail ?? '无附加错误'}）`)
+      }
+      toolCalls.push({ id: c.id ?? `tc-${idx}-${c.name}`, tool: c.name, args })
+    }
+    return { stopReason: 'toolUse', ...(text ? { text } : {}), ...(toolCalls.length ? { toolCalls } : {}), secretsRedacted }
+  }
+  // error（含 aborted 映射）：以 B080001 抛出 → runTurn catch → turnEnd error 携带 detail（BD-04 收口）
+  if (stopReason === 'error') {
+    throw providerUnreachable(errorDetail ?? 'provider 返回 error 终止（无附加说明）')
+  }
+  return { stopReason: 'stop', ...(text ? { text } : {}), secretsRedacted }
+}

package/src/runtime-core/credentials.ts

@@ -0,0 +1,135 @@
+/**
+ * M8 · 凭据门（resolveCredential ——《系统设计》§3.2.M8.2 凭据行 / SQ-07 凭据解析 / O-13）
+ *
+ * 口径：
+ *  - 解析链：OS Keychain（C-03）→ env fallback（**需用户显式开启**——§3.2.M8.3 字段表
+ *    「env 需用户显式开启 fallback」）；全落空 = CarM8Error A080001（不重试，引导 car doctor）；
+ *  - Keychain 通道按平台探测（能力探测三件套：命令在场的显式探测，缺席显式降级不静默）：
+ *    darwin = `security find-generic-password`、linux = `secret-tool`、
+ *    win32 = 零依赖读通道缺席（cmdkey 仅列举不可读值）→ 显式降级登记；
+ *  - CredentialRef 不落明文（O-13）：ref 只含 provider/source/origin；明文经 reveal() 按需取用，
+ *    reveal 必须经审计回调（provider+source 留痕，值不入审计——值入日志即泄露面，secrets 红线）；
+ *  - 环境变量约定：OPENAI_API_KEY（openai-compat）/ ANTHROPIC_API_KEY（anthropic）/
+ *    CAR_LLM_API_KEY（通用兜底）；显式开启 = opts.allowEnvFallback 或 CAR_ALLOW_ENV_CREDENTIALS=1。
+ */
+import { spawnSync } from 'node:child_process'
+import { CarM8Error, credentialMissing } from './errors.ts'
+import type { CredentialRef, CredentialSource } from './types.ts'
+
+export interface CredentialResolveOptions {
+  /** 测试注入；缺省取 process.env */
+  env?: NodeJS.ProcessEnv
+  /** env fallback 显式开启（规格要求默认关；CAR_ALLOW_ENV_CREDENTIALS=1 等效） */
+  allowEnvFallback?: boolean
+  /**
+   * keychain 读取器注入（测试替身）：入参 keychain 服务名，返回明文或 null（不存在）。
+   * 缺省用平台命令真实读取；平台无读通道（win32）= 通道不可用（显式降级）。
+   */
+  keychainReader?: (service: string) => string | null
+  /** reveal 审计回调（值不入参——审计全量留痕但零明文） */
+  audit?: (event: { action: 'resolve' | 'reveal'; provider: string; source: CredentialSource; origin: string }) => void
+}
+
+/** provider → 候选 env 变量（按序检索；CAR_LLM_API_KEY 为通用兜底） */
+const PROVIDER_ENV_VARS: Record<string, string[]> = {
+  'openai-compat': ['OPENAI_API_KEY'],
+  anthropic: ['ANTHROPIC_API_KEY'],
+}
+const GENERIC_ENV_VARS = ['CAR_LLM_API_KEY']
+
+/** keychain 服务名（命名空间隔离：car-runtime/<provider>） */
+export function keychainService(provider: string): string {
+  return `car-runtime/${provider}`
+}
+
+interface KeychainChannel { reader: ((service: string) => string | null) | null; note: string }
+
+/** 平台 keychain 通道探测：命令在场（darwin/linux）→ 真实读取器；无读通道（win32）→ 显式 null */
+export function probeKeychainChannel(platform: NodeJS.Platform = process.platform): KeychainChannel {
+  if (platform === 'darwin') {
+    return { reader: service => {
+      const r = spawnSync('security', ['find-generic-password', '-s', service, '-w'], { encoding: 'utf-8', timeout: 5000 })
+      if (r.status !== 0 || r.stdout == null) return null
+      return r.stdout.replace(/\r?\n$/, '') || null
+    }, note: 'darwin security' }
+  }
+  if (platform === 'linux') {
+    return { reader: service => {
+      const r = spawnSync('secret-tool', ['lookup', 'service', service], { encoding: 'utf-8', timeout: 5000 })
+      if (r.status !== 0 || r.stdout == null) return null
+      return r.stdout.replace(/\r?\n$/, '') || null
+    }, note: 'linux secret-tool' }
+  }
+  // win32 及其他：无零依赖读通道——显式不可用（禁静默假装有 keychain）
+  return { reader: null, note: `keychain 读通道在 ${platform} 缺席（零依赖实现无 OS 凭据库读取面）——显式降级` }
+}
+
+export class CredentialService {
+  readonly #channel: KeychainChannel
+  readonly #platform: NodeJS.Platform
+
+  constructor(opts: { keychainReader?: (service: string) => string | null; platform?: NodeJS.Platform } = {}) {
+    this.#platform = opts.platform ?? process.platform
+    this.#channel = opts.keychainReader
+      ? { reader: opts.keychainReader, note: 'injected reader' }
+      : probeKeychainChannel(this.#platform)
+  }
+
+  /** keychain 通道状态（doctor 展示/测试断言；缺席显式登记不静默） */
+  get channelStatus(): { available: boolean; note: string } {
+    return { available: this.#channel.reader !== null, note: this.#channel.note }
+  }
+
+  /**
+   * 解析凭据引用（天然幂等；返回值不含明文）。
+   * 检索顺序：keychain →（显式开启时）env；全落空 = A080001。
+   */
+  resolve(provider: string, opts: CredentialResolveOptions = {}): CredentialRef {
+    const env = opts.env ?? process.env
+    const searched: string[] = []
+    const service = keychainService(provider)
+
+    if (this.#channel.reader) {
+      searched.push(`keychain:${service}`)
+      const value = this.#channel.reader(service)
+      if (value) {
+        opts.audit?.({ action: 'resolve', provider, source: 'keychain', origin: service })
+        return { provider, source: 'keychain', origin: service }
+      }
+    } else {
+      searched.push(`keychain:${service}(通道缺席)`)
+    }
+
+    const allowEnv = opts.allowEnvFallback === true || env.CAR_ALLOW_ENV_CREDENTIALS === '1'
+    if (allowEnv) {
+      const candidates = [...(PROVIDER_ENV_VARS[provider] ?? []), ...GENERIC_ENV_VARS]
+      for (const name of candidates) {
+        searched.push(`env:${name}`)
+        if (env[name]) {
+          opts.audit?.({ action: 'resolve', provider, source: 'env', origin: name })
+          return { provider, source: 'env', origin: name, degraded: this.#channel.reader ? undefined : this.#channel.note }
+        }
+      }
+    } else {
+      searched.push('env(未显式开启 fallback)')
+    }
+
+    throw credentialMissing(provider, searched)
+  }
+
+  /** 按引用取明文（仅 provider 适配器请求时点调用；每次经审计留痕，值不入日志不入错误） */
+  reveal(ref: CredentialRef, opts: CredentialResolveOptions = {}): string {
+    const env = opts.env ?? process.env
+    if (ref.source === 'keychain') {
+      if (!this.#channel.reader) throw new CarM8Error('A080001', 'CAR-E-CRED-MISSING', `keychain 通道缺席，无法取值（${ref.origin}）`, '未找到模型服务凭据，请运行 car doctor', false)
+      const value = this.#channel.reader(ref.origin)
+      if (!value) throw credentialMissing(ref.provider, [`keychain:${ref.origin}(resolve 后消失)`])
+      opts.audit?.({ action: 'reveal', provider: ref.provider, source: ref.source, origin: ref.origin })
+      return value
+    }
+    const value = env[ref.origin]
+    if (!value) throw credentialMissing(ref.provider, [`env:${ref.origin}(resolve 后消失)`])
+    opts.audit?.({ action: 'reveal', provider: ref.provider, source: ref.source, origin: ref.origin })
+    return value
+  }
+}

package/src/runtime-core/errors.ts

@@ -0,0 +1,47 @@
+/**
+ * M8 · 错误面（《系统设计》§3.5.1 六位错误码 + 代码库 CAR-E-* 前缀双轨）
+ *
+ *  - A080001 凭据缺失：不重试，用户文案引导 car doctor（SQ-07 凭据缺失分支）；
+ *  - B080001 LLM Provider 不可达/重试耗尽：退避后重试（§3.5.4 基线——2 次指数退避 1s/2s）；
+ *  - 两条均为「错误路径不改写 finishReason 语义」的守门错误：流中途失败以
+ *    finishReason='error' chunk 收口（BD-04），首块前失败以 CarError 抛出（runTurn catch → turn error）。
+ */
+
+export type M8ErrorCode = 'A080001' | 'B080001'
+
+export class CarM8Error extends Error {
+  constructor(
+    /** 六位错误码（§3.5.1 注册表） */
+    readonly code: M8ErrorCode,
+    /** CAR-E-* 代码库前缀（与 CAR-E-DEPCYCLE 等同风格） */
+    readonly slug: string,
+    message: string,
+    /** 用户文案（§3.5.1 注册表原文） */
+    readonly userHint?: string,
+    /** 重试建议（A080001 不重试 / B080001 退避后重试） */
+    readonly retryable = false,
+  ) {
+    super(`${slug}: ${message}（${code}）`)
+    this.name = 'CarM8Error'
+  }
+}
+
+export function credentialMissing(provider: string, searched: string[]): CarM8Error {
+  return new CarM8Error(
+    'A080001',
+    'CAR-E-CRED-MISSING',
+    `未找到模型服务凭据（provider=${provider}，已检索：${searched.join('、') || '无可用通道'}）`,
+    '未找到模型服务凭据，请运行 car doctor',
+    false,
+  )
+}
+
+export function providerUnreachable(detail: string): CarM8Error {
+  return new CarM8Error(
+    'B080001',
+    'CAR-E-LLM-UNREACHABLE',
+    `LLM Provider 不可达/重试耗尽：${detail}`,
+    '模型服务暂时不可用，本轮已停止',
+    true,
+  )
+}

package/src/runtime-core/llm.ts

@@ -0,0 +1,304 @@
+/**
+ * M8 · LLM 适配面（chat / registerLlmAdapter ——《系统设计》§3.2.M8.2 模型与适配行 / SQ-07 / O-11）
+ *
+ * 口径：
+ *  - 适配器为 ACL（C-02）：统一 LlmAdapter 签名消解 Provider 差异；注册经 ctx.effect 可逆
+ *    （disposeRuntime 回卷后可重注册——注册即逆变换，POC-2 红线同源）；重复 id 显式报错禁静默覆盖；
+ *  - finishReason 不可变透传（ADR-001 / SR-17）：SDK 边界流包装做防御性断言——首个
+ *    finishReason 定格，冲突 = 适配器契约违规显式抛错（改写/吞没均禁止，缺失触发 AL-05 口径）；
+ *  - 重试基线（§3.5.4）：仅网络错误/429/5xx、≤2 次、指数退避 1s/2s；**首块前失败才可重试**
+ *    （已消费的 chunk 不可重放——重试不产生额外副作用）；重试耗尽 = CarM8Error B080001
+ *    （BD-04 error 收口由消费方 runTurn 落 turnEnd）；流中途失败 = finishReason 'error' chunk；
+ *  - 超时基线：总 120s / 首字节 30s（均可注入缩短供测试）；TLS 强制（https-only）；
+ *  - declaredSideEffect 不出站（权限面只进权限门，不进模型请求体）。
+ */
+import { CarM8Error, providerUnreachable } from './errors.ts'
+import { CredentialService } from './credentials.ts'
+import type { Disposable, LlmAdapter, LlmChunk, LlmRequest, ToolCallDelta } from './types.ts'
+import type { PluginContext } from '../kernel/context.ts'
+
+// ==================== 适配器注册表（registerLlmAdapter） ====================
+
+export class AdapterRegistry {
+  #adapters = new Map<string, LlmAdapter>()
+  #defaultId: string | null = null
+
+  /** 注册（幂等语义：同 id 重复注册显式报错——冲突链定位风格） */
+  register(adapter: LlmAdapter, opts: { default?: boolean } = {}): Disposable {
+    if (this.#adapters.has(adapter.id)) {
+      throw new Error(`CAR-E-LLM-DUP: LLM adapter "${adapter.id}" already registered (duplicate registration is blocked)`)
+    }
+    this.#adapters.set(adapter.id, adapter)
+    if (opts.default || this.#defaultId === null) this.#defaultId = adapter.id
+    let disposed = false
+    return {
+      dispose: () => {
+        if (disposed) return // 幂等回卷（二次 dispose 静默收敛，登记口径）
+        disposed = true
+        this.#adapters.delete(adapter.id)
+        if (this.#defaultId === adapter.id) this.#defaultId = this.#adapters.keys().next().value ?? null
+      },
+    }
+  }
+
+  /** 解析：显式 id > 默认适配器；无可用适配器显式报错（禁静默降级） */
+  get(id?: string): LlmAdapter {
+    const target = id ?? this.#defaultId
+    if (!target || !this.#adapters.has(target)) {
+      const available = [...this.#adapters.keys()].join(', ') || '无'
+      throw new Error(`CAR-E-LLM-NOADAPTER: LLM adapter "${target ?? '<default>'}" not registered（在册：${available}）`)
+    }
+    return this.#adapters.get(target)!
+  }
+
+  list(): Array<{ id: string; isDefault: boolean }> {
+    return [...this.#adapters.keys()].map(id => ({ id, isDefault: id === this.#defaultId }))
+  }
+}
+
+// ==================== finishReason 不可变守卫（SDK 边界） ====================
+
+/** 首个 finishReason 定格；适配器后续给出不同值 = 契约违规显式抛错（不改写不吞没） */
+export async function* withFinishReasonGuard(stream: AsyncIterable<LlmChunk>): AsyncIterable<LlmChunk> {
+  let settled: LlmChunk['finishReason'] | undefined
+  for await (const chunk of stream) {
+    if (chunk.finishReason !== undefined) {
+      if (settled === undefined) settled = chunk.finishReason
+      else if (settled !== chunk.finishReason) {
+        throw new Error(`CAR-E-LLM-FINISH: finishReason 已定格为 "${settled}"，适配器试图给出 "${chunk.finishReason}"（不可变透传契约违规）`)
+      }
+    }
+    yield chunk
+  }
+}
+
+// ==================== RuntimeCore（M8 SDK 面） ====================
+
+export class RuntimeCore {
+  readonly registry = new AdapterRegistry()
+  readonly credentials: CredentialService
+  #ctx: Pick<PluginContext, 'provide' | 'effect'> | null = null
+
+  constructor(credentials: CredentialService = new CredentialService()) {
+    this.credentials = credentials
+  }
+
+  /** 绑定插件作用域：服务注册 + 适配器注册进入 Effect 可逆通道（宿主传 Context——根作用域 effect 同纪律） */
+  bindContext(ctx: Pick<PluginContext, 'provide' | 'effect'>): void {
+    this.#ctx = ctx
+    ctx.provide('runtime-core', this)
+  }
+
+  /** §3.2.M8.2：registerLlmAdapter(adapter): Disposable——Effect 可逆（卸载回卷后可重注册） */
+  registerLlmAdapter(adapter: LlmAdapter, opts: { default?: boolean } = {}): Disposable {
+    if (!this.#ctx) return this.registry.register(adapter, opts)
+    let handle: Disposable | null = null
+    this.#ctx.effect(() => {
+      handle = this.registry.register(adapter, opts)
+      return () => handle?.dispose()
+    }, `llm-adapter:${adapter.id}`)
+    return { dispose: () => handle?.dispose() }
+  }
+
+  /** §3.2.M8.2：chat(req): AsyncIterable<LlmChunk>——统一入口 + finishReason 守卫 */
+  chat(req: LlmRequest): AsyncIterable<LlmChunk> {
+    const adapter = this.registry.get(req.adapterId)
+    return withFinishReasonGuard(adapter.chat(req))
+  }
+}
+
+// ==================== 内置 openai-compat 适配器（流式 SSE） ====================
+
+export interface OpenAICompatOptions {
+  id?: string
+  baseUrl: string
+  /** 凭据服务与 provider 名（Bearer token 来源） */
+  credentials?: CredentialService
+  provider?: string
+  fetchImpl?: typeof fetch
+  /** §3.5.4 基线：总 120s / 首字节 30s / 2 次退避 1s-2s（测试可注入缩短） */
+  timeoutMs?: number
+  firstByteMs?: number
+  retries?: number
+  backoffMs?: number[]
+  /** 测试注入睡眠（退避可观测；缺省真实定时器） */
+  sleep?: (ms: number) => Promise<void>
+}
+
+const FINISH_MAP: Record<string, LlmChunk['finishReason']> = {
+  stop: 'stop',
+  length: 'length',
+  tool_calls: 'toolUse',
+  function_call: 'toolUse',
+  content_filter: 'aborted',
+}
+
+class Retryable extends Error {}
+
+/** 明文 SSE → LlmChunk 流解析（增量容错：半行驻留到下一 chunk） */
+async function* parseSseStream(body: AsyncIterable<Uint8Array>): AsyncIterable<LlmChunk> {
+  const decoder = new TextDecoder()
+  let buf = ''
+  for await (const bytes of body) {
+    buf += decoder.decode(bytes, { stream: true })
+    let nl: number
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, nl).replace(/\r$/, '')
+      buf = buf.slice(nl + 1)
+      if (!line.startsWith('data:')) continue
+      const data = line.slice(5).trim()
+      if (data === '[DONE]') return
+      if (!data) continue
+      let evt: any
+      try { evt = JSON.parse(data) } catch { continue } // 心跳/注释行容错（显式跳过非 JSON data）
+      const choice = evt.choices?.[0]
+      if (!choice) continue
+      const delta = choice.delta ?? {}
+      const raw = choice.finish_reason
+      const finish: LlmChunk['finishReason'] | undefined = raw == null ? undefined : (() => {
+        const mapped = FINISH_MAP[String(raw)]
+        return mapped
+          ? mapped
+          : 'error' // 未映射信号 fail-visible（禁静默改写），raw 附在 error.message
+      })()
+      const toolCallDeltas: ToolCallDelta[] = Array.isArray(delta.tool_calls)
+        ? delta.tool_calls.map((tc: any) => ({
+            index: tc.index,
+            id: tc.id,
+            name: tc.function?.name ?? tc.name,
+            argumentsDelta: tc.function?.arguments,
+          }))
+        : []
+      const text = typeof delta.content === 'string' && delta.content.length ? delta.content : undefined
+      // LlmChunk 单 toolCallDelta 口径：同事件多条 tool_calls 顺序展开为多 chunk
+      if (!text && !toolCallDeltas.length && finish === undefined) continue
+      if (toolCallDeltas.length === 0) {
+        yield {
+          ...(text !== undefined ? { delta: text } : {}),
+          ...(finish !== undefined
+            ? { finishReason: finish, ...(finish === 'error' ? { error: { code: 'B080001', message: `未映射的 finish_reason "${raw}"` } } : {}) }
+            : {}),
+        }
+      } else {
+        for (let i = 0; i < toolCallDeltas.length; i++) {
+          const last = i === toolCallDeltas.length - 1
+          yield {
+            ...(i === 0 && text !== undefined ? { delta: text } : {}),
+            toolCallDelta: toolCallDeltas[i],
+            ...(last && finish !== undefined
+              ? { finishReason: finish, ...(finish === 'error' ? { error: { code: 'B080001', message: `未映射的 finish_reason "${raw}"` } } : {}) }
+              : {}),
+          }
+        }
+      }
+    }
+  }
+}
+
+export function createOpenAICompatAdapter(opts: OpenAICompatOptions): LlmAdapter & { id: string } {
+  const id = opts.id ?? 'openai-compat'
+  const baseUrl = opts.baseUrl.replace(/\/+$/, '')
+  if (!baseUrl.startsWith('https://')) {
+    throw new Error(`CAR-E-LLM-TLS: baseUrl 必须 https（TLS 强制，§3.2.M8.4；本地明文部署请经 TLS 代理或自建适配器）`)
+  }
+  const url = `${baseUrl}/chat/completions`
+  const fetchImpl = opts.fetchImpl ?? fetch
+  const sleep = opts.sleep ?? (ms => new Promise<void>(r => setTimeout(r, ms)))
+  const timeoutMs = opts.timeoutMs ?? 120_000
+  const firstByteMs = opts.firstByteMs ?? 30_000
+  const retries = opts.retries ?? 2
+  const backoffMs = opts.backoffMs ?? [1_000, 2_000]
+
+  const toOpenAI = (req: LlmRequest, apiKey: string) => ({
+    headers: {
+      'content-type': 'application/json',
+      authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      model: req.model,
+      stream: true,
+      ...(req.maxTokens != null ? { max_tokens: req.maxTokens } : {}),
+      messages: req.messages.map(m => {
+        if (m.role === 'toolResult') {
+          const p = m.content as { id?: string; result?: unknown; error?: string }
+          return { role: 'tool', tool_call_id: p?.id, content: p?.error ?? JSON.stringify(p?.result ?? null) }
+        }
+        if (m.role === 'assistant' && m.content != null && typeof m.content === 'object' && 'toolCall' in (m.content as object)) {
+          const tc = (m.content as { toolCall: { id: string; tool: string; args: unknown } }).toolCall
+          return {
+            role: 'assistant',
+            content: null,
+            tool_calls: [{ id: tc.id, type: 'function', function: { name: tc.tool, arguments: JSON.stringify(tc.args ?? {}) } }],
+          }
+        }
+        return { role: m.role, content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content) }
+      }),
+      // declaredSideEffect 不出站：权限面只进权限门（§3.2.M8.3 字段表约束方向）
+      ...(req.tools.length ? { tools: req.tools.map(t => ({ type: 'function', function: { name: t.name, description: t.description, parameters: t.parameters } })) } : {}),
+    }),
+  })
+
+  return {
+    id,
+    async *chat(req: LlmRequest): AsyncIterable<LlmChunk> {
+      // 凭据门：resolve → reveal（SQ-07 凭据解析；A080001 在此抛出——首块前，runTurn 可 error 收口）
+      let apiKey = ''
+      if (opts.credentials) {
+        const ref = opts.credentials.resolve(opts.provider ?? id, {})
+        apiKey = opts.credentials.reveal(ref, {})
+      }
+      const payload = toOpenAI(req, apiKey)
+
+      for (let attempt = 0; ; attempt++) {
+        const controller = new AbortController()
+        const started = Date.now()
+        let firstByteSeen = false
+        const firstByteTimer = setTimeout(() => controller.abort(), firstByteMs)
+        const overallTimer = setTimeout(() => controller.abort(), timeoutMs)
+        try {
+          const res = await fetchImpl(url, { ...payload, signal: controller.signal })
+          if (res.status === 429 || res.status >= 500) throw new Retryable(`HTTP ${res.status}`)
+          if (!res.ok) {
+            const text = await res.text().catch(() => '')
+            // 4xx 业务错不重试（§3.5.4）；错误信息不含凭据（Bearer 值不进错误路径）
+            yield { finishReason: 'error', error: { code: 'B080001', message: `provider HTTP ${res.status}${text ? `：${text.slice(0, 200)}` : ''}` } }
+            return
+          }
+          if (!res.body) throw new Retryable('响应无 body 流')
+          let sawFinish = false
+          for await (const chunk of parseSseStream(res.body)) {
+            if (!firstByteSeen) { firstByteSeen = true; clearTimeout(firstByteTimer) }
+            if (chunk.finishReason !== undefined) sawFinish = true
+            yield chunk
+          }
+          // 流自然结束但未给 finishReason = 异常终止（AL-05 口径：缺失显式化，禁吞没）；
+          // 已携带 finishReason 的流原样收口——兜底不得追加（M8-BUG-1：无条件 error chunk
+          // 会污染成功流并触发 finishReason 守卫冲突；成功流零 error chunk 由 s25 断言钉死）
+          if (!sawFinish) {
+            yield { finishReason: 'error', error: { code: 'B080001', message: '流结束未携带 finish_reason（AL-05）' } }
+          }
+          return
+        } catch (e) {
+          const beforeFirstByte = !firstByteSeen
+          clearTimeout(firstByteTimer)
+          // 首块前失败 = 网络错误/429/5xx/首字节超时（§3.5.4 重试条件全集）——未消费任何
+          // chunk，请求体可重放，重试不产生额外副作用；流中途失败不可重放（chunk 已消费）
+          if (beforeFirstByte && attempt < retries) {
+            await sleep(backoffMs[Math.min(attempt, backoffMs.length - 1)]!)
+            continue
+          }
+          if (beforeFirstByte) {
+            // 重试耗尽 → B080001（BD-04：消费方 runTurn 以 error 收口）
+            throw providerUnreachable(`${(e as Error).name}: ${(e as Error).message}（尝试 ${attempt + 1}/${retries + 1}，${Date.now() - started}ms）`)
+          }
+          // 流中途失败：已消费 chunk 不可重放 → error chunk 收口
+          yield { finishReason: 'error', error: { code: 'B080001', message: `流中途失败：${(e as Error).message}` } }
+          return
+        } finally {
+          clearTimeout(firstByteTimer)
+          clearTimeout(overallTimer)
+        }
+      }
+    },
+  }
+}