@hypequery/datasets 0.27.0 → 0.28.0

package/dist/client-contract/build-from-deployment.d.ts

@@ -0,0 +1,26 @@
+import { type PreparedProtocolClientContract, type ProtocolDeploymentContract, type ProtocolDeploymentDataset } from '@hypequery/protocol';
+import { type ClientContractProfile } from './deployment-profile.js';
+export interface BuildClientContractOptions {
+    /** Ceilings the host enforces; defaults mirror Python's ClientQueryProfile. */
+    readonly profile?: ClientContractProfile;
+    /**
+     * Trusted mount prefix, such as `/v1`: absolute, no trailing slash. Never a
+     * proxy or request header; the host knows how it is mounted.
+     */
+    readonly mountPath?: string;
+    /** Final route per published dataset, when the host serves it somewhere other than `endpoint.path`. */
+    readonly paths?: Readonly<Record<string, string>>;
+    /** `authorized` is a caller's view, narrowed by `include`. */
+    readonly view?: 'build' | 'authorized';
+    /** Which published datasets to advertise; every one by default. */
+    readonly include?: (dataset: ProtocolDeploymentDataset) => boolean;
+}
+/**
+ * The client contract for a deployment's published datasets: typed fields,
+ * routes and schema hashes `hypequery generate:client` turns into React types
+ * and a route manifest. Pure: no network, no execution. Datasets without an
+ * endpoint policy (relationship targets) are not advertised, and neither are
+ * relationship fields yet.
+ */
+export declare function buildClientContract(contract: ProtocolDeploymentContract, options?: BuildClientContractOptions): PreparedProtocolClientContract;
+//# sourceMappingURL=build-from-deployment.d.ts.map

package/dist/client-contract/build-from-deployment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-from-deployment.d.ts","sourceRoot":"","sources":["../../src/client-contract/build-from-deployment.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,8BAA8B,EACnC,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC/B,MAAM,qBAAqB,CAAC;AAI7B,OAAO,EAAmD,KAAK,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAEtH,MAAM,WAAW,0BAA0B;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,uGAAuG;IACvG,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,YAAY,CAAC;IACvC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,OAAO,CAAC;CACpE;AA2DD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,0BAA0B,EACpC,OAAO,GAAE,0BAA+B,GACvC,8BAA8B,CAchC"}

package/dist/client-contract/build-from-deployment.js

@@ -0,0 +1,76 @@
+import { prepareProtocolClientContract, } from '@hypequery/protocol';
+import { PORTABLE_TIME_GRAINS } from '../utils/portable-grains.js';
+import { endpointAnnotations } from './deployment-annotations.js';
+import { publicFields } from './deployment-fields.js';
+import { clientQueryLimits, resolveClientContractProfile } from './deployment-profile.js';
+function endpointPath(dataset, options) {
+    const path = options.paths?.[dataset.name] ?? dataset.endpoint?.path;
+    if (path === undefined || !path.startsWith('/')) {
+        throw new Error(`Client export: dataset "${dataset.name}" needs an absolute endpoint path.`);
+    }
+    return (options.mountPath ?? '') + path;
+}
+function endpointDescriptor(dataset, options, profile) {
+    const { dimensions, measures, filters } = publicFields(dataset);
+    // Rows carry the time bucket as `period`, so a field of that name would collide.
+    if (dataset.timeField !== undefined && (Object.hasOwn(dimensions, 'period') || Object.hasOwn(measures, 'period'))) {
+        throw new Error(`Client export: dataset "${dataset.name}" has a field named "period", which its time bucket uses. Rename it.`);
+    }
+    const limits = clientQueryLimits(dataset, profile);
+    // An endpoint's default selection is the base measures it can serve, capped
+    // at the dataset's own measure limit so a dataset with more base measures
+    // than it may select at once still exports. The selection is hashed, so a
+    // host budget never trims it: a budget-only change must not move the schema
+    // hash a generated client pins. A budget too small for it is refused.
+    const defaultMeasures = dataset.measures
+        .filter(measure => !('kind' in measure) && Object.hasOwn(measures, measure.name))
+        .map(measure => measure.name)
+        .slice(0, dataset.limits?.maxMeasures);
+    if (defaultMeasures.length > limits.maxMeasures) {
+        throw new Error(`Client export: dataset "${dataset.name}" selects ${defaultMeasures.length} measures by default, `
+            + `more than the host's measure budget of ${limits.maxMeasures}. Raise the budget, or set the dataset's limits.maxMeasures.`);
+    }
+    const annotations = endpointAnnotations(dataset, Object.keys(dimensions), Object.keys(measures));
+    return {
+        id: dataset.name,
+        kind: 'dataset',
+        dataset: dataset.name,
+        path: endpointPath(dataset, options),
+        dimensions,
+        measures,
+        filters,
+        metadata: true,
+        limits,
+        // Deployment contract 2 carries day-and-longer grains only.
+        time: dataset.timeField === undefined ? null : {
+            grains: [...PORTABLE_TIME_GRAINS],
+            defaultTimezone: profile.defaultTimezone,
+            timezone: true,
+            periodFormat: 'calendar-date-or-local-datetime-v1',
+        },
+        defaultMeasures,
+        ...(annotations ? { annotations } : {}),
+    };
+}
+/**
+ * The client contract for a deployment's published datasets: typed fields,
+ * routes and schema hashes `hypequery generate:client` turns into React types
+ * and a route manifest. Pure: no network, no execution. Datasets without an
+ * endpoint policy (relationship targets) are not advertised, and neither are
+ * relationship fields yet.
+ */
+export function buildClientContract(contract, options = {}) {
+    const { mountPath } = options;
+    if (mountPath && (!mountPath.startsWith('/') || mountPath.endsWith('/'))) {
+        throw new Error('Client export: mountPath must be empty or an absolute path without a trailing slash.');
+    }
+    const profile = resolveClientContractProfile(options.profile);
+    const published = contract.datasets
+        .filter(dataset => dataset.endpoint !== undefined && (options.include?.(dataset) ?? true));
+    return prepareProtocolClientContract({
+        kind: 'hypequery-client-contract',
+        version: 1,
+        view: options.view ?? 'build',
+        endpoints: published.map(dataset => endpointDescriptor(dataset, options, profile)),
+    });
+}

package/dist/client-contract/deployment-annotations.d.ts

@@ -0,0 +1,6 @@
+import type { ClientEndpointAnnotations, ProtocolDeploymentDataset } from '@hypequery/protocol';
+/** Fold whitespace runs so multi-line definitions stay advertisable; omit blank text. */
+export declare function annotationText(value: string | undefined): string | undefined;
+/** Group text from the dataset; field text for each advertised dimension and measure. */
+export declare function endpointAnnotations(dataset: ProtocolDeploymentDataset, dimensions: readonly string[], measures: readonly string[]): ClientEndpointAnnotations | undefined;
+//# sourceMappingURL=deployment-annotations.d.ts.map

package/dist/client-contract/deployment-annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-annotations.d.ts","sourceRoot":"","sources":["../../src/client-contract/deployment-annotations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,yBAAyB,EAEzB,yBAAyB,EAC1B,MAAM,qBAAqB,CAAC;AAE7B,yFAAyF;AACzF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAI5E;AASD,yFAAyF;AACzF,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,yBAAyB,EAClC,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,yBAAyB,GAAG,SAAS,CAgBvC"}

package/dist/client-contract/deployment-annotations.js

@@ -0,0 +1,32 @@
+/** Fold whitespace runs so multi-line definitions stay advertisable; omit blank text. */
+export function annotationText(value) {
+    if (value === undefined)
+        return undefined;
+    const folded = value.split(/\s+/).filter(Boolean).join(' ');
+    return folded.trim() ? folded : undefined;
+}
+function fieldAnnotation(definition) {
+    const label = annotationText(definition.label);
+    const description = annotationText(definition.description);
+    if (label === undefined && description === undefined)
+        return undefined;
+    return { ...(label !== undefined ? { label } : {}), ...(description !== undefined ? { description } : {}) };
+}
+/** Group text from the dataset; field text for each advertised dimension and measure. */
+export function endpointAnnotations(dataset, dimensions, measures) {
+    const advertised = [
+        ...dataset.dimensions.filter(item => dimensions.includes(item.name)),
+        ...dataset.measures.filter(item => measures.includes(item.name)),
+    ];
+    // Object.fromEntries defines each name as an own key, `__proto__` included.
+    const fields = Object.fromEntries(advertised.flatMap(definition => {
+        const node = fieldAnnotation(definition);
+        return node ? [[definition.name, node]] : [];
+    }));
+    const description = annotationText(dataset.description);
+    const result = {
+        ...(description !== undefined ? { description } : {}),
+        ...(Object.keys(fields).length ? { fields } : {}),
+    };
+    return Object.keys(result).length ? result : undefined;
+}

package/dist/client-contract/deployment-fields.d.ts

@@ -0,0 +1,19 @@
+import type { ClientDimension, ClientFilter, ClientMeasure, ProtocolDatasetDimension, ProtocolDatasetFilter, ProtocolDeploymentDataset, ProtocolDeploymentMeasure } from '@hypequery/protocol';
+/** Local fields have unknown nullability; the client contract says so rather than guess. */
+export declare function dimensionDescriptor(dimension: ProtocolDatasetDimension): ClientDimension;
+/** `having` compares numbers, so ordered aggregations over non-numeric fields can't take it. */
+export declare function measureDescriptor(dataset: ProtocolDeploymentDataset, measure: ProtocolDeploymentMeasure): ClientMeasure;
+export declare function filterDescriptor(dimension: ProtocolDatasetDimension, filter: ProtocolDatasetFilter): ClientFilter | null;
+/** Tenant identities come from the caller's credential, never from request predicates. */
+export declare function requestFilter(dataset: ProtocolDeploymentDataset, dimension: ProtocolDatasetDimension): boolean;
+/**
+ * The fields one dataset endpoint advertises. Relationship fields are not
+ * exported yet, matching Python's default (`related=()`), so a measure whose
+ * fixed filters cross a relationship is left out rather than advertised.
+ */
+export declare function publicFields(dataset: ProtocolDeploymentDataset): {
+    dimensions: Record<string, ClientDimension>;
+    measures: Record<string, ClientMeasure>;
+    filters: Record<string, ClientFilter>;
+};
+//# sourceMappingURL=deployment-fields.d.ts.map

package/dist/client-contract/deployment-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-fields.d.ts","sourceRoot":"","sources":["../../src/client-contract/deployment-fields.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,aAAa,EACb,wBAAwB,EACxB,qBAAqB,EACrB,yBAAyB,EACzB,yBAAyB,EAE1B,MAAM,qBAAqB,CAAC;AAQ7B,4FAA4F;AAC5F,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,wBAAwB,GAAG,eAAe,CAQxF;AAED,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,yBAAyB,EAAE,OAAO,EAAE,yBAAyB,GAAG,aAAa,CAUvH;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,wBAAwB,EAAE,MAAM,EAAE,qBAAqB,GAAG,YAAY,GAAG,IAAI,CAKxH;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,OAAO,EAAE,yBAAyB,EAAE,SAAS,EAAE,wBAAwB,GAAG,OAAO,CAI9G;AAmCD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,yBAAyB,GAAG;IAChE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC5C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACvC,CAkBA"}

package/dist/client-contract/deployment-fields.js

@@ -0,0 +1,103 @@
+// As Python's builder: booleans compare by equality and membership only.
+const BOOLEAN_OPERATORS = new Set(['eq', 'neq', 'in', 'notIn']);
+const ORDERED_AGGREGATIONS = new Set(['min', 'max', 'argMin', 'argMax']);
+/** Stored states whose merged value is the stored value itself, which may not be a number. */
+const ORDERED_STATES = new Set(['min', 'max', 'any', 'anyLast']);
+/** Local fields have unknown nullability; the client contract says so rather than guess. */
+export function dimensionDescriptor(dimension) {
+    return {
+        type: dimension.type,
+        wireType: dimension.type === 'number' ? 'number-or-string' : dimension.type === 'boolean' ? 'boolean' : 'string',
+        nullable: 'unknown',
+        groupable: dimension.groupable,
+        orderable: dimension.groupable,
+    };
+}
+/** `having` compares numbers, so ordered aggregations over non-numeric fields can't take it. */
+export function measureDescriptor(dataset, measure) {
+    if ('kind' in measure)
+        return { wireType: 'string', nullable: true, having: true };
+    if (measure.aggregation === 'merge') {
+        return { wireType: 'string', nullable: true, having: !ORDERED_STATES.has(String(measure.stateFunction)) };
+    }
+    if (!ORDERED_AGGREGATIONS.has(measure.aggregation)) {
+        return { wireType: 'string', nullable: true, having: true };
+    }
+    const dimension = dataset.dimensions.find(item => item.name === measure.field);
+    return { wireType: 'string', nullable: true, having: dimension?.type === 'number' };
+}
+export function filterDescriptor(dimension, filter) {
+    const operators = [...new Set(filter.operators.filter(operator => dimension.type === 'boolean'
+            ? BOOLEAN_OPERATORS.has(operator)
+            : dimension.type !== 'number' || operator !== 'like'))].sort();
+    return operators.length ? { type: dimension.type, operators } : null;
+}
+/** Tenant identities come from the caller's credential, never from request predicates. */
+export function requestFilter(dataset, dimension) {
+    if (dataset.tenant.kind !== 'required')
+        return true;
+    const column = dimension.source.kind === 'column' ? dimension.source.column : dimension.name;
+    return column !== dataset.tenant.field;
+}
+function expressionFields(expression) {
+    switch (expression.kind) {
+        case 'reference': return [expression.name];
+        case 'aggregate': return [expression.field];
+        case 'binary': return [...expressionFields(expression.left), ...expressionFields(expression.right)];
+        case 'call': return expression.args.flatMap(expressionFields);
+        case 'comparison': return 'right' in expression
+            ? [...expressionFields(expression.left), ...expressionFields(expression.right)]
+            : expressionFields(expression.left);
+        case 'logical': return 'operands' in expression ? expression.operands.flatMap(expressionFields) : expressionFields(expression.operand);
+        default: return [];
+    }
+}
+/** The fields a measure's fixed filters read, through any derived dependencies. */
+function measureFilterFields(dataset, name) {
+    const filters = new Map(dataset.filters.map(filter => [filter.name, filter.field]));
+    const measures = new Map(dataset.measures.map(measure => [measure.name, measure]));
+    const pending = [name];
+    const seen = new Set();
+    const fields = [];
+    while (pending.length) {
+        const current = pending.pop();
+        if (seen.has(current))
+            continue;
+        seen.add(current);
+        const measure = measures.get(current);
+        if (measure === undefined)
+            continue;
+        if ('kind' in measure)
+            pending.push(...measure.uses.map(use => use.measure));
+        else
+            for (const field of measure.filters.flatMap(expressionFields))
+                fields.push(filters.get(field) ?? field);
+    }
+    return fields;
+}
+/**
+ * The fields one dataset endpoint advertises. Relationship fields are not
+ * exported yet, matching Python's default (`related=()`), so a measure whose
+ * fixed filters cross a relationship is left out rather than advertised.
+ */
+export function publicFields(dataset) {
+    const dimensions = Object.fromEntries(dataset.dimensions.map(dimension => [dimension.name, dimensionDescriptor(dimension)]));
+    const measures = Object.fromEntries(dataset.measures
+        .filter(measure => measureFilterFields(dataset, measure.name).every(field => !field.includes('.')))
+        .map(measure => [measure.name, measureDescriptor(dataset, measure)]));
+    // Built with Object.fromEntries, as above: assigning a key such as
+    // `__proto__` would set the prototype instead of adding an entry.
+    const filters = Object.fromEntries(dataset.filters.flatMap((filter) => {
+        if (filter.field.includes('.'))
+            return [];
+        const dimension = dataset.dimensions.find(item => item.name === filter.field);
+        if (dimension === undefined) {
+            throw new Error(`Client export: filter "${dataset.name}.${filter.name}" references unknown dimension "${filter.field}".`);
+        }
+        if (!requestFilter(dataset, dimension))
+            return [];
+        const descriptor = filterDescriptor(dimension, filter);
+        return descriptor ? [[filter.name, descriptor]] : [];
+    }));
+    return { dimensions, measures, filters };
+}

package/dist/client-contract/deployment-profile.d.ts

@@ -0,0 +1,22 @@
+import type { ClientQueryLimits, ProtocolDeploymentDataset } from '@hypequery/protocol';
+/**
+ * Trusted host ceilings for an exported client contract. The host must enforce
+ * at least these bounds; the export only ever narrows them by each dataset's
+ * own limits and endpoint `maxLimit`. Defaults mirror Python's ClientQueryProfile.
+ */
+export interface ClientContractProfile {
+    readonly defaultLimit?: number;
+    readonly maxLimit?: number;
+    readonly maxOffset?: number;
+    readonly maxDimensions?: number;
+    readonly maxMeasures?: number;
+    readonly maxPredicates?: number;
+    readonly maxOrderBy?: number;
+    readonly maxFilterValues?: number;
+    /** IANA zone used when a request names none. */
+    readonly defaultTimezone?: string;
+}
+export declare function resolveClientContractProfile(profile?: ClientContractProfile): Required<ClientContractProfile>;
+/** Intersect the profile with the dataset's own ceilings; never widen them. */
+export declare function clientQueryLimits(dataset: ProtocolDeploymentDataset, profile: Required<ClientContractProfile>): ClientQueryLimits;
+//# sourceMappingURL=deployment-profile.d.ts.map

package/dist/client-contract/deployment-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-profile.d.ts","sourceRoot":"","sources":["../../src/client-contract/deployment-profile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAExF;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,gDAAgD;IAChD,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAcD,wBAAgB,4BAA4B,CAAC,OAAO,GAAE,qBAA0B,GAAG,QAAQ,CAAC,qBAAqB,CAAC,CAEjH;AAID,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,yBAAyB,EAAE,OAAO,EAAE,QAAQ,CAAC,qBAAqB,CAAC,GAAG,iBAAiB,CAYjI"}

package/dist/client-contract/deployment-profile.js

@@ -0,0 +1,29 @@
+const DEFAULT_PROFILE = {
+    defaultLimit: 1000,
+    maxLimit: 1000,
+    maxOffset: 1_000_000,
+    maxDimensions: 100,
+    maxMeasures: 100,
+    maxPredicates: 100,
+    maxOrderBy: 100,
+    maxFilterValues: 10_000,
+    defaultTimezone: 'UTC',
+};
+export function resolveClientContractProfile(profile = {}) {
+    return { ...DEFAULT_PROFILE, ...Object.fromEntries(Object.entries(profile).filter(([, value]) => value !== undefined)) };
+}
+const narrower = (ceiling, value) => value === undefined ? ceiling : Math.min(ceiling, value);
+/** Intersect the profile with the dataset's own ceilings; never widen them. */
+export function clientQueryLimits(dataset, profile) {
+    const maxLimit = narrower(narrower(profile.maxLimit, dataset.limits?.maxResultSize), dataset.endpoint?.maxLimit);
+    return {
+        defaultLimit: Math.min(profile.defaultLimit, maxLimit),
+        maxLimit,
+        maxOffset: profile.maxOffset,
+        maxDimensions: narrower(profile.maxDimensions, dataset.limits?.maxDimensions),
+        maxMeasures: narrower(profile.maxMeasures, dataset.limits?.maxMeasures),
+        maxPredicates: narrower(profile.maxPredicates, dataset.limits?.maxFilters),
+        maxOrderBy: profile.maxOrderBy,
+        maxFilterValues: profile.maxFilterValues,
+    };
+}

package/dist/client-contract/query-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-schema.d.ts","sourceRoot":"","sources":["../../src/client-contract/query-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,sBAAsB,EAAE,KAAK,sBAAsB,EACzD,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAK,KAAK,UAAU,EAAE,MAAM,KAAK,CAAC;AACzC,OAAO,EAAwB,KAAK,6BAA6B,EAAE,MAAM,6BAA6B,CAAC;AACvG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,UAAU,CAAC;CACrC;AACD,MAAM,WAAW,0BAA2B,SAAQ,6BAA6B;IAC/E,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;CACpE;AAgED;;;GAGG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,0BAA0B,CAe1F"}
+{"version":3,"file":"query-schema.d.ts","sourceRoot":"","sources":["../../src/client-contract/query-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,sBAAsB,EAAE,KAAK,sBAAsB,EACzD,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAK,KAAK,UAAU,EAAE,MAAM,KAAK,CAAC;AACzC,OAAO,EAAwB,KAAK,6BAA6B,EAAE,MAAM,6BAA6B,CAAC;AACvG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,UAAU,CAAC;CACrC;AACD,MAAM,WAAW,0BAA2B,SAAQ,6BAA6B;IAC/E,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;CACpE;AAiED;;;GAGG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,0BAA0B,CAe1F"}

package/dist/client-contract/query-schema.js

@@ -1,6 +1,7 @@
-import { validateProtocolClientContract, validateProtocolClientQuery, } from '@hypequery/protocol';
+import { ProtocolClientContractError, validateProtocolClientContract, validateProtocolClientQuery, } from '@hypequery/protocol';
 import { z } from 'zod';
 import { toSemanticJsonSchema } from '../semantic-query-schema.js';
+import { pointerSegments } from '../utils/json-pointer-segments.js';
 function union(schemas) {
     return schemas.length === 0 ? z.never() : schemas.length === 1 ? schemas[0]
         : z.union(schemas);
@@ -60,8 +61,9 @@ function endpointSchema(contract, endpoint, transport) {
         try {
             validateProtocolClientQuery(contract, endpoint.id, input, transport);
         }
-        catch {
-            context.addIssue({ code: z.ZodIssueCode.custom, message: 'Invalid client query.' });
+        catch (error) {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: 'Invalid client query.',
+                path: error instanceof ProtocolClientContractError ? pointerSegments(error.path) : [] });
             return z.NEVER;
         }
         return input;

package/dist/index.d.ts

@@ -28,6 +28,9 @@ export type { BuildProtocolDeploymentContractOptions } from './protocol-deployme
 export { rehydrateProtocolDeploymentContract } from './protocol-rehydrate.js';
 export type { BuildProtocolDatasetContractOptions } from './protocol-adapter.js';
 export { publishToCloud } from './cloud-publishing.js';
+export { buildClientContract } from './client-contract/build-from-deployment.js';
+export type { BuildClientContractOptions } from './client-contract/build-from-deployment.js';
+export type { ClientContractProfile } from './client-contract/deployment-profile.js';
 export type { CloudPublishingOptions } from './cloud-publishing.js';
 export { createPortableSemanticExecutor, createPortableSemanticRuntime, PortableExecutionBudgetError, PortableExecutionTenantError, PortableExecutionUnsupportedError, } from './portable-executor.js';
 export type { PortableSemanticBudget, PortableSemanticRuntime, PortableDatasetCompilation, PortableSemanticExecutionInput, PortableSemanticExecutorOptions, } from './portable-executor.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AAGxC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EACV,yBAAyB,EACzB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,GAAG,EAAE,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAC7D,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,GAC5D,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,yBAAyB,EAAE,KAAK,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAG9G,OAAO,EACL,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAC/B,UAAU,EAAE,QAAQ,EACpB,KAAK,EAAE,KAAK,EAAE,IAAI,GACnB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EACzB,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAChC,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,IAAI,EACT,MAAM,EAAE,KAAK,GACd,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAGtD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,8BAA8B,EAAE,gCAAgC,EAAE,MAAM,cAAc,CAAC;AACvI,OAAO,EAAE,+BAA+B,EAAE,MAAM,gCAAgC,CAAC;AACjF,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,+BAA+B,EAC/B,4BAA4B,EAC5B,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,mBAAmB,EACnB,2BAA2B,EAC3B,6BAA6B,EAC7B,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,wBAAwB,EACxB,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,gCAAgC,GACjC,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,YAAY,EACZ,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,yBAAyB,EACzB,4BAA4B,EAC5B,+BAA+B,GAChC,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,iBAAiB,EACjB,gCAAgC,EAChC,yBAAyB,GAC1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,+BAA+B,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,YAAY,EAAE,sCAAsC,EAAE,MAAM,kCAAkC,CAAC;AAC/F,OAAO,EAAE,mCAAmC,EAAE,MAAM,yBAAyB,CAAC;AAC9E,YAAY,EAAE,mCAAmC,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAGpE,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC7B,4BAA4B,EAC5B,4BAA4B,EAC5B,iCAAiC,GAClC,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,EAC1B,8BAA8B,EAC9B,+BAA+B,GAChC,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,GAC/B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,gBAAgB,EAChB,gCAAgC,EAChC,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAKvB,uGAAuG;AACvG,eAAO,MAAM,oBAAoB,qCAA+B,CAAC;AACjE,uGAAuG;AACvG,eAAO,MAAM,aAAa,8BAAwB,CAAC;AACnD,uGAAuG;AACvG,eAAO,MAAM,YAAY,6BAAuB,CAAC;AACjD,uGAAuG;AACvG,eAAO,MAAM,UAAU,2BAAqB,CAAC;AAC7C,uGAAuG;AACvG,eAAO,MAAM,uBAAuB,wCAAkC,CAAC;AACvE,uGAAuG;AACvG,eAAO,MAAM,sBAAsB,uCAAiC,CAAC;AACrE,uGAAuG;AACvG,eAAO,MAAM,kCAAkC,mDAA6C,CAAC;AAC7F,uGAAuG;AACvG,eAAO,MAAM,oBAAoB,qCAA+B,CAAC;AACjE,uGAAuG;AACvG,eAAO,MAAM,oCAAoC;;;;;;;EAA+C,CAAC;AACjG,uGAAuG;AACvG,eAAO,MAAM,+BAA+B,gDAA0C,CAAC;AACvF,uGAAuG;AACvG,eAAO,MAAM,8BAA8B,+CAAyC,CAAC;AACrF,uGAAuG;AACvG,eAAO,MAAM,mBAAmB,oCAA8B,CAAC;AAC/D,uGAAuG;AACvG,eAAO,MAAM,0BAA0B,2CAAqC,CAAC;AAC7E,uGAAuG;AACvG,MAAM,MAAM,0BAA0B,GAAG,OAAO,CAAC,0BAA0B,CAAC;AAC5E,uGAAuG;AACvG,eAAO,MAAM,+BAA+B,gDAA0C,CAAC;AACvF,uGAAuG;AACvG,MAAM,MAAM,6BAA6B,GAAG,OAAO,CAAC,6BAA6B,CAAC;AAClF,uGAAuG;AACvG,MAAM,MAAM,0BAA0B,GAAG,OAAO,CAAC,0BAA0B,CAAC;AAC5E,uGAAuG;AACvG,MAAM,MAAM,yBAAyB,GAAG,OAAO,CAAC,yBAAyB,CAAC;AAI1E,YAAY,EACV,2BAA2B,EAC3B,yBAAyB,EACzB,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,2BAA2B,EAC3B,UAAU,EACV,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,YAAY,EAAE,aAAa,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAG/E,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACzE,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,4BAA4B,CAAC;AAIpC,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC5E,YAAY,EACV,QAAQ,EACR,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,uBAAuB,EACvB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGxE,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,6BAA6B,EAC7B,wBAAwB,GACzB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAGpE,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAGhG,OAAO,EACL,eAAe,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,6BAA6B,EAAE,qBAAqB,GAC5H,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EACV,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,sBAAsB,EACtB,wBAAwB,EACxB,wBAAwB,EACxB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,uBAAuB,EACvB,yBAAyB,EACzB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,wBAAwB,EACxB,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,EACjB,yBAAyB,EACzB,aAAa,EACb,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,EACrB,0BAA0B,EAC1B,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,qBAAqB,EACrB,UAAU,EACV,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,SAAS,EACT,YAAY,EACZ,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,kBAAkB,EAAE,wBAAwB,EAAE,6BAA6B,GAC5E,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,8BAA8B,EAAE,MAAM,6BAA6B,CAAC;AAC7E,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AACvH,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -33,6 +33,7 @@ export { buildProtocolDeploymentContract } from './protocol-deployment-adapter.j
 export { assertDeployable } from './utils/deployable-formulas.js';
 export { rehydrateProtocolDeploymentContract } from './protocol-rehydrate.js';
 export { publishToCloud } from './cloud-publishing.js';
+export { buildClientContract } from './client-contract/build-from-deployment.js';
 // Portable native execution of a semantic invocation (decision 0005).
 export { createPortableSemanticExecutor, createPortableSemanticRuntime, PortableExecutionBudgetError, PortableExecutionTenantError, PortableExecutionUnsupportedError, } from './portable-executor.js';
 // SQL portability compiler (R1A-07)

package/dist/query-planner.js

@@ -18,7 +18,7 @@ export function resolveDimensionExpression(ds, dimensionName, joinCtx) {
         assertNoRawSqlUnderJoins('dimension', dimensionName, definition.sql, joinCtx);
         return definition.sql;
     }
-    return qualifyBaseColumn(joinCtx, definition?.column ?? dimensionName);
+    return qualifyBaseColumn(joinCtx, definition?.column ?? dimensionName, ds.source);
 }
 export function resolveFilterField(ds, filterField, joinCtx) {
     if (joinCtx && isQualifiedField(filterField)) {

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

@@ -1 +1 @@
-{"version":3,"file":"relationship-check.d.ts","sourceRoot":"","sources":["../src/relationship-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAyB,KAAK,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAInG,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,mCAAmC,CAAC;AAE3C,YAAY,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAE9E,MAAM,WAAW,yBAAyB;IACxC,uDAAuD;IACvD,YAAY,EAAE,wBAAwB,CAAC;IACvC;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,6DAA6D;IAC7D,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,EAAE,EAAE,OAAO,CAAC;IACZ,4CAA4C;IAC5C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,oBAAoB,EAAE,CAAC;CAChC;AAKD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,kBAAkB,EACtB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAkCnC"}
+{"version":3,"file":"relationship-check.d.ts","sourceRoot":"","sources":["../src/relationship-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAyB,KAAK,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAInG,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,mCAAmC,CAAC;AAE3C,YAAY,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAE9E,MAAM,WAAW,yBAAyB;IACxC,uDAAuD;IACvD,YAAY,EAAE,wBAAwB,CAAC;IACvC;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,6DAA6D;IAC7D,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,EAAE,EAAE,OAAO,CAAC;IACZ,4CAA4C;IAC5C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,oBAAoB,EAAE,CAAC;CAChC;AAKD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,kBAAkB,EACtB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAuCnC"}

package/dist/relationship-check.js

@@ -18,7 +18,7 @@
  */
 import { datasetSourceBuilder } from './utils/dataset-source.js';
 import { toQueryBuilderFactory } from './query-builder-protocol.js';
-import { validateTenantRuntime } from './utils/tenant-runtime.js';
+import { joinsWithinTenant, validateTenantRuntime } from './utils/tenant-runtime.js';
 import { applyRowScope, datasetRowScope } from './utils/row-scope.js';
 import { resolveDatasetSqlDialect } from './utils/dataset-sql-dialect.js';
 import { listToOneRelationships, readCount, relationshipKeyIssue, } from './utils/relationship-key-check.js';
@@ -40,13 +40,18 @@ export async function checkRelationships(ds, options) {
         if (tenantError) {
             throw new Error(`Cannot check relationship "${entry.relationship}": ${tenantError}`);
         }
+        // Joins then match keys within each tenant, so a key reused by another
+        // tenant is not a duplicate; count (key, tenant) pairs instead.
+        const distinctColumns = joinsWithinTenant(ds, entry.target, options.context)
+            ? [...(entry.columns ?? [entry.column]), entry.target.tenantKey]
+            : entry.columns;
         let qb = datasetSourceBuilder(factory, entry.target)
             .count(entry.column, ROWS_ALIAS)
-            .countDistinct(entry.columns ? dialect.packRow(entry.columns) : entry.column, KEYS_ALIAS);
-        if (entry.columns) {
-            for (const column of entry.columns)
-                qb = qb.where(column, 'isNotNull', undefined);
-        }
+            .countDistinct(distinctColumns ? dialect.packRow(distinctColumns) : entry.column, KEYS_ALIAS);
+        // count() skips a NULL key but a packed row counts it, so filter NULL keys
+        // out of both: under a multi-tenant scope one would cancel a duplicate.
+        for (const column of entry.columns ?? [entry.column])
+            qb = qb.where(column, 'isNotNull', undefined);
         qb = applyRowScope(qb, datasetRowScope(entry.target, options.context));
         const [row] = await qb.execute({
             abortSignal: options.context?.abortSignal,

package/dist/utils/clickhouse-dataset-sql-dialect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clickhouse-dataset-sql-dialect.d.ts","sourceRoot":"","sources":["../../src/utils/clickhouse-dataset-sql-dialect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA4B,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAwClG,4EAA4E;AAC5E,eAAO,MAAM,2BAA2B,EAAE,sBAiHP,CAAC"}
+{"version":3,"file":"clickhouse-dataset-sql-dialect.d.ts","sourceRoot":"","sources":["../../src/utils/clickhouse-dataset-sql-dialect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA4B,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAwClG,4EAA4E;AAC5E,eAAO,MAAM,2BAA2B,EAAE,sBAqHP,CAAC"}

package/dist/utils/clickhouse-dataset-sql-dialect.js

@@ -129,6 +129,11 @@ export const clickhouseDatasetSqlDialect = Object.freeze({
         const symbol = BINARY_OPERATORS[operator];
         if (!symbol)
             throw new Error('Formula contains an unsupported binary operator.');
+        // Decimal division keeps the dividend's scale and truncates, so the average
+        // of 2.00 over 3 rows would be 0.66 before any ROUND. Integer division already
+        // returns Float64; a Float64 dividend makes decimals match.
+        if (operator === 'divide')
+            return `(toFloat64(${left}) ${symbol} ${right})`;
         return `(${left} ${symbol} ${right})`;
     },
     formulaFunction(name, args) {

package/dist/utils/json-pointer-segments.d.ts

@@ -0,0 +1,7 @@
+/**
+ * An RFC 6901 pointer as path segments, item indexes as numbers, for zod
+ * issues and wire `issues[].path`. Client-contract member names are
+ * identifiers, so an all-digit segment is always an index.
+ */
+export declare function pointerSegments(pointer: string): (string | number)[];
+//# sourceMappingURL=json-pointer-segments.d.ts.map

package/dist/utils/json-pointer-segments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-pointer-segments.d.ts","sourceRoot":"","sources":["../../src/utils/json-pointer-segments.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAGpE"}

package/dist/utils/json-pointer-segments.js

@@ -0,0 +1,9 @@
+/**
+ * An RFC 6901 pointer as path segments, item indexes as numbers, for zod
+ * issues and wire `issues[].path`. Client-contract member names are
+ * identifiers, so an all-digit segment is always an index.
+ */
+export function pointerSegments(pointer) {
+    return pointer.split('/').slice(1)
+        .map(part => /^\d+$/.test(part) ? Number(part) : part.replaceAll('~1', '/').replaceAll('~0', '~'));
+}

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

@@ -52,8 +52,13 @@ type QueryLike = Pick<DatasetQuery & MetricQuery, 'dimensions' | 'filters' | 'or
  * here is skipped defensively.
  */
 export declare function buildRelationshipBuilderContext(ds: AnyDatasetInstance, query: QueryLike, context?: ExecutionContext, dialect?: DatasetSqlDialectRules): RelationshipBuilderContext | undefined;
-/** Qualifies a base physical column with the base source when joins are active. */
-export declare function qualifyBaseColumn(ctx: RelationshipBuilderContext | undefined, column: string): string;
+/**
+ * Qualifies a base physical column with the base source. Always qualified:
+ * ClickHouse resolves an output alias before a column of the same name, so a
+ * bare `status` could read a dimension aliased `status`, and a bare `amount`
+ * inside another aggregate could read a measure aliased `amount`.
+ */
+export declare function qualifyBaseColumn(ctx: RelationshipBuilderContext | undefined, column: string, source: string): string;
 /**
  * Resolves a relationship-qualified field to a null-guarded SQL expression:
  * the target column when the join matched, NULL otherwise

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":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAGxE;;;;;;;;;;;;;;;;GAgBG;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,EAAuC,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAG7F,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IAClC,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,4EAA4E;IAC5E,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,uFAAuF;IACvF,KAAK,EAAE,OAAO,CAAC;CAChB;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;IACrD,oEAAoE;IACpE,OAAO,EAAE,sBAAsB,CAAC;CACjC;AAED,KAAK,SAAS,GAAG,IAAI,CAAC,YAAY,GAAG,WAAW,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;AAEzH;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,gBAAgB,EAC1B,OAAO,GAAE,sBAAoD,GAC5D,0BAA0B,GAAG,SAAS,CA+CxC;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,0BAA0B,GAAG,SAAS,EAC3C,MAAM,EAAE,MAAM,GACb,MAAM,CAER;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,0BAA0B,GAC9B,MAAM,CAaR;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,GAAG,EAAE,0BAA0B,GAAG,SAAS,GAC1C,gBAAgB,CAoClB"}
+{"version":3,"file":"relationship-builder-plan.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-builder-plan.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAIxE;;;;;;;;;;;;;;;;GAgBG;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,EAAuC,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAG7F,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IAClC,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,4EAA4E;IAC5E,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,uFAAuF;IACvF,KAAK,EAAE,OAAO,CAAC;CAChB;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;IACrD,oEAAoE;IACpE,OAAO,EAAE,sBAAsB,CAAC;CACjC;AAED,KAAK,SAAS,GAAG,IAAI,CAAC,YAAY,GAAG,WAAW,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;AAEzH;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,gBAAgB,EAC1B,OAAO,GAAE,sBAAoD,GAC5D,0BAA0B,GAAG,SAAS,CAmDxC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,0BAA0B,GAAG,SAAS,EAC3C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,MAAM,CAER;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,0BAA0B,GAC9B,MAAM,CAaR;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,GAAG,EAAE,0BAA0B,GAAG,SAAS,GAC1C,gBAAgB,CAoClB"}

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

@@ -2,6 +2,7 @@ import { relationshipKeys } from './relationship-keys.js';
 import { relationshipJoinSource } from './relationship-measure-sql.js';
 import { clickhouseDatasetSqlDialect } from './clickhouse-dataset-sql-dialect.js';
 import { resolveRelationshipReference } from './relationship-measures.js';
+import { joinsWithinTenant } from './tenant-runtime.js';
 import { datasetRowScope, runtimeConstraints } from './row-scope.js';
 import { isQualifiedField, resolveQualifiedField } from './relationship-fields.js';
 /**
@@ -34,7 +35,11 @@ export function buildRelationshipBuilderContext(ds, query, context, dialect = cl
         const measureNames = (query.measures ?? [])
             .filter(name => name.startsWith(`${relationshipName}.`))
             .map(name => name.slice(relationshipName.length + 1));
-        const keys = relationshipKeys(relationship);
+        const authoredKeys = relationshipKeys(relationship);
+        // Under a scope of several tenants, a key reused by another tenant must not match.
+        const keys = joinsWithinTenant(ds, target, context)
+            ? [...authoredKeys, { from: ds.tenantKey, to: target.tenantKey }]
+            : authoredKeys;
         const projected = relationshipJoinSource(target, keys.map(key => key.to), measureNames, dialect);
         joinByRelationship.set(relationshipName, {
             relationship: relationshipName,
@@ -54,9 +59,14 @@ export function buildRelationshipBuilderContext(ds, query, context, dialect = cl
         dialect,
     };
 }
-/** Qualifies a base physical column with the base source when joins are active. */
-export function qualifyBaseColumn(ctx, column) {
-    return ctx ? `${ctx.baseSource}.${column}` : column;
+/**
+ * Qualifies a base physical column with the base source. Always qualified:
+ * ClickHouse resolves an output alias before a column of the same name, so a
+ * bare `status` could read a dimension aliased `status`, and a bare `amount`
+ * inside another aggregate could read a measure aliased `amount`.
+ */
+export function qualifyBaseColumn(ctx, column, source) {
+    return `${ctx ? ctx.baseSource : source}.${column}`;
 }
 /**
  * Resolves a relationship-qualified field to a null-guarded SQL expression:

package/dist/utils/scoped-dataset-source.js

@@ -21,7 +21,7 @@ export function scopedDatasetSource(options) {
     // A resolved join target is read with FINAL even when this dataset isn't.
     if (queryReadsFinal(ds, joinCtx) && qb.settings)
         qb = qb.settings(FINAL_SAFETY_SETTINGS);
-    qb = applyRowScope(qb, datasetRowScope(ds, context), column => qualifyBaseColumn(joinCtx, column));
+    qb = applyRowScope(qb, datasetRowScope(ds, context), column => qualifyBaseColumn(joinCtx, column, ds.source));
     // Constraints are filters in the dataset's vocabulary, applied exactly as a
     // caller filter on the same field would be.
     for (const constraint of runtimeConstraints(context)) {

package/dist/utils/tenant-runtime.d.ts

@@ -9,6 +9,13 @@ export type TenantPredicate = {
 export declare function getRuntimeTenantPredicate(context?: ExecutionContext): TenantPredicate | undefined;
 export declare function getRuntimeTenantId(context?: ExecutionContext): string | undefined;
 export declare function isCrossTenantRuntime(context?: ExecutionContext): boolean;
+/**
+ * Whether a join from `base` to `target` must also match their tenant keys.
+ * One tenant pins both sides to the same id already. A scope over several
+ * tenants, or all of them, admits every scoped tenant's target rows, so a key
+ * reused across tenants would otherwise match another tenant's row.
+ */
+export declare function joinsWithinTenant(base: Pick<AnyDatasetInstance, 'tenantKey'>, target: Pick<AnyDatasetInstance, 'tenantKey'>, context?: ExecutionContext): boolean;
 export declare function hasTenantRuntime(context?: ExecutionContext): boolean;
 export declare function validateTenantRuntime(ds: AnyDatasetInstance, context?: ExecutionContext): string | undefined;
 //# sourceMappingURL=tenant-runtime.d.ts.map

package/dist/utils/tenant-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tenant-runtime.d.ts","sourceRoot":"","sources":["../../src/utils/tenant-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAExC,wBAAgB,yBAAyB,CACvC,OAAO,CAAC,EAAE,gBAAgB,GACzB,eAAe,GAAG,SAAS,CAe7B;AAED,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAGjF;AAED,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAGxE;AAED,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAEpE;AAED,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,kBAAkB,EACtB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,SAAS,CAQpB"}
+{"version":3,"file":"tenant-runtime.d.ts","sourceRoot":"","sources":["../../src/utils/tenant-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAExC,wBAAgB,yBAAyB,CACvC,OAAO,CAAC,EAAE,gBAAgB,GACzB,eAAe,GAAG,SAAS,CAe7B;AAED,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAGjF;AAED,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAGxE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC,EAC3C,MAAM,EAAE,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC,EAC7C,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAST;AAED,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAEpE;AAED,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,kBAAkB,EACtB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,SAAS,CAQpB"}

package/dist/utils/tenant-runtime.js

@@ -22,6 +22,22 @@ export function isCrossTenantRuntime(context) {
     const tenant = context?.runtime?.tenant;
     return !!tenant && typeof tenant === 'object' && 'scope' in tenant && tenant.scope === 'all';
 }
+/**
+ * Whether a join from `base` to `target` must also match their tenant keys.
+ * One tenant pins both sides to the same id already. A scope over several
+ * tenants, or all of them, admits every scoped tenant's target rows, so a key
+ * reused across tenants would otherwise match another tenant's row.
+ */
+export function joinsWithinTenant(base, target, context) {
+    if (!base.tenantKey || !target.tenantKey) {
+        return false;
+    }
+    const predicate = getRuntimeTenantPredicate(context);
+    if (predicate) {
+        return predicate.operator === 'in' && predicate.value.length > 1;
+    }
+    return isCrossTenantRuntime(context);
+}
 export function hasTenantRuntime(context) {
     return !!getRuntimeTenantPredicate(context) || isCrossTenantRuntime(context);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/datasets",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Code-first TypeScript semantic layer for ClickHouse datasets, metrics, multi-tenancy, and AI agents",
   "keywords": [
     "semantic-layer",
@@ -55,7 +55,7 @@
     "!dist/**/type-tests/**"
   ],
   "dependencies": {
-    "@hypequery/protocol": "^0.24.0",
+    "@hypequery/protocol": "^0.24.2",
     "@noble/hashes": "^2.4.0",
     "zod": "^4.6.6",
     "zod-to-json-schema": "^3.25.2"