@fabric-harness/databricks 0.16.1 → 1.0.0

package/dist/telemetry-sink.js

@@ -0,0 +1,129 @@
+/** Create the telemetry tables when absent. Idempotent. */
+export async function ensureDatabricksTelemetryTables(client) {
+    await client.query(`CREATE TABLE IF NOT EXISTS fh_submission_telemetry (
+    id BIGSERIAL PRIMARY KEY,
+    submission_id TEXT NOT NULL,
+    event_type TEXT NOT NULL,
+    kind TEXT NOT NULL,
+    agent TEXT NOT NULL,
+    instance_id TEXT NOT NULL,
+    session TEXT NOT NULL,
+    attempt_id TEXT,
+    attempt_count INTEGER,
+    outcome TEXT,
+    error TEXT,
+    duration_ms BIGINT,
+    model TEXT,
+    input_tokens BIGINT,
+    output_tokens BIGINT,
+    cost_usd DOUBLE PRECISION,
+    tenant_id TEXT,
+    principal_kind TEXT,
+    principal_id TEXT,
+    at BIGINT NOT NULL
+  )`);
+    await client.query('CREATE INDEX IF NOT EXISTS fh_submission_telemetry_submission_idx ON fh_submission_telemetry (submission_id)');
+    await client.query(`CREATE TABLE IF NOT EXISTS fh_lineage (
+    id BIGSERIAL PRIMARY KEY,
+    submission_id TEXT,
+    attempt_id TEXT,
+    tool TEXT NOT NULL,
+    service TEXT,
+    provider TEXT,
+    principal TEXT,
+    catalog TEXT,
+    schema_name TEXT,
+    ok BOOLEAN NOT NULL,
+    error TEXT,
+    tenant_id TEXT,
+    input JSONB,
+    started_at TEXT NOT NULL,
+    finished_at TEXT NOT NULL
+  )`);
+    await client.query('CREATE INDEX IF NOT EXISTS fh_lineage_submission_idx ON fh_lineage (submission_id)');
+}
+export function databricksTelemetry(options) {
+    const { client } = options;
+    const onError = options.onError ??
+        ((context, error) => {
+            console.error(`[fabric-harness:databricks-telemetry] ${context}:`, error);
+        });
+    let initialized;
+    const ensure = () => {
+        if (options.initialize === false)
+            return Promise.resolve();
+        initialized ??= ensureDatabricksTelemetryTables(client).catch((error) => {
+            initialized = undefined;
+            throw error;
+        });
+        return initialized;
+    };
+    async function writeEvent(event) {
+        await ensure();
+        const attemptId = 'attemptId' in event ? (event.attemptId ?? null) : null;
+        const attemptCount = 'attemptCount' in event ? (event.attemptCount ?? null) : null;
+        const outcome = event.type === 'submission_settled' ? event.outcome : null;
+        const error = event.type === 'submission_settled' ? (event.error ?? null) : null;
+        const durationMs = event.type === 'submission_settled' ? (event.durationMs ?? null) : null;
+        const model = event.type === 'submission_usage' ? (event.model ?? null) : null;
+        const inputTokens = event.type === 'submission_usage' ? (event.inputTokens ?? null) : null;
+        const outputTokens = event.type === 'submission_usage' ? (event.outputTokens ?? null) : null;
+        const costUsd = event.type === 'submission_usage' ? (event.costUsd ?? null) : null;
+        await client.query(`INSERT INTO fh_submission_telemetry
+        (submission_id, event_type, kind, agent, instance_id, session, attempt_id, attempt_count, outcome, error, duration_ms, model, input_tokens, output_tokens, cost_usd, tenant_id, principal_kind, principal_id, at)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19)`, [
+            event.submissionId,
+            event.type,
+            event.kind,
+            event.agent,
+            event.instanceId,
+            event.session,
+            attemptId,
+            attemptCount,
+            outcome,
+            error,
+            durationMs,
+            model,
+            inputTokens,
+            outputTokens,
+            costUsd,
+            event.tenantId ?? null,
+            event.actor?.principal?.kind ?? null,
+            event.actor?.principal?.id ?? null,
+            event.at,
+        ]);
+    }
+    async function writeLineage(record) {
+        await ensure();
+        await client.query(`INSERT INTO fh_lineage
+        (submission_id, attempt_id, tool, service, provider, principal, catalog, schema_name, ok, error, tenant_id, input, started_at, finished_at)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12::jsonb, $13, $14)`, [
+            record.submissionId ?? null,
+            record.attemptId ?? null,
+            record.tool,
+            record.service ?? null,
+            record.provider ?? null,
+            record.principal ?? null,
+            record.catalog ?? null,
+            record.schema ?? null,
+            record.ok,
+            record.error ?? null,
+            record.tenantId ?? null,
+            JSON.stringify(record.input ?? {}),
+            record.startedAt,
+            record.finishedAt,
+        ]);
+    }
+    return {
+        sink: {
+            record(event) {
+                return writeEvent(event);
+            },
+        },
+        onLineage(record) {
+            void writeLineage(record).catch((error) => onError(`lineage write failed for ${record.tool}`, error));
+        },
+        migrate: ensure,
+    };
+}
+//# sourceMappingURL=telemetry-sink.js.map

package/dist/telemetry-sink.js.map

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

package/dist/tools.d.ts

@@ -0,0 +1,71 @@
+import type { FilesystemSource, JsonObject, ToolDef } from '@fabric-harness/sdk';
+import type { DatabricksRestClient } from './client.js';
+export interface DatabricksSqlToolOptions {
+    warehouseId: string;
+    name?: string;
+    description?: string;
+    waitTimeout?: string;
+    disposition?: 'INLINE' | 'EXTERNAL_LINKS';
+}
+export declare function databricksSqlTool(client: DatabricksRestClient, options: DatabricksSqlToolOptions): ToolDef<{
+    statement: string;
+    catalog?: string;
+    schema?: string;
+}, unknown>;
+export declare function databricksRunJobTool(client: DatabricksRestClient, options?: {
+    name?: string;
+    description?: string;
+}): ToolDef<{
+    jobId: number;
+    notebookParams?: JsonObject;
+    pythonParams?: string[];
+    jarParams?: string[];
+}, unknown>;
+export declare function databricksNotebookTool(client: DatabricksRestClient, options?: {
+    name?: string;
+    description?: string;
+    existingClusterId?: string;
+}): ToolDef<{
+    notebookPath: string;
+    baseParameters?: JsonObject;
+    runName?: string;
+}, unknown>;
+export declare function databricksMlflowLogMetricTool(client: DatabricksRestClient, options?: {
+    name?: string;
+    description?: string;
+}): ToolDef<{
+    runId: string;
+    key: string;
+    value: number;
+    step?: number;
+    timestamp?: number;
+}, unknown>;
+export declare function databricksMlflowLogParamTool(client: DatabricksRestClient, options?: {
+    name?: string;
+    description?: string;
+}): ToolDef<{
+    runId: string;
+    key: string;
+    value: string;
+}, unknown>;
+export declare function unityCatalogTablesTool(client: DatabricksRestClient, options?: {
+    name?: string;
+    description?: string;
+}): ToolDef<{
+    catalog: string;
+    schema: string;
+}, unknown>;
+export declare function databricksTableInfoTool(client: DatabricksRestClient, options?: {
+    name?: string;
+    description?: string;
+}): ToolDef<{
+    fullName: string;
+}, unknown>;
+export interface DatabricksWorkspaceSourceOptions {
+    name?: string;
+    include?: (path: string) => boolean;
+    recursive?: boolean;
+    format?: 'SOURCE' | 'HTML' | 'JUPYTER' | 'DBC';
+}
+export declare function databricksWorkspaceSource(client: DatabricksRestClient, rootPath: string, options?: DatabricksWorkspaceSourceOptions): FilesystemSource;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

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

package/dist/tools.js

@@ -0,0 +1,176 @@
+export function databricksSqlTool(client, options) {
+    return {
+        name: options.name ?? 'databricks_sql',
+        description: options.description ?? 'Run a SQL statement on a Databricks SQL Warehouse.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                statement: { type: 'string' },
+                catalog: { type: 'string' },
+                schema: { type: 'string' },
+            },
+            required: ['statement'],
+        },
+        metadata: { effect: 'execute', provider: 'databricks', service: 'sql' },
+        execute: (input) => client.post('/api/2.0/sql/statements', {
+            warehouse_id: options.warehouseId,
+            statement: input.statement,
+            wait_timeout: options.waitTimeout ?? '30s',
+            disposition: options.disposition ?? 'INLINE',
+            ...(input.catalog ? { catalog: input.catalog } : {}),
+            ...(input.schema ? { schema: input.schema } : {}),
+        }),
+    };
+}
+export function databricksRunJobTool(client, options = {}) {
+    return {
+        name: options.name ?? 'databricks_run_job',
+        description: options.description ?? 'Trigger an existing Databricks job by job id.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                jobId: { type: 'number' },
+                notebookParams: { type: 'object', additionalProperties: true },
+                pythonParams: { type: 'array', items: { type: 'string' } },
+                jarParams: { type: 'array', items: { type: 'string' } },
+            },
+            required: ['jobId'],
+        },
+        metadata: { effect: 'execute', provider: 'databricks', service: 'jobs' },
+        execute: (input) => client.post('/api/2.1/jobs/run-now', {
+            job_id: input.jobId,
+            ...(input.notebookParams ? { notebook_params: input.notebookParams } : {}),
+            ...(input.pythonParams ? { python_params: input.pythonParams } : {}),
+            ...(input.jarParams ? { jar_params: input.jarParams } : {}),
+        }),
+    };
+}
+export function databricksNotebookTool(client, options = {}) {
+    return {
+        name: options.name ?? 'databricks_run_notebook',
+        description: options.description ?? 'Submit a one-off Databricks notebook run.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                notebookPath: { type: 'string' },
+                baseParameters: { type: 'object', additionalProperties: true },
+                runName: { type: 'string' },
+            },
+            required: ['notebookPath'],
+        },
+        metadata: { effect: 'execute', provider: 'databricks', service: 'jobs' },
+        execute: (input) => client.post('/api/2.1/jobs/runs/submit', {
+            run_name: input.runName ?? `fabric-harness:${input.notebookPath}`,
+            ...(options.existingClusterId ? { existing_cluster_id: options.existingClusterId } : {}),
+            notebook_task: {
+                notebook_path: input.notebookPath,
+                ...(input.baseParameters ? { base_parameters: input.baseParameters } : {}),
+            },
+        }),
+    };
+}
+export function databricksMlflowLogMetricTool(client, options = {}) {
+    return {
+        name: options.name ?? 'databricks_mlflow_log_metric',
+        description: options.description ?? 'Log a metric to an MLflow run hosted in Databricks.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                runId: { type: 'string' },
+                key: { type: 'string' },
+                value: { type: 'number' },
+                step: { type: 'number' },
+                timestamp: { type: 'number' },
+            },
+            required: ['runId', 'key', 'value'],
+        },
+        metadata: { effect: 'write', provider: 'databricks', service: 'mlflow' },
+        execute: (input) => client.post('/api/2.0/mlflow/runs/log-metric', {
+            run_id: input.runId,
+            key: input.key,
+            value: input.value,
+            timestamp: input.timestamp ?? Date.now(),
+            ...(input.step !== undefined ? { step: input.step } : {}),
+        }),
+    };
+}
+export function databricksMlflowLogParamTool(client, options = {}) {
+    return {
+        name: options.name ?? 'databricks_mlflow_log_param',
+        description: options.description ?? 'Log a parameter to an MLflow run hosted in Databricks.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: { runId: { type: 'string' }, key: { type: 'string' }, value: { type: 'string' } },
+            required: ['runId', 'key', 'value'],
+        },
+        metadata: { effect: 'write', provider: 'databricks', service: 'mlflow' },
+        execute: (input) => client.post('/api/2.0/mlflow/runs/log-parameter', { run_id: input.runId, key: input.key, value: input.value }),
+    };
+}
+export function unityCatalogTablesTool(client, options = {}) {
+    return {
+        name: options.name ?? 'databricks_unity_catalog_tables',
+        description: options.description ?? 'List Unity Catalog tables in a catalog and schema.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: { catalog: { type: 'string' }, schema: { type: 'string' } },
+            required: ['catalog', 'schema'],
+        },
+        metadata: { effect: 'read', provider: 'databricks', service: 'unity-catalog' },
+        execute: (input) => client.get('/api/2.1/unity-catalog/tables', { catalog_name: input.catalog, schema_name: input.schema }),
+    };
+}
+export function databricksTableInfoTool(client, options = {}) {
+    return {
+        name: options.name ?? 'databricks_table_info',
+        description: options.description ?? 'Describe a Unity Catalog table (columns, types, comment) by its full name (catalog.schema.table).',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: { fullName: { type: 'string' } },
+            required: ['fullName'],
+        },
+        metadata: { effect: 'read', provider: 'databricks', service: 'unity-catalog' },
+        execute: (input) => client.get(`/api/2.1/unity-catalog/tables/${encodeURIComponent(input.fullName)}`),
+    };
+}
+export function databricksWorkspaceSource(client, rootPath, options = {}) {
+    const include = options.include ?? (() => true);
+    return {
+        name: options.name ?? `databricks-workspace:${rootPath}`,
+        async *entries() {
+            yield* walkWorkspace(client, rootPath, rootPath, include, options.recursive ?? true, options.format ?? 'SOURCE');
+        },
+    };
+}
+async function* walkWorkspace(client, root, current, include, recursive, format) {
+    const listing = await client.get('/api/2.0/workspace/list', { path: current });
+    for (const object of listing.objects ?? []) {
+        if (object.object_type === 'DIRECTORY') {
+            if (recursive)
+                yield* walkWorkspace(client, root, object.path, include, recursive, format);
+            continue;
+        }
+        const relative = object.path.slice(root.length).replace(/^\/+/, '');
+        if (!relative || !include(relative))
+            continue;
+        const exported = await client.get('/api/2.0/workspace/export', { path: object.path, format });
+        yield { path: relative, content: exported.content ? base64ToBytes(exported.content) : new Uint8Array() };
+    }
+}
+function base64ToBytes(value) {
+    if (typeof Buffer !== 'undefined')
+        return new Uint8Array(Buffer.from(value, 'base64'));
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

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

package/dist/vector-search.d.ts

@@ -0,0 +1,24 @@
+import type { EmbeddingProvider, Retriever } from '@fabric-harness/sdk';
+import type { DatabricksRestClient } from './client.js';
+export interface DatabricksVectorSearchOptions {
+    client: DatabricksRestClient;
+    /** Full index name: `catalog.schema.index`. */
+    index: string;
+    /** Column that holds the chunk text returned to the model. */
+    textColumn: string;
+    /** Columns to retrieve. Defaults to `[textColumn]` plus `idColumn` when set. */
+    columns?: string[];
+    /** Column to surface as `RetrievedChunk.id`. */
+    idColumn?: string;
+    /**
+     * `'text'` (default) for Databricks-managed-embedding indexes (send `query_text`); `'vector'` for
+     * self-managed / direct-access indexes (embed the query via `embeddings` and send `query_vector`).
+     */
+    queryType?: 'text' | 'vector';
+    /** Required when `queryType: 'vector'`. */
+    embeddings?: EmbeddingProvider;
+    name?: string;
+}
+/** Databricks Mosaic AI Vector Search as a {@link Retriever}. Runs under the bundle's UC principal. */
+export declare function databricksVectorSearch(options: DatabricksVectorSearchOptions): Retriever;
+//# sourceMappingURL=vector-search.d.ts.map

package/dist/vector-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-search.d.ts","sourceRoot":"","sources":["../src/vector-search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAA+C,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,oBAAoB,CAAC;IAC7B,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC9B,2CAA2C;IAC3C,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AASD,uGAAuG;AACvG,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,6BAA6B,GAAG,SAAS,CAyBxF"}

package/dist/vector-search.js

@@ -0,0 +1,63 @@
+const SCORE_COLUMN = 'score';
+/** Databricks Mosaic AI Vector Search as a {@link Retriever}. Runs under the bundle's UC principal. */
+export function databricksVectorSearch(options) {
+    const queryType = options.queryType ?? 'text';
+    const columns = options.columns ?? dedupe([options.textColumn, ...(options.idColumn ? [options.idColumn] : [])]);
+    return {
+        name: options.name ?? `databricks-vector-search:${options.index}`,
+        async retrieve(query, opts = {}) {
+            const body = { columns, num_results: opts.k ?? 5 };
+            if (opts.filter)
+                body.filters_json = JSON.stringify(opts.filter);
+            if (queryType === 'vector') {
+                if (!options.embeddings)
+                    throw new Error('databricks vector search: queryType "vector" requires an embeddings provider.');
+                const [vector] = await options.embeddings.embed([query]);
+                if (!vector)
+                    throw new Error('databricks vector search: embeddings returned no vector for the query.');
+                body.query_vector = vector;
+            }
+            else {
+                body.query_text = query;
+            }
+            const response = await options.client.post(`/api/2.0/vector-search/indexes/${encodeURIComponent(options.index)}/query`, body);
+            return mapResults(response, options, columns);
+        },
+    };
+}
+function mapResults(response, options, requestedColumns) {
+    const names = (response.manifest?.columns ?? []).map((c) => c.name);
+    const requested = new Set(requestedColumns);
+    // Identify the score column: a literal `score`, else a single trailing column the response
+    // appended beyond what we requested (Databricks adds the similarity score). Never treat a
+    // requested column as the score — that would mis-attribute a numeric metadata field.
+    const lastName = names[names.length - 1];
+    const scoreColumn = names.includes(SCORE_COLUMN)
+        ? SCORE_COLUMN
+        : (lastName && !requested.has(lastName) ? lastName : undefined);
+    const rows = response.result?.data_array ?? [];
+    return rows.map((row) => {
+        const record = {};
+        names.forEach((name, i) => { record[name] = row[i]; });
+        const text = String(record[options.textColumn] ?? '');
+        const scoreRaw = scoreColumn ? record[scoreColumn] : undefined;
+        const score = typeof scoreRaw === 'number' ? scoreRaw : undefined;
+        const idRaw = options.idColumn ? record[options.idColumn] : undefined;
+        const metadata = { ...record };
+        delete metadata[options.textColumn];
+        if (scoreColumn)
+            delete metadata[scoreColumn];
+        if (options.idColumn)
+            delete metadata[options.idColumn];
+        return {
+            ...(idRaw != null ? { id: String(idRaw) } : {}),
+            text,
+            ...(score !== undefined ? { score } : {}),
+            metadata,
+        };
+    });
+}
+function dedupe(values) {
+    return [...new Set(values)];
+}
+//# sourceMappingURL=vector-search.js.map

package/dist/vector-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-search.js","sourceRoot":"","sources":["../src/vector-search.ts"],"names":[],"mappings":"AA4BA,MAAM,YAAY,GAAG,OAAO,CAAC;AAE7B,uGAAuG;AACvG,MAAM,UAAU,sBAAsB,CAAC,OAAsC;IAC3E,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC;IAC9C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAEjH,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,4BAA4B,OAAO,CAAC,KAAK,EAAE;QACjE,KAAK,CAAC,QAAQ,CAAC,KAAa,EAAE,OAAwB,EAAE;YACtD,MAAM,IAAI,GAAe,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/D,IAAI,IAAI,CAAC,MAAM;gBAAE,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACjE,IAAI,SAAS,KAAK,QAAQ,EAAE,CAAC;gBAC3B,IAAI,CAAC,OAAO,CAAC,UAAU;oBAAE,MAAM,IAAI,KAAK,CAAC,+EAA+E,CAAC,CAAC;gBAC1H,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;gBACzD,IAAI,CAAC,MAAM;oBAAE,MAAM,IAAI,KAAK,CAAC,wEAAwE,CAAC,CAAC;gBACvG,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC;YAC7B,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;YAC1B,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,IAAI,CACxC,kCAAkC,kBAAkB,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,EAC3E,IAAI,CACL,CAAC;YACF,OAAO,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAChD,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,QAAmC,EAAE,OAAsC,EAAE,gBAA0B;IACzH,MAAM,KAAK,GAAG,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACpE,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC5C,2FAA2F;IAC3F,0FAA0F;IAC1F,qFAAqF;IACrF,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACzC,MAAM,WAAW,GAAG,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC;QAC9C,CAAC,CAAC,YAAY;QACd,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAElE,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,EAAE,UAAU,IAAI,EAAE,CAAC;IAC/C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACtB,MAAM,MAAM,GAAe,EAAE,CAAC;QAC9B,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAuB,CAAC,CAAC,CAAC,CAAC,CAAC;QAE7E,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;QACtD,MAAM,QAAQ,GAAG,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC/D,MAAM,KAAK,GAAG,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;QAClE,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAEtE,MAAM,QAAQ,GAAe,EAAE,GAAG,MAAM,EAAE,CAAC;QAC3C,OAAO,QAAQ,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACpC,IAAI,WAAW;YAAE,OAAO,QAAQ,CAAC,WAAW,CAAC,CAAC;QAC9C,IAAI,OAAO,CAAC,QAAQ;YAAE,OAAO,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAExD,OAAO;YACL,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/C,IAAI;YACJ,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzC,QAAQ;SACT,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,MAAM,CAAC,MAAgB;IAC9B,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;AAC9B,CAAC"}

package/dist/volumes-attachment-store.d.ts

@@ -0,0 +1,64 @@
+import type { AttachmentPutInput, AttachmentRef, AttachmentStore, StoredAttachment } from '@fabric-harness/sdk';
+/**
+ * Unity Catalog Volumes attachment backend (v2 migration, workstream C2).
+ *
+ * Implements the SDK {@link AttachmentStore} contract on a UC Volume via the
+ * Databricks Files API, so attachment bytes are governed by Unity Catalog
+ * grants like every other Databricks asset. Layout under the volume:
+ *
+ * ```
+ * /Volumes/<catalog>/<schema>/<volume>/<rootPrefix>/<encodeURIComponent(scope)>/<digest[0:2]>/<digest>
+ * /Volumes/<catalog>/<schema>/<volume>/<rootPrefix>/<encodeURIComponent(scope)>/<digest[0:2]>/<digest>.json
+ * ```
+ *
+ * The bare `<digest>` file holds the raw bytes; the `<digest>.json` sidecar
+ * holds the {@link AttachmentRef} metadata and doubles as the record's
+ * existence marker: `put` is first-write-wins per `(scope, digest)` — when the
+ * sidecar already exists the put is a no-op, so the first stored ref metadata
+ * is retained (contract semantics).
+ *
+ * The JSON-only `DatabricksRestClient` cannot carry raw request/response
+ * bodies, so this store uses its own minimal fetch path with per-request
+ * bearer-token resolution (mirroring the client's rotating-token handling).
+ * Requests are single-shot (no transport retries) — the harness treats
+ * attachment materialization failures as submission admission failures and
+ * retries at that level.
+ */
+export interface UcVolumesAttachmentStoreOptions {
+    /** Workspace host, e.g. `https://adb-1234567890.0.cloud.databricks.com`. */
+    host: string;
+    /** Static PAT or rotating token resolver (resolved per request). */
+    token: string | (() => string | Promise<string>);
+    catalog: string;
+    schema: string;
+    volume: string;
+    /** Directory under the volume root holding all attachments. Default `fh-attachments`. */
+    rootPrefix?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare class UcVolumesAttachmentStore implements AttachmentStore {
+    private readonly host;
+    private readonly token;
+    private readonly fetchImpl;
+    private readonly volumeRoot;
+    private readonly rootPrefix;
+    constructor(options: UcVolumesAttachmentStoreOptions);
+    put(input: AttachmentPutInput): Promise<void>;
+    get(scope: string, digest: string): Promise<StoredAttachment | null>;
+    getByAttachmentId(scope: string, attachmentId: string): Promise<StoredAttachment | null>;
+    list(scope: string): Promise<AttachmentRef[]>;
+    delete(scope: string, digest: string): Promise<void>;
+    private scopeDir;
+    private bytesPath;
+    private refPath;
+    private writeFile;
+    /** Raw file bytes, or `null` when the file does not exist (404). */
+    private readFile;
+    /** True when the file existed and was deleted; false on 404. */
+    private deleteFile;
+    /** Immediate children of a directory; empty for a missing directory (404). */
+    private listDirectory;
+    private request;
+    private fail;
+}
+//# sourceMappingURL=volumes-attachment-store.d.ts.map

package/dist/volumes-attachment-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"volumes-attachment-store.d.ts","sourceRoot":"","sources":["../src/volumes-attachment-store.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,gBAAgB,EACjB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,+BAA+B;IAC9C,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAaD,qBAAa,wBAAyB,YAAW,eAAe;IAC9D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2C;IACjE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,OAAO,EAAE,+BAA+B;IAQ9C,GAAG,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAUpE,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAOxF,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAa7C,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW1D,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,OAAO;YAMD,SAAS;IAQvB,oEAAoE;YACtD,QAAQ;IAOtB,gEAAgE;YAClD,UAAU;IAOxB,8EAA8E;YAChE,aAAa;YAgBb,OAAO;YAqBP,IAAI;CAOnB"}