@aaac/observability 0.1.0

package/dist/chunk-FVFGVBXM.js

@@ -0,0 +1,1307 @@
+// src/types/ids.ts
+import { randomBytes } from "crypto";
+function generateId() {
+  const ms = BigInt(Date.now());
+  const buf = randomBytes(16);
+  buf[0] = Number(ms >> 40n & 0xffn);
+  buf[1] = Number(ms >> 32n & 0xffn);
+  buf[2] = Number(ms >> 24n & 0xffn);
+  buf[3] = Number(ms >> 16n & 0xffn);
+  buf[4] = Number(ms >> 8n & 0xffn);
+  buf[5] = Number(ms & 0xffn);
+  buf[6] = buf[6] & 15 | 112;
+  buf[8] = buf[8] & 63 | 128;
+  const hex = buf.toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+function currentTimeUnixNano() {
+  return BigInt(Date.now()) * 1000000n;
+}
+function isoToUnixNano(iso) {
+  const ms = Date.parse(iso);
+  if (Number.isNaN(ms)) {
+    return currentTimeUnixNano();
+  }
+  return BigInt(ms) * 1000000n;
+}
+
+// src/collector/event-collector.ts
+var EventCollector = class {
+  handler;
+  constructor(handler) {
+    this.handler = handler;
+  }
+  /**
+   * In-process observer entry point.
+   * Called by @aaac/runtime (or any in-process producer) with an event payload.
+   */
+  emit(event) {
+    const raw = {
+      ...event,
+      receivedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.handler(raw);
+  }
+  /**
+   * External event registration API.
+   * Called by git hooks, Cursor hooks, CI, or the `aaac-observ record` CLI.
+   * Identical wire format to emit(); separated to aid future routing logic.
+   */
+  registerExternalEvent(event) {
+    const raw = {
+      ...event,
+      receivedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.handler(raw);
+  }
+};
+
+// src/collector/external-registrar.ts
+var DefaultExternalRegistrar = class {
+  constructor(collector) {
+    this.collector = collector;
+  }
+  collector;
+  registerEvent(event) {
+    this.collector.registerExternalEvent(event);
+  }
+};
+
+// src/normalize/validator.ts
+var VALID_LIFECYCLES = /* @__PURE__ */ new Set(["open", "close", "event", "instant"]);
+var NormalizationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NormalizationError";
+  }
+};
+function validateRawEvent(event) {
+  const errors = [];
+  if (!event.source || typeof event.source !== "string") {
+    errors.push("'source' must be a non-empty string");
+  }
+  if (!event.eventType || typeof event.eventType !== "string") {
+    errors.push("'eventType' must be a non-empty string");
+  }
+  if (!event.lifecycle || !VALID_LIFECYCLES.has(event.lifecycle)) {
+    errors.push(
+      `'lifecycle' must be one of: ${[...VALID_LIFECYCLES].join(", ")}`
+    );
+  }
+  if (!event.receivedAt || typeof event.receivedAt !== "string") {
+    errors.push("'receivedAt' must be a non-empty string");
+  }
+  if (event.attributes === null || typeof event.attributes !== "object" || Array.isArray(event.attributes)) {
+    errors.push("'attributes' must be a plain object");
+  }
+  if (errors.length > 0) {
+    throw new NormalizationError(
+      `Invalid RawEvent: ${errors.join("; ")}`
+    );
+  }
+}
+
+// src/normalize/normalizer.ts
+function coerceAttrValue(value) {
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  return String(value);
+}
+function coerceAttributes(raw) {
+  const result = {};
+  for (const [k, v] of Object.entries(raw)) {
+    result[k] = coerceAttrValue(v);
+  }
+  return result;
+}
+var Normalizer = class {
+  /**
+   * Validate and normalise a single RawEvent.
+   * Throws NormalizationError on invalid input.
+   */
+  normalize(raw) {
+    validateRawEvent(raw);
+    const id = generateId();
+    const timeUnixNano = isoToUnixNano(raw.receivedAt);
+    const spanId = raw.spanId ?? generateId();
+    const traceId = generateId();
+    const attributes = coerceAttributes(
+      raw.attributes
+    );
+    const sessionId = extractString(attributes, "session_id");
+    const taskId = extractString(attributes, "task_id");
+    const runId = extractString(attributes, "run_id");
+    return {
+      id,
+      timeUnixNano,
+      source: raw.source,
+      eventType: raw.eventType,
+      lifecycle: raw.lifecycle,
+      traceId,
+      spanId,
+      parentSpanId: raw.parentSpanId,
+      runId,
+      sessionId,
+      taskId,
+      attributes,
+      links: raw.links ?? []
+    };
+  }
+};
+function extractString(attrs, key) {
+  const v = attrs[key];
+  return typeof v === "string" && v.length > 0 ? v : void 0;
+}
+
+// src/correlate/correlator.ts
+var Correlator = class {
+  /** Open spans awaiting a matching 'close' event (keyed by spanId). */
+  openSpans = /* @__PURE__ */ new Map();
+  /** General-purpose short-term key-value cache (architecture.md §8). */
+  cache = /* @__PURE__ */ new Map();
+  /**
+   * Correlate a single CanonicalEvent.
+   *
+   * Mutates the event's traceId if a parent span is found in the open set.
+   * Updates open span state according to the event's lifecycle.
+   *
+   * Returns the (possibly updated) CanonicalEvent.
+   */
+  correlate(event) {
+    let result = { ...event };
+    if (result.parentSpanId !== void 0) {
+      const parentEntry = this.openSpans.get(result.parentSpanId);
+      if (parentEntry !== void 0) {
+        result = { ...result, traceId: parentEntry.event.traceId };
+      }
+    }
+    switch (result.lifecycle) {
+      case "open":
+        this.openSpans.set(result.spanId, { event: result });
+        break;
+      case "close": {
+        this.openSpans.delete(result.spanId);
+        break;
+      }
+      case "event":
+        break;
+      case "instant":
+        break;
+    }
+    return result;
+  }
+  /**
+   * Retrieve the currently-open entry for a span (undefined if not open).
+   * Useful for SqliteSink to look up start_time without a DB round-trip.
+   */
+  getOpenSpan(spanId) {
+    return this.openSpans.get(spanId)?.event;
+  }
+  // ── Generic key-value cache (architecture.md §8) ──────────────────────────
+  /** Store a value under an arbitrary key (TTL not enforced in Phase 0). */
+  cacheSet(key, value) {
+    this.cache.set(key, value);
+  }
+  /** Retrieve a cached value; returns undefined if absent. */
+  cacheGet(key) {
+    return this.cache.get(key);
+  }
+  /** Remove a cached entry. */
+  cacheDel(key) {
+    this.cache.delete(key);
+  }
+  /** Return the number of currently-open spans (useful for testing). */
+  get openSpanCount() {
+    return this.openSpans.size;
+  }
+};
+
+// src/correlate/keys.ts
+var keys = {
+  /** Per-run context: run:{id} */
+  run: (id) => `run:${id}`,
+  /** Latest span in a trace: trace:{id}:latest */
+  traceLatest: (id) => `trace:${id}:latest`,
+  /** Per-session context: session:{id} */
+  session: (id) => `session:${id}`,
+  /** Tool call tracking: toolcall:{id} */
+  toolCall: (id) => `toolcall:${id}`,
+  /** Request tracking: request:{id} */
+  request: (id) => `request:${id}`
+};
+
+// src/enrich/rules/artifact.ts
+function globSegmentToRegex(segment) {
+  return segment.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]");
+}
+function globToRegex(pattern) {
+  if (!pattern.includes("/")) {
+    const base = globSegmentToRegex(pattern);
+    return new RegExp(`(?:^|/)${base}$`);
+  }
+  const parts = pattern.split("**/");
+  let result = "^";
+  for (let i = 0; i < parts.length; i++) {
+    if (i > 0) {
+      result += "(?:.*/)?";
+    }
+    result += globSegmentToRegex(parts[i]);
+  }
+  result += "$";
+  return new RegExp(result);
+}
+function lookupArtifact(filePath, patterns) {
+  let bestArtifactId;
+  let bestLen = -1;
+  for (const entry of patterns) {
+    const rx = globToRegex(entry.pattern);
+    if (rx.test(filePath)) {
+      if (entry.pattern.length > bestLen) {
+        bestLen = entry.pattern.length;
+        bestArtifactId = entry.artifact_id;
+      }
+    }
+  }
+  return bestArtifactId ?? "unknown";
+}
+function createArtifactRule(patterns) {
+  return function artifactRule(event, ctx) {
+    if (event.eventType !== "process.edit" || event.lifecycle !== "instant") {
+      return;
+    }
+    const filePath = event.attributes["edit.path"];
+    if (typeof filePath !== "string" || filePath.length === 0) {
+      return;
+    }
+    const existing = event.attributes["edit.artifact_id"];
+    if (typeof existing === "string" && existing.length > 0 && existing !== "unknown") {
+      return;
+    }
+    const artifactId = ctx.api.lookupArtifact(filePath);
+    event.attributes["edit.artifact_id"] = artifactId;
+    ctx.api.logDebug(
+      `R7: resolved artifact_id=${artifactId} for path=${filePath}`
+    );
+  };
+}
+
+// src/enrich/rules/process.ts
+function activeTasksKey(sessionId) {
+  return `session:${sessionId}:active_tasks`;
+}
+function allTaskSpansKey(sessionId) {
+  return `session:${sessionId}:all_task_spans`;
+}
+function taskFilesKey(sessionId, taskSpanId) {
+  return `session:${sessionId}:task_files:${taskSpanId}`;
+}
+function createProcessRule() {
+  return function processRule(event, ctx) {
+    const sid = event.sessionId;
+    if (event.eventType === "process.task") {
+      if (!sid) return;
+      if (event.lifecycle === "open") {
+        const tasks = ctx.api.cacheGet(activeTasksKey(sid)) ?? [];
+        tasks.push({ spanId: event.spanId, taskId: event.taskId });
+        ctx.api.cacheSet(activeTasksKey(sid), tasks);
+        const allSpans = ctx.api.cacheGet(allTaskSpansKey(sid)) ?? [];
+        if (!allSpans.includes(event.spanId)) {
+          allSpans.push(event.spanId);
+          ctx.api.cacheSet(allTaskSpansKey(sid), allSpans);
+        }
+        ctx.api.cacheSet(taskFilesKey(sid, event.spanId), []);
+        ctx.api.logDebug(
+          `R3/R4: pushed task spanId=${event.spanId} session=${sid}`
+        );
+        return;
+      }
+      if (event.lifecycle === "close") {
+        const tasks = ctx.api.cacheGet(activeTasksKey(sid)) ?? [];
+        const updated = tasks.filter((t) => t.spanId !== event.spanId);
+        ctx.api.cacheSet(activeTasksKey(sid), updated);
+        ctx.api.logDebug(
+          `R3/R4: popped task spanId=${event.spanId} session=${sid}`
+        );
+        return;
+      }
+      return;
+    }
+    if (event.eventType === "process.edit" && event.lifecycle === "instant") {
+      if (event.parentSpanId) return;
+      if (!sid) return;
+      const tasks = ctx.api.cacheGet(activeTasksKey(sid)) ?? [];
+      if (tasks.length === 0) {
+        return;
+      }
+      if (tasks.length === 1) {
+        event.parentSpanId = tasks[0].spanId;
+        event.taskId = tasks[0].taskId;
+        const fp = event.attributes["edit.path"];
+        if (typeof fp === "string" && fp.length > 0) {
+          const files = ctx.api.cacheGet(
+            taskFilesKey(sid, tasks[0].spanId)
+          ) ?? [];
+          if (!files.includes(fp)) {
+            files.push(fp);
+            ctx.api.cacheSet(taskFilesKey(sid, tasks[0].spanId), files);
+          }
+        }
+        ctx.api.logDebug(
+          `R3: resolved parent=${tasks[0].spanId} for process.edit`
+        );
+        return;
+      }
+      const artifactId = event.attributes["edit.artifact_id"];
+      if (typeof artifactId === "string" && artifactId !== "unknown") {
+        const owner = tasks.find(
+          (t) => {
+            const taskArtifact = ctx.api.cacheGet(
+              `session:${sid}:task_artifact:${t.spanId}`
+            );
+            return taskArtifact === artifactId;
+          }
+        );
+        if (owner) {
+          event.parentSpanId = owner.spanId;
+          event.taskId = owner.taskId;
+          const fp = event.attributes["edit.path"];
+          if (typeof fp === "string" && fp.length > 0) {
+            const files = ctx.api.cacheGet(taskFilesKey(sid, owner.spanId)) ?? [];
+            if (!files.includes(fp)) {
+              files.push(fp);
+              ctx.api.cacheSet(taskFilesKey(sid, owner.spanId), files);
+            }
+          }
+          ctx.api.logDebug(
+            `R3: disambiguated parent=${owner.spanId} by artifact=${artifactId}`
+          );
+          return;
+        }
+      }
+      event.attributes["reconcile.status"] = "ambiguous";
+      ctx.api.logDebug(
+        `R3: ambiguous (${tasks.length} active tasks, no unique artifact match)`
+      );
+      return;
+    }
+    if (event.eventType === "process.tool" && event.lifecycle === "instant") {
+      if (event.parentSpanId) return;
+      if (!sid) return;
+      const tasks = ctx.api.cacheGet(activeTasksKey(sid)) ?? [];
+      if (tasks.length === 0) {
+        return;
+      }
+      if (tasks.length === 1) {
+        event.parentSpanId = tasks[0].spanId;
+        event.taskId = tasks[0].taskId;
+        ctx.api.logDebug(
+          `R4: resolved parent=${tasks[0].spanId} for process.tool`
+        );
+        return;
+      }
+      event.attributes["reconcile.status"] = "ambiguous";
+      ctx.api.logDebug(
+        `R4: ambiguous (${tasks.length} active tasks)`
+      );
+    }
+  };
+}
+function recordTaskArtifact(sessionId, taskSpanId, artifactId, cacheSet) {
+  cacheSet(`session:${sessionId}:task_artifact:${taskSpanId}`, artifactId);
+}
+
+// src/enrich/rules/cross-axis.ts
+function createCrossAxisRule() {
+  return function crossAxisRule(event, ctx) {
+    if (event.eventType !== "promotion.commit" || event.lifecycle !== "close") {
+      return;
+    }
+    const sid = event.sessionId;
+    const committedFilesRaw = event.attributes["committed_files"];
+    if (!sid || typeof committedFilesRaw !== "string") {
+      return;
+    }
+    let committedFiles;
+    try {
+      const parsed = JSON.parse(committedFilesRaw);
+      if (!Array.isArray(parsed)) {
+        ctx.api.logDebug(
+          "R5: committed_files is not an array",
+          committedFilesRaw
+        );
+        return;
+      }
+      committedFiles = parsed.filter((x) => typeof x === "string");
+    } catch {
+      ctx.api.logDebug("R5: failed to parse committed_files", committedFilesRaw);
+      return;
+    }
+    if (committedFiles.length === 0) return;
+    const committedSet = new Set(committedFiles);
+    const allTaskSpans = ctx.api.cacheGet(allTaskSpansKey(sid)) ?? [];
+    for (const taskSpanId of allTaskSpans) {
+      const taskFiles = ctx.api.cacheGet(taskFilesKey(sid, taskSpanId)) ?? [];
+      const hasIntersection = taskFiles.some((f) => committedSet.has(f));
+      if (hasIntersection) {
+        ctx.api.addLink({
+          linkType: "materializes_as_commit",
+          targetSpanId: taskSpanId
+        });
+        ctx.api.logDebug(
+          `R5: added materializes_as_commit \u2192 task=${taskSpanId}`
+        );
+      }
+    }
+  };
+}
+
+// src/enrich/rules/promotion.ts
+function changesKey(sessionId, filePath) {
+  return `session:${sessionId}:changes:${filePath}`;
+}
+function createPromotionRule() {
+  return function promotionRule(event, ctx) {
+    if (event.eventType === "promotion.change" && event.lifecycle === "instant") {
+      const sid = event.sessionId;
+      const fp = event.attributes["file.path"];
+      if (!sid || typeof fp !== "string" || fp.length === 0) {
+        return;
+      }
+      const key = changesKey(sid, fp);
+      const existing = ctx.api.cacheGet(key) ?? [];
+      existing.push({ spanId: event.spanId, traceId: event.traceId });
+      ctx.api.cacheSet(key, existing);
+      ctx.api.logDebug(
+        `R1: cached promotion.change spanId=${event.spanId} file=${fp} session=${sid}`
+      );
+      return;
+    }
+    if (event.eventType === "promotion.commit" && event.lifecycle === "close") {
+      const sid = event.sessionId;
+      const committedFilesRaw = event.attributes["committed_files"];
+      if (!sid || typeof committedFilesRaw !== "string") {
+        return;
+      }
+      let committedFiles;
+      try {
+        const parsed = JSON.parse(committedFilesRaw);
+        if (!Array.isArray(parsed)) {
+          ctx.api.logDebug("R1/R2: committed_files is not an array", committedFilesRaw);
+          return;
+        }
+        committedFiles = parsed.filter((x) => typeof x === "string");
+      } catch {
+        ctx.api.logDebug("R1/R2: failed to parse committed_files", committedFilesRaw);
+        return;
+      }
+      const commitSpanId = event.spanId;
+      const commitTraceId = event.traceId;
+      for (const fp of committedFiles) {
+        const cacheKey = changesKey(sid, fp);
+        const changeRefs = ctx.api.cacheGet(cacheKey) ?? [];
+        const links = changeRefs.map((ref) => ({
+          linkType: "contains_change",
+          targetSpanId: ref.spanId,
+          // Omit targetTraceId if same trace as the commit (most common case)
+          targetTraceId: ref.traceId !== commitTraceId ? ref.traceId : void 0
+        }));
+        const fileEvent = {
+          id: generateId(),
+          timeUnixNano: ctx.api.nowUnixNano(),
+          source: "enricher",
+          eventType: "promotion.file",
+          lifecycle: "instant",
+          traceId: commitTraceId,
+          spanId: generateId(),
+          parentSpanId: commitSpanId,
+          // R2: parent = commit
+          sessionId: sid,
+          runId: event.runId,
+          taskId: event.taskId,
+          attributes: {
+            "file.path": fp,
+            "commit.span_id": commitSpanId
+          },
+          links
+          // R1: contains_change links
+        };
+        ctx.api.emitRecord(fileEvent);
+        ctx.api.logDebug(
+          `R2: emitted promotion.file file=${fp} commit=${commitSpanId} changes=${links.length}`
+        );
+        ctx.api.cacheSet(cacheKey, []);
+      }
+    }
+  };
+}
+
+// src/enrich/enricher.ts
+var Enricher = class {
+  correlator;
+  artifactPatterns;
+  rules;
+  /**
+   * @param options  Correlator + optional artifact patterns
+   * @param rules    Enrichment rules to apply in order.
+   *                 Use createDefaultRules() for the standard Phase 5 rule set.
+   */
+  constructor(options, rules) {
+    this.correlator = options.correlator;
+    this.artifactPatterns = options.artifactPatterns ?? [];
+    this.rules = rules;
+  }
+  /**
+   * Enrich a single CanonicalEvent.
+   *
+   * Returns a shallow copy of the event (with mutated fields from rules) and
+   * a list of derived events queued by api.emitRecord().
+   *
+   * fail-open: each rule runs in a try/catch; a throwing rule logs to stderr
+   * and does NOT prevent the event from reaching the sinks.
+   */
+  enrich(event) {
+    const mutableEvent = {
+      ...event,
+      attributes: { ...event.attributes },
+      links: [...event.links]
+    };
+    const derived = [];
+    const patterns = this.artifactPatterns;
+    const correlator = this.correlator;
+    const api = {
+      cacheGet: (k) => correlator.cacheGet(k),
+      cacheSet: (k, v) => correlator.cacheSet(k, v),
+      emitRecord: (e) => derived.push(e),
+      addLink: (link) => mutableEvent.links.push(link),
+      lookupArtifact: (path) => lookupArtifact(path, patterns),
+      logDebug: (msg, data) => {
+        if (data !== void 0) {
+          console.debug(`[Enricher] ${msg}`, data);
+        } else {
+          console.debug(`[Enricher] ${msg}`);
+        }
+      },
+      nowUnixNano: () => currentTimeUnixNano()
+    };
+    const ctx = { event: mutableEvent, api };
+    for (const rule of this.rules) {
+      try {
+        rule(mutableEvent, ctx);
+      } catch (err) {
+        console.error("[Enricher] rule threw (fail-open):", err);
+      }
+    }
+    return { enriched: mutableEvent, derived };
+  }
+};
+function createDefaultRules(artifactPatterns = []) {
+  return [
+    createArtifactRule(artifactPatterns),
+    // R7
+    createProcessRule(),
+    // R3/R4
+    createCrossAxisRule(),
+    // R5
+    createPromotionRule()
+    // R1/R2
+  ];
+}
+
+// src/sink/sqlite-sink.ts
+import { DatabaseSync } from "node:sqlite";
+import { mkdirSync } from "fs";
+import { dirname, resolve } from "path";
+var DEFAULT_DB_PATH = ".agent-logs/observability.db";
+var SCHEMA = `
+CREATE TABLE IF NOT EXISTS canonical_events (
+  id             TEXT    PRIMARY KEY,
+  time_unix_nano INTEGER NOT NULL,
+  source         TEXT    NOT NULL,
+  event_type     TEXT    NOT NULL,
+  lifecycle      TEXT    NOT NULL,
+  trace_id       TEXT,
+  span_id        TEXT    NOT NULL,
+  parent_span_id TEXT,
+  run_id         TEXT,
+  session_id     TEXT,
+  task_id        TEXT,
+  attributes     TEXT    NOT NULL DEFAULT '{}'
+);
+
+CREATE INDEX IF NOT EXISTS idx_ce_trace_id   ON canonical_events (trace_id);
+CREATE INDEX IF NOT EXISTS idx_ce_span_id    ON canonical_events (span_id);
+CREATE INDEX IF NOT EXISTS idx_ce_event_type ON canonical_events (event_type);
+CREATE INDEX IF NOT EXISTS idx_ce_session_id ON canonical_events (session_id);
+CREATE INDEX IF NOT EXISTS idx_ce_time       ON canonical_events (time_unix_nano);
+
+CREATE TABLE IF NOT EXISTS spans (
+  span_id        TEXT    PRIMARY KEY,
+  trace_id       TEXT,
+  parent_span_id TEXT,
+  event_type     TEXT    NOT NULL,
+  start_time     INTEGER,
+  end_time       INTEGER,
+  duration_ns    INTEGER,
+  status         TEXT    NOT NULL DEFAULT 'open',
+  run_id         TEXT,
+  session_id     TEXT,
+  task_id        TEXT,
+  attributes     TEXT    NOT NULL DEFAULT '{}'
+);
+
+CREATE INDEX IF NOT EXISTS idx_spans_trace_id   ON spans (trace_id);
+CREATE INDEX IF NOT EXISTS idx_spans_parent     ON spans (parent_span_id);
+CREATE INDEX IF NOT EXISTS idx_spans_event_type ON spans (event_type);
+CREATE INDEX IF NOT EXISTS idx_spans_session_id ON spans (session_id);
+CREATE INDEX IF NOT EXISTS idx_spans_task_id    ON spans (task_id);
+CREATE INDEX IF NOT EXISTS idx_spans_status     ON spans (status);
+
+CREATE TABLE IF NOT EXISTS canonical_links (
+  id              TEXT PRIMARY KEY,
+  source_event_id TEXT NOT NULL,
+  source_span_id  TEXT NOT NULL,
+  target_span_id  TEXT NOT NULL,
+  target_trace_id TEXT,
+  link_type       TEXT NOT NULL,
+  attributes      TEXT NOT NULL DEFAULT '{}'
+);
+
+CREATE INDEX IF NOT EXISTS idx_links_source ON canonical_links (source_span_id);
+CREATE INDEX IF NOT EXISTS idx_links_target ON canonical_links (target_span_id);
+CREATE INDEX IF NOT EXISTS idx_links_type   ON canonical_links (link_type);
+`;
+var SqliteSink = class {
+  db;
+  constructor(dbPath = DEFAULT_DB_PATH) {
+    if (dbPath !== ":memory:") {
+      const abs = resolve(dbPath);
+      mkdirSync(dirname(abs), { recursive: true });
+      this.db = new DatabaseSync(abs);
+    } else {
+      this.db = new DatabaseSync(":memory:");
+    }
+    this.db.exec(SCHEMA);
+  }
+  // ── Public write API ───────────────────────────────────────────────────────
+  /**
+   * Persist a single CanonicalEvent.
+   *  1. Append to canonical_events (immutable)
+   *  2. Upsert spans materialised view
+   *  3. Insert canonical_links rows
+   */
+  write(event) {
+    this.insertCanonicalEvent(event);
+    this.upsertSpan(event);
+    if (event.links.length > 0) {
+      this.insertLinks(event);
+    }
+  }
+  /** Close the database connection. */
+  close() {
+    this.db.close();
+  }
+  /**
+   * Expose the underlying DatabaseSync for testing / read-path adapters.
+   * Should not be used in production write paths.
+   */
+  getDb() {
+    return this.db;
+  }
+  // ── Private helpers ────────────────────────────────────────────────────────
+  insertCanonicalEvent(event) {
+    const stmt = this.db.prepare(`
+      INSERT INTO canonical_events
+        (id, time_unix_nano, source, event_type, lifecycle,
+         trace_id, span_id, parent_span_id, run_id, session_id, task_id, attributes)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    stmt.run(
+      event.id,
+      event.timeUnixNano,
+      event.source,
+      event.eventType,
+      event.lifecycle,
+      event.traceId ?? null,
+      event.spanId,
+      event.parentSpanId ?? null,
+      event.runId ?? null,
+      event.sessionId ?? null,
+      event.taskId ?? null,
+      JSON.stringify(event.attributes)
+    );
+  }
+  upsertSpan(event) {
+    switch (event.lifecycle) {
+      case "open":
+        this.db.prepare(`
+            INSERT INTO spans
+              (span_id, trace_id, parent_span_id, event_type, start_time,
+               status, run_id, session_id, task_id, attributes)
+            VALUES (?, ?, ?, ?, ?, 'open', ?, ?, ?, ?)
+          `).run(
+          event.spanId,
+          event.traceId ?? null,
+          event.parentSpanId ?? null,
+          event.eventType,
+          event.timeUnixNano,
+          event.runId ?? null,
+          event.sessionId ?? null,
+          event.taskId ?? null,
+          JSON.stringify(event.attributes)
+        );
+        break;
+      case "close":
+        this.db.prepare(`
+            UPDATE spans
+            SET end_time    = ?,
+                duration_ns = (? - start_time),
+                status      = 'closed'
+            WHERE span_id = ?
+          `).run(event.timeUnixNano, event.timeUnixNano, event.spanId);
+        break;
+      case "instant":
+        this.db.prepare(`
+            INSERT OR IGNORE INTO spans
+              (span_id, trace_id, parent_span_id, event_type,
+               start_time, end_time, duration_ns, status,
+               run_id, session_id, task_id, attributes)
+            VALUES (?, ?, ?, ?, ?, ?, 0, 'instant', ?, ?, ?, ?)
+          `).run(
+          event.spanId,
+          event.traceId ?? null,
+          event.parentSpanId ?? null,
+          event.eventType,
+          event.timeUnixNano,
+          event.timeUnixNano,
+          event.runId ?? null,
+          event.sessionId ?? null,
+          event.taskId ?? null,
+          JSON.stringify(event.attributes)
+        );
+        break;
+      case "event":
+        break;
+    }
+  }
+  insertLinks(event) {
+    const stmt = this.db.prepare(`
+      INSERT INTO canonical_links
+        (id, source_event_id, source_span_id, target_span_id, target_trace_id, link_type, attributes)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+    for (const link of event.links) {
+      stmt.run(
+        generateId(),
+        event.id,
+        event.spanId,
+        link.targetSpanId,
+        link.targetTraceId ?? null,
+        link.linkType,
+        JSON.stringify(link.attributes ?? {})
+      );
+    }
+  }
+};
+
+// src/otel/otel-emitter.ts
+import { BasicTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { trace, SpanKind, SpanStatusCode, ROOT_CONTEXT } from "@opentelemetry/api";
+var OtelEmitter = class {
+  provider;
+  tracer;
+  enabled;
+  constructor(options = {}) {
+    const endpoint = options.endpoint ?? process.env["OTEL_EXPORTER_OTLP_ENDPOINT"];
+    if (!endpoint) {
+      this.provider = null;
+      this.tracer = null;
+      this.enabled = false;
+      return;
+    }
+    const serviceName = options.serviceName ?? "@aaac/observability";
+    const exporter = new OTLPTraceExporter({ url: `${endpoint}/v1/traces` });
+    const processor = new BatchSpanProcessor(exporter);
+    this.provider = new BasicTracerProvider({
+      resource: {
+        attributes: { "service.name": serviceName }
+      },
+      spanProcessors: [processor]
+    });
+    trace.setGlobalTracerProvider(this.provider);
+    this.tracer = this.provider.getTracer("@aaac/observability", "0.1.0");
+    this.enabled = true;
+  }
+  /**
+   * Emit a single MappedSpan to the configured OTLP backend.
+   *
+   * fail-open: any error is caught, logged to stderr, and swallowed.
+   * This method never throws into the caller.
+   */
+  emit(span) {
+    if (!this.enabled || this.tracer === null) return;
+    try {
+      this._emitSpan(span);
+    } catch (err) {
+      console.error("[OtelEmitter] emit error (swallowed):", err);
+    }
+  }
+  /**
+   * Emit a batch of MappedSpans.
+   * Each span is emitted independently; one failure does not block others.
+   */
+  emitBatch(spans) {
+    for (const span of spans) {
+      this.emit(span);
+    }
+  }
+  /**
+   * Flush pending spans and shut down the OTEL provider.
+   * Returns a promise that resolves when the flush is complete (or on error).
+   */
+  async shutdown() {
+    if (this.provider === null) return;
+    try {
+      await this.provider.shutdown();
+    } catch (err) {
+      console.error("[OtelEmitter] shutdown error (swallowed):", err);
+    }
+  }
+  // ── Private helpers ────────────────────────────────────────────────────────
+  _emitSpan(mapped) {
+    if (this.tracer === null) return;
+    const parentCtx = mapped.parentSpanId ? this._buildParentContext(mapped.traceId, mapped.parentSpanId) : ROOT_CONTEXT;
+    const startMs = Number(mapped.startTimeUnixNano / 1000000n);
+    const endMs = Number(mapped.endTimeUnixNano / 1000000n);
+    const otelSpan = this.tracer.startSpan(
+      mapped.name,
+      {
+        kind: SpanKind.INTERNAL,
+        startTime: startMs,
+        attributes: convertAttributes(mapped.attributes),
+        links: mapped.links.map((l) => ({
+          context: {
+            traceId: l.targetTraceId ?? mapped.traceId,
+            spanId: l.targetSpanId,
+            traceFlags: 1
+          },
+          attributes: l.attributes
+        }))
+      },
+      parentCtx
+    );
+    for (const ev of mapped.spanEvents) {
+      otelSpan.addEvent(
+        ev.name,
+        convertAttributes(ev.attributes),
+        Number(ev.timeUnixNano / 1000000n)
+      );
+    }
+    otelSpan.setStatus({ code: SpanStatusCode.OK });
+    otelSpan.end(endMs);
+  }
+  _buildParentContext(traceId, spanId) {
+    const spanContext = {
+      traceId,
+      spanId,
+      traceFlags: 1,
+      // SAMPLED
+      isRemote: false
+    };
+    return trace.setSpanContext(ROOT_CONTEXT, spanContext);
+  }
+};
+function convertAttributes(attrs) {
+  return attrs;
+}
+
+// src/otel/span-mapper.ts
+function mapEventsToSpan(events) {
+  if (events.length === 0) return void 0;
+  const sorted = [...events].sort(
+    (a, b) => a.timeUnixNano < b.timeUnixNano ? -1 : a.timeUnixNano > b.timeUnixNano ? 1 : 0
+  );
+  const first = sorted[0];
+  const spanId = first.spanId;
+  const traceId = first.traceId;
+  const parentSpanId = first.parentSpanId;
+  const name = first.eventType;
+  let startTimeUnixNano;
+  let endTimeUnixNano;
+  const spanEvents = [];
+  let mergedAttributes = {};
+  const allLinks = [];
+  for (const ev of sorted) {
+    switch (ev.lifecycle) {
+      case "open":
+        startTimeUnixNano = ev.timeUnixNano;
+        mergedAttributes = { ...mergedAttributes, ...ev.attributes };
+        break;
+      case "close":
+        endTimeUnixNano = ev.timeUnixNano;
+        mergedAttributes = { ...mergedAttributes, ...ev.attributes };
+        break;
+      case "event":
+        spanEvents.push({
+          name: ev.eventType,
+          timeUnixNano: ev.timeUnixNano,
+          attributes: ev.attributes
+        });
+        mergedAttributes = { ...mergedAttributes, ...ev.attributes };
+        break;
+      case "instant":
+        startTimeUnixNano = ev.timeUnixNano;
+        endTimeUnixNano = ev.timeUnixNano;
+        mergedAttributes = { ...mergedAttributes, ...ev.attributes };
+        break;
+    }
+    allLinks.push(...ev.links);
+  }
+  if (startTimeUnixNano === void 0) {
+    startTimeUnixNano = first.timeUnixNano;
+  }
+  if (endTimeUnixNano === void 0) {
+    endTimeUnixNano = startTimeUnixNano;
+  }
+  const links = allLinks.map((l) => ({
+    targetSpanId: l.targetSpanId,
+    targetTraceId: l.targetTraceId,
+    attributes: {
+      link_type: l.linkType,
+      ...l.attributes ?? {}
+    }
+  }));
+  return {
+    spanId,
+    traceId,
+    parentSpanId,
+    name,
+    startTimeUnixNano,
+    endTimeUnixNano,
+    attributes: mergedAttributes,
+    spanEvents,
+    links
+  };
+}
+function mapAllEventsToSpans(events) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const ev of events) {
+    const group = groups.get(ev.spanId);
+    if (group !== void 0) {
+      group.push(ev);
+    } else {
+      groups.set(ev.spanId, [ev]);
+    }
+  }
+  const spans = [];
+  for (const group of groups.values()) {
+    const mapped = mapEventsToSpan(group);
+    if (mapped !== void 0) {
+      spans.push(mapped);
+    }
+  }
+  return spans;
+}
+
+// src/query/sqlite-adapter.ts
+import { DatabaseSync as DatabaseSync2 } from "node:sqlite";
+import { mkdirSync as mkdirSync2 } from "fs";
+import { dirname as dirname2, resolve as resolve2 } from "path";
+var SqliteQueryAdapter = class {
+  db;
+  ownsDb;
+  /**
+   * @param dbPathOrDb Either a file path string (opens a new connection) or
+   *                   an existing DatabaseSync instance (shared connection,
+   *                   e.g. from SqliteSink.getDb() in tests).
+   */
+  constructor(dbPathOrDb = DEFAULT_DB_PATH) {
+    if (typeof dbPathOrDb === "string") {
+      if (dbPathOrDb !== ":memory:") {
+        const abs = resolve2(dbPathOrDb);
+        mkdirSync2(dirname2(abs), { recursive: true });
+        this.db = new DatabaseSync2(abs);
+      } else {
+        this.db = new DatabaseSync2(":memory:");
+      }
+      this.ownsDb = true;
+    } else {
+      this.db = dbPathOrDb;
+      this.ownsDb = false;
+    }
+  }
+  // ── Span-level queries ─────────────────────────────────────────────────────
+  querySpans(filter) {
+    const { clauses, params } = buildSpanFilter(filter);
+    const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+    const limit = filter.limit !== void 0 ? `LIMIT ${Number(filter.limit)}` : "";
+    const sql = `SELECT * FROM spans ${where} ORDER BY start_time ASC ${limit}`;
+    const stmt = this.db.prepare(sql);
+    stmt.setReadBigInts(true);
+    const rows = stmt.all(...params);
+    return rows.map(parseSpanRow);
+  }
+  getSpan(spanId) {
+    const stmt = this.db.prepare("SELECT * FROM spans WHERE span_id = ?");
+    stmt.setReadBigInts(true);
+    const row = stmt.get(spanId);
+    return row !== void 0 ? parseSpanRow(row) : void 0;
+  }
+  getTrace(traceId) {
+    const stmt = this.db.prepare(
+      "SELECT * FROM spans WHERE trace_id = ? ORDER BY start_time ASC"
+    );
+    stmt.setReadBigInts(true);
+    const rows = stmt.all(traceId);
+    return rows.map(parseSpanRow);
+  }
+  // ── Event-level queries ────────────────────────────────────────────────────
+  queryEvents(filter) {
+    const { clauses, params } = buildEventFilter(filter);
+    const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+    const limit = filter.limit !== void 0 ? `LIMIT ${Number(filter.limit)}` : "";
+    const sql = `SELECT * FROM canonical_events ${where} ORDER BY time_unix_nano ASC ${limit}`;
+    const stmt = this.db.prepare(sql);
+    stmt.setReadBigInts(true);
+    const rows = stmt.all(...params);
+    return rows.map(parseEventRow);
+  }
+  getSpanEvents(spanId) {
+    const stmt = this.db.prepare(
+      "SELECT * FROM canonical_events WHERE span_id = ? ORDER BY time_unix_nano ASC"
+    );
+    stmt.setReadBigInts(true);
+    const rows = stmt.all(spanId);
+    return rows.map(parseEventRow);
+  }
+  // ── Link traversal ─────────────────────────────────────────────────────────
+  getLinks(spanId, direction = "forward") {
+    const rawRows = [];
+    if (direction === "forward" || direction === "both") {
+      const stmt = this.db.prepare(
+        "SELECT * FROM canonical_links WHERE source_span_id = ?"
+      );
+      rawRows.push(...stmt.all(spanId));
+    }
+    if (direction === "reverse" || direction === "both") {
+      const stmt = this.db.prepare(
+        "SELECT * FROM canonical_links WHERE target_span_id = ?"
+      );
+      rawRows.push(...stmt.all(spanId));
+    }
+    if (direction === "both") {
+      const seen = /* @__PURE__ */ new Set();
+      return rawRows.filter((r) => {
+        if (seen.has(r.id)) return false;
+        seen.add(r.id);
+        return true;
+      }).map(parseLinkRow);
+    }
+    return rawRows.map(parseLinkRow);
+  }
+  getLinksByType(linkType) {
+    const stmt = this.db.prepare(
+      "SELECT * FROM canonical_links WHERE link_type = ?"
+    );
+    const rows = stmt.all(linkType);
+    return rows.map(parseLinkRow);
+  }
+  // ── Lifecycle ──────────────────────────────────────────────────────────────
+  close() {
+    if (this.ownsDb) {
+      this.db.close();
+    }
+  }
+};
+function parseSpanRow(row) {
+  return {
+    spanId: row.span_id,
+    traceId: row.trace_id,
+    parentSpanId: row.parent_span_id,
+    eventType: row.event_type,
+    startTime: row.start_time,
+    endTime: row.end_time,
+    durationNs: row.duration_ns,
+    status: row.status,
+    runId: row.run_id,
+    sessionId: row.session_id,
+    taskId: row.task_id,
+    attributes: safeParseJson(row.attributes)
+  };
+}
+function parseEventRow(row) {
+  return {
+    id: row.id,
+    timeUnixNano: row.time_unix_nano,
+    source: row.source,
+    eventType: row.event_type,
+    lifecycle: row.lifecycle,
+    traceId: row.trace_id ?? "",
+    spanId: row.span_id,
+    parentSpanId: row.parent_span_id ?? void 0,
+    runId: row.run_id ?? void 0,
+    sessionId: row.session_id ?? void 0,
+    taskId: row.task_id ?? void 0,
+    attributes: safeParseJson(row.attributes),
+    links: []
+    // links are stored in canonical_links, not inline on events
+  };
+}
+function parseLinkRow(row) {
+  return {
+    id: row.id,
+    sourceEventId: row.source_event_id,
+    sourceSpanId: row.source_span_id,
+    targetSpanId: row.target_span_id,
+    targetTraceId: row.target_trace_id,
+    linkType: row.link_type,
+    attributes: safeParseJson(row.attributes)
+  };
+}
+function safeParseJson(json) {
+  try {
+    return JSON.parse(json);
+  } catch {
+    return {};
+  }
+}
+function buildSpanFilter(filter) {
+  const clauses = [];
+  const params = [];
+  if (filter.traceId !== void 0) {
+    clauses.push("trace_id = ?");
+    params.push(filter.traceId);
+  }
+  if (filter.spanId !== void 0) {
+    clauses.push("span_id = ?");
+    params.push(filter.spanId);
+  }
+  if (filter.eventType !== void 0) {
+    clauses.push("event_type = ?");
+    params.push(filter.eventType);
+  }
+  if (filter.taskId !== void 0) {
+    clauses.push("task_id = ?");
+    params.push(filter.taskId);
+  }
+  if (filter.fromTimeUnixNano !== void 0) {
+    clauses.push("start_time >= ?");
+    params.push(filter.fromTimeUnixNano);
+  }
+  if (filter.toTimeUnixNano !== void 0) {
+    clauses.push("start_time <= ?");
+    params.push(filter.toTimeUnixNano);
+  }
+  return { clauses, params };
+}
+function buildEventFilter(filter) {
+  const clauses = [];
+  const params = [];
+  if (filter.traceId !== void 0) {
+    clauses.push("trace_id = ?");
+    params.push(filter.traceId);
+  }
+  if (filter.spanId !== void 0) {
+    clauses.push("span_id = ?");
+    params.push(filter.spanId);
+  }
+  if (filter.eventType !== void 0) {
+    clauses.push("event_type = ?");
+    params.push(filter.eventType);
+  }
+  if (filter.taskId !== void 0) {
+    clauses.push("task_id = ?");
+    params.push(filter.taskId);
+  }
+  if (filter.fromTimeUnixNano !== void 0) {
+    clauses.push("time_unix_nano >= ?");
+    params.push(filter.fromTimeUnixNano);
+  }
+  if (filter.toTimeUnixNano !== void 0) {
+    clauses.push("time_unix_nano <= ?");
+    params.push(filter.toTimeUnixNano);
+  }
+  return { clauses, params };
+}
+
+// src/index.ts
+function createPipeline(options = {}) {
+  const {
+    dbPath = DEFAULT_DB_PATH,
+    afterCorrelate,
+    otel,
+    artifactPatterns = [],
+    enrichRules
+  } = options;
+  const sink = new SqliteSink(dbPath);
+  const correlator = new Correlator();
+  const normalizer = new Normalizer();
+  const otelEmitter = new OtelEmitter(otel ?? {});
+  const rules = enrichRules ?? createDefaultRules(artifactPatterns);
+  const enricher = new Enricher({ correlator, artifactPatterns }, rules);
+  function sinkEvent(event) {
+    sink.write(event);
+    otelEmitter.emit({
+      spanId: event.spanId,
+      traceId: event.traceId,
+      parentSpanId: event.parentSpanId,
+      name: event.eventType,
+      startTimeUnixNano: event.timeUnixNano,
+      endTimeUnixNano: event.timeUnixNano,
+      attributes: event.attributes,
+      spanEvents: [],
+      links: event.links.map((l) => ({
+        targetSpanId: l.targetSpanId,
+        targetTraceId: l.targetTraceId,
+        attributes: { link_type: l.linkType, ...l.attributes ?? {} }
+      }))
+    });
+  }
+  const collector = new EventCollector((raw) => {
+    const canonical = normalizer.normalize(raw);
+    let correlated = correlator.correlate(canonical);
+    if (afterCorrelate) {
+      correlated = afterCorrelate(correlated);
+    }
+    const { enriched, derived } = enricher.enrich(correlated);
+    sinkEvent(enriched);
+    for (const d of derived) {
+      sinkEvent(d);
+    }
+  });
+  return { collector, correlator, sink, otelEmitter, enricher };
+}
+
+export {
+  generateId,
+  currentTimeUnixNano,
+  isoToUnixNano,
+  EventCollector,
+  DefaultExternalRegistrar,
+  NormalizationError,
+  validateRawEvent,
+  Normalizer,
+  Correlator,
+  keys,
+  globToRegex,
+  lookupArtifact,
+  createArtifactRule,
+  activeTasksKey,
+  allTaskSpansKey,
+  taskFilesKey,
+  createProcessRule,
+  recordTaskArtifact,
+  createCrossAxisRule,
+  createPromotionRule,
+  Enricher,
+  createDefaultRules,
+  DEFAULT_DB_PATH,
+  SqliteSink,
+  OtelEmitter,
+  mapEventsToSpan,
+  mapAllEventsToSpans,
+  SqliteQueryAdapter,
+  createPipeline
+};
+//# sourceMappingURL=chunk-FVFGVBXM.js.map