@hypequery/datasets 0.23.1 → 0.25.0

package/dist/measure.js

@@ -1,4 +1,4 @@
-import { createMeasureHelper, createArgMeasureHelper, createPercentileMeasure, createMedianMeasure, createDerivedMeasure } from './utils/base-measure-definition.js';
+import { createMeasureHelper, createArgMeasureHelper, createPercentileMeasure, createMedianMeasure, createDerivedMeasure, createMergeMeasure } from './utils/base-measure-definition.js';
 export { validatePercentileLevel } from './utils/base-measure-definition.js';
 import { createShiftMeasure } from './utils/shift-measure-definition.js';
 import { createWindowMeasure } from './utils/window-measure-definition.js';
@@ -27,6 +27,14 @@ export const measure = {
     argMax: createArgMeasureHelper('argMax'),
     /** Value of `field` on the row where `by` is smallest (ClickHouse `argMin`). */
     argMin: createArgMeasureHelper('argMin'),
+    /**
+     * Finalize stored aggregate states: `measure.merge('uniq', 'users')` reads an
+     * `AggregateFunction(uniq, …)` column of an AggregatingMergeTree table as
+     * `uniqMerge(users)`. For `SimpleAggregateFunction` columns use the plain
+     * measure (`measure.sum`, `measure.max`). Not usable through relationships,
+     * with measure filters, or in published contracts.
+     */
+    merge: createMergeMeasure,
     /** Sample standard deviation (ClickHouse `stddevSamp`). */
     stddev: createMeasureHelper('stddev'),
     /** Sample variance (ClickHouse `varSamp`). */

package/dist/metric-query-engine.d.ts

@@ -1,4 +1,3 @@
-/** Metric validation, compilation orchestration and execution. */
 import type { MetricRef, GrainedMetricRef, MetricQuery, MetricResult, ExecutionContext } from './types.js';
 import type { QueryBuilderFactoryLike, QueryBuilderFactoryInput } from './query-builder-protocol.js';
 import type { ValidationResult } from './validation.js';

package/dist/metric-query-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metric-query-engine.d.ts","sourceRoot":"","sources":["../src/metric-query-engine.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC3G,OAAO,KAAK,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAErG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAQxD,MAAM,WAAW,wBAAwB;IACvC,mDAAmD;IACnD,cAAc,EAAE,wBAAwB,CAAC;CAC1C;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0B;gBAE7C,OAAO,EAAE,wBAAwB;IAI7C,SAAS,CAAC,iBAAiB,IAAI,uBAAuB;IAItD,yEAAyE;IACzE,SAAS,CAAC,qBAAqB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,uBAAuB;IAKpF;;OAEG;IACG,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,GAAE,WAAgB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAW3B;;OAEG;IACH,KAAK,CACH,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,GAAE,WAAgB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM;IAmBT;;OAEG;IACH,QAAQ,CACN,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB;YA+BL,aAAa;CAiC5B"}
+{"version":3,"file":"metric-query-engine.d.ts","sourceRoot":"","sources":["../src/metric-query-engine.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC3G,OAAO,KAAK,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAErG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AASxD,MAAM,WAAW,wBAAwB;IACvC,mDAAmD;IACnD,cAAc,EAAE,wBAAwB,CAAC;CAC1C;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0B;gBAE7C,OAAO,EAAE,wBAAwB;IAI7C,SAAS,CAAC,iBAAiB,IAAI,uBAAuB;IAItD,yEAAyE;IACzE,SAAS,CAAC,qBAAqB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,uBAAuB;IAKpF;;OAEG;IACG,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,GAAE,WAAgB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAW3B;;OAEG;IACH,KAAK,CACH,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,GAAE,WAAgB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM;IAmBT;;OAEG;IACH,QAAQ,CACN,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB;YA+BL,aAAa;CAuC5B"}

package/dist/metric-query-engine.js

@@ -1,3 +1,7 @@
+/** Metric validation, compilation orchestration and execution. */
+import { queryReadsFinal, withFinalSafety } from './utils/dataset-source.js';
+import { buildRelationshipBuilderContext } from './utils/relationship-builder-plan.js';
+import { resolveDatasetSqlDialect } from './utils/dataset-sql-dialect.js';
 import { toQueryBuilderFactory } from './query-builder-protocol.js';
 import { assertMetricHandle, getMetricRef, getMetricGrain } from './utils/metric-handle.js';
 import { validateMetricQueryInput } from './utils/metric-query-validation.js';
@@ -5,6 +9,7 @@ import { buildMetricQueryBuilder } from './utils/metric-query-builder.js';
 import { buildDerivedMetricSql } from './utils/metric-derived-query.js';
 import { overfetchLimit } from './utils/pagination.js';
 import { toMetricQueryResult } from './utils/metric-query-result.js';
+import { renderStatement } from './utils/statement-parameters.js';
 export class MetricQueryEngine {
     builderFactory;
     constructor(options) {
@@ -43,7 +48,7 @@ export class MetricQueryEngine {
         const grain = getMetricGrain(metric, query);
         const spec = ref.spec;
         if (spec.__type === 'derived_metric_spec') {
-            return buildDerivedMetricSql(ref, spec, query, grain, this.resolveBuilderFactory(context), context).sql;
+            return renderStatement(buildDerivedMetricSql(ref, spec, query, grain, this.resolveBuilderFactory(context), context)).sql;
         }
         const builder = buildMetricQueryBuilder(ref, spec, ref.dataset, query, grain, this.resolveBuilderFactory(context), context);
         return builder.toSQLWithParams().sql;
@@ -61,7 +66,7 @@ export class MetricQueryEngine {
         const grain = getMetricGrain(metric, query);
         try {
             if (ref.spec.__type === 'derived_metric_spec') {
-                buildDerivedMetricSql(ref, ref.spec, query, grain, this.resolveBuilderFactory(context), context);
+                renderStatement(buildDerivedMetricSql(ref, ref.spec, query, grain, this.resolveBuilderFactory(context), context));
             }
             else {
                 buildMetricQueryBuilder(ref, ref.spec, ref.dataset, query, grain, this.resolveBuilderFactory(context), context).toSQLWithParams();
@@ -87,7 +92,10 @@ export class MetricQueryEngine {
         const buildQuery = { ...query, limit: overfetchLimit(query.limit) };
         if (spec.__type === 'derived_metric_spec') {
             // Derived metrics: build CTE via builder, outer query via string, execute via rawQuery
-            const { sql, params } = buildDerivedMetricSql(ref, spec, buildQuery, grain, activeBuilderFactory, context);
+            const planned = renderStatement(buildDerivedMetricSql(ref, spec, buildQuery, grain, activeBuilderFactory, context));
+            // After planning, which validates the query; rawQuery drops builder settings.
+            const readsFinal = queryReadsFinal(ref.dataset, buildRelationshipBuilderContext(ref.dataset, buildQuery, context, resolveDatasetSqlDialect(activeBuilderFactory)));
+            const { sql, parameters: params } = withFinalSafety(readsFinal, planned);
             const rows = await activeBuilderFactory.rawQuery(sql, params, {
                 abortSignal: context?.abortSignal,
             });

package/dist/protocol-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-adapter.d.ts","sourceRoot":"","sources":["../src/protocol-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,uBAAuB,EAE5B,KAAK,sBAAsB,EAI5B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EACV,kBAAkB,EAElB,YAAY,EAEb,MAAM,YAAY,CAAC;AAMpB,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;AAuFD;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,mCAAwC,GAChD,uBAAuB,CAoIzB"}
+{"version":3,"file":"protocol-adapter.d.ts","sourceRoot":"","sources":["../src/protocol-adapter.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,uBAAuB,EAE5B,KAAK,sBAAsB,EAI5B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EACV,kBAAkB,EAElB,YAAY,EAEb,MAAM,YAAY,CAAC;AAMpB,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;AAmFD;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,mCAAwC,GAChD,uBAAuB,CAqIzB"}

package/dist/protocol-adapter.js

@@ -1,3 +1,4 @@
+import { byName } from './utils/by-name.js';
 import { splitDatasetMeasures } from './utils/dataset-measures.js';
 import { filterExpression, metricExpression, metricDerivation } from './utils/protocol-metric-expressions.js';
 import { parseProtocolIdentifier, parseProtocolQualifiedIdentifier, validateProtocolDatasetContract, } from '@hypequery/protocol';
@@ -6,9 +7,6 @@ import { toProtocolSemanticMetadata } from './utils/protocol-semantic-metadata.j
 import { assertPublishableTimeGrains, isPortableTimeGrain, requirePortableTimeGrain } from './utils/portable-grains.js';
 import { requirePortableAggregation } from './utils/portable-aggregations.js';
 import { assertNoPublishedSegments } from './utils/segments.js';
-function byName(left, right) {
-    return left.name.localeCompare(right.name);
-}
 function fieldSchema(type) {
     switch (type) {
         case 'string':
@@ -98,6 +96,7 @@ export function buildProtocolDatasetContract(dataset, options = {}) {
         ...(dataset.description !== undefined ? { description: dataset.description } : {}),
         ...toProtocolSemanticMetadata(dataset),
         source: dataset.source,
+        ...(dataset.rowResolution === undefined ? {} : { rowResolution: { ...dataset.rowResolution } }),
         ...(dataset.freshness !== undefined ? { freshness: { ...dataset.freshness } } : {}),
         ...(dataset.owner !== undefined ? { owner: dataset.owner } : {}),
         ...(dataset.defaults !== undefined

package/dist/protocol-deployment-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-deployment-adapter.d.ts","sourceRoot":"","sources":["../src/protocol-deployment-adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,0BAA0B,EAE/B,KAAK,sBAAsB,EAC5B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAKrD,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;CACvE;AAED,oEAAoE;AACpE,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,SAAS,kBAAkB,EAAE,EACvC,OAAO,GAAE,sCAA2C,GACnD,0BAA0B,CAyB5B"}
+{"version":3,"file":"protocol-deployment-adapter.d.ts","sourceRoot":"","sources":["../src/protocol-deployment-adapter.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,0BAA0B,EAE/B,KAAK,sBAAsB,EAC5B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAKrD,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;CACvE;AAED,oEAAoE;AACpE,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,SAAS,kBAAkB,EAAE,EACvC,OAAO,GAAE,sCAA2C,GACnD,0BAA0B,CA6B5B"}

package/dist/protocol-deployment-adapter.js

@@ -1,11 +1,17 @@
+import { byName } from './utils/by-name.js';
 import { splitDatasetMeasures } from './utils/dataset-measures.js';
+import { assertDeployable } from './utils/deployable-formulas.js';
 import { parseProtocolIdentifier, validateProtocolDeploymentContract, } from '@hypequery/protocol';
 import { buildProtocolDatasetContract } from './protocol-adapter.js';
 import { derivedMeasureExpression } from './utils/protocol-metric-expressions.js';
 import { toProtocolSemanticMetadata } from './utils/protocol-semantic-metadata.js';
 /** Build the deployment contract; local metrics are not carried. */
 export function buildProtocolDeploymentContract(datasets, options = {}) {
-    const contracts = datasets.map(dataset => {
+    // Sorted, as Python's builder does: the contract's identity must not depend
+    // on the order the datasets were passed in.
+    const contracts = [...datasets].sort(byName).map(dataset => {
+        // Name the dataset and measure before the contract grammar can only name a path.
+        assertDeployable(dataset);
         const contract = buildProtocolDatasetContract(dataset, {
             endpoint: options.endpoints?.[dataset.name],
         });

package/dist/protocol-rehydrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-rehydrate.d.ts","sourceRoot":"","sources":["../src/protocol-rehydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,uBAAuB,EAEvB,yBAAyB,EAM1B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAMlB,YAAY,EAIb,MAAM,YAAY,CAAC;AAOpB,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,4BAA4B,EAC5B,KAAK,yBAAyB,GAC/B,MAAM,yCAAyC,CAAC;AAEjD,kFAAkF;AAClF,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAAG;IACnD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CAC1D,CAAC;AAEF,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACjD;AAED;;;;;GAKG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,yBAAyB,GAAG,SAAS,CAAC;gBAGrD,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,yBAAyB;CAQrC;AA8QD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,CAAC,uBAAuB,GAAG,yBAAyB,CAAC,EAAE,EAC3E,OAAO,GAAE,gCAAqC,GAC7C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAwF7C;AAED,gFAAgF;AAChF,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,gCAAqC,GAC7C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAG7C"}
+{"version":3,"file":"protocol-rehydrate.d.ts","sourceRoot":"","sources":["../src/protocol-rehydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,uBAAuB,EAEvB,yBAAyB,EAM1B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAMlB,YAAY,EAIb,MAAM,YAAY,CAAC;AAOpB,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,4BAA4B,EAC5B,KAAK,yBAAyB,GAC/B,MAAM,yCAAyC,CAAC;AAEjD,kFAAkF;AAClF,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAAG;IACnD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CAC1D,CAAC;AAEF,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACjD;AAED;;;;;GAKG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,yBAAyB,GAAG,SAAS,CAAC;gBAGrD,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,yBAAyB;CAQrC;AA8QD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,CAAC,uBAAuB,GAAG,yBAAyB,CAAC,EAAE,EAC3E,OAAO,GAAE,gCAAqC,GAC7C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAyF7C;AAED,gFAAgF;AAChF,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,gCAAqC,GAC7C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAG7C"}

package/dist/protocol-rehydrate.js

@@ -255,6 +255,7 @@ export function rehydrateProtocolDatasets(contracts, options = {}) {
         const name = String(contract.name);
         const instance = dataset(name, {
             source: contract.source,
+            ...(contract.rowResolution === undefined ? {} : { rowResolution: contract.rowResolution }),
             ...snapshotSemanticMetadata(contract),
             ...(contract.description !== undefined ? { description: contract.description } : {}),
             ...(contract.owner !== undefined ? { owner: contract.owner } : {}),

package/dist/protocol-schema-adapter.d.ts

@@ -1,9 +1,9 @@
-import type { ZodTypeAny } from 'zod';
 import { type ProtocolSchema } from '@hypequery/protocol';
-export declare class ProtocolSchemaAdapterError extends TypeError {
-    readonly path: string;
-    constructor(message: string, path?: string);
-}
-/** Converts the portable subset of a Zod v3 schema into RFC 0004. */
-export declare function zodToProtocolSchema(schema: ZodTypeAny | undefined, path?: string): ProtocolSchema;
+import { type AnyZodSchema } from './utils/zod-schema-version.js';
+export { ProtocolSchemaAdapterError } from './utils/protocol-schema-conversion.js';
+/**
+ * Converts the portable subset of a Zod schema into RFC 0004. Accepts schemas
+ * from Zod 3 or Zod 4, so a caller's own copy of Zod need not match ours.
+ */
+export declare function zodToProtocolSchema(schema: AnyZodSchema | undefined, path?: string): ProtocolSchema;
 //# sourceMappingURL=protocol-schema-adapter.d.ts.map

package/dist/protocol-schema-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-schema-adapter.d.ts","sourceRoot":"","sources":["../src/protocol-schema-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAE7B,qBAAa,0BAA2B,SAAQ,SAAS;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,OAAO,EAAE,MAAM,EAAE,IAAI,SAAM;CAKxC;AAoPD,qEAAqE;AACrE,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,UAAU,GAAG,SAAS,EAC9B,IAAI,SAAM,GACT,cAAc,CAGhB"}
+{"version":3,"file":"protocol-schema-adapter.d.ts","sourceRoot":"","sources":["../src/protocol-schema-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAIhF,OAAO,EAAE,0BAA0B,EAAE,MAAM,uCAAuC,CAAC;AAEnF;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,YAAY,GAAG,SAAS,EAChC,IAAI,SAAM,GACT,cAAc,CAKhB"}

package/dist/protocol-schema-adapter.js

@@ -1,249 +1,16 @@
-import { validateCanonicalValue, validateProtocolSchema, } from '@hypequery/protocol';
-export class ProtocolSchemaAdapterError extends TypeError {
-    path;
-    constructor(message, path = '$') {
-        super(`${message} at ${path}`);
-        this.name = 'ProtocolSchemaAdapterError';
-        this.path = path;
-    }
-}
-function canonicalValue(input, path) {
-    try {
-        if (Array.isArray(input)) {
-            return validateCanonicalValue({
-                $hypequery: {
-                    type: 'array',
-                    version: 1,
-                    values: input.map((item, index) => canonicalValue(item, `${path}[${index}]`)),
-                },
-            });
-        }
-        if (typeof input === 'object' && input !== null) {
-            if ('$hypequery' in input)
-                return validateCanonicalValue(input);
-            const prototype = Object.getPrototypeOf(input);
-            if (prototype !== Object.prototype && prototype !== null) {
-                throw new ProtocolSchemaAdapterError('Default is not portable plain data', path);
-            }
-            return validateCanonicalValue({
-                $hypequery: {
-                    type: 'map',
-                    version: 1,
-                    entries: Object.entries(input)
-                        .sort(([left], [right]) => left.localeCompare(right))
-                        .map(([key, value]) => [key, canonicalValue(value, `${path}.${key}`)]),
-                },
-            });
-        }
-        return validateCanonicalValue(input);
-    }
-    catch (error) {
-        if (error instanceof ProtocolSchemaAdapterError)
-            throw error;
-        throw new ProtocolSchemaAdapterError('Default is not a canonical protocol value', path);
-    }
-}
-function typeName(schema) {
-    return String(schema?._def?.typeName ?? 'Unknown');
-}
-function description(schema) {
-    return typeof schema.description === 'string'
-        ? schema.description
-        : undefined;
-}
-function annotate(schema, result) {
-    const value = description(schema);
-    return value === undefined ? result : { ...result, description: value };
-}
-function convertString(schema, path) {
-    const result = { kind: 'string' };
-    for (const check of schema._def.checks) {
-        switch (check.kind) {
-            case 'min':
-                result.minLength = check.value;
-                break;
-            case 'max':
-                result.maxLength = check.value;
-                break;
-            case 'length':
-                result.minLength = check.value;
-                result.maxLength = check.value;
-                break;
-            default:
-                throw new ProtocolSchemaAdapterError(`Unsupported Zod string check "${String(check.kind)}"`, path);
-        }
-    }
-    return annotate(schema, result);
-}
-function convertNumber(schema, path) {
-    const result = { kind: 'number' };
-    for (const check of schema._def.checks) {
-        switch (check.kind) {
-            case 'int':
-                result.kind = 'integer';
-                break;
-            case 'min':
-                result[check.inclusive === false ? 'exclusiveMinimum' : 'minimum'] = check.value;
-                break;
-            case 'max':
-                result[check.inclusive === false ? 'exclusiveMaximum' : 'maximum'] = check.value;
-                break;
-            case 'finite':
-                break;
-            default:
-                throw new ProtocolSchemaAdapterError(`Unsupported Zod number check "${String(check.kind)}"`, path);
-        }
-    }
-    return annotate(schema, result);
-}
-function isOptionalProperty(schema) {
-    const name = typeName(schema);
-    return name === 'ZodOptional' || name === 'ZodDefault';
-}
-function nativeEnumValues(input) {
-    const values = Object.keys(input)
-        .filter(key => typeof input[String(input[key])] !== 'number')
-        .map(key => input[key]);
-    return [...new Set(values)];
-}
-function isUnconstrainedRecordKey(schema) {
-    if (schema === undefined || typeName(schema) !== 'ZodString')
-        return false;
-    const definition = schema._def;
-    return Array.isArray(definition.checks)
-        && definition.checks.length === 0
-        && definition.coerce !== true;
-}
-function convert(schema, path) {
-    const definition = schema._def;
-    switch (typeName(schema)) {
-        case 'ZodAny':
-        case 'ZodUnknown':
-            return annotate(schema, { kind: 'any' });
-        case 'ZodNever':
-        case 'ZodVoid':
-        case 'ZodUndefined':
-            return annotate(schema, { kind: 'void' });
-        case 'ZodNull':
-            return annotate(schema, { kind: 'null' });
-        case 'ZodBoolean':
-            return annotate(schema, { kind: 'boolean' });
-        case 'ZodString':
-            return convertString(schema, path);
-        case 'ZodNumber':
-            return convertNumber(schema, path);
-        case 'ZodLiteral':
-            return annotate(schema, {
-                kind: 'literal',
-                value: canonicalValue(definition.value, `${path}.value`),
-            });
-        case 'ZodEnum':
-            return annotate(schema, {
-                kind: 'enum',
-                values: [...definition.values],
-            });
-        case 'ZodNativeEnum': {
-            const values = nativeEnumValues(definition.values);
-            return annotate(schema, { kind: 'enum', values });
-        }
-        case 'ZodArray': {
-            const result = {
-                kind: 'array',
-                items: convert(definition.type, `${path}.items`),
-            };
-            if (definition.minLength?.value !== undefined)
-                result.minItems = definition.minLength.value;
-            if (definition.maxLength?.value !== undefined)
-                result.maxItems = definition.maxLength.value;
-            if (definition.exactLength?.value !== undefined) {
-                result.minItems = definition.exactLength.value;
-                result.maxItems = definition.exactLength.value;
-            }
-            return annotate(schema, result);
-        }
-        case 'ZodObject': {
-            if (typeName(definition.catchall) !== 'ZodNever') {
-                throw new ProtocolSchemaAdapterError('Unsupported Zod object catchall', path);
-            }
-            const shape = definition.shape();
-            const properties = Object.fromEntries(Object.entries(shape).map(([name, property]) => [
-                name,
-                convert(property, `${path}.properties.${name}`),
-            ]));
-            const required = Object.entries(shape)
-                .filter(([, property]) => !isOptionalProperty(property))
-                .map(([name]) => name);
-            const unknownProperties = definition.unknownKeys === 'passthrough'
-                ? 'preserve'
-                : definition.unknownKeys === 'strict'
-                    ? 'reject'
-                    : 'strip';
-            return annotate(schema, {
-                kind: 'object',
-                properties,
-                required,
-                unknownProperties,
-            });
-        }
-        case 'ZodRecord':
-            if (!isUnconstrainedRecordKey(definition.keyType)) {
-                throw new ProtocolSchemaAdapterError('Unsupported constrained Zod record key', path);
-            }
-            return annotate(schema, {
-                kind: 'record',
-                values: convert(definition.valueType, `${path}.values`),
-            });
-        case 'ZodUnion':
-            return annotate(schema, {
-                kind: 'union',
-                variants: definition.options.map((option, index) => convert(option, `${path}.variants[${index}]`)),
-            });
-        case 'ZodDiscriminatedUnion':
-            // RFC 0004 has no separate discriminator index. Converting every option
-            // drops only Zod's lookup metadata; each object's literal discriminator
-            // property remains part of its protocol variant.
-            return annotate(schema, {
-                kind: 'union',
-                variants: [...definition.options.values()].map((option, index) => convert(option, `${path}.variants[${index}]`)),
-            });
-        case 'ZodNullable':
-            return annotate(schema, {
-                kind: 'union',
-                variants: [convert(definition.innerType, `${path}.variants[0]`), { kind: 'null' }],
-            });
-        case 'ZodOptional':
-            return annotate(schema, convert(definition.innerType, path));
-        case 'ZodDefault': {
-            const inner = convert(definition.innerType, path);
-            if (inner.kind === 'void') {
-                throw new ProtocolSchemaAdapterError('Void schemas cannot carry defaults', path);
-            }
-            return annotate(schema, {
-                ...inner,
-                default: canonicalValue(definition.defaultValue(), `${path}.default`),
-            });
-        }
-        case 'ZodBranded':
-            return annotate(schema, convert(definition.type, path));
-        case 'ZodReadonly':
-            return annotate(schema, convert(definition.innerType, path));
-        case 'ZodEffects': {
-            const effectType = String(definition.effect?.type ?? 'unknown');
-            if (effectType !== 'refinement') {
-                throw new ProtocolSchemaAdapterError(`Unsupported Zod effect "${effectType}"`, path);
-            }
-            // A refinement preserves the wrapped schema's input and output shape.
-            // The rule itself remains enforced by Zod, but cannot be advertised by
-            // ProtocolSchema (for example, a cross-field selection requirement).
-            return annotate(schema, convert(definition.schema, path));
-        }
-        default:
-            throw new ProtocolSchemaAdapterError(`Unsupported Zod type "${typeName(schema)}"`, path);
-    }
-}
-/** Converts the portable subset of a Zod v3 schema into RFC 0004. */
+import { validateProtocolSchema } from '@hypequery/protocol';
+import { isZod4Schema } from './utils/zod-schema-version.js';
+import { convertZodV3Schema } from './utils/zod-v3-protocol-schema.js';
+import { convertZodV4Schema } from './utils/zod-v4-protocol-schema.js';
+export { ProtocolSchemaAdapterError } from './utils/protocol-schema-conversion.js';
+/**
+ * Converts the portable subset of a Zod schema into RFC 0004. Accepts schemas
+ * from Zod 3 or Zod 4, so a caller's own copy of Zod need not match ours.
+ */
 export function zodToProtocolSchema(schema, path = '$') {
     if (schema === undefined)
         return validateProtocolSchema({ kind: 'any' });
-    return validateProtocolSchema(convert(schema, path));
+    return validateProtocolSchema(isZod4Schema(schema)
+        ? convertZodV4Schema(schema, path)
+        : convertZodV3Schema(schema, path));
 }

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

@@ -9,7 +9,14 @@
  * This keeps @hypequery/serve DB-agnostic while enabling first-class builder usage.
  */
 import type { DatasetSqlDialect } from './dataset-sql-dialect.js';
-/** A chainable query builder instance (what `.table(name)` returns). */
+/**
+ * A chainable query builder instance (what `.table(name)` returns).
+ *
+ * Aliases and column arguments the datasets planner passes are SQL text as
+ * the datasets dialect spells it: generated output aliases arrive already
+ * quoted (for example `` `revenue` ``). Insert them verbatim; do not quote
+ * them again.
+ */
 export interface QueryBuilderLike {
     select(columns: string[] | string): QueryBuilderLike;
     sum(column: string, alias?: string): QueryBuilderLike;
@@ -30,7 +37,23 @@ export interface QueryBuilderLike {
     variance?(column: string, alias?: string): QueryBuilderLike;
     /** Estimated number of distinct non-NULL values of `column`. */
     approxCountDistinct?(column: string, alias?: string): QueryBuilderLike;
+    /**
+     * Finalize the aggregate states in `column` with `stateFunction`'s `-Merge`
+     * combinator (ClickHouse `uniqMerge(users)`). `stateFunction` is one of the
+     * datasets allowlist. `@hypequery/clickhouse` implements it from the release
+     * that adds `mergeState`.
+     */
+    mergeState?(stateFunction: string, column: string, alias?: string): QueryBuilderLike;
     where(column: string, operator: string, value: unknown): QueryBuilderLike;
+    /**
+     * Optional: read the table source with ClickHouse `FINAL`. Needed only for
+     * datasets that declare `rowResolution`; querying one through a builder without
+     * it is refused rather than run without `FINAL`, which would count every
+     * unmerged row version.
+     */
+    final?(): QueryBuilderLike;
+    /** Query-level ClickHouse settings, sent with the query. */
+    settings?(opts: Record<string, string | number | boolean>): QueryBuilderLike;
     leftJoin(table: string, leftColumn: string, rightColumn: string, alias?: string, on?: QueryBuilderJoinCondition | QueryBuilderJoinCondition[]): QueryBuilderLike;
     /**
      * Single-match LEFT JOIN (ClickHouse `LEFT ANY JOIN`). Required to query
@@ -55,6 +78,16 @@ export interface QueryBuilderLike {
         sql: string;
         parameters: unknown[];
     };
+    /**
+     * Optional: compile with each bound value written through `placeholder`,
+     * called once per value in SQL order, its result inserted verbatim. Lets
+     * the datasets planner own placeholder spelling and numbering when it
+     * embeds this statement in a larger one. Required on datasets dialects that
+     * number placeholders (such as Postgres `$n`) and only called there:
+     * positional `?` dialects keep using `toSQLWithParams`, unchanged.
+     * `@hypequery/clickhouse` implements it from 2.14.0.
+     */
+    toSQLWithPlaceholders?(placeholder: (value: unknown) => string): string;
     execute<T = Record<string, unknown>>(options?: {
         abortSignal?: AbortSignal;
     }): Promise<T[]>;

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":"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"}
+{"version":3,"file":"query-builder-protocol.d.ts","sourceRoot":"","sources":["../src/query-builder-protocol.ts"],"names":[],"mappings":"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"}

package/dist/query-planner.d.ts

@@ -1,20 +1,29 @@
 import type { AggregationSpec, AnyDatasetInstance, ExecutionContext, MeasureDefinition, MetricOrderBy, TimeGrain } from "./types.js";
 import type { QueryBuilderLike } from "./query-builder-protocol.js";
-import type { DatasetSqlDialect } from './dataset-sql-dialect.js';
+import type { DatasetSqlDialectRules } from './dataset-sql-dialect.js';
 import { type RelationshipBuilderContext } from './utils/relationship-builder-plan.js';
 type DatasetShape = AnyDatasetInstance;
 export declare function resolveDimensionExpression(ds: DatasetShape, dimensionName: string, joinCtx?: RelationshipBuilderContext): string;
 export declare function resolveFilterField(ds: DatasetShape, filterField: string, joinCtx?: RelationshipBuilderContext): string;
-export declare function buildDimensionSelectionPlan(ds: DatasetShape, dimensions: string[], grain: TimeGrain | undefined, joinCtx?: RelationshipBuilderContext, timezone?: string, dialect?: DatasetSqlDialect): {
+export declare function buildDimensionSelectionPlan(ds: DatasetShape, dimensions: string[], grain: TimeGrain | undefined, joinCtx: RelationshipBuilderContext | undefined, timezone: string | undefined, dialect: DatasetSqlDialectRules): {
     selectParts: string[];
     groupByParts: string[];
 };
-export declare function applyAggregationSpec(qb: QueryBuilderLike, ds: DatasetShape, spec: AggregationSpec, alias: string, joinCtx?: RelationshipBuilderContext, expressions?: {
+export declare function applyAggregationSpec(qb: QueryBuilderLike, ds: DatasetShape, spec: AggregationSpec, name: string, joinCtx: RelationshipBuilderContext | undefined, dialect: DatasetSqlDialectRules, expressions?: {
     field: string;
     arg?: string;
 }): QueryBuilderLike;
-export declare function applyMeasureDefinition(qb: QueryBuilderLike, ds: DatasetShape, name: string, definition: MeasureDefinition, joinCtx?: RelationshipBuilderContext): QueryBuilderLike;
-export declare function appendOrderLimitOffset(qb: QueryBuilderLike, orderBy: MetricOrderBy[] | undefined, grain: TimeGrain | undefined, limit?: number, offset?: number, joinCtx?: RelationshipBuilderContext, dialect?: DatasetSqlDialect): QueryBuilderLike;
+export declare function applyMeasureDefinition(qb: QueryBuilderLike, ds: DatasetShape, name: string, definition: MeasureDefinition, joinCtx: RelationshipBuilderContext | undefined, dialect: DatasetSqlDialectRules): QueryBuilderLike;
+/**
+ * Appends ORDER BY, LIMIT and OFFSET. Under joins, an order on a selected
+ * qualified dimension repeats its guarded expression (the GROUP BY key) rather
+ * than naming the alias, which the engine may resolve to the raw joined column;
+ * any other qualified order (a related measure) sorts by its quoted alias.
+ */
+export declare function appendOrderLimitOffset(qb: QueryBuilderLike, orderBy: MetricOrderBy[] | undefined, grain: TimeGrain | undefined, limit: number | undefined, offset: number | undefined, joinCtx: RelationshipBuilderContext | undefined, dialect: DatasetSqlDialectRules, selection?: {
+    ds: DatasetShape;
+    dimensions: readonly string[];
+}): QueryBuilderLike;
 export declare function resolveTenantFilterColumn(ds: DatasetShape, context?: ExecutionContext): string | undefined;
 export {};
 //# sourceMappingURL=query-planner.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"query-planner.d.ts","sourceRoot":"","sources":["../src/query-planner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,SAAS,EACV,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAIpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAGlE,OAAO,EAGL,KAAK,0BAA0B,EAChC,MAAM,sCAAsC,CAAC;AAI9C,KAAK,YAAY,GAAG,kBAAkB,CAAC;AAEvC,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,YAAY,EAChB,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,0BAA0B,GACnC,MAAM,CAUR;AAED,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,YAAY,EAChB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,0BAA0B,GACnC,MAAM,CAMR;AAED,wBAAgB,2BAA2B,CACzC,EAAE,EAAE,YAAY,EAChB,UAAU,EAAE,MAAM,EAAE,EACpB,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,OAAO,CAAC,EAAE,0BAA0B,EACpC,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,GAAE,iBAA+C,GACvD;IAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAmCnD;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,gBAAgB,EACpB,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,0BAA0B,EACpC,WAAW,CAAC,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,gBAAgB,CAqElB;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,iBAAiB,EAC7B,OAAO,CAAC,EAAE,0BAA0B,GACnC,gBAAgB,CAElB;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,OAAO,EAAE,aAAa,EAAE,GAAG,SAAS,EACpC,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,0BAA0B,EACpC,OAAO,GAAE,iBAA+C,GACvD,gBAAgB,CAoBlB;AAED,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,YAAY,EAChB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,SAAS,CAMpB"}
+{"version":3,"file":"query-planner.d.ts","sourceRoot":"","sources":["../src/query-planner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,SAAS,EACV,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAIpE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAEvE,OAAO,EAGL,KAAK,0BAA0B,EAChC,MAAM,sCAAsC,CAAC;AAK9C,KAAK,YAAY,GAAG,kBAAkB,CAAC;AAEvC,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,YAAY,EAChB,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,0BAA0B,GACnC,MAAM,CAUR;AAED,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,YAAY,EAChB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,0BAA0B,GACnC,MAAM,CAMR;AAED,wBAAgB,2BAA2B,CACzC,EAAE,EAAE,YAAY,EAChB,UAAU,EAAE,MAAM,EAAE,EACpB,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,OAAO,EAAE,0BAA0B,GAAG,SAAS,EAC/C,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,EAAE,sBAAsB,GAC9B;IAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAkCnD;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,gBAAgB,EACpB,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,0BAA0B,GAAG,SAAS,EAC/C,OAAO,EAAE,sBAAsB,EAC/B,WAAW,CAAC,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,gBAAgB,CAmFlB;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,iBAAiB,EAC7B,OAAO,EAAE,0BAA0B,GAAG,SAAS,EAC/C,OAAO,EAAE,sBAAsB,GAC9B,gBAAgB,CAElB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,OAAO,EAAE,aAAa,EAAE,GAAG,SAAS,EACpC,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,0BAA0B,GAAG,SAAS,EAC/C,OAAO,EAAE,sBAAsB,EAC/B,SAAS,CAAC,EAAE;IAAE,EAAE,EAAE,YAAY,CAAC;IAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC9D,gBAAgB,CAsBlB;AAED,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,YAAY,EAChB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,SAAS,CAMpB"}