@fabric-harness/databricks 0.18.0 → 1.0.0

package/dist/mlflow-tracing.d.ts

@@ -0,0 +1,111 @@
+import type { FabricEvent, SubmissionTelemetrySink, TelemetrySpan } from '@fabric-harness/sdk';
+import type { DatabricksRestClient } from './client.js';
+/**
+ * MLflow trace export (v2 migration, workstream C6): one MLflow trace per
+ * settled submission, so agent activity shows up in the workspace's MLflow
+ * experiment UI next to models and evaluations.
+ *
+ * Wiring: `sink` goes into `createSubmissionRunner({ telemetry })` and
+ * `onEvent` fans in with the app's `onEvent` callback. A `submission_started`
+ * telemetry event opens a span buffer keyed by the store session id
+ * (`agent:<agent>:<instanceId>:<session>` — the `sessionId` stamped on
+ * `FabricEvent`s during the attempt); every event that matches an open buffer
+ * and converts via the SDK's `eventToTelemetrySpan` (i.e. carries
+ * `data.durationMs`) is appended as a child span. `submission_settled` builds
+ * the trace and POSTs it to the MLflow **V3 traces API**
+ * (`POST /api/3.0/mlflow/traces`), then drops the buffer.
+ *
+ * The V3 payload ({@link buildMlflowTrace}) is implemented to the published
+ * API spec — OTLP-shaped spans with base64 ids, unix-nano timestamps and
+ * typed attributes — but live verification requires a workspace: run the
+ * live-gated smoke test (`DATABRICKS_LIVE_TEST=1` +
+ * `DATABRICKS_MLFLOW_EXPERIMENT_ID`) against yours before relying on it.
+ *
+ * Both `sink.record` and `onEvent` never throw — failures (including the
+ * async POST) are reported through `onError`.
+ */
+export interface MlflowTraceExporterOptions {
+    client: DatabricksRestClient;
+    /** MLflow experiment receiving the traces. */
+    experimentId: string;
+    /** Failure reporter (default console.error). */
+    onError?: (context: string, error: unknown) => void;
+}
+export interface MlflowTraceExporter {
+    /** Wire into `createSubmissionRunner({ telemetry })`. */
+    sink: SubmissionTelemetrySink;
+    /** Fan in with the app's `onEvent` to capture per-turn/tool spans. */
+    onEvent: (event: FabricEvent) => void;
+}
+export declare function mlflowTraceExporter(options: MlflowTraceExporterOptions): MlflowTraceExporter;
+export interface MlflowTraceInput {
+    submissionId: string;
+    agent: string;
+    instanceId: string;
+    session: string;
+    experimentId: string;
+    /** Epoch ms when the submission started executing. */
+    startedAtMs: number;
+    /** Epoch ms when the submission settled. */
+    settledAtMs: number;
+    state: 'OK' | 'ERROR';
+    /** Child spans (from `eventToTelemetrySpan`) buffered during execution. */
+    spans: TelemetrySpan[];
+    attemptCount?: number;
+    tenantId?: string;
+    error?: string;
+}
+interface OtlpAttribute {
+    key: string;
+    value: {
+        string_value: string;
+    } | {
+        double_value: number;
+    } | {
+        int_value: string;
+    };
+}
+interface MlflowSpan {
+    trace_id: string;
+    span_id: string;
+    parent_span_id?: string;
+    name: string;
+    start_time_unix_nano: string;
+    end_time_unix_nano: string;
+    attributes: OtlpAttribute[];
+    status: {
+        code: 'STATUS_CODE_OK' | 'STATUS_CODE_ERROR';
+        message?: string;
+    };
+}
+export interface MlflowTracePayload {
+    trace: {
+        trace_info: {
+            trace_id: string;
+            trace_location: {
+                type: 'MLFLOW_EXPERIMENT';
+                mlflow_experiment: {
+                    experiment_id: string;
+                };
+            };
+            request_time: string;
+            execution_duration: string;
+            state: 'OK' | 'ERROR';
+            trace_metadata: Record<string, string>;
+            tags: Record<string, string>;
+        };
+        trace_data: {
+            spans: MlflowSpan[];
+        };
+    };
+}
+/**
+ * Build the MLflow V3 `POST /api/3.0/mlflow/traces` payload for one settled
+ * submission. Pure and deterministic: trace/span ids derive from the
+ * submission id (+ span index) via SHA-256, so replaying the same settled
+ * submission produces byte-identical ids. The root span covers the whole
+ * submission; buffered {@link TelemetrySpan}s become its children.
+ */
+export declare function buildMlflowTrace(input: MlflowTraceInput): MlflowTracePayload;
+export {};
+//# sourceMappingURL=mlflow-tracing.d.ts.map

package/dist/mlflow-tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mlflow-tracing.d.ts","sourceRoot":"","sources":["../src/mlflow-tracing.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,WAAW,EACX,uBAAuB,EACvB,aAAa,EACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACrD;AAED,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,IAAI,EAAE,uBAAuB,CAAC;IAC9B,sEAAsE;IACtE,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;CACvC;AAaD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,mBAAmB,CAoE5F;AAID,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC;IACtB,2EAA2E;IAC3E,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,aAAa;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACpF;AAED,UAAU,UAAU;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,MAAM,EAAE;QAAE,IAAI,EAAE,gBAAgB,GAAG,mBAAmB,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5E;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE;QACL,UAAU,EAAE;YACV,QAAQ,EAAE,MAAM,CAAC;YACjB,cAAc,EAAE;gBACd,IAAI,EAAE,mBAAmB,CAAC;gBAC1B,iBAAiB,EAAE;oBAAE,aAAa,EAAE,MAAM,CAAA;iBAAE,CAAC;aAC9C,CAAC;YACF,YAAY,EAAE,MAAM,CAAC;YACrB,kBAAkB,EAAE,MAAM,CAAC;YAC3B,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC;YACtB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YACvC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;SAC9B,CAAC;QACF,UAAU,EAAE;YAAE,KAAK,EAAE,UAAU,EAAE,CAAA;SAAE,CAAC;KACrC,CAAC;CACH;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,kBAAkB,CAmE5E"}

package/dist/mlflow-tracing.js

@@ -0,0 +1,167 @@
+import { createHash } from 'node:crypto';
+import { eventToTelemetrySpan } from '@fabric-harness/sdk';
+export function mlflowTraceExporter(options) {
+    const onError = options.onError ??
+        ((context, error) => {
+            console.error(`[fabric-harness:mlflow-tracing] ${context}:`, error);
+        });
+    /** Open buffers keyed by store session id (`agent:<agent>:<instanceId>:<session>`). */
+    const buffers = new Map();
+    return {
+        sink: {
+            record(event) {
+                try {
+                    const key = `agent:${event.agent}:${event.instanceId}:${event.session}`;
+                    if (event.type === 'submission_started') {
+                        buffers.set(key, {
+                            submissionId: event.submissionId,
+                            agent: event.agent,
+                            instanceId: event.instanceId,
+                            session: event.session,
+                            startedAtMs: event.at,
+                            attemptCount: event.attemptCount,
+                            ...(event.tenantId !== undefined ? { tenantId: event.tenantId } : {}),
+                            spans: [],
+                        });
+                        return;
+                    }
+                    if (event.type !== 'submission_settled')
+                        return;
+                    const buffer = buffers.get(key);
+                    buffers.delete(key);
+                    // Settlement without an observed start (exporter attached late) still
+                    // produces a trace: derive the start from the settlement duration.
+                    const startedAtMs = buffer?.startedAtMs ?? event.at - (event.durationMs ?? 0);
+                    const attemptCount = event.attemptCount ?? buffer?.attemptCount;
+                    const trace = buildMlflowTrace({
+                        submissionId: event.submissionId,
+                        agent: event.agent,
+                        instanceId: event.instanceId,
+                        session: event.session,
+                        experimentId: options.experimentId,
+                        startedAtMs,
+                        settledAtMs: event.at,
+                        state: event.outcome === 'completed' ? 'OK' : 'ERROR',
+                        spans: buffer?.spans ?? [],
+                        ...(attemptCount !== undefined ? { attemptCount } : {}),
+                        ...(event.tenantId !== undefined ? { tenantId: event.tenantId } : {}),
+                        ...(event.error !== undefined ? { error: event.error } : {}),
+                    });
+                    void options.client
+                        .post('/api/3.0/mlflow/traces', trace)
+                        .catch((error) => onError(`trace export failed for ${event.submissionId}`, error));
+                }
+                catch (error) {
+                    onError('telemetry event handling failed', error);
+                }
+            },
+        },
+        onEvent(event) {
+            try {
+                if (!event.sessionId)
+                    return;
+                const buffer = buffers.get(event.sessionId);
+                if (!buffer)
+                    return;
+                const span = eventToTelemetrySpan(event);
+                if (span)
+                    buffer.spans.push(span);
+            }
+            catch (error) {
+                onError('event buffering failed', error);
+            }
+        },
+    };
+}
+/**
+ * Build the MLflow V3 `POST /api/3.0/mlflow/traces` payload for one settled
+ * submission. Pure and deterministic: trace/span ids derive from the
+ * submission id (+ span index) via SHA-256, so replaying the same settled
+ * submission produces byte-identical ids. The root span covers the whole
+ * submission; buffered {@link TelemetrySpan}s become its children.
+ */
+export function buildMlflowTrace(input) {
+    const traceBytes = sha256(input.submissionId).subarray(0, 16);
+    const traceIdBase64 = traceBytes.toString('base64');
+    const rootSpanId = spanIdFor(input.submissionId, 0);
+    const durationSeconds = Math.max(0, input.settledAtMs - input.startedAtMs) / 1000;
+    const rootSpan = {
+        trace_id: traceIdBase64,
+        span_id: rootSpanId,
+        name: `fabric.submission ${input.agent}`,
+        start_time_unix_nano: toUnixNano(input.startedAtMs),
+        end_time_unix_nano: toUnixNano(input.settledAtMs),
+        attributes: toOtlpAttributes({
+            'fabric.submission_id': input.submissionId,
+            'fabric.agent': input.agent,
+            'fabric.instance_id': input.instanceId,
+            'fabric.session': input.session,
+            ...(input.attemptCount !== undefined ? { 'fabric.attempt_count': input.attemptCount } : {}),
+            ...(input.error !== undefined ? { 'fabric.error': input.error } : {}),
+        }),
+        status: {
+            code: input.state === 'OK' ? 'STATUS_CODE_OK' : 'STATUS_CODE_ERROR',
+            ...(input.error !== undefined ? { message: input.error } : {}),
+        },
+    };
+    const childSpans = input.spans.map((span, index) => ({
+        trace_id: traceIdBase64,
+        span_id: spanIdFor(input.submissionId, index + 1),
+        parent_span_id: rootSpanId,
+        name: span.name,
+        start_time_unix_nano: toUnixNano(Date.parse(span.startedAt)),
+        end_time_unix_nano: toUnixNano(Date.parse(span.endedAt)),
+        attributes: toOtlpAttributes(span.attributes),
+        status: { code: 'STATUS_CODE_OK' },
+    }));
+    return {
+        trace: {
+            trace_info: {
+                trace_id: `tr-${traceBytes.toString('hex')}`,
+                trace_location: {
+                    type: 'MLFLOW_EXPERIMENT',
+                    mlflow_experiment: { experiment_id: input.experimentId },
+                },
+                request_time: new Date(input.startedAtMs).toISOString(),
+                execution_duration: `${durationSeconds.toFixed(3)}s`,
+                state: input.state,
+                trace_metadata: {
+                    'fabric.submission_id': input.submissionId,
+                    'fabric.agent': input.agent,
+                    'fabric.instance_id': input.instanceId,
+                    'fabric.session': input.session,
+                    ...(input.attemptCount !== undefined
+                        ? { 'fabric.attempt_count': String(input.attemptCount) }
+                        : {}),
+                },
+                tags: {
+                    'fabric.agent': input.agent,
+                    ...(input.tenantId !== undefined ? { 'fabric.tenant_id': input.tenantId } : {}),
+                },
+            },
+            trace_data: { spans: [rootSpan, ...childSpans] },
+        },
+    };
+}
+function sha256(seed) {
+    return createHash('sha256').update(seed).digest();
+}
+/** Deterministic 8-byte OTLP span id: sha-256 of `<submissionId>:span:<index>`. Index 0 is the root. */
+function spanIdFor(submissionId, index) {
+    return sha256(`${submissionId}:span:${index}`).subarray(0, 8).toString('base64');
+}
+function toUnixNano(epochMs) {
+    return `${Math.round(epochMs)}000000`;
+}
+function toOtlpAttributes(attributes) {
+    return Object.entries(attributes).map(([key, value]) => {
+        if (typeof value === 'number') {
+            // OTLP proto3 JSON mapping: int64 serializes as a string.
+            return Number.isInteger(value)
+                ? { key, value: { int_value: String(value) } }
+                : { key, value: { double_value: value } };
+        }
+        return { key, value: { string_value: String(value) } };
+    });
+}
+//# sourceMappingURL=mlflow-tracing.js.map

package/dist/mlflow-tracing.js.map

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

package/dist/persistence.d.ts

@@ -0,0 +1,73 @@
+import type { AgentSubmissionStore, ConversationStreamStore, PersistenceAdapter, SessionStore } from '@fabric-harness/sdk';
+import type { LakebaseClient, LakebaseClientOptions } from './lakebase.js';
+/**
+ * The slice of `@fabric-harness/node` this adapter assembles. Loaded
+ * dynamically (node is an optional peer — Databricks Apps always run on
+ * Node, but this package stays importable without it); injectable for tests.
+ */
+export interface DatabricksPersistenceStoreModule {
+    PostgresSessionStore: new (options: {
+        client: LakebaseClient;
+        initialize?: boolean;
+    }) => SessionStore;
+    PostgresSubmissionStore: new (options: {
+        client: LakebaseClient;
+        initialize?: boolean;
+    }) => AgentSubmissionStore;
+    PostgresConversationStreamStore: new (options: {
+        client: LakebaseClient;
+        initialize?: boolean;
+    }) => ConversationStreamStore;
+    ensurePostgresSubmissionTables(client: LakebaseClient): Promise<void>;
+    ensurePostgresConversationStreamTables(client: LakebaseClient): Promise<void>;
+}
+export interface DatabricksPersistenceOptions {
+    /**
+     * Lakebase connection options (rotating-OAuth `token` supported), or an
+     * already-constructed client to reuse.
+     */
+    lakebase: LakebaseClientOptions | LakebaseClient;
+    /** Override the `@fabric-harness/node` loader (tests / bundlers). */
+    loadStores?: () => Promise<DatabricksPersistenceStoreModule>;
+}
+/**
+ * Everything the v2 runtime persists, on Lakebase, in one adapter:
+ * sessions (canonical conversation state), durable agent submissions
+ * (admission/FIFO/leases/settlement), and offset-addressable conversation
+ * streams. Implements the SDK {@link PersistenceAdapter} contract, so it
+ * plugs straight into `init({ persistence })`; the extra `connect*` methods
+ * feed `startDevServer({ submissionStore, conversationStreamStore })`.
+ */
+export interface DatabricksPersistence extends PersistenceAdapter {
+    readonly client: LakebaseClient;
+    connect(): Promise<SessionStore>;
+    connectSubmissionStore(): Promise<AgentSubmissionStore>;
+    connectConversationStreamStore(): Promise<ConversationStreamStore>;
+    /** All three stores in one call (server wiring convenience). */
+    connectAll(): Promise<{
+        store: SessionStore;
+        submissionStore: AgentSubmissionStore;
+        conversationStreamStore: ConversationStreamStore;
+    }>;
+    /** Idempotent schema setup for every store (CREATE TABLE IF NOT EXISTS). */
+    migrate(): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * One-call Lakebase persistence for Databricks-hosted agents.
+ *
+ * ```ts
+ * const persistence = databricksPersistence({
+ *   lakebase: { host, database: 'fabric', user: clientId, token: identity },
+ * });
+ * const { store, submissionStore, conversationStreamStore } = await persistence.connectAll();
+ * await startDevServer({ submissionStore, conversationStreamStore });
+ * ```
+ *
+ * The Postgres store implementations come from `@fabric-harness/node`
+ * (optional peer) and run unchanged against Lakebase — the only Databricks
+ * specifics are the rotating-token pool and TLS defaults from
+ * {@link lakebaseClient}.
+ */
+export declare function databricksPersistence(options: DatabricksPersistenceOptions): DatabricksPersistence;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../src/persistence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAClB,YAAY,EACb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE3E;;;;GAIG;AACH,MAAM,WAAW,gCAAgC;IAC/C,oBAAoB,EAAE,KAAK,OAAO,EAAE;QAAE,MAAM,EAAE,cAAc,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,YAAY,CAAC;IACtG,uBAAuB,EAAE,KAAK,OAAO,EAAE;QAAE,MAAM,EAAE,cAAc,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,oBAAoB,CAAC;IACjH,+BAA+B,EAAE,KAAK,OAAO,EAAE;QAAE,MAAM,EAAE,cAAc,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,uBAAuB,CAAC;IAC5H,8BAA8B,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,sCAAsC,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,QAAQ,EAAE,qBAAqB,GAAG,cAAc,CAAC;IACjD,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,gCAAgC,CAAC,CAAC;CAC9D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,OAAO,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;IACjC,sBAAsB,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACxD,8BAA8B,IAAI,OAAO,CAAC,uBAAuB,CAAC,CAAC;IACnE,gEAAgE;IAChE,UAAU,IAAI,OAAO,CAAC;QACpB,KAAK,EAAE,YAAY,CAAC;QACpB,eAAe,EAAE,oBAAoB,CAAC;QACtC,uBAAuB,EAAE,uBAAuB,CAAC;KAClD,CAAC,CAAC;IACH,4EAA4E;IAC5E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,qBAAqB,CA2DlG"}

package/dist/persistence.js

@@ -0,0 +1,82 @@
+import { lakebaseClient } from './lakebase.js';
+/**
+ * One-call Lakebase persistence for Databricks-hosted agents.
+ *
+ * ```ts
+ * const persistence = databricksPersistence({
+ *   lakebase: { host, database: 'fabric', user: clientId, token: identity },
+ * });
+ * const { store, submissionStore, conversationStreamStore } = await persistence.connectAll();
+ * await startDevServer({ submissionStore, conversationStreamStore });
+ * ```
+ *
+ * The Postgres store implementations come from `@fabric-harness/node`
+ * (optional peer) and run unchanged against Lakebase — the only Databricks
+ * specifics are the rotating-token pool and TLS defaults from
+ * {@link lakebaseClient}.
+ */
+export function databricksPersistence(options) {
+    const client = isLakebaseClient(options.lakebase) ? options.lakebase : lakebaseClient(options.lakebase);
+    const ownsClient = !isLakebaseClient(options.lakebase);
+    const loadStores = options.loadStores ?? defaultStoreLoader;
+    let modulePromise;
+    const stores = () => {
+        modulePromise ??= loadStores();
+        return modulePromise;
+    };
+    let sessionStore;
+    let submissionStore;
+    let conversationStreamStore;
+    const persistence = {
+        client,
+        async connect() {
+            const module = await stores();
+            sessionStore ??= new module.PostgresSessionStore({ client });
+            return sessionStore;
+        },
+        async connectSubmissionStore() {
+            const module = await stores();
+            submissionStore ??= new module.PostgresSubmissionStore({ client });
+            return submissionStore;
+        },
+        async connectConversationStreamStore() {
+            const module = await stores();
+            conversationStreamStore ??= new module.PostgresConversationStreamStore({ client });
+            return conversationStreamStore;
+        },
+        async connectAll() {
+            return {
+                store: await persistence.connect(),
+                submissionStore: await persistence.connectSubmissionStore(),
+                conversationStreamStore: await persistence.connectConversationStreamStore(),
+            };
+        },
+        async migrate() {
+            const module = await stores();
+            // Session tables initialize inside the store constructor; the
+            // submission/stream ensure functions are exported directly.
+            await persistence.connect();
+            await module.ensurePostgresSubmissionTables(client);
+            await module.ensurePostgresConversationStreamTables(client);
+        },
+        async close() {
+            if (ownsClient)
+                await client.end();
+        },
+    };
+    return persistence;
+}
+function isLakebaseClient(value) {
+    return typeof value.query === 'function';
+}
+async function defaultStoreLoader() {
+    try {
+        // Dynamic specifier keeps bundlers from hard-wiring the optional peer.
+        const specifier = '@fabric-harness/node';
+        return (await import(specifier));
+    }
+    catch (error) {
+        throw new Error(`databricksPersistence() requires the optional "@fabric-harness/node" package (it provides the Postgres store implementations). Install it alongside @fabric-harness/databricks. ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+//# sourceMappingURL=persistence.js.map

package/dist/persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../src/persistence.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAkD/C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAqC;IACzE,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACxG,MAAM,UAAU,GAAG,CAAC,gBAAgB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,kBAAkB,CAAC;IAE5D,IAAI,aAAoE,CAAC;IACzE,MAAM,MAAM,GAAG,GAAG,EAAE;QAClB,aAAa,KAAK,UAAU,EAAE,CAAC;QAC/B,OAAO,aAAa,CAAC;IACvB,CAAC,CAAC;IAEF,IAAI,YAAsC,CAAC;IAC3C,IAAI,eAAiD,CAAC;IACtD,IAAI,uBAA4D,CAAC;IAEjE,MAAM,WAAW,GAA0B;QACzC,MAAM;QAEN,KAAK,CAAC,OAAO;YACX,MAAM,MAAM,GAAG,MAAM,MAAM,EAAE,CAAC;YAC9B,YAAY,KAAK,IAAI,MAAM,CAAC,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;YAC7D,OAAO,YAAY,CAAC;QACtB,CAAC;QAED,KAAK,CAAC,sBAAsB;YAC1B,MAAM,MAAM,GAAG,MAAM,MAAM,EAAE,CAAC;YAC9B,eAAe,KAAK,IAAI,MAAM,CAAC,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;YACnE,OAAO,eAAe,CAAC;QACzB,CAAC;QAED,KAAK,CAAC,8BAA8B;YAClC,MAAM,MAAM,GAAG,MAAM,MAAM,EAAE,CAAC;YAC9B,uBAAuB,KAAK,IAAI,MAAM,CAAC,+BAA+B,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;YACnF,OAAO,uBAAuB,CAAC;QACjC,CAAC;QAED,KAAK,CAAC,UAAU;YACd,OAAO;gBACL,KAAK,EAAE,MAAM,WAAW,CAAC,OAAO,EAAE;gBAClC,eAAe,EAAE,MAAM,WAAW,CAAC,sBAAsB,EAAE;gBAC3D,uBAAuB,EAAE,MAAM,WAAW,CAAC,8BAA8B,EAAE;aAC5E,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,OAAO;YACX,MAAM,MAAM,GAAG,MAAM,MAAM,EAAE,CAAC;YAC9B,8DAA8D;YAC9D,4DAA4D;YAC5D,MAAM,WAAW,CAAC,OAAO,EAAE,CAAC;YAC5B,MAAM,MAAM,CAAC,8BAA8B,CAAC,MAAM,CAAC,CAAC;YACpD,MAAM,MAAM,CAAC,sCAAsC,CAAC,MAAM,CAAC,CAAC;QAC9D,CAAC;QAED,KAAK,CAAC,KAAK;YACT,IAAI,UAAU;gBAAE,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC;QACrC,CAAC;KACF,CAAC;IAEF,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,SAAS,gBAAgB,CAAC,KAA+C;IACvE,OAAO,OAAQ,KAAwB,CAAC,KAAK,KAAK,UAAU,CAAC;AAC/D,CAAC;AAED,KAAK,UAAU,kBAAkB;IAC/B,IAAI,CAAC;QACH,uEAAuE;QACvE,MAAM,SAAS,GAAG,sBAAsB,CAAC;QACzC,OAAO,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,CAAgD,CAAC;IAClF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,mLAAmL,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAC5O,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/serving-usage.d.ts

@@ -0,0 +1,48 @@
+import type { FabricEvent, SubmissionTelemetrySink } from '@fabric-harness/sdk';
+/**
+ * Serving usage capture (v2 migration, workstream C7): attribute model/serving
+ * spend to submissions through the ambient submission context.
+ */
+export interface ServingUsageCaptureOptions {
+    /** Telemetry sink receiving `submission_usage` events (e.g. `databricksTelemetry().sink`). */
+    sink: SubmissionTelemetrySink;
+    /** Failure reporter for sink errors (default: silent, matching fire-and-forget telemetry). */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Build an `onEvent` fan-in that turns model-usage events into
+ * `submission_usage` telemetry. For every {@link FabricEvent} carrying
+ * `data.usage` (`{ inputTokens?, outputTokens?, costUsd? }`, at least one
+ * numeric field) — and optionally `data.model` — while an ambient
+ * {@link currentSubmissionContext} is set, it emits one `submission_usage`
+ * event stamped with the submission correlation (submission/attempt ids,
+ * agent identity, tenant, actor).
+ *
+ * Events observed outside a submission context are dropped silently — not
+ * every session turn belongs to a submission. The submission context does not
+ * carry the submission kind, so emitted events use `kind: 'unknown'`.
+ */
+export declare function servingUsageCapture(options: ServingUsageCaptureOptions): (event: FabricEvent) => void;
+export interface InferenceTableUsageQueryOptions {
+    /** Fully-qualified inference/payload table, `catalog.schema.table`. */
+    fullTableName: string;
+    /** Only aggregate requests at or after this ISO-8601 instant. */
+    sinceIso?: string;
+}
+/**
+ * SQL aggregating a serving endpoint's inference/payload table by
+ * `client_request_id` — one row per submission with the request count and the
+ * first/last request timestamps — for offline joins against
+ * `fh_submission_telemetry.submission_id`.
+ *
+ * Join contract: callers MUST send the submission id as the serving request's
+ * `client_request_id` (e.g. the `client_request_id` field on the
+ * serving-endpoint invocation) — the inference table records it verbatim, and
+ * this query's `submission_id` column only joins when that convention holds.
+ * Rows without a `client_request_id` (traffic from other callers) are
+ * excluded. Assumes the AI Gateway payload-table schema (`request_time`
+ * timestamp column); adapt the projection for classic inference tables that
+ * use `timestamp_ms`.
+ */
+export declare function inferenceTableUsageQuery(options: InferenceTableUsageQueryOptions): string;
+//# sourceMappingURL=serving-usage.d.ts.map

package/dist/serving-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serving-usage.d.ts","sourceRoot":"","sources":["../src/serving-usage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEhF;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,8FAA8F;IAC9F,IAAI,EAAE,uBAAuB,CAAC;IAC9B,8FAA8F;IAC9F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAiCrG;AAuBD,MAAM,WAAW,+BAA+B;IAC9C,uEAAuE;IACvE,aAAa,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,+BAA+B,GAAG,MAAM,CAyBzF"}

package/dist/serving-usage.js

@@ -0,0 +1,100 @@
+import { currentSubmissionContext, emitSubmissionTelemetry } from '@fabric-harness/sdk';
+/**
+ * Build an `onEvent` fan-in that turns model-usage events into
+ * `submission_usage` telemetry. For every {@link FabricEvent} carrying
+ * `data.usage` (`{ inputTokens?, outputTokens?, costUsd? }`, at least one
+ * numeric field) — and optionally `data.model` — while an ambient
+ * {@link currentSubmissionContext} is set, it emits one `submission_usage`
+ * event stamped with the submission correlation (submission/attempt ids,
+ * agent identity, tenant, actor).
+ *
+ * Events observed outside a submission context are dropped silently — not
+ * every session turn belongs to a submission. The submission context does not
+ * carry the submission kind, so emitted events use `kind: 'unknown'`.
+ */
+export function servingUsageCapture(options) {
+    return (event) => {
+        try {
+            const usage = usageOf(event);
+            if (!usage)
+                return;
+            const context = currentSubmissionContext();
+            if (!context)
+                return;
+            const model = typeof event.data?.model === 'string' ? event.data.model : undefined;
+            const at = Date.parse(event.timestamp);
+            emitSubmissionTelemetry(options.sink, {
+                type: 'submission_usage',
+                submissionId: context.submissionId,
+                attemptId: context.attemptId,
+                kind: 'unknown',
+                agent: context.agent,
+                instanceId: context.instanceId,
+                session: context.session,
+                at: Number.isFinite(at) ? at : Date.now(),
+                ...(context.tenantId !== undefined ? { tenantId: context.tenantId } : {}),
+                ...(context.actor !== undefined ? { actor: context.actor } : {}),
+                ...(model !== undefined ? { model } : {}),
+                ...(usage.inputTokens !== undefined ? { inputTokens: usage.inputTokens } : {}),
+                ...(usage.outputTokens !== undefined ? { outputTokens: usage.outputTokens } : {}),
+                ...(usage.costUsd !== undefined ? { costUsd: usage.costUsd } : {}),
+            }, options.onError);
+        }
+        catch (error) {
+            options.onError?.(error);
+        }
+    };
+}
+/** `data.usage` with at least one numeric field, else `undefined`. */
+function usageOf(event) {
+    const raw = event.data?.usage;
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return undefined;
+    const usage = raw;
+    const fields = {
+        ...(typeof usage.inputTokens === 'number' ? { inputTokens: usage.inputTokens } : {}),
+        ...(typeof usage.outputTokens === 'number' ? { outputTokens: usage.outputTokens } : {}),
+        ...(typeof usage.costUsd === 'number' ? { costUsd: usage.costUsd } : {}),
+    };
+    return Object.keys(fields).length > 0 ? fields : undefined;
+}
+/**
+ * SQL aggregating a serving endpoint's inference/payload table by
+ * `client_request_id` — one row per submission with the request count and the
+ * first/last request timestamps — for offline joins against
+ * `fh_submission_telemetry.submission_id`.
+ *
+ * Join contract: callers MUST send the submission id as the serving request's
+ * `client_request_id` (e.g. the `client_request_id` field on the
+ * serving-endpoint invocation) — the inference table records it verbatim, and
+ * this query's `submission_id` column only joins when that convention holds.
+ * Rows without a `client_request_id` (traffic from other callers) are
+ * excluded. Assumes the AI Gateway payload-table schema (`request_time`
+ * timestamp column); adapt the projection for classic inference tables that
+ * use `timestamp_ms`.
+ */
+export function inferenceTableUsageQuery(options) {
+    if (!/^[A-Za-z0-9_]+\.[A-Za-z0-9_]+\.[A-Za-z0-9_]+$/.test(options.fullTableName)) {
+        throw new Error(`databricks serving-usage: fullTableName must be catalog.schema.table, got: ${options.fullTableName}`);
+    }
+    let since = '';
+    if (options.sinceIso !== undefined) {
+        // Strict shape check first — Date.parse alone is far too lenient to gate a SQL literal.
+        const isoShape = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?(Z|[+-]\d{2}:\d{2})$/;
+        const parsed = Date.parse(options.sinceIso);
+        if (!isoShape.test(options.sinceIso) || !Number.isFinite(parsed)) {
+            throw new Error(`databricks serving-usage: sinceIso is not a valid ISO-8601 instant: ${options.sinceIso}`);
+        }
+        since = `\n  AND request_time >= TIMESTAMP '${new Date(parsed).toISOString()}'`;
+    }
+    return `SELECT
+  client_request_id AS submission_id,
+  COUNT(*) AS request_count,
+  MIN(request_time) AS first_request_at,
+  MAX(request_time) AS last_request_at
+FROM ${options.fullTableName}
+WHERE client_request_id IS NOT NULL${since}
+GROUP BY client_request_id
+ORDER BY last_request_at DESC`;
+}
+//# sourceMappingURL=serving-usage.js.map

package/dist/serving-usage.js.map

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

package/dist/telemetry-sink.d.ts

@@ -0,0 +1,29 @@
+import type { SubmissionTelemetrySink } from '@fabric-harness/sdk';
+import type { DatabricksLineageRecord } from './governance.js';
+import type { LakebaseClient } from './lakebase.js';
+/**
+ * Cost + lineage as core telemetry (v2, workstream C4): submission lifecycle
+ * events and governed tool-call lineage land in Lakebase tables keyed by the
+ * same `submissionId` that drives events, settlement, and audit — so spend,
+ * lineage, and outcomes join on one stable key. Writes are fire-and-forget:
+ * a telemetry failure must never affect execution.
+ */
+export interface DatabricksTelemetryOptions {
+    client: LakebaseClient;
+    /** Create the telemetry tables on first use. Default true. */
+    initialize?: boolean;
+    /** Failure reporter (default console.error). */
+    onError?: (context: string, error: unknown) => void;
+}
+export interface DatabricksTelemetry {
+    /** Wire into `createSubmissionRunner({ telemetry })`. */
+    sink: SubmissionTelemetrySink;
+    /** Wire into `withGovernance({ onLineage })` / the `databricks()` bundle. */
+    onLineage: (record: DatabricksLineageRecord) => void;
+    /** Idempotent schema setup (also runs lazily on first write). */
+    migrate(): Promise<void>;
+}
+/** Create the telemetry tables when absent. Idempotent. */
+export declare function ensureDatabricksTelemetryTables(client: LakebaseClient): Promise<void>;
+export declare function databricksTelemetry(options: DatabricksTelemetryOptions): DatabricksTelemetry;
+//# sourceMappingURL=telemetry-sink.d.ts.map