@lqc123qwe/car-runtime 1.0.0 → 1.2.0

package/src/runtime-core/telemetry.ts

@@ -0,0 +1,333 @@
+/**
+ * M8 · 遥测门面（getTracer/getMeter ——《系统设计》§3.2.M8.2 遥测行 / §3.2.M8.5 隐私三原则）
+ *
+ * 口径（§3.2.M8.5 关键约束，逐条落地）：
+ *  - 默认关：无端点配置时不初始化任何 exporter——无配置 = noop 句柄 + 零出站（可机器断言）；
+ *  - 显式开：用户配置端点即视为开启（CAR_OTEL_ENDPOINT 或显式 config 传入）；
+ *  - 端点归用户：数据只发往用户自配 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 的零内容红线语义（内容治理属调用方）；
+ *  - 零依赖：OTel「标准句柄形态」自研（startSpan/attributes/end、createCounter/add），
+ *    不引入 @opentelemetry/* 依赖（项目零依赖红线，README engines 纪律）。
+ */
+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
+  serviceName?: string
+  headers?: Record<string, string>
+  /** 导出超时（§3.5.4 基线 5s） */
+  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 {
+  setAttribute(key: string, value: string | number | boolean): this
+  addEvent(name: string, attrs?: Record<string, string | number | boolean>): this
+  recordException(err: unknown): this
+  end(): void
+  readonly traceId: string
+}
+
+export interface TelemetryTracer {
+  startSpan(name: string, opts?: { attributes?: Record<string, string | number | boolean> }): TelemetrySpan
+}
+
+export interface TelemetryCounter {
+  add(value: number, labels?: Record<string, string>): void
+}
+
+export interface TelemetryMeter {
+  createCounter(name: string): TelemetryCounter
+}
+
+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 {
+  /** 默认关 = false（无端点配置时） */
+  readonly enabled: boolean
+  /** 幂等句柄（§3.2.M8.2：天然幂等） */
+  getTracer(): TelemetryTracer
+  getMeter(): TelemetryMeter
+  /** 手动导出（BD-05：端点不可达静默丢弃——resolve 不 reject） */
+  flush(): Promise<void>
+  shutdown(): Promise<void>
+  /** 观察面（测试/收口；不含内容字段） */
+  stats(): TelemetryStats
+}
+
+// ==================== noop 句柄（默认关路径：零出站、零积累） ====================
+
+const noopSpan = (): TelemetrySpan => ({
+  setAttribute() { return noopSpan() },
+  addEvent() { return noopSpan() },
+  recordException() { return noopSpan() },
+  end() {},
+  traceId: '',
+})
+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
+}
+
+// ==================== 活动门面（显式开路径） ====================
+
+interface SpanRecord {
+  traceId: string
+  spanId: string
+  parentSpanId: string | null
+  name: string
+  startMs: number
+  endMs: number
+  attributes: Record<string, string | number | boolean>
+}
+
+const attrValue = (v: string | number | boolean) =>
+  typeof v === 'string' ? { stringValue: v } : typeof v === 'boolean' ? { boolValue: v } : { doubleValue: v }
+
+export function createTelemetryFacade(
+  config: TelemetryConfig | null | undefined,
+  opts: { fetchImpl?: typeof fetch; now?: () => number } = {},
+): TelemetryFacade {
+  const endpoint = config?.endpoint?.replace(/\/+$/, '')
+  if (!endpoint) {
+    return {
+      enabled: false,
+      getTracer: () => NOOP_TRACER,
+      getMeter: () => NOOP_METER,
+      flush: async () => {},
+      shutdown: async () => {},
+      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[] = []
+  // 计数器键 = 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> => {
+    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
+      }
+    }
+  }
+
+  const flush = async (): Promise<void> => {
+    if (flushing) return
+    flushing = true
+    try {
+      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: batch.map(s => ({
+              traceId: s.traceId,
+              spanId: s.spanId,
+              ...(s.parentSpanId ? { parentSpanId: s.parentSpanId } : {}),
+              name: s.name,
+              kind: 'SPAN_KIND_INTERNAL',
+              startTimeUnixNano: String(s.startMs * 1e6),
+              endTimeUnixNano: String(s.endMs * 1e6),
+              attributes: Object.entries(s.attributes).map(([key, v]) => ({ key, value: attrValue(v) })),
+              status: { code: 'STATUS_CODE_UNSET' },
+            })),
+          }],
+        }
+        if (await exportOtlp('/v1/traces', body)) stats.tracesExported++
+        else stats.droppedExports++
+      }
+      if (counters.size) {
+        const batch = [...counters.entries()]
+        counters.clear()
+        const body = {
+          resource: { attributes: [{ key: 'service.name', value: { stringValue: serviceName } }] },
+          scopeMetrics: [{
+            scope: { name: 'car-runtime' },
+            metrics: batch.map(([, c]) => ({
+              name: c.name,
+              sum: {
+                aggregationTemporality: 'AGGREGATION_TEMPORALITY_CUMULATIVE',
+                dataPoints: Object.entries(c.labels).length
+                  ? Object.entries(c.labels).map(([k, v]) => ({ asInt: c.value, attributes: [{ key: k, value: { stringValue: v } }] }))
+                  : [{ asInt: c.value }],
+              },
+            })),
+          }],
+        }
+        if (await exportOtlp('/v1/metrics', body)) stats.metricsExported++
+        else stats.droppedExports++
+      }
+    } finally {
+      flushing = false
+    }
+  }
+
+  if ((config?.intervalMs ?? 0) > 0) timer = setInterval(() => { void flush() }, config!.intervalMs!)
+
+  const activeTracer: TelemetryTracer = {
+    startSpan(name, startOpts) {
+      const record: SpanRecord = {
+        traceId: randomBytes(16).toString('hex'),
+        spanId: randomBytes(8).toString('hex'),
+        parentSpanId: null,
+        name,
+        startMs: now(),
+        endMs: 0,
+        attributes: { ...startOpts?.attributes },
+      }
+      return {
+        get traceId() { return record.traceId },
+        setAttribute(key, value) { record.attributes[key] = value; return this },
+        addEvent(evtName, attrs) { record.attributes[`event.${evtName}`] = attrs ? JSON.stringify(attrs) : evtName; return this },
+        recordException(err) { record.attributes['exception.message'] = String((err as Error)?.message ?? err); return this },
+        end() {
+          record.endMs = now()
+          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)
+        },
+      }
+    },
+  }
+
+  const activeMeter: TelemetryMeter = {
+    createCounter(name) {
+      return {
+        add(value, labels = {}) {
+          const key = name + JSON.stringify(labels)
+          const cur = counters.get(key) ?? { name, labels, value: 0 }
+          cur.value += value
+          counters.set(key, cur)
+        },
+      }
+    },
+  }
+
+  return {
+    enabled: true,
+    getTracer() { tracer ??= activeTracer; return tracer },
+    getMeter() { meter ??= activeMeter; return meter },
+    flush,
+    async shutdown() {
+      if (timer) { clearInterval(timer); timer = null }
+      await flush()
+    },
+    stats: () => ({ ...stats }),
+  }
+}

package/src/runtime-core/types.ts

@@ -0,0 +1,79 @@
+/**
+ * M8 · 运行时底座共享 DTO（《系统设计》§3.2.M8.3 / §3.3.1 O-10/O-11/O-13/O-14）
+ *
+ * 口径：
+ *  - LlmChunk.finishReason 为不可变透传（readonly 语义，ADR-001；vLLM #53269 教训 SR-17）——
+ *    唯一信号源，禁止中间层改写/吞没；llm.ts 的流包装层对此做防御性断言；
+ *  - LlmRequest.tools 含 declaredSideEffect（权限门依据；readonly 是 ADR-001 补错重试白名单前置）；
+ *  - ToolDefinition 为 M8 共享 DTO（O-10）：M3 授权门/M5 MCP 网关/M8 模型请求三方复用；
+ *    与 loop/stop.ts 的 ToolDef 分工——ToolDefinition 是声明面（进模型 schema），ToolDef 是执行面；
+ *  - CredentialRef 不落明文（O-13）：ref 只含来源定位，值经 credentials.reveal 按需取用；
+ *  - 规格外扩展字段（adapterId / error）以加法演进登记——与 hostRaw 同纪律，不改动规格最小集语义。
+ */
+
+/** 模型请求（Provider 无关） */
+export interface LlmRequest {
+  model: string
+  messages: Array<{ role: 'system' | 'user' | 'assistant' | 'toolResult'; content: unknown }>
+  /** 工具 schema（缓存失效因素：工具集合/模型切换/compaction，D3 §14.6） */
+  tools: ToolDefinition[]
+  maxTokens?: number
+  metadata?: { sessionId: string; turnId: string; traceId: string }
+  // —— 规格外加法扩展（登记：M8 收口文档 §4）——
+  /** 多适配器在册时显式路由；缺省用默认适配器 */
+  adapterId?: string
+}
+
+/** 工具调用流式增量（跨 chunk 聚合出完整 ToolCall） */
+export interface ToolCallDelta {
+  index?: number
+  id?: string
+  name?: string
+  /** JSON 增量片段，聚合后整体 JSON.parse（半截 JSON 不解析——ADR-001 同纪律） */
+  argumentsDelta?: string
+}
+
+/** 流式块（finishReason 一经产生不可被任何中间层改写） */
+export interface LlmChunk {
+  delta?: string
+  toolCallDelta?: ToolCallDelta
+  finishReason?: 'stop' | 'length' | 'toolUse' | 'error' | 'aborted'
+  // —— 规格外加法扩展（登记：M8 收口文档 §4）——
+  /** finishReason='error' 时的结构化原因（消费方落 turnEnd meta，不进模型消息流） */
+  error?: { code: string; message: string }
+}
+
+/** Provider 适配器（ACL，C-02）：统一签名，消解 Provider 差异 */
+export interface LlmAdapter {
+  /** 如 openai-compat / anthropic */
+  id: string
+  chat(req: LlmRequest): AsyncIterable<LlmChunk>
+}
+
+/** 可逆注册句柄（dispose = Effect 回卷） */
+export interface Disposable {
+  dispose(): void
+}
+
+/** 共享工具声明 DTO（O-10；注册时构造，进模型请求 schema） */
+export interface ToolDefinition {
+  name: string
+  description?: string
+  /** JSON Schema 形态参数声明 */
+  parameters?: unknown
+  /** 副作用声明（必填——M5 网关 T-22 强制点同一口径：缺声明即 write） */
+  declaredSideEffect: 'readonly' | 'write'
+}
+
+/** 凭据来源（§3.2.M8.3 字段表：env 需用户显式开启 fallback） */
+export type CredentialSource = 'keychain' | 'env'
+
+/** 凭据引用（O-13）：只含来源定位与掩码提示，值永不入此结构 */
+export interface CredentialRef {
+  provider: string
+  source: CredentialSource
+  /** 来源标识：keychain 服务名 / env 变量名 */
+  origin: string
+  /** keychain 通道不可用等降级留痕（降级必须显式，禁静默） */
+  degraded?: string
+}

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/s18.spec.ts

@@ -50,6 +50,15 @@ test('S18: 采集窗口——会话结束 stderr 输出零内容快照（登记
   assert.ok('car_registry_decision|source=registry' in snap)
 })
 
+test('S18+: 1.1-S4 边界——未指定 --plugin 时装载计数不出现（装载接线不改变缺省协议面与快照键集）', async () => {
+  const { stderr } = await talk('claude-code', [
+    JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'session_start', arguments: { hostSessionId: 's' } } }),
+  ])
+  const snap = JSON.parse(/snapshot=(\{.*?\}) zeroContent/.exec(stderr)![1])
+  assert.ok(!('car_load_total|result=ok' in snap), '无 --plugin = 无装载计数（1.1 装载接线为显式 opt-in）')
+  assert.ok(!('car_unsigned_confirmed|confirmed=no' in snap))
+})
+
 test('S18: codex 宿主接入（同一入口不同 hostId）', async () => {
   const { outs } = await talk('codex', [
     JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'session_start', arguments: { hostSessionId: 'cx-e2e' } } }),