@aaac/observability 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,959 @@
+import { DatabaseSync } from 'node:sqlite';
+
+/**
+ * Canonical event types — single source of truth for @aaac/observability.
+ * Matches event-catalog.md §1 exactly.
+ */
+/** Primitive attribute value type accepted by all event fields. */
+type AttrValue = string | number | boolean;
+/** Span lifecycle semantics (event-catalog.md §1.3). */
+type Lifecycle = "open" | "close" | "event" | "instant";
+/**
+ * Cross-axis link to another span (event-catalog.md §1.2, §2.7).
+ * link_type is supplied by event_mapping — not hardcoded here.
+ */
+interface CanonicalLink {
+    /** Semantic relationship type, e.g. 'executes', 'produces_change'. */
+    linkType: string;
+    /** spanId of the target span. */
+    targetSpanId: string;
+    /** traceId of the target span (if in a different trace). */
+    targetTraceId?: string;
+    /** Optional link-level attributes. */
+    attributes?: Record<string, string>;
+}
+/**
+ * Raw event — input to the pipeline from observer.emit() or registerExternalEvent().
+ * event-catalog.md §1.1
+ */
+interface RawEvent {
+    /** Origin of the event: 'aaac-runtime' | 'git-hook' | 'cursor-hook' | 'ci' */
+    source: string;
+    /** ISO-8601 wall-clock time when this package received the event. */
+    receivedAt: string;
+    /** Span name following {axis}.{name} convention (event-catalog.md §2). */
+    eventType: string;
+    /** Lifecycle position of this event within its span. */
+    lifecycle: Lifecycle;
+    /** Caller-assigned span identifier. Generated if absent. */
+    spanId?: string;
+    /** Parent span's spanId for hierarchical correlation. */
+    parentSpanId?: string;
+    /** Arbitrary key-value attributes attached to this event. */
+    attributes: Record<string, AttrValue>;
+    /** Cross-axis links declared at emit time. */
+    links?: CanonicalLink[];
+}
+/**
+ * Normalised internal representation — the pipeline's primary data type.
+ * Same spanId group forms a logical Span; parentSpanId points to the parent span.
+ * event-catalog.md §1.2
+ */
+interface CanonicalEvent {
+    /** Unique event identifier (UUIDv7). */
+    id: string;
+    /** Unix timestamp in nanoseconds (BigInt). */
+    timeUnixNano: bigint;
+    /** Origin of the event. */
+    source: string;
+    /** Span name, e.g. 'agent.session'. */
+    eventType: string;
+    /** Lifecycle position of this event. */
+    lifecycle: Lifecycle;
+    /** Trace identifier shared by all spans in the same trace. */
+    traceId: string;
+    /** Span identifier. Multiple events with the same spanId form one logical span. */
+    spanId: string;
+    /** Parent span's spanId, if any. */
+    parentSpanId?: string;
+    /** ExecutionEnvelope.run_id (event-catalog.md §1.5). */
+    runId?: string;
+    /** Extracted from attributes.session_id. */
+    sessionId?: string;
+    /** Extracted from attributes.task_id. */
+    taskId?: string;
+    /** Arbitrary key-value attributes. */
+    attributes: Record<string, AttrValue>;
+    /** Cross-axis links (first-class; maps to OTEL SpanLinks). */
+    links: CanonicalLink[];
+}
+/**
+ * Query return type — hides storage-backend differences (event-catalog.md §1.4).
+ * Core fields are identical to CanonicalEvent.
+ */
+type StoredEvent = CanonicalEvent;
+
+/**
+ * ExecutionEnvelope — agent-axis primary source from @aaac/runtime.
+ * event-catalog.md §1.5; shared with @aaac/runtime (Phase 1).
+ *
+ * All fields except run_id and timestamp are optional — runtime attaches
+ * whatever context is available at the time of execution.
+ */
+interface ExecutionEnvelope {
+    /** UUIDv7 identifying this execution run. Maps to CanonicalEvent.runId. */
+    run_id: string;
+    /** Identifies the task instance within the run. */
+    task_instance_id?: string;
+    /** Component identifier from the agent-contracts definition. */
+    component_id?: string;
+    /** Agent that issued this execution (handoff source). */
+    from_agent?: string;
+    /** Agent that receives this execution (handoff target). */
+    to_agent?: string;
+    /** agent-contracts schema version used for this execution. */
+    contract_version?: string;
+    /** LLM adapter identifier (e.g. 'claude-agent-sdk', 'openai-agents-sdk'). */
+    adapter?: string;
+    /** LLM model identifier (e.g. 'claude-opus-4-5'). */
+    model?: string;
+    /** ISO-8601 timestamp of execution start. */
+    timestamp: string;
+    /** run_id of the parent execution (for subagent / handoff correlation). */
+    parent_run_id?: string;
+    /**
+     * Free-form metadata collected during execution:
+     * duration_ms, token_usage, cost_usd, hashes, etc.
+     */
+    execution_metadata?: Record<string, unknown>;
+}
+
+/**
+ * Generate a UUIDv7 string.
+ * Monotonically ordered by creation time at millisecond granularity.
+ */
+declare function generateId(): string;
+/**
+ * Current wall-clock time as Unix nanoseconds (BigInt).
+ * Resolution is millisecond (Date.now() × 1_000_000).
+ */
+declare function currentTimeUnixNano(): bigint;
+/**
+ * Convert an ISO-8601 / RFC-3339 string to Unix nanoseconds (BigInt).
+ * Falls back to current time if the string cannot be parsed.
+ */
+declare function isoToUnixNano(iso: string): bigint;
+
+/**
+ * EventCollector — in-process entry point for the write pipeline.
+ *
+ * Responsibilities:
+ *  - Accept events from @aaac/runtime via emit() (in-process observer)
+ *  - Accept events from external sources (git-hook, ci, …) via registerExternalEvent()
+ *  - Wrap them as RawEvent with a receivedAt timestamp and forward to the downstream handler
+ *
+ * The downstream handler (pipeline) is injected via the constructor so that the
+ * collector stays decoupled from normalizer / correlator / sink.
+ */
+
+/** Minimal shape expected by both emit() and registerExternalEvent(). */
+interface EmitInput {
+    source: string;
+    eventType: string;
+    lifecycle: Lifecycle;
+    spanId?: string;
+    parentSpanId?: string;
+    attributes: Record<string, AttrValue>;
+    links?: CanonicalLink[];
+}
+/** Callback that receives each RawEvent produced by the collector. */
+type RawEventHandler = (event: RawEvent) => void;
+/**
+ * EventCollector wraps an injected pipeline handler and stamps each incoming
+ * event with a receivedAt timestamp before forwarding.
+ */
+declare class EventCollector {
+    private readonly handler;
+    constructor(handler: RawEventHandler);
+    /**
+     * In-process observer entry point.
+     * Called by @aaac/runtime (or any in-process producer) with an event payload.
+     */
+    emit(event: EmitInput): void;
+    /**
+     * 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: EmitInput): void;
+}
+
+/**
+ * ExternalEventRegistrar — thin facade implementing the external event
+ * registration contract from architecture.md §9.
+ *
+ * External processes (git hooks, Cursor hooks, CI) call registerEvent() to
+ * inject events into the same write pipeline as in-process events.
+ */
+
+/** Typed input for external event sources (architecture.md §9). */
+interface RawExternalEvent {
+    /** Event origin: 'git-hook' | 'cursor-hook' | 'ci' | ... */
+    source: string;
+    eventType: string;
+    lifecycle: Lifecycle;
+    spanId?: string;
+    parentSpanId?: string;
+    attributes: Record<string, AttrValue>;
+    links?: CanonicalLink[];
+}
+/** Interface contract for external event registration (architecture.md §9). */
+interface ExternalEventRegistrar {
+    registerEvent(event: RawExternalEvent): void;
+}
+/**
+ * Default implementation — delegates to EventCollector.registerExternalEvent().
+ */
+declare class DefaultExternalRegistrar implements ExternalEventRegistrar {
+    private readonly collector;
+    constructor(collector: EventCollector);
+    registerEvent(event: RawExternalEvent): void;
+}
+
+/**
+ * Normalizer — converts RawEvent → CanonicalEvent.
+ *
+ * Responsibilities (architecture.md §4.1 / §3):
+ *  - Required-key validation (delegated to validator.ts)
+ *  - Type coercion: attribute values are coerced to AttrValue
+ *  - Default values: id, timeUnixNano, spanId, traceId are generated if absent
+ *  - Link declaration conversion: RawEvent.links → CanonicalEvent.links
+ *  - Extraction of well-known scalar fields: sessionId, taskId, runId
+ *
+ * traceId *propagation* (child → parent) is the Correlator's responsibility;
+ * the Normalizer only generates a fresh traceId as the default.
+ */
+
+/**
+ * Normalizer converts a validated RawEvent into a CanonicalEvent.
+ * An instance is stateless — the same instance may be reused for many events.
+ */
+declare class Normalizer {
+    /**
+     * Validate and normalise a single RawEvent.
+     * Throws NormalizationError on invalid input.
+     */
+    normalize(raw: RawEvent): CanonicalEvent;
+}
+
+/**
+ * Validator — checks that a RawEvent has all required fields before normalization.
+ * Throws NormalizationError with a descriptive message on failure.
+ */
+
+/** Thrown when a RawEvent fails validation. */
+declare class NormalizationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate a RawEvent.
+ * Throws NormalizationError listing all violated constraints.
+ */
+declare function validateRawEvent(event: RawEvent): void;
+
+/**
+ * Correlator — generic, domain-agnostic span correlation.
+ *
+ * Responsibilities (architecture.md §4.1 / §8):
+ *  - span lifecycle pairing: tracks 'open' events by spanId; pairs with 'close'
+ *  - duration computation: stored in the in-memory state so SqliteSink can read
+ *    startTime when processing the close event
+ *  - traceId propagation: child spans inherit their parent's traceId
+ *  - in-memory short-term cache: cacheGet / cacheSet for Enricher use (Phase 1+)
+ *
+ * No domain logic. The correlator does not know about agent / process / promotion axes.
+ */
+
+/**
+ * Correlator maintains in-memory state across events in the same write session.
+ * A single instance should be reused for the lifetime of the write pipeline.
+ */
+declare class Correlator {
+    /** Open spans awaiting a matching 'close' event (keyed by spanId). */
+    private readonly openSpans;
+    /** General-purpose short-term key-value cache (architecture.md §8). */
+    private readonly cache;
+    /**
+     * 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: CanonicalEvent): CanonicalEvent;
+    /**
+     * 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: string): CanonicalEvent | undefined;
+    /** Store a value under an arbitrary key (TTL not enforced in Phase 0). */
+    cacheSet(key: string, value: unknown): void;
+    /** Retrieve a cached value; returns undefined if absent. */
+    cacheGet<T = unknown>(key: string): T | undefined;
+    /** Remove a cached entry. */
+    cacheDel(key: string): void;
+    /** Return the number of currently-open spans (useful for testing). */
+    get openSpanCount(): number;
+}
+
+/**
+ * Cache key helpers for the Correlator's in-memory short-term store.
+ * architecture.md §8.2
+ */
+declare const keys: {
+    /** Per-run context: run:{id} */
+    readonly run: (id: string) => string;
+    /** Latest span in a trace: trace:{id}:latest */
+    readonly traceLatest: (id: string) => string;
+    /** Per-session context: session:{id} */
+    readonly session: (id: string) => string;
+    /** Tool call tracking: toolcall:{id} */
+    readonly toolCall: (id: string) => string;
+    /** Request tracking: request:{id} */
+    readonly request: (id: string) => string;
+};
+
+/**
+ * EnrichApi — the capability surface exposed to every enrichment rule.
+ *
+ * shift-left-event-mapping.md §5.2 / architecture.md §5.5
+ *
+ * Design principles:
+ *  - cacheGet/cacheSet reuse the Correlator's in-memory short-term store (no extra state)
+ *  - emitRecord queues a derived CanonicalEvent to be written to OtelEmitter + SqliteSink
+ *    after the current event's enrichment completes (re-injected into the pipeline)
+ *  - addLink appends a cross-axis link to the event currently being enriched
+ *  - lookupArtifact resolves file paths to artifact_ids via longest-match glob
+ *  - All resolution uses STRUCTURED keys only — no natural-language guessing
+ */
+
+/**
+ * A single artifact path-glob pattern entry.
+ * Provided via config / constructor from the artifact-contracts declarations
+ * (generated by Phase 4's binding; not hardcoded here).
+ * shift-left-event-mapping.md §3.3
+ */
+interface ArtifactPattern {
+    /** The artifact identifier (e.g. 'feature-spec', 'impl-ts'). */
+    artifact_id: string;
+    /** A glob pattern (e.g. 'src/**\/*.ts', 'docs/*.md'). */
+    pattern: string;
+}
+/**
+ * The API surface available to enrichment rule functions.
+ * All methods are synchronous — rules run in the hot write path.
+ */
+interface EnrichApi {
+    /**
+     * Read from the Correlator's shared in-memory cache.
+     * Returns undefined if the key is absent.
+     */
+    cacheGet<T = unknown>(key: string): T | undefined;
+    /**
+     * Write to the Correlator's shared in-memory cache.
+     * Overwrites any existing value for the key.
+     */
+    cacheSet(key: string, value: unknown): void;
+    /**
+     * Queue a fully-formed CanonicalEvent to be written to OtelEmitter + SqliteSink
+     * after the current event's enrichment pipeline completes.
+     *
+     * Derived events are NOT re-enriched (depth-1 limit to prevent cycles).
+     * Use this to emit promotion.file, attribution events, etc.
+     */
+    emitRecord(event: CanonicalEvent): void;
+    /**
+     * Append a cross-axis link to the event currently being enriched.
+     * Architecture.md §5.2 — post-discovery links are attached to the discovering event.
+     */
+    addLink(link: CanonicalLink): void;
+    /**
+     * Resolve a file path to an artifact_id via longest-match glob lookup.
+     * Returns "unknown" if no pattern matches (shift-left-event-mapping.md §3.3).
+     */
+    lookupArtifact(path: string): string;
+    /**
+     * Emit a debug log. fail-open: never throws.
+     * In production this is a no-op or routes to the configured logger.
+     */
+    logDebug(message: string, data?: unknown): void;
+    /** Current wall-clock time in Unix nanoseconds (for derived event timestamps). */
+    nowUnixNano(): bigint;
+}
+/**
+ * Context object passed to every enrichment rule.
+ *
+ * `ctx.event` is the MUTABLE event currently being enriched.
+ * Rules may set fields like `parentSpanId`, `taskId`, or `attributes` directly.
+ * `ctx.api` provides the enrichment capabilities.
+ *
+ * shift-left-event-mapping.md §5.2 example:
+ *   function resolveProcessParent(event: CanonicalEvent, ctx: EnrichContext): void
+ */
+interface EnrichContext {
+    /** The event being enriched. Mutable — rules set fields directly. */
+    event: CanonicalEvent;
+    /** Enrichment capabilities. */
+    api: EnrichApi;
+}
+/**
+ * Signature of an enrichment rule.
+ *
+ * - `event` is the same reference as `ctx.event` (convenience alias, consistent with spec)
+ * - Rules check their applicability at the top (eventType / lifecycle / presence of fields)
+ * - Rules MUST NOT throw — the Enricher wraps each call in a fail-open try/catch
+ *
+ * shift-left-event-mapping.md §5 — all resolution via STRUCTURED keys only.
+ */
+type EnrichRule = (event: CanonicalEvent, ctx: EnrichContext) => void;
+
+/**
+ * Enricher — domain-specific enrichment stage in the write-path pipeline.
+ *
+ * architecture.md §4.1 (Enricher role) / §5.5 / shift-left-event-mapping.md §5:
+ *   Positioned between Correlator and the sinks (OtelEmitter + SqliteSink).
+ *   Applies enrichment rules to each CanonicalEvent:
+ *     - attribute completion (artifact_id, reconcile.status)
+ *     - parent resolution (parentSpanId, taskId)
+ *     - cross-axis link addition (materializes_as_commit, contains_change)
+ *     - derived event emission (promotion.file)
+ *
+ * Design:
+ *   - Reuses the Correlator's in-memory short-term store for cacheGet/cacheSet
+ *   - fail-open: a rule that throws is logged and execution continues
+ *   - emitRecord queues derived CanonicalEvents (written to sinks after the
+ *     current event's enrichment completes; NOT re-enriched to prevent cycles)
+ *   - dispatch: all registered rules run for every event; each rule checks
+ *     its own applicability (eventType / lifecycle / field presence)
+ */
+
+interface EnricherOptions {
+    /** Correlator instance — its cache is shared with the Enricher (architecture.md §8). */
+    correlator: Correlator;
+    /**
+     * Artifact path-glob patterns for lookupArtifact.
+     * Provided via config / createPipeline options; generated by Phase 4 binding.
+     * Pass [] for no artifact resolution (all paths → "unknown").
+     */
+    artifactPatterns?: ArtifactPattern[];
+}
+/** Return value of Enricher.enrich(). */
+interface EnrichResult {
+    /** The (possibly mutated) canonical event ready to write to sinks. */
+    enriched: CanonicalEvent;
+    /**
+     * Derived canonical events queued by rules via api.emitRecord().
+     * Caller writes these to sinks after the primary event (no re-enrichment).
+     */
+    derived: CanonicalEvent[];
+}
+declare class Enricher {
+    private readonly correlator;
+    private readonly artifactPatterns;
+    private readonly 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: EnricherOptions, rules: EnrichRule[]);
+    /**
+     * 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: CanonicalEvent): EnrichResult;
+}
+/**
+ * Build the standard Phase 5 enrichment rule set.
+ *
+ * Rule ordering:
+ *   1. R7 artifact.ts   — resolve edit.artifact_id first (R3 disambiguation depends on it)
+ *   2. R3/R4 process.ts — maintain active-task stack; resolve process.edit/tool parent
+ *   3. R5 cross-axis.ts — materializes_as_commit on promotion.commit close
+ *   4. R1/R2 promotion.ts — cache changes; emit promotion.file on commit close
+ *
+ * @param artifactPatterns  Passed to createArtifactRule for R7 lookupArtifact.
+ */
+declare function createDefaultRules(artifactPatterns?: ArtifactPattern[]): EnrichRule[];
+
+/**
+ * R7 — Artifact ID resolution for process.edit events.
+ *
+ * shift-left-event-mapping.md §5.1:
+ *   "R7: artifact_id 未解決 → file_path → artifact-lookup (§3.3) — longest-match glob,
+ *    未マッチは unknown"
+ *
+ * Resolution is via STRUCTURED lookup only (path glob → artifact_id).
+ * No natural-language guessing; unresolved → "unknown".
+ */
+
+declare function globToRegex(pattern: string): RegExp;
+/**
+ * Resolve a file path to an artifact_id using longest-match glob.
+ *
+ * Among all patterns that match `filePath`, the one with the longest pattern
+ * string wins (longer = more specific). Ties are broken by declaration order
+ * (first wins). Returns "unknown" if no pattern matches.
+ *
+ * shift-left-event-mapping.md §3.3
+ */
+declare function lookupArtifact(filePath: string, patterns: ArtifactPattern[]): string;
+/**
+ * Create the R7 artifact-resolution enrichment rule.
+ *
+ * Applies to: process.edit (instant)
+ * Action: sets `edit.artifact_id` on the event attributes via lookupArtifact.
+ *         If no pattern matches, sets `edit.artifact_id = "unknown"`.
+ *         Skips if `edit.artifact_id` is already set to a non-empty, non-"unknown" value.
+ *
+ * The `patterns` list is provided via config/constructor (no hardcoded project values).
+ */
+declare function createArtifactRule(patterns: ArtifactPattern[]): EnrichRule;
+
+/**
+ * R3/R4 — Process parent resolution for process.edit and process.tool events.
+ *
+ * shift-left-event-mapping.md §5.1:
+ *   R3: process.edit → process.task (parent)
+ *       "session_id の active task スタック + file_path→artifact で一意化"
+ *       "単一 active task なら確定、複数なら artifact 一致で一意化、不能なら ambiguous"
+ *   R4: process.tool → process.task (parent)
+ *       "単一なら確定、複数なら ambiguous"
+ *
+ * All resolution via STRUCTURED keys only:
+ *   - active task stack per session (in-memory cache)
+ *   - artifact_id already set by R7 (for disambiguation in R3)
+ *   - Never guess from natural language or timing
+ *
+ * Cache schema maintained by this rule:
+ *   session:{sid}:active_tasks   → ActiveTask[]    (currently open tasks)
+ *   session:{sid}:all_task_spans → string[]        (all task spanIds, open + closed, for R5)
+ *   session:{sid}:task_files:{taskSpanId} → string[] (accumulated modified files, for R5)
+ */
+
+/** A currently-open process.task span tracked on the active stack. */
+interface ActiveTask {
+    spanId: string;
+    taskId: string | undefined;
+}
+declare function activeTasksKey(sessionId: string): string;
+declare function allTaskSpansKey(sessionId: string): string;
+declare function taskFilesKey(sessionId: string, taskSpanId: string): string;
+/**
+ * Create the R3/R4 process-parent enrichment rule.
+ *
+ * Handles three event types:
+ *   1. process.task open  — push task onto active-task stack
+ *   2. process.task close — pop task from active-task stack
+ *   3. process.edit instant — resolve parentSpanId/taskId (R3)
+ *   4. process.tool instant — resolve parentSpanId/taskId (R4)
+ *
+ * Resolution algorithm (R3/R4):
+ *   - If event already has parentSpanId → skip (already resolved)
+ *   - 0 active tasks → leave provisional (no parentSpanId)
+ *   - 1 active task  → set parentSpanId + taskId (confirmed)
+ *   - 2+ active tasks (R3) → try to disambiguate by edit.artifact_id match
+ *     against task's artifact_ids; if still ambiguous → set reconcile.status=ambiguous
+ *   - 2+ active tasks (R4) → set reconcile.status=ambiguous (no artifact disambig)
+ */
+declare function createProcessRule(): EnrichRule;
+/**
+ * Record a task's primary artifact in the cache so that R3 disambiguation can use it.
+ * Call this when a process.task open event carries a known artifact_id attribute.
+ *
+ * This is an optional supplement to the createProcessRule — the main rule will
+ * call lookupArtifact on the task's own attributes if available, but the cache
+ * entry is more reliable for disambiguation.
+ */
+declare function recordTaskArtifact(sessionId: string, taskSpanId: string, artifactId: string, cacheSet: (key: string, value: unknown) => void): void;
+
+/**
+ * Create the R5 cross-axis enrichment rule.
+ *
+ * Applies to: promotion.commit (close)
+ * Action: for each known task whose accumulated modified_files intersect the
+ *         committed_files attribute, add a materializes_as_commit link to the
+ *         promotion.commit event (pointing to the task's spanId).
+ *
+ * committed_files must be a JSON-encoded string array on the commit event.
+ * If absent or unparseable, the rule skips silently (fail-open).
+ */
+declare function createCrossAxisRule(): EnrichRule;
+
+/**
+ * Create the R1/R2 promotion-correlation enrichment rule.
+ *
+ * Handles two event types:
+ *   1. promotion.change instant  — cache the change by (session_id, file.path)
+ *   2. promotion.commit close    — emit promotion.file per committed file (R2),
+ *                                   with contains_change links to cached changes (R1)
+ *
+ * The committed_files attribute on promotion.commit must be a JSON-encoded
+ * string array (e.g., '["src/foo.ts","README.md"]').
+ * If absent or unparseable, the rule skips silently (fail-open).
+ */
+declare function createPromotionRule(): EnrichRule;
+
+/**
+ * SqliteSink — persists CanonicalEvents to a local SQLite database.
+ *
+ * architecture.md §10 / §4.1 (SqliteSink role):
+ *  - canonical_events : append-only INSERT (immutable log)
+ *  - spans            : open→INSERT, close→UPDATE, instant→INSERT
+ *  - canonical_links  : expand event.links into normalised rows
+ *
+ * Default path: .agent-logs/observability.db
+ * Pass ':memory:' for an in-process in-memory database (tests, ephemeral use).
+ *
+ * Uses the built-in node:sqlite (stable in Node ≥ 24, experimental in 22.5+).
+ */
+
+/** Default database file location (relative to cwd). */
+declare const DEFAULT_DB_PATH = ".agent-logs/observability.db";
+declare class SqliteSink {
+    private readonly db;
+    constructor(dbPath?: string);
+    /**
+     * Persist a single CanonicalEvent.
+     *  1. Append to canonical_events (immutable)
+     *  2. Upsert spans materialised view
+     *  3. Insert canonical_links rows
+     */
+    write(event: CanonicalEvent): void;
+    /** Close the database connection. */
+    close(): void;
+    /**
+     * Expose the underlying DatabaseSync for testing / read-path adapters.
+     * Should not be used in production write paths.
+     */
+    getDb(): DatabaseSync;
+    private insertCanonicalEvent;
+    private upsertSpan;
+    private insertLinks;
+}
+
+/**
+ * span-mapper — converts a group of CanonicalEvents sharing the same spanId
+ * into a structure ready for OTEL Span emission.
+ *
+ * architecture.md §11 / §4.1 (OtelEmitter role):
+ *  - open  → Span start_time
+ *  - close → Span end_time
+ *  - event → SpanEvent (attached to the span)
+ *  - instant → start_time = end_time (duration-zero Span)
+ *
+ * attributes are merged across open / close / event events (open first,
+ * then close, then each event in time order — later keys win).
+ *
+ * parentSpanId → OTEL parent context.
+ * CanonicalEvent.links → OTEL SpanLinks (link_type stored as a SpanLink attribute).
+ */
+
+/** A single SpanEvent (mid-span event attached to the logical span). */
+interface MappedSpanEvent {
+    name: string;
+    timeUnixNano: bigint;
+    attributes: Record<string, AttrValue>;
+}
+/** A SpanLink pointing to another span, carrying link_type as an attribute. */
+interface MappedSpanLink {
+    /** Target span identifier. */
+    targetSpanId: string;
+    /** Target trace identifier (may be same as the span's traceId). */
+    targetTraceId?: string;
+    /** Attributes including 'link_type' (the semantic relationship). */
+    attributes: Record<string, string>;
+}
+/**
+ * A logical OTEL Span derived from one or more CanonicalEvents.
+ * This is an intermediate representation, not coupled to any OTEL SDK type.
+ */
+interface MappedSpan {
+    /** Span identifier. */
+    spanId: string;
+    /** Trace identifier. */
+    traceId: string;
+    /** Parent span identifier (undefined for root spans). */
+    parentSpanId?: string;
+    /** Span name (== eventType of the constituent events). */
+    name: string;
+    /** Span start time in Unix nanoseconds. */
+    startTimeUnixNano: bigint;
+    /** Span end time in Unix nanoseconds. */
+    endTimeUnixNano: bigint;
+    /** Merged attributes from all constituent events. */
+    attributes: Record<string, AttrValue>;
+    /** Mid-span events (from lifecycle='event' CanonicalEvents). */
+    spanEvents: MappedSpanEvent[];
+    /** Links to other spans. */
+    links: MappedSpanLink[];
+}
+/**
+ * Map a group of CanonicalEvents (all sharing the same spanId) to a MappedSpan.
+ *
+ * The caller must ensure all events belong to the same spanId.
+ * Events need not be pre-sorted; this function sorts by timeUnixNano internally.
+ *
+ * Returns undefined if the group is empty.
+ */
+declare function mapEventsToSpan(events: CanonicalEvent[]): MappedSpan | undefined;
+/**
+ * Group an array of CanonicalEvents by spanId, then map each group to a MappedSpan.
+ * Useful for batch conversion (e.g. flushing a set of events to OTEL).
+ */
+declare function mapAllEventsToSpans(events: CanonicalEvent[]): MappedSpan[];
+
+interface OtelEmitterOptions {
+    /**
+     * OTLP HTTP endpoint URL.
+     * Defaults to process.env.OTEL_EXPORTER_OTLP_ENDPOINT.
+     * If neither is set, OtelEmitter becomes a no-op.
+     */
+    endpoint?: string;
+    /** Service name reported to the OTEL backend. Default: '@aaac/observability'. */
+    serviceName?: string;
+}
+declare class OtelEmitter {
+    private readonly provider;
+    private readonly tracer;
+    private readonly enabled;
+    constructor(options?: OtelEmitterOptions);
+    /**
+     * 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: MappedSpan): void;
+    /**
+     * Emit a batch of MappedSpans.
+     * Each span is emitted independently; one failure does not block others.
+     */
+    emitBatch(spans: MappedSpan[]): void;
+    /**
+     * Flush pending spans and shut down the OTEL provider.
+     * Returns a promise that resolves when the flush is complete (or on error).
+     */
+    shutdown(): Promise<void>;
+    private _emitSpan;
+    private _buildParentContext;
+}
+
+/**
+ * Query-layer models — decouple read-path return types from storage internals.
+ *
+ * event-catalog.md §1.4 / architecture.md §12.
+ *
+ * StoredEvent is already defined in types/canonical-event.ts as an alias of
+ * CanonicalEvent. Here we re-export it alongside query-specific types so
+ * consumers can import everything from '@aaac/observability/query' (or the
+ * barrel) without reaching into internal modules.
+ */
+
+/**
+ * A logical Span as materialised in the `spans` table.
+ * Returned by span-level queries (QueryAdapter.querySpans, getSpan, etc.).
+ */
+interface SpanRecord {
+    spanId: string;
+    traceId: string | null;
+    parentSpanId: string | null;
+    eventType: string;
+    /** Unix nanoseconds (bigint, may be null for spans with no open event). */
+    startTime: bigint | null;
+    /** Unix nanoseconds (bigint, may be null for open spans). */
+    endTime: bigint | null;
+    /** Computed duration in nanoseconds. */
+    durationNs: bigint | null;
+    /** 'open' | 'closed' | 'instant' */
+    status: string;
+    runId: string | null;
+    sessionId: string | null;
+    taskId: string | null;
+    attributes: Record<string, AttrValue>;
+}
+/** A single cross-axis link row from the `canonical_links` table. */
+interface LinkRecord {
+    id: string;
+    sourceEventId: string;
+    sourceSpanId: string;
+    targetSpanId: string;
+    targetTraceId: string | null;
+    linkType: string;
+    attributes: Record<string, string>;
+}
+/** Filters for span-level queries. All fields are optional (AND-combined). */
+interface SpanQueryFilter {
+    traceId?: string;
+    spanId?: string;
+    eventType?: string;
+    taskId?: string;
+    /** Inclusive lower bound (Unix nanoseconds). */
+    fromTimeUnixNano?: bigint;
+    /** Inclusive upper bound (Unix nanoseconds). */
+    toTimeUnixNano?: bigint;
+    /** Limit the number of returned rows. */
+    limit?: number;
+}
+/** Filters for canonical_events queries. All fields are optional (AND-combined). */
+interface EventQueryFilter {
+    traceId?: string;
+    spanId?: string;
+    eventType?: string;
+    taskId?: string;
+    fromTimeUnixNano?: bigint;
+    toTimeUnixNano?: bigint;
+    limit?: number;
+}
+/** Direction for link traversal queries. */
+type LinkDirection = "forward" | "reverse" | "both";
+
+/**
+ * QueryAdapter — abstract interface for reading stored observability data.
+ *
+ * architecture.md §12:
+ *  - Decouples the read path from the write path and from storage backends.
+ *  - Implementations: SqliteQueryAdapter (local), future: OtelBackendAdapter.
+ *  - Returns StoredEvent / SpanRecord / LinkRecord — backend-neutral types.
+ */
+
+interface QueryAdapter {
+    /**
+     * Query the materialised `spans` table.
+     * Returns spans matching all supplied filter fields (AND-combined).
+     */
+    querySpans(filter: SpanQueryFilter): SpanRecord[];
+    /**
+     * Retrieve a single span by spanId.
+     * Returns undefined if not found.
+     */
+    getSpan(spanId: string): SpanRecord | undefined;
+    /**
+     * Retrieve all spans belonging to a trace, ordered by startTime.
+     */
+    getTrace(traceId: string): SpanRecord[];
+    /**
+     * Query raw CanonicalEvents from the `canonical_events` table.
+     */
+    queryEvents(filter: EventQueryFilter): StoredEvent[];
+    /**
+     * Retrieve all CanonicalEvents for a specific spanId (the constituent events
+     * of a logical span), ordered by timeUnixNano.
+     */
+    getSpanEvents(spanId: string): StoredEvent[];
+    /**
+     * Retrieve links involving the given spanId.
+     *
+     * direction:
+     *  'forward' — links where source_span_id = spanId  (outgoing)
+     *  'reverse' — links where target_span_id = spanId  (incoming)
+     *  'both'    — union of forward and reverse
+     */
+    getLinks(spanId: string, direction?: LinkDirection): LinkRecord[];
+    /**
+     * Retrieve all links of a given link_type.
+     */
+    getLinksByType(linkType: string): LinkRecord[];
+    /** Release any resources held by this adapter (e.g. close DB connection). */
+    close(): void;
+}
+
+/**
+ * SqliteQueryAdapter — reads the SqliteSink database independently of the
+ * write path.
+ *
+ * architecture.md §12 / §12.3:
+ *  - Queries the `spans` materialised table for span-level queries.
+ *  - Queries `canonical_events` for raw event access.
+ *  - Queries `canonical_links` for link traversal (source/target bidirectional).
+ *  - Can open the same database file as SqliteSink, or an in-memory DB for tests.
+ *  - Does NOT touch write-path state (no Correlator, no Normalizer, etc.).
+ */
+
+declare class SqliteQueryAdapter implements QueryAdapter {
+    private readonly db;
+    private readonly 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?: string | DatabaseSync);
+    querySpans(filter: SpanQueryFilter): SpanRecord[];
+    getSpan(spanId: string): SpanRecord | undefined;
+    getTrace(traceId: string): SpanRecord[];
+    queryEvents(filter: EventQueryFilter): StoredEvent[];
+    getSpanEvents(spanId: string): StoredEvent[];
+    getLinks(spanId: string, direction?: LinkDirection): LinkRecord[];
+    getLinksByType(linkType: string): LinkRecord[];
+    close(): void;
+}
+
+/**
+ * @aaac/observability — Phase 0–5 public API
+ *
+ * Write pipeline (Phase 5):
+ *   EventCollector → Normalizer → Correlator → [afterCorrelate?] → Enricher → SqliteSink
+ *                                                                            → OtelEmitter
+ *
+ * Quick start:
+ *   import { createPipeline } from '@aaac/observability';
+ *   const { collector, sink } = createPipeline();
+ *   collector.emit({ source: 'aaac-runtime', eventType: 'agent.session', lifecycle: 'open', attributes: {} });
+ *   sink.close();
+ */
+
+interface PipelineOptions {
+    /** SQLite database path. Defaults to DEFAULT_DB_PATH. Pass ':memory:' for tests. */
+    dbPath?: string;
+    /**
+     * Optional post-correlate hook — runs before the Enricher.
+     * Kept for backward compatibility; prefer using enrichRules for Phase 5+.
+     */
+    afterCorrelate?: (event: CanonicalEvent) => CanonicalEvent;
+    /**
+     * Optional OTEL emitter options.
+     * If provided (and endpoint is set), events are also emitted to the OTEL backend.
+     * fail-open: OTEL failures never block SQLite recording.
+     */
+    otel?: OtelEmitterOptions;
+    /**
+     * Artifact path-glob patterns for the Enricher's lookupArtifact (R7).
+     * Provided from artifact-contracts declarations (generated by Phase 4 binding).
+     * Defaults to [] (all file paths resolve to "unknown").
+     */
+    artifactPatterns?: ArtifactPattern[];
+    /**
+     * Custom enrichment rule list.
+     * Defaults to createDefaultRules(artifactPatterns) — the standard Phase 5 set.
+     * Pass [] to disable all enrichment.
+     */
+    enrichRules?: EnrichRule[];
+}
+interface Pipeline {
+    collector: EventCollector;
+    correlator: Correlator;
+    sink: SqliteSink;
+    otelEmitter: OtelEmitter;
+    /** Phase 5 Enricher (Correlator → Enricher → OtelEmitter + SqliteSink). */
+    enricher: Enricher;
+}
+/**
+ * Create a complete write pipeline wired together:
+ *
+ *   EventCollector → Normalizer → Correlator → [afterCorrelate?]
+ *     → Enricher → SqliteSink
+ *               → OtelEmitter (if configured, fail-open)
+ *
+ * Derived events from Enricher.emitRecord() are written to both sinks after
+ * the primary event (depth-1; derived events are NOT re-enriched).
+ */
+declare function createPipeline(options?: PipelineOptions): Pipeline;
+
+export { type ActiveTask, type ArtifactPattern, type AttrValue, type CanonicalEvent, type CanonicalLink, Correlator, DEFAULT_DB_PATH, DefaultExternalRegistrar, type EmitInput, type EnrichApi, type EnrichContext, type EnrichResult, type EnrichRule, Enricher, type EnricherOptions, EventCollector, type EventQueryFilter, type ExecutionEnvelope, type ExternalEventRegistrar, type Lifecycle, type LinkDirection, type LinkRecord, type MappedSpan, type MappedSpanEvent, type MappedSpanLink, NormalizationError, Normalizer, OtelEmitter, type OtelEmitterOptions, type Pipeline, type PipelineOptions, type QueryAdapter, type RawEvent, type RawEventHandler, type RawExternalEvent, type SpanQueryFilter, type SpanRecord, SqliteQueryAdapter, SqliteSink, type StoredEvent, activeTasksKey, allTaskSpansKey, keys as correlateKeys, createArtifactRule, createCrossAxisRule, createDefaultRules, createPipeline, createProcessRule, createPromotionRule, currentTimeUnixNano, generateId, globToRegex, isoToUnixNano, lookupArtifact, mapAllEventsToSpans, mapEventsToSpan, recordTaskArtifact, taskFilesKey, validateRawEvent };