@hypequery/protocol 0.11.1 → 0.13.0

package/dist/deployments/index.d.ts

@@ -3,5 +3,5 @@ export { PROTOCOL_DEPLOYMENT_IDENTITY_DOMAIN, encodeProtocolDeploymentContract,
 export type { PreparedProtocolDeploymentContract } from './codec.js';
 export { DEFAULT_PROTOCOL_DEPLOYMENT_LIMITS } from './limits.js';
 export { validateProtocolDatasetContract, validateProtocolDeploymentContract, } from './validate.js';
-export type { ProtocolAccessPolicy, ProtocolDatasetContract, ProtocolDatasetDimension, ProtocolDatasetFieldSource, ProtocolDatasetFieldType, ProtocolDatasetFilter, ProtocolDatasetLimits, ProtocolDatasetMeasure, ProtocolDatasetMetric, ProtocolDatasetRelationship, ProtocolDatasetTenantPolicy, ProtocolDeploymentContract, ProtocolDeploymentErrorCode, ProtocolDeploymentLimits, ProtocolDeploymentOptions, ProtocolEndpointPolicy, ProtocolEndpointTenantPolicy, ProtocolNamedQueryContract, ProtocolRuntimeArtifact, } from './types.js';
+export type { ProtocolAccessPolicy, ProtocolDatasetContract, ProtocolDatasetDefaults, ProtocolDatasetDimension, ProtocolDatasetFieldSource, ProtocolDatasetFieldType, ProtocolDatasetFilter, ProtocolDatasetFreshness, ProtocolDatasetLimits, ProtocolDatasetMeasure, ProtocolDatasetMetric, ProtocolDatasetRelationship, ProtocolDatasetTenantPolicy, ProtocolSemanticMetadata, ProtocolSemanticSensitivity, ProtocolDeploymentContract, ProtocolDeploymentErrorCode, ProtocolDeploymentLimits, ProtocolDeploymentOptions, ProtocolEndpointPolicy, ProtocolEndpointTenantPolicy, ProtocolMetricDerivation, ProtocolMetricInput, ProtocolNamedQueryContract, ProtocolRuntimeArtifact, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/deployments/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/deployments/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EACL,mCAAmC,EACnC,gCAAgC,EAChC,wCAAwC,EACxC,8BAA8B,EAC9B,iCAAiC,GAClC,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,kCAAkC,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,EAAE,kCAAkC,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EACL,+BAA+B,EAC/B,kCAAkC,GACnC,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,EACtB,4BAA4B,EAC5B,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/deployments/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EACL,mCAAmC,EACnC,gCAAgC,EAChC,wCAAwC,EACxC,8BAA8B,EAC9B,iCAAiC,GAClC,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,kCAAkC,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,EAAE,kCAAkC,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EACL,+BAA+B,EAC/B,kCAAkC,GACnC,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACrB,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,2BAA2B,EAC3B,2BAA2B,EAC3B,wBAAwB,EACxB,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,EACtB,4BAA4B,EAC5B,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,YAAY,CAAC"}

package/dist/deployments/limits.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/deployments/limits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAEtF,eAAO,MAAM,kCAAkC,EAAE,QAAQ,CAAC,wBAAwB,CAQhF,CAAC;AAEH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,yBAA8B,GACtC,QAAQ,CAAC,wBAAwB,CAAC,CAcpC"}
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/deployments/limits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAEtF,eAAO,MAAM,kCAAkC,EAAE,QAAQ,CAAC,wBAAwB,CAShF,CAAC;AAEH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,yBAA8B,GACtC,QAAQ,CAAC,wBAAwB,CAAC,CAcpC"}

package/dist/deployments/limits.js

@@ -3,6 +3,7 @@ export const DEFAULT_PROTOCOL_DEPLOYMENT_LIMITS = Object.freeze({
     maxQueries: 1_000,
     maxArtifacts: 100,
     maxDatasetItems: 1_000,
+    maxSemanticMetadataItems: 100,
     maxTextBytes: 4_096,
     maxSourceBytes: 1_024,
     maxPathBytes: 2_048,

package/dist/deployments/types.d.ts

@@ -3,6 +3,23 @@ import type { ProtocolIdentifier, ProtocolQualifiedIdentifier } from '../identif
 import type { ProtocolQueryImplementation, ProtocolSqlExpression } from '../query-implementations/index.js';
 import type { ProtocolSchema } from '../schemas/index.js';
 export type ProtocolDatasetFieldType = 'string' | 'number' | 'boolean' | 'timestamp';
+export type ProtocolSemanticSensitivity = 'public' | 'internal' | 'confidential' | 'restricted';
+export interface ProtocolSemanticMetadata {
+    readonly examples?: readonly string[];
+    readonly synonyms?: readonly string[];
+    readonly format?: string;
+    readonly unit?: string;
+    readonly currency?: string;
+    readonly timezone?: string;
+    readonly sensitivity?: ProtocolSemanticSensitivity;
+}
+export interface ProtocolDatasetFreshness {
+    readonly maxAgeSeconds: number;
+}
+export interface ProtocolDatasetDefaults {
+    readonly dimensions?: readonly ProtocolIdentifier[];
+    readonly timeGrain?: ProtocolTimeGrain;
+}
 export type ProtocolAccessPolicy = {
     readonly kind: 'public';
 } | {
@@ -34,7 +51,7 @@ export type ProtocolDatasetFieldSource = {
     readonly kind: 'column';
     readonly column: string;
 } | ProtocolSqlExpression;
-export interface ProtocolDatasetDimension {
+export interface ProtocolDatasetDimension extends ProtocolSemanticMetadata {
     readonly name: ProtocolIdentifier;
     readonly type: ProtocolDatasetFieldType;
     readonly source: ProtocolDatasetFieldSource;
@@ -43,7 +60,7 @@ export interface ProtocolDatasetDimension {
     readonly label?: string;
     readonly description?: string;
 }
-export interface ProtocolDatasetMeasure {
+export interface ProtocolDatasetMeasure extends ProtocolSemanticMetadata {
     readonly name: ProtocolIdentifier;
     readonly aggregation: 'sum' | 'count' | 'countDistinct' | 'avg' | 'min' | 'max' | 'argMax' | 'argMin' | 'percentile' | 'stddev' | 'variance';
     readonly field: ProtocolQualifiedIdentifier;
@@ -54,7 +71,7 @@ export interface ProtocolDatasetMeasure {
     readonly label?: string;
     readonly description?: string;
 }
-export interface ProtocolDatasetFilter {
+export interface ProtocolDatasetFilter extends ProtocolSemanticMetadata {
     readonly name: ProtocolIdentifier;
     readonly field: ProtocolQualifiedIdentifier;
     readonly operators: readonly ('eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'between' | 'like')[];
@@ -69,10 +86,37 @@ export interface ProtocolDatasetRelationship {
     readonly to: ProtocolQualifiedIdentifier;
     readonly queryable: boolean;
 }
-export interface ProtocolDatasetMetric {
+/** One aggregate a derived metric's formula names, under the alias it named it by. */
+export interface ProtocolMetricInput {
+    readonly alias: ProtocolIdentifier;
+    readonly expression: ProtocolExpression;
+}
+/**
+ * A derived metric's formula in the shape it was authored in.
+ *
+ * `ProtocolDatasetMetric.expression` inlines each input aggregate where the
+ * formula referenced it, which says what the metric means but loses the aliases
+ * the author chose. Those aliases are not cosmetic: they are emitted as the
+ * column names of the intermediate aggregate and referenced by the outer
+ * select, so a catalog rebuilt without them computes the same number through
+ * different SQL. `expression` here references the aliases instead, and
+ * validation proves that substituting the inputs back into it reproduces the
+ * inlined form exactly — the two can describe the same formula or the contract
+ * is invalid, never disagree silently.
+ */
+export interface ProtocolMetricDerivation {
+    readonly inputs: readonly ProtocolMetricInput[];
+    readonly expression: ProtocolExpression;
+}
+export interface ProtocolDatasetMetric extends ProtocolSemanticMetadata {
     readonly name: ProtocolIdentifier;
     readonly kind: 'metric' | 'derived-metric' | 'grained-metric';
     readonly expression: ProtocolExpression;
+    /**
+     * Present only on a derived metric, and optional: a contract written before
+     * this field existed stays valid and simply is not portably executable.
+     */
+    readonly derivation?: ProtocolMetricDerivation;
     readonly dimensions: readonly ProtocolQualifiedIdentifier[];
     readonly filters: readonly ProtocolIdentifier[];
     readonly grains: readonly ProtocolTimeGrain[];
@@ -87,9 +131,13 @@ export interface ProtocolDatasetLimits {
     readonly maxFilters?: number;
     readonly maxResultSize?: number;
 }
-export interface ProtocolDatasetContract {
+export interface ProtocolDatasetContract extends ProtocolSemanticMetadata {
     readonly name: ProtocolIdentifier;
+    readonly description?: string;
     readonly source: string;
+    readonly freshness?: ProtocolDatasetFreshness;
+    readonly owner?: string;
+    readonly defaults?: ProtocolDatasetDefaults;
     readonly tenant: ProtocolDatasetTenantPolicy;
     readonly timeField?: ProtocolQualifiedIdentifier;
     readonly dimensions: readonly ProtocolDatasetDimension[];
@@ -129,6 +177,13 @@ export interface ProtocolDeploymentLimits {
     readonly maxQueries: number;
     readonly maxArtifacts: number;
     readonly maxDatasetItems: number;
+    /**
+     * Ceiling on each semantic-metadata collection (`examples`, `synonyms`, and
+     * `defaults.dimensions`). Deliberately tighter than `maxDatasetItems`: these
+     * are authoring aids, and the definition-time validator in
+     * `@hypequery/datasets` applies the same ceiling.
+     */
+    readonly maxSemanticMetadataItems: number;
     readonly maxTextBytes: number;
     readonly maxSourceBytes: number;
     readonly maxPathBytes: number;

package/dist/deployments/types.d.ts.map

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

package/dist/deployments/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/deployments/validate.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAEV,uBAAuB,EASvB,0BAA0B,EAE1B,yBAAyB,EAK1B,MAAM,YAAY,CAAC;AAsfpB,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,yBAA8B,GACtC,uBAAuB,CAEzB;AAoKD,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,yBAA8B,GACtC,0BAA0B,CA2C5B"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/deployments/validate.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAEV,uBAAuB,EAUvB,0BAA0B,EAE1B,yBAAyB,EAK1B,MAAM,YAAY,CAAC;AA0wBpB,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,yBAA8B,GACtC,uBAAuB,CAEzB;AAqLD,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,yBAA8B,GACtC,0BAA0B,CA2C5B"}

package/dist/deployments/validate.js

@@ -14,6 +14,10 @@ const OPERATORS = new Set([
     'eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'in', 'notIn', 'between', 'like',
 ]);
 const GRAINS = new Set(['day', 'week', 'month', 'quarter', 'year']);
+const SENSITIVITIES = new Set(['public', 'internal', 'confidential', 'restricted']);
+const SEMANTIC_METADATA_FIELDS = [
+    'examples', 'synonyms', 'format', 'unit', 'currency', 'timezone', 'sensitivity',
+];
 function requireRecord(input, path) {
     if (typeof input !== 'object' || input === null || Array.isArray(input)) {
         deploymentError('HQ_DEPLOYMENT_TYPE', path);
@@ -108,6 +112,30 @@ function uniqueStrings(input, path, maxItems, parse) {
         deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', path);
     return Object.freeze(result);
 }
+function validateSemanticMetadata(value, result, path, limits) {
+    const parseText = (item, itemPath) => (boundedText(item, itemPath, limits.maxTextBytes));
+    for (const key of ['examples', 'synonyms']) {
+        if (value[key] !== undefined) {
+            result[key] = uniqueStrings(value[key], `${path}.${key}`, limits.maxSemanticMetadataItems, parseText);
+        }
+    }
+    for (const key of ['format', 'unit', 'timezone']) {
+        optionalText(value[key], key, result, path, limits);
+    }
+    if (value.currency !== undefined) {
+        const currency = boundedText(value.currency, `${path}.currency`, limits.maxTextBytes);
+        if (!/^[A-Z]{3}$/.test(currency)) {
+            deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.currency`);
+        }
+        result.currency = currency;
+    }
+    if (value.sensitivity !== undefined) {
+        if (typeof value.sensitivity !== 'string' || !SENSITIVITIES.has(value.sensitivity)) {
+            deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.sensitivity`);
+        }
+        result.sensitivity = value.sensitivity;
+    }
+}
 function validateAccess(input, path, limits) {
     const value = requireRecord(input, path);
     if (value.kind === 'public') {
@@ -223,7 +251,7 @@ function validateFieldSource(input, path, limits) {
 }
 function validateDimension(input, path, limits) {
     const value = requireRecord(input, path);
-    exactFields(value, ['name', 'type', 'source', 'filterable', 'groupable'], ['label', 'description'], path);
+    exactFields(value, ['name', 'type', 'source', 'filterable', 'groupable'], ['label', 'description', ...SEMANTIC_METADATA_FIELDS], path);
     if (!['string', 'number', 'boolean', 'timestamp'].includes(value.type)) {
         deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.type`);
     }
@@ -240,11 +268,12 @@ function validateDimension(input, path, limits) {
     };
     optionalText(value.label, 'label', result, path, limits);
     optionalText(value.description, 'description', result, path, limits);
+    validateSemanticMetadata(value, result, path, limits);
     return freezeRecord(result);
 }
 function validateMeasure(input, path, limits) {
     const value = requireRecord(input, path);
-    exactFields(value, ['name', 'aggregation', 'field', 'filters'], ['argField', 'level', 'sql', 'label', 'description'], path);
+    exactFields(value, ['name', 'aggregation', 'field', 'filters'], ['argField', 'level', 'sql', 'label', 'description', ...SEMANTIC_METADATA_FIELDS], path);
     if (typeof value.aggregation !== 'string' || !AGGREGATIONS.has(value.aggregation)) {
         deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.aggregation`);
     }
@@ -275,11 +304,12 @@ function validateMeasure(input, path, limits) {
         result.sql = nested(() => validateProtocolSqlExpression(value.sql), `${path}.sql`);
     optionalText(value.label, 'label', result, path, limits);
     optionalText(value.description, 'description', result, path, limits);
+    validateSemanticMetadata(value, result, path, limits);
     return freezeRecord(result);
 }
 function validateFilter(input, path, limits) {
     const value = requireRecord(input, path);
-    exactFields(value, ['name', 'field', 'operators'], ['label', 'description'], path);
+    exactFields(value, ['name', 'field', 'operators'], ['label', 'description', ...SEMANTIC_METADATA_FIELDS], path);
     const operators = uniqueStrings(value.operators, `${path}.operators`, limits.maxDatasetItems, (operator, operatorPath) => {
         if (typeof operator !== 'string' || !OPERATORS.has(operator)) {
             deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', operatorPath);
@@ -295,6 +325,7 @@ function validateFilter(input, path, limits) {
     };
     optionalText(value.label, 'label', result, path, limits);
     optionalText(value.description, 'description', result, path, limits);
+    validateSemanticMetadata(value, result, path, limits);
     return freezeRecord(result);
 }
 function validateRelationship(input, path) {
@@ -317,9 +348,148 @@ function validateRelationship(input, path) {
         queryable: value.queryable,
     });
 }
+/**
+ * The subset of the expression grammar a derived metric's formula may use.
+ *
+ * `validateProtocolExpression` accepts the whole of RFC 0003, which is wider
+ * than anything a formula can be written in: it permits comparisons, logical
+ * operators, a bare aggregate, and a one-argument `round`. A `derivation` exists
+ * to be rebuilt and executed, so accepting a form nothing can rebuild would
+ * publish a contract that validates and then fails at the point of use. The
+ * grammar is pinned here, in the artifact that defines the field, rather than
+ * left to whichever runtime happens to read it.
+ */
+function validateFormulaGrammar(expression, path) {
+    const node = expression;
+    const operand = (child, childPath) => validateFormulaGrammar(child, childPath);
+    const numericLiteral = (child, childPath) => {
+        const candidate = child;
+        if (candidate?.kind !== 'literal' || typeof candidate.value !== 'number') {
+            deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', childPath);
+        }
+    };
+    switch (node.kind) {
+        case 'reference':
+            return;
+        case 'binary':
+            // Arithmetic only, and never over a bare value: the authoring helpers
+            // take a name or another expression, never a literal.
+            if (!['add', 'subtract', 'multiply', 'divide'].includes(node.operator)) {
+                deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.operator`);
+            }
+            operand(node.left, `${path}.left`);
+            operand(node.right, `${path}.right`);
+            return;
+        case 'call': {
+            const args = node.args;
+            const expected = node.function === 'round' || node.function === 'coalesce' ? 2 : 1;
+            if (!['nullIfZero', 'coalesce', 'round', 'floor', 'ceil'].includes(node.function)) {
+                deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.function`);
+            }
+            if (args.length !== expected) {
+                deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.args`);
+            }
+            operand(args[0], `${path}.args[0]`);
+            if (node.function === 'round')
+                numericLiteral(args[1], `${path}.args[1]`);
+            // A `coalesce` fallback is the one position accepting a bare value.
+            if (node.function === 'coalesce' && args[1]?.kind === 'literal') {
+                numericLiteral(args[1], `${path}.args[1]`);
+            }
+            else if (node.function === 'coalesce') {
+                operand(args[1], `${path}.args[1]`);
+            }
+            return;
+        }
+        default:
+            deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', path);
+    }
+}
+/** Structural equality over two already-validated expressions. */
+function sameExpression(left, right) {
+    if (left === right)
+        return true;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return Array.isArray(left) && Array.isArray(right)
+            && left.length === right.length
+            && left.every((item, index) => sameExpression(item, right[index]));
+    }
+    if (typeof left !== 'object' || typeof right !== 'object' || left === null || right === null) {
+        return false;
+    }
+    const leftKeys = Object.keys(left);
+    const rightKeys = Object.keys(right);
+    return leftKeys.length === rightKeys.length
+        && leftKeys.every(key => Object.hasOwn(right, key)
+            && sameExpression(left[key], right[key]));
+}
+/** Replaces each aliased reference with the aggregate the alias stands for. */
+function substituteInputs(expression, inputs) {
+    if (Array.isArray(expression)) {
+        return expression.map(item => substituteInputs(item, inputs));
+    }
+    if (typeof expression !== 'object' || expression === null)
+        return expression;
+    const record = expression;
+    if (record.kind === 'reference' && typeof record.name === 'string' && inputs.has(record.name)) {
+        return inputs.get(record.name);
+    }
+    return Object.fromEntries(Object.entries(record).map(([key, value]) => [key, substituteInputs(value, inputs)]));
+}
+/**
+ * Validates the authored form of a derived metric's formula.
+ *
+ * Input order is significant and deliberately not sorted: each input becomes a
+ * column of the intermediate aggregate in this order, so reordering them
+ * reorders the emitted SQL. Two datasets that differ only in input order are
+ * genuinely different contracts.
+ */
+function validateDerivation(input, path, limits, inlined) {
+    const value = requireRecord(input, path);
+    exactFields(value, ['inputs', 'expression'], [], path);
+    const items = requireArray(value.inputs, `${path}.inputs`, limits.maxDatasetItems);
+    if (items.length === 0)
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.inputs`);
+    const seen = new Set();
+    const inputs = items.map((item, index) => {
+        const itemPath = `${path}.inputs[${index}]`;
+        const record = requireRecord(item, itemPath);
+        exactFields(record, ['alias', 'expression'], [], itemPath);
+        const alias = identifier(record.alias, `${itemPath}.alias`);
+        if (seen.has(alias))
+            deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${itemPath}.alias`);
+        seen.add(alias);
+        const expression = nested(() => validateProtocolExpression(record.expression), `${itemPath}.expression`);
+        // Only an aggregate can become a column of the intermediate result. A
+        // formula that named something else has no faithful rebuild.
+        if (expression.kind !== 'aggregate') {
+            deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${itemPath}.expression`);
+        }
+        return freezeRecord({ alias, expression });
+    });
+    const expression = nested(() => validateProtocolExpression(value.expression), `${path}.expression`);
+    validateFormulaGrammar(expression, `${path}.expression`);
+    // A formula that is a bare reference names one of its inputs instead of
+    // combining them. The authoring API cannot produce it — a formula must return
+    // a composed expression — so nothing could rebuild it.
+    if (expression.kind === 'reference') {
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.expression`);
+    }
+    // The two forms must describe one formula. Substituting the inputs back into
+    // the authored form has to reproduce the inlined one exactly, or the contract
+    // advertises a meaning its aliases do not compute.
+    const substituted = substituteInputs(expression, new Map(inputs.map(entry => [entry.alias, entry.expression])));
+    if (!sameExpression(substituted, inlined)) {
+        deploymentError('HQ_DEPLOYMENT_INVALID_REFERENCE', `${path}.expression`);
+    }
+    return freezeRecord({
+        inputs: Object.freeze(inputs),
+        expression,
+    });
+}
 function validateMetric(input, path, limits) {
     const value = requireRecord(input, path);
-    exactFields(value, ['name', 'kind', 'expression', 'dimensions', 'filters', 'grains', 'endpoint'], ['grain', 'label', 'description'], path);
+    exactFields(value, ['name', 'kind', 'expression', 'dimensions', 'filters', 'grains', 'endpoint'], ['grain', 'derivation', 'label', 'description', ...SEMANTIC_METADATA_FIELDS], path);
     if (!['metric', 'derived-metric', 'grained-metric'].includes(value.kind)) {
         deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.kind`);
     }
@@ -353,8 +523,21 @@ function validateMetric(input, path, limits) {
     };
     if (grain !== undefined)
         result.grain = grain;
+    if (value.derivation !== undefined) {
+        // Eligibility follows the expression, not `kind`. `kind` conflates grain
+        // with derivation — a derived metric pinned to a grain reports
+        // `grained-metric` — so it can neither confirm nor deny that a formula
+        // exists. A metric whose expression is a bare aggregate has none, whatever
+        // its kind says, and a derivation attached to one describes something the
+        // metric does not do.
+        if (result.expression.kind === 'aggregate') {
+            deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.derivation`);
+        }
+        result.derivation = validateDerivation(value.derivation, `${path}.derivation`, limits, result.expression);
+    }
     optionalText(value.label, 'label', result, path, limits);
     optionalText(value.description, 'description', result, path, limits);
+    validateSemanticMetadata(value, result, path, limits);
     return freezeRecord(result);
 }
 function validateLimits(input, path) {
@@ -367,6 +550,31 @@ function validateLimits(input, path) {
     }
     return freezeRecord(result);
 }
+function validateFreshness(input, path) {
+    const value = requireRecord(input, path);
+    exactFields(value, ['maxAgeSeconds'], [], path);
+    return freezeRecord({
+        maxAgeSeconds: positiveInteger(value.maxAgeSeconds, `${path}.maxAgeSeconds`),
+    });
+}
+function validateDefaults(input, path, limits) {
+    const value = requireRecord(input, path);
+    exactFields(value, [], ['dimensions', 'timeGrain'], path);
+    const result = {};
+    if (value.dimensions !== undefined) {
+        result.dimensions = uniqueStrings(value.dimensions, `${path}.dimensions`, limits.maxSemanticMetadataItems, (dimension, dimensionPath) => identifier(dimension, dimensionPath));
+    }
+    if (value.timeGrain !== undefined) {
+        if (typeof value.timeGrain !== 'string' || !GRAINS.has(value.timeGrain)) {
+            deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', `${path}.timeGrain`);
+        }
+        result.timeGrain = value.timeGrain;
+    }
+    if (Object.keys(result).length === 0) {
+        deploymentError('HQ_DEPLOYMENT_INVALID_VALUE', path);
+    }
+    return freezeRecord(result);
+}
 function namedItems(input, path, maxItems, validate) {
     const items = requireArray(input, path, maxItems).map((value, index) => validate(value, `${path}[${index}]`));
     if (new Set(items.map(item => item.name)).size !== items.length) {
@@ -376,7 +584,11 @@ function namedItems(input, path, maxItems, validate) {
 }
 function validateDataset(input, path, limits) {
     const value = requireRecord(input, path);
-    exactFields(value, ['name', 'source', 'tenant', 'dimensions', 'measures', 'filters', 'metrics', 'relationships'], ['timeField', 'limits', 'endpoint'], path);
+    exactFields(value, ['name', 'source', 'tenant', 'dimensions', 'measures', 'filters', 'metrics', 'relationships'], [
+        'description', 'freshness', 'owner', 'defaults',
+        ...SEMANTIC_METADATA_FIELDS,
+        'timeField', 'limits', 'endpoint',
+    ], path);
     const result = {
         name: identifier(value.name, `${path}.name`),
         source: boundedText(value.source, `${path}.source`, limits.maxSourceBytes),
@@ -389,6 +601,15 @@ function validateDataset(input, path, limits) {
     };
     if (value.timeField !== undefined)
         result.timeField = identifier(value.timeField, `${path}.timeField`, true);
+    optionalText(value.description, 'description', result, path, limits);
+    optionalText(value.owner, 'owner', result, path, limits);
+    validateSemanticMetadata(value, result, path, limits);
+    if (value.freshness !== undefined) {
+        result.freshness = validateFreshness(value.freshness, `${path}.freshness`);
+    }
+    if (value.defaults !== undefined) {
+        result.defaults = validateDefaults(value.defaults, `${path}.defaults`, limits);
+    }
     if (value.limits !== undefined)
         result.limits = validateLimits(value.limits, `${path}.limits`);
     if (value.endpoint !== undefined)
@@ -430,6 +651,12 @@ function validateArtifact(input, path) {
 function validateReferences(contract) {
     const datasets = new Map(contract.datasets.map(dataset => [dataset.name, dataset]));
     for (const [datasetIndex, dataset] of contract.datasets.entries()) {
+        if (dataset.defaults?.dimensions?.some(name => (!dataset.dimensions.some(dimension => dimension.name === name && dimension.groupable)))) {
+            deploymentError('HQ_DEPLOYMENT_INVALID_REFERENCE', `$.datasets[${datasetIndex}].defaults.dimensions`);
+        }
+        if (dataset.defaults?.timeGrain !== undefined && dataset.timeField === undefined) {
+            deploymentError('HQ_DEPLOYMENT_INVALID_REFERENCE', `$.datasets[${datasetIndex}].defaults.timeGrain`);
+        }
         for (const [relationshipIndex, relationship] of dataset.relationships.entries()) {
             if (!datasets.has(relationship.target)) {
                 deploymentError('HQ_DEPLOYMENT_INVALID_REFERENCE', `$.datasets[${datasetIndex}].relationships[${relationshipIndex}].target`);
@@ -453,13 +680,16 @@ function validateReferences(contract) {
                 && dataset.timeField === undefined) {
                 deploymentError('HQ_DEPLOYMENT_INVALID_REFERENCE', `$.datasets[${datasetIndex}].metrics[${metricIndex}].grains`);
             }
-            if (dataset.tenant.kind === 'required' && metric.endpoint.tenant.kind !== 'required') {
+            // Biconditional, as for a compiled-SQL query below. An endpoint that
+            // requires a tenant over a dataset carrying no tenant field resolves one
+            // and then has no column to scope by, so the query reads every tenant
+            // while both layers believe tenancy was enforced.
+            if ((dataset.tenant.kind === 'required') !== (metric.endpoint.tenant.kind === 'required')) {
                 deploymentError('HQ_DEPLOYMENT_INVALID_REFERENCE', `$.datasets[${datasetIndex}].metrics[${metricIndex}].endpoint.tenant`);
             }
         }
-        if (dataset.tenant.kind === 'required'
-            && dataset.endpoint !== undefined
-            && dataset.endpoint.tenant.kind !== 'required') {
+        if (dataset.endpoint !== undefined
+            && (dataset.tenant.kind === 'required') !== (dataset.endpoint.tenant.kind === 'required')) {
             deploymentError('HQ_DEPLOYMENT_INVALID_REFERENCE', `$.datasets[${datasetIndex}].endpoint.tenant`);
         }
     }

package/dist/index.d.ts

@@ -11,11 +11,14 @@ export type { ProtocolIdentifier, ProtocolIdentifierErrorCode, ProtocolQualified
 export { DEFAULT_PROTOCOL_QUERY_IMPLEMENTATION_LIMITS, ProtocolQueryImplementationError, validateProtocolQueryImplementation, validateProtocolSqlExpression, } from './query-implementations/index.js';
 export { DEFAULT_PROTOCOL_QUERY_EVENT_LIMITS, ProtocolQueryDiagnosticsError, ProtocolQueryEventError, validateProtocolQueryDiagnostics, validateProtocolQueryEvent, } from './events/index.js';
 export type { ProtocolQueryDiagnostics, ProtocolQueryDiagnosticsErrorCode, ProtocolQueryErrorCategory, ProtocolQueryEvent, ProtocolQueryEventErrorCode, ProtocolQueryEventLimits, ProtocolQueryEventOptions, ProtocolQueryEventOutcome, ProtocolQueryEventTarget, ProtocolQueryOperation, ProtocolQueryTerminalReason, } from './events/index.js';
+export { DEFAULT_PROTOCOL_SEMANTIC_INVOCATION_LIMITS, ProtocolSemanticInvocationError, validateProtocolSemanticInvocation, validateProtocolSemanticInvocationFailure, validateProtocolSemanticInvocationResult, } from './invocations/index.js';
+export type { ProtocolSemanticInvocation, ProtocolSemanticInvocationBudget, ProtocolSemanticInvocationErrorCode, ProtocolSemanticInvocationFailure, ProtocolSemanticInvocationFailureCategory, ProtocolSemanticInvocationLimits, ProtocolSemanticInvocationMeta, ProtocolSemanticInvocationOptions, ProtocolSemanticInvocationPagination, ProtocolSemanticInvocationResult, ProtocolSemanticInvocationRow, ProtocolSemanticInvocationTarget, ProtocolSemanticInvocationValue, } from './invocations/index.js';
 export { DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS, PROTOCOL_DEPLOYMENT_BUNDLE_IDENTITY_DOMAIN, ProtocolDeploymentBundleError, encodeProtocolDeploymentBundleManifest, encodeProtocolDeploymentBundleManifestToString, hashProtocolDeploymentBundleManifest, prepareProtocolDeploymentBundleManifest, validateProtocolDeploymentBundleManifest, } from './bundles/index.js';
 export { DEFAULT_PROTOCOL_DEPLOYMENT_RELEASE_LIMITS, PROTOCOL_DEPLOYMENT_RELEASE_IDENTITY_DOMAIN, ProtocolDeploymentReleaseError, encodeProtocolDeploymentReleaseEnvelope, encodeProtocolDeploymentReleaseEnvelopeToString, hashProtocolDeploymentReleaseEnvelope, prepareProtocolDeploymentReleaseEnvelope, validateProtocolDeploymentReleaseEnvelope, validateProtocolDeploymentReleaseTarget, } from './releases/index.js';
 export type { PreparedProtocolDeploymentReleaseEnvelope, ProtocolDeploymentReleaseEnvelope, ProtocolDeploymentReleaseErrorCode, ProtocolDeploymentReleaseLimits, ProtocolDeploymentReleaseOptions, ProtocolDeploymentReleaseTarget, } from './releases/index.js';
 export type { PreparedProtocolDeploymentBundleManifest, ProtocolDeploymentBundleArtifact, ProtocolDeploymentBundleDeployment, ProtocolDeploymentBundleErrorCode, ProtocolDeploymentBundleFile, ProtocolDeploymentBundleLimits, ProtocolDeploymentBundleManifest, ProtocolDeploymentBundleOptions, } from './bundles/index.js';
 export { DEFAULT_PROTOCOL_DEPLOYMENT_LIMITS, PROTOCOL_DEPLOYMENT_IDENTITY_DOMAIN, ProtocolDeploymentError, encodeProtocolDeploymentContract, encodeProtocolDeploymentContractToString, hashProtocolDeploymentContract, prepareProtocolDeploymentContract, validateProtocolDatasetContract, validateProtocolDeploymentContract, } from './deployments/index.js';
-export type { PreparedProtocolDeploymentContract, ProtocolAccessPolicy, ProtocolDatasetContract, ProtocolDatasetDimension, ProtocolDatasetFieldSource, ProtocolDatasetFieldType, ProtocolDatasetFilter, ProtocolDatasetLimits, ProtocolDatasetMeasure, ProtocolDatasetMetric, ProtocolDatasetRelationship, ProtocolDatasetTenantPolicy, ProtocolDeploymentContract, ProtocolDeploymentErrorCode, ProtocolDeploymentLimits, ProtocolDeploymentOptions, ProtocolEndpointPolicy, ProtocolEndpointTenantPolicy, ProtocolNamedQueryContract, ProtocolRuntimeArtifact, } from './deployments/index.js';
+export type { PreparedProtocolDeploymentContract, ProtocolAccessPolicy, ProtocolDatasetContract, ProtocolDatasetDefaults, ProtocolDatasetDimension, ProtocolDatasetFieldSource, ProtocolDatasetFieldType, ProtocolDatasetFilter, ProtocolDatasetFreshness, ProtocolDatasetLimits, ProtocolDatasetMeasure, ProtocolDatasetMetric, ProtocolDatasetRelationship, ProtocolDatasetTenantPolicy, ProtocolSemanticMetadata, ProtocolSemanticSensitivity, ProtocolDeploymentContract, ProtocolDeploymentErrorCode, ProtocolDeploymentLimits, ProtocolDeploymentOptions, ProtocolEndpointPolicy, ProtocolEndpointTenantPolicy, ProtocolMetricDerivation, ProtocolMetricInput, ProtocolNamedQueryContract, ProtocolRuntimeArtifact, } from './deployments/index.js';
 export type { ProtocolQueryImplementation, ProtocolQueryImplementationErrorCode, ProtocolQueryImplementationLimits, ProtocolQueryImplementationOptions, ProtocolSqlDialect, ProtocolSqlExpression, ProtocolSqlParameter, ProtocolSqlParameterSource, ProtocolSqlTenantPolicy, } from './query-implementations/index.js';
+export { PROTOCOL_SEMANTIC_FAILURE_MESSAGES } from './invocations/failure-messages.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,EAC9B,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,4BAA4B,EAC5B,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,sBAAsB,EACtB,WAAW,EACX,gBAAgB,EAChB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,0BAA0B,EAC1B,uBAAuB,EACvB,oBAAoB,EACpB,6BAA6B,EAC7B,+BAA+B,EAC/B,uBAAuB,EACvB,gCAAgC,EAChC,gCAAgC,GACjC,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,EACtB,iCAAiC,GAClC,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,kCAAkC,EAClC,uBAAuB,EACvB,0BAA0B,EAC1B,6BAA6B,GAC9B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,8BAA8B,EAC9B,oCAAoC,EACpC,mBAAmB,EACnB,wBAAwB,EACxB,wBAAwB,EACxB,+BAA+B,EAC/B,gCAAgC,EAChC,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,cAAc,EACd,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,mBAAmB,EACnB,sBAAsB,EACtB,0BAA0B,EAC1B,oBAAoB,EACpB,kBAAkB,EAClB,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,EACf,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAEhC,YAAY,EACV,6BAA6B,EAC7B,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,kBAAkB,EAClB,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,4CAA4C,EAC5C,gCAAgC,EAChC,mCAAmC,EACnC,6BAA6B,GAC9B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,mCAAmC,EACnC,6BAA6B,EAC7B,uBAAuB,EACvB,gCAAgC,EAChC,0BAA0B,GAC3B,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,wBAAwB,EACxB,iCAAiC,EACjC,0BAA0B,EAC1B,kBAAkB,EAClB,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,EACxB,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,yCAAyC,EACzC,0CAA0C,EAC1C,6BAA6B,EAC7B,sCAAsC,EACtC,8CAA8C,EAC9C,oCAAoC,EACpC,uCAAuC,EACvC,wCAAwC,GACzC,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,0CAA0C,EAC1C,2CAA2C,EAC3C,8BAA8B,EAC9B,uCAAuC,EACvC,+CAA+C,EAC/C,qCAAqC,EACrC,wCAAwC,EACxC,yCAAyC,EACzC,uCAAuC,GACxC,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EACV,yCAAyC,EACzC,iCAAiC,EACjC,kCAAkC,EAClC,+BAA+B,EAC/B,gCAAgC,EAChC,+BAA+B,GAChC,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EACV,wCAAwC,EACxC,gCAAgC,EAChC,kCAAkC,EAClC,iCAAiC,EACjC,4BAA4B,EAC5B,8BAA8B,EAC9B,gCAAgC,EAChC,+BAA+B,GAChC,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,kCAAkC,EAClC,mCAAmC,EACnC,uBAAuB,EACvB,gCAAgC,EAChC,wCAAwC,EACxC,8BAA8B,EAC9B,iCAAiC,EACjC,+BAA+B,EAC/B,kCAAkC,GACnC,MAAM,wBAAwB,CAAC;AAEhC,YAAY,EACV,kCAAkC,EAClC,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,EACtB,4BAA4B,EAC5B,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAEhC,YAAY,EACV,2BAA2B,EAC3B,oCAAoC,EACpC,iCAAiC,EACjC,kCAAkC,EAClC,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -5,6 +5,8 @@ export { DEFAULT_PROTOCOL_EXPRESSION_LIMITS, ProtocolExpressionError, validatePr
 export { DEFAULT_PROTOCOL_SCHEMA_LIMITS, DEFAULT_PROTOCOL_SCHEMA_VALUE_LIMITS, ProtocolSchemaError, ProtocolSchemaValueError, applyProtocolSchemaValue, createProtocolSchemaValueParser, resolveProtocolSchemaValueLimits, validateProtocolSchema, } from './schemas/index.js';
 export { DEFAULT_PROTOCOL_QUERY_IMPLEMENTATION_LIMITS, ProtocolQueryImplementationError, validateProtocolQueryImplementation, validateProtocolSqlExpression, } from './query-implementations/index.js';
 export { DEFAULT_PROTOCOL_QUERY_EVENT_LIMITS, ProtocolQueryDiagnosticsError, ProtocolQueryEventError, validateProtocolQueryDiagnostics, validateProtocolQueryEvent, } from './events/index.js';
+export { DEFAULT_PROTOCOL_SEMANTIC_INVOCATION_LIMITS, ProtocolSemanticInvocationError, validateProtocolSemanticInvocation, validateProtocolSemanticInvocationFailure, validateProtocolSemanticInvocationResult, } from './invocations/index.js';
 export { DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS, PROTOCOL_DEPLOYMENT_BUNDLE_IDENTITY_DOMAIN, ProtocolDeploymentBundleError, encodeProtocolDeploymentBundleManifest, encodeProtocolDeploymentBundleManifestToString, hashProtocolDeploymentBundleManifest, prepareProtocolDeploymentBundleManifest, validateProtocolDeploymentBundleManifest, } from './bundles/index.js';
 export { DEFAULT_PROTOCOL_DEPLOYMENT_RELEASE_LIMITS, PROTOCOL_DEPLOYMENT_RELEASE_IDENTITY_DOMAIN, ProtocolDeploymentReleaseError, encodeProtocolDeploymentReleaseEnvelope, encodeProtocolDeploymentReleaseEnvelopeToString, hashProtocolDeploymentReleaseEnvelope, prepareProtocolDeploymentReleaseEnvelope, validateProtocolDeploymentReleaseEnvelope, validateProtocolDeploymentReleaseTarget, } from './releases/index.js';
 export { DEFAULT_PROTOCOL_DEPLOYMENT_LIMITS, PROTOCOL_DEPLOYMENT_IDENTITY_DOMAIN, ProtocolDeploymentError, encodeProtocolDeploymentContract, encodeProtocolDeploymentContractToString, hashProtocolDeploymentContract, prepareProtocolDeploymentContract, validateProtocolDatasetContract, validateProtocolDeploymentContract, } from './deployments/index.js';
+export { PROTOCOL_SEMANTIC_FAILURE_MESSAGES } from './invocations/failure-messages.js';

package/dist/invocations/errors.d.ts

@@ -0,0 +1,8 @@
+import type { ProtocolSemanticInvocationErrorCode } from './types.js';
+export declare class ProtocolSemanticInvocationError extends TypeError {
+    readonly code: ProtocolSemanticInvocationErrorCode;
+    readonly path: string;
+    constructor(code: ProtocolSemanticInvocationErrorCode, path?: string);
+}
+export declare function invocationError(code: ProtocolSemanticInvocationErrorCode, path?: string): never;
+//# sourceMappingURL=errors.d.ts.map

package/dist/invocations/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/invocations/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mCAAmC,EAAE,MAAM,YAAY,CAAC;AAEtE,qBAAa,+BAAgC,SAAQ,SAAS;IAC5D,QAAQ,CAAC,IAAI,EAAE,mCAAmC,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,mCAAmC,EAAE,IAAI,SAAM;CAMlE;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,mCAAmC,EACzC,IAAI,SAAM,GACT,KAAK,CAEP"}

package/dist/invocations/errors.js

@@ -0,0 +1,13 @@
+export class ProtocolSemanticInvocationError extends TypeError {
+    code;
+    path;
+    constructor(code, path = '$') {
+        super(`${code} at ${path}`);
+        this.name = 'ProtocolSemanticInvocationError';
+        this.code = code;
+        this.path = path;
+    }
+}
+export function invocationError(code, path = '$') {
+    throw new ProtocolSemanticInvocationError(code, path);
+}

package/dist/invocations/failure-messages.d.ts

@@ -0,0 +1,4 @@
+import type { ProtocolSemanticInvocationFailureCategory } from './types.js';
+/** Fixed public messages; provider exceptions belong only in private logs. */
+export declare const PROTOCOL_SEMANTIC_FAILURE_MESSAGES: Readonly<Record<ProtocolSemanticInvocationFailureCategory, string>>;
+//# sourceMappingURL=failure-messages.d.ts.map

package/dist/invocations/failure-messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-messages.d.ts","sourceRoot":"","sources":["../../src/invocations/failure-messages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yCAAyC,EAAE,MAAM,YAAY,CAAC;AAE5E,8EAA8E;AAC9E,eAAO,MAAM,kCAAkC,EAAE,QAAQ,CAAC,MAAM,CAAC,yCAAyC,EAAE,MAAM,CAAC,CAcjH,CAAC"}

package/dist/invocations/failure-messages.js

@@ -0,0 +1,16 @@
+/** Fixed public messages; provider exceptions belong only in private logs. */
+export const PROTOCOL_SEMANTIC_FAILURE_MESSAGES = Object.freeze({
+    "configuration-invalid": "The execution configuration is invalid.",
+    "not-found": "The requested target was not found.",
+    "unauthenticated": "Authentication is required.",
+    "forbidden": "Access is forbidden.",
+    "tenant-required": "A trusted tenant is required.",
+    "input-invalid": "The semantic query is invalid.",
+    "budget-exceeded": "The invocation budget was exceeded.",
+    "cancelled": "The invocation was cancelled.",
+    "stale-activation": "The pinned activation is no longer active.",
+    "unsupported-capability": "Portable execution cannot reproduce this target.",
+    "executor-unavailable": "The executor is unavailable.",
+    "executor-failed": "The executor failed.",
+    "output-invalid": "The executor returned an invalid result."
+});

package/dist/invocations/index.d.ts

@@ -0,0 +1,6 @@
+export { PROTOCOL_SEMANTIC_FAILURE_MESSAGES } from './failure-messages.js';
+export { ProtocolSemanticInvocationError } from './errors.js';
+export { DEFAULT_PROTOCOL_SEMANTIC_INVOCATION_LIMITS } from './limits.js';
+export { validateProtocolSemanticInvocation, validateProtocolSemanticInvocationFailure, validateProtocolSemanticInvocationResult, } from './validate.js';
+export type { ProtocolSemanticInvocation, ProtocolSemanticInvocationBudget, ProtocolSemanticInvocationErrorCode, ProtocolSemanticInvocationFailure, ProtocolSemanticInvocationFailureCategory, ProtocolSemanticInvocationLimits, ProtocolSemanticInvocationMeta, ProtocolSemanticInvocationOptions, ProtocolSemanticInvocationPagination, ProtocolSemanticInvocationResult, ProtocolSemanticInvocationRow, ProtocolSemanticInvocationTarget, ProtocolSemanticInvocationValue, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/invocations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/invocations/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kCAAkC,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAE,+BAA+B,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,2CAA2C,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EACL,kCAAkC,EAClC,yCAAyC,EACzC,wCAAwC,GACzC,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,0BAA0B,EAC1B,gCAAgC,EAChC,mCAAmC,EACnC,iCAAiC,EACjC,yCAAyC,EACzC,gCAAgC,EAChC,8BAA8B,EAC9B,iCAAiC,EACjC,oCAAoC,EACpC,gCAAgC,EAChC,6BAA6B,EAC7B,gCAAgC,EAChC,+BAA+B,GAChC,MAAM,YAAY,CAAC"}

package/dist/invocations/index.js

@@ -0,0 +1,4 @@
+export { PROTOCOL_SEMANTIC_FAILURE_MESSAGES } from './failure-messages.js';
+export { ProtocolSemanticInvocationError } from './errors.js';
+export { DEFAULT_PROTOCOL_SEMANTIC_INVOCATION_LIMITS } from './limits.js';
+export { validateProtocolSemanticInvocation, validateProtocolSemanticInvocationFailure, validateProtocolSemanticInvocationResult, } from './validate.js';

package/dist/invocations/limits.d.ts

@@ -0,0 +1,4 @@
+import type { ProtocolSemanticInvocationLimits, ProtocolSemanticInvocationOptions } from './types.js';
+export declare const DEFAULT_PROTOCOL_SEMANTIC_INVOCATION_LIMITS: Readonly<ProtocolSemanticInvocationLimits>;
+export declare function resolveSemanticInvocationLimits(options?: ProtocolSemanticInvocationOptions): Readonly<ProtocolSemanticInvocationLimits>;
+//# sourceMappingURL=limits.d.ts.map

package/dist/invocations/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/invocations/limits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gCAAgC,EAChC,iCAAiC,EAClC,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,2CAA2C,EACxD,QAAQ,CAAC,gCAAgC,CAQvC,CAAC;AAEH,wBAAgB,+BAA+B,CAC7C,OAAO,GAAE,iCAAsC,GAC9C,QAAQ,CAAC,gCAAgC,CAAC,CAe5C"}

package/dist/invocations/limits.js

@@ -0,0 +1,24 @@
+export const DEFAULT_PROTOCOL_SEMANTIC_INVOCATION_LIMITS = Object.freeze({
+    maxTextBytes: 1_024,
+    maxMessageBytes: 1_024,
+    maxRows: 10_000,
+    maxColumnsPerRow: 256,
+    maxValueBytes: 65_536,
+    maxDeadlineMs: 3_600_000,
+    maxResponseBytes: 33_554_432,
+});
+export function resolveSemanticInvocationLimits(options = {}) {
+    const result = { ...DEFAULT_PROTOCOL_SEMANTIC_INVOCATION_LIMITS };
+    for (const key of Object.keys(result)) {
+        const value = options.limits?.[key];
+        if (value === undefined)
+            continue;
+        const maximum = DEFAULT_PROTOCOL_SEMANTIC_INVOCATION_LIMITS[key];
+        if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+            throw new RangeError(`${key} must be a positive safe integer no greater than ${maximum} `
+                + '(the semantic invocation v1 maximum)');
+        }
+        result[key] = value;
+    }
+    return Object.freeze(result);
+}

package/dist/invocations/types.d.ts

@@ -0,0 +1,111 @@
+import type { ProtocolSemanticQuery } from '../expressions/index.js';
+export interface ProtocolSemanticInvocationTarget {
+    readonly project: string;
+    readonly environment: string;
+}
+/**
+ * Caller-requested ceilings. A runtime applies the most restrictive of these,
+ * the endpoint policy, and its own defaults — a caller can tighten a budget but
+ * never widen one.
+ */
+export interface ProtocolSemanticInvocationBudget {
+    readonly deadlineMs?: number;
+    readonly maxRows?: number;
+    readonly maxResponseBytes?: number;
+}
+/**
+ * One dataset or metric invocation against an activated deployment.
+ *
+ * Decision 0002 sketched the dataset/metric name beside the nested query, which
+ * would let the two disagree. It also permits normalizing to a single
+ * identifier location, so the names live only inside `operation`, whose own
+ * `kind` discriminates dataset from metric.
+ *
+ * There is deliberately no tenant field: a caller cannot supply or change a
+ * tenant, which is resolved by the provider callback inside trusted execution
+ * context.
+ */
+export interface ProtocolSemanticInvocation {
+    readonly kind: 'hypequery-semantic-invocation';
+    readonly version: 1;
+    readonly target: ProtocolSemanticInvocationTarget;
+    /** Pins execution to one activation. Omit to accept whichever is active. */
+    readonly activationRevision?: string;
+    readonly operation: ProtocolSemanticQuery;
+    readonly budget?: ProtocolSemanticInvocationBudget;
+    /** External correlation only; never authoritative. */
+    readonly correlationId?: string;
+}
+/**
+ * A result cell. Portable execution returns scalars; anything richer would need
+ * the RFC 0001 tagged value model, which this envelope deliberately does not
+ * pull into result rows.
+ */
+export type ProtocolSemanticInvocationValue = string | number | boolean | null;
+export type ProtocolSemanticInvocationRow = Readonly<Record<string, ProtocolSemanticInvocationValue>>;
+export interface ProtocolSemanticInvocationPagination {
+    readonly limit: number;
+    readonly offset: number;
+    readonly hasMore: boolean;
+}
+export interface ProtocolSemanticInvocationMeta {
+    readonly rowCount: number;
+    readonly pagination?: ProtocolSemanticInvocationPagination;
+}
+/**
+ * The successful result. Operational metadata (trace, timing, cache outcome)
+ * belongs in the transport's own metadata rather than beside the rows shown to
+ * a model, so it is not carried here.
+ */
+export interface ProtocolSemanticInvocationResult {
+    readonly kind: 'hypequery-semantic-invocation-result';
+    readonly version: 1;
+    /** The activation that actually served the call, never the one requested. */
+    readonly activationRevision: string;
+    readonly data: readonly ProtocolSemanticInvocationRow[];
+    readonly meta: ProtocolSemanticInvocationMeta;
+}
+/** Provider-neutral failure categories from decision 0002, plus decision 0005. */
+export type ProtocolSemanticInvocationFailureCategory = 'configuration-invalid' | 'not-found' | 'unauthenticated' | 'forbidden' | 'tenant-required' | 'input-invalid' | 'budget-exceeded' | 'cancelled' | 'stale-activation'
+/** Portable execution cannot reproduce this target exactly. Decision 0005. */
+ | 'unsupported-capability' | 'executor-unavailable' | 'executor-failed' | 'output-invalid';
+/**
+ * A failed invocation. Closed by construction: there is no field that accepts
+ * SQL, parameter values, tenant identifiers, physical source details, stack
+ * traces, or a provider exception.
+ */
+export interface ProtocolSemanticInvocationFailure {
+    readonly kind: 'hypequery-semantic-invocation-failure';
+    readonly version: 1;
+    readonly category: ProtocolSemanticInvocationFailureCategory;
+    /** Stable machine-readable code, e.g. `HQ_SEMANTIC_TENANT_REQUIRED`. */
+    readonly code: string;
+    readonly message: string;
+    /** Bounded input path for a correctable failure, e.g. `$.operation.limit`. */
+    readonly path?: string;
+    readonly retryable: boolean;
+    /** The caller must re-read discovery before retrying. */
+    readonly relist: boolean;
+    readonly activationRevision?: string;
+}
+export interface ProtocolSemanticInvocationLimits {
+    readonly maxTextBytes: number;
+    readonly maxMessageBytes: number;
+    readonly maxRows: number;
+    readonly maxColumnsPerRow: number;
+    readonly maxValueBytes: number;
+    readonly maxDeadlineMs: number;
+    readonly maxResponseBytes: number;
+}
+/**
+ * Validation budgets for a semantic invocation.
+ *
+ * Each configured value must be a positive safe integer no greater than the
+ * corresponding value in `DEFAULT_PROTOCOL_SEMANTIC_INVOCATION_LIMITS`. These
+ * options may tighten the v1 conformance limits but cannot raise them.
+ */
+export interface ProtocolSemanticInvocationOptions {
+    readonly limits?: Partial<ProtocolSemanticInvocationLimits>;
+}
+export type ProtocolSemanticInvocationErrorCode = 'HQ_INVOCATION_TYPE' | 'HQ_INVOCATION_UNKNOWN_FIELD' | 'HQ_INVOCATION_INVALID_VERSION' | 'HQ_INVOCATION_INVALID_VALUE' | 'HQ_INVOCATION_TOO_MANY_ITEMS' | 'HQ_INVOCATION_TOO_LARGE' | 'HQ_INVOCATION_UNSAFE_OBJECT';
+//# sourceMappingURL=types.d.ts.map

package/dist/invocations/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/invocations/types.ts"],"names":[],"mappings":"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"}

package/dist/invocations/types.js

@@ -0,0 +1 @@
+export {};

package/dist/invocations/validate.d.ts

@@ -0,0 +1,8 @@
+import type { ProtocolSemanticInvocation, ProtocolSemanticInvocationFailure, ProtocolSemanticInvocationOptions, ProtocolSemanticInvocationResult } from './types.js';
+/** Validate one dataset or metric invocation request. */
+export declare function validateProtocolSemanticInvocation(input: unknown, options?: ProtocolSemanticInvocationOptions): ProtocolSemanticInvocation;
+/** Validate a successful invocation result before it is returned or cached. */
+export declare function validateProtocolSemanticInvocationResult(input: unknown, options?: ProtocolSemanticInvocationOptions): ProtocolSemanticInvocationResult;
+/** Validate a failed invocation before it crosses a trust boundary. */
+export declare function validateProtocolSemanticInvocationFailure(input: unknown, options?: ProtocolSemanticInvocationOptions): ProtocolSemanticInvocationFailure;
+//# sourceMappingURL=validate.d.ts.map

package/dist/invocations/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/invocations/validate.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,0BAA0B,EAE1B,iCAAiC,EAGjC,iCAAiC,EACjC,gCAAgC,EAGjC,MAAM,YAAY,CAAC;AA+KpB,yDAAyD;AACzD,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,iCAAsC,GAC9C,0BAA0B,CAgC5B;AAyED,+EAA+E;AAC/E,wBAAgB,wCAAwC,CACtD,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,iCAAsC,GAC9C,gCAAgC,CAiBlC;AAED,uEAAuE;AACvE,wBAAgB,yCAAyC,CACvD,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,iCAAsC,GAC9C,iCAAiC,CAyCnC"}

package/dist/invocations/validate.js

@@ -0,0 +1,306 @@
+import { ProtocolExpressionError, validateProtocolSemanticQuery } from '../expressions/index.js';
+import { PROTOCOL_SEMANTIC_FAILURE_MESSAGES } from './failure-messages.js';
+import { invocationError } from './errors.js';
+import { resolveSemanticInvocationLimits } from './limits.js';
+const HEX64_PATTERN = /^[0-9a-f]{64}$/;
+const FAILURE_CATEGORIES = [
+    'configuration-invalid',
+    'not-found',
+    'unauthenticated',
+    'forbidden',
+    'tenant-required',
+    'input-invalid',
+    'budget-exceeded',
+    'cancelled',
+    'stale-activation',
+    'unsupported-capability',
+    'executor-unavailable',
+    'executor-failed',
+    'output-invalid',
+];
+const FAILURE_CODE_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+const textEncoder = new TextEncoder();
+function requireRecord(input, path) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        invocationError('HQ_INVOCATION_TYPE', path);
+    }
+    const prototype = Object.getPrototypeOf(input);
+    if (prototype !== Object.prototype && prototype !== null) {
+        invocationError('HQ_INVOCATION_UNSAFE_OBJECT', path);
+    }
+    if (Object.getOwnPropertySymbols(input).length > 0) {
+        invocationError('HQ_INVOCATION_UNSAFE_OBJECT', path);
+    }
+    for (const descriptor of Object.values(Object.getOwnPropertyDescriptors(input))) {
+        if (!descriptor.enumerable || !('value' in descriptor)) {
+            invocationError('HQ_INVOCATION_UNSAFE_OBJECT', path);
+        }
+    }
+    return input;
+}
+function requireArray(input, path, maximum) {
+    if (!Array.isArray(input))
+        invocationError('HQ_INVOCATION_TYPE', path);
+    if (input.length > maximum)
+        invocationError('HQ_INVOCATION_TOO_MANY_ITEMS', path);
+    if (Object.getPrototypeOf(input) !== Array.prototype || Object.getOwnPropertySymbols(input).length > 0) {
+        invocationError('HQ_INVOCATION_UNSAFE_OBJECT', path);
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(input);
+    if (Object.keys(descriptors).length !== input.length + 1) {
+        invocationError('HQ_INVOCATION_UNSAFE_OBJECT', path);
+    }
+    for (let index = 0; index < input.length; index++) {
+        const descriptor = descriptors[String(index)];
+        if (!descriptor || !descriptor.enumerable || !('value' in descriptor)) {
+            invocationError('HQ_INVOCATION_UNSAFE_OBJECT', path);
+        }
+    }
+    return input;
+}
+function exactFields(value, required, optional, path) {
+    const allowed = new Set([...required, ...optional]);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key))
+            invocationError('HQ_INVOCATION_UNKNOWN_FIELD', `${path}.${key}`);
+    }
+    for (const key of required) {
+        if (!Object.hasOwn(value, key))
+            invocationError('HQ_INVOCATION_TYPE', `${path}.${key}`);
+    }
+}
+function freezeRecord(entries) {
+    return Object.freeze(Object.assign(Object.create(null), entries));
+}
+function hasControlCharacter(text) {
+    for (let index = 0; index < text.length; index += 1) {
+        const code = text.charCodeAt(index);
+        if (code <= 0x1f || (code >= 0x7f && code <= 0x9f))
+            return true;
+    }
+    return false;
+}
+function boundedText(value, path, maximum) {
+    if (typeof value !== 'string')
+        invocationError('HQ_INVOCATION_TYPE', path);
+    if (value.length > maximum || textEncoder.encode(value).byteLength > maximum) {
+        invocationError('HQ_INVOCATION_TOO_LARGE', path);
+    }
+    if (hasControlCharacter(value))
+        invocationError('HQ_INVOCATION_INVALID_VALUE', path);
+    return value;
+}
+function boundedInteger(value, path, maximum) {
+    if (typeof value !== 'number')
+        invocationError('HQ_INVOCATION_TYPE', path);
+    if (!Number.isSafeInteger(value) || value < 1) {
+        invocationError('HQ_INVOCATION_INVALID_VALUE', path);
+    }
+    if (value > maximum)
+        invocationError('HQ_INVOCATION_TOO_LARGE', path);
+    return value;
+}
+function nonNegativeInteger(value, path, maximum) {
+    if (typeof value !== 'number')
+        invocationError('HQ_INVOCATION_TYPE', path);
+    if (!Number.isSafeInteger(value) || value < 0) {
+        invocationError('HQ_INVOCATION_INVALID_VALUE', path);
+    }
+    if (value > maximum)
+        invocationError('HQ_INVOCATION_TOO_LARGE', path);
+    return value;
+}
+function requireBoolean(value, path) {
+    if (typeof value !== 'boolean')
+        invocationError('HQ_INVOCATION_TYPE', path);
+    return value;
+}
+function activationRevision(value, path) {
+    if (typeof value !== 'string')
+        invocationError('HQ_INVOCATION_TYPE', path);
+    if (!HEX64_PATTERN.test(value))
+        invocationError('HQ_INVOCATION_INVALID_VALUE', path);
+    return value;
+}
+function requireVersion(value, kind, path) {
+    if (value.kind !== kind) {
+        if (typeof value.kind !== 'string')
+            invocationError('HQ_INVOCATION_TYPE', `${path}.kind`);
+        invocationError('HQ_INVOCATION_INVALID_VALUE', `${path}.kind`);
+    }
+    if (value.version !== 1) {
+        if (typeof value.version !== 'number')
+            invocationError('HQ_INVOCATION_TYPE', `${path}.version`);
+        invocationError('HQ_INVOCATION_INVALID_VERSION', `${path}.version`);
+    }
+}
+function target(input, path, limits) {
+    const value = requireRecord(input, path);
+    exactFields(value, ['project', 'environment'], [], path);
+    const result = {};
+    for (const key of ['project', 'environment']) {
+        const text = boundedText(value[key], `${path}.${key}`, limits.maxTextBytes);
+        if (!/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(text)) {
+            invocationError('HQ_INVOCATION_INVALID_VALUE', `${path}.${key}`);
+        }
+        result[key] = text;
+    }
+    return freezeRecord(result);
+}
+function budget(input, path, limits) {
+    const value = requireRecord(input, path);
+    exactFields(value, [], ['deadlineMs', 'maxRows', 'maxResponseBytes'], path);
+    const result = {};
+    if (value.deadlineMs !== undefined) {
+        result.deadlineMs = boundedInteger(value.deadlineMs, `${path}.deadlineMs`, limits.maxDeadlineMs);
+    }
+    if (value.maxRows !== undefined) {
+        result.maxRows = boundedInteger(value.maxRows, `${path}.maxRows`, limits.maxRows);
+    }
+    if (value.maxResponseBytes !== undefined) {
+        result.maxResponseBytes = boundedInteger(value.maxResponseBytes, `${path}.maxResponseBytes`, limits.maxResponseBytes);
+    }
+    // An empty budget is indistinguishable from omitting the field, and two
+    // encodings of the same request are not portable.
+    if (Object.keys(result).length === 0)
+        invocationError('HQ_INVOCATION_INVALID_VALUE', path);
+    return freezeRecord(result);
+}
+/** Validate one dataset or metric invocation request. */
+export function validateProtocolSemanticInvocation(input, options = {}) {
+    const limits = resolveSemanticInvocationLimits(options);
+    const value = requireRecord(input, '$');
+    exactFields(value, ['kind', 'version', 'target', 'operation'], ['activationRevision', 'budget', 'correlationId'], '$');
+    requireVersion(value, 'hypequery-semantic-invocation', '$');
+    const result = {
+        kind: 'hypequery-semantic-invocation',
+        version: 1,
+        target: target(value.target, '$.target', limits),
+        operation: semanticQuery(value.operation, '$.operation'),
+    };
+    if (value.activationRevision !== undefined) {
+        result.activationRevision = activationRevision(value.activationRevision, '$.activationRevision');
+    }
+    if (value.budget !== undefined)
+        result.budget = budget(value.budget, '$.budget', limits);
+    if (value.correlationId !== undefined) {
+        result.correlationId = boundedText(value.correlationId, '$.correlationId', limits.maxTextBytes);
+    }
+    return freezeRecord(result);
+}
+function semanticQuery(input, path) {
+    try {
+        return validateProtocolSemanticQuery(input);
+    }
+    catch (error) {
+        if (error instanceof ProtocolExpressionError) {
+            invocationError('HQ_INVOCATION_INVALID_VALUE', path);
+        }
+        throw error;
+    }
+}
+function row(input, path, limits) {
+    const value = requireRecord(input, path);
+    const keys = Object.keys(value);
+    if (keys.length > limits.maxColumnsPerRow) {
+        invocationError('HQ_INVOCATION_TOO_MANY_ITEMS', path);
+    }
+    const result = {};
+    for (const key of keys) {
+        const cell = value[key];
+        const cellPath = `${path}.${key}`;
+        if (cell === null || typeof cell === 'boolean') {
+            result[key] = cell;
+        }
+        else if (typeof cell === 'number') {
+            // A non-finite number has no portable JSON encoding.
+            if (!Number.isFinite(cell))
+                invocationError('HQ_INVOCATION_INVALID_VALUE', cellPath);
+            result[key] = cell;
+        }
+        else if (typeof cell === 'string') {
+            if (textEncoder.encode(cell).byteLength > limits.maxValueBytes) {
+                invocationError('HQ_INVOCATION_TOO_LARGE', cellPath);
+            }
+            if (hasControlCharacter(cell))
+                invocationError('HQ_INVOCATION_INVALID_VALUE', cellPath);
+            result[key] = cell;
+        }
+        else {
+            invocationError('HQ_INVOCATION_TYPE', cellPath);
+        }
+    }
+    return freezeRecord(result);
+}
+function meta(input, path, limits, rowCount) {
+    const value = requireRecord(input, path);
+    exactFields(value, ['rowCount'], ['pagination'], path);
+    const declared = nonNegativeInteger(value.rowCount, `${path}.rowCount`, limits.maxRows);
+    // A rowCount that disagrees with the rows it describes is a broken result,
+    // not a hint — the caller would page or aggregate on a false total.
+    if (declared !== rowCount)
+        invocationError('HQ_INVOCATION_INVALID_VALUE', `${path}.rowCount`);
+    const result = { rowCount: declared };
+    if (value.pagination !== undefined) {
+        const paginationPath = `${path}.pagination`;
+        const pagination = requireRecord(value.pagination, paginationPath);
+        exactFields(pagination, ['limit', 'offset', 'hasMore'], [], paginationPath);
+        result.pagination = freezeRecord({
+            limit: boundedInteger(pagination.limit, `${paginationPath}.limit`, limits.maxRows),
+            offset: nonNegativeInteger(pagination.offset, `${paginationPath}.offset`, Number.MAX_SAFE_INTEGER),
+            hasMore: requireBoolean(pagination.hasMore, `${paginationPath}.hasMore`),
+        });
+    }
+    return freezeRecord(result);
+}
+/** Validate a successful invocation result before it is returned or cached. */
+export function validateProtocolSemanticInvocationResult(input, options = {}) {
+    const limits = resolveSemanticInvocationLimits(options);
+    const value = requireRecord(input, '$');
+    exactFields(value, ['kind', 'version', 'activationRevision', 'data', 'meta'], [], '$');
+    requireVersion(value, 'hypequery-semantic-invocation-result', '$');
+    const rows = requireArray(value.data, '$.data', limits.maxRows);
+    const data = Object.freeze(rows.map((entry, index) => row(entry, `$.data[${index}]`, limits)));
+    return freezeRecord({
+        kind: 'hypequery-semantic-invocation-result',
+        version: 1,
+        activationRevision: activationRevision(value.activationRevision, '$.activationRevision'),
+        data,
+        meta: meta(value.meta, '$.meta', limits, data.length),
+    });
+}
+/** Validate a failed invocation before it crosses a trust boundary. */
+export function validateProtocolSemanticInvocationFailure(input, options = {}) {
+    const limits = resolveSemanticInvocationLimits(options);
+    const value = requireRecord(input, '$');
+    exactFields(value, ['kind', 'version', 'category', 'code', 'message', 'retryable', 'relist'], ['path', 'activationRevision'], '$');
+    requireVersion(value, 'hypequery-semantic-invocation-failure', '$');
+    if (typeof value.category !== 'string')
+        invocationError('HQ_INVOCATION_TYPE', '$.category');
+    if (!FAILURE_CATEGORIES.includes(value.category)) {
+        invocationError('HQ_INVOCATION_INVALID_VALUE', '$.category');
+    }
+    const message = boundedText(value.message, '$.message', limits.maxMessageBytes);
+    if (message !== PROTOCOL_SEMANTIC_FAILURE_MESSAGES[value.category]) {
+        invocationError('HQ_INVOCATION_INVALID_VALUE', '$.message');
+    }
+    const code = boundedText(value.code, '$.code', limits.maxTextBytes);
+    if (!FAILURE_CODE_PATTERN.test(code))
+        invocationError('HQ_INVOCATION_INVALID_VALUE', '$.code');
+    const result = {
+        kind: 'hypequery-semantic-invocation-failure',
+        version: 1,
+        category: value.category,
+        code,
+        message,
+        retryable: requireBoolean(value.retryable, '$.retryable'),
+        relist: requireBoolean(value.relist, '$.relist'),
+    };
+    if (value.path !== undefined) {
+        result.path = boundedText(value.path, '$.path', limits.maxTextBytes);
+    }
+    if (value.activationRevision !== undefined) {
+        result.activationRevision = activationRevision(value.activationRevision, '$.activationRevision');
+    }
+    return freezeRecord(result);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/protocol",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "description": "Portable analytics contracts and TypeScript reference implementation for Hypequery",
   "keywords": [
     "hypequery",