@fabric-harness/databricks 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/NOTICE +4 -0
  2. package/README.md +14 -8
  3. package/dist/agent.d.ts +5 -5
  4. package/dist/agent.d.ts.map +1 -1
  5. package/dist/agent.js +40 -30
  6. package/dist/agent.js.map +1 -1
  7. package/dist/ai-gateway.d.ts +25 -0
  8. package/dist/ai-gateway.d.ts.map +1 -0
  9. package/dist/ai-gateway.js +51 -0
  10. package/dist/ai-gateway.js.map +1 -0
  11. package/dist/app.d.ts +31 -10
  12. package/dist/app.d.ts.map +1 -1
  13. package/dist/app.js +68 -19
  14. package/dist/app.js.map +1 -1
  15. package/dist/certification.d.ts +62 -0
  16. package/dist/certification.d.ts.map +1 -0
  17. package/dist/certification.js +110 -0
  18. package/dist/certification.js.map +1 -0
  19. package/dist/certify.d.ts +2 -0
  20. package/dist/certify.d.ts.map +1 -0
  21. package/dist/certify.js +707 -0
  22. package/dist/certify.js.map +1 -0
  23. package/dist/client.d.ts +2 -0
  24. package/dist/client.d.ts.map +1 -1
  25. package/dist/client.js +13 -2
  26. package/dist/client.js.map +1 -1
  27. package/dist/compatibility.d.ts +54 -0
  28. package/dist/compatibility.d.ts.map +1 -0
  29. package/dist/compatibility.js +59 -0
  30. package/dist/compatibility.js.map +1 -0
  31. package/dist/cost-budget-actuals.d.ts +29 -1
  32. package/dist/cost-budget-actuals.d.ts.map +1 -1
  33. package/dist/cost-budget-actuals.js +51 -0
  34. package/dist/cost-budget-actuals.js.map +1 -1
  35. package/dist/governance.d.ts +4 -0
  36. package/dist/governance.d.ts.map +1 -1
  37. package/dist/governance.js +27 -4
  38. package/dist/governance.js.map +1 -1
  39. package/dist/identity.d.ts +20 -6
  40. package/dist/identity.d.ts.map +1 -1
  41. package/dist/identity.js +55 -23
  42. package/dist/identity.js.map +1 -1
  43. package/dist/index.d.ts +98 -52
  44. package/dist/index.d.ts.map +1 -1
  45. package/dist/index.js +141 -53
  46. package/dist/index.js.map +1 -1
  47. package/dist/jobs.d.ts +77 -0
  48. package/dist/jobs.d.ts.map +1 -0
  49. package/dist/jobs.js +173 -0
  50. package/dist/jobs.js.map +1 -0
  51. package/dist/lakebase.d.ts +5 -1
  52. package/dist/lakebase.d.ts.map +1 -1
  53. package/dist/lakebase.js +26 -17
  54. package/dist/lakebase.js.map +1 -1
  55. package/dist/mlflow-tracing.d.ts +3 -3
  56. package/dist/model.d.ts +24 -15
  57. package/dist/model.d.ts.map +1 -1
  58. package/dist/model.js +155 -32
  59. package/dist/model.js.map +1 -1
  60. package/dist/rag-chain.d.ts +118 -0
  61. package/dist/rag-chain.d.ts.map +1 -0
  62. package/dist/rag-chain.js +212 -0
  63. package/dist/rag-chain.js.map +1 -0
  64. package/dist/rag-eval.d.ts +118 -0
  65. package/dist/rag-eval.d.ts.map +1 -0
  66. package/dist/rag-eval.js +151 -0
  67. package/dist/rag-eval.js.map +1 -0
  68. package/dist/secrets.d.ts +9 -0
  69. package/dist/secrets.d.ts.map +1 -0
  70. package/dist/secrets.js +25 -0
  71. package/dist/secrets.js.map +1 -0
  72. package/dist/telemetry-sink.d.ts +12 -0
  73. package/dist/telemetry-sink.d.ts.map +1 -1
  74. package/dist/telemetry-sink.js +29 -2
  75. package/dist/telemetry-sink.js.map +1 -1
  76. package/dist/tools.d.ts +5 -2
  77. package/dist/tools.d.ts.map +1 -1
  78. package/dist/tools.js +5 -16
  79. package/dist/tools.js.map +1 -1
  80. package/package.json +7 -5
@@ -0,0 +1,707 @@
1
+ import { createHash, randomUUID } from "node:crypto";
2
+ import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
3
+ import path from "node:path";
4
+ import { evaluateToolCallPolicy, runWithSubmissionContext, } from "@fabric-harness/sdk";
5
+ import { ensureDatabricksAiGateway, listDatabricksModelServices } from "./ai-gateway.js";
6
+ import { runDatabricksCertification } from "./certification.js";
7
+ import { createDatabricksClient, waitForDatabricksStatement } from "./client.js";
8
+ import { DATABRICKS_API_VERSIONS, databricksCompatibilityRecord } from "./compatibility.js";
9
+ import { databricksConsumption } from "./consumption.js";
10
+ import { databricksActualCostSource, reconcileDatabricksCost } from "./cost-budget-actuals.js";
11
+ import { databricksFeatureLookupTool } from "./feature-serving.js";
12
+ import { databricksGenieTool } from "./genie.js";
13
+ import { databricksGovernancePolicy, withGovernance } from "./governance.js";
14
+ import { databricksIdentity, databricksPrincipalFromEnv } from "./identity.js";
15
+ import { databricksJobs } from "./jobs.js";
16
+ import { lakebaseClient } from "./lakebase.js";
17
+ import { databricksPipelineStartTool, databricksPipelineStatusTool } from "./lakeflow.js";
18
+ import { databricksFoundationModelProvider } from "./model.js";
19
+ import { createDatabricksRagChain } from "./rag-chain.js";
20
+ import { databricksTelemetry, queryDatabricksLineageEvidence } from "./telemetry-sink.js";
21
+ import { databricksSqlTool, databricksTableInfoTool, unityCatalogTablesTool } from "./tools.js";
22
+ import { databricksVectorSearch } from "./vector-search.js";
23
+ import { UcVolumesAttachmentStore } from "./volumes-attachment-store.js";
24
+ const env = process.env;
25
+ const host = requiredEnv("DATABRICKS_HOST");
26
+ const principal = databricksPrincipalFromEnv(env);
27
+ const identity = databricksIdentity(principal);
28
+ const client = createDatabricksClient({ host, token: identity });
29
+ const model = env.DATABRICKS_MODEL;
30
+ let principalKind = env.DATABRICKS_PRINCIPAL_KIND;
31
+ const checks = [
32
+ {
33
+ id: "identity",
34
+ description: "Configured PAT or OAuth M2M identity authenticates against the current-user endpoint.",
35
+ configured: true,
36
+ run: async () => {
37
+ const me = await client.get("/api/2.0/preview/scim/v2/Me");
38
+ assertTruthy(me.id ?? me.userName, "Current-user response did not contain an identity.");
39
+ principalKind ??= typeof me.applicationId === "string" ? "service-principal" : "user";
40
+ return { principalKind, principalId: String(me.id ?? me.userName) };
41
+ },
42
+ },
43
+ {
44
+ id: "ai-gateway",
45
+ description: "Unity AI Gateway v2 is enabled and exposes the configured system.ai model service.",
46
+ configured: Boolean(model?.startsWith("system.ai.")),
47
+ run: async () => {
48
+ await ensureDatabricksAiGateway(client);
49
+ const services = await listDatabricksModelServices(client);
50
+ if (!model || !services.some((service) => service.name === model)) {
51
+ throw new Error(`Configured model service ${model ?? "(missing)"} was not discovered through Unity Catalog.`);
52
+ }
53
+ return { model, discoveredServices: services.length };
54
+ },
55
+ },
56
+ {
57
+ id: "sql",
58
+ description: "SQL Warehouse executes a statement to completion.",
59
+ configured: Boolean(env.DATABRICKS_WAREHOUSE_ID),
60
+ run: async () => {
61
+ const result = (await databricksSqlTool(client, {
62
+ warehouseId: requiredEnv("DATABRICKS_WAREHOUSE_ID"),
63
+ waitTimeout: "10s",
64
+ }).execute?.({ statement: "select 1 as fabric_harness_certification" }));
65
+ if (!result?.statement_id && result?.status?.state !== "SUCCEEDED")
66
+ throw new Error("SQL statement was not admitted.");
67
+ const final = result.statement_id && result.status?.state !== "SUCCEEDED"
68
+ ? await waitForDatabricksStatement(client, result.statement_id, { timeoutMs: 120_000 })
69
+ : result;
70
+ if (JSON.stringify(final).includes("SUCCEEDED") === false)
71
+ throw new Error("SQL statement did not succeed.");
72
+ },
73
+ },
74
+ {
75
+ id: "unity-catalog",
76
+ description: "Acting principal can list tables in the configured UC catalog and schema.",
77
+ configured: Boolean(env.DATABRICKS_CATALOG && env.DATABRICKS_SCHEMA),
78
+ run: async () => {
79
+ await unityCatalogTablesTool(client).execute?.({
80
+ catalog: requiredEnv("DATABRICKS_CATALOG"),
81
+ schema: requiredEnv("DATABRICKS_SCHEMA"),
82
+ });
83
+ },
84
+ },
85
+ {
86
+ id: "uc-denial",
87
+ description: "Unity Catalog rejects SELECT against a deliberately unauthorized table.",
88
+ configured: Boolean(env.DATABRICKS_WAREHOUSE_ID && env.DATABRICKS_DENIED_TABLE),
89
+ run: async () => {
90
+ try {
91
+ const result = (await databricksSqlTool(client, {
92
+ warehouseId: requiredEnv("DATABRICKS_WAREHOUSE_ID"),
93
+ waitTimeout: "10s",
94
+ }).execute?.({
95
+ statement: `SELECT * FROM ${sqlIdentifier(requiredEnv("DATABRICKS_DENIED_TABLE"))} LIMIT 1`,
96
+ }));
97
+ const final = (result?.statement_id && !isTerminalStatementState(result.status?.state)
98
+ ? await waitForDatabricksStatement(client, result.statement_id, { timeoutMs: 120_000 })
99
+ : result);
100
+ if (final?.status?.state === "SUCCEEDED") {
101
+ throw new Error("The configured denied table was readable; the UC denial control was not demonstrated.");
102
+ }
103
+ if (/403|PERMISSION_DENIED|does not have|not authorized/i.test(JSON.stringify(final))) {
104
+ return { deniedByUnityCatalog: true };
105
+ }
106
+ throw new Error(`Denied-table query failed for an unexpected reason: ${JSON.stringify(final)}`);
107
+ }
108
+ catch (error) {
109
+ if (/403|PERMISSION_DENIED|does not have|not authorized/i.test(String(error)))
110
+ return { deniedByUnityCatalog: true };
111
+ throw error;
112
+ }
113
+ },
114
+ },
115
+ {
116
+ id: "uc-allowed-select",
117
+ description: "Unity Catalog permits SELECT against the configured governed table.",
118
+ configured: Boolean(env.DATABRICKS_WAREHOUSE_ID && env.DATABRICKS_ALLOWED_TABLE),
119
+ run: async () => {
120
+ const result = (await databricksSqlTool(client, {
121
+ warehouseId: requiredEnv("DATABRICKS_WAREHOUSE_ID"),
122
+ waitTimeout: "10s",
123
+ }).execute?.({
124
+ statement: `SELECT * FROM ${sqlIdentifier(requiredEnv("DATABRICKS_ALLOWED_TABLE"))} LIMIT 1`,
125
+ }));
126
+ assertTruthy(result, "Allowed SELECT returned no statement response.");
127
+ const final = (result.statement_id && !isTerminalStatementState(result.status?.state)
128
+ ? await waitForDatabricksStatement(client, result.statement_id, { timeoutMs: 120_000 })
129
+ : result);
130
+ if (final.status?.state !== "SUCCEEDED") {
131
+ throw new Error(`Allowed SELECT did not succeed: ${JSON.stringify(final.status)}`);
132
+ }
133
+ },
134
+ },
135
+ {
136
+ id: "catalog-preflight-denial",
137
+ description: "Fabric rejects a disallowed fully-qualified catalog before a REST request is sent.",
138
+ configured: Boolean(env.DATABRICKS_CATALOG),
139
+ run: async () => {
140
+ let requested = false;
141
+ const probe = {
142
+ get: async () => {
143
+ requested = true;
144
+ return {};
145
+ },
146
+ };
147
+ const tool = withGovernance(databricksTableInfoTool(probe), {
148
+ catalogs: [requiredEnv("DATABRICKS_CATALOG")],
149
+ });
150
+ const deniedObject = env.DATABRICKS_PREFLIGHT_DENIED_TABLE ??
151
+ "fabric_harness_disallowed.certification.denied_probe";
152
+ try {
153
+ await tool.execute?.({ fullName: deniedObject });
154
+ }
155
+ catch (error) {
156
+ if (/not in the allowed list/.test(String(error)) && !requested)
157
+ return { deniedBeforeRest: true };
158
+ throw error;
159
+ }
160
+ throw new Error("Catalog preflight did not reject the disallowed object.");
161
+ },
162
+ },
163
+ {
164
+ id: "mutation-approval",
165
+ description: "A Lakeflow mutation is classified as approval-required for the data steward.",
166
+ configured: Boolean(env.DATABRICKS_PIPELINE_ID),
167
+ run: () => {
168
+ const tool = databricksPipelineStartTool(client);
169
+ const policy = databricksGovernancePolicy({
170
+ tools: [tool],
171
+ host,
172
+ stewardAudience: "data-steward",
173
+ });
174
+ const decision = evaluateToolCallPolicy({ tool: tool.name, input: { pipelineId: requiredEnv("DATABRICKS_PIPELINE_ID") } }, policy);
175
+ if (!decision.approvalRequired || decision.approvalAudience !== "data-steward")
176
+ throw new Error("Mutation approval policy did not gate Lakeflow start.");
177
+ return { approvalRequired: true, audience: decision.approvalAudience };
178
+ },
179
+ },
180
+ {
181
+ id: "model-serving",
182
+ description: "Mosaic AI Model Serving returns a model response.",
183
+ configured: Boolean(model),
184
+ run: async () => {
185
+ if (!model)
186
+ throw new Error("DATABRICKS_MODEL is required.");
187
+ const provider = databricksFoundationModelProvider({
188
+ host,
189
+ token: identity,
190
+ defaultModel: model,
191
+ requestTags: { project: "fabric-harness", purpose: "certification" },
192
+ });
193
+ const result = await provider.generate({
194
+ model,
195
+ messages: [{ role: "user", content: "Reply with the word certified." }],
196
+ });
197
+ assertTruthy(result.message?.content, "Model Serving returned no text.");
198
+ },
199
+ },
200
+ {
201
+ id: "rag",
202
+ description: "Vector Search retrieval and AI Gateway generation produce a grounded answer with a valid source citation.",
203
+ configured: Boolean(model && env.DATABRICKS_VECTOR_INDEX && env.DATABRICKS_VECTOR_TEXT_COLUMN),
204
+ run: async () => {
205
+ if (!model)
206
+ throw new Error("DATABRICKS_MODEL is required.");
207
+ const retriever = databricksVectorSearch({
208
+ client,
209
+ index: requiredEnv("DATABRICKS_VECTOR_INDEX"),
210
+ textColumn: requiredEnv("DATABRICKS_VECTOR_TEXT_COLUMN"),
211
+ ...(env.DATABRICKS_VECTOR_ID_COLUMN ? { idColumn: env.DATABRICKS_VECTOR_ID_COLUMN } : {}),
212
+ });
213
+ const chain = createDatabricksRagChain({
214
+ retriever,
215
+ modelProvider: databricksFoundationModelProvider({
216
+ host,
217
+ token: identity,
218
+ defaultModel: model,
219
+ requestTags: { project: "fabric-harness", purpose: "rag-certification" },
220
+ }),
221
+ model,
222
+ index: requiredEnv("DATABRICKS_VECTOR_INDEX"),
223
+ topK: 3,
224
+ postProcess: { requireCitations: true, citationRepairAttempts: 3 },
225
+ });
226
+ const turn = await chain.invoke({
227
+ question: env.DATABRICKS_RAG_QUERY ?? env.DATABRICKS_VECTOR_QUERY ?? "What is Fabric Harness?",
228
+ });
229
+ if (turn.chunks.length === 0)
230
+ throw new Error("RAG certification retrieved no context.");
231
+ if (turn.citations.length === 0)
232
+ throw new Error("RAG certification answer contained no valid inline citation.");
233
+ return {
234
+ retrieved: turn.chunks.length,
235
+ citations: turn.citations.map((citation) => citation.id),
236
+ };
237
+ },
238
+ },
239
+ {
240
+ id: "chat-agent-proxy",
241
+ description: "The registered MLflow ChatAgent proxy accepts its message schema and securely reaches the Fabric App.",
242
+ configured: Boolean(env.DATABRICKS_CHAT_AGENT_ENDPOINT),
243
+ run: async () => {
244
+ const result = await client.post(`/serving-endpoints/${encodeURIComponent(requiredEnv("DATABRICKS_CHAT_AGENT_ENDPOINT"))}/invocations`, {
245
+ messages: [{ role: "user", content: "Reply with certified." }],
246
+ custom_inputs: {
247
+ id: `cert-${randomUUID()}`,
248
+ payload: { question: "Reply with certified." },
249
+ },
250
+ });
251
+ const messages = Array.isArray(result.messages) ? result.messages : [];
252
+ if (messages.length === 0)
253
+ throw new Error("ChatAgent proxy returned no messages.");
254
+ return {
255
+ endpoint: requiredEnv("DATABRICKS_CHAT_AGENT_ENDPOINT"),
256
+ streaming: false,
257
+ messages: messages.length,
258
+ };
259
+ },
260
+ },
261
+ {
262
+ id: "rag-evaluation",
263
+ description: "Databricks MLflow 3 evaluates the governed RAG golden set with managed relevance, groundedness, sufficiency, and correctness judges.",
264
+ configured: Boolean(env.DATABRICKS_RAG_EVAL_JOB_ID),
265
+ run: async () => {
266
+ const jobs = databricksJobs(client);
267
+ const receipt = await jobs.runJob({
268
+ jobId: Number(requiredEnv("DATABRICKS_RAG_EVAL_JOB_ID")),
269
+ idempotencyToken: `fabric-rag-eval-${randomUUID()}`,
270
+ });
271
+ const state = await jobs.wait(receipt.runId, {
272
+ timeoutMs: 3_600_000,
273
+ pollIntervalMs: 10_000,
274
+ });
275
+ if (state.resultState !== "SUCCESS")
276
+ throw new Error(`MLflow RAG evaluation job ended in ${state.resultState ?? state.lifeCycleState}.`);
277
+ const outputs = await jobs.getOutputs(receipt.runId);
278
+ return { runId: receipt.runId, resultState: state.resultState, outputCount: outputs.length };
279
+ },
280
+ },
281
+ {
282
+ id: "vector-search",
283
+ description: "Mosaic AI Vector Search returns governed index results.",
284
+ configured: Boolean(env.DATABRICKS_VECTOR_INDEX && env.DATABRICKS_VECTOR_TEXT_COLUMN),
285
+ run: async () => {
286
+ const results = await databricksVectorSearch({
287
+ client,
288
+ index: requiredEnv("DATABRICKS_VECTOR_INDEX"),
289
+ textColumn: requiredEnv("DATABRICKS_VECTOR_TEXT_COLUMN"),
290
+ }).retrieve(env.DATABRICKS_VECTOR_QUERY ?? "fabric harness certification", { k: 1 });
291
+ if (!Array.isArray(results))
292
+ throw new Error("Vector Search returned an invalid result.");
293
+ },
294
+ },
295
+ {
296
+ id: "genie",
297
+ description: "AI/BI Genie completes a natural-language analytics request.",
298
+ configured: Boolean(env.DATABRICKS_GENIE_SPACE_ID),
299
+ run: async () => {
300
+ const result = (await databricksGenieTool(client, {
301
+ spaceId: requiredEnv("DATABRICKS_GENIE_SPACE_ID"),
302
+ timeoutMs: 180_000,
303
+ }).execute?.({
304
+ question: env.DATABRICKS_GENIE_QUESTION ?? "How many rows are available?",
305
+ }));
306
+ if (result?.status !== "COMPLETED")
307
+ throw new Error(`Genie ended in status ${result?.status ?? "unknown"}.`);
308
+ },
309
+ },
310
+ {
311
+ id: "feature-serving",
312
+ description: "Feature Serving resolves configured primary-key records.",
313
+ configured: Boolean(env.DATABRICKS_FEATURE_ENDPOINT && env.DATABRICKS_FEATURE_RECORDS_JSON),
314
+ run: async () => {
315
+ const records = JSON.parse(requiredEnv("DATABRICKS_FEATURE_RECORDS_JSON"));
316
+ assertTruthy(await databricksFeatureLookupTool(client, {
317
+ endpoint: requiredEnv("DATABRICKS_FEATURE_ENDPOINT"),
318
+ }).execute?.({ records }), "Feature Serving returned no result.");
319
+ },
320
+ },
321
+ {
322
+ id: "lakeflow",
323
+ description: "Lakeflow pipeline status is readable under the acting principal.",
324
+ configured: Boolean(env.DATABRICKS_PIPELINE_ID),
325
+ run: async () => {
326
+ assertTruthy(await databricksPipelineStatusTool(client).execute?.({
327
+ pipelineId: requiredEnv("DATABRICKS_PIPELINE_ID"),
328
+ }), "Lakeflow returned no pipeline.");
329
+ },
330
+ },
331
+ {
332
+ id: "jobs",
333
+ description: "Jobs run-now accepts a stable idempotency token, terminates successfully, and exposes output.",
334
+ configured: Boolean(env.DATABRICKS_JOB_ID),
335
+ run: async () => {
336
+ const jobs = databricksJobs(client);
337
+ const receipt = await jobs.runJob({
338
+ jobId: Number(requiredEnv("DATABRICKS_JOB_ID")),
339
+ idempotencyToken: `fabric-cert-${randomUUID()}`,
340
+ });
341
+ const state = await jobs.wait(receipt.runId, { timeoutMs: 900_000, pollIntervalMs: 5_000 });
342
+ if (state.resultState !== "SUCCESS")
343
+ throw new Error(`Jobs run ended in ${state.resultState ?? state.lifeCycleState}.`);
344
+ const outputs = await jobs.getOutputs(receipt.runId);
345
+ return { runId: receipt.runId, resultState: state.resultState, outputCount: outputs.length };
346
+ },
347
+ },
348
+ {
349
+ id: "notebook",
350
+ description: "A one-off notebook task executes on the configured existing cluster.",
351
+ configured: Boolean(env.DATABRICKS_NOTEBOOK_PATH),
352
+ run: async () => {
353
+ const jobs = databricksJobs(client);
354
+ const receipt = await jobs.submitNotebook({
355
+ notebookPath: requiredEnv("DATABRICKS_NOTEBOOK_PATH"),
356
+ ...(env.DATABRICKS_CLUSTER_ID ? { existingClusterId: env.DATABRICKS_CLUSTER_ID } : {}),
357
+ idempotencyToken: `fabric-cert-notebook-${randomUUID()}`,
358
+ });
359
+ const state = await jobs.wait(receipt.runId, { timeoutMs: 900_000, pollIntervalMs: 5_000 });
360
+ if (state.resultState !== "SUCCESS")
361
+ throw new Error(`Notebook run ended in ${state.resultState ?? state.lifeCycleState}.`);
362
+ return { runId: receipt.runId, resultState: state.resultState };
363
+ },
364
+ },
365
+ {
366
+ id: "volumes",
367
+ description: "UC Volumes supports attachment write, read, and delete.",
368
+ configured: Boolean(env.DATABRICKS_CATALOG && env.DATABRICKS_SCHEMA && env.DATABRICKS_VOLUME),
369
+ run: async () => {
370
+ const bytes = new TextEncoder().encode(`fabric-harness-certification:${randomUUID()}`);
371
+ const digest = createHash("sha256").update(bytes).digest("hex");
372
+ const scope = `certification-${randomUUID()}`;
373
+ const ref = {
374
+ id: randomUUID(),
375
+ digest,
376
+ mimeType: "text/plain",
377
+ sizeBytes: bytes.byteLength,
378
+ filename: "certification.txt",
379
+ };
380
+ const store = new UcVolumesAttachmentStore({
381
+ host,
382
+ token: identity,
383
+ catalog: requiredEnv("DATABRICKS_CATALOG"),
384
+ schema: requiredEnv("DATABRICKS_SCHEMA"),
385
+ volume: requiredEnv("DATABRICKS_VOLUME"),
386
+ rootPrefix: env.DATABRICKS_VOLUME_ROOT ?? "fabric-harness-certification",
387
+ });
388
+ await store.put({ scope, ref, bytes });
389
+ const loaded = await store.get(scope, digest);
390
+ if (!loaded || loaded.ref.digest !== digest)
391
+ throw new Error("UC Volumes attachment round trip failed.");
392
+ await store.delete(scope, digest);
393
+ },
394
+ },
395
+ {
396
+ id: "lakebase",
397
+ description: "Lakebase credential exchange opens a managed Postgres connection.",
398
+ configured: Boolean(env.ENDPOINT_NAME && env.PGHOST && env.PGDATABASE && env.PGUSER),
399
+ run: async () => {
400
+ const pool = lakebaseClient({
401
+ workspaceHost: host,
402
+ endpoint: requiredEnv("ENDPOINT_NAME"),
403
+ token: identity,
404
+ host: requiredEnv("PGHOST"),
405
+ database: requiredEnv("PGDATABASE"),
406
+ user: requiredEnv("PGUSER"),
407
+ port: Number(env.PGPORT ?? 5432),
408
+ ssl: { rejectUnauthorized: true },
409
+ max: 1,
410
+ });
411
+ try {
412
+ const result = await pool.query("select current_user, current_database()");
413
+ assertTruthy(result.rows[0], "Lakebase returned no row.");
414
+ }
415
+ finally {
416
+ await pool.end();
417
+ }
418
+ },
419
+ },
420
+ {
421
+ id: "lineage",
422
+ description: "Lakebase joins a governed UC object to submission, actor, outcome, and cost.",
423
+ configured: Boolean(env.ENDPOINT_NAME &&
424
+ env.PGHOST &&
425
+ env.PGDATABASE &&
426
+ env.PGUSER &&
427
+ env.DATABRICKS_ALLOWED_TABLE),
428
+ run: async () => {
429
+ const pool = lakebaseClient({
430
+ workspaceHost: host,
431
+ endpoint: requiredEnv("ENDPOINT_NAME"),
432
+ token: identity,
433
+ host: requiredEnv("PGHOST"),
434
+ database: requiredEnv("PGDATABASE"),
435
+ user: requiredEnv("PGUSER"),
436
+ port: Number(env.PGPORT ?? 5432),
437
+ ssl: { rejectUnauthorized: true },
438
+ max: 1,
439
+ });
440
+ const submissionId = `cert-lineage-${randomUUID()}`;
441
+ try {
442
+ const telemetry = databricksTelemetry({ client: pool });
443
+ await telemetry.migrate();
444
+ await telemetry.sink.record({
445
+ type: "submission_usage",
446
+ submissionId,
447
+ kind: "certification",
448
+ agent: "databricks-certifier",
449
+ instanceId: "partner-review",
450
+ session: "default",
451
+ tenantId: "certification",
452
+ at: Date.now(),
453
+ model: model ?? "certification",
454
+ costUsd: 0.01,
455
+ actor: { principal: { kind: "app-principal", id: principalKind ?? "databricks-app" } },
456
+ });
457
+ const tool = withGovernance(databricksTableInfoTool(client), {
458
+ principal: principalKind ?? "databricks-app",
459
+ catalogs: [requiredEnv("DATABRICKS_CATALOG")],
460
+ onLineage: telemetry.onLineage,
461
+ });
462
+ await runWithSubmissionContext({
463
+ submissionId,
464
+ attemptId: "attempt-1",
465
+ agent: "databricks-certifier",
466
+ instanceId: "partner-review",
467
+ session: "default",
468
+ tenantId: "certification",
469
+ actor: { principal: { kind: "app-principal", id: principalKind ?? "databricks-app" } },
470
+ }, () => tool.execute?.({ fullName: requiredEnv("DATABRICKS_ALLOWED_TABLE") }));
471
+ let rows = [];
472
+ for (let attempt = 0; attempt < 20 && rows.length === 0; attempt += 1) {
473
+ await new Promise((resolve) => setTimeout(resolve, 250));
474
+ rows = await queryDatabricksLineageEvidence(pool, submissionId);
475
+ }
476
+ const row = rows[0];
477
+ if (!row?.actor ||
478
+ row.object !== requiredEnv("DATABRICKS_ALLOWED_TABLE") ||
479
+ row.outcome !== "succeeded" ||
480
+ row.estimatedCostUsd < 0.01) {
481
+ throw new Error("Lineage evidence did not join actor, object, outcome, and cost.");
482
+ }
483
+ return {
484
+ submissionId,
485
+ actor: row.actor,
486
+ object: row.object,
487
+ outcome: row.outcome,
488
+ estimatedCostUsd: row.estimatedCostUsd,
489
+ };
490
+ }
491
+ finally {
492
+ await pool
493
+ .query("DELETE FROM fh_lineage WHERE submission_id = $1", [submissionId])
494
+ .catch(() => undefined);
495
+ await pool
496
+ .query("DELETE FROM fh_submission_telemetry WHERE submission_id = $1", [submissionId])
497
+ .catch(() => undefined);
498
+ await pool.end();
499
+ }
500
+ },
501
+ },
502
+ {
503
+ id: "obo",
504
+ description: "A forwarded user token resolves identity and demonstrates a different UC grant outcome from the App principal.",
505
+ configured: Boolean(env.DATABRICKS_OBO_TOKEN && env.DATABRICKS_OBO_DIFFERENTIAL_TABLE),
506
+ run: async () => {
507
+ const obo = createDatabricksClient({ host, token: requiredEnv("DATABRICKS_OBO_TOKEN") });
508
+ const me = await obo.get("/api/2.0/preview/scim/v2/Me");
509
+ assertTruthy(me.id ?? me.userName, "OBO token did not resolve a user identity.");
510
+ const table = requiredEnv("DATABRICKS_OBO_DIFFERENTIAL_TABLE");
511
+ const [appAllowed, userAllowed] = await Promise.all([
512
+ canReadTable(client, table),
513
+ canReadTable(obo, table),
514
+ ]);
515
+ const expected = env.DATABRICKS_OBO_EXPECT ?? "user-allowed";
516
+ if (appAllowed === userAllowed)
517
+ throw new Error("App and OBO principals produced the same UC grant outcome; configure a differential table.");
518
+ if (expected === "user-allowed" && !userAllowed)
519
+ throw new Error("Expected the OBO user to read the differential table.");
520
+ if (expected === "app-allowed" && !appAllowed)
521
+ throw new Error("Expected the App principal to read the differential table.");
522
+ return { appAllowed, userAllowed, expected };
523
+ },
524
+ },
525
+ {
526
+ id: "system-tables",
527
+ description: "System billing tables return attributed usage through SQL Warehouse.",
528
+ configured: Boolean(env.DATABRICKS_WAREHOUSE_ID && env.DATABRICKS_SYSTEM_TABLES_TEST === "1"),
529
+ run: async () => {
530
+ const summary = await databricksConsumption(client, {
531
+ warehouseId: requiredEnv("DATABRICKS_WAREHOUSE_ID"),
532
+ }).summary({
533
+ startDate: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString().slice(0, 10),
534
+ endDate: new Date().toISOString().slice(0, 10),
535
+ groupBy: "sku",
536
+ });
537
+ if (!Array.isArray(summary.rows))
538
+ throw new Error("System Tables returned an invalid summary.");
539
+ },
540
+ },
541
+ {
542
+ id: "actual-cost-reconciliation",
543
+ description: "Delayed System Tables actuals reconcile with an estimate and exercise drift alerting.",
544
+ configured: Boolean(env.DATABRICKS_WAREHOUSE_ID &&
545
+ env.DATABRICKS_SYSTEM_TABLES_TEST === "1" &&
546
+ env.DATABRICKS_COST_SCOPE_KEY &&
547
+ env.DATABRICKS_ESTIMATED_COST_USD),
548
+ run: async () => {
549
+ let alerted = false;
550
+ const result = await reconcileDatabricksCost({
551
+ scopeKey: requiredEnv("DATABRICKS_COST_SCOPE_KEY"),
552
+ estimatedUsd: Number(requiredEnv("DATABRICKS_ESTIMATED_COST_USD")),
553
+ usageOccurredAt: env.DATABRICKS_COST_OCCURRED_AT ?? new Date(Date.now() - 48 * 60 * 60_000),
554
+ accountingDelayMs: Number(env.DATABRICKS_ACCOUNTING_DELAY_MS ?? 24 * 60 * 60_000),
555
+ actualSource: databricksActualCostSource(client, requiredEnv("DATABRICKS_WAREHOUSE_ID"), {
556
+ cacheTtlMs: 0,
557
+ }),
558
+ maxDriftUsd: Number(env.DATABRICKS_MAX_COST_DRIFT_USD ?? 1),
559
+ maxDriftPercent: Number(env.DATABRICKS_MAX_COST_DRIFT_PERCENT ?? 10),
560
+ unavailable: "fail-closed",
561
+ onDrift: () => {
562
+ alerted = true;
563
+ },
564
+ });
565
+ if (result.status === "pending-accounting")
566
+ throw new Error("Configured usage has not passed the accounting delay.");
567
+ if (result.status === "drift" && !alerted)
568
+ throw new Error("Cost drift did not invoke the alert hook.");
569
+ return { ...result, alerted };
570
+ },
571
+ },
572
+ {
573
+ id: "databricks-app",
574
+ description: "The deployed Databricks App passes its health endpoint.",
575
+ configured: Boolean(env.DATABRICKS_APP_URL),
576
+ run: async () => {
577
+ const response = await fetch(`${env.DATABRICKS_APP_URL?.replace(/\/$/, "")}/health`, {
578
+ headers: { authorization: `Bearer ${await identity()}` },
579
+ });
580
+ if (!response.ok)
581
+ throw new Error(`Databricks App health returned HTTP ${response.status}.`);
582
+ const body = (await response.json());
583
+ if (body.ok !== true)
584
+ throw new Error("Databricks App health response was not ok.");
585
+ },
586
+ },
587
+ ];
588
+ const required = splitCsv(env.FABRIC_DATABRICKS_REQUIRED_CHECKS ||
589
+ [
590
+ "identity",
591
+ "ai-gateway",
592
+ "sql",
593
+ "unity-catalog",
594
+ "uc-denial",
595
+ "uc-allowed-select",
596
+ "catalog-preflight-denial",
597
+ "mutation-approval",
598
+ "model-serving",
599
+ "rag",
600
+ "rag-evaluation",
601
+ "chat-agent-proxy",
602
+ "vector-search",
603
+ "genie",
604
+ "feature-serving",
605
+ "lakeflow",
606
+ "jobs",
607
+ "notebook",
608
+ "volumes",
609
+ "lakebase",
610
+ "lineage",
611
+ "obo",
612
+ "system-tables",
613
+ "actual-cost-reconciliation",
614
+ "databricks-app",
615
+ ].join(","));
616
+ const packageManifest = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
617
+ const artifactSha256 = env.FABRIC_DATABRICKS_ARTIFACT_PATH
618
+ ? await digestArtifact(path.resolve(env.FABRIC_DATABRICKS_ARTIFACT_PATH))
619
+ : undefined;
620
+ const evidence = await runDatabricksCertification({
621
+ workspaceHost: host,
622
+ checks,
623
+ required,
624
+ ...(env.GITHUB_SHA ? { commitSha: env.GITHUB_SHA } : {}),
625
+ secrets: [
626
+ principal.kind === "pat" ? principal.token : principal.clientSecret,
627
+ env.DATABRICKS_OBO_TOKEN ?? "",
628
+ ].filter(Boolean),
629
+ ...(env.DATABRICKS_WORKSPACE_CLOUD ? { workspaceCloud: env.DATABRICKS_WORKSPACE_CLOUD } : {}),
630
+ ...(env.DATABRICKS_WORKSPACE_REGION ? { workspaceRegion: env.DATABRICKS_WORKSPACE_REGION } : {}),
631
+ ...(env.DATABRICKS_WORKSPACE_ID ? { workspaceId: env.DATABRICKS_WORKSPACE_ID } : {}),
632
+ runtimeVersion: `node ${process.version}`,
633
+ ...(packageManifest.version ? { packageVersion: packageManifest.version } : {}),
634
+ ...(principalKind ? { principalKind } : {}),
635
+ authMode: env.DATABRICKS_AUTH_MODE ?? (principalKind === "service-principal" ? "oauth-m2m" : "pat"),
636
+ apiVersions: { ...DATABRICKS_API_VERSIONS },
637
+ ...(artifactSha256 ? { artifactSha256 } : {}),
638
+ });
639
+ const output = path.resolve(env.FABRIC_DATABRICKS_EVIDENCE_PATH ?? "artifacts/databricks-certification.json");
640
+ await mkdir(path.dirname(output), { recursive: true });
641
+ await writeFile(output, `${JSON.stringify(evidence, null, 2)}\n`);
642
+ if (evidence.passed &&
643
+ evidence.workspaceCloud &&
644
+ evidence.workspaceRegion &&
645
+ evidence.authMode &&
646
+ evidence.runtimeVersion &&
647
+ evidence.packageVersion &&
648
+ evidence.artifactSha256) {
649
+ const compatibilityOutput = path.join(path.dirname(output), "databricks-compatibility.json");
650
+ await writeFile(compatibilityOutput, `${JSON.stringify(databricksCompatibilityRecord(evidence), null, 2)}\n`);
651
+ }
652
+ process.stdout.write(`${JSON.stringify(evidence, null, 2)}\n`);
653
+ if (!evidence.passed)
654
+ process.exitCode = 1;
655
+ function splitCsv(value) {
656
+ return value
657
+ .split(",")
658
+ .map((item) => item.trim())
659
+ .filter(Boolean);
660
+ }
661
+ function requiredEnv(name) {
662
+ const value = env[name];
663
+ if (!value)
664
+ throw new Error(`${name} is required for Databricks certification.`);
665
+ return value;
666
+ }
667
+ function assertTruthy(value, message) {
668
+ if (!value)
669
+ throw new Error(message);
670
+ }
671
+ function isTerminalStatementState(state) {
672
+ return state === "SUCCEEDED" || state === "FAILED" || state === "CANCELED" || state === "CLOSED";
673
+ }
674
+ function sqlIdentifier(value) {
675
+ const parts = value.split(".");
676
+ if (parts.length !== 3 || parts.some((part) => !/^[A-Za-z0-9_][A-Za-z0-9_$-]*$/.test(part))) {
677
+ throw new Error(`Expected a three-part Unity Catalog identifier, received: ${value}`);
678
+ }
679
+ return parts.map((part) => `\`${part.replaceAll("`", "``")}\``).join(".");
680
+ }
681
+ async function canReadTable(rest, fullName) {
682
+ try {
683
+ await rest.get(`/api/2.1/unity-catalog/tables/${encodeURIComponent(fullName)}`);
684
+ return true;
685
+ }
686
+ catch (error) {
687
+ if (/403|PERMISSION_DENIED|does not have/.test(String(error)))
688
+ return false;
689
+ throw error;
690
+ }
691
+ }
692
+ async function digestArtifact(target) {
693
+ const hash = createHash("sha256");
694
+ async function append(candidate, relative) {
695
+ const info = await stat(candidate);
696
+ if (info.isDirectory()) {
697
+ for (const name of (await readdir(candidate)).sort())
698
+ await append(path.join(candidate, name), path.join(relative, name));
699
+ return;
700
+ }
701
+ hash.update(relative.replaceAll(path.sep, "/"));
702
+ hash.update(await readFile(candidate));
703
+ }
704
+ await append(target, ".");
705
+ return hash.digest("hex");
706
+ }
707
+ //# sourceMappingURL=certify.js.map