@lqc123qwe/car-runtime 1.1.0 → 1.3.0

package/src/runtime-core/telemetry.ts

@@ -4,8 +4,17 @@
  * 口径（§3.2.M8.5 关键约束，逐条落地）：
  *  - 默认关：无端点配置时不初始化任何 exporter——无配置 = noop 句柄 + 零出站（可机器断言）；
  *  - 显式开：用户配置端点即视为开启（CAR_OTEL_ENDPOINT 或显式 config 传入）；
- *  - 端点归用户：数据只发往用户自配 E-05；OTLP/HTTP JSON（fetch），导出超时 5s、0 重试、
- *    端点不可达静默丢弃（BD-05——不抛错、不重试、不落审计）；
+ *  - 端点归用户：数据只发往用户自配 E-05；OTLP/HTTP JSON（fetch），导出超时 5s；
+ *    1.2-S3 生产级策略（D-12b 口径修订，2026-09-27）：**0 重试 → 有界重试 ≤2**（仅 429/5xx/
+ *    网络错误，退避 1s/2s；4xx 业务错不重试）——重试耗尽静默丢弃 + droppedExports 计数，
+ *    永不抛错（BD-05「不抛错、不落审计」收紧保持）；隐私三原则不变（数据仍只发用户自配端点）；
+ *  - 采样（1.2-S3 加法）：head 采样于 span.end() 决策——always_on（缺省，全量，1.1 行为不变）/
+ *    always_off / { ratio }（概率）；被采出计入 spansSampledOut；采样只减少出站数据（隐私正向）；
+ *  - 批处理上限（1.2-S3 加法）：maxBatchSize 单请求分批（512）+ maxQueueSize buffer 上限
+ *    （2048，溢出丢最旧 + queueOverflows 计数）——内存有界；
+ *  - env 通道（1.2-S3 加法）：telemetryConfigFromEnv——CAR_OTEL_ENDPOINT（唯一开关）/
+ *    CAR_OTEL_SAMPLING（always_on|always_off|0..1，非法值保持缺省——遥测面禁 fail-hard）/
+ *    CAR_OTEL_INTERVAL_MS / CAR_OTEL_SERVICE_NAME；
  *  - 严格解耦：本文件零 import 自 session/*（遥测与审计日志禁止混流）——测试做静态断言；
  *  - S17 零内容计数器（telemetry/metrics.ts）是登记表兜底通道，与本门面并存互补：
  *    本面是 OTel 形态的出站通道，不承接 S17 的零内容红线语义（内容治理属调用方）；
@@ -14,6 +23,8 @@
  */
 import { randomBytes } from 'node:crypto'
 
+export type SamplingSpec = 'always_on' | 'always_off' | { ratio: number }
+
 export interface TelemetryConfig {
   /** 用户自配 OTLP/HTTP 端点（如 https://otel.example.internal）——无值 = 默认关 */
   endpoint?: string
@@ -23,6 +34,19 @@ export interface TelemetryConfig {
   exportTimeoutMs?: number
   /** 自动导出间隔 ms；0（缺省）= 仅手动 flush（测试/收口时点调用） */
   intervalMs?: number
+  // —— 1.2-S3 生产级策略（加法；缺省值保持 1.1 行为）——
+  /** 有界重试上限（仅 429/5xx/网络错误；§3.5.4 基线 ≤2；D-12b 口径修订） */
+  retryLimit?: number
+  /** 重试退避序列 ms（缺省 [1000, 2000]；测试可注入） */
+  retryBackoffMs?: number[]
+  /** 采样（缺省 always_on = 全量）；head 决策于 span.end() */
+  sampling?: SamplingSpec
+  /** 单请求 spans 上限（超限分批；缺省 512） */
+  maxBatchSize?: number
+  /** span buffer 上限（溢出丢最旧 + queueOverflows 计数；缺省 2048） */
+  maxQueueSize?: number
+  /** 测试注入睡眠（退避可观测；缺省真实定时器） */
+  sleep?: (ms: number) => Promise<void>
 }
 
 export interface TelemetrySpan {
@@ -47,9 +71,14 @@ export interface TelemetryMeter {
 
 export interface TelemetryStats {
   spansEnded: number
+  /** 1.2-S3 加法：head 采样被采出的 span 数（缺省 always_on 下恒 0） */
+  spansSampledOut: number
+  /** 成功出站的 OTLP 请求计数（traces/metrics 分批后按请求计） */
   tracesExported: number
   metricsExported: number
   droppedExports: number
+  /** 1.2-S3 加法：buffer 溢出丢最旧计数（maxQueueSize 上限） */
+  queueOverflows: number
 }
 
 export interface TelemetryFacade {
@@ -76,6 +105,33 @@ const noopSpan = (): TelemetrySpan => ({
 })
 const NOOP_TRACER: TelemetryTracer = { startSpan: () => noopSpan() }
 const NOOP_METER: TelemetryMeter = { createCounter: () => ({ add() {} }) }
+const NOOP_STATS: TelemetryStats = { spansEnded: 0, spansSampledOut: 0, tracesExported: 0, metricsExported: 0, droppedExports: 0, queueOverflows: 0 }
+
+/**
+ * 1.2-S3 env 配置通道：CAR_OTEL_ENDPOINT（唯一开关）/ CAR_OTEL_SAMPLING（always_on|always_off|0..1，
+ * 非法值保持缺省 always_on——遥测面禁 fail-hard）/ CAR_OTEL_INTERVAL_MS / CAR_OTEL_SERVICE_NAME。
+ * 无 endpoint = null（默认关，noop 门面）。
+ */
+export function telemetryConfigFromEnv(env: NodeJS.ProcessEnv = process.env): TelemetryConfig | null {
+  const endpoint = env.CAR_OTEL_ENDPOINT
+  if (!endpoint) return null
+  const cfg: TelemetryConfig = { endpoint }
+  if (env.CAR_OTEL_SERVICE_NAME) cfg.serviceName = env.CAR_OTEL_SERVICE_NAME
+  if (env.CAR_OTEL_INTERVAL_MS) {
+    const n = Number(env.CAR_OTEL_INTERVAL_MS)
+    if (Number.isFinite(n) && n >= 0) cfg.intervalMs = n
+  }
+  if (env.CAR_OTEL_SAMPLING) {
+    const s = env.CAR_OTEL_SAMPLING
+    if (s === 'always_on' || s === 'always_off') cfg.sampling = s
+    else {
+      const r = Number(s)
+      if (Number.isFinite(r) && r >= 0 && r <= 1) cfg.sampling = { ratio: r }
+      // 非法采样值：保持缺省 always_on（登记口径，禁 fail-hard）
+    }
+  }
+  return cfg
+}
 
 // ==================== 活动门面（显式开路径） ====================
 
@@ -104,36 +160,61 @@ export function createTelemetryFacade(
       getMeter: () => NOOP_METER,
       flush: async () => {},
       shutdown: async () => {},
-      stats: () => ({ spansEnded: 0, tracesExported: 0, metricsExported: 0, droppedExports: 0 }),
+      stats: () => ({ ...NOOP_STATS }),
     }
   }
 
   const fetchImpl = opts.fetchImpl ?? fetch
   const now = opts.now ?? Date.now
+  const sleep = config?.sleep ?? (ms => new Promise<void>(r => setTimeout(r, ms)))
   const timeoutMs = config?.exportTimeoutMs ?? 5_000
+  const retryLimit = config?.retryLimit ?? 2
+  const backoff = config?.retryBackoffMs ?? [1_000, 2_000]
+  const sampling = config?.sampling ?? 'always_on'
+  const maxBatchSize = config?.maxBatchSize ?? 512
+  const maxQueueSize = config?.maxQueueSize ?? 2_048
   const baseHeaders = { 'content-type': 'application/json', ...(config?.headers ?? {}) }
   const serviceName = config?.serviceName ?? 'car-runtime'
 
   const spans: SpanRecord[] = []
-  const counters = new Map<string, { labels: Record<string, string>; value: number }>()
-  const stats: TelemetryStats = { spansEnded: 0, tracesExported: 0, metricsExported: 0, droppedExports: 0 }
+  // 计数器键 = name+labels JSON（聚合去重）；记录体分离保存 name/labels——
+  // OTLP metric 名必须是纯 name（1.2-BUG-3：键直当名会把 labels JSON 拼进 metric 名，
+  // M8 最小实现即存在，meter 零生产调用点掩盖至今，1.2-S3 meter 桥接入时暴露）
+  const counters = new Map<string, { name: string; labels: Record<string, string>; value: number }>()
+  const stats: TelemetryStats = { spansEnded: 0, spansSampledOut: 0, tracesExported: 0, metricsExported: 0, droppedExports: 0, queueOverflows: 0 }
   let tracer: TelemetryTracer | null = null
   let meter: TelemetryMeter | null = null
   let timer: ReturnType<typeof setInterval> | null = null
   let flushing = false
 
+  /**
+   * OTLP 出站（D-12b 口径：有界重试）——ok / 429/5xx/网络错误退避重试 ≤retryLimit /
+   * 4xx 业务错不重试（端点配置类问题，重试无益）；重试耗尽返回 false 由调用方计入
+   * droppedExports（静默丢弃，永不抛错——BD-05「不抛错」收紧保持）。
+   */
   const exportOtlp = async (path: string, body: unknown): Promise<boolean> => {
-    try {
-      // 单次尝试 + 有界超时（§3.5.4：OTel 导出 5s / 0 重试）；失败静默丢弃（BD-05）
-      await fetchImpl(endpoint + path, {
-        method: 'POST',
-        headers: baseHeaders,
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(timeoutMs),
-      })
-      return true
-    } catch {
-      return false
+    for (let attempt = 0; ; attempt++) {
+      try {
+        const res = await fetchImpl(endpoint + path, {
+          method: 'POST',
+          headers: baseHeaders,
+          body: JSON.stringify(body),
+          signal: AbortSignal.timeout(timeoutMs),
+        })
+        if (res.ok) return true
+        if ((res.status === 429 || res.status >= 500) && attempt < retryLimit) {
+          await sleep(backoff[Math.min(attempt, backoff.length - 1)]!)
+          continue
+        }
+        return false
+      } catch {
+        // 网络错误/超时：可重试类
+        if (attempt < retryLimit) {
+          await sleep(backoff[Math.min(attempt, backoff.length - 1)]!)
+          continue
+        }
+        return false
+      }
     }
   }
 
@@ -141,13 +222,15 @@ export function createTelemetryFacade(
     if (flushing) return
     flushing = true
     try {
-      const spanBatch = spans.splice(0, spans.length)
-      if (spanBatch.length) {
+      const spanQueue = spans.splice(0, spans.length)
+      // maxBatchSize 分批（1.2-S3）：tracesExported 按成功出站请求计数
+      for (let i = 0; i < spanQueue.length; i += maxBatchSize) {
+        const batch = spanQueue.slice(i, i + maxBatchSize)
         const body = {
           resource: { attributes: [{ key: 'service.name', value: { stringValue: serviceName } }] },
           scopeSpans: [{
             scope: { name: 'car-runtime' },
-            spans: spanBatch.map(s => ({
+            spans: batch.map(s => ({
               traceId: s.traceId,
               spanId: s.spanId,
               ...(s.parentSpanId ? { parentSpanId: s.parentSpanId } : {}),
@@ -170,8 +253,8 @@ export function createTelemetryFacade(
           resource: { attributes: [{ key: 'service.name', value: { stringValue: serviceName } }] },
           scopeMetrics: [{
             scope: { name: 'car-runtime' },
-            metrics: batch.map(([name, c]) => ({
-              name,
+            metrics: batch.map(([, c]) => ({
+              name: c.name,
               sum: {
                 aggregationTemporality: 'AGGREGATION_TEMPORALITY_CUMULATIVE',
                 dataPoints: Object.entries(c.labels).length
@@ -209,8 +292,15 @@ export function createTelemetryFacade(
         recordException(err) { record.attributes['exception.message'] = String((err as Error)?.message ?? err); return this },
         end() {
           record.endMs = now()
-          spans.push(record)
           stats.spansEnded++
+          // head 采样于 end() 决策（1.2-S3）：缺省 always_on 全量（1.1 行为不变）；采样只减少出站
+          const keep = sampling === 'always_on' ? true
+            : sampling === 'always_off' ? false
+            : Math.random() < sampling.ratio
+          if (!keep) { stats.spansSampledOut++; return }
+          // buffer 上限：溢出丢最旧 + 计数（内存有界）
+          if (spans.length >= maxQueueSize) { spans.shift(); stats.queueOverflows++ }
+          spans.push(record)
         },
       }
     },
@@ -221,7 +311,7 @@ export function createTelemetryFacade(
       return {
         add(value, labels = {}) {
           const key = name + JSON.stringify(labels)
-          const cur = counters.get(key) ?? { labels, value: 0 }
+          const cur = counters.get(key) ?? { name, labels, value: 0 }
           cur.value += value
           counters.set(key, cur)
         },

package/src/session/indexStore.ts

@@ -8,8 +8,8 @@
  *    索引只收录链完整会话（审计面口径：可索引 = 可验证）；
  *  - 物理编码 layout-blind：plain / zstd 统一经 format.ts 装载，索引记录 encoding 供检索。
  */
-import { readdirSync } from 'node:fs'
-import { join } from 'node:path'
+import { readdirSync, existsSync, realpathSync } from 'node:fs'
+import { join, resolve } from 'node:path'
 import { loadSessionLog, type SessionEvent } from './log.ts'
 
 export interface SessionIndexRow {
@@ -31,14 +31,189 @@ export interface RebuildResult {
 }
 
 type SqliteValue = string | number | null
-interface SqliteStmt { run(...v: SqliteValue[]): unknown }
+interface SqliteStmt { run(...v: SqliteValue[]): unknown; get(...v: SqliteValue[]): unknown }
 interface SqliteDb { exec(sql: string): void; prepare(sql: string): SqliteStmt; close(): void }
 
+const CAR_E_SQLITE = 'CAR-E-SQLITE: 当前 Node 无 node:sqlite 能力（22.5+ 需 --experimental-sqlite，23.4+ 原生）——显式拒绝，不静默降级'
+
 /** node:sqlite 能力探测（模块存在性；静态 import 在无能力 Node 上会崩模块加载，故动态） */
 export async function sqliteAvailable(): Promise<boolean> {
   try { await import('node:sqlite'); return true } catch { return false }
 }
 
+/** 打开索引库（db 文件必须已存在——lookup 不产生建文件副作用；open 失败 = 索引文件无效显式报错） */
+async function openExistingDb(dbPath: string): Promise<SqliteDb> {
+  if (!existsSync(dbPath)) {
+    throw new Error(`CAR-E-INDEX: 会话索引不存在：${dbPath}——先执行 car session rebuild-index 建立索引`)
+  }
+  const mod = await import('node:sqlite').catch(() => null)
+  if (!mod) throw new Error(CAR_E_SQLITE)
+  const DatabaseSync = (mod as unknown as { DatabaseSync: new (path: string) => SqliteDb }).DatabaseSync
+  try {
+    return new DatabaseSync(dbPath)
+  } catch (e) {
+    throw new Error(`CAR-E-INDEX: 索引文件无效（打开失败：${(e as Error).message}）：${dbPath}`)
+  }
+}
+
+/** 单会话检索（1.2-S1 W3-1）：--session <id> 经索引解析 sessionId → 文件；未收录 = null（「可索引 = 可验证」口径——断链会话不入索引） */
+export async function lookupSession(dbPath: string, sessionId: string): Promise<SessionIndexRow | null> {
+  const db = await openExistingDb(dbPath)
+  try {
+    const table = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='sessions'").get()
+    if (!table) throw new Error(`CAR-E-INDEX: 索引文件无效（无 sessions 表）：${dbPath}`)
+    const row = db.prepare('SELECT * FROM sessions WHERE sessionId = ?').get(sessionId) as Record<string, SqliteValue> | undefined
+    if (!row) return null
+    return {
+      sessionId: String(row.sessionId),
+      file: String(row.file),
+      eventCount: Number(row.eventCount),
+      chainHead: row.chainHead == null ? null : String(row.chainHead),
+      chainTail: row.chainTail == null ? null : String(row.chainTail),
+      firstTs: row.firstTs == null ? null : Number(row.firstTs),
+      lastTs: row.lastTs == null ? null : Number(row.lastTs),
+      tornTail: Number(row.tornTail) === 1,
+      encoding: row.encoding === 'zstd' ? 'zstd' : 'plain',
+    }
+  } catch (e) {
+    const msg = (e as Error).message
+    if (msg.startsWith('CAR-E-')) throw e // 本层显式错误原样透传
+    // SQLite 惰性校验：非索引文件 open 不报错、query 才报（file is not a database）——统一收口为显式口径
+    throw new Error(`CAR-E-INDEX: 索引文件无效（${msg}）：${dbPath}`)
+  } finally {
+    db.close()
+  }
+}
+
+const CREATE_SESSIONS_SQL = `CREATE TABLE IF NOT EXISTS sessions (
+  sessionId TEXT PRIMARY KEY,
+  file TEXT NOT NULL,
+  eventCount INTEGER NOT NULL,
+  chainHead TEXT,
+  chainTail TEXT,
+  firstTs INTEGER,
+  lastTs INTEGER,
+  tornTail INTEGER NOT NULL DEFAULT 0,
+  encoding TEXT NOT NULL DEFAULT 'plain',
+  rebuiltAt TEXT NOT NULL
+)`
+
+/** 单行增量 upsert（1.2-S2 W3-2「更新半边」）：库/表不存在则自举创建（活会话无需先 rebuild 即可入索引） */
+export async function upsertSessionRow(dbPath: string, row: SessionIndexRow): Promise<void> {
+  const mod = await import('node:sqlite').catch(() => null)
+  if (!mod) throw new Error(CAR_E_SQLITE)
+  const DatabaseSync = (mod as unknown as { DatabaseSync: new (path: string) => SqliteDb }).DatabaseSync
+  try {
+    const db = new DatabaseSync(dbPath)
+    try {
+      db.exec(CREATE_SESSIONS_SQL)
+      db.prepare(
+        'INSERT OR REPLACE INTO sessions (sessionId, file, eventCount, chainHead, chainTail, firstTs, lastTs, tornTail, encoding, rebuiltAt) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
+      ).run(row.sessionId, row.file, row.eventCount, row.chainHead, row.chainTail, row.firstTs, row.lastTs, row.tornTail ? 1 : 0, row.encoding, new Date().toISOString())
+    } finally {
+      db.close()
+    }
+  } catch (e) {
+    const msg = (e as Error).message
+    if (msg.startsWith('CAR-E-')) throw e
+    throw new Error(`CAR-E-INDEX: 索引更新失败（${msg}）：${dbPath}`)
+  }
+}
+
+/**
+ * 运行时索引更新器（1.2-S2 W3-2）：file-backed 会话 append 后的异步增量通道。
+ *
+ * 口径（M7 §4.2 登记 + 1.2 规划 R-2）：
+ *  - 按行增量：SessionLog.append 的 sink 先于事件入内存调用（fail-fast 语义），故 record
+ *    直接收行 JSON——seq/ts/hash 取自行数据（seq 权威：eventCount = seq+1），不读内存快照；
+ *  - debounce 合并：窗口内多次 append 只落一次 upsert（行状态由最新 append 覆盖）；
+ *  - 失败非致命：upsert 任何错误经 onError 留痕并计数，绝不向 append 路径传播——
+ *    索引是派生缓存，丢失由 rebuild-index 兜底（语义自洽，M7 已登记）；
+ *  - SQLite 能力缺席：首次 flush 显式登记一次后停用（非静默，后续 record 不再调度）；
+ *  - 活会话行口径：tornTail=false（按构造完整）、encoding='plain'（zstd 定位归档/导出，M7 W3）。
+ */
+interface PendingState {
+  sessionId: string
+  file: string
+  eventCount: number
+  chainHead: string
+  chainTail: string
+  firstTs: number
+  lastTs: number
+}
+
+export class IndexUpdater {
+  readonly #dbPath: string
+  readonly #debounceMs: number
+  readonly #onError: (e: Error) => void
+  #state: PendingState | null = null
+  #timer: ReturnType<typeof setTimeout> | null = null
+  #capabilityMissing = false
+  #updates = 0
+  #failures = 0
+
+  constructor(opts: { dbPath: string; debounceMs?: number; onError?: (e: Error) => void }) {
+    this.#dbPath = opts.dbPath
+    this.#debounceMs = opts.debounceMs ?? 2_000
+    this.#onError = opts.onError ?? (e => { try { console.error(`[index-updater] ${e.message}`) } catch { /* 收口期 stderr 不可用 */ } })
+  }
+
+  get stats(): { updates: number; failures: number } {
+    return { updates: this.#updates, failures: this.#failures }
+  }
+
+  /** append sink 链上调用（行 JSON）：seq 权威增量；非预期行防御性忽略 */
+  record(sessionId: string, line: string, file: string): void {
+    if (this.#capabilityMissing) return
+    let e: { seq?: unknown; ts?: unknown; hash?: unknown }
+    try { e = JSON.parse(line) as { seq?: unknown; ts?: unknown; hash?: unknown } } catch { return }
+    const seq = Number(e.seq)
+    const ts = Number(e.ts)
+    const hash = typeof e.hash === 'string' ? e.hash : ''
+    if (!Number.isFinite(seq) || !Number.isFinite(ts) || !hash) return
+    // realpath 规范化（1.2-BUG-4）：macOS tmpdir 为 symlink（/var → /private/var），子进程 cwd 由
+    // OS 返回物理路径——resolve() 不解析符号链接，父子进程会产出同一文件的两个别名形态；
+    // 入库统一为 realpath（文件刚被 append 过必存在；异常回退 resolve）
+    const canonical = (() => {
+      try { return realpathSync(file) } catch { return resolve(file) }
+    })()
+    const s = this.#state
+    if (!s || s.sessionId !== sessionId || s.file !== canonical) {
+      this.#state = { sessionId, file: canonical, eventCount: seq + 1, chainHead: hash, chainTail: hash, firstTs: ts, lastTs: ts }
+    } else {
+      s.eventCount = Math.max(s.eventCount, seq + 1)
+      s.chainTail = hash
+      s.lastTs = ts
+    }
+    this.#timer ??= setTimeout(() => { void this.flush() }, this.#debounceMs)
+  }
+
+  /** 立即落 pending（close/exit 时点调用；幂等——无 pending 即空转） */
+  async flush(): Promise<void> {
+    if (this.#timer) { clearTimeout(this.#timer); this.#timer = null }
+    if (!this.#state) return
+    const s = this.#state
+    const row: SessionIndexRow = { ...s, tornTail: false, encoding: 'plain' }
+    try {
+      await upsertSessionRow(this.#dbPath, row)
+      this.#updates++
+    } catch (e) {
+      this.#failures++
+      const msg = (e as Error).message
+      if (msg.startsWith('CAR-E-SQLITE')) {
+        // 能力缺席：登记一次后停用（后续 record 不再调度——禁每窗口重复刷屏）
+        this.#capabilityMissing = true
+      }
+      this.#onError(e as Error)
+    }
+  }
+
+  /** 收口：取消未决 timer + 落 pending（car run 关句柄前调用） */
+  async close(): Promise<void> {
+    await this.flush()
+  }
+}
+
 function scanLogFiles(root: string): string[] {
   const rels = readdirSync(root, { recursive: true }) as string[]
   return rels

package/test/s25-m8-runtime-core.spec.ts

@@ -198,7 +198,8 @@ test('M8: 遥测默认关——noop 句柄 + 零出站 + 零积累（可机器
   t.getMeter().createCounter('c').add(1)
   await t.flush()
   await t.shutdown()
-  assert.deepEqual(t.stats(), { spansEnded: 0, tracesExported: 0, metricsExported: 0, droppedExports: 0 })
+  // 1.2-S3 stats 加法字段（spansSampledOut/queueOverflows）——noop 全零意图不变
+  assert.deepEqual(t.stats(), { spansEnded: 0, spansSampledOut: 0, tracesExported: 0, metricsExported: 0, droppedExports: 0, queueOverflows: 0 })
 })
 
 test('M8: 遥测显式开——OTLP/HTTP 形状出站 + stats + 端点不可达静默丢弃（BD-05）', async () => {