@lqc123qwe/car-runtime 1.0.0 → 1.2.0

package/test/s28-session-index-followup.spec.ts

@@ -0,0 +1,236 @@
+/**
+ * 1.2 · 会话索引后续项（S28）：--session id 经索引定位（W3-1）+ 运行时异步索引更新（W3-2）
+ *
+ * 覆盖（1.2-迭代规划 W3-1/W3-2；M7 §4/§5 登记后续出清）：
+ *  - lookupSession：命中全字段还原 / 未收录 null / 索引不存在 / 索引文件无效显式报错
+ *  - CLI 三入口 --session 全链：verify / replay / export 经索引定位；互斥、缺 db、未收录显式报错
+ *  - IndexUpdater：append → flush → 索引可见（自举建库建表）；快照覆盖；close flush；失败非致命
+ *  - 生产调用点：car run 真进程 append → sessions-index.db 自动可见（「更新半边」闭环）
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { spawn } from 'node:child_process'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { SessionLog } from '../src/session/log.ts'
+import { SessionFileStore } from '../src/session/store.ts'
+import { rebuildIndex, lookupSession, IndexUpdater } from '../src/session/indexStore.ts'
+
+const CLI = join(dirname(fileURLToPath(import.meta.url)), '..', 'src', 'cli.ts')
+
+function withTempDir(name: string, fn: (dir: string) => Promise<void> | void): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), `car-s28-${name}-`))
+  try {
+    const r = fn(dir)
+    const cleanup = () => { try { rmSync(dir, { recursive: true, force: true }) } catch { /* 红线 8 */ } }
+    if (r instanceof Promise) return r.finally(cleanup)
+    cleanup()
+    return Promise.resolve()
+  } catch (e) {
+    try { rmSync(dir, { recursive: true, force: true }) } catch { /* 红线 8 */ }
+    throw e
+  }
+}
+
+/** 写一个链完整会话文件（car run 同构：log + attachSink(fs store)），返回 sessionId */
+function makeSession(dir: string, file: string, sessionId: string, turns = 2): string {
+  const log = new SessionLog(sessionId)
+  const store = new SessionFileStore(join(dir, file))
+  log.attachSink(line => store.append(line))
+  for (let i = 0; i < turns; i++) {
+    log.append('user', 'user', `T${i}`, `question ${i}`)
+    log.append('model', 'assistant', `T${i}`, `answer ${i}`)
+  }
+  store.close()
+  return sessionId
+}
+
+function car(args: string[], opts: { cwd?: string } = {}): Promise<{ code: number; stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, ['--experimental-transform-types', CLI, ...args], { cwd: opts.cwd, stdio: ['ignore', 'pipe', 'pipe'] })
+    let out = ''
+    let err = ''
+    child.stdout.on('data', d => { out += d })
+    child.stderr.on('data', d => { err += d })
+    child.on('error', reject)
+    child.on('exit', code => resolve({ code: code ?? -1, stdout: out, stderr: err }))
+  })
+}
+
+// ==================== lookupSession（W3-1） ====================
+
+test('S28: lookupSession——命中全字段还原 / 未收录 null / 索引不存在 / 索引文件无效显式报错', async () => {
+  await withTempDir('lookup', async dir => {
+    makeSession(dir, 'session-S-lookup-a.jsonl', 'S-lookup-a')
+    makeSession(dir, 'session-S-lookup-b.jsonl', 'S-lookup-b')
+    const dbPath = join(dir, 'sessions-index.db')
+    const r = await rebuildIndex(dir, dbPath)
+    assert.equal(r.errors.length, 0)
+
+    const hit = await lookupSession(dbPath, 'S-lookup-a')
+    assert.ok(hit)
+    assert.equal(hit.sessionId, 'S-lookup-a')
+    assert.equal(hit.file, join(dir, 'session-S-lookup-a.jsonl'))
+    assert.equal(hit.eventCount, 4)
+    assert.equal(hit.tornTail, false)
+    assert.equal(hit.encoding, 'plain')
+
+    assert.equal(await lookupSession(dbPath, 'S-missing'), null, '未收录 = null（可索引 = 可验证）')
+
+    await assert.rejects(
+      () => lookupSession(join(dir, 'nope.db'), 'S-lookup-a'),
+      /CAR-E-INDEX: 会话索引不存在/,
+      'db 缺文件显式报错（lookup 不产生建文件副作用）',
+    )
+
+    const bad = join(dir, 'bad.db')
+    writeFileSync(bad, 'this is not a sqlite database')
+    await assert.rejects(() => lookupSession(bad, 'S-lookup-a'), /CAR-E-INDEX: 索引文件无效/)
+  })
+})
+
+test('S28: CLI --session 三入口——verify/replay/export 经索引定位全链（真进程）', async () => {
+  await withTempDir('cli-session-flag', async dir => {
+    const sid = makeSession(dir, 'session-S-cli-s1.jsonl', 'S-cli-s1')
+    await rebuildIndex(dir, join(dir, 'sessions-index.db'))
+
+    const v = await car(['session', 'verify', '--session', sid, '--db', 'sessions-index.db'], { cwd: dir })
+    assert.equal(v.code, 0, v.stderr)
+    assert.match(v.stdout, /哈希链完整：4 事件/)
+
+    const rp = await car(['session', 'replay', '--session', sid, '--db', 'sessions-index.db'], { cwd: dir })
+    assert.equal(rp.code, 0, rp.stderr)
+    assert.match(rp.stdout, /"role":"user"/)
+    assert.match(rp.stdout, /answer 1/)
+
+    const ex = await car(['session', 'export', '--session', sid, '--out', 'out-bundle', '--db', 'sessions-index.db'], { cwd: dir })
+    assert.equal(ex.code, 0, ex.stderr)
+    assert.match(ex.stdout, /取证包导出：4 事件/)
+    assert.ok(existsSync(join(dir, 'out-bundle', 'manifest.json')))
+  })
+})
+
+test('S28: CLI --session 显式拒绝面——与位置路径互斥 / 缺 db / 未收录 / 坏格式会话不入索引（真进程）', async () => {
+  await withTempDir('cli-session-flag-reject', async dir => {
+    const sid = makeSession(dir, 'session-S-cli-r1.jsonl', 'S-cli-r1')
+    // 与位置路径互斥
+    const both = await car(['session', 'verify', 's1.jsonl', '--session', sid, '--db', 'sessions-index.db'], { cwd: dir })
+    assert.equal(both.code, 2)
+    assert.match(both.stderr, /互斥/)
+    // 未建索引 + cwd 无 sessions-index.db → 显式报错提示 rebuild
+    const nodb = await car(['session', 'verify', '--session', sid], { cwd: dir })
+    assert.equal(nodb.code, 2)
+    assert.match(nodb.stderr, /CAR-E-INDEX: 会话索引不存在/)
+    // 建索引后查不存在的 id → 未收录显式报错
+    await rebuildIndex(dir, join(dir, 'sessions-index.db'))
+    const miss = await car(['session', 'verify', '--session', 'S-absent', '--db', 'sessions-index.db'], { cwd: dir })
+    assert.equal(miss.code, 2)
+    assert.match(miss.stderr, /未收录索引/)
+    // 坏格式会话（完整非法行）不入索引（「可索引 = 可验证」）→ --session 定位失败
+    const bf = join(dir, 'session-S-broken.jsonl')
+    makeSession(dir, 'session-S-broken.jsonl', 'S-broken')
+    writeFileSync(bf, readFileSync(bf, 'utf-8') + 'not-a-json-line\n')
+    const rb = await rebuildIndex(dir, join(dir, 'broken.db'))
+    assert.equal(rb.rows.some(r => r.sessionId === 'S-broken'), false, '坏格式文件不入索引（errors 通道）')
+    assert.equal(rb.errors.length, 1)
+    const broken = await car(['session', 'verify', '--session', 'S-broken', '--db', 'broken.db'], { cwd: dir })
+    assert.equal(broken.code, 2)
+    assert.match(broken.stderr, /未收录索引/)
+  })
+})
+
+// ==================== IndexUpdater（W3-2） ====================
+
+test('S28: IndexUpdater——append 后 flush 索引可见（自举建库建表）/ 快照覆盖 / close flush（真 sqlite）', async () => {
+  await withTempDir('updater', async dir => {
+    const dbPath = join(dir, 'sessions-index.db')
+    const log = new SessionLog('S-updater-1')
+    const store = new SessionFileStore(join(dir, 'session-S-updater-1.jsonl'))
+    const file = join(dir, 'session-S-updater-1.jsonl')
+    const updater = new IndexUpdater({ dbPath, debounceMs: 30 })
+    // 单 sink 语义（SessionLog.attachSink 覆盖式）——更新器经链式包装接入，不改日志层；
+    // sink 先于事件入内存（fail-fast），故 record 按行增量（seq/hash 自行数据）
+    log.attachSink(line => { store.append(line); updater.record('S-updater-1', line, file) })
+
+    log.append('user', 'user', 'T0', 'q0')
+    await updater.flush()
+    assert.equal(updater.stats.updates, 1)
+    let row = await lookupSession(dbPath, 'S-updater-1')
+    assert.ok(row, 'flush 后索引可见（无 rebuild 自举）')
+    assert.equal(row!.eventCount, 1)
+
+    // debounce 窗口内多次 record 合并为一次 upsert，行快照 = 最新 append 时点全量
+    log.append('model', 'assistant', 'T0', 'a0')
+    log.append('user', 'user', 'T1', 'q1')
+    await updater.flush()
+    row = await lookupSession(dbPath, 'S-updater-1')
+    assert.equal(row!.eventCount, 3)
+
+    // close flush（car run 关句柄前收口）
+    log.append('user', 'user', 'T2', 'q2')
+    await updater.close()
+    assert.equal(updater.stats.updates, 3)
+    row = await lookupSession(dbPath, 'S-updater-1')
+    assert.equal(row!.eventCount, 4)
+    assert.equal(row!.tornTail, false, '活会话按构造完整（tornTail=false 口径）')
+    assert.equal(row!.encoding, 'plain')
+    store.close()
+  })
+})
+
+test('S28: IndexUpdater 失败非致命——db 路径不可用持续留痕不抛出（append 路径零影响）', async () => {
+  await withTempDir('updater-fail', async dir => {
+    // dbPath 指向目录 → open 必败
+    const badPath = join(dir, 'a-directory')
+    mkdirSync(badPath)
+    const errors: string[] = []
+    const updater = new IndexUpdater({ dbPath: badPath, onError: e => errors.push(e.message) })
+    const log = new SessionLog('S-fail-1')
+    const store = new SessionFileStore(join(dir, 'x.jsonl'))
+    log.attachSink(line => { store.append(line); updater.record('S-fail-1', line, join(dir, 'x.jsonl')) })
+
+    // 事件照常落盘（updater 错误绝不传播到 append 路径——R-2 钉死）
+    log.append('user', 'user', 'T0', 'q')
+    await updater.flush()
+    assert.equal(updater.stats.failures, 1)
+    assert.ok(errors[0], '错误经 onError 留痕（不向调用方抛出）')
+    assert.match(errors[0]!, /CAR-E-INDEX|CAR-E-SQLITE/)
+
+    // 继续使用不抛出
+    log.append('user', 'user', 'T1', 'q')
+    await updater.close()
+    assert.equal(updater.stats.failures, 2)
+    // 落盘本体未受影响：文件行数 = 事件数
+    assert.equal(readFileSync(join(dir, 'x.jsonl'), 'utf-8').trim().split('\n').length, 2)
+    store.close()
+  })
+})
+
+test('S28: 生产调用点——car run 真进程 append → cwd sessions-index.db 自动可见（「更新半边」闭环）', async () => {
+  await withTempDir('car-run-index', async dir => {
+    // 工具名避开 demo_tool：CLI 演示脚手架硬编码注册 demo_tool，同名插件工具触发预存在的 provide
+    // 撞名边缘（登记不修——W1 重做 car run 装配面时出清）
+    writeFileSync(join(dir, 'p.ts'), `export const manifest = { name: 'p', version: '1.0.0' }\nexport default function apply(api) {\n  api.registerTool({ name: 't', run: async () => 'ok' })\n}\n`)
+    const r = await car(['run', 'p.ts'], { cwd: dir })
+    assert.equal(r.code, 0, r.stderr)
+    const dbPath = join(dir, 'sessions-index.db')
+    assert.ok(existsSync(dbPath), 'car run 运行后 cwd 索引自举在位')
+    // 经 sqlite 直查（run 会话 id 为 S-<time36> 运行期生成，全表核对）
+    const mod = await import('node:sqlite')
+    const DatabaseSync = (mod as unknown as { DatabaseSync: new (path: string) => { prepare(s: string): { all(...v: unknown[]): Record<string, unknown>[] }; close(): void } }).DatabaseSync
+    const db = new DatabaseSync(dbPath)
+    try {
+      const all = db.prepare('SELECT sessionId, eventCount, file FROM sessions').all()
+      assert.ok(all.length >= 1, 'run 会话入索引')
+      const hit = all.find(x => String(x.sessionId).startsWith('S-'))
+      assert.ok(hit, 'run 会话 id 在索引')
+      // realpath 比较（1.2-BUG-4）：macOS 子进程 cwd 为物理路径 /private/var…，父进程持逻辑路径 /var…
+      assert.equal(realpathSync(String(hit!.file)), realpathSync(join(dir, `session-${hit!.sessionId}.jsonl`)))
+      assert.ok(Number(hit!.eventCount) >= 3, '事件计数 = run 全程 append 量（装配+对话+收口）')
+    } finally {
+      db.close()
+    }
+  })
+})

package/test/s29-otel-producer.spec.ts

@@ -0,0 +1,252 @@
+/**
+ * 1.2 · OTLP exporter 生产级策略（S29）：有界重试 / 采样 / 批上限 / env 通道 / mcp-serve meter 桥
+ *
+ * 覆盖（1.2-迭代规划 W3-3；M8 §4.4 登记后续出清；D-12b 口径修订 0 重试 → 有界 ≤2）：
+ *  - 重试：429/5xx/网络错误退避重试（序列 1s/2s 可注入）→ 成功计数；耗尽 droppedExports 静默丢弃；
+ *    4xx 业务错不重试；res.ok 语义（旧实现 5xx 也计成功——本代修正为显式状态判定）
+ *  - 采样：always_on 缺省行为不变 / always_off 全采出 / ratio 概率边界；spansSampledOut 计数
+ *  - 批上限：maxBatchSize 分批（tracesExported 按请求计）/ maxQueueSize 溢出丢最旧 queueOverflows
+ *  - env 通道：telemetryConfigFromEnv（endpoint 唯一开关 / sampling 三形态 / 非法值保持缺省）
+ *  - 生产调用点：mcp-serve 真进程 CAR_OTEL_ENDPOINT → 本地 http 捕获端点断言 OTLP metrics 出站
+ *    （S17 counters 双写桥；快照面不变）；零依赖静态断言保持（telemetry 零 session import）
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { spawn } from 'node:child_process'
+import { createServer, type Server } from 'node:http'
+import { mkdtempSync, rmSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createTelemetryFacade, telemetryConfigFromEnv, type TelemetryConfig } from '../src/runtime-core/telemetry.ts'
+
+const CLI = join(dirname(fileURLToPath(import.meta.url)), '..', 'src', 'cli.ts')
+
+const sleepsOf = (log: number[]) => async (ms: number) => { log.push(ms) }
+const okRes = () => ({ ok: true, status: 200 }) as unknown as Response
+const statusRes = (status: number) => ({ ok: false, status }) as unknown as Response
+
+function withTempDir(name: string, fn: (dir: string) => Promise<void> | void): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), `car-s29-${name}-`))
+  try {
+    const r = fn(dir)
+    const cleanup = () => { try { rmSync(dir, { recursive: true, force: true }) } catch { /* 红线 8 */ } }
+    if (r instanceof Promise) return r.finally(cleanup)
+    cleanup()
+    return Promise.resolve()
+  } catch (e) {
+    try { rmSync(dir, { recursive: true, force: true }) } catch { /* 红线 8 */ }
+    throw e
+  }
+}
+
+// ==================== env 通道 ====================
+
+test('S29: telemetryConfigFromEnv——endpoint 唯一开关 / sampling 三形态 / 非法值保持缺省 / interval 解析', () => {
+  assert.equal(telemetryConfigFromEnv({}), null, '无 endpoint = null（默认关）')
+  const c1 = telemetryConfigFromEnv({ CAR_OTEL_ENDPOINT: 'https://otel.internal' })!
+  assert.equal(c1.endpoint, 'https://otel.internal')
+  assert.equal(c1.sampling, undefined, '缺省采样不写入（= always_on 行为）')
+  assert.equal(telemetryConfigFromEnv({ CAR_OTEL_ENDPOINT: 'https://x', CAR_OTEL_SAMPLING: 'always_off' })!.sampling, 'always_off')
+  assert.deepEqual(telemetryConfigFromEnv({ CAR_OTEL_ENDPOINT: 'https://x', CAR_OTEL_SAMPLING: '0.25' })!.sampling, { ratio: 0.25 })
+  assert.equal(telemetryConfigFromEnv({ CAR_OTEL_ENDPOINT: 'https://x', CAR_OTEL_SAMPLING: 'bogus' })!.sampling, undefined, '非法值保持缺省（禁 fail-hard）')
+  assert.equal(telemetryConfigFromEnv({ CAR_OTEL_ENDPOINT: 'https://x', CAR_OTEL_SAMPLING: '1.5' })!.sampling, undefined, '超界 ratio = 非法')
+  const c2 = telemetryConfigFromEnv({ CAR_OTEL_ENDPOINT: 'https://x', CAR_OTEL_INTERVAL_MS: '5000', CAR_OTEL_SERVICE_NAME: 'svc' })!
+  assert.equal(c2.intervalMs, 5000)
+  assert.equal(c2.serviceName, 'svc')
+})
+
+// ==================== 有界重试（D-12b 口径） ====================
+
+test('S29: 重试——5xx 退避后成功计数；耗尽 droppedExports 静默丢弃；4xx 不重试直接丢', async () => {
+  await withTempDir('retry', async () => {
+    const sleeps: number[] = []
+    // 500 → 500 → 200：两次退避后成功
+    let calls = 0
+    const f1 = createTelemetryFacade({ endpoint: 'https://otel', retryBackoffMs: [10, 20], sleep: sleepsOf(sleeps) }, {
+      fetchImpl: (async () => (calls++ === 2 ? okRes() : statusRes(500))) as typeof fetch,
+    })
+    f1.getTracer().startSpan('s').end()
+    await f1.flush()
+    assert.deepEqual(sleeps, [10, 20], '退避序列可注入且按序生效')
+    assert.deepEqual(f1.stats(), { spansEnded: 1, spansSampledOut: 0, tracesExported: 1, metricsExported: 0, droppedExports: 0, queueOverflows: 0 })
+
+    // 恒 429：耗尽 2 次重试（3 次尝试）→ 静默丢弃，flush 不抛错
+    let tries = 0
+    const f2 = createTelemetryFacade({ endpoint: 'https://otel', retryLimit: 2, retryBackoffMs: [1, 1], sleep: sleepsOf([]) }, {
+      fetchImpl: (async () => (tries++, statusRes(429))) as typeof fetch,
+    })
+    f2.getTracer().startSpan('s').end()
+    await f2.flush()
+    assert.equal(tries, 3, '1 原始 + 2 重试')
+    assert.equal(f2.stats().droppedExports, 1)
+    assert.equal(f2.stats().tracesExported, 0)
+
+    // 400 业务错：不重试，立即丢弃
+    let tries4xx = 0
+    const f3 = createTelemetryFacade({ endpoint: 'https://otel', sleep: sleepsOf([]) }, {
+      fetchImpl: (async () => (tries4xx++, statusRes(400))) as typeof fetch,
+    })
+    f3.getTracer().startSpan('s').end()
+    await f3.flush()
+    assert.equal(tries4xx, 1, '4xx 不重试')
+    assert.equal(f3.stats().droppedExports, 1)
+
+    // 网络错误（fetch throw）：可重试，耗尽后静默
+    let netTries = 0
+    const f4 = createTelemetryFacade({ endpoint: 'https://otel', retryLimit: 1, retryBackoffMs: [1], sleep: sleepsOf([]) }, {
+      fetchImpl: (async () => (netTries++, Promise.reject(new Error('ECONNREFUSED')))) as unknown as typeof fetch,
+    })
+    f4.getTracer().startSpan('s').end()
+    await f4.flush()
+    assert.equal(netTries, 2)
+    assert.equal(f4.stats().droppedExports, 1)
+  })
+})
+
+test('S29: res.ok 显式语义——5xx 不再被计为成功（旧实现口径修正的回归钉）', async () => {
+  await withTempDir('ok-semantics', async () => {
+    const f = createTelemetryFacade({ endpoint: 'https://otel', retryLimit: 0, sleep: sleepsOf([]) }, {
+      fetchImpl: (async () => statusRes(503)) as typeof fetch,
+    })
+    f.getTracer().startSpan('s').end()
+    await f.flush()
+    assert.equal(f.stats().tracesExported, 0, '非 2xx 不计成功')
+    assert.equal(f.stats().droppedExports, 1)
+  })
+})
+
+// ==================== 采样 ====================
+
+test('S29: 采样——always_on 缺省全量（1.1 行为不变）/ always_off 全采出 / ratio=0 与 1 边界', async () => {
+  await withTempDir('sampling', async () => {
+    const posts: unknown[] = []
+    const mk = (cfg: TelemetryConfig) => createTelemetryFacade({ endpoint: 'https://otel', ...cfg }, {
+      fetchImpl: (async (_url: string | URL, init?: RequestInit) => { posts.push(init?.body); return okRes() }) as typeof fetch,
+    })
+    // always_on（缺省不写 sampling）：全量出站
+    const f1 = mk({})
+    for (let i = 0; i < 3; i++) f1.getTracer().startSpan(`s${i}`).end()
+    await f1.flush()
+    assert.equal(f1.stats().spansSampledOut, 0)
+    assert.equal(f1.stats().tracesExported, 1)
+    // always_off：全采出，零出站
+    const f2 = mk({ sampling: 'always_off' })
+    for (let i = 0; i < 3; i++) f2.getTracer().startSpan(`s${i}`).end()
+    await f2.flush()
+    assert.equal(f2.stats().spansSampledOut, 3)
+    assert.equal(f2.stats().tracesExported, 0)
+    // ratio 0 / 1 边界
+    const f3 = mk({ sampling: { ratio: 0 } })
+    f3.getTracer().startSpan('s').end()
+    assert.equal(f3.stats().spansSampledOut, 1)
+    const f4 = mk({ sampling: { ratio: 1 } })
+    f4.getTracer().startSpan('s').end()
+    assert.equal(f4.stats().spansSampledOut, 0)
+  })
+})
+
+// ==================== 批上限 ====================
+
+test('S29: 批上限——maxBatchSize 分批（tracesExported 按请求计）/ maxQueueSize 溢出丢最旧', async () => {
+  await withTempDir('batch', async () => {
+    const bodies: any[] = []
+    const f = createTelemetryFacade({ endpoint: 'https://otel', maxBatchSize: 2, maxQueueSize: 5 }, {
+      fetchImpl: (async (_u: string | URL, init?: RequestInit) => { bodies.push(JSON.parse(String(init?.body))); return okRes() }) as typeof fetch,
+    })
+    for (let i = 0; i < 5; i++) f.getTracer().startSpan(`s${i}`).end()
+    await f.flush()
+    assert.equal(bodies.length, 3, '5 spans / batch=2 → 3 请求')
+    assert.deepEqual(bodies.map(b => b.scopeSpans[0].spans.length), [2, 2, 1])
+    assert.equal(f.stats().tracesExported, 3, 'tracesExported 按成功出站请求计数')
+
+    // 溢出丢最旧：queue=3，end 5 个 → 丢最旧 2 个，flush 导出最新 3 个
+    const f2 = createTelemetryFacade({ endpoint: 'https://otel', maxQueueSize: 3 }, {
+      fetchImpl: (async (_u: string | URL, init?: RequestInit) => { bodies.push(JSON.parse(String(init?.body))); return okRes() }) as typeof fetch,
+    })
+    for (let i = 0; i < 5; i++) f2.getTracer().startSpan(`s${i}`).end()
+    assert.equal(f2.stats().queueOverflows, 2)
+    await f2.flush()
+    const names = bodies[bodies.length - 1]!.scopeSpans[0].spans.map((s: { name: string }) => s.name)
+    assert.deepEqual(names, ['s2', 's3', 's4'], '溢出丢最旧（保留最新）')
+  })
+})
+
+// ==================== 默认关（noop）不变 ====================
+
+test('S29: 默认关三原则——无 endpoint = noop 零出站（fetch 不被调用）+ stats 全零', async () => {
+  await withTempDir('default-off', async () => {
+    let called = 0
+    const f = createTelemetryFacade(null, { fetchImpl: (async () => (called++, okRes())) as typeof fetch })
+    assert.equal(f.enabled, false)
+    f.getTracer().startSpan('s').end()
+    f.getMeter().createCounter('c').add(1)
+    await f.flush()
+    await f.shutdown()
+    assert.equal(called, 0, '零出站')
+    assert.deepEqual(f.stats(), { spansEnded: 0, spansSampledOut: 0, tracesExported: 0, metricsExported: 0, droppedExports: 0, queueOverflows: 0 })
+  })
+})
+
+// ==================== 零依赖解耦红线（静态断言保持） ====================
+
+test('S29: 严格解耦——telemetry.ts 零 import 自 session/*（静态断言）', () => {
+  const src = readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'src', 'runtime-core', 'telemetry.ts'), 'utf-8')
+  assert.equal(/from\s+'\.\.\/session\//.test(src), false)
+  assert.equal(/from\s+'\.\/\.\.\/session\//.test(src), false)
+})
+
+// ==================== 生产调用点：mcp-serve meter 桥（真进程 + 本地捕获端点） ====================
+
+test('S29: mcp-serve 生产接线——CAR_OTEL_ENDPOINT 显式开 → S17 counters 双写出站 OTLP metrics（快照面不变）', async () => {
+  await withTempDir('mcp-otel', async dir => {
+    const bodies: any[] = []
+    let done: (v: void) => void = () => {}
+    const closed = new Promise<void>(r => { done = r })
+    const server: Server = createServer((req, res) => {
+      let body = ''
+      req.on('data', c => { body += c })
+      req.on('end', () => {
+        if (req.url === '/v1/metrics') bodies.push(JSON.parse(body))
+        res.writeHead(200).end()
+      })
+    })
+    await new Promise<void>(r => server.listen(0, '127.0.0.1', r))
+    const port = (server.address() as { port: number }).port
+    try {
+      const child = spawn(process.execPath, ['--experimental-transform-types', CLI, 'mcp-serve'], {
+        cwd: dir,
+        env: { ...process.env, CAR_OTEL_ENDPOINT: `http://127.0.0.1:${port}`, CAR_OTEL_INTERVAL_MS: '0' },
+        stdio: ['pipe', 'pipe', 'pipe'],
+      })
+      let err = ''
+      child.stderr.on('data', d => { err += d })
+      child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'session_start', arguments: { hostSessionId: 's29' } } }) + '\n')
+      child.stdin.end()
+      child.on('exit', () => done())
+      // macOS runner 慢启动容差（60s）；落选的 race timer 必须 clear——未清时它把事件循环
+      // 挂满整个超时窗（本文件曾因此空转 20s，慢 runner 上叠加成 j03 假失败形态）
+      let raceTimer: ReturnType<typeof setTimeout> | undefined
+      try {
+        await Promise.race([
+          closed,
+          new Promise<never>((_, rej) => { raceTimer = setTimeout(() => rej(new Error(`mcp-serve 超时\n${err}`)), 60_000) }),
+        ])
+      } finally {
+        if (raceTimer) clearTimeout(raceTimer)
+      }
+      // S17 快照面不变（双写非迁移）
+      assert.match(err, /snapshot=/)
+      assert.match(err, /zeroContent=true/)
+      assert.match(err, /otel=enabled/)
+      // OTLP metrics 出站：counter 名 + 零内容 labels 到达用户端点
+      assert.ok(bodies.length >= 1, 'metrics POST 到达捕获端点')
+      const names = bodies.flatMap(b => b.scopeMetrics[0].metrics.map((m: { name: string }) => m.name))
+      assert.ok(names.includes('car_registry_decision'), 'S17 counter 名出站')
+      assert.equal(/sk-|ghp_/.test(JSON.stringify(bodies)), false, '出站体无凭据形态（零内容口径）')
+    } finally {
+      server.closeAllConnections()
+      server.close()
+    }
+  })
+})