@hypequery/datasets 0.13.6 → 0.15.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.
- package/README.md +10 -0
- package/dist/agent-catalog.d.ts +97 -0
- package/dist/agent-catalog.d.ts.map +1 -0
- package/dist/agent-catalog.js +79 -0
- package/dist/api.type-test.js +19 -1
- package/dist/catalog.d.ts +17 -6
- package/dist/catalog.d.ts.map +1 -1
- package/dist/catalog.js +18 -1
- package/dist/contract.d.ts +11 -7
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js +22 -1
- package/dist/dataset-query.js +1 -1
- package/dist/dataset.d.ts.map +1 -1
- package/dist/dataset.js +19 -2
- package/dist/executor.d.ts +6 -0
- package/dist/executor.d.ts.map +1 -1
- package/dist/executor.js +55 -23
- package/dist/field.d.ts.map +1 -1
- package/dist/field.js +2 -0
- package/dist/index.d.ts +12 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +9 -0
- package/dist/measure.d.ts.map +1 -1
- package/dist/measure.js +4 -0
- package/dist/portable-execution-errors.d.ts +49 -0
- package/dist/portable-execution-errors.d.ts.map +1 -0
- package/dist/portable-execution-errors.js +52 -0
- package/dist/portable-executor.d.ts +61 -0
- package/dist/portable-executor.d.ts.map +1 -0
- package/dist/portable-executor.js +90 -0
- package/dist/protocol-adapter.d.ts.map +1 -1
- package/dist/protocol-adapter.js +26 -97
- package/dist/protocol-rehydrate.d.ts +56 -0
- package/dist/protocol-rehydrate.d.ts.map +1 -0
- package/dist/protocol-rehydrate.js +264 -0
- package/dist/publishing/features/dataset-publication.d.ts +10 -0
- package/dist/publishing/features/dataset-publication.d.ts.map +1 -0
- package/dist/publishing/features/dataset-publication.js +34 -0
- package/dist/publishing/node.d.ts +16 -0
- package/dist/publishing/node.d.ts.map +1 -0
- package/dist/publishing/node.js +35 -0
- package/dist/publishing/publisher.d.ts +17 -0
- package/dist/publishing/publisher.d.ts.map +1 -0
- package/dist/publishing/publisher.js +32 -0
- package/dist/publishing/types.d.ts +31 -0
- package/dist/publishing/types.d.ts.map +1 -0
- package/dist/publishing/types.js +1 -0
- package/dist/query-builder-protocol.d.ts +6 -2
- package/dist/query-builder-protocol.d.ts.map +1 -1
- package/dist/semantic-plan.d.ts +3 -1
- package/dist/semantic-plan.d.ts.map +1 -1
- package/dist/semantic-planner.d.ts.map +1 -1
- package/dist/semantic-planner.js +4 -0
- package/dist/semantic-query-schema.d.ts +60 -0
- package/dist/semantic-query-schema.d.ts.map +1 -0
- package/dist/semantic-query-schema.js +223 -0
- package/dist/sql-utils.d.ts +36 -0
- package/dist/sql-utils.d.ts.map +1 -1
- package/dist/sql-utils.js +76 -0
- package/dist/tools.d.ts +5 -0
- package/dist/tools.d.ts.map +1 -1
- package/dist/tools.js +25 -267
- package/dist/types.d.ts +98 -8
- package/dist/types.d.ts.map +1 -1
- package/dist/utils/agent-catalog-projection.d.ts +78 -0
- package/dist/utils/agent-catalog-projection.d.ts.map +1 -0
- package/dist/utils/agent-catalog-projection.js +179 -0
- package/dist/utils/dataset-cache-policy.d.ts +34 -0
- package/dist/utils/dataset-cache-policy.d.ts.map +1 -0
- package/dist/utils/dataset-cache-policy.js +50 -0
- package/dist/utils/dataset-contract.d.ts +2 -2
- package/dist/utils/dataset-contract.d.ts.map +1 -1
- package/dist/utils/dataset-contract.js +3 -1
- package/dist/utils/dataset-definition-validation.d.ts +35 -0
- package/dist/utils/dataset-definition-validation.d.ts.map +1 -0
- package/dist/utils/dataset-definition-validation.js +215 -0
- package/dist/utils/dataset-metric-ref.d.ts +2 -2
- package/dist/utils/dataset-metric-ref.d.ts.map +1 -1
- package/dist/utils/dataset-metric-ref.js +5 -3
- package/dist/utils/metric-alias.d.ts +4 -0
- package/dist/utils/metric-alias.d.ts.map +1 -0
- package/dist/utils/metric-alias.js +28 -0
- package/dist/utils/portable-execution-deadline.d.ts +4 -0
- package/dist/utils/portable-execution-deadline.d.ts.map +1 -0
- package/dist/utils/portable-execution-deadline.js +27 -0
- package/dist/utils/portable-result-budget.d.ts +12 -0
- package/dist/utils/portable-result-budget.d.ts.map +1 -0
- package/dist/utils/portable-result-budget.js +21 -0
- package/dist/utils/portable-semantic-query.d.ts +5 -0
- package/dist/utils/portable-semantic-query.d.ts.map +1 -0
- package/dist/utils/portable-semantic-query.js +36 -0
- package/dist/utils/protocol-metric-capabilities.d.ts +7 -0
- package/dist/utils/protocol-metric-capabilities.d.ts.map +1 -0
- package/dist/utils/protocol-metric-capabilities.js +57 -0
- package/dist/utils/protocol-metric-expressions.d.ts +17 -0
- package/dist/utils/protocol-metric-expressions.d.ts.map +1 -0
- package/dist/utils/protocol-metric-expressions.js +118 -0
- package/dist/utils/protocol-rehydrate-derivation.d.ts +27 -0
- package/dist/utils/protocol-rehydrate-derivation.d.ts.map +1 -0
- package/dist/utils/protocol-rehydrate-derivation.js +104 -0
- package/dist/utils/protocol-rehydrate-filters.d.ts +10 -0
- package/dist/utils/protocol-rehydrate-filters.d.ts.map +1 -0
- package/dist/utils/protocol-rehydrate-filters.js +36 -0
- package/dist/utils/protocol-semantic-metadata.d.ts +5 -0
- package/dist/utils/protocol-semantic-metadata.d.ts.map +1 -0
- package/dist/utils/protocol-semantic-metadata.js +5 -0
- package/dist/utils/published-name.d.ts +3 -0
- package/dist/utils/published-name.d.ts.map +1 -0
- package/dist/utils/published-name.js +7 -0
- package/dist/utils/published-relationships.d.ts +34 -0
- package/dist/utils/published-relationships.d.ts.map +1 -0
- package/dist/utils/published-relationships.js +35 -0
- package/dist/utils/relationship-fields.d.ts +7 -0
- package/dist/utils/relationship-fields.d.ts.map +1 -1
- package/dist/utils/relationship-fields.js +13 -1
- package/dist/utils/result-limits.d.ts +34 -0
- package/dist/utils/result-limits.d.ts.map +1 -0
- package/dist/utils/result-limits.js +40 -0
- package/dist/utils/semantic-metadata-validation.d.ts +4 -0
- package/dist/utils/semantic-metadata-validation.d.ts.map +1 -0
- package/dist/utils/semantic-metadata-validation.js +103 -0
- package/dist/utils/semantic-metadata.d.ts +4 -0
- package/dist/utils/semantic-metadata.d.ts.map +1 -0
- package/dist/utils/semantic-metadata.js +13 -0
- package/dist/utils/semantic-tool.d.ts +5 -0
- package/dist/utils/semantic-tool.d.ts.map +1 -0
- package/dist/utils/semantic-tool.js +29 -0
- package/package.json +5 -4
package/dist/executor.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"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"}
|
package/dist/executor.js
CHANGED
|
@@ -1,9 +1,4 @@
|
|
|
1
|
-
|
|
2
|
-
* Semantic dataset client internals.
|
|
3
|
-
*
|
|
4
|
-
* Public callers use `createDatasetClient(...).execute(...)`. The implementation
|
|
5
|
-
* stays database-agnostic via query-builder and backend protocol interfaces.
|
|
6
|
-
*/
|
|
1
|
+
import { protocolMetricCapabilityErrors } from './utils/protocol-metric-capabilities.js';
|
|
7
2
|
import { toQueryBuilderFactory } from './query-builder-protocol.js';
|
|
8
3
|
import { quoteSQLIdentifier, validateSQLIdentifier } from './sql-utils.js';
|
|
9
4
|
import { SUPPORTED_TIME_GRAINS, isSupportedTimeGrain } from './constants.js';
|
|
@@ -18,11 +13,13 @@ import { applyPagination, overfetchLimit } from './utils/pagination.js';
|
|
|
18
13
|
import { serializeSemanticMeasureValues } from './utils/semantic-result-serialization.js';
|
|
19
14
|
import { SemanticQueryCache, } from './cache/semantic-query-cache.js';
|
|
20
15
|
import { buildDatasetQuerySignature, buildMetricQuerySignature, } from './cache/query-signature.js';
|
|
16
|
+
import { resolveResultLimit, withResultLimit } from './utils/result-limits.js';
|
|
17
|
+
import { resolveDatasetCacheRuntime, } from './utils/dataset-cache-policy.js';
|
|
21
18
|
import { isQualifiedField, resolveQualifiedField } from './utils/relationship-fields.js';
|
|
22
19
|
import { validateQualifiedFilter, validateRelationshipTenantRuntime, } from './utils/relationship-validation.js';
|
|
23
20
|
import { applyRelationshipJoins, buildRelationshipBuilderContext, qualifyBaseColumn, } from './utils/relationship-builder-plan.js';
|
|
24
21
|
function validateQuery(metric, query, context) {
|
|
25
|
-
const errors =
|
|
22
|
+
const errors = protocolMetricCapabilityErrors(metric, query);
|
|
26
23
|
const ref = getMetricRef(metric);
|
|
27
24
|
const ds = ref.dataset;
|
|
28
25
|
const dimensionNames = Object.keys(ds.dimensions);
|
|
@@ -213,7 +210,9 @@ export class MetricQueryEngine {
|
|
|
213
210
|
if (spec.__type === 'derived_metric_spec') {
|
|
214
211
|
// Derived metrics: build CTE via builder, outer query via string, execute via rawQuery
|
|
215
212
|
const { sql, params } = this.buildDerivedSQLViaBuilder(ref, spec, buildQuery, grain, context);
|
|
216
|
-
const rows = await activeBuilderFactory.rawQuery(sql, params
|
|
213
|
+
const rows = await activeBuilderFactory.rawQuery(sql, params, {
|
|
214
|
+
abortSignal: context?.abortSignal,
|
|
215
|
+
});
|
|
217
216
|
const timingMs = Date.now() - start;
|
|
218
217
|
const { data, pagination } = applyPagination(rows, query.limit, query.offset);
|
|
219
218
|
const serializedData = serializeSemanticMeasureValues(data, [ref.name]);
|
|
@@ -231,7 +230,7 @@ export class MetricQueryEngine {
|
|
|
231
230
|
// Base metrics: fully use the builder's execute()
|
|
232
231
|
const builder = this.buildBaseQuery(ref, spec, ref.dataset, buildQuery, grain, context);
|
|
233
232
|
const { sql } = builder.toSQLWithParams();
|
|
234
|
-
const rows = await builder.execute();
|
|
233
|
+
const rows = await builder.execute({ abortSignal: context?.abortSignal });
|
|
235
234
|
const timingMs = Date.now() - start;
|
|
236
235
|
const { data, pagination } = applyPagination(rows, query.limit, query.offset);
|
|
237
236
|
const serializedData = serializeSemanticMeasureValues(data, [ref.name]);
|
|
@@ -372,6 +371,7 @@ export class DatasetClientImpl extends MetricQueryEngine {
|
|
|
372
371
|
backend;
|
|
373
372
|
queryCache;
|
|
374
373
|
cacheEnabledByDefault;
|
|
374
|
+
cacheDefaults;
|
|
375
375
|
defaultCacheScope;
|
|
376
376
|
constructor(options) {
|
|
377
377
|
if (!options.queryBuilder && !options.backend) {
|
|
@@ -391,6 +391,12 @@ export class DatasetClientImpl extends MetricQueryEngine {
|
|
|
391
391
|
this.queryCache = new SemanticQueryCache(options.cache);
|
|
392
392
|
this.cacheEnabledByDefault = (options.cache?.ttlMs ?? 0) > 0;
|
|
393
393
|
this.defaultCacheScope = options.cache?.scope;
|
|
394
|
+
// Kept so a dataset's declared ceiling can clamp the client default too; the
|
|
395
|
+
// cache would otherwise fill a missing TTL from it after clamping has run.
|
|
396
|
+
this.cacheDefaults = {
|
|
397
|
+
ttlMs: options.cache?.ttlMs,
|
|
398
|
+
staleWhileRevalidateMs: options.cache?.staleWhileRevalidateMs,
|
|
399
|
+
};
|
|
394
400
|
}
|
|
395
401
|
getCacheStats() {
|
|
396
402
|
return this.queryCache.getStats();
|
|
@@ -404,7 +410,7 @@ export class DatasetClientImpl extends MetricQueryEngine {
|
|
|
404
410
|
* the common uncached path.
|
|
405
411
|
*/
|
|
406
412
|
isCacheable(context) {
|
|
407
|
-
if (context?.cache === false || context?.cache?.mode === 'bypass') {
|
|
413
|
+
if (context?.abortSignal || context?.cache === false || context?.cache?.mode === 'bypass') {
|
|
408
414
|
return false;
|
|
409
415
|
}
|
|
410
416
|
const builderOverride = context?.runtime?.builderFactory;
|
|
@@ -470,53 +476,79 @@ export class DatasetClientImpl extends MetricQueryEngine {
|
|
|
470
476
|
return super.validate(target, query, context);
|
|
471
477
|
}
|
|
472
478
|
executeMetric(metric, query, context) {
|
|
479
|
+
const ds = getMetricRef(metric).dataset;
|
|
480
|
+
// Same ceiling and same cache policy as a dataset query: a metric is a
|
|
481
|
+
// named query over the dataset, not a way around what it declared.
|
|
482
|
+
const resultLimit = resolveResultLimit(query.limit, ds.limits);
|
|
483
|
+
const boundedQuery = resultLimit.limit === query.limit ? query : { ...query, limit: resultLimit.limit };
|
|
484
|
+
const cacheRuntime = this.datasetCacheContext(ds, context);
|
|
473
485
|
const run = () => {
|
|
474
486
|
if (this.backend) {
|
|
475
|
-
const validation = validateQuery(metric,
|
|
487
|
+
const validation = validateQuery(metric, boundedQuery, context);
|
|
476
488
|
if (!validation.valid) {
|
|
477
489
|
throw new Error(`Invalid metric query: ${validation.errors.join('; ')}`);
|
|
478
490
|
}
|
|
479
|
-
return this.backend.execute(this.planMetric(metric,
|
|
491
|
+
return this.backend.execute(this.planMetric(metric, boundedQuery, context), { abortSignal: context?.abortSignal }).then((result) => ({
|
|
480
492
|
...result,
|
|
481
493
|
data: serializeSemanticMeasureValues(result.data, [getMetricRef(metric).name]),
|
|
482
494
|
}));
|
|
483
495
|
}
|
|
484
|
-
return this.run(metric,
|
|
496
|
+
return this.run(metric, boundedQuery, context);
|
|
485
497
|
};
|
|
486
|
-
if (!this.isCacheable(
|
|
487
|
-
return run();
|
|
498
|
+
if (!this.isCacheable(cacheRuntime)) {
|
|
499
|
+
return withResultLimit(run(), resultLimit.meta);
|
|
488
500
|
}
|
|
489
501
|
// Validate semantic rules before cache lookup so invalid queries and
|
|
490
502
|
// missing tenant runtime cannot be served from cache. Avoid this.validate()
|
|
491
503
|
// here because it dry-builds SQL, which is unnecessary on cache hits and
|
|
492
504
|
// invalid for backend-only clients.
|
|
493
|
-
const validation = validateQuery(metric,
|
|
505
|
+
const validation = validateQuery(metric, boundedQuery, context);
|
|
494
506
|
if (!validation.valid) {
|
|
495
507
|
throw new Error(`Invalid metric query: ${validation.errors.join('; ')}`);
|
|
496
508
|
}
|
|
497
|
-
return this.queryCache.through(buildMetricQuerySignature(metric,
|
|
509
|
+
return withResultLimit(this.queryCache.through(buildMetricQuerySignature(metric, boundedQuery, this.signatureContext(cacheRuntime)), run, cacheRuntime?.cache), resultLimit.meta);
|
|
498
510
|
}
|
|
499
511
|
executeDataset(ds, query, context) {
|
|
500
512
|
const validation = this.validate(ds, query, context);
|
|
501
513
|
if (!validation.valid) {
|
|
502
514
|
throw new Error(`Invalid dataset query: ${validation.errors.join('; ')}`);
|
|
503
515
|
}
|
|
516
|
+
// Bound before the signature is built, so an unbounded call and an explicit
|
|
517
|
+
// call at the ceiling produce the same rows and share one cache entry.
|
|
518
|
+
const resultLimit = resolveResultLimit(query.limit, ds.limits);
|
|
519
|
+
const boundedQuery = resultLimit.limit === query.limit ? query : { ...query, limit: resultLimit.limit };
|
|
520
|
+
const cacheRuntime = this.datasetCacheContext(ds, context);
|
|
504
521
|
const run = () => {
|
|
505
522
|
if (this.backend) {
|
|
506
|
-
return this.backend.execute(this.planDataset(ds,
|
|
523
|
+
return this.backend.execute(this.planDataset(ds, boundedQuery, context), { abortSignal: context?.abortSignal }).then((result) => ({
|
|
507
524
|
...result,
|
|
508
|
-
data: serializeSemanticMeasureValues(result.data,
|
|
525
|
+
data: serializeSemanticMeasureValues(result.data,
|
|
526
|
+
// Same measures either way; boundedQuery differs only in `limit`.
|
|
527
|
+
boundedQuery.measures ?? Object.keys(ds.measures)),
|
|
509
528
|
}));
|
|
510
529
|
}
|
|
511
|
-
return runDatasetQuery(ds,
|
|
530
|
+
return runDatasetQuery(ds, boundedQuery, {
|
|
512
531
|
builderFactory: resolveBuilderFactory(context, this.getBuilderFactory()),
|
|
513
532
|
context,
|
|
514
533
|
});
|
|
515
534
|
};
|
|
516
|
-
if (!this.isCacheable(
|
|
517
|
-
return run();
|
|
535
|
+
if (!this.isCacheable(cacheRuntime)) {
|
|
536
|
+
return withResultLimit(run(), resultLimit.meta);
|
|
537
|
+
}
|
|
538
|
+
// Annotated outside the cache: the ceiling is derived from the query, not
|
|
539
|
+
// from the rows, so it must not be stored in or read back from an entry.
|
|
540
|
+
return withResultLimit(this.queryCache.through(buildDatasetQuerySignature(ds, boundedQuery, this.signatureContext(cacheRuntime)), run, cacheRuntime?.cache), resultLimit.meta);
|
|
541
|
+
}
|
|
542
|
+
/**
|
|
543
|
+
* Folds the dataset's declared cache policy into the call's context, so both
|
|
544
|
+
* the cacheability decision and the lookup see the same resolved TTL.
|
|
545
|
+
*/
|
|
546
|
+
datasetCacheContext(ds, context) {
|
|
547
|
+
const cache = resolveDatasetCacheRuntime(ds.cache, context?.cache, this.cacheDefaults);
|
|
548
|
+
if (cache === context?.cache) {
|
|
549
|
+
return context;
|
|
518
550
|
}
|
|
519
|
-
return
|
|
551
|
+
return { ...context, cache };
|
|
520
552
|
}
|
|
521
553
|
toDatasetSQL(ds, query, context) {
|
|
522
554
|
const builder = buildDatasetQueryBuilder(ds, query, {
|
package/dist/field.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../src/field.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAa,MAAM,YAAY,CAAC;
|
|
1
|
+
{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../src/field.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAa,MAAM,YAAY,CAAC;AAoBnF,eAAO,MAAM,SAAS;sBAhBZ,QAAQ,SAAS,gBAAgB,GAAG,SAAS;sBAA7C,QAAQ,SAAS,gBAAgB,GAAG,SAAS;uBAA7C,QAAQ,SAAS,gBAAgB,GAAG,SAAS;yBAA7C,QAAQ,SAAS,gBAAgB,GAAG,SAAS;CAqB7C,CAAC"}
|
package/dist/field.js
CHANGED
|
@@ -15,12 +15,14 @@
|
|
|
15
15
|
* });
|
|
16
16
|
* ```
|
|
17
17
|
*/
|
|
18
|
+
import { snapshotSemanticMetadata } from './utils/semantic-metadata.js';
|
|
18
19
|
function createFieldHelper(fieldType) {
|
|
19
20
|
return (opts) => ({
|
|
20
21
|
__type: 'field_definition',
|
|
21
22
|
fieldType,
|
|
22
23
|
label: opts?.label,
|
|
23
24
|
description: opts?.description,
|
|
25
|
+
...snapshotSemanticMetadata(opts ?? {}),
|
|
24
26
|
column: opts?.column,
|
|
25
27
|
sql: opts?.sql,
|
|
26
28
|
dependencies: opts?.dependencies,
|
package/dist/index.d.ts
CHANGED
|
@@ -6,16 +6,27 @@ export { sum, count, countDistinct, avg, min, max, percentile, median, argMax, a
|
|
|
6
6
|
export { divide, multiply, subtract, add, nullIfZero, coalesce, round, floor, ceil, } from './formulas.js';
|
|
7
7
|
export { eq, neq, gt, gte, lt, lte, inList, notInList, between, like, asc, desc, filter, order, } from './query-helpers.js';
|
|
8
8
|
export { createDatasetRegistry } from './registry.js';
|
|
9
|
+
export { publishDatasets } from './publishing/publisher.js';
|
|
10
|
+
export type { DatasetPublisher } from './publishing/publisher.js';
|
|
11
|
+
export type { PublishableMetric, PublishedMetricHandle, PublishedMetricMap, PublishedMetrics, PublishedDataset, PublishedDatasetRegistry, PublishDatasetOptions, } from './publishing/types.js';
|
|
9
12
|
export { getDatasetCatalog, getDatasetCatalogs, getQueryableRelationshipFields } from './catalog.js';
|
|
10
13
|
export { listQueryableRelationshipFields } from './utils/relationship-fields.js';
|
|
11
14
|
export type { DatasetCatalog, DatasetCatalogMap, DatasetCatalogSource, DimensionCatalogEntry, MeasureCatalogEntry, MetricCatalogEntry, FilterCatalogEntry, RelationshipCatalogEntry, } from './catalog.js';
|
|
15
|
+
export { DEFAULT_AGENT_CATALOG_MAX_BYTES, assertAgentSafeCatalogBudget, projectAgentSafeCatalog, projectTrustedDebugCatalog, } from './agent-catalog.js';
|
|
16
|
+
export type { AgentCatalogDataset, AgentCatalogDatasetRegistry, AgentCatalogProjectionOptions, AgentCatalogDimension, AgentCatalogFilter, AgentCatalogMeasure, AgentCatalogMetric, AgentCatalogRelationship, AgentCatalogSource, AgentSafeCatalog, TrustedDebugCatalog, TrustedDebugCatalogAuthorization, } from './agent-catalog.js';
|
|
12
17
|
export { serializeSemanticContract, contractToStableJson, hashContract, SEMANTIC_CONTRACT_VERSION, } from './contract.js';
|
|
18
|
+
export { rehydrateProtocolDatasets, UnsupportedContractFeatureError, } from './protocol-rehydrate.js';
|
|
19
|
+
export type { RehydratedDataset, RehydrateProtocolDatasetsOptions, } from './protocol-rehydrate.js';
|
|
13
20
|
export { buildProtocolDatasetContract } from './protocol-adapter.js';
|
|
14
21
|
export type { BuildProtocolDatasetContractOptions } from './protocol-adapter.js';
|
|
22
|
+
export { createPortableSemanticExecutor, PortableExecutionBudgetError, PortableExecutionTenantError, PortableExecutionUnsupportedError, } from './portable-executor.js';
|
|
23
|
+
export type { PortableSemanticBudget, PortableSemanticExecutionInput, PortableSemanticExecutorOptions, } from './portable-executor.js';
|
|
15
24
|
export { compilePortableSqlExpression, DEFAULT_SQL_PORTABILITY_LIMITS, } from './sql-portability.js';
|
|
16
25
|
export type { SqlPortabilityIssue, SqlPortabilityIssueCode, SqlPortabilityLimits, SqlPortabilityOptions, SqlPortabilityResult, } from './sql-portability.js';
|
|
17
26
|
export type { SemanticContract, SerializeSemanticContractOptions, ContractDataset, ContractDimension, ContractMeasure, ContractMetric, ContractFilter, ContractRelationship, } from './contract.js';
|
|
18
27
|
export { generateDatasetTools, toOpenAITools, toAISDKTools, toMcpTools, } from './tools.js';
|
|
28
|
+
export { buildDatasetInputSchema, buildMetricInputSchema, buildCanonicalSemanticQuerySchemas, toSemanticJsonSchema, DEFAULT_SEMANTIC_QUERY_SCHEMA_LIMITS, } from './semantic-query-schema.js';
|
|
29
|
+
export type { CanonicalSemanticQuerySchemas, SemanticMetricQueryContract, SemanticQuerySchemaLimits, SemanticQuerySchemaOptions, SemanticQuerySchemaSource, } from './semantic-query-schema.js';
|
|
19
30
|
export type { AISDKToolDefinition, DatasetToolAnalytics, DatasetToolMode, GenerateDatasetToolsOptions, JsonSchema, McpToolDefinition, OpenAIToolDefinition, SemanticToolDefinition, } from './tools.js';
|
|
20
31
|
export { createDatasetClient } from './executor.js';
|
|
21
32
|
export type { DatasetClient, CreateDatasetClientOptions } from './executor.js';
|
|
@@ -31,5 +42,5 @@ export type { QueryBuilderLike, QueryBuilderFactoryLike, QueryBuilderFactoryComp
|
|
|
31
42
|
export { toQueryBuilderFactory } from './query-builder-protocol.js';
|
|
32
43
|
export { validateSQLIdentifier, isSafeSQLIdentifier, quoteSQLIdentifier } from './sql-utils.js';
|
|
33
44
|
export { GRAIN_FUNCTIONS, SEMANTIC_FILTER_OPERATORS, SUPPORTED_TIME_GRAINS } from './constants.js';
|
|
34
|
-
export type { FieldType, DimensionType, DimensionOptions, DimensionDefinition, MeasureOptions, MeasureDefinition, InferDimensionType, RelationshipKind, RelationshipDefinition, AggregationType, MeasureAggregation, AggregationSpec, FormulaExpr, DerivedMetricSpec, TimeGrain, MetricRef, BaseMetricRef, DerivedMetricRef, GrainedMetricRef, MetricContract, MetricFilter, MetricOrderBy, MetricQuery, DatasetQuery, MetricResultMeta, MetricResult, DatasetQueryResult, MetricHandle, ExecutionContext, SemanticExecutionRuntime, SemanticTenantRuntime, SemanticFilterDefinition, SemanticFiltersDefinition, DatasetConfig, DatasetLimits, DatasetInstance, AnyDatasetInstance, BaseMetricConfig, DerivedMetricConfig, DatasetRegistryInstance, DatasetFieldNames, DatasetDimensionNames, DatasetQueryableDimensions, DatasetMeasureNames, DatasetOrderableNames, DatasetQueryFor, DatasetRow, DatasetRowFor, DatasetQueryResultFor, MetricQueryFor, MetricRow, MetricRowFor, MetricResultFor, KnownStringKeys, } from './types.js';
|
|
45
|
+
export type { FieldType, DimensionType, DimensionOptions, DimensionDefinition, MeasureOptions, MeasureDefinition, InferDimensionType, RelationshipKind, RelationshipDefinition, AggregationType, MeasureAggregation, AggregationSpec, FormulaExpr, DerivedMetricSpec, TimeGrain, MetricRef, BaseMetricRef, DerivedMetricRef, GrainedMetricRef, MetricContract, MetricFilter, MetricOrderBy, MetricQuery, DatasetQuery, MetricResultMeta, MetricResult, DatasetQueryResult, MetricHandle, ExecutionContext, SemanticExecutionRuntime, SemanticTenantRuntime, SemanticFilterDefinition, SemanticFiltersDefinition, DatasetConfig, DatasetDefaults, DatasetFreshness, DatasetLimits, DatasetCachePolicy, SemanticMetadata, SemanticSensitivity, DatasetInstance, AnyDatasetInstance, BaseMetricConfig, DerivedMetricConfig, DatasetRegistryInstance, DatasetFieldNames, DatasetDimensionNames, DatasetQueryableDimensions, DatasetMeasureNames, DatasetOrderableNames, DatasetQueryFor, DatasetRow, DatasetRowFor, DatasetQueryResultFor, MetricQueryFor, MetricRow, MetricRowFor, MetricResultFor, KnownStringKeys, } from './types.js';
|
|
35
46
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGhE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAGnI,OAAO,EACL,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAC/B,UAAU,EAAE,QAAQ,EACpB,KAAK,EAAE,KAAK,EAAE,IAAI,GACnB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EACzB,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAChC,GAAG,EAAE,IAAI,EACT,MAAM,EAAE,KAAK,GACd,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAGtD,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,8BAA8B,EAAE,MAAM,cAAc,CAAC;AACrG,OAAO,EAAE,+BAA+B,EAAE,MAAM,gCAAgC,CAAC;AACjF,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,YAAY,EACZ,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AACrE,YAAY,EAAE,mCAAmC,EAAE,MAAM,uBAAuB,CAAC;AAGjF,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,GAC/B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,gBAAgB,EAChB,gCAAgC,EAChC,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,YAAY,EACZ,UAAU,GACX,MAAM,YAAY,CAAC;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
package/dist/index.js
CHANGED
|
@@ -14,17 +14,26 @@ export { divide, multiply, subtract, add, nullIfZero, coalesce, round, floor, ce
|
|
|
14
14
|
export { eq, neq, gt, gte, lt, lte, inList, notInList, between, like, asc, desc, filter, order, } from './query-helpers.js';
|
|
15
15
|
// Registry
|
|
16
16
|
export { createDatasetRegistry } from './registry.js';
|
|
17
|
+
// First-class publication builder for Serve, MCP, and agent consumers.
|
|
18
|
+
export { publishDatasets } from './publishing/publisher.js';
|
|
17
19
|
// Catalog
|
|
18
20
|
export { getDatasetCatalog, getDatasetCatalogs, getQueryableRelationshipFields } from './catalog.js';
|
|
19
21
|
export { listQueryableRelationshipFields } from './utils/relationship-fields.js';
|
|
22
|
+
// Agent-safe and separately authorized trusted-debug catalog projections.
|
|
23
|
+
export { DEFAULT_AGENT_CATALOG_MAX_BYTES, assertAgentSafeCatalogBudget, projectAgentSafeCatalog, projectTrustedDebugCatalog, } from './agent-catalog.js';
|
|
20
24
|
// Semantic contract (stable, hashable export for snapshots/diffs/validation)
|
|
21
25
|
export { serializeSemanticContract, contractToStableJson, hashContract, SEMANTIC_CONTRACT_VERSION, } from './contract.js';
|
|
22
26
|
// Portable deployment contract adapter
|
|
27
|
+
export { rehydrateProtocolDatasets, UnsupportedContractFeatureError, } from './protocol-rehydrate.js';
|
|
23
28
|
export { buildProtocolDatasetContract } from './protocol-adapter.js';
|
|
29
|
+
// Portable native execution of a semantic invocation (decision 0005).
|
|
30
|
+
export { createPortableSemanticExecutor, PortableExecutionBudgetError, PortableExecutionTenantError, PortableExecutionUnsupportedError, } from './portable-executor.js';
|
|
24
31
|
// SQL portability compiler (R1A-07)
|
|
25
32
|
export { compilePortableSqlExpression, DEFAULT_SQL_PORTABILITY_LIMITS, } from './sql-portability.js';
|
|
26
33
|
// Agent/tool metadata
|
|
27
34
|
export { generateDatasetTools, toOpenAITools, toAISDKTools, toMcpTools, } from './tools.js';
|
|
35
|
+
// Canonical semantic query schemas shared by Serve, MCP, and agent adapters.
|
|
36
|
+
export { buildDatasetInputSchema, buildMetricInputSchema, buildCanonicalSemanticQuerySchemas, toSemanticJsonSchema, DEFAULT_SEMANTIC_QUERY_SCHEMA_LIMITS, } from './semantic-query-schema.js';
|
|
28
37
|
// Dataset client
|
|
29
38
|
export { createDatasetClient } from './executor.js';
|
|
30
39
|
// Semantic query result cache
|
package/dist/measure.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"measure.d.ts","sourceRoot":"","sources":["../src/measure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAsB,MAAM,YAAY,CAAC;
|
|
1
|
+
{"version":3,"file":"measure.d.ts","sourceRoot":"","sources":["../src/measure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAsB,MAAM,YAAY,CAAC;AAiBxF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAI3D;AAqBD,iBAAS,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,iBAAiB,CAcvG;AAED,eAAO,MAAM,OAAO;0BAtDH,MAAM,SAAS,cAAc,KAAG,iBAAiB;4BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;oCAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;0BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;0BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;0BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;IA6DhE,gFAAgF;;IAEhF,mDAAmD;6BACnC,MAAM,SAAS,cAAc,KAAG,iBAAiB;IAEjE;;;;;OAKG;6BAnDY,MAAM,MAAM,MAAM,SAAS,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,KAAG,iBAAiB;IAqD7F,gFAAgF;6BArDjE,MAAM,MAAM,MAAM,SAAS,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,KAAG,iBAAiB;IAuD7F,2DAA2D;6BA3E5C,MAAM,SAAS,cAAc,KAAG,iBAAiB;IA6EhE,8CAA8C;+BA7E/B,MAAM,SAAS,cAAc,KAAG,iBAAiB;CA+ExD,CAAC"}
|
package/dist/measure.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { snapshotSemanticMetadata } from './utils/semantic-metadata.js';
|
|
1
2
|
function createMeasureHelper(aggregation) {
|
|
2
3
|
return (field, opts) => ({
|
|
3
4
|
__type: 'measure_definition',
|
|
@@ -7,6 +8,7 @@ function createMeasureHelper(aggregation) {
|
|
|
7
8
|
dependencies: opts?.dependencies,
|
|
8
9
|
label: opts?.label,
|
|
9
10
|
description: opts?.description,
|
|
11
|
+
...snapshotSemanticMetadata(opts ?? {}),
|
|
10
12
|
filters: opts?.filters,
|
|
11
13
|
});
|
|
12
14
|
}
|
|
@@ -29,6 +31,7 @@ function createArgMeasureHelper(aggregation) {
|
|
|
29
31
|
dependencies: opts?.dependencies,
|
|
30
32
|
label: opts?.label,
|
|
31
33
|
description: opts?.description,
|
|
34
|
+
...snapshotSemanticMetadata(opts ?? {}),
|
|
32
35
|
};
|
|
33
36
|
};
|
|
34
37
|
}
|
|
@@ -43,6 +46,7 @@ function createPercentileMeasure(field, level, opts) {
|
|
|
43
46
|
dependencies: opts?.dependencies,
|
|
44
47
|
label: opts?.label,
|
|
45
48
|
description: opts?.description,
|
|
49
|
+
...snapshotSemanticMetadata(opts ?? {}),
|
|
46
50
|
filters: opts?.filters,
|
|
47
51
|
};
|
|
48
52
|
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* An error that deliberately claims a portable failure category.
|
|
3
|
+
*
|
|
4
|
+
* A data plane forwards the category and message of an error carrying this
|
|
5
|
+
* marker instead of reporting a generic executor failure, so the marker — not
|
|
6
|
+
* the shape of the error — is what grants that. A provider exception cannot
|
|
7
|
+
* acquire one by accident, which is the point: the two packages are siblings
|
|
8
|
+
* and cannot share a class, but a raw driver error must never be able to pass
|
|
9
|
+
* itself off as a deliberate claim and put its own message in front of a
|
|
10
|
+
* caller.
|
|
11
|
+
*
|
|
12
|
+
* Deliberately not exported. The three errors below are, because this package's
|
|
13
|
+
* own executor throws them; this base is only how they share the marker. A
|
|
14
|
+
* supported way for someone else's executor to claim a category belongs beside
|
|
15
|
+
* the data plane that honours it, not beside one implementation of the slot it
|
|
16
|
+
* fills.
|
|
17
|
+
*/
|
|
18
|
+
declare abstract class PortableExecutionError extends Error {
|
|
19
|
+
/** The opt-in a data plane checks before trusting anything below it. */
|
|
20
|
+
readonly hypequerySemanticFailure: true;
|
|
21
|
+
abstract readonly code: string;
|
|
22
|
+
abstract readonly category: string;
|
|
23
|
+
}
|
|
24
|
+
/** Signalled when portable execution cannot faithfully serve a target. */
|
|
25
|
+
export declare class PortableExecutionUnsupportedError extends PortableExecutionError {
|
|
26
|
+
readonly code = "HQ_SEMANTIC_UNSUPPORTED_CAPABILITY";
|
|
27
|
+
readonly category = "unsupported-capability";
|
|
28
|
+
constructor(message: string, options?: {
|
|
29
|
+
cause?: unknown;
|
|
30
|
+
});
|
|
31
|
+
}
|
|
32
|
+
export declare class PortableExecutionBudgetError extends PortableExecutionError {
|
|
33
|
+
readonly code = "HQ_SEMANTIC_BUDGET_EXCEEDED";
|
|
34
|
+
readonly category = "budget-exceeded";
|
|
35
|
+
constructor(message: string);
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Signalled when tenancy cannot be enforced for a call that resolved a tenant.
|
|
39
|
+
*
|
|
40
|
+
* `configuration-invalid` rather than a caller-facing category: nothing the
|
|
41
|
+
* caller sent is wrong, and nothing it can send would make the call succeed.
|
|
42
|
+
*/
|
|
43
|
+
export declare class PortableExecutionTenantError extends PortableExecutionError {
|
|
44
|
+
readonly code = "HQ_SEMANTIC_TENANT_UNENFORCEABLE";
|
|
45
|
+
readonly category = "configuration-invalid";
|
|
46
|
+
constructor(message: string);
|
|
47
|
+
}
|
|
48
|
+
export {};
|
|
49
|
+
//# sourceMappingURL=portable-execution-errors.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"portable-execution-errors.d.ts","sourceRoot":"","sources":["../src/portable-execution-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,uBAAe,sBAAuB,SAAQ,KAAK;IACjD,wEAAwE;IACxE,QAAQ,CAAC,wBAAwB,EAAG,IAAI,CAAU;IAClD,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CACpC;AAED,0EAA0E;AAC1E,qBAAa,iCAAkC,SAAQ,sBAAsB;IAC3E,QAAQ,CAAC,IAAI,wCAAwC;IACrD,QAAQ,CAAC,QAAQ,4BAA4B;gBAEjC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAI/D;AAED,qBAAa,4BAA6B,SAAQ,sBAAsB;IACtE,QAAQ,CAAC,IAAI,iCAAiC;IAC9C,QAAQ,CAAC,QAAQ,qBAAqB;gBAE1B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,4BAA6B,SAAQ,sBAAsB;IACtE,QAAQ,CAAC,IAAI,sCAAsC;IACnD,QAAQ,CAAC,QAAQ,2BAA2B;gBAEhC,OAAO,EAAE,MAAM;CAI5B"}
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* An error that deliberately claims a portable failure category.
|
|
3
|
+
*
|
|
4
|
+
* A data plane forwards the category and message of an error carrying this
|
|
5
|
+
* marker instead of reporting a generic executor failure, so the marker — not
|
|
6
|
+
* the shape of the error — is what grants that. A provider exception cannot
|
|
7
|
+
* acquire one by accident, which is the point: the two packages are siblings
|
|
8
|
+
* and cannot share a class, but a raw driver error must never be able to pass
|
|
9
|
+
* itself off as a deliberate claim and put its own message in front of a
|
|
10
|
+
* caller.
|
|
11
|
+
*
|
|
12
|
+
* Deliberately not exported. The three errors below are, because this package's
|
|
13
|
+
* own executor throws them; this base is only how they share the marker. A
|
|
14
|
+
* supported way for someone else's executor to claim a category belongs beside
|
|
15
|
+
* the data plane that honours it, not beside one implementation of the slot it
|
|
16
|
+
* fills.
|
|
17
|
+
*/
|
|
18
|
+
class PortableExecutionError extends Error {
|
|
19
|
+
/** The opt-in a data plane checks before trusting anything below it. */
|
|
20
|
+
hypequerySemanticFailure = true;
|
|
21
|
+
}
|
|
22
|
+
/** Signalled when portable execution cannot faithfully serve a target. */
|
|
23
|
+
export class PortableExecutionUnsupportedError extends PortableExecutionError {
|
|
24
|
+
code = 'HQ_SEMANTIC_UNSUPPORTED_CAPABILITY';
|
|
25
|
+
category = 'unsupported-capability';
|
|
26
|
+
constructor(message, options = {}) {
|
|
27
|
+
super(message, options);
|
|
28
|
+
this.name = 'PortableExecutionUnsupportedError';
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
export class PortableExecutionBudgetError extends PortableExecutionError {
|
|
32
|
+
code = 'HQ_SEMANTIC_BUDGET_EXCEEDED';
|
|
33
|
+
category = 'budget-exceeded';
|
|
34
|
+
constructor(message) {
|
|
35
|
+
super(message);
|
|
36
|
+
this.name = 'PortableExecutionBudgetError';
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Signalled when tenancy cannot be enforced for a call that resolved a tenant.
|
|
41
|
+
*
|
|
42
|
+
* `configuration-invalid` rather than a caller-facing category: nothing the
|
|
43
|
+
* caller sent is wrong, and nothing it can send would make the call succeed.
|
|
44
|
+
*/
|
|
45
|
+
export class PortableExecutionTenantError extends PortableExecutionError {
|
|
46
|
+
code = 'HQ_SEMANTIC_TENANT_UNENFORCEABLE';
|
|
47
|
+
category = 'configuration-invalid';
|
|
48
|
+
constructor(message) {
|
|
49
|
+
super(message);
|
|
50
|
+
this.name = 'PortableExecutionTenantError';
|
|
51
|
+
}
|
|
52
|
+
}
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
export { PortableExecutionUnsupportedError, PortableExecutionBudgetError, PortableExecutionTenantError } from './portable-execution-errors.js';
|
|
2
|
+
/**
|
|
3
|
+
* Portable native execution of a semantic invocation.
|
|
4
|
+
*
|
|
5
|
+
* Decision 0005 chose this over a supervised runtime binding: resolve the
|
|
6
|
+
* dataset or metric from the validated active contract, rebuild its catalog
|
|
7
|
+
* with `rehydrateProtocolDatasets`, and plan the query with the existing
|
|
8
|
+
* semantic planner. No customer module is loaded and no isolated runtime is
|
|
9
|
+
* required, so customer code only ever runs on the author's machine at deploy
|
|
10
|
+
* time.
|
|
11
|
+
*
|
|
12
|
+
* The input is typed structurally rather than against
|
|
13
|
+
* `@hypequery/deployment`'s execution input, so this package stays a sibling of
|
|
14
|
+
* that one. A caller wires the returned function into the data plane's injected
|
|
15
|
+
* `execute` slot.
|
|
16
|
+
*/
|
|
17
|
+
import type { ProtocolDatasetContract, ProtocolDatasetMetric, ProtocolSemanticInvocationResult, ProtocolSemanticQuery } from '@hypequery/protocol';
|
|
18
|
+
import type { QueryBuilderFactoryInput } from './query-builder-protocol.js';
|
|
19
|
+
/** Ceilings the data plane already reduced to the most restrictive value. */
|
|
20
|
+
export interface PortableSemanticBudget {
|
|
21
|
+
readonly maxRows: number;
|
|
22
|
+
readonly deadlineMs?: number;
|
|
23
|
+
readonly maxResponseBytes?: number;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Structurally compatible with the deployment data plane's execution input.
|
|
27
|
+
* Only the fields portable execution reads are declared, so the two packages
|
|
28
|
+
* stay independent.
|
|
29
|
+
*/
|
|
30
|
+
export interface PortableSemanticExecutionInput {
|
|
31
|
+
readonly deployment: {
|
|
32
|
+
readonly datasets: readonly ProtocolDatasetContract[];
|
|
33
|
+
};
|
|
34
|
+
readonly dataset: ProtocolDatasetContract;
|
|
35
|
+
readonly metric?: ProtocolDatasetMetric;
|
|
36
|
+
readonly operation: ProtocolSemanticQuery;
|
|
37
|
+
/** Resolved by the provider callback; never caller-supplied. */
|
|
38
|
+
readonly tenant: unknown;
|
|
39
|
+
readonly budget: PortableSemanticBudget;
|
|
40
|
+
/** Identifies the immutable generation, and keys the rebuilt catalog. */
|
|
41
|
+
readonly activationRevision: string;
|
|
42
|
+
readonly signal?: AbortSignal;
|
|
43
|
+
}
|
|
44
|
+
export interface PortableSemanticExecutorOptions {
|
|
45
|
+
readonly queryBuilder: QueryBuilderFactoryInput;
|
|
46
|
+
/**
|
|
47
|
+
* Rebuilt catalogs are memoized by activation revision. A release is
|
|
48
|
+
* immutable and content-addressed, so the revision is an exact key with no
|
|
49
|
+
* invalidation problem. Only the most recent generation is kept here;
|
|
50
|
+
* `CLOUD-09` owns the bounded multi-release cache.
|
|
51
|
+
*/
|
|
52
|
+
readonly cacheRebuiltCatalogs?: boolean;
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Build the executor the deployment data plane injects.
|
|
56
|
+
*
|
|
57
|
+
* Returns the portable result record; the data plane validates it before it
|
|
58
|
+
* reaches a caller.
|
|
59
|
+
*/
|
|
60
|
+
export declare function createPortableSemanticExecutor(options: PortableSemanticExecutorOptions): (input: PortableSemanticExecutionInput) => Promise<ProtocolSemanticInvocationResult>;
|
|
61
|
+
//# sourceMappingURL=portable-executor.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"portable-executor.d.ts","sourceRoot":"","sources":["../src/portable-executor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iCAAiC,EAAE,4BAA4B,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAK/I;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,uBAAuB,EACvB,qBAAqB,EACrB,gCAAgC,EAChC,qBAAqB,EACtB,MAAM,qBAAqB,CAAC;AAO7B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAC5E,6EAA6E;AAC7E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;;;;GAIG;AACH,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,CAAA;KAAE,CAAC;IAC/E,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAC;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC;IAC1C,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,yEAAyE;IACzE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,YAAY,EAAE,wBAAwB,CAAC;IAChD;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CACzC;AAID;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,CAAC,KAAK,EAAE,8BAA8B,KAAK,OAAO,CAAC,gCAAgC,CAAC,CAgGtF"}
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
import { PortableExecutionUnsupportedError, PortableExecutionTenantError } from './portable-execution-errors.js';
|
|
2
|
+
export { PortableExecutionUnsupportedError, PortableExecutionBudgetError, PortableExecutionTenantError } from './portable-execution-errors.js';
|
|
3
|
+
import { tenantRuntime, semanticQuery } from './utils/portable-semantic-query.js';
|
|
4
|
+
import { bounded } from './utils/portable-result-budget.js';
|
|
5
|
+
import { withDeadline } from './utils/portable-execution-deadline.js';
|
|
6
|
+
import { createDatasetClient } from './executor.js';
|
|
7
|
+
import { rehydrateProtocolDatasets, UnsupportedContractFeatureError, } from './protocol-rehydrate.js';
|
|
8
|
+
/**
|
|
9
|
+
* Build the executor the deployment data plane injects.
|
|
10
|
+
*
|
|
11
|
+
* Returns the portable result record; the data plane validates it before it
|
|
12
|
+
* reaches a caller.
|
|
13
|
+
*/
|
|
14
|
+
export function createPortableSemanticExecutor(options) {
|
|
15
|
+
const client = createDatasetClient({ queryBuilder: options.queryBuilder });
|
|
16
|
+
let memo;
|
|
17
|
+
function registryFor(input) {
|
|
18
|
+
if (options.cacheRebuiltCatalogs !== false && memo?.revision === input.activationRevision) {
|
|
19
|
+
return memo.registry;
|
|
20
|
+
}
|
|
21
|
+
let registry;
|
|
22
|
+
try {
|
|
23
|
+
// Skip rather than throw: a single derived metric anywhere in the
|
|
24
|
+
// contract must not make every other dataset unexecutable. The requested
|
|
25
|
+
// target is still refused below when it is one of the skipped ones.
|
|
26
|
+
registry = rehydrateProtocolDatasets(input.deployment.datasets, {
|
|
27
|
+
onUnsupportedMetric: 'skip',
|
|
28
|
+
});
|
|
29
|
+
}
|
|
30
|
+
catch (error) {
|
|
31
|
+
if (error instanceof UnsupportedContractFeatureError) {
|
|
32
|
+
// Decision 0005: a surface portable execution cannot reproduce is
|
|
33
|
+
// excluded from it, never approximated.
|
|
34
|
+
throw new PortableExecutionUnsupportedError(error.message, { cause: error });
|
|
35
|
+
}
|
|
36
|
+
throw error;
|
|
37
|
+
}
|
|
38
|
+
memo = { revision: input.activationRevision, registry };
|
|
39
|
+
return registry;
|
|
40
|
+
}
|
|
41
|
+
return async function execute(input) {
|
|
42
|
+
if (input.metric?.kind === 'derived-metric' && input.metric.derivation === undefined) {
|
|
43
|
+
// A derived metric is executable once the contract carries the formula in
|
|
44
|
+
// the shape it was authored in. One written before that field existed
|
|
45
|
+
// still states only what the metric means, not the aliases its SQL is
|
|
46
|
+
// written in terms of, so it stays excluded rather than approximated.
|
|
47
|
+
throw new PortableExecutionUnsupportedError(`Metric "${String(input.metric.name)}" is derived, and this deployment contract does not `
|
|
48
|
+
+ 'carry the authored formula portable execution needs to plan it.');
|
|
49
|
+
}
|
|
50
|
+
const registry = registryFor(input);
|
|
51
|
+
const rebuilt = registry[String(input.dataset.name)];
|
|
52
|
+
if (rebuilt === undefined) {
|
|
53
|
+
throw new PortableExecutionUnsupportedError(`Dataset "${String(input.dataset.name)}" is not part of the activated contract.`);
|
|
54
|
+
}
|
|
55
|
+
const target = input.metric === undefined
|
|
56
|
+
? rebuilt
|
|
57
|
+
: rebuilt.metrics[String(input.metric.name)];
|
|
58
|
+
if (target === undefined) {
|
|
59
|
+
throw new PortableExecutionUnsupportedError(`Metric "${String(input.metric?.name)}" could not be rebuilt from the contract.`);
|
|
60
|
+
}
|
|
61
|
+
const tenant = tenantRuntime(input.tenant);
|
|
62
|
+
// A tenant with nothing to scope by is the one failure that is silent
|
|
63
|
+
// everywhere else: the runtime accepts it, the planner emits no predicate,
|
|
64
|
+
// and the query reads every tenant while each layer believes tenancy was
|
|
65
|
+
// enforced. Contract validation refuses that shape, but this executor is
|
|
66
|
+
// exported on its own and typed structurally, so it must refuse it too
|
|
67
|
+
// rather than trusting the caller to have validated the contract.
|
|
68
|
+
if (tenant !== undefined && rebuilt.tenantKey === undefined) {
|
|
69
|
+
throw new PortableExecutionTenantError(`Dataset "${String(input.dataset.name)}" declares no tenant field, so a resolved tenant `
|
|
70
|
+
+ 'cannot be applied to it.');
|
|
71
|
+
}
|
|
72
|
+
const query = semanticQuery(input.operation, input.budget.maxRows);
|
|
73
|
+
const output = await withDeadline(input.budget, input.signal, async (signal) => (await client.execute(target, query, {
|
|
74
|
+
abortSignal: signal,
|
|
75
|
+
...(tenant === undefined ? {} : { runtime: { tenant } }),
|
|
76
|
+
})));
|
|
77
|
+
const rows = output.data ?? [];
|
|
78
|
+
const pagination = output.meta?.pagination;
|
|
79
|
+
return bounded(Object.freeze({
|
|
80
|
+
kind: 'hypequery-semantic-invocation-result',
|
|
81
|
+
version: 1,
|
|
82
|
+
activationRevision: input.activationRevision,
|
|
83
|
+
data: rows,
|
|
84
|
+
meta: {
|
|
85
|
+
rowCount: rows.length,
|
|
86
|
+
...(pagination === undefined ? {} : { pagination }),
|
|
87
|
+
},
|
|
88
|
+
}), input.budget);
|
|
89
|
+
};
|
|
90
|
+
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"protocol-adapter.d.ts","sourceRoot":"","sources":["../src/protocol-adapter.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"protocol-adapter.d.ts","sourceRoot":"","sources":["../src/protocol-adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,uBAAuB,EAE5B,KAAK,sBAAsB,EAG5B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EACV,kBAAkB,EAElB,YAAY,EAEb,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAC3C,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;CAC7E;AAsFD;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,mCAAwC,GAChD,uBAAuB,CAiHzB"}
|