livetap 0.1.0

package/src/server/types.ts

@@ -0,0 +1,94 @@
+/**
+ * Types for the livetap stream service.
+ * Schema-agnostic — the service knows nothing about payload contents.
+ */
+
+// --- Connection config (discriminated union) ---
+
+export interface MqttConnectionConfig {
+  type: 'mqtt'
+  broker: string
+  port: number
+  tls: boolean
+  credentials: { username: string; password: string }
+  topics: string[]
+}
+
+export interface WebhookConnectionConfig {
+  type: 'webhook'
+}
+
+export interface WebSocketConnectionConfig {
+  type: 'websocket'
+  url: string
+  headers?: Record<string, string>
+  handshake?: string
+  reconnect?: {
+    enabled: boolean
+    maxRetries: number
+    initialDelayMs: number
+    maxDelayMs: number
+  }
+  pingIntervalMs?: number
+  binaryFormat?: 'json' | 'text' | 'base64'
+}
+
+export interface FileConnectionConfig {
+  type: 'file'
+  path: string
+}
+
+export type ConnectionConfig =
+  | MqttConnectionConfig
+  | WebhookConnectionConfig
+  | WebSocketConnectionConfig
+  | FileConnectionConfig
+
+// --- Connection status ---
+
+export interface ConnectionStatus {
+  connectionId: string
+  type: 'mqtt' | 'webhook' | 'websocket'
+  name?: string
+  summary: string
+  streamKey: string
+  createdAt: string
+  msgPerSec: number
+  bufferedCount: number
+  runtimeState: 'connected' | 'reconnecting' | 'disconnected' | 'error'
+  ingestUrl?: string
+  error?: string
+}
+
+// --- Stream entry ---
+
+export interface StreamEntry {
+  id: string
+  fields: Record<string, string>
+  ts: number
+}
+
+// --- Subscriber interface ---
+
+export interface Subscriber {
+  start(): Promise<void>
+  stop(): Promise<void>
+  getStatus(): { runtimeState: ConnectionStatus['runtimeState']; error?: string }
+}
+
+// --- Connection record (internal) ---
+
+export interface ConnectionRecord {
+  id: string
+  config: ConnectionConfig
+  name?: string
+  streamKey: string
+  createdAt: string
+  subscriber: Subscriber
+  msgCount: number
+  msgCountAtLastSample: number
+  msgPerSec: number
+  bufferedCount: number
+  throughputInterval?: ReturnType<typeof setInterval>
+  bufferedInterval?: ReturnType<typeof setInterval>
+}

package/src/server/watchers/engine.ts

@@ -0,0 +1,70 @@
+/**
+ * Expression evaluation engine for watchers.
+ * Resolves dot-paths, evaluates conditions, manages cooldown.
+ */
+
+import type { WatcherCondition, WatcherDefinition } from './types.js'
+
+/**
+ * Resolve a dot-separated path into a nested object.
+ * Returns undefined if any segment is missing.
+ */
+export function resolveDotPath(obj: any, path: string): any {
+  return path.split('.').reduce((o, k) => o?.[k], obj)
+}
+
+/**
+ * Evaluate a single condition against a parsed payload.
+ * Returns false if the field doesn't exist (no crash).
+ */
+export function evaluateCondition(payload: any, condition: WatcherCondition): boolean {
+  const value = resolveDotPath(payload, condition.field)
+  if (value === undefined) return false
+
+  switch (condition.op) {
+    case '>':        return value > condition.value
+    case '<':        return value < condition.value
+    case '>=':       return value >= condition.value
+    case '<=':       return value <= condition.value
+    case '==':       return value == condition.value
+    case '!=':       return value != condition.value
+    case 'contains': return String(value).includes(String(condition.value))
+    case 'matches':
+      try { return new RegExp(String(condition.value)).test(String(value)) }
+      catch { return false }
+    default:         return false
+  }
+}
+
+/**
+ * Evaluate all conditions for a watcher against a payload.
+ * match='all' → AND, match='any' → OR.
+ */
+export function evaluateWatcher(payload: any, watcher: Pick<WatcherDefinition, 'conditions' | 'match'>): boolean {
+  const results = watcher.conditions.map((c) => evaluateCondition(payload, c))
+  return watcher.match === 'all' ? results.every(Boolean) : results.some(Boolean)
+}
+
+/**
+ * Extract the matched field values from a payload for a set of conditions.
+ * Used in alert payloads to show what triggered the match.
+ */
+export function extractMatchedValues(payload: any, conditions: WatcherCondition[]): Record<string, unknown> {
+  const matched: Record<string, unknown> = {}
+  for (const c of conditions) {
+    const value = resolveDotPath(payload, c.field)
+    if (value !== undefined) {
+      matched[c.field] = value
+    }
+  }
+  return matched
+}
+
+/**
+ * Format conditions as a human-readable expression string.
+ */
+export function formatExpression(conditions: WatcherCondition[], match: 'all' | 'any'): string {
+  const parts = conditions.map((c) => `${c.field} ${c.op} ${c.value}`)
+  const joiner = match === 'all' ? ' AND ' : ' OR '
+  return parts.join(joiner)
+}

package/src/server/watchers/manager.ts

@@ -0,0 +1,354 @@
+/**
+ * Watcher Manager — CRUD + evaluation loops for expression watchers.
+ * Stores definitions in Redis hashes. Runs evaluator loops in-process.
+ */
+
+import Redis from 'ioredis'
+import { mkdirSync, appendFileSync, statSync, writeFileSync, readFileSync, unlinkSync } from 'fs'
+import { resolve } from 'path'
+import { homedir } from 'os'
+import type { WatcherCondition, WatcherDefinition, WatcherInfo, WatcherAlert, WatcherAction } from './types.js'
+import { VALID_OPS } from './types.js'
+import { evaluateWatcher, extractMatchedValues, formatExpression } from './engine.js'
+
+function generateId(): string {
+  const hex = Array.from(crypto.getRandomValues(new Uint8Array(4)))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('')
+  return `w_${hex}`
+}
+
+const LOG_DIR = resolve(homedir(), '.livetap', 'logs', 'watchers')
+const MAX_LOG_SIZE = 512 * 1024 // 512KB
+
+export type AlertCallback = (alert: WatcherAlert) => void
+
+export class WatcherManager {
+  private redisUrl: string
+  private loops = new Map<string, { abort: AbortController; reader: Redis }>()
+  private info = new Map<string, WatcherInfo>()
+  private onAlert: AlertCallback
+  private redis: Redis
+
+  constructor(redis: Redis, redisUrl: string, onAlert: AlertCallback) {
+    this.redis = redis
+    this.redisUrl = redisUrl
+    this.onAlert = onAlert
+    mkdirSync(LOG_DIR, { recursive: true })
+  }
+
+  async create(
+    connectionId: string,
+    streamKey: string,
+    conditions: WatcherCondition[],
+    match: 'all' | 'any' = 'all',
+    action: WatcherAction = 'channel_alert',
+    cooldown = 60,
+  ): Promise<WatcherInfo> {
+    // Validate conditions
+    if (!conditions.length) throw new Error('At least one condition is required.')
+    for (const c of conditions) {
+      if (!VALID_OPS.includes(c.op as any)) {
+        throw new Error(`Invalid op '${c.op}'. Supported: ${VALID_OPS.join(', ')}`)
+      }
+      if (!c.field) throw new Error('Each condition must have a field.')
+      if (c.op === 'matches') {
+        try { new RegExp(String(c.value)) }
+        catch (err) { throw new Error(`Invalid regex '${c.value}': ${(err as Error).message}`) }
+      }
+    }
+
+    const id = generateId()
+    const now = new Date().toISOString()
+
+    const def: WatcherDefinition = {
+      id,
+      connectionId,
+      conditions,
+      match,
+      action,
+      cooldown,
+      status: 'running',
+      createdAt: now,
+      updatedAt: now,
+    }
+
+    // Store in flat hash (globally unique watcher IDs)
+    await this.redis.hset('livetap:watchers', id, JSON.stringify(def))
+
+    const info: WatcherInfo = { ...def, matchCount: 0, entriesChecked: 0 }
+    this.info.set(id, info)
+
+    this.writeLog(id, `STARTED conditions=${formatExpression(conditions, match)} cooldown=${cooldown}s`)
+    this.startLoop(id, streamKey, def)
+
+    return info
+  }
+
+  async list(connectionId?: string): Promise<WatcherInfo[]> {
+    const all = Array.from(this.info.values())
+    return connectionId ? all.filter((w) => w.connectionId === connectionId) : all
+  }
+
+  async get(watcherId: string): Promise<WatcherInfo | undefined> {
+    return this.info.get(watcherId)
+  }
+
+  async getLogs(watcherId: string, lines = 50): Promise<string[]> {
+    const logPath = resolve(LOG_DIR, `${watcherId}.log`)
+    try {
+      const content = readFileSync(logPath, 'utf-8')
+      return content.split('\n').filter(Boolean).slice(-lines)
+    } catch {
+      return []
+    }
+  }
+
+  async update(watcherId: string, streamKey: string | null, updates: {
+    conditions?: WatcherCondition[]
+    match?: 'all' | 'any'
+    action?: WatcherAction
+    cooldown?: number
+  }): Promise<WatcherInfo | null> {
+    const info = this.info.get(watcherId)
+    if (!info) return null
+
+    // Stop existing loop
+    this.stopLoop(watcherId)
+
+    // Apply updates
+    if (updates.conditions) {
+      for (const c of updates.conditions) {
+        if (!VALID_OPS.includes(c.op as any)) {
+          throw new Error(`Invalid op '${c.op}'. Supported: ${VALID_OPS.join(', ')}`)
+        }
+        if (c.op === 'matches') {
+          try { new RegExp(String(c.value)) }
+          catch (err) { throw new Error(`Invalid regex '${c.value}': ${(err as Error).message}`) }
+        }
+      }
+      info.conditions = updates.conditions
+    }
+    if (updates.match) info.match = updates.match
+    if (updates.action) info.action = updates.action
+    if (updates.cooldown !== undefined) info.cooldown = updates.cooldown
+    info.updatedAt = new Date().toISOString()
+    info.status = 'running'
+
+    // Persist
+    const def: WatcherDefinition = { ...info }
+    await this.redis.hset('livetap:watchers', watcherId, JSON.stringify(def))
+
+    this.writeLog(watcherId, `UPDATED conditions=${formatExpression(info.conditions, info.match)} cooldown=${info.cooldown}s`)
+    this.startLoop(watcherId, streamKey, info)
+
+    return info
+  }
+
+  async restart(watcherId: string, streamKey: string | null): Promise<boolean> {
+    const info = this.info.get(watcherId)
+    if (!info) return false
+
+    this.stopLoop(watcherId)
+    info.status = 'running'
+    this.writeLog(watcherId, 'RESTARTED')
+    this.startLoop(watcherId, streamKey, info)
+    return true
+  }
+
+  async delete(watcherId: string): Promise<boolean> {
+    const info = this.info.get(watcherId)
+    if (!info) return false
+
+    this.stopLoop(watcherId)
+    this.info.delete(watcherId)
+    await this.redis.hdel('livetap:watchers', watcherId)
+
+    // Delete log file
+    try { unlinkSync(resolve(LOG_DIR, `${watcherId}.log`)) } catch { /* ok */ }
+
+    return true
+  }
+
+  async deleteAllForConnection(connectionId: string): Promise<void> {
+    const watchers = await this.list(connectionId)
+    for (const w of watchers) {
+      await this.delete(w.id)
+    }
+  }
+
+  private startLoop(watcherId: string, streamKey: string, def: WatcherDefinition) {
+    const abort = new AbortController()
+    const reader = new Redis(this.redisUrl)
+    this.loops.set(watcherId, { abort, reader })
+
+    const info = this.info.get(watcherId)!
+    let lastAlertTime = 0
+    let checkpointTime = Date.now()
+    const fieldNotFoundThrottle = new Map<string, number>() // field → last logged time
+
+    const run = async () => {
+      let lastId = '$'
+      while (!abort.signal.aborted) {
+        try {
+          const result = await reader.xread('BLOCK', 2000, 'STREAMS', streamKey, lastId)
+          if (!result || abort.signal.aborted) continue
+
+          for (const [, entries] of result) {
+            for (const [id, fieldArray] of entries) {
+              lastId = id
+              info.entriesChecked++
+              info.lastChecked = new Date().toISOString()
+
+              // Parse fields
+              const fields: Record<string, string> = {}
+              for (let i = 0; i < fieldArray.length; i += 2) {
+                fields[fieldArray[i]] = fieldArray[i + 1]
+              }
+
+              // Parse payload: try JSON first, fall back to raw fields
+              let payload: any
+              try {
+                payload = JSON.parse(fields.payload ?? '{}')
+              } catch {
+                // Plain text — use raw Redis fields as the payload
+                // This allows conditions like { field: "payload", op: "contains", value: "ERROR" }
+                payload = fields
+              }
+
+              // Log missing fields (throttled: once per field per minute)
+              for (const c of def.conditions) {
+                const val = resolveDotPathImport(payload, c.field)
+                if (val === undefined) {
+                  const last = fieldNotFoundThrottle.get(c.field) ?? 0
+                  if (Date.now() - last > 60_000) {
+                    this.writeLog(watcherId, `FIELD_NOT_FOUND ${c.field} in entry ${id}`)
+                    fieldNotFoundThrottle.set(c.field, Date.now())
+                  }
+                }
+              }
+
+              // Evaluate
+              const matched = evaluateWatcher(payload, def)
+              if (matched) {
+                const now = Date.now()
+                if (now - lastAlertTime >= def.cooldown * 1000) {
+                  lastAlertTime = now
+                  info.matchCount++
+                  info.lastMatch = new Date().toISOString()
+
+                  const matchedValues = extractMatchedValues(payload, def.conditions)
+                  const expression = formatExpression(def.conditions, def.match)
+
+                  this.writeLog(watcherId, `MATCH ${Object.entries(matchedValues).map(([k, v]) => `${k}=${v}`).join(' ')} action=${typeof def.action === 'string' ? def.action : JSON.stringify(def.action)}`)
+
+                  const alert: WatcherAlert = {
+                    watcherId,
+                    connectionId: def.connectionId,
+                    expression,
+                    matchedValues,
+                    entry: fields,
+                    ts: now,
+                  }
+
+                  // Execute action
+                  await this.executeAction(def.action, alert)
+                  this.onAlert(alert)
+                } else {
+                  const remaining = Math.round((def.cooldown * 1000 - (Date.now() - lastAlertTime)) / 1000)
+                  this.writeLog(watcherId, `SUPPRESSED ${formatExpression(def.conditions, def.match)} (cooldown ${remaining}s remaining)`)
+                }
+              }
+
+              // Checkpoint every 5 minutes
+              if (Date.now() - checkpointTime > 5 * 60 * 1000) {
+                this.writeLog(watcherId, `CHECKPOINT entries_checked=${info.entriesChecked} matches=${info.matchCount}`)
+                checkpointTime = Date.now()
+              }
+            }
+          }
+        } catch (err) {
+          if (!abort.signal.aborted) {
+            this.writeLog(watcherId, `ERROR ${(err as Error).message}`)
+            await new Promise((r) => setTimeout(r, 1000))
+          }
+        }
+      }
+      reader.disconnect()
+    }
+
+    run()
+  }
+
+  private stopLoop(watcherId: string) {
+    const loop = this.loops.get(watcherId)
+    if (loop) {
+      loop.abort.abort()
+      loop.reader.disconnect()
+      this.loops.delete(watcherId)
+    }
+    const info = this.info.get(watcherId)
+    if (info) info.status = 'stopped'
+  }
+
+  private async executeAction(action: WatcherAction, alert: WatcherAlert) {
+    if (action === 'channel_alert') return // handled by onAlert callback
+
+    if (typeof action === 'object' && 'webhook' in action) {
+      try {
+        await fetch(action.webhook, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(alert),
+        })
+      } catch (err) {
+        this.writeLog(alert.watcherId, `WEBHOOK_ERROR ${(err as Error).message}`)
+      }
+    }
+
+    if (typeof action === 'object' && 'shell' in action) {
+      try {
+        Bun.spawn(['sh', '-c', action.shell], {
+          env: {
+            ...process.env,
+            LIVETAP_WATCHER: alert.watcherId,
+            LIVETAP_PAYLOAD: JSON.stringify(alert.entry),
+            LIVETAP_MATCHED: JSON.stringify(alert.matchedValues),
+          },
+        })
+      } catch (err) {
+        this.writeLog(alert.watcherId, `SHELL_ERROR ${(err as Error).message}`)
+      }
+    }
+  }
+
+  private writeLog(watcherId: string, msg: string) {
+    const logPath = resolve(LOG_DIR, `${watcherId}.log`)
+    const line = `[${new Date().toISOString()}] ${msg}\n`
+
+    appendFileSync(logPath, line)
+
+    // Size protection: truncate to last 256KB if over 512KB
+    try {
+      const stats = statSync(logPath)
+      if (stats.size > MAX_LOG_SIZE) {
+        const content = readFileSync(logPath, 'utf-8')
+        const truncated = content.slice(-MAX_LOG_SIZE / 2)
+        // Start from first complete line
+        const firstNewline = truncated.indexOf('\n')
+        writeFileSync(logPath, truncated.slice(firstNewline + 1))
+      }
+    } catch { /* ok */ }
+  }
+
+  async stopAll() {
+    for (const id of this.loops.keys()) {
+      this.stopLoop(id)
+    }
+  }
+}
+
+// Import from engine to avoid circular
+function resolveDotPathImport(obj: any, path: string): any {
+  return path.split('.').reduce((o, k) => o?.[k], obj)
+}

package/src/server/watchers/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Watcher types for expression-based alerting.
+ */
+
+export interface WatcherCondition {
+  field: string
+  op: '>' | '<' | '>=' | '<=' | '==' | '!=' | 'contains' | 'matches'
+  value: number | string | boolean
+}
+
+export type WatcherAction =
+  | 'channel_alert'
+  | { webhook: string }
+  | { shell: string }
+
+export interface WatcherDefinition {
+  id: string
+  connectionId: string
+  conditions: WatcherCondition[]
+  match: 'all' | 'any'
+  action: WatcherAction
+  cooldown: number
+  status: 'running' | 'stopped'
+  createdAt: string
+  updatedAt: string
+}
+
+export interface WatcherInfo extends WatcherDefinition {
+  lastChecked?: string
+  matchCount: number
+  lastMatch?: string
+  entriesChecked: number
+}
+
+export interface WatcherAlert {
+  watcherId: string
+  connectionId: string
+  expression: string
+  matchedValues: Record<string, unknown>
+  entry: Record<string, string>
+  ts: number
+}
+
+export const VALID_OPS = ['>', '<', '>=', '<=', '==', '!=', 'contains', 'matches'] as const

package/src/shared/catalog-generators.ts

@@ -0,0 +1,125 @@
+/**
+ * Generates help text, --llm-help JSON, and MCP instructions from the command catalog.
+ */
+
+import { CLI_COMMANDS, type CatalogCommand } from './command-catalog.js'
+import { TOOLS } from '../mcp/tools.js'
+
+/**
+ * Generate human-readable --help text.
+ */
+export function generateHelpText(): string {
+  const lines: string[] = [
+    'livetap — Push live data streams into your AI coding agent',
+    '',
+    'Usage:',
+  ]
+
+  // Group: daemon, connections, sampling, watchers
+  const groups: { label: string; commands: string[] }[] = [
+    { label: '', commands: ['start', 'stop', 'status'] },
+    { label: '', commands: ['tap', 'untap', 'taps'] },
+    { label: '', commands: ['sip'] },
+    { label: '', commands: ['watch', 'unwatch', 'watchers'] },
+  ]
+
+  for (const group of groups) {
+    for (const name of group.commands) {
+      const cmd = CLI_COMMANDS.find((c) => c.name === name)
+      if (!cmd) continue
+      lines.push(`  ${cmd.usage.padEnd(45)} ${cmd.description}`)
+    }
+    lines.push('')
+  }
+
+  lines.push('Options:')
+  lines.push('  --port <n>        Daemon port (default 8788, env: LIVETAP_PORT)')
+  lines.push('  --foreground      Run daemon in foreground (start only)')
+  lines.push('  --json            Output as JSON (taps, watchers, sip)')
+  lines.push('  --help, -h        Show this help')
+  lines.push('  --llm-help        Machine-readable JSON for AI agents')
+  lines.push('')
+
+  return lines.join('\n')
+}
+
+/**
+ * Generate machine-readable JSON for --llm-help.
+ * Includes CLI commands AND MCP tool schemas from the same source.
+ */
+export function generateLlmHelp(): object {
+  return {
+    name: 'livetap',
+    version: '0.1.0',
+    description: 'Push live data streams into your AI coding agent',
+    commands: CLI_COMMANDS,
+    mcp_tools: TOOLS,
+  }
+}
+
+/**
+ * Generate MCP instructions string for the LLM.
+ * References actual tool names from the TOOLS array.
+ */
+export function generateInstructions(): string {
+  const toolNames = TOOLS.map((t) => t.name)
+  const connectionTools = toolNames.filter((n) => n.includes('connection'))
+  const watcherTools = toolNames.filter((n) => n.includes('watcher') || n.includes('watch'))
+
+  return `
+You have access to livetap, a live data streaming tool. Use it to connect to data sources, sample streams, and set up expression-based watchers that alert you when conditions match.
+
+WORKFLOW:
+1. CONNECT: Use create_connection to tap into a data source.
+   - MQTT: create_connection({ type: "mqtt", broker: "hostname", port: 1883, tls: false, topics: ["topic/#"], username: "", password: "" })
+   - WebSocket: create_connection({ type: "websocket", url: "wss://..." })
+   - File: create_connection({ type: "file", path: "/var/log/app.log" }) → tails the file for new lines
+   Note: for MQTT, set tls: false and port: 1883 for unencrypted brokers.
+
+2. SAMPLE: Use read_stream to inspect what data is flowing.
+   - read_stream({ connectionId: "conn_xxx", backfillSeconds: 60, maxEntries: 10 })
+   - Study the JSON payload structure to find the correct dot-paths for watchers.
+   - ALWAYS sample before creating a watcher so you know the correct field paths.
+
+3. WATCH: Use create_watcher to set up expression-based alerts.
+   - create_watcher({ connectionId: "conn_xxx", conditions: [{ field: "sensors.temperature.value", op: ">", value: 50 }], match: "all", cooldown: 60 })
+   - Supported operators: >, <, >=, <=, ==, !=, contains, matches (regex)
+   - match: "all" = AND (all conditions must be true), "any" = OR (at least one)
+   - cooldown: seconds between repeated alerts. Use 0 for rare events, 30-60 for sensors, 300+ for high-frequency.
+   - Alerts arrive as <channel> events. When you see one, act on it as the user requested.
+
+4. MANAGE:
+   - ${connectionTools.join(', ')} — manage connections
+   - ${watcherTools.join(', ')} — manage watchers
+   - Watcher IDs (w_xxx) are globally unique. No connectionId needed for get/update/delete.
+
+CHANNEL EVENTS:
+- <channel source="livetap" type="alert"> = a watcher condition matched. Read the payload and act on it.
+  The payload contains: watcherId, expression, matched_values, and the full stream entry.
+
+When the user asks to "monitor", "watch", or "alert on" something:
+1. First check list_connections — reuse an existing connection if possible
+2. If no connection exists, create one
+3. Sample the stream with read_stream to understand the data shape
+4. Create a watcher with the correct field paths from the sample
+5. Tell the user what you set up and what will trigger it
+
+AVAILABLE TOOLS: ${toolNames.join(', ')}
+
+DATA SHAPE BY SOURCE:
+- MQTT/WebSocket: entries have { payload: "{...json...}", topic: "..." }. The payload is parsed as JSON.
+  Use dot-paths into the parsed JSON: "sensors.temperature.value", "metadata.device_name"
+- File (plain text lines): entries have { payload: "the raw line", format: "text" }.
+  Use field "payload" with contains/matches: { field: "payload", op: "contains", value: "ERROR" }
+  or { field: "payload", op: "matches", value: "5[0-9]{2}" }
+- File (JSON lines): entries have { payload: "{...json...}", format: "json" }. Parsed as JSON.
+  Use dot-paths like MQTT: "level", "msg", "status"
+- IMPORTANT: always use read_stream first to see the actual field names. Do NOT guess — the field is "payload", not "line" or "message".
+
+TIPS:
+- Watcher IDs (w_xxx) are globally unique. You don't need the connectionId to get, update, or delete a watcher.
+- Common MQTT brokers: broker.emqx.io (public demo), test.mosquitto.org (public test).
+- For regex watchers, use the "matches" operator: { field: "payload", op: "matches", value: "ERROR|FATAL" }
+- If a field path doesn't exist in the payload, the condition evaluates to false (no crash, no error).
+`.trim()
+}