@fabric-harness/databricks 0.18.0 → 1.0.0

package/dist/telemetry-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-sink.d.ts","sourceRoot":"","sources":["../src/telemetry-sink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA4B,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC7F,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,cAAc,CAAC;IACvB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,OAAO,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,6EAA6E;IAC7E,SAAS,EAAE,CAAC,MAAM,EAAE,uBAAuB,KAAK,IAAI,CAAC;IACrD,iEAAiE;IACjE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,2DAA2D;AAC3D,wBAAsB,+BAA+B,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CA4C3F;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,mBAAmB,CA6F5F"}

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/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"}

package/dist/volumes-attachment-store.js

@@ -0,0 +1,172 @@
+import { AttachmentStoreError, redactText, verifyAttachmentBytes, } from '@fabric-harness/sdk';
+export class UcVolumesAttachmentStore {
+    host;
+    token;
+    fetchImpl;
+    volumeRoot;
+    rootPrefix;
+    constructor(options) {
+        this.host = options.host.replace(/\/$/, '');
+        this.token = options.token;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.rootPrefix = options.rootPrefix ?? 'fh-attachments';
+        this.volumeRoot = `/Volumes/${options.catalog}/${options.schema}/${options.volume}/${this.rootPrefix}`;
+    }
+    async put(input) {
+        await verifyAttachmentBytes(input.ref, input.bytes);
+        const refPath = this.refPath(input.scope, input.ref.digest);
+        // First-write-wins per (scope, digest): the sidecar marks a complete record.
+        if (await this.readFile(refPath))
+            return;
+        await this.writeFile(this.bytesPath(input.scope, input.ref.digest), input.bytes);
+        await this.writeFile(refPath, new TextEncoder().encode(JSON.stringify(input.ref)));
+    }
+    async get(scope, digest) {
+        const refBytes = await this.readFile(this.refPath(scope, digest));
+        if (!refBytes)
+            return null;
+        const ref = parseAttachmentRef(refBytes);
+        const bytes = await this.readFile(this.bytesPath(scope, digest));
+        // Sidecar without bytes is an incomplete (interrupted) record — a miss.
+        if (!bytes)
+            return null;
+        return { ref, bytes };
+    }
+    async getByAttachmentId(scope, attachmentId) {
+        for (const ref of await this.list(scope)) {
+            if (ref.id === attachmentId)
+                return this.get(scope, ref.digest);
+        }
+        return null;
+    }
+    async list(scope) {
+        const refs = [];
+        for (const prefixDir of await this.listDirectory(this.scopeDir(scope))) {
+            if (!prefixDir.is_directory || !prefixDir.path)
+                continue;
+            for (const entry of await this.listDirectory(prefixDir.path)) {
+                if (entry.is_directory || !entry.path || !entry.path.endsWith('.json'))
+                    continue;
+                const refBytes = await this.readFile(entry.path);
+                if (refBytes)
+                    refs.push(parseAttachmentRef(refBytes));
+            }
+        }
+        return refs;
+    }
+    async delete(scope, digest) {
+        // The sidecar is the record marker — delete it first so the record
+        // disappears even if the bytes delete below fails.
+        if (!(await this.deleteFile(this.refPath(scope, digest)))) {
+            throw new AttachmentStoreError('NOT_FOUND', `Attachment not found: ${scope}/${digest}`);
+        }
+        await this.deleteFile(this.bytesPath(scope, digest));
+    }
+    // ─── Volume paths ─────────────────────────────────────────────────────────
+    scopeDir(scope) {
+        return `${this.volumeRoot}/${encodeURIComponent(scope)}`;
+    }
+    bytesPath(scope, digest) {
+        return `${this.scopeDir(scope)}/${digest.slice(0, 2)}/${digest}`;
+    }
+    refPath(scope, digest) {
+        return `${this.bytesPath(scope, digest)}.json`;
+    }
+    // ─── Files API ────────────────────────────────────────────────────────────
+    async writeFile(path, bytes) {
+        const response = await this.request('PUT', 'files', path, {
+            query: { overwrite: 'true' },
+            body: bytes,
+        });
+        if (!response.ok)
+            await this.fail(`PUT ${path}`, response);
+    }
+    /** Raw file bytes, or `null` when the file does not exist (404). */
+    async readFile(path) {
+        const response = await this.request('GET', 'files', path);
+        if (response.status === 404)
+            return null;
+        if (!response.ok)
+            await this.fail(`GET ${path}`, response);
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    /** True when the file existed and was deleted; false on 404. */
+    async deleteFile(path) {
+        const response = await this.request('DELETE', 'files', path);
+        if (response.status === 404)
+            return false;
+        if (!response.ok)
+            await this.fail(`DELETE ${path}`, response);
+        return true;
+    }
+    /** Immediate children of a directory; empty for a missing directory (404). */
+    async listDirectory(path) {
+        const entries = [];
+        let pageToken;
+        do {
+            const response = await this.request('GET', 'directories', path, {
+                query: pageToken ? { page_token: pageToken } : {},
+            });
+            if (response.status === 404)
+                return entries;
+            if (!response.ok)
+                await this.fail(`LIST ${path}`, response);
+            const listing = (await response.json());
+            entries.push(...(listing.contents ?? []));
+            pageToken = listing.next_page_token;
+        } while (pageToken);
+        return entries;
+    }
+    async request(method, api, path, options = {}) {
+        const url = new URL(`${this.host}/api/2.0/fs/${api}${encodeVolumePath(path)}`);
+        for (const [key, value] of Object.entries(options.query ?? {})) {
+            url.searchParams.set(key, value);
+        }
+        const token = typeof this.token === 'function' ? await this.token() : this.token;
+        return this.fetchImpl(url, {
+            method,
+            headers: {
+                authorization: `Bearer ${token}`,
+                ...(options.body !== undefined ? { 'content-type': 'application/octet-stream' } : {}),
+            },
+            ...(options.body !== undefined ? { body: viewToBuffer(options.body) } : {}),
+        });
+    }
+    async fail(operation, response) {
+        const token = typeof this.token === 'function' ? await this.token() : this.token;
+        const text = redactText(await response.text().catch(() => ''), { additionalSecrets: [token] });
+        throw new Error(`databricks volumes: ${operation}: ${response.status} ${response.statusText}: ${text.slice(0, 1000)}`);
+    }
+}
+/**
+ * Percent-encode each segment of a volume path for use in a Files API URL.
+ * The scope directory name is itself `encodeURIComponent(scope)` (a literal
+ * name containing `%xx` sequences), so its `%` signs are re-encoded here and
+ * the server-decoded path matches the literal layout exactly.
+ */
+function encodeVolumePath(path) {
+    return path
+        .split('/')
+        .map((segment) => encodeURIComponent(segment))
+        .join('/');
+}
+function parseAttachmentRef(bytes) {
+    const parsed = JSON.parse(new TextDecoder().decode(bytes));
+    if (typeof parsed.id !== 'string' ||
+        typeof parsed.mimeType !== 'string' ||
+        typeof parsed.sizeBytes !== 'number' ||
+        typeof parsed.digest !== 'string') {
+        throw new Error('databricks volumes: malformed attachment ref sidecar');
+    }
+    return {
+        id: parsed.id,
+        mimeType: parsed.mimeType,
+        sizeBytes: parsed.sizeBytes,
+        digest: parsed.digest,
+        ...(typeof parsed.filename === 'string' ? { filename: parsed.filename } : {}),
+    };
+}
+function viewToBuffer(bytes) {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+//# sourceMappingURL=volumes-attachment-store.js.map

package/dist/volumes-attachment-store.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabric-harness/databricks",
-  "version": "0.18.0",
+  "version": "1.0.0",
   "description": "Databricks tools and filesystem sources for Fabric Harness agents.",
   "license": "Apache-2.0",
   "author": "Fabric",
@@ -52,19 +52,24 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@fabric-harness/sdk": "^1.14.0"
+    "@fabric-harness/sdk": "^2.0.0"
   },
   "peerDependencies": {
-    "pg": "^8.11.0"
+    "pg": "^8.11.0",
+    "@fabric-harness/node": ">=1.14.0 <3"
   },
   "peerDependenciesMeta": {
     "pg": {
       "optional": true
+    },
+    "@fabric-harness/node": {
+      "optional": true
     }
   },
   "devDependencies": {
     "typescript": "^5.8.3",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.5",
+    "@fabric-harness/node": "^2.0.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",