@kilnai/core 0.1.0

package/dist/memory/sqlite-store.js

@@ -0,0 +1,320 @@
+import { Database } from "bun:sqlite";
+import { applyDecayCurve, DEFAULT_DECAY_CONFIG } from "./decay-curves.js";
+import { MemoryCompactor } from "./compactor.js";
+import { KilnError } from "../engine/errors.js";
+/** Rough heuristic: ~4 characters per token for English text */
+const CHARS_PER_TOKEN_ESTIMATE = 4;
+export class SqliteMemoryStore {
+    db;
+    layer;
+    enableDecay;
+    decayConfig;
+    compactor;
+    tenantId;
+    constructor(options) {
+        this.layer = options.layer;
+        this.enableDecay = options.enableDecay ?? false;
+        this.decayConfig = options.decay ?? DEFAULT_DECAY_CONFIG;
+        this.compactor = options.compaction ? new MemoryCompactor(options.compaction) : null;
+        this.tenantId = options.tenantId;
+        if (this.tenantId && /[%_]/.test(this.tenantId)) {
+            throw new KilnError('CONFIG_INVALID', 'tenantId must not contain SQL wildcard characters (% or _)', {
+                context: { tenantId: this.tenantId },
+                retryable: false,
+            });
+        }
+        this.db = new Database(options.dbPath);
+        this.db.exec("PRAGMA journal_mode = WAL;");
+        this.initSchema();
+    }
+    initSchema() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS memories (
+        id TEXT PRIMARY KEY,
+        content TEXT NOT NULL,
+        tags TEXT NOT NULL,
+        agent_role TEXT,
+        project_id TEXT,
+        created_at TEXT NOT NULL,
+        last_accessed_at TEXT NOT NULL,
+        access_count INTEGER DEFAULT 0,
+        decay_score REAL DEFAULT 1.0
+      );
+    `);
+        this.db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+        id UNINDEXED, content, tags, tokenize='porter'
+      );
+    `);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS memories_archive (
+        id TEXT PRIMARY KEY,
+        content TEXT NOT NULL,
+        tags TEXT NOT NULL,
+        agent_role TEXT,
+        project_id TEXT,
+        created_at TEXT NOT NULL,
+        last_accessed_at TEXT NOT NULL,
+        access_count INTEGER DEFAULT 0,
+        decay_score REAL DEFAULT 1.0,
+        archived_at TEXT NOT NULL
+      );
+    `);
+    }
+    async save(entry) {
+        const id = crypto.randomUUID();
+        const now = new Date().toISOString();
+        let tags = [...entry.tags];
+        if (this.tenantId) {
+            const tenantTag = `_tenant:${this.tenantId}`;
+            if (!tags.includes(tenantTag))
+                tags.push(tenantTag);
+        }
+        const tagsJson = JSON.stringify(tags);
+        this.db.prepare(`
+      INSERT INTO memories (id, content, tags, agent_role, project_id, created_at, last_accessed_at, access_count, decay_score)
+      VALUES (?, ?, ?, ?, ?, ?, ?, 0, 1.0)
+    `).run(id, entry.content, tagsJson, entry.agentRole ?? null, entry.projectId ?? null, now, now);
+        this.db.prepare(`
+      INSERT INTO memories_fts (id, content, tags) VALUES (?, ?, ?)
+    `).run(id, entry.content, tagsJson);
+        return id;
+    }
+    async search(query, limit) {
+        const maxResults = limit ?? 10;
+        let rows;
+        if (this.tenantId) {
+            const tenantTag = `_tenant:${this.tenantId}`;
+            rows = this.db.prepare(`
+        SELECT m.*, bm25(memories_fts) AS score,
+               snippet(memories_fts, 1, '<b>', '</b>', '...', 32) AS snippet
+        FROM memories_fts fts
+        JOIN memories m ON m.id = fts.id
+        WHERE memories_fts MATCH ?
+          AND m.tags LIKE ?
+        ORDER BY bm25(memories_fts)
+        LIMIT ?
+      `).all(query, `%"${tenantTag}"%`, maxResults);
+            // Runtime assertion: verify each returned row has the tenant tag
+            for (const row of rows) {
+                const tags = JSON.parse(row.tags);
+                if (!tags.includes(tenantTag)) {
+                    throw new KilnError("TENANT_ISOLATION_VIOLATED", `Memory entry ${row.id} lacks tenant tag for tenant ${this.tenantId}`, {
+                        context: { entryId: row.id, tenantId: this.tenantId },
+                        retryable: false,
+                    });
+                }
+            }
+        }
+        else {
+            rows = this.db.prepare(`
+        SELECT m.*, bm25(memories_fts) AS score,
+               snippet(memories_fts, 1, '<b>', '</b>', '...', 32) AS snippet
+        FROM memories_fts fts
+        JOIN memories m ON m.id = fts.id
+        WHERE memories_fts MATCH ?
+        ORDER BY bm25(memories_fts)
+        LIMIT ?
+      `).all(query, maxResults);
+        }
+        return rows.map((row) => this.toSearchResult(row));
+    }
+    async recall(query, tokenBudget) {
+        const results = await this.search(query, 50);
+        const parts = [];
+        let tokensUsed = 0;
+        for (const result of results) {
+            const tokenEstimate = Math.ceil(result.entry.content.length / CHARS_PER_TOKEN_ESTIMATE);
+            if (tokensUsed + tokenEstimate > tokenBudget)
+                break;
+            parts.push(result.entry.content);
+            tokensUsed += tokenEstimate;
+        }
+        return parts.join("\n\n");
+    }
+    async forget(id) {
+        if (this.tenantId) {
+            const row = this.db.prepare("SELECT tags FROM memories WHERE id = ?").get(id);
+            if (row) {
+                const tags = JSON.parse(row.tags);
+                const tenantTag = `_tenant:${this.tenantId}`;
+                if (!tags.includes(tenantTag)) {
+                    throw new KilnError("TENANT_ISOLATION_VIOLATED", `Cannot delete memory entry ${id}: tenant isolation violation`, {
+                        context: { entryId: id, tenantId: this.tenantId },
+                        retryable: false,
+                    });
+                }
+            }
+        }
+        this.db.prepare("DELETE FROM memories_fts WHERE id = ?").run(id);
+        this.db.prepare("DELETE FROM memories WHERE id = ?").run(id);
+    }
+    reinforce(id) {
+        const now = new Date().toISOString();
+        this.db.prepare(`
+      UPDATE memories
+      SET last_accessed_at = ?, access_count = access_count + 1, decay_score = 1.0
+      WHERE id = ?
+    `).run(now, id);
+    }
+    applyDecay(factor) {
+        const config = this.decayConfig;
+        const now = Date.now();
+        if (config.curve === "step") {
+            // Step decay: set score to 0 for entries older than factor days
+            const rows = this.db.prepare("SELECT id, created_at FROM memories").all();
+            for (const row of rows) {
+                const ageInDays = (now - new Date(row.created_at).getTime()) / (1000 * 60 * 60 * 24);
+                const newScore = applyDecayCurve(1, config, ageInDays);
+                this.db.prepare("UPDATE memories SET decay_score = ? WHERE id = ?").run(newScore, row.id);
+            }
+        }
+        else if (config.curve === "linear") {
+            const linearFactor = factor ?? config.factor;
+            const rows = this.db.prepare("SELECT id, decay_score FROM memories").all();
+            for (const row of rows) {
+                const newScore = applyDecayCurve(row.decay_score, { ...config, factor: linearFactor });
+                this.db.prepare("UPDATE memories SET decay_score = ? WHERE id = ?").run(newScore, row.id);
+            }
+        }
+        else {
+            // Exponential (default) -- batch update for efficiency
+            const decayFactor = factor ?? config.factor;
+            this.db.prepare("UPDATE memories SET decay_score = decay_score * ?").run(decayFactor);
+        }
+        // Prune entries below threshold
+        const threshold = config.pruneThreshold;
+        const pruned = this.db.prepare("SELECT id FROM memories WHERE decay_score < ?").all(threshold);
+        for (const row of pruned) {
+            this.db.prepare("DELETE FROM memories_fts WHERE id = ?").run(row.id);
+        }
+        this.db.prepare("DELETE FROM memories WHERE decay_score < ?").run(threshold);
+    }
+    /** Run compaction if configured and threshold exceeded. Returns null if compaction is not configured. */
+    runCompaction() {
+        if (!this.compactor)
+            return null;
+        if (!this.compactor.shouldCompact(this.asCompactable()))
+            return null;
+        return this.compactor.compact(this.asCompactable());
+    }
+    asCompactable() {
+        const db = this.db;
+        return {
+            entryCount() {
+                const row = db.prepare("SELECT COUNT(*) AS cnt FROM memories").get();
+                return row.cnt;
+            },
+            queryOldEntries(minAgeDays, limit) {
+                const cutoff = new Date(Date.now() - minAgeDays * 24 * 60 * 60 * 1000).toISOString();
+                const rows = db.prepare(`
+          SELECT id, content, tags, decay_score
+          FROM memories
+          WHERE created_at < ?
+          ORDER BY decay_score ASC
+          LIMIT ?
+        `).all(cutoff, limit);
+                return rows.map((r) => ({
+                    id: r.id,
+                    content: r.content,
+                    tags: JSON.parse(r.tags),
+                    decayScore: r.decay_score,
+                }));
+            },
+            saveSummary(content, tags) {
+                const id = crypto.randomUUID();
+                const now = new Date().toISOString();
+                const tagsJson = JSON.stringify(tags);
+                db.prepare(`
+          INSERT INTO memories (id, content, tags, created_at, last_accessed_at, access_count, decay_score)
+          VALUES (?, ?, ?, ?, ?, 0, 1.0)
+        `).run(id, content, tagsJson, now, now);
+                db.prepare(`
+          INSERT INTO memories_fts (id, content, tags) VALUES (?, ?, ?)
+        `).run(id, content, tagsJson);
+                return id;
+            },
+            archiveEntries(ids) {
+                const now = new Date().toISOString();
+                for (const id of ids) {
+                    db.prepare(`
+            INSERT OR IGNORE INTO memories_archive
+            SELECT *, ? AS archived_at FROM memories WHERE id = ?
+          `).run(now, id);
+                    db.prepare("DELETE FROM memories_fts WHERE id = ?").run(id);
+                    db.prepare("DELETE FROM memories WHERE id = ?").run(id);
+                }
+            },
+        };
+    }
+    listEntries(options) {
+        const limit = options?.limit ?? 100;
+        const tagFilter = options?.tags ? options.tags.split(",").map((t) => t.trim()).filter(Boolean) : [];
+        let rows;
+        if (this.tenantId) {
+            const tenantTag = `_tenant:${this.tenantId}`;
+            rows = this.db.prepare(`
+        SELECT * FROM memories
+        WHERE tags LIKE ?
+        ORDER BY last_accessed_at DESC
+        LIMIT ?
+      `).all(`%"${tenantTag}"%`, limit);
+            for (const row of rows) {
+                const tags = JSON.parse(row.tags);
+                if (!tags.includes(tenantTag)) {
+                    throw new KilnError("TENANT_ISOLATION_VIOLATED", `Memory entry ${row.id} lacks tenant tag for tenant ${this.tenantId}`, {
+                        context: { entryId: row.id, tenantId: this.tenantId },
+                        retryable: false,
+                    });
+                }
+            }
+        }
+        else {
+            rows = this.db.prepare(`
+        SELECT * FROM memories
+        ORDER BY last_accessed_at DESC
+        LIMIT ?
+      `).all(limit);
+        }
+        if (tagFilter.length > 0) {
+            rows = rows.filter((row) => {
+                const rowTags = JSON.parse(row.tags);
+                return tagFilter.every((t) => rowTags.includes(t));
+            });
+        }
+        return rows.map((row) => this.toEntry(row));
+    }
+    hasEntry(id) {
+        const row = this.db.prepare("SELECT 1 FROM memories WHERE id = ?").get(id);
+        return row !== undefined;
+    }
+    close() {
+        this.db.close();
+    }
+    get count() {
+        const row = this.db.prepare("SELECT COUNT(*) AS cnt FROM memories").get();
+        return row.cnt;
+    }
+    toSearchResult(row) {
+        const score = this.enableDecay ? Math.abs(row.score) * row.decay_score : Math.abs(row.score);
+        return {
+            entry: this.toEntry(row),
+            score,
+            snippet: row.snippet,
+        };
+    }
+    toEntry(row) {
+        return {
+            id: row.id,
+            layer: this.layer,
+            content: row.content,
+            tags: JSON.parse(row.tags),
+            createdAt: new Date(row.created_at),
+            lastAccessedAt: new Date(row.last_accessed_at),
+            accessCount: row.access_count,
+            agentRole: row.agent_role,
+            projectId: row.project_id ?? undefined,
+        };
+    }
+}
+//# sourceMappingURL=sqlite-store.js.map

package/dist/memory/sqlite-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-store.js","sourceRoot":"","sources":["../../src/memory/sqlite-store.ts"],"names":[],"mappings":"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"}

package/dist/observability/index.d.ts

@@ -0,0 +1,5 @@
+export { mapEventToSpan } from "./span-mapper.js";
+export type { SpanOperation } from "./span-mapper.js";
+export { OTelExporter } from "./otel-exporter.js";
+export type { OTelExporterConfig } from "./otel-exporter.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/observability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/observability/index.js

@@ -0,0 +1,3 @@
+export { mapEventToSpan } from "./span-mapper.js";
+export { OTelExporter } from "./otel-exporter.js";
+//# sourceMappingURL=index.js.map

package/dist/observability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/observability/otel-exporter.d.ts

@@ -0,0 +1,41 @@
+import type { TracerProvider } from "@opentelemetry/api";
+import type { KilnEvent } from "../events/index.js";
+import type { EventStore } from "../events/event-store.js";
+export interface OTelExporterConfig {
+    readonly serviceName: string;
+    readonly attributes?: Record<string, string>;
+}
+/**
+ * Implements EventStore by forwarding Kiln events to an OpenTelemetry TracerProvider.
+ * Received events are mapped by SpanMapper then dispatched to the OTel API.
+ *
+ * This class is write-only. getBySession() and getAfter() throw errors -- retrieval
+ * is handled by the OTel backend (Jaeger, Datadog, etc.), not this adapter.
+ *
+ * Active spans are tracked per-session in an internal Map, and cleaned up on session end.
+ * Memory leaks are prevented by the span lifecycle (startSpan/endSpan pairing from SpanMapper).
+ */
+export declare class OTelExporter implements EventStore {
+    private readonly tracer;
+    private readonly provider;
+    private readonly activeSpans;
+    constructor(tracerProvider: TracerProvider, config: OTelExporterConfig);
+    save(event: KilnEvent): Promise<void>;
+    getBySession(_sessionId: string): Promise<KilnEvent[]>;
+    getAfter(_sessionId: string, _afterId: string): Promise<KilnEvent[]>;
+    /**
+     * Flush all pending spans and shut down the tracer provider.
+     * Call this during graceful gateway shutdown.
+     */
+    shutdown(): Promise<void>;
+    private getOrCreateSessionSpans;
+    /**
+     * Derive a stable span key from the event's identifying fields.
+     * For startSpan/endSpan pairs, the same key must be produced for both events.
+     */
+    private resolveSpanKey;
+    /** Return the most recently started span for a session (stack-like access). */
+    private getActiveSpan;
+    private setAttributes;
+}
+//# sourceMappingURL=otel-exporter.d.ts.map

package/dist/observability/otel-exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-exporter.d.ts","sourceRoot":"","sources":["../../src/observability/otel-exporter.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAgC,MAAM,oBAAoB,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAO3D,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChD;AAED;;;;;;;;;GASG;AACH,qBAAa,YAAa,YAAW,UAAU;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAG1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAwC;gBAExD,cAAc,EAAE,cAAc,EAAE,MAAM,EAAE,kBAAkB;IAKhE,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAmD3C,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAItD,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAIpE;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB/B,OAAO,CAAC,uBAAuB;IAS/B;;;OAGG;IACH,OAAO,CAAC,cAAc;IA+BtB,+EAA+E;IAC/E,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,aAAa;CAKxB"}

package/dist/observability/otel-exporter.js

@@ -0,0 +1,166 @@
+// Observability: OTelExporter -- implements EventStore, wraps @opentelemetry/api TracerProvider.
+// @opentelemetry/api is a PEER DEPENDENCY in @kilnai/runtime, NOT a dependency of @kilnai/core.
+// The TracerProvider is created and injected by the gateway-server, never imported here at runtime.
+import { mapEventToSpan } from "./span-mapper.js";
+// SpanStatusCode numeric values from @opentelemetry/api -- avoids importing the enum at runtime.
+const SPAN_STATUS_OK = 1;
+const SPAN_STATUS_ERROR = 2;
+/**
+ * Implements EventStore by forwarding Kiln events to an OpenTelemetry TracerProvider.
+ * Received events are mapped by SpanMapper then dispatched to the OTel API.
+ *
+ * This class is write-only. getBySession() and getAfter() throw errors -- retrieval
+ * is handled by the OTel backend (Jaeger, Datadog, etc.), not this adapter.
+ *
+ * Active spans are tracked per-session in an internal Map, and cleaned up on session end.
+ * Memory leaks are prevented by the span lifecycle (startSpan/endSpan pairing from SpanMapper).
+ */
+export class OTelExporter {
+    tracer;
+    provider;
+    // sessionId -> (spanKey -> Span)
+    // spanKey is derived from taskId / toolName / workerIndex for each startSpan operation
+    activeSpans = new Map();
+    constructor(tracerProvider, config) {
+        this.provider = tracerProvider;
+        this.tracer = tracerProvider.getTracer(config.serviceName, "0.1.0");
+    }
+    async save(event) {
+        const operation = mapEventToSpan(event);
+        const spans = this.getOrCreateSessionSpans(event.sessionId);
+        switch (operation.action) {
+            case "startSpan": {
+                const spanKey = this.resolveSpanKey(event);
+                const span = this.tracer.startSpan(operation.name);
+                this.setAttributes(span, operation.attributes);
+                spans.set(spanKey, span);
+                break;
+            }
+            case "endSpan": {
+                const spanKey = this.resolveSpanKey(event);
+                const span = spans.get(spanKey) ?? this.getActiveSpan(spans);
+                if (span) {
+                    if (operation.attributes) {
+                        this.setAttributes(span, operation.attributes);
+                    }
+                    const statusCode = operation.status === "error" ? SPAN_STATUS_ERROR : SPAN_STATUS_OK;
+                    span.setStatus({ code: statusCode });
+                    span.end();
+                    spans.delete(spanKey);
+                    // Also delete by iteration if key-based lookup was a miss (fallback case)
+                    for (const [k, s] of spans.entries()) {
+                        if (s === span) {
+                            spans.delete(k);
+                            break;
+                        }
+                    }
+                    // Clean up empty session maps to avoid memory leaks
+                    if (spans.size === 0) {
+                        this.activeSpans.delete(event.sessionId);
+                    }
+                }
+                break;
+            }
+            case "addEvent": {
+                const activeSpan = this.getActiveSpan(spans);
+                if (activeSpan) {
+                    activeSpan.addEvent(operation.name, operation.attributes);
+                }
+                break;
+            }
+            case "setAttributes": {
+                const activeSpan = this.getActiveSpan(spans);
+                if (activeSpan) {
+                    this.setAttributes(activeSpan, operation.attributes);
+                }
+                break;
+            }
+        }
+    }
+    getBySession(_sessionId) {
+        return Promise.reject(new Error("OTelExporter does not support retrieval. Query your OTel backend (Jaeger, Datadog, etc.)."));
+    }
+    getAfter(_sessionId, _afterId) {
+        return Promise.reject(new Error("OTelExporter does not support retrieval. Query your OTel backend (Jaeger, Datadog, etc.)."));
+    }
+    /**
+     * Flush all pending spans and shut down the tracer provider.
+     * Call this during graceful gateway shutdown.
+     */
+    async shutdown() {
+        // End any leaked spans (belt-and-suspenders)
+        for (const spans of this.activeSpans.values()) {
+            for (const span of spans.values()) {
+                span.end();
+            }
+        }
+        this.activeSpans.clear();
+        // TracerProvider.shutdown() is available in the SDK implementations
+        const providerWithShutdown = this.provider;
+        if (typeof providerWithShutdown.shutdown === "function") {
+            await providerWithShutdown.shutdown();
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    getOrCreateSessionSpans(sessionId) {
+        let spans = this.activeSpans.get(sessionId);
+        if (!spans) {
+            spans = new Map();
+            this.activeSpans.set(sessionId, spans);
+        }
+        return spans;
+    }
+    /**
+     * Derive a stable span key from the event's identifying fields.
+     * For startSpan/endSpan pairs, the same key must be produced for both events.
+     */
+    resolveSpanKey(event) {
+        const e = event;
+        // Tool spans: keyed by toolName + taskId (must be first -- tool events have both)
+        if (typeof e["toolName"] === "string" && typeof e["taskId"] === "string") {
+            return `tool:${e["toolName"]}:${e["taskId"]}`;
+        }
+        // Worker spans: keyed by workerIndex + taskId (check BEFORE bare taskId).
+        // WorkerAssignedEvent has both workerIndex AND taskId -- without this ordering it would
+        // collide with the task:taskId key and overwrite the task span.
+        if (typeof e["workerIndex"] === "number" && typeof e["taskId"] === "string") {
+            return `worker:${String(e["workerIndex"])}:${e["taskId"]}`;
+        }
+        if (typeof e["workerIndex"] === "number") {
+            return `worker:${String(e["workerIndex"])}`;
+        }
+        // Task spans: keyed by taskId alone
+        if (typeof e["taskId"] === "string") {
+            return `task:${e["taskId"]}`;
+        }
+        // Trigger spans: keyed by triggerName
+        if (typeof e["triggerName"] === "string") {
+            return `trigger:${e["triggerName"]}`;
+        }
+        // Phase spans: keyed by phase name
+        if (typeof e["phase"] === "string") {
+            return `phase:${e["phase"]}`;
+        }
+        // Fallback: event type
+        return `event:${event.type}`;
+    }
+    /** Return the most recently started span for a session (stack-like access). */
+    getActiveSpan(spans) {
+        if (spans.size === 0)
+            return undefined;
+        // Return the last inserted span (Map preserves insertion order)
+        let last;
+        for (const span of spans.values()) {
+            last = span;
+        }
+        return last;
+    }
+    setAttributes(span, attributes) {
+        for (const [key, value] of Object.entries(attributes)) {
+            span.setAttribute(key, value);
+        }
+    }
+}
+//# sourceMappingURL=otel-exporter.js.map

package/dist/observability/otel-exporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-exporter.js","sourceRoot":"","sources":["../../src/observability/otel-exporter.ts"],"names":[],"mappings":"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"}

package/dist/observability/span-mapper.d.ts

@@ -0,0 +1,24 @@
+import type { KilnEvent } from "../events/index.js";
+export type SpanOperation = {
+    action: "startSpan";
+    name: string;
+    kind: string;
+    attributes: Record<string, string | number | boolean>;
+} | {
+    action: "endSpan";
+    status: "ok" | "error";
+    attributes?: Record<string, string | number | boolean>;
+} | {
+    action: "addEvent";
+    name: string;
+    attributes: Record<string, string | number | boolean>;
+} | {
+    action: "setAttributes";
+    attributes: Record<string, string | number | boolean>;
+};
+/**
+ * Maps a KilnEvent to a SpanOperation descriptor.
+ * Exhaustive -- adding a new EventType without updating this switch is a compile error.
+ */
+export declare function mapEventToSpan(event: KilnEvent): SpanOperation;
+//# sourceMappingURL=span-mapper.d.ts.map

package/dist/observability/span-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-mapper.d.ts","sourceRoot":"","sources":["../../src/observability/span-mapper.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACR,SAAS,EAiCZ,MAAM,oBAAoB,CAAC;AAM5B,MAAM,MAAM,aAAa,GACnB;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;CAAE,GAC1G;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;CAAE,GACrG;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;CAAE,GAC3F;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;CAAE,CAAC;AAyUzF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,aAAa,CA0E9D"}