@aiwayds/dsh-topics-memory 0.22.0 → 0.23.0

package/src/embedding.ts

@@ -0,0 +1,294 @@
+/**
+ * Local embedding client (ollama) — the semantic layer behind the nearFloor
+ * reranker (A4 决议 2, spec §3.1).
+ *
+ * Semantics (mirror of jev/client's outcome mode):
+ *  - every failure returns as a structured {ok:false, outcome} result, NEVER
+ *    a throw — the caller degrades explicitly to the pure-lexical path;
+ *  - one AbortSignal.timeout per request, NO retry (query 2s / batch 30s);
+ *  - localhost only in v1 (ADR 0017 local exception). Remote providers do
+ *    not exist here by design: a remote embedding may only ever enter a
+ *    slow-lane/offline path, never the fast lane (red line ①).
+ *
+ * @module embedding
+ */
+
+import { execFileSync } from 'node:child_process'
+
+/** Default ollama bind (the plugin's own default; OLLAMA_HOST overrides). */
+export const DEFAULT_EMBED_HOST = 'http://127.0.0.1:11434'
+
+/** Provider default model when embeddingModel is the '' sentinel
+ *  (spec §7: ollama → nomic-embed-text, 768 dims, A1 §5 measured). */
+export const DEFAULT_EMBED_MODEL = 'nomic-embed-text'
+
+/** Query-side timeout — the reranker sits in the spliced hot path; a slow
+ *  ollama must lose the race, not the injection. */
+export const EMBED_QUERY_TIMEOUT_MS = 2000
+/** Batch-side timeout (index rebuild: A1 measured ~9.5s for 137 topics). */
+export const EMBED_BATCH_TIMEOUT_MS = 30_000
+
+/** Per-text byte cap before anything leaves the process (query端 p50=153 tok
+ *  ~ well under this; the cap only bites on paste pollution). */
+export const MAX_TEXT_BYTES = 2048
+
+/** The only provider v1 speaks. Anything else is an explicit
+ *  unsupported_provider outcome, not a silent attempt. */
+export const SUPPORTED_PROVIDER = 'ollama'
+
+/** The config slice the embed functions need (pass straight from
+ *  TopicsConfigValue). '' sentinels: provider off / provider default model. */
+export interface EmbeddingConfig {
+  provider?: string
+  model?: string
+  /** Explicit host; absent → OLLAMA_HOST env → DEFAULT_EMBED_HOST. */
+  host?: string
+}
+
+/** Resolve the ollama base URL: explicit arg wins, then OLLAMA_HOST, then
+ *  the localhost default. Bare `host:port` values get the http:// prefix
+ *  (ollama's own OLLAMA_HOST convention); trailing slashes are trimmed. */
+export function resolveEmbedHost(explicit?: string): string {
+  const raw = (explicit ?? process.env.OLLAMA_HOST ?? '').trim()
+  const withScheme = raw === '' ? DEFAULT_EMBED_HOST : /^https?:\/\//.test(raw) ? raw : `http://${raw.replace(/^tcp:\/\//, '')}`
+  return withScheme.replace(/\/+$/, '')
+}
+
+/** '' sentinel → provider default model. */
+export function resolveEmbedModel(model?: string): string {
+  const m = (model ?? '').trim()
+  return m === '' ? DEFAULT_EMBED_MODEL : m
+}
+
+/** Truncate a string to ≤ maxBytes UTF-8 bytes WITHOUT splitting a multibyte
+ *  character: cut at the byte cap, then back off over any continuation bytes
+ *  (0b10xxxxxx) so the decoded tail is never a replacement char. */
+export function truncateUtf8(text: string, maxBytes: number = MAX_TEXT_BYTES): string {
+  if (maxBytes <= 0) return ''
+  const buf = Buffer.from(text, 'utf8')
+  if (buf.length <= maxBytes) return text
+  let end = maxBytes
+  while (end > 0 && (buf[end]! & 0xc0) === 0x80) end -= 1
+  return buf.subarray(0, end).toString('utf8')
+}
+
+// ---------------------------------------------------------------------------
+// Outcomes — the explicit-degradation vocabulary. Callers branch on `ok`;
+// `outcome` is the human/queryable why (降级状态可查, spec §3.1).
+// ---------------------------------------------------------------------------
+
+export type EmbeddingFailureOutcome =
+  | 'provider_off' // config provider is the '' sentinel — semantic layer off
+  | 'unsupported_provider' // configured, but not a v1 provider (no remote!)
+  | 'empty_input' // nothing to embed — refused before any network activity
+  | 'network' // connect refused / DNS / socket — ollama not serving
+  | 'timeout' // the one AbortSignal fired
+  | 'model_missing' // ollama answered 404: model not pulled
+  | 'http_4xx'
+  | 'http_5xx'
+  | 'bad_json'
+  | 'bad_shape' // 200 but the embeddings array is malformed / dims disagree
+
+export interface EmbedBatchOk {
+  ok: true
+  /** Vectors aligned 1:1 with the (truncated) input texts. */
+  vectors: number[][]
+  model: string
+  dim: number
+  latencyMs: number
+}
+
+export interface EmbedQueryOk {
+  ok: true
+  vector: number[]
+  model: string
+  dim: number
+  latencyMs: number
+}
+
+export interface EmbedFailure {
+  ok: false
+  outcome: EmbeddingFailureOutcome
+  message: string
+  host: string
+  model: string
+  latencyMs: number
+}
+
+export type EmbedResult = EmbedBatchOk | EmbedFailure
+export type EmbedQueryResult = EmbedQueryOk | EmbedFailure
+export type ProbeResult = { ok: true; host: string; model: string; dim: number; latencyMs: number } | EmbedFailure
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v)
+}
+
+/** Shared request path: POST {host}/api/embed, outcome-mode failures only. */
+async function embedRequest(
+  texts: readonly string[],
+  config: EmbeddingConfig,
+  timeoutMs: number,
+): Promise<EmbedResult> {
+  const provider = (config.provider ?? '').trim()
+  if (provider === '') {
+    return { ok: false, outcome: 'provider_off', message: "embeddingProvider is '' — the semantic layer is off (pure lexical).", host: resolveEmbedHost(config.host), model: resolveEmbedModel(config.model), latencyMs: 0 }
+  }
+  if (provider !== SUPPORTED_PROVIDER) {
+    return { ok: false, outcome: 'unsupported_provider', message: `embeddingProvider '${provider}' is not supported in v1 (only '${SUPPORTED_PROVIDER}'); remote providers may not enter the fast lane.`, host: resolveEmbedHost(config.host), model: resolveEmbedModel(config.model), latencyMs: 0 }
+  }
+  if (texts.length === 0) {
+    return { ok: false, outcome: 'empty_input', message: 'no texts to embed.', host: resolveEmbedHost(config.host), model: resolveEmbedModel(config.model), latencyMs: 0 }
+  }
+  const host = resolveEmbedHost(config.host)
+  const model = resolveEmbedModel(config.model)
+  const started = Date.now()
+  let res: Response
+  try {
+    res = await fetch(`${host}/api/embed`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ model, input: texts.map((t) => truncateUtf8(t)) }),
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+  } catch (err) {
+    const outcome: EmbeddingFailureOutcome =
+      err instanceof Error && (err.name === 'TimeoutError' || err.name === 'AbortError') ? 'timeout' : 'network'
+    return { ok: false, outcome, message: `${outcome}: ${err instanceof Error ? err.message : String(err)}`, host, model, latencyMs: Date.now() - started }
+  }
+  if (!res.ok) {
+    const text = (await res.text().catch(() => '')).slice(0, 300)
+    // ollama answers 404 {"error":"model \"…\" not found, try pulling it first"}
+    const outcome: EmbeddingFailureOutcome = res.status === 404 ? 'model_missing' : res.status >= 500 ? 'http_5xx' : 'http_4xx'
+    return { ok: false, outcome, message: `ollama responded ${res.status}: ${text}`, host, model, latencyMs: Date.now() - started }
+  }
+  let json: unknown
+  try {
+    json = await res.json()
+  } catch (err) {
+    return { ok: false, outcome: 'bad_json', message: `non-JSON body: ${err instanceof Error ? err.message : String(err)}`, host, model, latencyMs: Date.now() - started }
+  }
+  const vectors = isPlainObject(json) ? json.embeddings : undefined
+  if (
+    !Array.isArray(vectors) ||
+    vectors.length !== texts.length ||
+    !vectors.every((v) => Array.isArray(v) && v.length > 0 && v.every((n) => typeof n === 'number' && Number.isFinite(n))) ||
+    new Set(vectors.map((v) => (v as number[]).length)).size !== 1
+  ) {
+    return { ok: false, outcome: 'bad_shape', message: 'embeddings must be a rectangular [texts.length][dim] array of finite numbers.', host, model, latencyMs: Date.now() - started }
+  }
+  return { ok: true, vectors: vectors as number[][], model, dim: (vectors[0] as number[]).length, latencyMs: Date.now() - started }
+}
+
+/** Batch-embed texts (index build/rebuild path). Vectors align 1:1 with the
+ *  input order; each text is truncated to MAX_TEXT_BYTES first. */
+export async function embedTexts(
+  texts: readonly string[],
+  config: EmbeddingConfig = {},
+  opts: { timeoutMs?: number } = {},
+): Promise<EmbedResult> {
+  const timeoutMs = Number(opts.timeoutMs) > 0 ? Number(opts.timeoutMs) : EMBED_BATCH_TIMEOUT_MS
+  return embedRequest(texts, config, timeoutMs)
+}
+
+/** Embed one query (reranker hot path, 2s budget). Empty/whitespace queries
+ *  fail locally with 'empty_input' — nothing leaves the process. */
+export async function embedQuery(
+  query: string,
+  config: EmbeddingConfig = {},
+  opts: { timeoutMs?: number } = {},
+): Promise<EmbedQueryResult> {
+  if ((query ?? '').trim() === '') {
+    return { ok: false, outcome: 'empty_input', message: 'empty query.', host: resolveEmbedHost(config.host), model: resolveEmbedModel(config.model), latencyMs: 0 }
+  }
+  const timeoutMs = Number(opts.timeoutMs) > 0 ? Number(opts.timeoutMs) : EMBED_QUERY_TIMEOUT_MS
+  const r = await embedRequest([query], config, timeoutMs)
+  if (!r.ok) return r
+  return { ok: true, vector: r.vectors[0]!, model: r.model, dim: r.dim, latencyMs: r.latencyMs }
+}
+
+/**
+ * Probe: is the server there, is the model pulled? One micro embed call —
+ * unlike a /api/tags listing it validates the FULL path (server + model +
+ * response shape) and yields the vector dim for index validation, at the
+ * same 15-30ms cost (A1 §5). Structured result; never throws.
+ */
+export async function probeEmbedding(config: EmbeddingConfig = {}, opts: { timeoutMs?: number } = {}): Promise<ProbeResult> {
+  const timeoutMs = Number(opts.timeoutMs) > 0 ? Number(opts.timeoutMs) : EMBED_QUERY_TIMEOUT_MS
+  const r = await embedRequest(['dsh-topics-memory semantic layer probe'], config, timeoutMs)
+  if (!r.ok) return r
+  return { ok: true, host: resolveEmbedHost(config.host), model: resolveEmbedModel(config.model), dim: r.dim, latencyMs: r.latencyMs }
+}
+
+/**
+ * Build an embedder handle for retrieval's `ensureIndexFresh` — a callable
+ * embedTexts bound to this config, carrying the RESOLVED model identity the
+ * index must match. ensureIndexFresh reads `.model` only; the actual
+ * rebuild stays with the caller.
+ */
+export function embedderWith(
+  config: EmbeddingConfig,
+): ((texts: readonly string[]) => Promise<EmbedResult>) & { model: string } {
+  const fn = (texts: readonly string[]) => embedTexts(texts, config)
+  return Object.assign(fn, { model: resolveEmbedModel(config.model) })
+}
+
+// --- Sync query embed (Phase-2 wiring) --------------------------------------
+// The spliced hot path is synchronous (the chancelu lesson): retrieveSync
+// cannot await. A local ollama query is 15-30ms steady state (A1 §5), so a
+// bounded SYNC subprocess call keeps the reranker on the hot lane inside the
+// ADR 0017 local exception — hard-capped so a wedged ollama loses the race,
+// never the injection. curl ships with the host OS; node has no sync HTTP.
+
+/** Hard sync budget for the hot-lane query embed. Generous over the measured
+ *  15-30ms, merciless for a wedged server. */
+export const EMBED_QUERY_SYNC_TIMEOUT_MS = 250
+
+export function embedQuerySync(query: string, config: EmbeddingConfig = {}): EmbedQueryResult {
+  const provider = (config.provider ?? '').trim()
+  if (provider === '') {
+    return { ok: false, outcome: 'provider_off', message: "embeddingProvider is '' — the semantic layer is off.", host: resolveEmbedHost(config.host), model: resolveEmbedModel(config.model), latencyMs: 0 }
+  }
+  if (provider !== SUPPORTED_PROVIDER) {
+    return { ok: false, outcome: 'unsupported_provider', message: `embeddingProvider '${provider}' is not supported in v1.`, host: resolveEmbedHost(config.host), model: resolveEmbedModel(config.model), latencyMs: 0 }
+  }
+  if ((query ?? '').trim() === '') {
+    return { ok: false, outcome: 'empty_input', message: 'empty query.', host: resolveEmbedHost(config.host), model: resolveEmbedModel(config.model), latencyMs: 0 }
+  }
+  const host = resolveEmbedHost(config.host)
+  const model = resolveEmbedModel(config.model)
+  const started = Date.now()
+  let raw: string
+  try {
+    raw = execFileSync(
+      'curl',
+      [
+        '-sS',
+        '--max-time', String(Math.ceil(EMBED_QUERY_SYNC_TIMEOUT_MS / 1000)),
+        '-X', 'POST', `${host}/api/embed`,
+        '-H', 'content-type: application/json',
+        '-d', JSON.stringify({ model, input: [truncateUtf8(query)] }),
+      ],
+      { timeout: EMBED_QUERY_SYNC_TIMEOUT_MS, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] },
+    )
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    const outcome: EmbeddingFailureOutcome = /timed out|ETIMEDOUT|maxTime/i.test(message) ? 'timeout' : 'network'
+    return { ok: false, outcome, message: `${outcome}: ${message}`, host, model, latencyMs: Date.now() - started }
+  }
+  let json: unknown
+  try {
+    json = JSON.parse(raw)
+  } catch {
+    return { ok: false, outcome: 'bad_json', message: 'ollama returned non-JSON (sync path).', host, model, latencyMs: Date.now() - started }
+  }
+  const embeddings = isPlainObject(json) ? (json as Record<string, unknown>).embeddings : undefined
+  const first = Array.isArray(embeddings) && embeddings.length > 0 ? embeddings[0] : undefined
+  if (!Array.isArray(first)) {
+    return { ok: false, outcome: 'bad_shape', message: 'ollama response has no embeddings[0] array (sync path).', host, model, latencyMs: Date.now() - started }
+  }
+  const vector = (first as unknown[]).filter((n): n is number => typeof n === 'number')
+  if (vector.length === 0 || vector.length !== (first as unknown[]).length) {
+    return { ok: false, outcome: 'bad_shape', message: 'embeddings[0] malformed (sync path).', host, model, latencyMs: Date.now() - started }
+  }
+  return { ok: true, vector, model, dim: vector.length, latencyMs: Date.now() - started }
+}

package/src/ilog.ts

@@ -27,6 +27,14 @@ export interface SlowItem {
   why: string
 }
 
+/**
+ * Slow-lane full-lifecycle outcome (A4 决议 3, spec §3.2): where a slow-lane
+ * run (or round with a slow-lane stake) ended. Precedent = decisions.jsonl's
+ * outcome enum — a closed vocabulary so 「没跑」(no-run/no-claim) and 「跑了
+ * 全败」(llm-error/timeout) are finally distinguishable in the log.
+ */
+export type SlowOutcome = 'no-run' | 'no-claim' | 'no-candidates' | 'llm-error' | 'timeout' | 'delivered' | 'expired'
+
 export interface InjectionRecord {
   at: string
   sessionId?: string
@@ -60,6 +68,15 @@ export interface InjectionRecord {
   slowMs?: number
   /** Slow-lane pointers this round, in delivery order. */
   slow?: SlowItem[]
+  /**
+   * Slow-lane disposition for this round (A4 决议 3, spec §8.2): `delivered`
+   * when a pending was consumed and packed, `expired` at its hard bounds, and
+   * the producing run's failure point (no-run/no-claim/no-candidates/
+   * llm-error/timeout) when a spliced arrived with no pending. Optional —
+   * older lines predate the field and pure fast-lane rounds may omit it.
+   * Written once with the record, never backfilled (ilog append-only).
+   */
+  slowOutcome?: SlowOutcome
 }
 
 /**

package/src/index.ts

@@ -501,8 +501,9 @@ export async function apply(ctx: Context, config: TopicsRuntimeConfig = {}): Pro
       if (cfg.autoInject) {
         const consumed = slowLane.consume(sessionId, observer.turnCountOf(sessionId))
         if (consumed !== undefined) {
-          if ('pending' in consumed) slow = consumed.pending
-          else slowExpired = consumed.expired
+          if ('pending' in consumed) {
+            slow = { ...consumed.pending, outcome: consumed.pending.outcome }
+          } else slowExpired = consumed.expired
         }
       }
       const r = service.retrieveSync(query, sessionId, seen === undefined && echo === undefined ? undefined : { exclude: seen, echo }, slow, slowExpired)
@@ -708,7 +709,10 @@ export async function apply(ctx: Context, config: TopicsRuntimeConfig = {}): Pro
     // and its own settle hook does the release.
     const run = distiller.request(sessionId, reason)
     if (run !== undefined) {
-      void run.finally(() => releaseSessionLlm(sessionId)).catch(() => undefined)
+      void run
+        .finally(() => releaseSessionLlm(sessionId))
+        .then(() => service.refreshEmbeddingIndex())
+        .catch(() => undefined)
     }
   })
 
@@ -916,7 +920,11 @@ export async function apply(ctx: Context, config: TopicsRuntimeConfig = {}): Pro
                 // no-adapter detail instead
               }
               const run = distiller.request(sessionId, 'boot-replay')
-              if (run !== undefined) void run.catch(() => undefined)
+              if (run !== undefined) {
+                void run
+                  .then(() => service.refreshEmbeddingIndex())
+                  .catch(() => undefined)
+              }
             })
             .catch(() => undefined)
           // Consolidation cadence check — after the pull (freshest pool),
@@ -951,6 +959,9 @@ export async function apply(ctx: Context, config: TopicsRuntimeConfig = {}): Pro
               })
               .catch(() => undefined)
           }
+          // Embedding index maintenance (A4/A6, spec §3): boot-time freshness
+          // check + incremental rebuild — provider '' / packageMode off = no-op.
+          void service.refreshEmbeddingIndex().catch(() => undefined)
         })
         .catch((error: unknown) => {
           warn(`dsh-topics-memory 启动链失败（不影响会话启动）：${error instanceof Error ? error.message : String(error)}`)
@@ -1075,7 +1086,11 @@ export async function apply(ctx: Context, config: TopicsRuntimeConfig = {}): Pro
           ? { ok: false, reason: 'in-flight', created: [], updated: [], marked: 0 }
           : { ok: false, reason: 'no-model', created: [], updated: [], marked: 0 }
       }
-      return run.finally(() => releaseSessionLlm(sessionId))
+      void run
+        .finally(() => releaseSessionLlm(sessionId))
+        .then(() => service.refreshEmbeddingIndex())
+        .catch(() => undefined)
+      return run
     }
     // Manual /topics consolidate trigger: same lane as the cadence path, same
     // trigger-time llm capture and in-flight guard (the command runs inside a
@@ -1146,6 +1161,9 @@ const DEFAULTS: TopicsConfigValue = {
   distillMaxModelCalls: 8,
   consolidateCadence: 'daily',
   deprecatedTtlDays: 15,
+  embeddingProvider: '',
+  embeddingModel: '',
+  packageMode: 'off',
   usageBoost: 0.15,
   pushDebounceSeconds: 45,
 }

package/src/pipeline-events.ts

@@ -0,0 +1,132 @@
+/**
+ * meta/pipeline-events.jsonl — the pipeline-level anomaly ledger (spec §8.1,
+ * A2/A6 BL-1 revised: the "记 wtf 账" mechanism never existed, this IS the
+ * explicit ledger). One line JSON per event; always on, no config key
+ * (恒开无键 — observability is not a gray-release feature).
+ *
+ * Discipline = decisions.jsonl (src/jev/log.ts) verbatim: field-whitelist
+ * copy on write (extra caller fields cannot leak in, detail values must be
+ * scalar), 512KB auto-compaction keeping the most recent quarter, and write
+ * failures swallowed silently — a broken sink must never break the pipeline.
+ * Unlike jev/log this writer takes the bundle root explicitly (callers like
+ * the slow lane already hold it; tests point it at a tmp dir).
+ *
+ * @module pipeline-events
+ */
+
+import { appendFile, mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import { dirname, join } from 'node:path'
+import { metaDir } from './paths.ts'
+
+/** Closed vocabulary, spec §8.1 + W-C wave start set. `slow-lane-outcome` is
+ *  the slow lane's per-run disposition row (quality.ts); the distill/link
+ *  kinds are the A2/A6 producers' contract — they import this module. */
+export type PipelineEventKind = 'slow-lane-outcome' | 'distill-op-invalid' | 'distill-op-retry-exhausted' | 'link-ref-rejected'
+
+/** File NAME inside the bundle's meta dir (path via pipelineEventsFile). */
+export const PIPELINE_EVENTS_FILE = 'pipeline-events.jsonl'
+
+export interface PipelineEvent {
+  at: string
+  kind: PipelineEventKind
+  /** Bounded scalar metadata only — never conversation or conclusion text. */
+  detail?: Record<string, string | number | boolean>
+}
+
+const COMPACT_LIMIT = 512 * 1024 // ~512KB cap, same as the decisions/ilog sidecars
+/** Whitelist copy bounds: detail entries and their values stay metadata-sized. */
+const DETAIL_MAX_ENTRIES = 16
+const DETAIL_KEY_MAX_CHARS = 64
+const DETAIL_VALUE_MAX_CHARS = 256
+
+/** Runtime mirror of PipelineEventKind — the closed vocabulary is enforced
+ *  at the write gate too (a JS caller cannot smuggle an unknown kind in). */
+const KNOWN_KINDS: ReadonlySet<string> = new Set<string>([
+  'slow-lane-outcome',
+  'distill-op-invalid',
+  'distill-op-retry-exhausted',
+  'link-ref-rejected',
+])
+
+export function pipelineEventsFile(bundleDir: string): string {
+  return join(metaDir(bundleDir), PIPELINE_EVENTS_FILE)
+}
+
+// Serialized like jev/log: single-record appends are line-atomic anyway, but
+// the compaction rewrite must not interleave with an append.
+let queue: Promise<unknown> = Promise.resolve()
+
+function enqueue<T>(op: () => Promise<T>): Promise<T> {
+  const run = queue.then(op, op)
+  queue = run.catch(() => undefined)
+  return run
+}
+
+/** All write failures die HERE — never upstream. */
+async function appendJsonl(file: string, lines: readonly string[]): Promise<void> {
+  await enqueue(async () => {
+    try {
+      await mkdir(dirname(file), { recursive: true })
+      await appendFile(file, lines.map((l) => `${l}\n`).join(''), 'utf8')
+      await compactIfNeeded(file)
+    } catch {
+      // fail-open: a broken ledger must never break the pipeline (§8.1)
+    }
+  })
+}
+
+// jev/log compactIfNeeded pattern: ~512KB cap; keep the most recent quarter
+// when exceeded (headroom for the next window).
+async function compactIfNeeded(file: string): Promise<void> {
+  let raw: string
+  try {
+    raw = await readFile(file, 'utf8')
+  } catch {
+    return
+  }
+  if (raw.length <= COMPACT_LIMIT) return
+  const lines = raw.split('\n').filter((l) => l.trim() !== '')
+  const keep = lines.slice(-Math.max(1, Math.floor(lines.length / 4)))
+  const tmp = `${file}.tmp-${randomUUID()}`
+  try {
+    await writeFile(tmp, keep.map((l) => `${l}\n`).join(''), 'utf8')
+    await rename(tmp, file)
+  } catch {
+    // swallow — the next append retries the compaction
+  }
+}
+
+/**
+ * Copy one event through the field whitelist onto the ledger. Only `at`,
+ * `kind` and a scalar-valued `detail` map can pass; non-scalar detail values
+ * (objects/arrays/null/NaN), surplus entries and over-long keys/values are
+ * dropped here so no unbounded content can ride in. Write failures are
+ * swallowed downstream — this never rejects and never throws.
+ */
+export async function recordPipelineEvent(bundleDir: string, event: PipelineEvent): Promise<void> {
+  if (bundleDir === '' || typeof bundleDir !== 'string') return
+  if (event === null || typeof event !== 'object') return
+  if (typeof event.kind !== 'string' || !KNOWN_KINDS.has(event.kind)) return
+  const detail: Record<string, string | number | boolean> = {}
+  if (event.detail !== undefined && typeof event.detail === 'object') {
+    for (const [key, value] of Object.entries(event.detail)) {
+      if (Object.keys(detail).length >= DETAIL_MAX_ENTRIES) break
+      const t = typeof value
+      if (t === 'string') {
+        if ((value as string) !== '') detail[key.slice(0, DETAIL_KEY_MAX_CHARS)] = (value as string).slice(0, DETAIL_VALUE_MAX_CHARS)
+      } else if (t === 'number') {
+        if (Number.isFinite(value)) detail[key.slice(0, DETAIL_KEY_MAX_CHARS)] = value
+      } else if (t === 'boolean') {
+        detail[key.slice(0, DETAIL_KEY_MAX_CHARS)] = value
+      }
+      // objects/arrays/null/undefined never pass the whitelist
+    }
+  }
+  const at = typeof event.at === 'string' && event.at !== '' ? event.at : new Date().toISOString()
+  const row =
+    Object.keys(detail).length === 0
+      ? { at, kind: event.kind }
+      : { at, kind: event.kind, detail }
+  await appendJsonl(pipelineEventsFile(bundleDir), [JSON.stringify(row)])
+}