@fabric-harness/databricks 7.0.1 → 7.1.1
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.
- package/dist/agent.d.ts.map +1 -1
- package/dist/agent.js +54 -21
- package/dist/agent.js.map +1 -1
- package/dist/capabilities.d.ts.map +1 -1
- package/dist/certification-environment.d.ts.map +1 -1
- package/dist/certify.js +15 -7
- package/dist/certify.js.map +1 -1
- package/dist/compatibility.d.ts +1 -1
- package/dist/genie-authoring.d.ts +10 -0
- package/dist/genie-authoring.d.ts.map +1 -1
- package/dist/index.d.ts +11 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1848 -30
- package/dist/index.js.map +1 -1
- package/dist/mock-provider.d.ts +1 -0
- package/dist/mock-provider.d.ts.map +1 -1
- package/dist/model.d.ts +7 -0
- package/dist/model.d.ts.map +1 -1
- package/dist/ontology-apply.d.ts +156 -0
- package/dist/ontology-apply.d.ts.map +1 -0
- package/dist/ontology-drift.d.ts +205 -0
- package/dist/ontology-drift.d.ts.map +1 -0
- package/dist/ontology-export.d.ts +181 -0
- package/dist/ontology-export.d.ts.map +1 -0
- package/dist/ontology-feed-pipeline.d.ts +194 -0
- package/dist/ontology-feed-pipeline.d.ts.map +1 -0
- package/dist/ontology-feed.d.ts +49 -0
- package/dist/ontology-feed.d.ts.map +1 -0
- package/dist/ontology-genie-spec.d.ts +31 -0
- package/dist/ontology-genie-spec.d.ts.map +1 -0
- package/dist/ontology-glossary.d.ts +54 -0
- package/dist/ontology-glossary.d.ts.map +1 -0
- package/dist/ontology-metric-view.d.ts +42 -0
- package/dist/ontology-metric-view.d.ts.map +1 -0
- package/package.json +4 -4
package/dist/mock-provider.d.ts
CHANGED
|
@@ -21,6 +21,7 @@ export declare class MockDatabricksModelProvider implements ModelProvider {
|
|
|
21
21
|
private readonly options;
|
|
22
22
|
constructor(options?: MockDatabricksModelProviderOptions);
|
|
23
23
|
generate(request: ModelRequest): Promise<ModelResponse>;
|
|
24
|
+
private buildResponse;
|
|
24
25
|
stream(request: ModelRequest): AsyncIterable<ModelStreamChunk>;
|
|
25
26
|
}
|
|
26
27
|
//# sourceMappingURL=mock-provider.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"mock-provider.d.ts","sourceRoot":"","sources":["../src/mock-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEvH,MAAM,WAAW,kCAAkC;IACjD;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC;IACnD,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,aAAa,EAAE,CAAC;IACnC,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;
|
|
1
|
+
{"version":3,"file":"mock-provider.d.ts","sourceRoot":"","sources":["../src/mock-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEvH,MAAM,WAAW,kCAAkC;IACjD;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC;IACnD,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,aAAa,EAAE,CAAC;IACnC,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAsBD;;;;GAIG;AACH,qBAAa,2BAA4B,YAAW,aAAa;IAC/D,QAAQ,CAAC,IAAI,qBAAqB;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;gBAEjD,OAAO,GAAE,kCAAuC;IAItD,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAS7D,OAAO,CAAC,aAAa;IAmCd,MAAM,CAAC,OAAO,EAAE,YAAY,GAAG,aAAa,CAAC,gBAAgB,CAAC;CAoBtE"}
|
package/dist/model.d.ts
CHANGED
|
@@ -27,6 +27,13 @@ export interface DatabricksModelOptions {
|
|
|
27
27
|
export declare function databricksModelBaseUrl(host: string, mode: Exclude<DatabricksInferenceMode, "auto">): string;
|
|
28
28
|
/** True for Unity Catalog model-service identifiers accepted by Unity AI Gateway. */
|
|
29
29
|
export declare function isDatabricksModelService(model: string | undefined): boolean;
|
|
30
|
+
/**
|
|
31
|
+
* Strip the `databricks/` routing prefix from a model reference at the wire boundary.
|
|
32
|
+
* Callers may keep the full `databricks/<endpoint>` form (config `run.model`, job `model`);
|
|
33
|
+
* mode selection and the serving/gateway request must see the workspace-native name —
|
|
34
|
+
* serving endpoints 404 (`ENDPOINT_NOT_FOUND`) on the prefixed form.
|
|
35
|
+
*/
|
|
36
|
+
export declare function databricksNativeModelId(model: string | undefined): string | undefined;
|
|
30
37
|
/**
|
|
31
38
|
* Databricks inference provider supporting both Unity AI Gateway model services and custom
|
|
32
39
|
* Model Serving endpoints. In `auto` mode, fully-qualified `system.ai.*` models use AI Gateway and
|
package/dist/model.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EAKd,MAAM,qBAAqB,CAAC;AAI7B,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,YAAY,GAAG,mBAAmB,CAAC;AAElF,MAAM,MAAM,qBAAqB,GAC7B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtB,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;AAErE,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACjD,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sFAAsF;IACtF,IAAI,CAAC,EAAE,uBAAuB,CAAC;IAC/B,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EACJ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtB,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACrE,oEAAoE;IACpE,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC;IACtF,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,mFAAmF;AACnF,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,CAAC,uBAAuB,EAAE,MAAM,CAAC,GAC7C,MAAM,CAKR;AAED,qFAAqF;AACrF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAE3E;
|
|
1
|
+
{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EAKd,MAAM,qBAAqB,CAAC;AAI7B,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,YAAY,GAAG,mBAAmB,CAAC;AAElF,MAAM,MAAM,qBAAqB,GAC7B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtB,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;AAErE,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACjD,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sFAAsF;IACtF,IAAI,CAAC,EAAE,uBAAuB,CAAC;IAC/B,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EACJ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtB,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACrE,oEAAoE;IACpE,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC;IACtF,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,mFAAmF;AACnF,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,CAAC,uBAAuB,EAAE,MAAM,CAAC,GAC7C,MAAM,CAKR;AAED,qFAAqF;AACrF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAE3E;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAIrF;AA4GD;;;;GAIG;AACH,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,sBAAsB,GAAG,aAAa,CAEhG;AAgED,sDAAsD;AACtD,wBAAgB,+BAA+B,IAAI,IAAI,CAItD"}
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
import { type DatabricksGenieAdmin, type DatabricksGenieSqlPolicy } from "./genie-authoring.js";
|
|
2
|
+
import { type DatabricksManagedResourceStore } from "./managed-resource.js";
|
|
3
|
+
import type { DatabricksDomainAssignment, DatabricksGlossaryTerm, DatabricksOntologyExportPlan, DatabricksOntologyFeedTableKind } from "./ontology-export.js";
|
|
4
|
+
import { type DatabricksStatementClient, type StatementPoll } from "./sql-exec.js";
|
|
5
|
+
/** Writes apply can perform; each maps to one approval request. */
|
|
6
|
+
export type DatabricksOntologyApplyOperation = "metric-view-ddl" | "feed-table-ddl" | "domain-assignment" | "glossary-publish" | "genie-agent-create" | "genie-agent-update";
|
|
7
|
+
/**
|
|
8
|
+
* Approval request for one authoring write, mirroring the governance metadata
|
|
9
|
+
* the authoring ToolDefs declare (`effect`, governed resource, principal).
|
|
10
|
+
*/
|
|
11
|
+
export interface DatabricksOntologyApplyApprovalRequest {
|
|
12
|
+
/** Every apply mutation is an authoring write. */
|
|
13
|
+
effect: "write";
|
|
14
|
+
operation: DatabricksOntologyApplyOperation;
|
|
15
|
+
/** Governed resource being written. */
|
|
16
|
+
resource: {
|
|
17
|
+
kind: "metric-view" | "feed-table" | "glossary-domain" | "genie-agent";
|
|
18
|
+
id: string;
|
|
19
|
+
catalog?: string;
|
|
20
|
+
};
|
|
21
|
+
/** Exporting principal label (never a token). */
|
|
22
|
+
principal: string;
|
|
23
|
+
/** Stable correlation id for this apply invocation. */
|
|
24
|
+
toolCallId: string;
|
|
25
|
+
/** Fingerprint of the plan being applied. */
|
|
26
|
+
planFingerprint: string;
|
|
27
|
+
/** Fingerprint of the exact content this write admits. */
|
|
28
|
+
contentFingerprint: string;
|
|
29
|
+
/** Human-reviewable summary of the write. */
|
|
30
|
+
summary: string;
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Approval gate invoked before every apply write. Return/resolve to approve;
|
|
34
|
+
* throw to deny. This is the caller's hook into the existing steward approval
|
|
35
|
+
* flow — apply itself never approves.
|
|
36
|
+
*/
|
|
37
|
+
export type DatabricksOntologyApplyApproval = (request: DatabricksOntologyApplyApprovalRequest) => void | Promise<void>;
|
|
38
|
+
/**
|
|
39
|
+
* Glossary/domain publish client (design Q6: the UC glossary REST surface is
|
|
40
|
+
* still preview-tracked). Callers inject the governed client; when omitted,
|
|
41
|
+
* glossary and domain artifacts are reported as planned-but-unpublished and
|
|
42
|
+
* no glossary write occurs.
|
|
43
|
+
*/
|
|
44
|
+
export interface DatabricksOntologyGlossaryPublisher {
|
|
45
|
+
publishDomain(assignment: DatabricksDomainAssignment): Promise<void>;
|
|
46
|
+
upsertTerms(domain: string, terms: readonly DatabricksGlossaryTerm[]): Promise<void>;
|
|
47
|
+
}
|
|
48
|
+
/** Genie wiring for apply: the fingerprinted authoring client plus an optional existing agent. */
|
|
49
|
+
export interface DatabricksOntologyApplyGenieOptions {
|
|
50
|
+
/**
|
|
51
|
+
* Existing fingerprinted authoring client. Construct it with the same
|
|
52
|
+
* `managedResourceStore` passed to apply so ownership provenance and
|
|
53
|
+
* no-op/conflict detection share one record set.
|
|
54
|
+
*/
|
|
55
|
+
admin: DatabricksGenieAdmin;
|
|
56
|
+
/** Existing agent to update; omit to create (or reuse the agent a prior apply created). */
|
|
57
|
+
agentId?: string;
|
|
58
|
+
}
|
|
59
|
+
export interface DatabricksOntologyApplyOptions {
|
|
60
|
+
/** Managed-resource provenance store shared with the Genie admin client. */
|
|
61
|
+
resourceStore: DatabricksManagedResourceStore;
|
|
62
|
+
/** Exporting principal label recorded in provenance (never a token). */
|
|
63
|
+
principal: string;
|
|
64
|
+
/** Stable correlation id for this apply invocation (provenance + approval). */
|
|
65
|
+
toolCallId: string;
|
|
66
|
+
/** Governed statement-execution client for metric-view DDL. */
|
|
67
|
+
statements: DatabricksStatementClient;
|
|
68
|
+
/** Warehouse that executes the metric-view DDL. */
|
|
69
|
+
warehouseId: string;
|
|
70
|
+
/** Required approval gate; invoked once per write, immediately before it. */
|
|
71
|
+
approval: DatabricksOntologyApplyApproval;
|
|
72
|
+
/**
|
|
73
|
+
* Fail-closed SQL admission policy. Required when the plan's Genie spec
|
|
74
|
+
* carries SQL fragments (measure snippets, joins, examples, benchmarks);
|
|
75
|
+
* apply throws before any write if it is missing.
|
|
76
|
+
*/
|
|
77
|
+
sqlPolicy?: DatabricksGenieSqlPolicy;
|
|
78
|
+
/** Required when the plan carries a Genie spec. */
|
|
79
|
+
genie?: DatabricksOntologyApplyGenieOptions;
|
|
80
|
+
/** Glossary/domain publish client; omit to leave glossary artifacts unpublished. */
|
|
81
|
+
glossary?: DatabricksOntologyGlossaryPublisher;
|
|
82
|
+
/** Statement polling bounds for DDL execution. */
|
|
83
|
+
poll?: StatementPoll;
|
|
84
|
+
/** Clock injection for tests. */
|
|
85
|
+
now?: () => Date;
|
|
86
|
+
signal?: AbortSignal;
|
|
87
|
+
}
|
|
88
|
+
/** One metric view after apply (or after no-op detection). */
|
|
89
|
+
export interface DatabricksOntologyAppliedMetricView {
|
|
90
|
+
/** Fully-qualified `catalog.schema.<namespace>_metrics` name. */
|
|
91
|
+
view: string;
|
|
92
|
+
/** Fingerprint of the applied DDL statement. */
|
|
93
|
+
fingerprint: string;
|
|
94
|
+
/** True when this apply executed the DDL; false when the recorded fingerprint already matched. */
|
|
95
|
+
applied: boolean;
|
|
96
|
+
/** Managed-resource provenance record id (`<resourceType>/<resourceId>`). */
|
|
97
|
+
provenanceRecordId: string;
|
|
98
|
+
}
|
|
99
|
+
/** One glossary domain after apply (or after no-op detection / publisher-less apply). */
|
|
100
|
+
export interface DatabricksOntologyAppliedGlossaryDomain {
|
|
101
|
+
domain: string;
|
|
102
|
+
namespace: string;
|
|
103
|
+
termCount: number;
|
|
104
|
+
/** Fingerprint of the domain assignment plus its terms. */
|
|
105
|
+
fingerprint: string;
|
|
106
|
+
/** True when this apply published; false when unchanged or unpublished. */
|
|
107
|
+
applied: boolean;
|
|
108
|
+
/** False when no glossary publisher was configured (plan-only artifact). */
|
|
109
|
+
published: boolean;
|
|
110
|
+
provenanceRecordId?: string;
|
|
111
|
+
}
|
|
112
|
+
/** The Genie Agent after apply. */
|
|
113
|
+
export interface DatabricksOntologyAppliedGenieAgent {
|
|
114
|
+
agentId: string;
|
|
115
|
+
/** Post-apply canonical fingerprint. */
|
|
116
|
+
fingerprint: string;
|
|
117
|
+
created: boolean;
|
|
118
|
+
updated: boolean;
|
|
119
|
+
provenanceRecordId: string;
|
|
120
|
+
}
|
|
121
|
+
/** One feed table after apply (or after no-op detection). */
|
|
122
|
+
export interface DatabricksOntologyAppliedFeedTable {
|
|
123
|
+
/** Feed table kind (design §3.7). */
|
|
124
|
+
kind: DatabricksOntologyFeedTableKind;
|
|
125
|
+
/** Fully-qualified `catalog.schema.<namespace>_<kind>` name. */
|
|
126
|
+
table: string;
|
|
127
|
+
/** Fingerprint of the applied DDL statement. */
|
|
128
|
+
fingerprint: string;
|
|
129
|
+
/** True when this apply executed the DDL; false when the recorded fingerprint already matched. */
|
|
130
|
+
applied: boolean;
|
|
131
|
+
/** Managed-resource provenance record id (`<resourceType>/<resourceId>`). */
|
|
132
|
+
provenanceRecordId: string;
|
|
133
|
+
}
|
|
134
|
+
/** Apply outcome: applied artifacts, provenance record ids, and post-apply fingerprints. */
|
|
135
|
+
export interface DatabricksOntologyExportResult {
|
|
136
|
+
planFingerprint: string;
|
|
137
|
+
/** True when every artifact already matched the recorded state; no writes occurred. */
|
|
138
|
+
noChanges: boolean;
|
|
139
|
+
/** ISO timestamp of the apply; absent when nothing changed. */
|
|
140
|
+
appliedAt?: string;
|
|
141
|
+
metricViews: DatabricksOntologyAppliedMetricView[];
|
|
142
|
+
feedTables: DatabricksOntologyAppliedFeedTable[];
|
|
143
|
+
glossaryDomains: DatabricksOntologyAppliedGlossaryDomain[];
|
|
144
|
+
/** Glossary terms published by this apply (0 on no-op or publisher-less apply). */
|
|
145
|
+
glossaryTermCount: number;
|
|
146
|
+
genieAgent?: DatabricksOntologyAppliedGenieAgent;
|
|
147
|
+
/** Append-only export provenance record id; absent when nothing changed. */
|
|
148
|
+
exportRecordId?: string;
|
|
149
|
+
}
|
|
150
|
+
/**
|
|
151
|
+
* Apply a deterministic ontology export plan through the governed authoring
|
|
152
|
+
* seams. See the module header for the approval, conflict, SQL-policy,
|
|
153
|
+
* provenance, and no-op contracts.
|
|
154
|
+
*/
|
|
155
|
+
export declare function applyModuleOntologyExport(plan: DatabricksOntologyExportPlan, options: DatabricksOntologyApplyOptions): Promise<DatabricksOntologyExportResult>;
|
|
156
|
+
//# sourceMappingURL=ontology-apply.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ontology-apply.d.ts","sourceRoot":"","sources":["../src/ontology-apply.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
import type { ExecutionAttestation } from "@fabricorg/platform/governance";
|
|
2
|
+
import type { DatabricksOntologyExportPlan } from "./ontology-export.js";
|
|
3
|
+
/**
|
|
4
|
+
* Declared-vs-inferred drift comparison (P2-1) and attestation emission
|
|
5
|
+
* (P2-2) for the Genie Ontology exporter (design §4, §5).
|
|
6
|
+
*
|
|
7
|
+
* Genie Ontology's knowledge store *infers* expressions, synonyms, concepts,
|
|
8
|
+
* and experts; the module manifest — through the export plan's glossary terms
|
|
9
|
+
* and policy classifications — *declares* semantics. They will diverge. This
|
|
10
|
+
* module compares the two and surfaces the divergence as audit evidence. The
|
|
11
|
+
* precedence rules of design §4 are encoded directly in the finding severity:
|
|
12
|
+
*
|
|
13
|
+
* - **The manifest is authoritative for mutation semantics.** An inference
|
|
14
|
+
* that contradicts a declared definition is a `conflict` finding — it never
|
|
15
|
+
* changes mutation behavior (Genie cannot mutate anyway) and is routed to
|
|
16
|
+
* steward review.
|
|
17
|
+
* - **Inference is tolerated for analytics only.** A learned synonym for a
|
|
18
|
+
* declared term or a learned expression over a declared measure is an
|
|
19
|
+
* `analytics-only` finding: it may improve answer quality as long as metric
|
|
20
|
+
* math resolves to the UC Metric Views the exporter generated.
|
|
21
|
+
* - **Drift is surfaced as evidence, never auto-applied.** Nothing in this
|
|
22
|
+
* module writes back: the knowledge-store client interface is read-only by
|
|
23
|
+
* construction, the comparison is pure, and the only side effect is one
|
|
24
|
+
* append per run to the caller-supplied evidence sink. There is deliberately
|
|
25
|
+
* no apply/update path here — re-export stays behind the P0-6 fingerprinted
|
|
26
|
+
* conflict contract (`DatabricksManagedResourceConflictError`), and nothing
|
|
27
|
+
* flows back into the `FabricModule` without a human changing governed code.
|
|
28
|
+
*
|
|
29
|
+
* **Preview caveat (design Q1).** Knowledge-store read APIs are still
|
|
30
|
+
* preview/unsettled. The wire shape is therefore hidden behind the narrow
|
|
31
|
+
* injectable `DatabricksGenieKnowledgeStoreReader` interface — one read
|
|
32
|
+
* method returning plain data — so a preview-API change reshapes only the
|
|
33
|
+
* caller's adapter, never this module. The comparison itself runs against
|
|
34
|
+
* plain fixtures, credential-free.
|
|
35
|
+
*
|
|
36
|
+
* Comparison semantics: matching keys on normalized references (the inferred
|
|
37
|
+
* concept's `target`, falling back to its `name`), not on SQL or definition
|
|
38
|
+
* text — measure-expression equivalence is out of scope because the plan does
|
|
39
|
+
* not carry declared expression text outside the generated DDL. Both
|
|
40
|
+
* `compareOntologyDrift` and the finding order are deterministic: no network,
|
|
41
|
+
* no clock, no randomness. `attestOntologyDrift` wraps the comparison with
|
|
42
|
+
* the injected read, the append-only attestation record (built through
|
|
43
|
+
* `databricksExecutionAttestation` from `platform.ts`), and steward routing;
|
|
44
|
+
* its only clock read is the record timestamp, injectable for tests.
|
|
45
|
+
*/
|
|
46
|
+
/** Inferred concept kinds the Genie knowledge store learns (design §4). */
|
|
47
|
+
export type DatabricksGenieInferredConceptKind = "expression" | "synonym" | "concept" | "expert";
|
|
48
|
+
/**
|
|
49
|
+
* One inferred concept read from the Genie knowledge store. Plain data: the
|
|
50
|
+
* preview wire shape is the caller's adapter concern (design Q1).
|
|
51
|
+
*/
|
|
52
|
+
export interface DatabricksGenieInferredConcept {
|
|
53
|
+
kind: DatabricksGenieInferredConceptKind;
|
|
54
|
+
/** Stable knowledge-store reference for the inference. */
|
|
55
|
+
id: string;
|
|
56
|
+
/** Human-facing label the store inferred (e.g. "loan app"). */
|
|
57
|
+
name: string;
|
|
58
|
+
/**
|
|
59
|
+
* Declared vocabulary element the inference maps onto (a glossary term or
|
|
60
|
+
* measure/policy id), when the store reports one. Matching prefers this
|
|
61
|
+
* over `name`.
|
|
62
|
+
*/
|
|
63
|
+
target?: string;
|
|
64
|
+
/** Inferred definition or expression text, when the store reports one. */
|
|
65
|
+
definition?: string;
|
|
66
|
+
}
|
|
67
|
+
/** The knowledge store's inferred concepts, as plain data. */
|
|
68
|
+
export interface DatabricksGenieInferredKnowledge {
|
|
69
|
+
concepts: DatabricksGenieInferredConcept[];
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Injectable read-only knowledge-store client (design Q1). The interface has
|
|
73
|
+
* exactly one method and no write surface: drift detection can never mutate
|
|
74
|
+
* the knowledge store, a Genie Agent spec, or any declared definition through
|
|
75
|
+
* this seam. Callers plug in whatever the preview API exposes.
|
|
76
|
+
*/
|
|
77
|
+
export interface DatabricksGenieKnowledgeStoreReader {
|
|
78
|
+
readInferredConcepts(input: {
|
|
79
|
+
/** Genie Agent scope for the read, when the run targets one agent. */
|
|
80
|
+
agentId?: string;
|
|
81
|
+
}): Promise<DatabricksGenieInferredKnowledge> | DatabricksGenieInferredKnowledge;
|
|
82
|
+
}
|
|
83
|
+
/** Drift finding taxonomy (design §4; P2-1 acceptance). */
|
|
84
|
+
export type DatabricksOntologyDriftFindingKind = "inferred-synonym-vs-declared-term" | "inferred-expression-vs-declared-measure" | "inferred-concept-without-declared-counterpart" | "declared-definition-without-inferred-counterpart";
|
|
85
|
+
/**
|
|
86
|
+
* Finding severity, encoding the §4 precedence:
|
|
87
|
+
* - `conflict` — the inference contradicts a declared definition (e.g. a
|
|
88
|
+
* learned synonym whose label collides with a different declared term than
|
|
89
|
+
* its target). The manifest stays authoritative; steward review required.
|
|
90
|
+
* - `analytics-only` — a tolerated inference mapped onto a declared
|
|
91
|
+
* definition; it may improve answer quality and never touches mutation
|
|
92
|
+
* semantics.
|
|
93
|
+
* - `informational` — no counterpart on one side; observation only.
|
|
94
|
+
*/
|
|
95
|
+
export type DatabricksOntologyDriftSeverity = "conflict" | "analytics-only" | "informational";
|
|
96
|
+
/** Reference to the declared side of a finding (from the export plan). */
|
|
97
|
+
export interface DatabricksOntologyDriftDeclaredReference {
|
|
98
|
+
kind: "term" | "measure";
|
|
99
|
+
/** Glossary term name, or the declaring policy id for a measure. */
|
|
100
|
+
id: string;
|
|
101
|
+
/** UC domain for terms; module namespace for measures. */
|
|
102
|
+
domain: string;
|
|
103
|
+
}
|
|
104
|
+
/** Reference to the inferred side of a finding (from the knowledge store). */
|
|
105
|
+
export interface DatabricksOntologyDriftInferredReference {
|
|
106
|
+
kind: DatabricksGenieInferredConceptKind;
|
|
107
|
+
id: string;
|
|
108
|
+
name: string;
|
|
109
|
+
}
|
|
110
|
+
/** One classified drift finding, carrying both references and steward-reviewable evidence. */
|
|
111
|
+
export interface DatabricksOntologyDriftFinding {
|
|
112
|
+
kind: DatabricksOntologyDriftFindingKind;
|
|
113
|
+
severity: DatabricksOntologyDriftSeverity;
|
|
114
|
+
/** Absent for `inferred-concept-without-declared-counterpart`. */
|
|
115
|
+
declared?: DatabricksOntologyDriftDeclaredReference;
|
|
116
|
+
/** Absent for `declared-definition-without-inferred-counterpart`. */
|
|
117
|
+
inferred?: DatabricksOntologyDriftInferredReference;
|
|
118
|
+
/** Human-reviewable explanation of the match and the classification. */
|
|
119
|
+
evidence: string;
|
|
120
|
+
}
|
|
121
|
+
/** Deterministic comparison result: findings plus per-kind counts for steward triage. */
|
|
122
|
+
export interface DatabricksOntologyDriftComparison {
|
|
123
|
+
/** Fingerprint of the plan the declared side was taken from. */
|
|
124
|
+
planFingerprint: string;
|
|
125
|
+
findings: DatabricksOntologyDriftFinding[];
|
|
126
|
+
counts: Record<DatabricksOntologyDriftFindingKind, number>;
|
|
127
|
+
}
|
|
128
|
+
/** Input for the pure comparison: the declared plan plus plain inferred data. */
|
|
129
|
+
export interface DatabricksOntologyDriftComparisonInput {
|
|
130
|
+
plan: DatabricksOntologyExportPlan;
|
|
131
|
+
inferred: DatabricksGenieInferredKnowledge;
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* Append-only audit sink for drift attestation records (design §5). Each
|
|
135
|
+
* `attestOntologyDrift` run appends exactly one record; the sink contract is
|
|
136
|
+
* append-only — historical records are never read back or rewritten here.
|
|
137
|
+
*/
|
|
138
|
+
export interface DatabricksOntologyDriftEvidenceSink {
|
|
139
|
+
append(record: DatabricksOntologyDriftAttestationRecord): Promise<void> | void;
|
|
140
|
+
}
|
|
141
|
+
/** Options for the attestation entry point (P2-2). */
|
|
142
|
+
export interface DatabricksOntologyDriftAttestationOptions {
|
|
143
|
+
/**
|
|
144
|
+
* Steward audience the drift record routes to, mirroring how
|
|
145
|
+
* `governance.stewardAudience` is threaded through the Databricks config.
|
|
146
|
+
* Required; an empty audience fails closed like the governance pack.
|
|
147
|
+
*/
|
|
148
|
+
stewardAudience: string;
|
|
149
|
+
/** Injectable read-only knowledge-store client (design Q1). */
|
|
150
|
+
knowledgeStore: DatabricksGenieKnowledgeStoreReader;
|
|
151
|
+
/** Genie Agent scope for the knowledge-store read and the attestation resource. */
|
|
152
|
+
agentId?: string;
|
|
153
|
+
/** Append-only audit sink; receives exactly one record per run. */
|
|
154
|
+
evidence: DatabricksOntologyDriftEvidenceSink;
|
|
155
|
+
/** Workspace host for the attestation resource reference, when available. */
|
|
156
|
+
workspaceHost?: string;
|
|
157
|
+
/** Clock injection for tests; the comparison itself never reads the clock. */
|
|
158
|
+
now?: () => Date;
|
|
159
|
+
}
|
|
160
|
+
/**
|
|
161
|
+
* One append-only drift attestation record (design §5). `runId` is a content
|
|
162
|
+
* fingerprint of the plan, the findings, and the steward audience, so the
|
|
163
|
+
* record is deterministic for an identical comparison; every run still
|
|
164
|
+
* appends its own record — historical evidence is never rewritten.
|
|
165
|
+
*/
|
|
166
|
+
export interface DatabricksOntologyDriftAttestationRecord {
|
|
167
|
+
/** Stable content fingerprint of this drift run. */
|
|
168
|
+
runId: string;
|
|
169
|
+
/** Steward audience the record routes to. */
|
|
170
|
+
stewardAudience: string;
|
|
171
|
+
planFingerprint: string;
|
|
172
|
+
comparison: DatabricksOntologyDriftComparison;
|
|
173
|
+
/** Audit-safe attestation built via `databricksExecutionAttestation`. */
|
|
174
|
+
attestation: ExecutionAttestation;
|
|
175
|
+
/** ISO timestamp of the run. */
|
|
176
|
+
recordedAt: string;
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* Pure declared-vs-inferred comparison (P2-1). No network, no clock, no
|
|
180
|
+
* randomness — the knowledge-store fetch is the caller's concern and is
|
|
181
|
+
* injected; this function runs credential-free against plain data.
|
|
182
|
+
*
|
|
183
|
+
* Matching rules: a synonym maps onto a declared term, an expression onto a
|
|
184
|
+
* declared measure, preferring the concept's `target` over its `name`. A
|
|
185
|
+
* mapped inference whose label collides with a *different* declared entry
|
|
186
|
+
* than its target is a `conflict`; otherwise it is `analytics-only`. An
|
|
187
|
+
* inference with no declared counterpart (including every inferred expert —
|
|
188
|
+
* experts are never declared vocabulary) is `informational`, as is a declared
|
|
189
|
+
* definition no inference observed. An inference whose label exactly restates
|
|
190
|
+
* its declared target is agreement, not drift, and produces no finding.
|
|
191
|
+
*/
|
|
192
|
+
export declare function compareOntologyDrift(input: DatabricksOntologyDriftComparisonInput): DatabricksOntologyDriftComparison;
|
|
193
|
+
/**
|
|
194
|
+
* Read the knowledge store through the injected client, compare it against
|
|
195
|
+
* the declared plan, and append one attestation record routed to steward
|
|
196
|
+
* review (P2-2; design §4 rule 3, §5 append-only audit evidence).
|
|
197
|
+
*
|
|
198
|
+
* Hard invariant: this function performs no write other than the single
|
|
199
|
+
* `evidence.append`. The knowledge-store interface is read-only by
|
|
200
|
+
* construction, and no Genie Agent spec, metric view, glossary, or manifest
|
|
201
|
+
* mutation path exists in this module — drift never auto-applies; re-export
|
|
202
|
+
* stays behind the P0-6 fingerprinted conflict contract.
|
|
203
|
+
*/
|
|
204
|
+
export declare function attestOntologyDrift(plan: DatabricksOntologyExportPlan, options: DatabricksOntologyDriftAttestationOptions): Promise<DatabricksOntologyDriftAttestationRecord>;
|
|
205
|
+
//# sourceMappingURL=ontology-drift.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ontology-drift.d.ts","sourceRoot":"","sources":["../src/ontology-drift.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
import type { ModuleManifest, ModuleManifestBundle } from "@fabricorg/platform/manifest";
|
|
2
|
+
import type { DatabricksGenieAdmin, DatabricksGenieAgentSpecV2 } from "./genie-authoring.js";
|
|
3
|
+
/**
|
|
4
|
+
* Durable generation of the module-ontology export plan shape. Bump when the
|
|
5
|
+
* serialized plan changes in a way plan-diff consumers must detect.
|
|
6
|
+
*/
|
|
7
|
+
export declare const DATABRICKS_ONTOLOGY_EXPORT_PLAN_VERSION = "1";
|
|
8
|
+
/**
|
|
9
|
+
* Genie Agent wiring for an ontology export. `admin` is the existing
|
|
10
|
+
* fingerprinted authoring client; `applyModuleOntologyExport`
|
|
11
|
+
* (`ontology-apply.ts`) routes every spec write through it with
|
|
12
|
+
* `expectedFingerprint` conflict detection.
|
|
13
|
+
*/
|
|
14
|
+
export interface DatabricksOntologyExportGenieOptions {
|
|
15
|
+
/** Existing agent to update; omit to create a new one. */
|
|
16
|
+
agentId?: string;
|
|
17
|
+
admin: DatabricksGenieAdmin;
|
|
18
|
+
parentPath: string;
|
|
19
|
+
warehouseId: string;
|
|
20
|
+
/**
|
|
21
|
+
* Vertical-declared sensitive-field fragments (design §3.6 parameter-name
|
|
22
|
+
* sensitivity rule). Action parameter names matching any fragment — or the
|
|
23
|
+
* built-in denylist (`password`, `secret`, `token`, `ssn`, …) — are never
|
|
24
|
+
* interpolated into derived sample questions, synonyms, or instructions.
|
|
25
|
+
*/
|
|
26
|
+
sensitiveFieldPatterns?: string[];
|
|
27
|
+
}
|
|
28
|
+
/** Operational-truth feed tables a module can publish, per the exporter design §3.7. */
|
|
29
|
+
export type DatabricksOntologyFeedTableKind = "asset_events" | "action_invocations" | "policy_evaluations";
|
|
30
|
+
/**
|
|
31
|
+
* Feed planning options (design §3.7). The plan generator
|
|
32
|
+
* (`ontology-feed.ts`, P1-1) is pure and deterministic; the redacted-record
|
|
33
|
+
* producer is deliberately NOT a plan option — redaction is a runtime boundary
|
|
34
|
+
* owned by the vertical (P1-3) and a function here would break the plan's
|
|
35
|
+
* canonical fingerprint. Row materialization requires it instead.
|
|
36
|
+
*/
|
|
37
|
+
export interface DatabricksOntologyFeedOptions {
|
|
38
|
+
/** Feed tables to plan; defaults to all three when feed planning is enabled. */
|
|
39
|
+
tables?: DatabricksOntologyFeedTableKind[];
|
|
40
|
+
}
|
|
41
|
+
export interface DatabricksOntologyExportOptions {
|
|
42
|
+
/** Single module manifest or an order-preserving bundle from `@fabricorg/platform/manifest`. */
|
|
43
|
+
manifest: ModuleManifest | ModuleManifestBundle;
|
|
44
|
+
/** Target Unity Catalog catalog. */
|
|
45
|
+
catalog: string;
|
|
46
|
+
/** Target schema for metric views and feed tables. */
|
|
47
|
+
schema: string;
|
|
48
|
+
/** UC domain assignment; defaults to each manifest's namespace. */
|
|
49
|
+
domain?: string;
|
|
50
|
+
/**
|
|
51
|
+
* Explicit opt-in promoting code-evaluator policies to metric seeds (design
|
|
52
|
+
* §3.4). The policy classifier (P0-3) is the only consumer; listing a policy
|
|
53
|
+
* here is the single supported escape hatch.
|
|
54
|
+
*/
|
|
55
|
+
metricSeedPolicyIds?: string[];
|
|
56
|
+
genie?: DatabricksOntologyExportGenieOptions;
|
|
57
|
+
feed?: DatabricksOntologyFeedOptions;
|
|
58
|
+
}
|
|
59
|
+
/** Policy classification per design §3.4. */
|
|
60
|
+
export type DatabricksOntologyPolicyClass = "threshold-ratio-metric" | "gate-compliance-rule" | "code-evaluator";
|
|
61
|
+
/**
|
|
62
|
+
* Explainable classification record for one manifest policy (design §3.4).
|
|
63
|
+
* Classification is conservative: ambiguity defaults to a glossary business
|
|
64
|
+
* rule, and a compliance gate must never silently become a KPI.
|
|
65
|
+
*/
|
|
66
|
+
export interface DatabricksOntologyPolicyClassification {
|
|
67
|
+
/** Namespace of the module that declares the policy. */
|
|
68
|
+
namespace: string;
|
|
69
|
+
policyId: string;
|
|
70
|
+
policyVersion: number;
|
|
71
|
+
policyType: ModuleManifest["policies"][number]["type"];
|
|
72
|
+
class: DatabricksOntologyPolicyClass;
|
|
73
|
+
/** Matched classification rule or the explicit `metricSeedPolicyIds` annotation. */
|
|
74
|
+
evidence: string;
|
|
75
|
+
/** Where the policy lands in the export. */
|
|
76
|
+
target: "metric-view-measure" | "glossary-business-rule";
|
|
77
|
+
}
|
|
78
|
+
/** Which manifest vocabulary group a glossary term was derived from (design §3.3). */
|
|
79
|
+
export type DatabricksGlossaryTermKind = "object-type" | "subject-type" | "event-type" | "lifecycle-action" | "business-rule" | "state";
|
|
80
|
+
/**
|
|
81
|
+
* A Unity Catalog glossary term upsert payload, generated by
|
|
82
|
+
* `ontology-glossary.ts` (P0-4). Plan data only — the governed publish path
|
|
83
|
+
* lands with the apply ticket.
|
|
84
|
+
*/
|
|
85
|
+
export interface DatabricksGlossaryTerm {
|
|
86
|
+
kind: DatabricksGlossaryTermKind;
|
|
87
|
+
name: string;
|
|
88
|
+
domain: string;
|
|
89
|
+
definition?: string;
|
|
90
|
+
/** Provenance metadata such as `manifestVersion` / `schemaVersion`. */
|
|
91
|
+
metadata?: Record<string, string>;
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* Binding of a module namespace to its UC domain (one domain per namespace;
|
|
95
|
+
* the `domain` option overrides the default), generated by
|
|
96
|
+
* `ontology-glossary.ts` (P0-4).
|
|
97
|
+
*/
|
|
98
|
+
export interface DatabricksDomainAssignment {
|
|
99
|
+
namespace: string;
|
|
100
|
+
domain: string;
|
|
101
|
+
comment?: string;
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* One operational-truth feed table spec (design §3.7), generated by
|
|
105
|
+
* `ontology-feed.ts` (P1-1). The DDL is deterministic and append-only; the
|
|
106
|
+
* governed apply path executes it through the same approval/provenance seams
|
|
107
|
+
* as the metric-view DDL.
|
|
108
|
+
*/
|
|
109
|
+
export interface DatabricksFeedTableSpec {
|
|
110
|
+
kind: DatabricksOntologyFeedTableKind;
|
|
111
|
+
/** Fully-qualified `catalog.schema.table` name. */
|
|
112
|
+
table: string;
|
|
113
|
+
/**
|
|
114
|
+
* Deterministic `CREATE TABLE IF NOT EXISTS ... USING DELTA` statement with
|
|
115
|
+
* the managed tag, a feed-fingerprint comment, and
|
|
116
|
+
* `TBLPROPERTIES ('delta.appendOnly' = 'true')`.
|
|
117
|
+
*/
|
|
118
|
+
ddl: string;
|
|
119
|
+
/**
|
|
120
|
+
* Platform id column the hydration pipeline merges on
|
|
121
|
+
* (`MERGE ... WHEN NOT MATCHED THEN INSERT`), making re-hydration idempotent.
|
|
122
|
+
*/
|
|
123
|
+
replayKey: string;
|
|
124
|
+
/**
|
|
125
|
+
* Publishable-field allowlist; row materialization drops anything not listed
|
|
126
|
+
* before Delta append, so PII/PHI never reaches Genie's training surface.
|
|
127
|
+
*/
|
|
128
|
+
publishableFields: string[];
|
|
129
|
+
}
|
|
130
|
+
/** Option-derived export target for one manifest, in bundle declaration order. */
|
|
131
|
+
export interface DatabricksOntologyModuleTarget {
|
|
132
|
+
namespace: string;
|
|
133
|
+
manifestVersion: ModuleManifest["manifestVersion"];
|
|
134
|
+
catalog: string;
|
|
135
|
+
schema: string;
|
|
136
|
+
domain: string;
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* Deterministic export plan (design §3.2, KD-6). `metricViewDdl` and
|
|
140
|
+
* `policyClassifications` are populated by the P0-2/P0-3 generators
|
|
141
|
+
* (`ontology-metric-view.ts`); `glossaryTerms` and `domainAssignments` by the
|
|
142
|
+
* P0-4 generator (`ontology-glossary.ts`); `genieSpec` by the P0-5 derivation
|
|
143
|
+
* (`ontology-genie-spec.ts`, only when `options.genie` is present);
|
|
144
|
+
* `feedTables` by the P1-1 generator (`ontology-feed.ts`, only when
|
|
145
|
+
* `options.feed` is present).
|
|
146
|
+
*/
|
|
147
|
+
export interface DatabricksOntologyExportPlan {
|
|
148
|
+
planVersion: typeof DATABRICKS_ONTOLOGY_EXPORT_PLAN_VERSION;
|
|
149
|
+
/** One target per manifest, preserving bundle declaration order. */
|
|
150
|
+
targets: DatabricksOntologyModuleTarget[];
|
|
151
|
+
metricViewDdl: string[];
|
|
152
|
+
glossaryTerms: DatabricksGlossaryTerm[];
|
|
153
|
+
domainAssignments: DatabricksDomainAssignment[];
|
|
154
|
+
policyClassifications: DatabricksOntologyPolicyClassification[];
|
|
155
|
+
genieSpec?: DatabricksGenieAgentSpecV2;
|
|
156
|
+
/**
|
|
157
|
+
* Canonical fingerprint of `genieSpec` computed exactly as
|
|
158
|
+
* `DatabricksGenieAdmin` fingerprints a fetched agent — the desired
|
|
159
|
+
* post-apply fingerprint. The apply path (`ontology-apply.ts`) compares it
|
|
160
|
+
* against the fingerprint recorded at last apply: a match is a no-op, and a
|
|
161
|
+
* mismatch triggers a governed update compare-and-swapped against the
|
|
162
|
+
* recorded fingerprint (design §3.6 — diffs key off the recorded
|
|
163
|
+
* fingerprint, not any manifest-internal hash).
|
|
164
|
+
*/
|
|
165
|
+
genieSpecFingerprint?: string;
|
|
166
|
+
feedTables?: DatabricksFeedTableSpec[];
|
|
167
|
+
/** Canonical fingerprint of the manifest plus all plan inputs. */
|
|
168
|
+
fingerprint: string;
|
|
169
|
+
}
|
|
170
|
+
/** Normalize a manifest or bundle into a declaration-ordered manifest list. */
|
|
171
|
+
export declare function normalizeModuleManifests(manifest: ModuleManifest | ModuleManifestBundle): ModuleManifest[];
|
|
172
|
+
/**
|
|
173
|
+
* Build the deterministic ontology export plan. Pure: no network, no clock, no
|
|
174
|
+
* randomness — identical inputs produce a byte-identical plan.
|
|
175
|
+
*
|
|
176
|
+
* Async only because the canonical fingerprint helper
|
|
177
|
+
* (`databricksResourceFingerprint`, SHA-256 over canonical JSON) is async;
|
|
178
|
+
* the computation itself is a pure function of `options`.
|
|
179
|
+
*/
|
|
180
|
+
export declare function planModuleOntologyExport(options: DatabricksOntologyExportOptions): Promise<DatabricksOntologyExportPlan>;
|
|
181
|
+
//# sourceMappingURL=ontology-export.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ontology-export.d.ts","sourceRoot":"","sources":["../src/ontology-export.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACzF,OAAO,KAAK,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAU7F;;;GAGG;AACH,eAAO,MAAM,uCAAuC,MAAM,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,WAAW,oCAAoC;IACnD,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,oBAAoB,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;CACnC;AAED,wFAAwF;AACxF,MAAM,MAAM,+BAA+B,GACvC,cAAc,GACd,oBAAoB,GACpB,oBAAoB,CAAC;AAEzB;;;;;;GAMG;AACH,MAAM,WAAW,6BAA6B;IAC5C,gFAAgF;IAChF,MAAM,CAAC,EAAE,+BAA+B,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,+BAA+B;IAC9C,gGAAgG;IAChG,QAAQ,EAAE,cAAc,GAAG,oBAAoB,CAAC;IAChD,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,KAAK,CAAC,EAAE,oCAAoC,CAAC;IAC7C,IAAI,CAAC,EAAE,6BAA6B,CAAC;CACtC;AAED,6CAA6C;AAC7C,MAAM,MAAM,6BAA6B,GACrC,wBAAwB,GACxB,sBAAsB,GACtB,gBAAgB,CAAC;AAErB;;;;GAIG;AACH,MAAM,WAAW,sCAAsC;IACrD,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;IACvD,KAAK,EAAE,6BAA6B,CAAC;IACrC,oFAAoF;IACpF,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,MAAM,EAAE,qBAAqB,GAAG,wBAAwB,CAAC;CAC1D;AAED,sFAAsF;AACtF,MAAM,MAAM,0BAA0B,GAClC,aAAa,GACb,cAAc,GACd,YAAY,GACZ,kBAAkB,GAClB,eAAe,GACf,OAAO,CAAC;AAEZ;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,0BAA0B,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,+BAA+B,CAAC;IACtC,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,kFAAkF;AAClF,MAAM,WAAW,8BAA8B;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,4BAA4B;IAC3C,WAAW,EAAE,OAAO,uCAAuC,CAAC;IAC5D,oEAAoE;IACpE,OAAO,EAAE,8BAA8B,EAAE,CAAC;IAC1C,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,sBAAsB,EAAE,CAAC;IACxC,iBAAiB,EAAE,0BAA0B,EAAE,CAAC;IAChD,qBAAqB,EAAE,sCAAsC,EAAE,CAAC;IAChE,SAAS,CAAC,EAAE,0BAA0B,CAAC;IACvC;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,UAAU,CAAC,EAAE,uBAAuB,EAAE,CAAC;IACvC,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,+EAA+E;AAC/E,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,cAAc,GAAG,oBAAoB,GAC9C,cAAc,EAAE,CAElB;AAQD;;;;;;;GAOG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,4BAA4B,CAAC,CA+GvC"}
|