@hypequery/datasets 0.17.1 → 0.19.0

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.17.1",
+  "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.14.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.11.2"
+    "@hypequery/protocol-conformance": "^0.13.0"
   },
   "repository": {
     "type": "git",