@hypequery/deployment 0.7.5 → 0.8.0

package/dist/authorized-contract.d.ts

@@ -0,0 +1,101 @@
+/**
+ * What one principal is allowed to see of a deployment contract.
+ *
+ * Discovery and execution must agree about who may reach what. The data plane
+ * already decides that per call, from the endpoint policy on the target; a
+ * gateway listing tools has to make the same decision over the whole contract,
+ * before any call exists. Restating the rule there would put an authorization
+ * predicate in two packages, and the copy that drifts is the one that leaks.
+ *
+ * The projection narrows, never widens: it can remove a target a principal may
+ * not reach, and can never add one or loosen a policy. Feeding the result to
+ * catalog projection or schema compilation therefore cannot advertise something
+ * execution would refuse.
+ */
+import type { ProtocolAccessPolicy, ProtocolDeploymentContract, ProtocolEndpointPolicy } from '@hypequery/protocol';
+import type { DeploymentDataPlanePrincipal } from './data-plane.js';
+/**
+ * Whether a principal satisfies an access policy.
+ *
+ * Shares `missing` with the semantic data plane rather than restating it, which
+ * is the whole point of this module existing in Core: one predicate, so
+ * discovery cannot come to answer differently than execution.
+ */
+export declare function satisfiesDeploymentAccess(access: ProtocolAccessPolicy, principal: DeploymentDataPlanePrincipal | null): boolean;
+/** Whether a principal may reach a target published under this endpoint policy. */
+export declare function isDeploymentEndpointAuthorized(endpoint: ProtocolEndpointPolicy | undefined, principal: DeploymentDataPlanePrincipal | null): boolean;
+export interface AuthorizedDeploymentProjection {
+    /**
+     * A valid contract narrowed to what the principal may see, including any
+     * dataset retained only to support a join or a named query.
+     */
+    readonly contract: ProtocolDeploymentContract;
+    /**
+     * Datasets to advertise at all, in contract order.
+     *
+     * Wider than `queryable`: a dataset the principal cannot address may still
+     * carry a metric it can, and hiding the dataset would hide that metric.
+     * Narrower than `contract.datasets`, which also holds datasets retained only
+     * to support a join.
+     *
+     * Always read this before advertising anything. Catalog projection and
+     * rehydration enumerate every dataset they are given and neither consults an
+     * endpoint, so handing them the whole contract would advertise a supporting
+     * dataset and disclose its dimensions and measures to a principal with no
+     * access to it.
+     */
+    readonly advertised: readonly string[];
+    /**
+     * Datasets addressable as a `query_dataset` target. A subset of `advertised`.
+     *
+     * The two differ because a deployment authorizes a dataset and each of its
+     * metrics through separate endpoint policies. Collapsing them would either
+     * offer a target execution refuses or withhold a metric it would run.
+     *
+     * The intended composition rehydrates the whole contract, so relationship
+     * targets still resolve, and advertises the two sets separately:
+     *
+     * ```ts
+     * const { contract, advertised, queryable } =
+     *   projectAuthorizedDeploymentContract(active, principal);
+     * const registry = rehydrateProtocolDatasets(contract.datasets, { onUnsupportedMetric: 'skip' });
+     * createMCPDiscoveryExecutor({
+     *   datasets: Object.fromEntries(advertised.map(name => [name, registry[name]])),
+     *   queryableDatasets: queryable,
+     * });
+     * ```
+     *
+     * A joined dimension such as `orders.employee.id` still resolves through the
+     * full registry, which is correct: that join is governed by the endpoint of
+     * the dataset being queried, not by the target's.
+     */
+    readonly queryable: readonly string[];
+}
+/**
+ * Projects the contract down to what `principal` may see.
+ *
+ * A dataset is *published* when the principal may address it directly, and
+ * *supporting* when something published still needs it to stay coherent — the
+ * target of a relationship, or the dataset a named query plans over. A
+ * supporting dataset keeps its shape and loses its endpoint and metrics, so a
+ * relationship can still be traversed exactly as execution would traverse it
+ * while the dataset itself is not offered as a target.
+ *
+ * Dropping a relationship target instead would be the tempting alternative and
+ * is wrong twice: it would invalidate any metric declaring a dimension across
+ * that relationship, and it would advertise less than the data plane permits,
+ * since a one-hop join is governed by the endpoint of the dataset being
+ * queried, not by the target's.
+ *
+ * The two are returned separately rather than as one contract because nothing
+ * downstream reads an endpoint. `projectAgentSafeCatalog` and
+ * `rehydrateProtocolDatasets` enumerate whatever they are handed, so an
+ * unpublished dataset left in the contract they see is an advertised one.
+ *
+ * The contract is revalidated. Callers hand it to catalog projection, schema
+ * compilation, and rehydration, all of which assume a valid contract; a
+ * projection that could emit an invalid one would move that failure to whatever
+ * read it next.
+ */
+export declare function projectAuthorizedDeploymentContract(contract: ProtocolDeploymentContract, principal: DeploymentDataPlanePrincipal | null): AuthorizedDeploymentProjection;
+//# sourceMappingURL=authorized-contract.d.ts.map

package/dist/authorized-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorized-contract.d.ts","sourceRoot":"","sources":["../src/authorized-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,oBAAoB,EAEpB,0BAA0B,EAC1B,sBAAsB,EACvB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAGpE;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,oBAAoB,EAC5B,SAAS,EAAE,4BAA4B,GAAG,IAAI,GAC7C,OAAO,CAIT;AAED,mFAAmF;AACnF,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,sBAAsB,GAAG,SAAS,EAC5C,SAAS,EAAE,4BAA4B,GAAG,IAAI,GAC7C,OAAO,CAKT;AA4GD,MAAM,WAAW,8BAA8B;IAC7C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,CAAC;IAC9C;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,0BAA0B,EACpC,SAAS,EAAE,4BAA4B,GAAG,IAAI,GAC7C,8BAA8B,CA8FhC"}

package/dist/index.d.ts

@@ -34,4 +34,9 @@ export { createDeploymentHost, DeploymentHostError, } from './host.js';
 export { createFileSystemDeploymentHost } from './filesystem-host.js';
 export type { FileSystemDeploymentHost, FileSystemDeploymentHostOptions, } from './filesystem-host.js';
 export type { DeploymentHost, DeploymentHostDataPlaneConfiguration, DeploymentHostDataPlaneInput, DeploymentHostErrorCode, DeploymentHostOptions, } from './host.js';
+export { createDeploymentSemanticDataPlane, DeploymentSemanticInvocationError, toProtocolSemanticInvocationFailure, } from './semantic-data-plane.js';
+export type { DeploymentSemanticAuthenticationInput, DeploymentSemanticBudget, DeploymentSemanticDataPlane, DeploymentSemanticDataPlaneOptions, DeploymentSemanticExecutionInput, DeploymentSemanticInvocationRequest, DeploymentSemanticTenantInput, } from './semantic-data-plane.js';
+export { validateSemanticOperation } from './semantic-operation-validation.js';
+export type { SemanticOperationLimits, SemanticOperationViolation, } from './semantic-operation-validation.js';
+export { isDeploymentEndpointAuthorized, projectAuthorizedDeploymentContract, satisfiesDeploymentAccess, } from './authorized-contract.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":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -16,3 +16,9 @@ export { createDeploymentRuntimeSupervisorExecutor } from './data-plane-runtime.
 export { createDeploymentDataPlaneFetchHandler, createDeploymentDataPlaneNodeHandler, } from './data-plane-adapters.js';
 export { createDeploymentHost, DeploymentHostError, } from './host.js';
 export { createFileSystemDeploymentHost } from './filesystem-host.js';
+// Semantic invocation beside named-query execution (decision 0002).
+export { createDeploymentSemanticDataPlane, DeploymentSemanticInvocationError, toProtocolSemanticInvocationFailure, } from './semantic-data-plane.js';
+export { validateSemanticOperation } from './semantic-operation-validation.js';
+// What one principal may see of a contract, for a gateway listing targets
+// before any call exists (decision 0002, CLOUD-03).
+export { isDeploymentEndpointAuthorized, projectAuthorizedDeploymentContract, satisfiesDeploymentAccess, } from './authorized-contract.js';

package/dist/semantic-data-plane.d.ts

@@ -0,0 +1,74 @@
+export { DeploymentSemanticInvocationError, toProtocolSemanticInvocationFailure } from './semantic-invocation-errors.js';
+/**
+ * Semantic invocation beside named-query execution.
+ *
+ * Decision 0002 requires a dataset or metric call to run the same enforcement
+ * sequence a named query does — select the active generation, resolve the
+ * target from its validated contract, authenticate, enforce roles and scopes,
+ * resolve tenant, apply the most restrictive budget, validate input, execute,
+ * then validate and bound the output.
+ *
+ * Execution itself is injected. This module decides whether a call is allowed
+ * and what it is allowed to ask for; `CORE-12` supplies the executor that
+ * answers it.
+ */
+import type { ProtocolDatasetContract, ProtocolDatasetMetric, ProtocolDeploymentContract, ProtocolSemanticInvocation, ProtocolSemanticInvocationResult, ProtocolSemanticQuery } from '@hypequery/protocol';
+import type { DeploymentDataPlanePrincipal } from './data-plane.js';
+import { type SemanticOperationLimits } from './semantic-operation-validation.js';
+/** The ceilings that survived after every source was applied. */
+export interface DeploymentSemanticBudget {
+    readonly maxRows: number;
+    readonly deadlineMs?: number;
+    readonly maxResponseBytes?: number;
+}
+export interface DeploymentSemanticAuthenticationInput {
+    readonly credentials: unknown;
+    readonly invocation: ProtocolSemanticInvocation;
+    readonly dataset: ProtocolDatasetContract;
+    readonly metric?: ProtocolDatasetMetric;
+}
+export interface DeploymentSemanticTenantInput {
+    readonly principal: DeploymentDataPlanePrincipal | null;
+    readonly invocation: ProtocolSemanticInvocation;
+    readonly dataset: ProtocolDatasetContract;
+    readonly metric?: ProtocolDatasetMetric;
+}
+export interface DeploymentSemanticExecutionInput {
+    readonly deployment: ProtocolDeploymentContract;
+    readonly dataset: ProtocolDatasetContract;
+    readonly metric?: ProtocolDatasetMetric;
+    readonly operation: ProtocolSemanticQuery;
+    readonly principal: DeploymentDataPlanePrincipal | null;
+    /**
+     * Resolved by the provider callback. Never a caller-supplied value — the
+     * invocation record has no field that could carry one.
+     */
+    readonly tenant: unknown;
+    readonly budget: DeploymentSemanticBudget;
+    readonly activationRevision: string;
+    readonly signal?: AbortSignal;
+}
+export interface DeploymentSemanticInvocationRequest {
+    /** An unvalidated invocation record; validated before anything else runs. */
+    readonly invocation: unknown;
+    readonly credentials?: unknown;
+    readonly signal?: AbortSignal;
+}
+export interface DeploymentSemanticDataPlaneOptions {
+    readonly deployment: ProtocolDeploymentContract;
+    /** The immutable generation this data plane serves. */
+    readonly activationRevision: string;
+    readonly authenticate?: (input: DeploymentSemanticAuthenticationInput) => Promise<DeploymentDataPlanePrincipal | null>;
+    readonly resolveTenant?: (input: DeploymentSemanticTenantInput) => Promise<unknown>;
+    readonly execute: (input: DeploymentSemanticExecutionInput) => Promise<unknown>;
+    /** Server-side ceilings, applied on top of contract and caller limits. */
+    readonly limits?: Partial<SemanticOperationLimits> & {
+        readonly deadlineMs?: number;
+        readonly maxResponseBytes?: number;
+    };
+}
+export interface DeploymentSemanticDataPlane {
+    invoke(request: DeploymentSemanticInvocationRequest): Promise<ProtocolSemanticInvocationResult>;
+}
+export declare function createDeploymentSemanticDataPlane(options: DeploymentSemanticDataPlaneOptions): DeploymentSemanticDataPlane;
+//# sourceMappingURL=semantic-data-plane.d.ts.map

package/dist/semantic-data-plane.d.ts.map

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

package/dist/semantic-data-plane.js

@@ -0,0 +1,224 @@
+import { claimedFailure } from './utils/semantic-executor-failure.js';
+import { DeploymentSemanticInvocationError, fail, throwIfAborted } from './semantic-invocation-errors.js';
+export { DeploymentSemanticInvocationError, toProtocolSemanticInvocationFailure } from './semantic-invocation-errors.js';
+import { definedLimits, lowest, tighten } from './utils/semantic-budget-limits.js';
+import { missing } from './utils/required-access.js';
+import { ProtocolSemanticInvocationError, validateProtocolDeploymentContract, validateProtocolSemanticInvocation, validateProtocolSemanticInvocationResult, } from '@hypequery/protocol';
+import { validateSemanticOperation, } from './semantic-operation-validation.js';
+const DEFAULT_LIMITS = Object.freeze({
+    maxRows: 10_000,
+    maxOffset: 10_000,
+    maxDimensions: 50,
+    maxMeasures: 50,
+    maxFilters: 100,
+});
+const REVISION_PATTERN = /^[0-9a-f]{64}$/;
+export function createDeploymentSemanticDataPlane(options) {
+    let deployment;
+    try {
+        deployment = validateProtocolDeploymentContract(options.deployment);
+    }
+    catch (error) {
+        throw new DeploymentSemanticInvocationError('configuration-invalid', 'HQ_SEMANTIC_CONFIGURATION', 'The semantic data plane requires a valid deployment contract.', { cause: error });
+    }
+    if (!REVISION_PATTERN.test(options.activationRevision)) {
+        throw new RangeError('activationRevision must be a lowercase SHA-256 identity');
+    }
+    const datasets = new Map(deployment.datasets.map(entry => [String(entry.name), entry]));
+    // Spreading `options.limits` directly would let an explicitly `undefined`
+    // property erase a default ceiling, and an undefined bound compares false
+    // against everything. A caller that omits a limit gets the default.
+    const configured = { ...DEFAULT_LIMITS, ...definedLimits(options.limits) };
+    function resolveTarget(operation) {
+        const dataset = datasets.get(String(operation.dataset));
+        if (dataset === undefined) {
+            fail('not-found', 'HQ_SEMANTIC_DATASET_NOT_FOUND', 'The dataset was not found.', {
+                path: '$.operation.dataset',
+                relist: true,
+            });
+        }
+        const metric = operation.kind === 'metric'
+            ? dataset.metrics.find(entry => String(entry.name) === String(operation.metric))
+            : undefined;
+        if (operation.kind === 'metric' && metric === undefined) {
+            fail('not-found', 'HQ_SEMANTIC_METRIC_NOT_FOUND', 'The metric was not found.', {
+                path: '$.operation.metric',
+                relist: true,
+            });
+        }
+        // An endpoint policy is what publishes a target. Without one the contract
+        // describes the dataset but never exposed it, so it is not addressable.
+        const endpoint = metric?.endpoint ?? dataset.endpoint;
+        if (endpoint === undefined) {
+            fail('not-found', 'HQ_SEMANTIC_NOT_PUBLISHED', 'The target is not published.', {
+                path: '$.operation',
+                relist: true,
+            });
+        }
+        return { dataset, ...(metric === undefined ? {} : { metric }), endpoint };
+    }
+    async function invoke(request) {
+        throwIfAborted(request.signal);
+        let invocation;
+        try {
+            invocation = validateProtocolSemanticInvocation(request.invocation);
+        }
+        catch (error) {
+            fail('input-invalid', 'HQ_SEMANTIC_INVOCATION_INVALID', 'The invocation record is invalid.', {
+                path: error instanceof ProtocolSemanticInvocationError ? error.path : undefined,
+                cause: error,
+            });
+        }
+        // Pinning is checked before anything else observable, so a stale caller
+        // cannot learn whether a target exists in a generation it may not use.
+        if (invocation.activationRevision !== undefined
+            && invocation.activationRevision !== options.activationRevision) {
+            fail('stale-activation', 'HQ_SEMANTIC_STALE_ACTIVATION', 'The pinned activation is no longer active.', { retryable: true, relist: true });
+        }
+        const operation = invocation.operation;
+        const { dataset, metric, endpoint } = resolveTarget(operation);
+        let principal = null;
+        if (endpoint.access.kind === 'authenticated' && !options.authenticate) {
+            fail('configuration-invalid', 'HQ_SEMANTIC_CONFIGURATION', 'An authenticator is required for this target.');
+        }
+        if (options.authenticate
+            && (endpoint.access.kind === 'authenticated' || request.credentials !== undefined)) {
+            try {
+                principal = await options.authenticate({
+                    credentials: request.credentials, invocation, dataset, ...(metric ? { metric } : {}),
+                });
+            }
+            catch (error) {
+                fail('unauthenticated', 'HQ_SEMANTIC_UNAUTHENTICATED', 'Authentication failed.', { cause: error });
+            }
+        }
+        throwIfAborted(request.signal);
+        if (endpoint.access.kind === 'authenticated') {
+            if (!principal) {
+                fail('unauthenticated', 'HQ_SEMANTIC_UNAUTHENTICATED', 'Authentication is required.');
+            }
+            if (missing(endpoint.access.roles, principal.roles)
+                || missing(endpoint.access.scopes, principal.scopes)) {
+                fail('forbidden', 'HQ_SEMANTIC_FORBIDDEN', 'The principal lacks required access.');
+            }
+        }
+        let tenant;
+        if (endpoint.tenant.kind !== 'not-required') {
+            if (!options.resolveTenant) {
+                if (endpoint.tenant.kind === 'required') {
+                    fail('configuration-invalid', 'HQ_SEMANTIC_CONFIGURATION', 'A tenant resolver is required for this target.');
+                }
+            }
+            else {
+                try {
+                    tenant = await options.resolveTenant({
+                        principal, invocation, dataset, ...(metric ? { metric } : {}),
+                    });
+                }
+                catch (error) {
+                    fail('forbidden', 'HQ_SEMANTIC_FORBIDDEN', 'Tenant resolution failed.', { cause: error });
+                }
+            }
+            if (endpoint.tenant.kind === 'required' && (tenant === undefined || tenant === null)) {
+                fail('tenant-required', 'HQ_SEMANTIC_TENANT_REQUIRED', 'Tenant context is required.');
+            }
+        }
+        throwIfAborted(request.signal);
+        const budget = Object.freeze({
+            maxRows: lowest(invocation.budget?.maxRows, endpoint.maxLimit, dataset.limits?.maxResultSize, configured.maxRows) ?? configured.maxRows,
+            ...(lowest(invocation.budget?.deadlineMs, options.limits?.deadlineMs) === undefined
+                ? {}
+                : { deadlineMs: lowest(invocation.budget?.deadlineMs, options.limits?.deadlineMs) }),
+            ...(lowest(invocation.budget?.maxResponseBytes, options.limits?.maxResponseBytes) === undefined
+                ? {}
+                : {
+                    maxResponseBytes: lowest(invocation.budget?.maxResponseBytes, options.limits?.maxResponseBytes),
+                }),
+        });
+        // Every ceiling the dataset declared binds here, not just the one that
+        // reaches the row budget. `maxDimensions`, `maxMeasures`, and `maxFilters`
+        // are published in the contract precisely so a gateway can apply them
+        // without loading the authoring package, and a set of ceilings where only
+        // one of the four binds is not a set of ceilings.
+        const violations = validateSemanticOperation(operation, dataset, datasets, {
+            maxRows: budget.maxRows,
+            maxOffset: configured.maxOffset,
+            maxDimensions: tighten(dataset.limits?.maxDimensions, configured.maxDimensions),
+            maxMeasures: tighten(dataset.limits?.maxMeasures, configured.maxMeasures),
+            maxFilters: tighten(dataset.limits?.maxFilters, configured.maxFilters),
+        });
+        if (violations.length > 0) {
+            const [first] = violations;
+            fail('input-invalid', 'HQ_SEMANTIC_INPUT_INVALID', first.message, { path: first.path });
+        }
+        throwIfAborted(request.signal);
+        let output;
+        try {
+            output = await options.execute({
+                deployment,
+                dataset,
+                ...(metric === undefined ? {} : { metric }),
+                operation,
+                principal,
+                tenant,
+                budget,
+                activationRevision: options.activationRevision,
+                ...(request.signal === undefined ? {} : { signal: request.signal }),
+            });
+        }
+        catch (error) {
+            if (error instanceof DeploymentSemanticInvocationError)
+                throw error;
+            if (request.signal?.aborted) {
+                fail('cancelled', 'HQ_SEMANTIC_CANCELLED', 'The invocation was cancelled.', { cause: error });
+            }
+            const claimed = claimedFailure(error);
+            if (claimed !== undefined) {
+                fail(claimed.category, claimed.code, claimed.message, {
+                    cause: error,
+                    retryable: claimed.retryable,
+                    relist: claimed.relist,
+                });
+            }
+            fail('executor-failed', 'HQ_SEMANTIC_EXECUTION_FAILED', 'Semantic execution failed.', {
+                cause: error,
+            });
+        }
+        // An executor may ignore the signal and resolve anyway. Every other await
+        // in this sequence is followed by this check; so is the last one.
+        throwIfAborted(request.signal);
+        let result;
+        try {
+            result = validateProtocolSemanticInvocationResult(output);
+        }
+        catch (error) {
+            // An executor that returned something unexpected is an internal fault,
+            // never a correctable caller error.
+            fail('output-invalid', 'HQ_SEMANTIC_OUTPUT_INVALID', 'The executor returned an invalid result.', {
+                cause: error,
+            });
+        }
+        // Protocol validation proves the record is well-formed, not that it honored
+        // this invocation. The bounds this layer computed are enforced here, so an
+        // executor cannot widen them by returning more than it was allowed to.
+        if (result.activationRevision !== options.activationRevision) {
+            fail('output-invalid', 'HQ_SEMANTIC_OUTPUT_INVALID', 'The executor served a different activation than the one selected.');
+        }
+        // The caller's own `limit` is part of what it was allowed to ask for, and
+        // validation already proved it is no larger than the budget. An executor
+        // that returns more rows than were requested widened the request just as
+        // surely as one that exceeded the budget.
+        const maxRows = Math.min(budget.maxRows, operation.limit ?? budget.maxRows);
+        if (result.data.length > maxRows) {
+            fail('budget-exceeded', 'HQ_SEMANTIC_BUDGET_EXCEEDED', `The result has ${result.data.length} rows; the effective limit is ${maxRows}.`);
+        }
+        if (budget.maxResponseBytes !== undefined) {
+            const bytes = new TextEncoder().encode(JSON.stringify(result)).byteLength;
+            if (bytes > budget.maxResponseBytes) {
+                fail('budget-exceeded', 'HQ_SEMANTIC_BUDGET_EXCEEDED', `The result is ${bytes} bytes; the effective limit is ${budget.maxResponseBytes}.`);
+            }
+        }
+        return result;
+    }
+    return Object.freeze({ invoke });
+}

package/dist/semantic-invocation-errors.d.ts

@@ -0,0 +1,30 @@
+import type { ProtocolSemanticInvocationFailure, ProtocolSemanticInvocationFailureCategory } from '@hypequery/protocol';
+/** A failure that already carries the public category a caller should see. */
+export declare class DeploymentSemanticInvocationError extends Error {
+    readonly category: ProtocolSemanticInvocationFailureCategory;
+    readonly code: string;
+    readonly path?: string;
+    readonly retryable: boolean;
+    readonly relist: boolean;
+    constructor(category: ProtocolSemanticInvocationFailureCategory, code: string, message: string, options?: {
+        readonly path?: string;
+        readonly cause?: unknown;
+        readonly retryable?: boolean;
+        readonly relist?: boolean;
+    });
+}
+export declare function fail(category: ProtocolSemanticInvocationFailureCategory, code: string, message: string, options?: {
+    readonly path?: string;
+    readonly cause?: unknown;
+    readonly retryable?: boolean;
+    readonly relist?: boolean;
+}): never;
+/**
+ * Projects a failure onto the portable record.
+ *
+ * The message is deliberately the one this module produced. A cause is never
+ * unwrapped into it, so a provider exception cannot reach a caller.
+ */
+export declare function toProtocolSemanticInvocationFailure(error: unknown, activationRevision?: string): ProtocolSemanticInvocationFailure;
+export declare function throwIfAborted(signal: AbortSignal | undefined): void;
+//# sourceMappingURL=semantic-invocation-errors.d.ts.map

package/dist/semantic-invocation-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-invocation-errors.d.ts","sourceRoot":"","sources":["../src/semantic-invocation-errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iCAAiC,EAAE,yCAAyC,EAAE,MAAM,qBAAqB,CAAC;AAExH,8EAA8E;AAC9E,qBAAa,iCAAkC,SAAQ,KAAK;IAC1D,QAAQ,CAAC,QAAQ,EAAE,yCAAyC,CAAC;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAGvB,QAAQ,EAAE,yCAAyC,EACnD,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;KACtB;CAUT;AAED,wBAAgB,IAAI,CAClB,QAAQ,EAAE,yCAAyC,EACnD,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IACP,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CACtB,GACL,KAAK,CAEP;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,OAAO,EACd,kBAAkB,CAAC,EAAE,MAAM,GAC1B,iCAAiC,CAanC;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,CAIpE"}

package/dist/semantic-invocation-errors.js

@@ -0,0 +1,45 @@
+/** A failure that already carries the public category a caller should see. */
+export class DeploymentSemanticInvocationError extends Error {
+    category;
+    code;
+    path;
+    retryable;
+    relist;
+    constructor(category, code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'DeploymentSemanticInvocationError';
+        this.category = category;
+        this.code = code;
+        this.path = options.path;
+        this.retryable = options.retryable ?? false;
+        this.relist = options.relist ?? false;
+    }
+}
+export function fail(category, code, message, options = {}) {
+    throw new DeploymentSemanticInvocationError(category, code, message, options);
+}
+/**
+ * Projects a failure onto the portable record.
+ *
+ * The message is deliberately the one this module produced. A cause is never
+ * unwrapped into it, so a provider exception cannot reach a caller.
+ */
+export function toProtocolSemanticInvocationFailure(error, activationRevision) {
+    const known = error instanceof DeploymentSemanticInvocationError;
+    return Object.freeze({
+        kind: 'hypequery-semantic-invocation-failure',
+        version: 1,
+        category: known ? error.category : 'executor-failed',
+        code: known ? error.code : 'HQ_SEMANTIC_EXECUTION_FAILED',
+        message: known ? error.message : 'Semantic invocation failed.',
+        ...(known && error.path !== undefined ? { path: error.path } : {}),
+        retryable: known ? error.retryable : false,
+        relist: known ? error.relist : false,
+        ...(activationRevision === undefined ? {} : { activationRevision }),
+    });
+}
+export function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        fail('cancelled', 'HQ_SEMANTIC_CANCELLED', 'The invocation was cancelled.');
+    }
+}

package/dist/semantic-operation-validation.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Contract-driven validation of a semantic operation.
+ *
+ * The deployment package deliberately depends only on `@hypequery/protocol`, so
+ * every check here is made against the validated contract rather than by
+ * loading the authoring package. A gateway must be able to reject a bad
+ * invocation without any of the deploying application's code.
+ */
+import type { ProtocolDatasetContract, ProtocolSemanticQuery } from '@hypequery/protocol';
+export interface SemanticOperationViolation {
+    readonly message: string;
+    readonly path: string;
+}
+export interface SemanticOperationLimits {
+    /** Largest row count the caller may ask for after every ceiling is applied. */
+    readonly maxRows: number;
+    readonly maxOffset: number;
+    readonly maxDimensions: number;
+    readonly maxMeasures: number;
+    readonly maxFilters: number;
+}
+/**
+ * Validates one semantic operation against the contract that will serve it.
+ *
+ * Returns every violation rather than the first, so a caller correcting an
+ * agent-authored query sees the whole problem in one round trip.
+ */
+export declare function validateSemanticOperation(operation: ProtocolSemanticQuery, dataset: ProtocolDatasetContract, datasets: ReadonlyMap<string, ProtocolDatasetContract>, limits: SemanticOperationLimits): readonly SemanticOperationViolation[];
+//# sourceMappingURL=semantic-operation-validation.d.ts.map

package/dist/semantic-operation-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-operation-validation.d.ts","sourceRoot":"","sources":["../src/semantic-operation-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,uBAAuB,EAGvB,qBAAqB,EAEtB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAiGD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,qBAAqB,EAChC,OAAO,EAAE,uBAAuB,EAChC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,uBAAuB,CAAC,EACtD,MAAM,EAAE,uBAAuB,GAC9B,SAAS,0BAA0B,EAAE,CAgGvC"}

package/dist/semantic-operation-validation.js

@@ -0,0 +1,177 @@
+/**
+ * Contract-driven validation of a semantic operation.
+ *
+ * The deployment package deliberately depends only on `@hypequery/protocol`, so
+ * every check here is made against the validated contract rather than by
+ * loading the authoring package. A gateway must be able to reject a bad
+ * invocation without any of the deploying application's code.
+ */
+const ALL_GRAINS = ['day', 'week', 'month', 'quarter', 'year'];
+/**
+ * What a dataset exposes, before any metric narrows it.
+ *
+ * A relationship contributes `<name>.<dimension>` for its target's groupable
+ * dimensions, matching the one-hop rule the authoring layer enforces. Filters
+ * over a relationship are accepted on the same qualified names, because the
+ * contract has no separate filter declaration for a joined field.
+ */
+function resolveDataset(dataset, datasets) {
+    const groupable = new Set();
+    const filters = new Map();
+    for (const dimension of dataset.dimensions) {
+        if (dimension.groupable)
+            groupable.add(String(dimension.name));
+    }
+    for (const filter of dataset.filters) {
+        filters.set(String(filter.name), new Set(filter.operators));
+    }
+    for (const relationship of dataset.relationships) {
+        if (!relationship.queryable)
+            continue;
+        const target = datasets.get(String(relationship.target));
+        for (const dimension of target?.dimensions ?? []) {
+            const qualified = `${String(relationship.name)}.${String(dimension.name)}`;
+            // The two capabilities are declared separately and travel separately
+            // across a join. Coupling them would both hide a filterable field that
+            // cannot be grouped and expose one the target declared unfilterable.
+            if (dimension.groupable)
+                groupable.add(qualified);
+            if (dimension.filterable) {
+                // A joined field has no named filter in the contract, so it accepts the
+                // full operator set the protocol allows rather than a narrowed list.
+                filters.set(qualified, new Set([
+                    'eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'in', 'notIn', 'between', 'like',
+                ]));
+            }
+        }
+    }
+    return {
+        groupable,
+        filters,
+        measures: new Set(dataset.measures.map(measure => String(measure.name))),
+        grains: new Set(dataset.timeField === undefined ? [] : ALL_GRAINS),
+    };
+}
+/** A metric may only narrow what its dataset exposes, never widen it. */
+function narrowToMetric(base, metric) {
+    const declaredDimensions = new Set(metric.dimensions.map(String));
+    const declaredFilters = new Set(metric.filters.map(String));
+    return {
+        groupable: new Set([...base.groupable].filter(name => declaredDimensions.has(name))),
+        filters: new Map([...base.filters].filter(([name]) => declaredFilters.has(name))),
+        // A metric selects itself; a caller cannot add measures to it.
+        measures: new Set(),
+        grains: new Set(metric.grain === undefined
+            ? metric.grains.filter(grain => base.grains.has(grain))
+            : [metric.grain]),
+    };
+}
+/**
+ * The field a filter expression addresses, or null when it is not a plain
+ * comparison.
+ *
+ * Both operands are checked. A right-hand side that is anything but a literal —
+ * another reference, an aggregate, a nested comparison — addresses something
+ * this validator never matched against the contract's allowlist, so accepting
+ * it would leave a published-surface check to whichever executor happens to be
+ * injected. It is also a caller mistake rather than a deployment capability
+ * gap, and only a violation raised here reports it as one.
+ */
+function comparisonField(expression) {
+    if (expression.kind !== 'comparison')
+        return null;
+    if (expression.left.kind !== 'reference' || expression.right.kind !== 'literal')
+        return null;
+    return { field: String(expression.left.name), operator: expression.operator };
+}
+/**
+ * Validates one semantic operation against the contract that will serve it.
+ *
+ * Returns every violation rather than the first, so a caller correcting an
+ * agent-authored query sees the whole problem in one round trip.
+ */
+export function validateSemanticOperation(operation, dataset, datasets, limits) {
+    const violations = [];
+    const fail = (message, path) => violations.push({ message, path });
+    let metric;
+    if (operation.kind === 'metric') {
+        metric = dataset.metrics.find(entry => String(entry.name) === String(operation.metric));
+        if (metric === undefined) {
+            fail(`Unknown metric "${String(operation.metric)}".`, '$.operation.metric');
+            return violations;
+        }
+    }
+    const base = resolveDataset(dataset, datasets);
+    const allowed = metric === undefined ? base : narrowToMetric(base, metric);
+    const dimensions = operation.dimensions ?? [];
+    if (dimensions.length > limits.maxDimensions) {
+        fail(`At most ${limits.maxDimensions} dimensions may be selected.`, '$.operation.dimensions');
+    }
+    dimensions.forEach((name, index) => {
+        if (!allowed.groupable.has(String(name))) {
+            fail(`Unknown or non-groupable dimension "${String(name)}".`, `$.operation.dimensions[${index}]`);
+        }
+    });
+    if (new Set(dimensions.map(String)).size !== dimensions.length) {
+        fail('Dimensions must be unique.', '$.operation.dimensions');
+    }
+    if (operation.kind === 'dataset') {
+        const measures = operation.measures ?? [];
+        if (measures.length > limits.maxMeasures) {
+            fail(`At most ${limits.maxMeasures} measures may be selected.`, '$.operation.measures');
+        }
+        measures.forEach((name, index) => {
+            if (!allowed.measures.has(String(name))) {
+                fail(`Unknown measure "${String(name)}".`, `$.operation.measures[${index}]`);
+            }
+        });
+        if (dimensions.length === 0 && measures.length === 0) {
+            fail('At least one dimension or measure must be selected.', '$.operation');
+        }
+    }
+    const filters = operation.filters ?? [];
+    if (filters.length > limits.maxFilters) {
+        fail(`At most ${limits.maxFilters} filters may be applied.`, '$.operation.filters');
+    }
+    filters.forEach((expression, index) => {
+        const path = `$.operation.filters[${index}]`;
+        const comparison = comparisonField(expression);
+        if (comparison === null) {
+            // Only `field <operator> value` is expressible against a contract; a
+            // richer expression could reference something the contract never
+            // published.
+            fail('Only a field/operator/value comparison may be filtered on.', path);
+            return;
+        }
+        const operators = allowed.filters.get(comparison.field);
+        if (operators === undefined) {
+            fail(`Unknown or unfilterable field "${comparison.field}".`, path);
+            return;
+        }
+        if (!operators.has(comparison.operator)) {
+            fail(`Operator "${comparison.operator}" is not allowed on "${comparison.field}".`, `${path}.operator`);
+        }
+    });
+    const orderBy = operation.orderBy ?? [];
+    const orderable = new Set([
+        ...allowed.groupable,
+        ...allowed.measures,
+        ...(metric === undefined ? [] : [String(metric.name)]),
+        ...(operation.by === undefined ? [] : ['period']),
+    ]);
+    orderBy.forEach((entry, index) => {
+        if (!orderable.has(String(entry.field))) {
+            fail(`Cannot order by "${String(entry.field)}".`, `$.operation.orderBy[${index}].field`);
+        }
+    });
+    if (operation.by !== undefined && !allowed.grains.has(operation.by)) {
+        fail(`Time grain "${operation.by}" is not supported here.`, '$.operation.by');
+    }
+    if (operation.limit !== undefined && operation.limit > limits.maxRows) {
+        fail(`The row limit may not exceed ${limits.maxRows}.`, '$.operation.limit');
+    }
+    if (operation.offset !== undefined && operation.offset > limits.maxOffset) {
+        fail(`The offset may not exceed ${limits.maxOffset}.`, '$.operation.offset');
+    }
+    return violations;
+}

package/dist/utils/required-access.d.ts

@@ -0,0 +1,2 @@
+export declare function missing(required: readonly string[], held: readonly string[] | undefined): boolean;
+//# sourceMappingURL=required-access.d.ts.map

package/dist/utils/required-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"required-access.d.ts","sourceRoot":"","sources":["../../src/utils/required-access.ts"],"names":[],"mappings":"AAAA,wBAAgB,OAAO,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,OAAO,CAGjG"}

package/dist/utils/required-access.js

@@ -0,0 +1,4 @@
+export function missing(required, held) {
+    const available = new Set(held ?? []);
+    return required.some(value => !available.has(value));
+}

package/dist/utils/semantic-budget-limits.d.ts

@@ -0,0 +1,7 @@
+/** Drops explicitly-undefined properties, so a spread cannot erase a default. */
+export declare function definedLimits<T extends object>(limits: T | undefined): Partial<T>;
+/** The lowest of every ceiling that applies. A caller can tighten, never widen. */
+export declare function lowest(...values: readonly (number | undefined)[]): number | undefined;
+/** A declared ceiling under a server one; declaring nothing leaves the server's. */
+export declare function tighten(declared: number | undefined, ceiling: number): number;
+//# sourceMappingURL=semantic-budget-limits.d.ts.map

package/dist/utils/semantic-budget-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-budget-limits.d.ts","sourceRoot":"","sources":["../../src/utils/semantic-budget-limits.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,CAKjF;AAED,mFAAmF;AACnF,wBAAgB,MAAM,CAAC,GAAG,MAAM,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,GAAG,MAAM,GAAG,SAAS,CAGrF;AAED,oFAAoF;AACpF,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE7E"}

package/dist/utils/semantic-budget-limits.js

@@ -0,0 +1,15 @@
+/** Drops explicitly-undefined properties, so a spread cannot erase a default. */
+export function definedLimits(limits) {
+    if (limits === undefined)
+        return {};
+    return Object.fromEntries(Object.entries(limits).filter(([, value]) => value !== undefined));
+}
+/** The lowest of every ceiling that applies. A caller can tighten, never widen. */
+export function lowest(...values) {
+    const finite = values.filter((value) => value !== undefined);
+    return finite.length === 0 ? undefined : Math.min(...finite);
+}
+/** A declared ceiling under a server one; declaring nothing leaves the server's. */
+export function tighten(declared, ceiling) {
+    return declared === undefined ? ceiling : Math.min(declared, ceiling);
+}

package/dist/utils/semantic-executor-failure.d.ts

@@ -0,0 +1,21 @@
+import type { ProtocolSemanticInvocationFailureCategory } from '@hypequery/protocol';
+/**
+ * The category an executor claimed, when it deliberately claimed one.
+ *
+ * The `hypequerySemanticFailure` marker, not the shape of the error, is what
+ * grants the claim. Allow-listing a `category` string alone would let a
+ * provider or library exception that happens to carry a generic one — a
+ * `not-found` from an HTTP client, say — put its own message in front of a
+ * caller and decide whether the call is retried. This module refuses to unwrap
+ * a cause for exactly that reason, and duck-typing would have reopened the door
+ * beside it. An error without the marker stays `executor-failed` with the
+ * generic message.
+ */
+export declare function claimedFailure(error: unknown): {
+    category: ProtocolSemanticInvocationFailureCategory;
+    code: string;
+    message: string;
+    retryable: boolean;
+    relist: boolean;
+} | undefined;
+//# sourceMappingURL=semantic-executor-failure.d.ts.map

package/dist/utils/semantic-executor-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-executor-failure.d.ts","sourceRoot":"","sources":["../../src/utils/semantic-executor-failure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yCAAyC,EAAE,MAAM,qBAAqB,CAAC;AAiCrF;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG;IAC9C,QAAQ,EAAE,yCAAyC,CAAC;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;CACjB,GAAG,SAAS,CAgBZ"}

package/dist/utils/semantic-executor-failure.js

@@ -0,0 +1,52 @@
+/**
+ * Categories an injected executor may claim for itself.
+ *
+ * Execution is injected, so the executor is the only component that knows the
+ * difference between "this query broke", "this deployment cannot express that",
+ * and "this deployment is incoherent". Every category here is one only the
+ * executor can determine; the ones it must never claim — `unauthenticated`,
+ * `forbidden`, `cancelled`, `stale-activation` — are decided by this module and
+ * are deliberately absent.
+ */
+const EXECUTOR_CATEGORIES = new Set([
+    'unsupported-capability',
+    'budget-exceeded',
+    'tenant-required',
+    'configuration-invalid',
+    'not-found',
+    'input-invalid',
+    'output-invalid',
+    'executor-unavailable',
+    'executor-failed',
+]);
+/**
+ * The category an executor claimed, when it deliberately claimed one.
+ *
+ * The `hypequerySemanticFailure` marker, not the shape of the error, is what
+ * grants the claim. Allow-listing a `category` string alone would let a
+ * provider or library exception that happens to carry a generic one — a
+ * `not-found` from an HTTP client, say — put its own message in front of a
+ * caller and decide whether the call is retried. This module refuses to unwrap
+ * a cause for exactly that reason, and duck-typing would have reopened the door
+ * beside it. An error without the marker stays `executor-failed` with the
+ * generic message.
+ */
+export function claimedFailure(error) {
+    if (typeof error !== 'object' || error === null)
+        return undefined;
+    const shape = error;
+    if (shape.hypequerySemanticFailure !== true)
+        return undefined;
+    if (typeof shape.category !== 'string' || !EXECUTOR_CATEGORIES.has(shape.category)) {
+        return undefined;
+    }
+    return {
+        category: shape.category,
+        code: typeof shape.code === 'string' && /^[A-Z][A-Z0-9_]*$/.test(shape.code)
+            ? shape.code
+            : 'HQ_SEMANTIC_EXECUTION_FAILED',
+        message: typeof shape.message === 'string' ? shape.message : 'Semantic execution failed.',
+        retryable: shape.retryable === true,
+        relist: shape.relist === true,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/deployment",
-  "version": "0.7.5",
+  "version": "0.8.0",
   "description": "Verified deployment intake, activation, and runtime hosting for Hypequery analytics",
   "keywords": [
     "hypequery",
@@ -26,12 +26,13 @@
     "README.md"
   ],
   "dependencies": {
-    "@hypequery/protocol": "0.12.0"
+    "@hypequery/protocol": "0.13.0"
   },
   "devDependencies": {
     "@types/node": "^22.5.0",
     "typescript": "^5.7.3",
-    "vitest": "^3.2.6"
+    "vitest": "^3.2.6",
+    "@hypequery/datasets": "0.15.0"
   },
   "engines": {
     "node": ">=20"