@hypequery/datasets 0.13.6 → 0.15.0

package/dist/protocol-adapter.js

@@ -1,5 +1,7 @@
-import { parseProtocolIdentifier, parseProtocolQualifiedIdentifier, validateCanonicalValue, validateProtocolDatasetContract, } from '@hypequery/protocol';
+import { filterExpression, metricExpression, metricDerivation } from './utils/protocol-metric-expressions.js';
+import { parseProtocolIdentifier, parseProtocolQualifiedIdentifier, validateProtocolDatasetContract, } from '@hypequery/protocol';
 import { SEMANTIC_FILTER_OPERATORS } from './constants.js';
+import { toProtocolSemanticMetadata } from './utils/protocol-semantic-metadata.js';
 function byName(left, right) {
     return left.name.localeCompare(right.name);
 }
@@ -16,107 +18,11 @@ function fieldSchema(type) {
             return { kind: 'any' };
     }
 }
-function canonicalValue(input) {
-    if (Array.isArray(input)) {
-        return validateCanonicalValue({
-            $hypequery: {
-                type: 'array',
-                version: 1,
-                values: input.map(canonicalValue),
-            },
-        });
-    }
-    if (typeof input === 'object' && input !== null) {
-        if ('$hypequery' in input)
-            return validateCanonicalValue(input);
-        const prototype = Object.getPrototypeOf(input);
-        if (prototype !== Object.prototype && prototype !== null) {
-            throw new TypeError('Dataset protocol adapter only accepts plain filter values.');
-        }
-        return validateCanonicalValue({
-            $hypequery: {
-                type: 'map',
-                version: 1,
-                entries: Object.entries(input)
-                    .sort(([left], [right]) => left.localeCompare(right))
-                    .map(([key, value]) => [key, canonicalValue(value)]),
-            },
-        });
-    }
-    return validateCanonicalValue(input);
-}
-function filterExpression(filter) {
-    const left = {
-        kind: 'reference',
-        name: parseProtocolQualifiedIdentifier(filter.field),
-    };
-    const right = {
-        kind: 'literal',
-        value: canonicalValue(filter.value),
-    };
-    const result = {
-        kind: 'comparison',
-        operator: filter.operator,
-        left,
-        right,
-    };
-    return result;
-}
-function aggregationExpression(spec) {
-    const result = {
-        kind: 'aggregate',
-        aggregation: spec.aggregation,
-        field: parseProtocolQualifiedIdentifier(spec.field),
-        ...(spec.argField !== undefined
-            ? { argField: parseProtocolQualifiedIdentifier(spec.argField) }
-            : {}),
-        ...(spec.level !== undefined ? { level: spec.level } : {}),
-        ...(spec.filters?.length
-            ? { filters: spec.filters.map(filterExpression) }
-            : {}),
-    };
-    return result;
-}
-function semanticExpression(expression, references = {}) {
-    switch (expression.kind) {
-        case 'ref':
-            return references[expression.name]
-                ?? {
-                    kind: 'reference',
-                    name: parseProtocolQualifiedIdentifier(expression.name),
-                };
-        case 'literal':
-            return { kind: 'literal', value: canonicalValue(expression.value) };
-        case 'binary':
-            return {
-                kind: 'binary',
-                operator: expression.operator,
-                left: semanticExpression(expression.left, references),
-                right: semanticExpression(expression.right, references),
-            };
-        case 'function':
-            return {
-                kind: 'call',
-                function: expression.name,
-                args: expression.args.map(argument => semanticExpression(argument, references)),
-            };
-    }
-}
 function unwrapMetric(metric) {
     return metric.__type === 'grained_metric_ref'
         ? { ref: metric.metric, grain: metric.grain }
         : { ref: metric };
 }
-function metricExpression(spec) {
-    if (spec.__type === 'aggregation_spec')
-        return aggregationExpression(spec);
-    const aliases = Object.fromEntries(Object.keys(spec.uses).map(alias => [alias, alias]));
-    const references = Object.fromEntries(Object.entries(spec.uses).map(([alias, metric]) => [
-        alias,
-        aggregationExpression(metric.spec),
-    ]));
-    return semanticExpression(spec.formula(aliases).expression, references);
-}
 function metricContract(exposedName, metric, endpoint) {
     const { ref, grain } = unwrapMetric(metric);
     const contract = metric.contract();
@@ -128,12 +34,16 @@ function metricContract(exposedName, metric, endpoint) {
                 ? 'derived-metric'
                 : 'metric',
         expression: metricExpression(ref.spec),
+        ...(ref.spec.__type === 'derived_metric_spec'
+            ? { derivation: metricDerivation(ref.spec) }
+            : {}),
         dimensions: [...contract.dimensions].sort().map(parseProtocolQualifiedIdentifier),
         filters: [...contract.filters].sort().map(parseProtocolIdentifier),
         grains: [...contract.grains].sort(),
         ...(grain !== undefined ? { grain } : {}),
         ...(ref.label !== undefined ? { label: ref.label } : {}),
         ...(ref.description !== undefined ? { description: ref.description } : {}),
+        ...toProtocolSemanticMetadata(ref),
         endpoint,
     };
     return result;
@@ -170,7 +80,23 @@ export function buildProtocolDatasetContract(dataset, options = {}) {
         .sort(byName);
     const contract = {
         name: dataset.name,
+        ...(dataset.description !== undefined ? { description: dataset.description } : {}),
+        ...toProtocolSemanticMetadata(dataset),
         source: dataset.source,
+        ...(dataset.freshness !== undefined ? { freshness: { ...dataset.freshness } } : {}),
+        ...(dataset.owner !== undefined ? { owner: dataset.owner } : {}),
+        ...(dataset.defaults !== undefined
+            ? {
+                defaults: {
+                    ...(dataset.defaults.dimensions !== undefined
+                        ? { dimensions: [...dataset.defaults.dimensions].map(parseProtocolIdentifier) }
+                        : {}),
+                    ...(dataset.defaults.timeGrain !== undefined
+                        ? { timeGrain: dataset.defaults.timeGrain }
+                        : {}),
+                },
+            }
+            : {}),
         tenant: dataset.tenantKey
             ? { kind: 'required', field: dataset.tenantKey }
             : { kind: 'not-required' },
@@ -185,6 +111,7 @@ export function buildProtocolDatasetContract(dataset, options = {}) {
             groupable: dimension.groupable !== false,
             ...(dimension.label !== undefined ? { label: dimension.label } : {}),
             ...(dimension.description !== undefined ? { description: dimension.description } : {}),
+            ...toProtocolSemanticMetadata(dimension),
         })).sort(byName),
         measures: Object.entries(dataset.measures).map(([name, measure]) => ({
             name,
@@ -200,6 +127,7 @@ export function buildProtocolDatasetContract(dataset, options = {}) {
             filters: (measure.filters ?? []).map(filterExpression),
             ...(measure.label !== undefined ? { label: measure.label } : {}),
             ...(measure.description !== undefined ? { description: measure.description } : {}),
+            ...toProtocolSemanticMetadata(measure),
         })).sort(byName),
         filters: Object.entries(dataset.filters).map(([name, filter]) => ({
             name,
@@ -207,6 +135,7 @@ export function buildProtocolDatasetContract(dataset, options = {}) {
             operators: [...(filter.operators ?? SEMANTIC_FILTER_OPERATORS)],
             ...(filter.label !== undefined ? { label: filter.label } : {}),
             ...(filter.description !== undefined ? { description: filter.description } : {}),
+            ...toProtocolSemanticMetadata(filter),
         })).sort(byName),
         metrics,
         relationships: Object.entries(dataset.relationships).map(([name, relationship]) => ({

package/dist/protocol-rehydrate.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Rebuilds executable datasets from a portable deployment contract.
+ *
+ * The inverse of `protocol-adapter.ts`. Decision 0005 chose portable native
+ * execution, which means a runtime resolves a dataset from the validated active
+ * contract and plans the query with the existing semantic planner — no customer
+ * module is loaded. This is the function that makes the contract executable.
+ *
+ * Rehydration deliberately routes through the public `dataset()` factory rather
+ * than assembling an instance by hand, so a rebuilt dataset is constructed by
+ * exactly the same code path as an authored one. That is what makes the
+ * byte-identical SQL claim mitigated by construction rather than by review.
+ */
+import type { ProtocolDatasetContract } from '@hypequery/protocol';
+import type { AnyDatasetInstance, DatasetCachePolicy, MetricHandle } from './types.js';
+/** A rebuilt dataset in the registry shape Serve, MCP, and the planner accept. */
+export type RehydratedDataset = AnyDatasetInstance & {
+    readonly metrics: Readonly<Record<string, MetricHandle>>;
+};
+export interface RehydrateProtocolDatasetsOptions {
+    /**
+     * Cache policy for the rebuilt datasets. Not carried by the contract — it is
+     * an operational concern of whoever runs the query, not of the deployment.
+     */
+    readonly cache?: DatasetCachePolicy;
+    /**
+     * What to do with a metric portable execution cannot rebuild.
+     *
+     * `throw` (the default) refuses the whole contract, which is right when a
+     * caller is checking whether a deployment is fully portable. `skip` omits
+     * just that metric, which is what a runtime wants: one derived metric must
+     * not make every other dataset in the deployment unexecutable. A caller that
+     * skips is responsible for refusing the skipped target at the point of use.
+     */
+    readonly onUnsupportedMetric?: 'throw' | 'skip';
+}
+/**
+ * Thrown when a contract describes something portable execution cannot rebuild.
+ *
+ * Callers map this onto the `unsupported-capability` invocation failure rather
+ * than executing an approximation, as decision 0005 requires.
+ */
+export declare class UnsupportedContractFeatureError extends Error {
+    readonly dataset: string;
+    readonly feature: string;
+    constructor(datasetName: string, feature: string, detail: string);
+}
+/**
+ * Rebuild every dataset in a validated deployment contract.
+ *
+ * Datasets are returned keyed by contract name with their named metrics
+ * attached, which is the registry shape `getDatasetCatalog`,
+ * `projectAgentSafeCatalog`, and `DatasetClient` already accept.
+ */
+export declare function rehydrateProtocolDatasets(contracts: readonly ProtocolDatasetContract[], options?: RehydrateProtocolDatasetsOptions): Readonly<Record<string, RehydratedDataset>>;
+//# sourceMappingURL=protocol-rehydrate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-rehydrate.d.ts","sourceRoot":"","sources":["../src/protocol-rehydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,uBAAuB,EAKxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAKlB,YAAY,EAIb,MAAM,YAAY,CAAC;AAMpB,kFAAkF;AAClF,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAAG;IACnD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CAC1D,CAAC;AAEF,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACjD;AAED;;;;;GAKG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAMjE;AAwOD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,uBAAuB,EAAE,EAC7C,OAAO,GAAE,gCAAqC,GAC7C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAqE7C"}

package/dist/protocol-rehydrate.js

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

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

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

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

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

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

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

package/dist/publishing/node.d.ts

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

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

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

package/dist/publishing/node.js

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

package/dist/publishing/publisher.d.ts

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

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

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

package/dist/publishing/publisher.js

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