@hypequery/datasets 0.13.5 → 0.14.0

package/dist/protocol-rehydrate.js

@@ -0,0 +1,218 @@
+/**
+ * Rebuilds executable datasets from a portable deployment contract.
+ *
+ * The inverse of `protocol-adapter.ts`. Decision 0005 chose portable native
+ * execution, which means a runtime resolves a dataset from the validated active
+ * contract and plans the query with the existing semantic planner — no customer
+ * module is loaded. This is the function that makes the contract executable.
+ *
+ * Rehydration deliberately routes through the public `dataset()` factory rather
+ * than assembling an instance by hand, so a rebuilt dataset is constructed by
+ * exactly the same code path as an authored one. That is what makes the
+ * byte-identical SQL claim mitigated by construction rather than by review.
+ */
+import { dataset } from './dataset.js';
+import { snapshotSemanticMetadata } from './utils/semantic-metadata.js';
+import { withContractCapabilities } from './utils/protocol-metric-capabilities.js';
+import { rehydrateMeasureFilter } from './utils/protocol-rehydrate-filters.js';
+/**
+ * Thrown when a contract describes something portable execution cannot rebuild.
+ *
+ * Callers map this onto the `unsupported-capability` invocation failure rather
+ * than executing an approximation, as decision 0005 requires.
+ */
+export class UnsupportedContractFeatureError extends Error {
+    dataset;
+    feature;
+    constructor(datasetName, feature, detail) {
+        super(`Cannot rebuild ${feature} on dataset "${datasetName}": ${detail}`);
+        this.name = 'UnsupportedContractFeatureError';
+        this.dataset = datasetName;
+        this.feature = feature;
+    }
+}
+function rehydrateDimensions(contract) {
+    const dimensions = {};
+    for (const dimension of contract.dimensions) {
+        const name = String(dimension.name);
+        const source = dimension.source;
+        dimensions[name] = {
+            __type: 'field_definition',
+            ...snapshotSemanticMetadata(dimension),
+            fieldType: dimension.type,
+            label: dimension.label,
+            description: dimension.description,
+            // A column source always carries its column, including when it matches
+            // the dimension name — the forward adapter defaults it, so dropping it
+            // here would still round-trip but would lose an authored mapping.
+            column: source.kind === 'column' ? source.column : undefined,
+            sql: source.kind === 'column' ? undefined : source.sql,
+            dependencies: source.kind === 'column' ? undefined : [...source.dependencies],
+            filterable: dimension.filterable,
+            groupable: dimension.groupable,
+        };
+    }
+    return dimensions;
+}
+function rehydrateMeasure(datasetName, measure) {
+    const filters = measure.filters.map((expression, index) => rehydrateMeasureFilter(expression, () => new UnsupportedContractFeatureError(datasetName, `measure "${String(measure.name)}"`, `fixed filter ${index} is not a field/operator/value comparison`)));
+    return {
+        __type: 'measure_definition',
+        ...snapshotSemanticMetadata(measure),
+        aggregation: measure.aggregation,
+        field: String(measure.field),
+        ...(measure.argField !== undefined ? { argField: String(measure.argField) } : {}),
+        ...(measure.level !== undefined ? { level: measure.level } : {}),
+        ...(measure.sql !== undefined
+            ? { sql: measure.sql.sql, dependencies: [...measure.sql.dependencies] }
+            : {}),
+        ...(measure.label !== undefined ? { label: measure.label } : {}),
+        ...(measure.description !== undefined ? { description: measure.description } : {}),
+        ...(filters.length > 0 ? { filters: filters } : {}),
+    };
+}
+function rehydrateFilters(contract) {
+    const filters = {};
+    for (const filter of contract.filters) {
+        filters[String(filter.name)] = {
+            __type: 'filter_definition',
+            ...snapshotSemanticMetadata(filter),
+            field: String(filter.field),
+            operators: [...filter.operators],
+            ...(filter.label !== undefined ? { label: filter.label } : {}),
+            ...(filter.description !== undefined ? { description: filter.description } : {}),
+        };
+    }
+    return filters;
+}
+function rehydrateRelationships(contract, resolve) {
+    const relationships = {};
+    for (const relationship of contract.relationships) {
+        const target = String(relationship.target);
+        relationships[String(relationship.name)] = {
+            __type: 'relationship',
+            kind: relationship.kind,
+            // Resolved on call: datasets in one contract may reference each other, so
+            // the target may not be built yet when this relationship is created.
+            target: () => resolve(target),
+            from: String(relationship.from),
+            to: String(relationship.to),
+        };
+    }
+    return relationships;
+}
+/**
+ * Identity of an aggregation, used to bind a metric back to the measure it was
+ * built from.
+ *
+ * Aggregation and field alone are not enough: two measures may share both and
+ * differ only by their fixed filters — `sum(amount)` and `sum(amount) where
+ * status = 'paid'`. Matching on the looser key binds the metric to whichever
+ * measure happens to sort first and silently changes the SQL it emits.
+ */
+function aggregationKey(value) {
+    return JSON.stringify([
+        value.aggregation,
+        String(value.field),
+        value.argField === undefined ? null : String(value.argField),
+        value.level ?? null,
+        value.filters ?? [],
+    ]);
+}
+function rehydrateMetric(instance, contract, metric) {
+    const name = String(metric.name);
+    if (metric.kind === 'derived-metric') {
+        // The symbolic expression a derived metric needs is not carried by contract
+        // v1; CORE-17 adds it. Until then this fails closed rather than guessing.
+        throw new UnsupportedContractFeatureError(instance.name, `metric "${name}"`, 'a derived metric requires its symbolic expression, which deployment contract v1 does not carry');
+    }
+    const expression = metric.expression;
+    if (expression.kind !== 'aggregate') {
+        throw new UnsupportedContractFeatureError(instance.name, `metric "${name}"`, `expected an aggregate expression, received "${expression.kind}"`);
+    }
+    const field = String(expression.field);
+    const candidates = contract.measures.filter(measure => (aggregationKey(measure) === aggregationKey(expression)));
+    if (candidates.length === 0) {
+        throw new UnsupportedContractFeatureError(instance.name, `metric "${name}"`, `no declared measure matches ${expression.aggregation}(${field})`);
+    }
+    // A metric expression carries no raw SQL, so two measures that share an
+    // aggregation identity but override SQL differently are indistinguishable in
+    // contract v1. Binding to either would be a guess at which SQL to emit.
+    const distinctSql = new Set(candidates.map(measure => measure.sql?.sql ?? null));
+    if (distinctSql.size > 1) {
+        throw new UnsupportedContractFeatureError(instance.name, `metric "${name}"`, `${candidates.map(measure => `"${String(measure.name)}"`).join(' and ')} share `
+            + `${expression.aggregation}(${field}) but emit different SQL, so the contract cannot `
+            + 'say which one this metric was built from');
+    }
+    const measureName = candidates[0].name;
+    const base = instance.metric(name, {
+        measure: measureName,
+        ...snapshotSemanticMetadata(metric),
+        ...(metric.label !== undefined ? { label: metric.label } : {}),
+        ...(metric.description !== undefined ? { description: metric.description } : {}),
+    });
+    const handle = metric.grain === undefined
+        ? base
+        : base.by(metric.grain);
+    return withContractCapabilities(handle, metric);
+}
+/**
+ * Rebuild every dataset in a validated deployment contract.
+ *
+ * Datasets are returned keyed by contract name with their named metrics
+ * attached, which is the registry shape `getDatasetCatalog`,
+ * `projectAgentSafeCatalog`, and `DatasetClient` already accept.
+ */
+export function rehydrateProtocolDatasets(contracts, options = {}) {
+    const instances = new Map();
+    const registry = {};
+    // Relationship targets resolve to the published entry, not the bare instance
+    // built below, so a caller that follows a relationship lands on the same
+    // object the registry exposes. Safe because `target()` is only called after
+    // the registry is complete.
+    const resolve = (target) => {
+        const instance = registry[target] ?? instances.get(target);
+        if (!instance) {
+            // The deployment validator already rejects a dangling relationship, so
+            // reaching this means the caller passed a partial contract.
+            throw new UnsupportedContractFeatureError(target, 'relationship target', `dataset "${target}" is not part of the supplied contract`);
+        }
+        return instance;
+    };
+    for (const contract of contracts) {
+        const name = String(contract.name);
+        const instance = dataset(name, {
+            source: contract.source,
+            ...snapshotSemanticMetadata(contract),
+            ...(contract.description !== undefined ? { description: contract.description } : {}),
+            ...(contract.owner !== undefined ? { owner: contract.owner } : {}),
+            ...(contract.freshness !== undefined ? { freshness: { ...contract.freshness } } : {}),
+            ...(contract.defaults !== undefined ? { defaults: {
+                    ...contract.defaults,
+                    ...(contract.defaults.dimensions !== undefined ? { dimensions: [...contract.defaults.dimensions] } : {}),
+                } } : {}),
+            ...(contract.tenant.kind === 'required' ? { tenantKey: contract.tenant.field } : {}),
+            ...(contract.timeField !== undefined ? { timeKey: String(contract.timeField) } : {}),
+            dimensions: rehydrateDimensions(contract),
+            measures: Object.fromEntries(contract.measures.map(measure => [
+                String(measure.name),
+                rehydrateMeasure(name, measure),
+            ])),
+            filters: rehydrateFilters(contract),
+            relationships: rehydrateRelationships(contract, resolve),
+            ...(contract.limits !== undefined ? { limits: { ...contract.limits } } : {}),
+            ...(options.cache !== undefined ? { cache: options.cache } : {}),
+        });
+        instances.set(name, instance);
+    }
+    for (const contract of contracts) {
+        const name = String(contract.name);
+        const instance = instances.get(name);
+        const metrics = {};
+        for (const metric of contract.metrics) {
+            metrics[String(metric.name)] = rehydrateMetric(instance, contract, metric);
+        }
+        registry[name] = Object.assign(Object.create(Object.getPrototypeOf(instance)), instance, { metrics });
+    }
+    return registry;
+}

package/dist/publishing/features/dataset-publication.d.ts

@@ -0,0 +1,10 @@
+import type { AnyDatasetInstance, MetricHandle } from '../../types.js';
+import type { DatasetPublisherNode } from '../node.js';
+export declare class DatasetPublicationFeature {
+    private readonly publisher;
+    constructor(publisher: {
+        getPublicationNode(): DatasetPublisherNode;
+    });
+    add(dataset: AnyDatasetInstance, alias: string, metrics: Readonly<Record<string, MetricHandle>>): DatasetPublisherNode;
+}
+//# sourceMappingURL=dataset-publication.d.ts.map

package/dist/publishing/features/dataset-publication.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-publication.d.ts","sourceRoot":"","sources":["../../../src/publishing/features/dataset-publication.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,qBAAa,yBAAyB;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE;QACtC,kBAAkB,IAAI,oBAAoB,CAAC;KAC5C;IAED,GAAG,CACD,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,GAC9C,oBAAoB;CA8BxB"}

package/dist/publishing/features/dataset-publication.js

@@ -0,0 +1,34 @@
+import { aliasMetricHandle } from '../../utils/metric-alias.js';
+import { assertPublishedName } from '../../utils/published-name.js';
+export class DatasetPublicationFeature {
+    publisher;
+    constructor(publisher) {
+        this.publisher = publisher;
+    }
+    add(dataset, alias, metrics) {
+        const node = this.publisher.getPublicationNode();
+        assertPublishedName(alias, 'dataset');
+        if (node.entries.some(entry => entry.alias === alias)) {
+            throw new Error(`Dataset alias "${alias}" is already published.`);
+        }
+        if (node.entries.some(entry => entry.dataset.name === dataset.name)) {
+            throw new Error(`Dataset "${dataset.name}" is already published.`);
+        }
+        const publishedMetrics = {};
+        for (const [metricAlias, metric] of Object.entries(metrics)) {
+            assertPublishedName(metricAlias, 'metric');
+            const ref = metric.__type === 'grained_metric_ref' ? metric.metric : metric;
+            if (ref.datasetName !== dataset.name) {
+                throw new Error(`Metric "${metricAlias}" belongs to dataset "${ref.datasetName}", expected "${dataset.name}".`);
+            }
+            publishedMetrics[metricAlias] = aliasMetricHandle(metric, metricAlias, alias);
+        }
+        return {
+            kind: 'dataset-publisher',
+            entries: [
+                ...node.entries,
+                { alias, dataset, metrics: publishedMetrics },
+            ],
+        };
+    }
+}

package/dist/publishing/node.d.ts

@@ -0,0 +1,16 @@
+import type { AnyDatasetInstance, MetricHandle } from '../types.js';
+export interface DatasetPublicationEntry {
+    readonly alias: string;
+    readonly dataset: AnyDatasetInstance;
+    readonly metrics: Readonly<Record<string, MetricHandle>>;
+}
+export interface DatasetPublisherNode {
+    readonly kind: 'dataset-publisher';
+    readonly entries: readonly DatasetPublicationEntry[];
+}
+export declare function createDatasetPublisherNode(entries?: readonly DatasetPublicationEntry[]): DatasetPublisherNode;
+export declare function cloneDatasetPublisherNode(node: DatasetPublisherNode): DatasetPublisherNode;
+export declare function materializeDatasetPublisherNode(node: DatasetPublisherNode): Readonly<Record<string, AnyDatasetInstance & {
+    readonly metrics: Readonly<Record<string, MetricHandle>>;
+}>>;
+//# sourceMappingURL=node.d.ts.map

package/dist/publishing/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/publishing/node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAMpE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,SAAS,uBAAuB,EAAE,CAAC;CACtD;AAED,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,SAAS,uBAAuB,EAAO,GAC/C,oBAAoB,CAStB;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,oBAAoB,GAAG,oBAAoB,CAE1F;AAED,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,oBAAoB,GACzB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,GAAG;IAC9C,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CAC1D,CAAC,CAAC,CAyBF"}

package/dist/publishing/node.js

@@ -0,0 +1,35 @@
+import { publishedAliasesByName, rewirePublishedRelationships, } from '../utils/published-relationships.js';
+export function createDatasetPublisherNode(entries = []) {
+    return {
+        kind: 'dataset-publisher',
+        entries: entries.map(entry => ({
+            alias: entry.alias,
+            dataset: entry.dataset,
+            metrics: { ...entry.metrics },
+        })),
+    };
+}
+export function cloneDatasetPublisherNode(node) {
+    return createDatasetPublisherNode(node.entries);
+}
+export function materializeDatasetPublisherNode(node) {
+    const aliasesByName = publishedAliasesByName(node.entries);
+    const registry = new Map();
+    // Relationships resolve their target through this map rather than capturing
+    // an instance, so datasets that reference each other are rewired without an
+    // ordering constraint.
+    const lookup = (alias) => registry.get(alias);
+    const entries = [...node.entries]
+        .sort((left, right) => left.alias < right.alias ? -1 : left.alias > right.alias ? 1 : 0)
+        .map(entry => {
+        const published = Object.freeze({
+            ...entry.dataset,
+            name: entry.alias,
+            relationships: rewirePublishedRelationships(entry.dataset.relationships, aliasesByName, lookup),
+            metrics: Object.freeze({ ...entry.metrics }),
+        });
+        registry.set(entry.alias, published);
+        return [entry.alias, published];
+    });
+    return Object.freeze(Object.fromEntries(entries));
+}

package/dist/publishing/publisher.d.ts

@@ -0,0 +1,17 @@
+import type { AnyDatasetInstance } from '../types.js';
+import { type DatasetPublisherNode } from './node.js';
+import type { AddPublishedDataset, AnyDatasetPublisherState, DatasetPublisherState, PublishedAlias, PublishedMetricMap, PublishDatasetOptions } from './types.js';
+/** Immutable builder for publishing datasets and named metrics to consumers. */
+export declare class DatasetPublisher<TState extends AnyDatasetPublisherState = DatasetPublisherState> {
+    private readonly state;
+    private readonly node;
+    private readonly publication;
+    constructor(state: TState, node?: DatasetPublisherNode);
+    getPublicationNode(): DatasetPublisherNode;
+    private transition;
+    publish<TDataset extends AnyDatasetInstance, const TAlias extends string | undefined = undefined, const TMetrics extends PublishedMetricMap<TDataset> = Record<string, never>>(dataset: TDataset, options?: PublishDatasetOptions<TDataset, TAlias, TMetrics>): DatasetPublisher<AddPublishedDataset<TState, TDataset, PublishedAlias<TDataset, TAlias>, TMetrics>>;
+    /** Materialize the plain registry shape accepted by existing Serve/MCP APIs. */
+    build(): TState['registry'];
+}
+export declare function publishDatasets(): DatasetPublisher<DatasetPublisherState>;
+//# sourceMappingURL=publisher.d.ts.map

package/dist/publishing/publisher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publisher.d.ts","sourceRoot":"","sources":["../../src/publishing/publisher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EACV,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB,gFAAgF;AAChF,qBAAa,gBAAgB,CAC3B,MAAM,SAAS,wBAAwB,GAAG,qBAAqB;IAK7D,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJvB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA4B;gBAGrC,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,oBAAmD;IAK5E,kBAAkB,IAAI,oBAAoB;IAI1C,OAAO,CAAC,UAAU;IAOlB,OAAO,CACL,QAAQ,SAAS,kBAAkB,EACnC,KAAK,CAAC,MAAM,SAAS,MAAM,GAAG,SAAS,GAAG,SAAS,EACnD,KAAK,CAAC,QAAQ,SAAS,kBAAkB,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAE3E,OAAO,EAAE,QAAQ,EACjB,OAAO,GAAE,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAM,GAC9D,gBAAgB,CAAC,mBAAmB,CACrC,MAAM,EACN,QAAQ,EACR,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,EAChC,QAAQ,CACT,CAAC;IAaF,gFAAgF;IAChF,KAAK,IAAI,MAAM,CAAC,UAAU,CAAC;CAG5B;AAED,wBAAgB,eAAe,IAAI,gBAAgB,CAAC,qBAAqB,CAAC,CAEzE"}

package/dist/publishing/publisher.js

@@ -0,0 +1,32 @@
+import { DatasetPublicationFeature } from './features/dataset-publication.js';
+import { cloneDatasetPublisherNode, createDatasetPublisherNode, materializeDatasetPublisherNode, } from './node.js';
+/** Immutable builder for publishing datasets and named metrics to consumers. */
+export class DatasetPublisher {
+    state;
+    node;
+    publication;
+    constructor(state, node = createDatasetPublisherNode()) {
+        this.state = state;
+        this.node = node;
+        this.publication = new DatasetPublicationFeature(this);
+    }
+    getPublicationNode() {
+        return cloneDatasetPublisherNode(this.node);
+    }
+    transition(state, node) {
+        return new DatasetPublisher(state, node);
+    }
+    publish(dataset, options = {}) {
+        const alias = options.alias ?? dataset.name;
+        const node = this.publication.add(dataset, alias, options.metrics ?? {});
+        const state = { registry: materializeDatasetPublisherNode(node) };
+        return this.transition(state, node);
+    }
+    /** Materialize the plain registry shape accepted by existing Serve/MCP APIs. */
+    build() {
+        return this.state.registry;
+    }
+}
+export function publishDatasets() {
+    return new DatasetPublisher({ registry: {} });
+}

package/dist/publishing/types.d.ts

@@ -0,0 +1,31 @@
+import type { AggregationSpec, AnyDatasetInstance, DerivedMetricSpec, GrainedMetricRef, MetricHandle, MetricRef, TimeGrain } from '../types.js';
+export type PublishableMetric<TDataset extends AnyDatasetInstance> = MetricHandle<TDataset['name'], string, AggregationSpec | DerivedMetricSpec<TDataset['name']>, TDataset>;
+export type PublishedMetricMap<TDataset extends AnyDatasetInstance> = Readonly<Record<string, PublishableMetric<TDataset>>>;
+export type PublishedMetricHandle<TMetric extends MetricHandle, TAlias extends string, TDatasetAlias extends string> = TMetric extends MetricRef ? Omit<TMetric, 'datasetName' | 'name' | 'by'> & {
+    readonly datasetName: TDatasetAlias;
+    readonly name: TAlias;
+    by(grain: TimeGrain): PublishedMetricHandle<ReturnType<TMetric['by']>, TAlias, TDatasetAlias>;
+} : TMetric extends GrainedMetricRef ? Omit<TMetric, 'metric'> & {
+    readonly metric: PublishedMetricHandle<TMetric['metric'], TAlias, TDatasetAlias>;
+} : never;
+export type PublishedMetrics<TMetrics extends Readonly<Record<string, MetricHandle>>, TDatasetAlias extends string> = {
+    readonly [TAlias in keyof TMetrics]: TAlias extends string ? PublishedMetricHandle<TMetrics[TAlias], TAlias, TDatasetAlias> : never;
+};
+export type PublishedDataset<TDataset extends AnyDatasetInstance = AnyDatasetInstance, TAlias extends string = TDataset['name'], TMetrics extends PublishedMetricMap<TDataset> = PublishedMetricMap<TDataset>> = Omit<TDataset, 'name'> & {
+    readonly name: TAlias;
+    readonly metrics: PublishedMetrics<TMetrics, TAlias>;
+};
+export type PublishedDatasetRegistry = Readonly<Record<string, PublishedDataset<AnyDatasetInstance, string>>>;
+export interface PublishDatasetOptions<TDataset extends AnyDatasetInstance, TAlias extends string | undefined = undefined, TMetrics extends PublishedMetricMap<TDataset> = Record<string, never>> {
+    /** Public registry name. Defaults to `dataset.name`. */
+    readonly alias?: TAlias;
+    /** Public metric names mapped to handles owned by this dataset. */
+    readonly metrics?: TMetrics;
+}
+export interface DatasetPublisherState<TRegistry extends PublishedDatasetRegistry = {}> {
+    readonly registry: TRegistry;
+}
+export type AnyDatasetPublisherState = DatasetPublisherState<PublishedDatasetRegistry>;
+export type PublishedAlias<TDataset extends AnyDatasetInstance, TAlias extends string | undefined> = TAlias extends string ? TAlias : TDataset['name'];
+export type AddPublishedDataset<TState extends AnyDatasetPublisherState, TDataset extends AnyDatasetInstance, TAlias extends string, TMetrics extends PublishedMetricMap<TDataset>> = DatasetPublisherState<TState['registry'] & Record<TAlias, PublishedDataset<TDataset, TAlias, TMetrics>>>;
+//# sourceMappingURL=types.d.ts.map

package/dist/publishing/types.d.ts.map

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

package/dist/publishing/types.js

@@ -0,0 +1 @@
+export {};

package/dist/query-builder-protocol.d.ts

@@ -43,7 +43,9 @@ export interface QueryBuilderLike {
         sql: string;
         parameters: unknown[];
     };
-    execute<T = Record<string, unknown>>(): Promise<T[]>;
+    execute<T = Record<string, unknown>>(options?: {
+        abortSignal?: AbortSignal;
+    }): Promise<T[]>;
 }
 export interface QueryBuilderJoinCondition {
     column: string;
@@ -53,7 +55,9 @@ export interface QueryBuilderJoinCondition {
 /** A query builder factory (what `createQueryBuilder(config)` returns). */
 export interface QueryBuilderFactoryLike {
     table(name: string): QueryBuilderLike;
-    rawQuery<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    rawQuery<T = Record<string, unknown>>(sql: string, params?: unknown[], options?: {
+        abortSignal?: AbortSignal;
+    }): Promise<T[]>;
 }
 /**
  * Acceptance shape for query builder factories at public entry points.

package/dist/query-builder-protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-builder-protocol.d.ts","sourceRoot":"","sources":["../src/query-builder-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,gBAAgB,CAAC;IAGrD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtD,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACxD,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAChE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAGtD,kEAAkE;IAClE,MAAM,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAC7E,kEAAkE;IAClE,MAAM,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAC7E,+DAA+D;IAC/D,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAC3E,6CAA6C;IAC7C,MAAM,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAC1D,mCAAmC;IACnC,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAG5D,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC;IAG1E,QAAQ,CACN,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,KAAK,CAAC,EAAE,MAAM,EACd,EAAE,CAAC,EAAE,yBAAyB,GAAG,yBAAyB,EAAE,GAC3D,gBAAgB,CAAC;IAEpB;;;;OAIG;IACH,WAAW,CAAC,CACV,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,KAAK,CAAC,EAAE,MAAM,EACd,EAAE,CAAC,EAAE,yBAAyB,GAAG,yBAAyB,EAAE,GAC3D,gBAAgB,CAAC;IAGpB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,gBAAgB,CAAC;IAGtD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,gBAAgB,CAAC;IACtE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACvC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAGxC,eAAe,IAAI;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;IAC1D,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,2EAA2E;AAC3E,MAAM,WAAW,uBAAuB;IACtC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtC,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CACtF;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,6BAA6B;IAC5C,KAAK,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzD;AAED,iEAAiE;AACjE,MAAM,MAAM,wBAAwB,GAChC,uBAAuB,GACvB,6BAA6B,CAAC;AAElC;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,wBAAwB,GAChC,uBAAuB,CAEzB"}
+{"version":3,"file":"query-builder-protocol.d.ts","sourceRoot":"","sources":["../src/query-builder-protocol.ts"],"names":[],"mappings":"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"}

package/dist/semantic-plan.d.ts

@@ -119,7 +119,9 @@ export interface SemanticBackendResult<T = Record<string, unknown>> {
  * implementing a backend.
  */
 export interface SemanticBackend {
-    execute<T = Record<string, unknown>>(plan: PlanNode): Promise<SemanticBackendResult<T>>;
+    execute<T = Record<string, unknown>>(plan: PlanNode, options?: {
+        abortSignal?: AbortSignal;
+    }): Promise<SemanticBackendResult<T>>;
     explain?(plan: PlanNode): Promise<{
         sql?: string;
     }>;

package/dist/semantic-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-plan.d.ts","sourceRoot":"","sources":["../src/semantic-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,SAAS,EACT,YAAY,EACZ,aAAa,EACb,SAAS,EACV,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;AAChF,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AAE1F,iHAAiH;AACjH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAA;CAAE,GAC5D;IACA,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,sBAAsB,CAAC;IACjC,IAAI,EAAE,kBAAkB,CAAC;IACzB,KAAK,EAAE,kBAAkB,CAAC;CAC3B,GACC;IACA,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,oBAAoB,CAAC;IAC3B,IAAI,EAAE,kBAAkB,EAAE,CAAC;CAC5B,CAAC;AAEJ,iHAAiH;AACjH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,iHAAiH;AACjH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,eAAe,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED,MAAM,MAAM,uBAAuB,GAC/B;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,uBAAuB,CAAC;CAClC;AAED,iHAAiH;AACjH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CACvC;AAED,iHAAiH;AACjH,MAAM,MAAM,QAAQ,GAChB;IACA,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,qBAAqB,EAAE,CAAC;IACpC,YAAY,EAAE,uBAAuB,EAAE,CAAC;IACxC,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC5B,GACC;IACA,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,kBAAkB,CAAA;KAAE,CAAC,CAAC;IACjE,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEJ,iHAAiH;AACjH,MAAM,WAAW,qBAAqB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAChE,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,IAAI,CAAC,EAAE;QACL,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC;IACxF,OAAO,CAAC,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD"}
+{"version":3,"file":"semantic-plan.d.ts","sourceRoot":"","sources":["../src/semantic-plan.ts"],"names":[],"mappings":"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"}

package/dist/semantic-planner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-planner.d.ts","sourceRoot":"","sources":["../src/semantic-planner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAGhB,WAAW,EACX,SAAS,EACT,gBAAgB,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACV,QAAQ,EAIT,MAAM,oBAAoB,CAAC;AAyL5B,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,kBAAkB,EACtB,KAAK,GAAE,YAAiB,EACxB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAaV;AA2FD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,GAAE,WAAgB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAUV"}
+{"version":3,"file":"semantic-planner.d.ts","sourceRoot":"","sources":["../src/semantic-planner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAGhB,WAAW,EACX,SAAS,EACT,gBAAgB,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACV,QAAQ,EAIT,MAAM,oBAAoB,CAAC;AAyL5B,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,kBAAkB,EACtB,KAAK,GAAE,YAAiB,EACxB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAaV;AA2FD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,GAAE,WAAgB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAYV"}

package/dist/semantic-planner.js

@@ -1,3 +1,4 @@
+import { protocolMetricCapabilityErrors } from './utils/protocol-metric-capabilities.js';
 import { getMetricGrain, getMetricRef, } from './utils/metric-handle.js';
 import { validateDatasetQuery } from './dataset-query.js';
 import { isSupportedTimeGrain } from './constants.js';
@@ -213,6 +214,9 @@ function buildDerivedMetricPlan(metric, query, context) {
     };
 }
 export function buildMetricPlan(metric, query = {}, context) {
+    const errors = protocolMetricCapabilityErrors(metric, query);
+    if (errors.length)
+        throw new Error(`Invalid metric query: ${errors.join('; ')}`);
     const ref = getMetricRef(metric);
     const grain = getMetricGrain(metric, query);
     const plannedQuery = { ...query, by: grain };

package/dist/semantic-query-schema.d.ts

@@ -0,0 +1,48 @@
+import { type ZodTypeAny } from 'zod';
+import { type DatasetCatalog, type DatasetCatalogSource, type MetricCatalogEntry } from './catalog.js';
+import type { JsonSchema } from './tools.js';
+export interface SemanticQuerySchemaLimits {
+    defaultResultSize?: number;
+    maxResultSize?: number;
+    maxOffset?: number;
+    maxDimensions?: number;
+    maxMeasures?: number;
+    maxFilters?: number;
+    maxOrderBy?: number;
+}
+export interface SemanticQuerySchemaOptions extends SemanticQuerySchemaLimits {
+    /** Input field used for time grain. Serve uses `by`; agent tools use `grain`. */
+    grainField?: 'by' | 'grain';
+    /** Include Serve's opt-in result metadata flag. */
+    includeMeta?: boolean;
+    /** Require at least one dimension or measure for dataset queries. */
+    requireSelection?: boolean;
+    /** Validate result limits in the schema. Disable when a consumer clamps them. */
+    enforceResultLimit?: boolean;
+}
+/** Metric-specific query capabilities used when they are not embedded in the Dataset source. */
+export type SemanticMetricQueryContract = Pick<MetricCatalogEntry, 'dimensions' | 'filters' | 'grains' | 'grain'>;
+export declare const DEFAULT_SEMANTIC_QUERY_SCHEMA_LIMITS: Readonly<{
+    maxResultSize: 10000;
+    maxOffset: 10000;
+    maxDimensions: 50;
+    maxMeasures: 50;
+    maxFilters: 100;
+    maxOrderBy: 50;
+}>;
+export interface CanonicalSemanticQuerySchemas {
+    readonly queryDataset: ZodTypeAny;
+    readonly queryMetric: ZodTypeAny;
+    readonly queryDatasetJsonSchema: JsonSchema;
+    readonly queryMetricJsonSchema: JsonSchema;
+    readonly manifestHash: string;
+}
+/** A live local Dataset or an already-normalized catalog from a hosted contract. */
+export type SemanticQuerySchemaSource = DatasetCatalogSource | DatasetCatalog;
+export declare function buildDatasetInputSchema(dataset: SemanticQuerySchemaSource, options?: SemanticQuerySchemaOptions): ZodTypeAny;
+export declare function buildMetricInputSchema(dataset: SemanticQuerySchemaSource, metricName: string, options?: SemanticQuerySchemaOptions, metricContract?: SemanticMetricQueryContract): ZodTypeAny;
+export declare function toSemanticJsonSchema(schema: ZodTypeAny, options?: {
+    requireSelection?: boolean;
+}): JsonSchema;
+export declare function buildCanonicalSemanticQuerySchemas(datasets: Record<string, SemanticQuerySchemaSource>, options?: SemanticQuerySchemaOptions): CanonicalSemanticQuerySchemas;
+//# sourceMappingURL=semantic-query-schema.d.ts.map

package/dist/semantic-query-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-query-schema.d.ts","sourceRoot":"","sources":["../src/semantic-query-schema.ts"],"names":[],"mappings":"AAEA,OAAO,EAAK,KAAK,UAAU,EAAE,MAAM,KAAK,CAAC;AAEzC,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACxB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,MAAM,WAAW,yBAAyB;IACxC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,0BAA2B,SAAQ,yBAAyB;IAC3E,iFAAiF;IACjF,UAAU,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC;IAC5B,mDAAmD;IACnD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,gGAAgG;AAChG,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAC5C,kBAAkB,EAClB,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAC9C,CAAC;AAEF,eAAO,MAAM,oCAAoC;;;;;;;EAO/C,CAAC;AAEH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,sBAAsB,EAAE,UAAU,CAAC;IAC5C,QAAQ,CAAC,qBAAqB,EAAE,UAAU,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,oFAAoF;AACpF,MAAM,MAAM,yBAAyB,GAAG,oBAAoB,GAAG,cAAc,CAAC;AA6I9E,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,yBAAyB,EAClC,OAAO,GAAE,0BAA+B,GACvC,UAAU,CAOZ;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,yBAAyB,EAClC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,0BAA+B,EACxC,cAAc,CAAC,EAAE,2BAA2B,GAC3C,UAAU,CAaZ;AAsBD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3C,UAAU,CAMZ;AAyBD,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,EACnD,OAAO,GAAE,0BAA+B,GACvC,6BAA6B,CA0C/B"}