@hypequery/datasets 0.18.0 → 0.19.0

package/dist/utils/portable-aggregations.js

@@ -0,0 +1,15 @@
+/**
+ * Aggregations that the published deployment contract can carry.
+ *
+ * `approxCountDistinct` runs locally, but it is an expression extension 2 and
+ * deployment contract 3 feature (RFC 0015). Publishing emits contract 2 until
+ * it can emit contract 3, so it refuses the measure with an error naming it.
+ */
+/** Returns `aggregation` when publishing can carry it; otherwise throws naming `owner`. */
+export function requirePortableAggregation(aggregation, owner) {
+    if (aggregation === 'approxCountDistinct') {
+        throw new Error(`${owner} uses approxCountDistinct, which cannot be published yet: approximate aggregations ` +
+            'need deployment contract 3 (RFC 0015). Use it for local queries, or publish countDistinct instead.');
+    }
+    return aggregation;
+}

package/dist/utils/portable-grains.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Time grains that the published deployment contract can carry.
+ *
+ * `minute` and `hour` run locally, but they are expression extension 2 and
+ * deployment contract 3 features (RFC 0015). Publishing emits contract 2 until
+ * it can emit contract 3, so a dataset that pins a sub-day grain is refused
+ * with an error naming what needs it, rather than failing later as an opaque
+ * contract validation error.
+ */
+import type { ProtocolTimeGrain } from '@hypequery/protocol';
+import type { TimeGrain } from '../types.js';
+/** Grains deployment contract 2 and invocation 1 carry, in ascending order. */
+export declare const PORTABLE_TIME_GRAINS: readonly ProtocolTimeGrain[];
+export declare function isPortableTimeGrain(grain: TimeGrain): grain is ProtocolTimeGrain;
+/** Returns `grain` when publishing can carry it; otherwise throws naming `owner`. */
+export declare function requirePortableTimeGrain(grain: TimeGrain, owner: string): ProtocolTimeGrain;
+/** Contract 2 cannot represent a dataset-level restriction on portable grains. */
+export declare function assertPublishableTimeGrains(dataset: {
+    readonly name: string;
+    readonly timeGrains?: readonly TimeGrain[];
+}): void;
+//# sourceMappingURL=portable-grains.d.ts.map

package/dist/utils/portable-grains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-grains.d.ts","sourceRoot":"","sources":["../../src/utils/portable-grains.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB,EAAE,SAAS,iBAAiB,EAE3D,CAAC;AAIH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK,IAAI,iBAAiB,CAEhF;AAED,qFAAqF;AACrF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAQ3F;AAED,kFAAkF;AAClF,wBAAgB,2BAA2B,CACzC,OAAO,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,SAAS,EAAE,CAAA;CAAE,GAC7E,IAAI,CASN"}

package/dist/utils/portable-grains.js

@@ -0,0 +1,35 @@
+/**
+ * Time grains that the published deployment contract can carry.
+ *
+ * `minute` and `hour` run locally, but they are expression extension 2 and
+ * deployment contract 3 features (RFC 0015). Publishing emits contract 2 until
+ * it can emit contract 3, so a dataset that pins a sub-day grain is refused
+ * with an error naming what needs it, rather than failing later as an opaque
+ * contract validation error.
+ */
+/** Grains deployment contract 2 and invocation 1 carry, in ascending order. */
+export const PORTABLE_TIME_GRAINS = Object.freeze([
+    'day', 'week', 'month', 'quarter', 'year',
+]);
+const CONTRACT_2_GRAINS = new Set(PORTABLE_TIME_GRAINS);
+export function isPortableTimeGrain(grain) {
+    return CONTRACT_2_GRAINS.has(grain);
+}
+/** Returns `grain` when publishing can carry it; otherwise throws naming `owner`. */
+export function requirePortableTimeGrain(grain, owner) {
+    if (!isPortableTimeGrain(grain)) {
+        throw new Error(`${owner} uses the "${grain}" time grain, which cannot be published yet: sub-day grains ` +
+            'need deployment contract 3 (RFC 0015). Use it for local queries, or pin a grain of a day or longer.');
+    }
+    return grain;
+}
+/** Contract 2 cannot represent a dataset-level restriction on portable grains. */
+export function assertPublishableTimeGrains(dataset) {
+    if (dataset.timeGrains === undefined)
+        return;
+    const missing = PORTABLE_TIME_GRAINS.filter(grain => !dataset.timeGrains?.includes(grain));
+    if (missing.length > 0) {
+        throw new Error(`Dataset "${dataset.name}" timeGrains excludes ${missing.join(', ')}, but deployment contract 2 ` +
+            'cannot preserve dataset-level grain restrictions. Use all day-through-year grains or keep this dataset local.');
+    }
+}

package/dist/utils/portable-semantic-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"portable-semantic-query.d.ts","sourceRoot":"","sources":["../../src/utils/portable-semantic-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAA+B,qBAAqB,EAAa,MAAM,aAAa,CAAC;AAIjG,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,qBAAqB,GAAG,SAAS,CAKhF;AAWD,wBAAgB,aAAa,CAAC,SAAS,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqBxG"}
+{"version":3,"file":"portable-semantic-query.d.ts","sourceRoot":"","sources":["../../src/utils/portable-semantic-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAA+B,qBAAqB,EAAa,MAAM,aAAa,CAAC;AAKjG,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,qBAAqB,GAAG,SAAS,CAKhF;AAYD,wBAAgB,aAAa,CAAC,SAAS,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqBxG"}

package/dist/utils/portable-semantic-query.js

@@ -1,5 +1,6 @@
 import { PortableExecutionUnsupportedError } from '../portable-execution-errors.js';
 import { rehydrateMeasureFilter } from './protocol-rehydrate-filters.js';
+import { UNSUPPORTED_CONTRACT_REASONS } from './unsupported-contract-reasons.js';
 export function tenantRuntime(tenant) {
     if (tenant === undefined || tenant === null)
         return undefined;
@@ -10,7 +11,7 @@ export function tenantRuntime(tenant) {
     return tenant;
 }
 function operationFilters(operation) {
-    return (operation.filters ?? []).map((expression, index) => rehydrateMeasureFilter(expression, () => new PortableExecutionUnsupportedError(`Filter ${index} is not a field/operator/value comparison, so it cannot be planned.`)));
+    return (operation.filters ?? []).map((expression, index) => rehydrateMeasureFilter(expression, () => new PortableExecutionUnsupportedError(`Filter ${index} is not a field/operator/value comparison, so it cannot be planned.`, { reason: UNSUPPORTED_CONTRACT_REASONS.queryFilterNotComparison })));
 }
 export function semanticQuery(operation, maxRows) {
     const filters = operationFilters(operation);

package/dist/utils/protocol-metric-expressions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-metric-expressions.d.ts","sourceRoot":"","sources":["../../src/utils/protocol-metric-expressions.ts"],"names":[],"mappings":"AAAA,OAAO,EAEgB,KAAK,kBAAkB,EAAE,KAAK,wBAAwB,EAC5E,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,eAAe,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAsC9G,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,kBAAkB,CAgBzE;AA+CD,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,wBAAwB,GAAG,kBAAkB,CAGjG;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,iBAAiB,GAAG,kBAAkB,CAQ9F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,wBAAwB,CASlF"}
+{"version":3,"file":"protocol-metric-expressions.d.ts","sourceRoot":"","sources":["../../src/utils/protocol-metric-expressions.ts"],"names":[],"mappings":"AAAA,OAAO,EAEgB,KAAK,kBAAkB,EAAE,KAAK,wBAAwB,EAC5E,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,eAAe,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAuC9G,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,kBAAkB,CAgBzE;AA+CD,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,wBAAwB,GAAG,kBAAkB,CAGjG;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,iBAAiB,GAAG,kBAAkB,CAQ9F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,wBAAwB,CASlF"}

package/dist/utils/protocol-metric-expressions.js

@@ -1,4 +1,5 @@
 import { parseProtocolIdentifier, parseProtocolQualifiedIdentifier, validateCanonicalValue, } from '@hypequery/protocol';
+import { requirePortableAggregation } from './portable-aggregations.js';
 function canonicalValue(input) {
     if (Array.isArray(input)) {
         return validateCanonicalValue({
@@ -48,7 +49,7 @@ export function filterExpression(filter) {
 function aggregationExpression(spec) {
     const result = {
         kind: 'aggregate',
-        aggregation: spec.aggregation,
+        aggregation: requirePortableAggregation(spec.aggregation, `An aggregate over "${spec.field}"`),
         field: parseProtocolQualifiedIdentifier(spec.field),
         ...(spec.argField !== undefined
             ? { argField: parseProtocolQualifiedIdentifier(spec.argField) }

package/dist/utils/relationship-builder-plan.d.ts

@@ -46,10 +46,13 @@ export declare function qualifyBaseColumn(ctx: RelationshipBuilderContext | unde
  */
 export declare function resolveQualifiedColumn(ds: AnyDatasetInstance, name: string): string;
 /**
- * Applies each relationship LEFT JOIN to the builder and, when runtime tenancy
+ * Applies each relationship join to the builder as a single-match LEFT JOIN
+ * (`leftAnyJoin`, e.g. ClickHouse `LEFT ANY JOIN`) and, when runtime tenancy
  * is active on a target, scopes the joined rows with the tenant predicate.
- * Builders that support single-match joins (`leftAnyJoin`, e.g. ClickHouse
- * `LEFT ANY JOIN`) get them so duplicate target keys cannot fan out aggregates.
+ *
+ * A builder without `leftAnyJoin` is refused rather than downgraded to a plain
+ * `leftJoin`: duplicate target keys would fan out base rows and silently
+ * inflate every aggregate in the query.
  */
 export declare function applyRelationshipJoins(qb: QueryBuilderLike, ctx: RelationshipBuilderContext | undefined): QueryBuilderLike;
 export {};

package/dist/utils/relationship-builder-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relationship-builder-plan.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-builder-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACZ,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAA6B,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGtF,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,MAAM,CAAC,EAAE,eAAe,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C;AAED,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CACtD;AAED,KAAK,SAAS,GAAG,IAAI,CAAC,YAAY,GAAG,WAAW,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC,CAAC;AAExF;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,gBAAgB,GACzB,0BAA0B,GAAG,SAAS,CAuCxC;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,0BAA0B,GAAG,SAAS,EAC3C,MAAM,EAAE,MAAM,GACb,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,MAAM,GACX,MAAM,CAOR;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,GAAG,EAAE,0BAA0B,GAAG,SAAS,GAC1C,gBAAgB,CAqBlB"}
+{"version":3,"file":"relationship-builder-plan.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-builder-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACZ,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAA6B,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGtF,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,MAAM,CAAC,EAAE,eAAe,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C;AAED,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CACtD;AAED,KAAK,SAAS,GAAG,IAAI,CAAC,YAAY,GAAG,WAAW,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC,CAAC;AAExF;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,gBAAgB,GACzB,0BAA0B,GAAG,SAAS,CAuCxC;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,0BAA0B,GAAG,SAAS,EAC3C,MAAM,EAAE,MAAM,GACb,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,MAAM,GACX,MAAM,CAOR;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,GAAG,EAAE,0BAA0B,GAAG,SAAS,GAC1C,gBAAgB,CA4BlB"}

package/dist/utils/relationship-builder-plan.js

@@ -69,18 +69,26 @@ export function resolveQualifiedColumn(ds, name) {
     return `${relationshipName}.${targetColumn}`;
 }
 /**
- * Applies each relationship LEFT JOIN to the builder and, when runtime tenancy
+ * Applies each relationship join to the builder as a single-match LEFT JOIN
+ * (`leftAnyJoin`, e.g. ClickHouse `LEFT ANY JOIN`) and, when runtime tenancy
  * is active on a target, scopes the joined rows with the tenant predicate.
- * Builders that support single-match joins (`leftAnyJoin`, e.g. ClickHouse
- * `LEFT ANY JOIN`) get them so duplicate target keys cannot fan out aggregates.
+ *
+ * A builder without `leftAnyJoin` is refused rather than downgraded to a plain
+ * `leftJoin`: duplicate target keys would fan out base rows and silently
+ * inflate every aggregate in the query.
  */
 export function applyRelationshipJoins(qb, ctx) {
     if (!ctx) {
         return qb;
     }
     for (const join of ctx.joins) {
-        const applyJoin = qb.leftAnyJoin?.bind(qb) ?? qb.leftJoin.bind(qb);
-        qb = applyJoin(join.source, `${ctx.baseSource}.${join.from}`, `${join.relationship}.${join.to}`, join.relationship, join.tenant
+        if (!qb.leftAnyJoin) {
+            throw new Error(`Relationship "${join.relationship}" cannot be joined: the query builder does not implement ` +
+                'leftAnyJoin (a single-match LEFT JOIN such as ClickHouse "LEFT ANY JOIN"). A plain leftJoin ' +
+                'would fan out duplicate target keys and inflate aggregates, so relationship-qualified fields ' +
+                'are unavailable with this builder.');
+        }
+        qb = qb.leftAnyJoin(join.source, `${ctx.baseSource}.${join.from}`, `${join.relationship}.${join.to}`, join.relationship, join.tenant
             ? {
                 column: `${join.relationship}.${join.tenant.field}`,
                 operator: join.tenant.operator,

package/dist/utils/relationship-key-check.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pure helpers for `checkRelationships`: which relationships a check covers,
+ * and how a key-count row becomes a finding.
+ */
+import type { AnyDatasetInstance } from '../types.js';
+export type ToOneRelationshipKind = 'belongsTo' | 'hasOne';
+export interface ToOneRelationshipTarget {
+    relationship: string;
+    kind: ToOneRelationshipKind;
+    /** Target dataset. */
+    target: AnyDatasetInstance;
+    /** Target join column, which a to-one declaration requires to be unique. */
+    column: string;
+}
+/**
+ * Lists the to-one relationships to check. `hasMany` is excluded because it
+ * never joins, so its key has no uniqueness requirement. An explicit
+ * `only` list must name declared to-one relationships.
+ */
+export declare function listToOneRelationships(ds: AnyDatasetInstance, only?: readonly string[]): ToOneRelationshipTarget[];
+export interface RelationshipKeyIssue {
+    relationship: string;
+    kind: ToOneRelationshipKind;
+    /** Target dataset name. */
+    target: string;
+    /** Physical target table. */
+    source: string;
+    /** Target join column. */
+    column: string;
+    /** Target rows with a non-NULL key, within the checked tenant scope. Large counts are decimal strings. */
+    rows: number | string;
+    /** Distinct non-NULL keys, within the checked tenant scope. Large counts are decimal strings. */
+    distinctKeys: number | string;
+    message: string;
+}
+/** Reads a count without losing precision when a driver returns UInt64 as a string. */
+export declare function readCount(value: unknown): bigint;
+/**
+ * Returns the finding for a to-one relationship whose target key repeats, or
+ * undefined when every non-NULL key is unique.
+ */
+export declare function relationshipKeyIssue(entry: ToOneRelationshipTarget, rows: bigint, distinctKeys: bigint): RelationshipKeyIssue | undefined;
+//# sourceMappingURL=relationship-key-check.d.ts.map

package/dist/utils/relationship-key-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-key-check.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-key-check.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAA0B,MAAM,aAAa,CAAC;AAE9E,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE3D,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,qBAAqB,CAAC;IAC5B,sBAAsB;IACtB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,kBAAkB,EACtB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GACvB,uBAAuB,EAAE,CAuB3B;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,qBAAqB,CAAC;IAC5B,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,0GAA0G;IAC1G,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,iGAAiG;IACjG,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,uFAAuF;AACvF,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAchD;AAMD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,uBAAuB,EAC9B,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GACnB,oBAAoB,GAAG,SAAS,CAkBlC"}

package/dist/utils/relationship-key-check.js

@@ -0,0 +1,72 @@
+/**
+ * Pure helpers for `checkRelationships`: which relationships a check covers,
+ * and how a key-count row becomes a finding.
+ */
+/**
+ * Lists the to-one relationships to check. `hasMany` is excluded because it
+ * never joins, so its key has no uniqueness requirement. An explicit
+ * `only` list must name declared to-one relationships.
+ */
+export function listToOneRelationships(ds, only) {
+    const declared = Object.entries(ds.relationships);
+    if (only) {
+        for (const name of only) {
+            const relationship = Object.hasOwn(ds.relationships, name) ? ds.relationships[name] : undefined;
+            if (!relationship) {
+                throw new Error(`Unknown relationship "${name}" on dataset "${ds.name}".`);
+            }
+            if (relationship.kind === 'hasMany') {
+                throw new Error(`Relationship "${name}" on dataset "${ds.name}" is hasMany; only to-one relationships have a key to check.`);
+            }
+        }
+    }
+    return declared
+        .filter(([name, relationship]) => relationship.kind !== 'hasMany' && (!only || only.includes(name)))
+        .map(([name, relationship]) => ({
+        relationship: name,
+        kind: relationship.kind,
+        target: relationship.target(),
+        column: relationship.to,
+    }));
+}
+/** Reads a count without losing precision when a driver returns UInt64 as a string. */
+export function readCount(value) {
+    if (value == null) {
+        return 0n;
+    }
+    if (typeof value === 'bigint' && value >= 0n) {
+        return value;
+    }
+    if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0) {
+        return BigInt(value);
+    }
+    if (typeof value === 'string' && /^\d+$/.test(value)) {
+        return BigInt(value);
+    }
+    throw new Error(`Expected a non-negative integer row count, received ${JSON.stringify(String(value))}.`);
+}
+function displayCount(count) {
+    return count <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(count) : count.toString();
+}
+/**
+ * Returns the finding for a to-one relationship whose target key repeats, or
+ * undefined when every non-NULL key is unique.
+ */
+export function relationshipKeyIssue(entry, rows, distinctKeys) {
+    if (rows <= distinctKeys) {
+        return undefined;
+    }
+    const source = entry.target.source;
+    return {
+        relationship: entry.relationship,
+        kind: entry.kind,
+        target: entry.target.name,
+        source,
+        column: entry.column,
+        rows: displayCount(rows),
+        distinctKeys: displayCount(distinctKeys),
+        message: `Relationship "${entry.relationship}" is declared ${entry.kind}, but "${source}.${entry.column}" ` +
+            `has ${rows} rows for ${distinctKeys} distinct keys. Joins pick an arbitrary matching row; ` +
+            'make the key unique or declare the relationship as hasMany.',
+    };
+}

package/dist/utils/segments.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Dataset segments (RFC 0015): named, author-defined row filters that a query
+ * selects by name.
+ *
+ * A segment compares the dataset's own dimensions with literals. It may use a
+ * dimension that is not exposed as a filter: the filter allow-list governs
+ * what a caller may construct, not what an author may declare. It may not
+ * traverse a relationship or constrain the tenant column, which only trusted
+ * runtime context scopes.
+ */
+import type { AnyDatasetInstance, DimensionDefinition, MetricFilter, SegmentDefinition } from '../types.js';
+interface SegmentOwner {
+    readonly tenantKey?: string;
+    readonly dimensions: Readonly<Record<string, DimensionDefinition>>;
+}
+/** Throws when a declared segment is malformed; returns a frozen copy otherwise. */
+export declare function normalizeSegments(datasetName: string, owner: SegmentOwner, segments: Record<string, SegmentDefinition> | undefined): Record<string, SegmentDefinition>;
+/**
+ * Publishing emits deployment contract 2, which cannot carry segments
+ * (RFC 0015), so a dataset that declares them is refused by name.
+ */
+export declare function assertNoPublishedSegments(ds: Pick<AnyDatasetInstance, 'name' | 'segments'>): void;
+/** Validation errors for a query's `segments` selection. */
+export declare function segmentSelectionErrors(ds: AnyDatasetInstance, names: unknown): string[];
+/**
+ * The conditions a selection applies, as filters over dimension names. Order
+ * follows the selection, then each segment's authored filters.
+ */
+export declare function segmentFilters(ds: AnyDatasetInstance, names: readonly string[] | undefined): MetricFilter[];
+export {};
+//# sourceMappingURL=segments.d.ts.map

package/dist/utils/segments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"segments.d.ts","sourceRoot":"","sources":["../../src/utils/segments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAM5G,UAAU,YAAY;IACpB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC;CACpE;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,SAAS,GACtD,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAkCnC;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,GAAG,UAAU,CAAC,GAAG,IAAI,CAQjG;AAED,4DAA4D;AAC5D,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAiBvF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,YAAY,EAAE,CAE3G"}

package/dist/utils/segments.js

@@ -0,0 +1,91 @@
+/**
+ * Dataset segments (RFC 0015): named, author-defined row filters that a query
+ * selects by name.
+ *
+ * A segment compares the dataset's own dimensions with literals. It may use a
+ * dimension that is not exposed as a filter: the filter allow-list governs
+ * what a caller may construct, not what an author may declare. It may not
+ * traverse a relationship or constrain the tenant column, which only trusted
+ * runtime context scopes.
+ */
+import { SEMANTIC_FILTER_OPERATORS } from '../constants.js';
+import { validateFilterValue } from '../validation.js';
+const SEGMENT_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const OPERATORS = new Set(SEMANTIC_FILTER_OPERATORS);
+/** Throws when a declared segment is malformed; returns a frozen copy otherwise. */
+export function normalizeSegments(datasetName, owner, segments) {
+    const fail = (name, message) => {
+        throw new Error(`Invalid segment "${name}" on dataset "${datasetName}": ${message}`);
+    };
+    const result = [];
+    for (const [name, segment] of Object.entries(segments ?? {})) {
+        if (!SEGMENT_NAME.test(name))
+            fail(name, 'names must be identifiers (letters, digits, underscores).');
+        if (!Array.isArray(segment?.filters) || segment.filters.length === 0) {
+            fail(name, 'filters must be a non-empty array.');
+        }
+        for (const filter of segment.filters) {
+            const dimension = Object.hasOwn(owner.dimensions, filter.field) ? owner.dimensions[filter.field] : undefined;
+            if (!dimension) {
+                fail(name, `"${filter.field}" is not a dimension of this dataset; segments cannot use relationships.`);
+            }
+            const column = dimension.column ?? filter.field;
+            if (owner.tenantKey !== undefined && (column === owner.tenantKey || filter.field === owner.tenantKey)) {
+                fail(name, `"${filter.field}" is the tenant column, which only runtime tenant scoping may constrain.`);
+            }
+            if (!OPERATORS.has(filter.operator))
+                fail(name, `unsupported operator "${String(filter.operator)}".`);
+            const valueError = validateFilterValue(filter, dimension.fieldType);
+            if (valueError)
+                fail(name, valueError);
+        }
+        result.push([name, Object.freeze({
+                filters: Object.freeze(segment.filters.map(filter => Object.freeze({
+                    ...filter,
+                    value: Array.isArray(filter.value) ? Object.freeze([...filter.value]) : filter.value,
+                }))),
+                ...(segment.label !== undefined ? { label: segment.label } : {}),
+                ...(segment.description !== undefined ? { description: segment.description } : {}),
+            })]);
+    }
+    // Object.fromEntries preserves names such as "__proto__" as own properties.
+    return Object.freeze(Object.fromEntries(result));
+}
+/**
+ * Publishing emits deployment contract 2, which cannot carry segments
+ * (RFC 0015), so a dataset that declares them is refused by name.
+ */
+export function assertNoPublishedSegments(ds) {
+    const names = Object.keys(ds.segments ?? {});
+    if (names.length > 0) {
+        throw new Error(`Dataset "${ds.name}" declares segments (${names.join(', ')}), which cannot be published yet: ` +
+            'segments need deployment contract 3 (RFC 0015). Use them for local queries until publishing emits contract 3.');
+    }
+}
+/** Validation errors for a query's `segments` selection. */
+export function segmentSelectionErrors(ds, names) {
+    if (names === undefined)
+        return [];
+    if (!Array.isArray(names))
+        return ['segments must be an array of segment names.'];
+    const errors = [];
+    const seen = new Set();
+    const available = Object.keys(ds.segments ?? {});
+    for (const name of names) {
+        if (typeof name !== 'string' || !Object.hasOwn(ds.segments ?? {}, name)) {
+            errors.push(`Unknown segment "${String(name)}" on dataset "${ds.name}". Available: ${available.join(', ') || '(none)'}`);
+        }
+        else if (seen.has(name)) {
+            errors.push(`Segment "${name}" is selected more than once.`);
+        }
+        seen.add(String(name));
+    }
+    return errors;
+}
+/**
+ * The conditions a selection applies, as filters over dimension names. Order
+ * follows the selection, then each segment's authored filters.
+ */
+export function segmentFilters(ds, names) {
+    return (names ?? []).flatMap(name => ds.segments?.[name]?.filters ?? []);
+}

package/dist/utils/semantic-metadata-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-metadata-validation.d.ts","sourceRoot":"","sources":["../../src/utils/semantic-metadata-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAoBrB,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,gBAAgB,GACzB,IAAI,CA8BN;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACvD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,EAC1D,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAE7D,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC,GAC5D,IAAI,CAuDN"}
+{"version":3,"file":"semantic-metadata-validation.d.ts","sourceRoot":"","sources":["../../src/utils/semantic-metadata-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAsBrB,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,gBAAgB,GACzB,IAAI,CA8BN;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACvD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,EAC1D,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAE7D,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC,GAC5D,IAAI,CA4EN"}

package/dist/utils/semantic-metadata-validation.js

@@ -1,7 +1,8 @@
+import { SUPPORTED_TIME_GRAINS } from '../constants.js';
 const MAX_METADATA_ITEMS = 100;
 const MAX_METADATA_TEXT_BYTES = 4_096;
 const SENSITIVITIES = new Set(['public', 'internal', 'confidential', 'restricted']);
-const TIME_GRAINS = new Set(['day', 'week', 'month', 'quarter', 'year']);
+const TIME_GRAINS = new Set(SUPPORTED_TIME_GRAINS);
 const textEncoder = new TextEncoder();
 function fail(datasetName, location, message) {
     throw new Error(`Invalid dataset "${datasetName}": ${location} ${message}`);
@@ -90,6 +91,26 @@ export function validateDatasetAgentMetadata(datasetName, config) {
         if (dimensions.length === 0 && config.defaults.timeGrain === undefined) {
             fail(datasetName, 'defaults', 'must define dimensions or timeGrain.');
         }
+        if (config.defaults.timeGrain !== undefined && config.timeGrains !== undefined
+            && !config.timeGrains.includes(config.defaults.timeGrain)) {
+            fail(datasetName, 'defaults.timeGrain', 'is not one of the dataset timeGrains.');
+        }
+    }
+    if (config.timeGrains !== undefined) {
+        if (!Array.isArray(config.timeGrains) || config.timeGrains.length === 0) {
+            fail(datasetName, 'timeGrains', 'must be a non-empty array.');
+        }
+        if (config.timeKey === undefined) {
+            fail(datasetName, 'timeGrains', 'requires the dataset to define timeKey.');
+        }
+        if (new Set(config.timeGrains).size !== config.timeGrains.length) {
+            fail(datasetName, 'timeGrains', 'must not contain duplicates.');
+        }
+        for (const grain of config.timeGrains) {
+            if (!TIME_GRAINS.has(grain)) {
+                fail(datasetName, 'timeGrains', `contains unsupported time grain "${String(grain)}".`);
+            }
+        }
     }
     for (const [name, dimension] of Object.entries(config.dimensions)) {
         validateSemanticMetadata(datasetName, `dimensions.${name}`, dimension);

package/dist/utils/unsupported-contract-reasons.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Why portable execution excluded a contract surface.
+ *
+ * Decision 0005 excludes any surface a rebuilt catalog cannot reproduce
+ * byte-for-byte rather than approximating it. Every exclusion names one of
+ * these reasons, so an operator can tell which surface a deployment tripped on
+ * without parsing the message, and the corpus can assert that nothing is
+ * refused for an unnamed reason. The wire failure stays
+ * `HQ_SEMANTIC_UNSUPPORTED_CAPABILITY`; the reason travels beside it.
+ */
+export declare const UNSUPPORTED_CONTRACT_REASONS: {
+    /** A measure's fixed filter is not a field/operator/literal comparison. */
+    readonly measureFilterNotComparison: "HQ_PORTABLE_MEASURE_FILTER_NOT_COMPARISON";
+    /** A metric input or base metric is not an aggregate expression. */
+    readonly expressionNotAggregate: "HQ_PORTABLE_EXPRESSION_NOT_AGGREGATE";
+    /** No declared measure has the aggregation a metric expression names. */
+    readonly noMatchingMeasure: "HQ_PORTABLE_NO_MATCHING_MEASURE";
+    /** Two measures share an aggregation but emit different SQL. */
+    readonly ambiguousMeasureSql: "HQ_PORTABLE_AMBIGUOUS_MEASURE_SQL";
+    /** A derived metric arrived without the authored formula and aliases. */
+    readonly derivedMetricWithoutFormula: "HQ_PORTABLE_DERIVED_METRIC_WITHOUT_FORMULA";
+    /** A derived formula uses an operator, function, or shape with no builder. */
+    readonly unsupportedFormula: "HQ_PORTABLE_UNSUPPORTED_FORMULA";
+    /** A relationship names a dataset outside the supplied contract. */
+    readonly relationshipTargetMissing: "HQ_PORTABLE_RELATIONSHIP_TARGET_MISSING";
+    /** An invocation filter is not a field/operator/literal comparison. */
+    readonly queryFilterNotComparison: "HQ_PORTABLE_QUERY_FILTER_NOT_COMPARISON";
+    /** The invoked dataset is not part of the activated contract. */
+    readonly datasetNotActivated: "HQ_PORTABLE_DATASET_NOT_ACTIVATED";
+};
+export type UnsupportedContractReason = typeof UNSUPPORTED_CONTRACT_REASONS[keyof typeof UNSUPPORTED_CONTRACT_REASONS];
+//# sourceMappingURL=unsupported-contract-reasons.d.ts.map

package/dist/utils/unsupported-contract-reasons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsupported-contract-reasons.d.ts","sourceRoot":"","sources":["../../src/utils/unsupported-contract-reasons.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B;IACvC,2EAA2E;;IAE3E,oEAAoE;;IAEpE,yEAAyE;;IAEzE,gEAAgE;;IAEhE,yEAAyE;;IAEzE,8EAA8E;;IAE9E,oEAAoE;;IAEpE,uEAAuE;;IAEvE,iEAAiE;;CAEzD,CAAC;AAEX,MAAM,MAAM,yBAAyB,GACnC,OAAO,4BAA4B,CAAC,MAAM,OAAO,4BAA4B,CAAC,CAAC"}

package/dist/utils/unsupported-contract-reasons.js

@@ -0,0 +1,30 @@
+/**
+ * Why portable execution excluded a contract surface.
+ *
+ * Decision 0005 excludes any surface a rebuilt catalog cannot reproduce
+ * byte-for-byte rather than approximating it. Every exclusion names one of
+ * these reasons, so an operator can tell which surface a deployment tripped on
+ * without parsing the message, and the corpus can assert that nothing is
+ * refused for an unnamed reason. The wire failure stays
+ * `HQ_SEMANTIC_UNSUPPORTED_CAPABILITY`; the reason travels beside it.
+ */
+export const UNSUPPORTED_CONTRACT_REASONS = {
+    /** A measure's fixed filter is not a field/operator/literal comparison. */
+    measureFilterNotComparison: 'HQ_PORTABLE_MEASURE_FILTER_NOT_COMPARISON',
+    /** A metric input or base metric is not an aggregate expression. */
+    expressionNotAggregate: 'HQ_PORTABLE_EXPRESSION_NOT_AGGREGATE',
+    /** No declared measure has the aggregation a metric expression names. */
+    noMatchingMeasure: 'HQ_PORTABLE_NO_MATCHING_MEASURE',
+    /** Two measures share an aggregation but emit different SQL. */
+    ambiguousMeasureSql: 'HQ_PORTABLE_AMBIGUOUS_MEASURE_SQL',
+    /** A derived metric arrived without the authored formula and aliases. */
+    derivedMetricWithoutFormula: 'HQ_PORTABLE_DERIVED_METRIC_WITHOUT_FORMULA',
+    /** A derived formula uses an operator, function, or shape with no builder. */
+    unsupportedFormula: 'HQ_PORTABLE_UNSUPPORTED_FORMULA',
+    /** A relationship names a dataset outside the supplied contract. */
+    relationshipTargetMissing: 'HQ_PORTABLE_RELATIONSHIP_TARGET_MISSING',
+    /** An invocation filter is not a field/operator/literal comparison. */
+    queryFilterNotComparison: 'HQ_PORTABLE_QUERY_FILTER_NOT_COMPARISON',
+    /** The invoked dataset is not part of the activated contract. */
+    datasetNotActivated: 'HQ_PORTABLE_DATASET_NOT_ACTIVATED',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/datasets",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Code-first TypeScript semantic layer for ClickHouse datasets, metrics, multi-tenancy, and AI agents",
   "keywords": [
     "semantic-layer",
@@ -42,7 +42,7 @@
     "dist"
   ],
   "dependencies": {
-    "@hypequery/protocol": "^0.15.0",
+    "@hypequery/protocol": "^0.16.0",
     "@noble/hashes": "^1.8.0",
     "zod": "^3.22.4",
     "zod-to-json-schema": "^3.23.5"
@@ -60,7 +60,7 @@
     "typescript": "^5.7.3",
     "@vitest/coverage-v8": "^3.2.6",
     "vitest": "^3.2.6",
-    "@hypequery/protocol-conformance": "^0.12.0"
+    "@hypequery/protocol-conformance": "^0.13.0"
   },
   "repository": {
     "type": "git",