@hypequery/protocol 0.20.0 → 0.21.0

package/README.md

@@ -19,6 +19,7 @@ This package implements those rules in TypeScript. Python and other implementati
 
 - canonical tagged values and RFC 8785 encoding
 - strict simple and qualified logical identifiers
+- signed semantic client descriptors and strict HTTP/MCP client queries
 - closed semantic expression and query envelopes
 - portable input and output schemas
 - trusted query implementation artifacts
@@ -75,3 +76,19 @@ Self-hosted `@hypequery/serve` can continue to run application source directly.
 ## License
 
 Apache-2.0.
+
+## Semantic client contracts
+
+RFC 0018 describes registered public endpoint capabilities for type generation
+and HTTP-backed MCP. Use `decodeProtocolClientContract(text)` at an untrusted JSON
+text boundary (bounded, rejects duplicate members), or
+`validateProtocolClientContract(value)` for an already decoded signed object.
+`prepareProtocolClientContract(unsigned)` computes the domain-separated schema
+and view hashes and refuses preexisting hash fields.
+
+`validateProtocolClientQuery(contract, endpointId, input, 'http' | 'mcp')` validates
+and normalizes the strict client profile. Its result contains the registered
+endpoint, selected measures, effective clamped limit and HTTP body. It maps MCP
+grain to by and removes routing arguments. All returned data is a frozen snapshot.
+These APIs do not authenticate, register a route, export application definitions
+or execute queries. An endpoint hash is a compatibility identity, not permission.

package/dist/bundles/codec.js

@@ -1,5 +1,5 @@
-import { sha256 } from '@noble/hashes/sha2';
-import { bytesToHex } from '@noble/hashes/utils';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
 import { serializeJcs } from '../values/jcs.js';
 import { validateProtocolDeploymentBundleManifest } from './validate.js';
 const textEncoder = new TextEncoder();

package/dist/cache-keys/cache-keys.js

@@ -1,5 +1,5 @@
-import { hmac } from '@noble/hashes/hmac';
-import { sha256 } from '@noble/hashes/sha2';
+import { hmac } from '@noble/hashes/hmac.js';
+import { sha256 } from '@noble/hashes/sha2.js';
 import { validateProtocolDeploymentReleaseTarget } from '../releases/validate.js';
 import { PROTOCOL_CACHE_KEY_LIMITS, } from './types.js';
 const SCHEME = 'hq1';

package/dist/cache-preimages/cache-preimages.js

@@ -1,6 +1,6 @@
-import { hmac } from '@noble/hashes/hmac';
-import { sha256 } from '@noble/hashes/sha2';
-import { bytesToHex } from '@noble/hashes/utils';
+import { hmac } from '@noble/hashes/hmac.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
 import { validateProtocolSemanticQuery } from '../expressions/validate.js';
 import { serializeJcs } from '../values/jcs.js';
 const FINGERPRINT_DOMAIN = 'hypequery.tenant.fingerprint.v1';

package/dist/client-contract/bounds.d.ts

@@ -0,0 +1,3 @@
+/** Run count budgets on the detached JSON tree before descriptor validation. */
+export declare function boundClientDescriptors(raw: Record<string, unknown>): void;
+//# sourceMappingURL=bounds.d.ts.map

package/dist/client-contract/bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounds.d.ts","sourceRoot":"","sources":["../../src/client-contract/bounds.ts"],"names":[],"mappings":"AACA,gFAAgF;AAChF,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAgBzE"}

package/dist/client-contract/bounds.js

@@ -0,0 +1,24 @@
+import { clientError } from './errors.js';
+/** Run count budgets on the detached JSON tree before descriptor validation. */
+export function boundClientDescriptors(raw) {
+    if (!Array.isArray(raw.endpoints))
+        return;
+    if (raw.endpoints.length > 256)
+        clientError('HQ_CLIENT_LIMIT', '/endpoints');
+    let descriptors = 0;
+    for (const [index, endpoint] of raw.endpoints.entries()) {
+        if (!endpoint || typeof endpoint !== 'object' || Array.isArray(endpoint))
+            continue;
+        for (const key of ['dimensions', 'measures', 'filters']) {
+            const value = endpoint[key];
+            if (value && typeof value === 'object' && !Array.isArray(value)) {
+                const count = Object.keys(value).length;
+                if (count > 256)
+                    clientError('HQ_CLIENT_LIMIT', `/endpoints/${index}/${key}`);
+                descriptors += count;
+                if (descriptors > 16384)
+                    clientError('HQ_CLIENT_LIMIT', `/endpoints/${index}`);
+            }
+        }
+    }
+}

package/dist/client-contract/codec.d.ts

@@ -0,0 +1,4 @@
+export declare const CLIENT_SCHEMA_DOMAIN = "hypequery:client-endpoint-schema:v1\0";
+export declare const CLIENT_CONTRACT_DOMAIN = "hypequery:client-contract:v1\0";
+export declare function clientDigest(domain: string, value: unknown): string;
+//# sourceMappingURL=codec.d.ts.map

package/dist/client-contract/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/client-contract/codec.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,oBAAoB,0CAA0C,CAAC;AAC5E,eAAO,MAAM,sBAAsB,mCAAmC,CAAC;AACvE,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAEnE"}

package/dist/client-contract/codec.js

@@ -0,0 +1,8 @@
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
+import { clientCanonical } from './safe-data.js';
+export const CLIENT_SCHEMA_DOMAIN = 'hypequery:client-endpoint-schema:v1\0';
+export const CLIENT_CONTRACT_DOMAIN = 'hypequery:client-contract:v1\0';
+export function clientDigest(domain, value) {
+    return bytesToHex(sha256(new TextEncoder().encode(domain + clientCanonical(value))));
+}

package/dist/client-contract/decode.d.ts

@@ -0,0 +1,4 @@
+import type { ProtocolClientContract } from './types.js';
+/** Decode untrusted JSON text without accepting duplicate object members. */
+export declare function decodeProtocolClientContract(input: string): ProtocolClientContract;
+//# sourceMappingURL=decode.d.ts.map

package/dist/client-contract/decode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["../../src/client-contract/decode.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAiEzD,6EAA6E;AAC7E,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG,sBAAsB,CAUlF"}

package/dist/client-contract/decode.js

@@ -0,0 +1,100 @@
+import { clientError, ProtocolClientContractError } from './errors.js';
+import { CLIENT_MAX_BYTES } from './safe-data.js';
+import { pointer } from './primitives.js';
+import { validateProtocolClientContract } from './validate.js';
+/** Bounded JSON parser retaining duplicate members until they can be refused. */
+class ClientJsonReader {
+    input;
+    position = 0;
+    nodes = 0;
+    constructor(input) {
+        this.input = input;
+    }
+    read() {
+        const result = this.value(1, '');
+        this.whitespace();
+        if (this.position !== this.input.length)
+            clientError('HQ_CLIENT_TYPE');
+        return result;
+    }
+    whitespace() {
+        while (' \t\r\n'.includes(this.input[this.position] ?? '\0'))
+            this.position++;
+    }
+    string() {
+        const start = this.position++;
+        while (this.position < this.input.length) {
+            const character = this.input[this.position++];
+            if (character === '\\')
+                this.position++;
+            else if (character === '"')
+                return JSON.parse(this.input.slice(start, this.position));
+        }
+        return clientError('HQ_CLIENT_TYPE');
+    }
+    value(depth, path) {
+        if (depth > 16 || ++this.nodes > 100_000)
+            clientError('HQ_CLIENT_LIMIT');
+        this.whitespace();
+        const character = this.input[this.position];
+        if (character === '"')
+            return this.string();
+        if (character === '{' || character === '[') {
+            const object = character === '{';
+            const close = object ? '}' : ']';
+            const result = Object.create(null);
+            const array = [];
+            this.position++;
+            this.whitespace();
+            if (this.input[this.position] !== close) {
+                for (;;) {
+                    this.whitespace();
+                    let key = String(array.length);
+                    if (object) {
+                        if (this.input[this.position] !== '"')
+                            clientError('HQ_CLIENT_TYPE');
+                        key = this.string();
+                        if (Object.hasOwn(result, key))
+                            clientError('HQ_CLIENT_DUPLICATE');
+                        this.whitespace();
+                        if (this.input[this.position++] !== ':')
+                            clientError('HQ_CLIENT_TYPE');
+                    }
+                    const child = this.value(depth + 1, pointer(path, key));
+                    if (object)
+                        result[key] = child;
+                    else
+                        array.push(child);
+                    this.whitespace();
+                    if (this.input[this.position] !== ',')
+                        break;
+                    this.position++;
+                }
+            }
+            if (this.input[this.position++] !== close)
+                clientError('HQ_CLIENT_TYPE');
+            return object ? result : array;
+        }
+        const match = /^(?:null|true|false|-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?)/.exec(this.input.slice(this.position));
+        if (!match)
+            clientError('HQ_CLIENT_TYPE');
+        this.position += match[0].length;
+        return JSON.parse(match[0]);
+    }
+}
+/** Decode untrusted JSON text without accepting duplicate object members. */
+export function decodeProtocolClientContract(input) {
+    if (typeof input !== 'string')
+        clientError('HQ_CLIENT_TYPE');
+    if (input.length > CLIENT_MAX_BYTES || new TextEncoder().encode(input).length > CLIENT_MAX_BYTES) {
+        clientError('HQ_CLIENT_LIMIT');
+    }
+    try {
+        return validateProtocolClientContract(new ClientJsonReader(input).read());
+    }
+    catch (error) {
+        if (error instanceof ProtocolClientContractError)
+            throw error;
+        return clientError('HQ_CLIENT_TYPE');
+    }
+}

package/dist/client-contract/errors.d.ts

@@ -0,0 +1,21 @@
+export declare const CLIENT_ERROR_MESSAGES: Readonly<{
+    HQ_CLIENT_TYPE: "Expected plain JSON data.";
+    HQ_CLIENT_LIMIT: "Client contract exceeds validation limits.";
+    HQ_CLIENT_VERSION: "Unsupported client contract version.";
+    HQ_CLIENT_UNKNOWN_FIELD: "Unknown client contract field.";
+    HQ_CLIENT_SHAPE: "Invalid client contract shape.";
+    HQ_CLIENT_IDENTIFIER: "Invalid client contract identifier.";
+    HQ_CLIENT_DUPLICATE: "Duplicate client contract entry.";
+    HQ_CLIENT_PATH: "Invalid client endpoint path.";
+    HQ_CLIENT_REFERENCE: "Inconsistent client contract reference.";
+    HQ_CLIENT_IDENTITY: "Client contract identity does not match.";
+    HQ_CLIENT_QUERY: "Invalid client query.";
+}>;
+export type ProtocolClientContractErrorCode = keyof typeof CLIENT_ERROR_MESSAGES;
+export declare class ProtocolClientContractError extends TypeError {
+    readonly code: ProtocolClientContractErrorCode;
+    readonly path: string;
+    constructor(code: ProtocolClientContractErrorCode, path?: string);
+}
+export declare function clientError(code: ProtocolClientContractErrorCode, path?: string): never;
+//# sourceMappingURL=errors.d.ts.map

package/dist/client-contract/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/client-contract/errors.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB;;;;;;;;;;;;EAYhC,CAAC;AACH,MAAM,MAAM,+BAA+B,GAAG,MAAM,OAAO,qBAAqB,CAAC;AACjF,qBAAa,2BAA4B,SAAQ,SAAS;IACxD,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,IAAI,EAAE,+BAA+B,EAAE,IAAI,SAAK;CAM7D;AACD,wBAAgB,WAAW,CAAC,IAAI,EAAE,+BAA+B,EAAE,IAAI,SAAK,GAAG,KAAK,CAEnF"}

package/dist/client-contract/errors.js

@@ -0,0 +1,26 @@
+export const CLIENT_ERROR_MESSAGES = Object.freeze({
+    HQ_CLIENT_TYPE: 'Expected plain JSON data.',
+    HQ_CLIENT_LIMIT: 'Client contract exceeds validation limits.',
+    HQ_CLIENT_VERSION: 'Unsupported client contract version.',
+    HQ_CLIENT_UNKNOWN_FIELD: 'Unknown client contract field.',
+    HQ_CLIENT_SHAPE: 'Invalid client contract shape.',
+    HQ_CLIENT_IDENTIFIER: 'Invalid client contract identifier.',
+    HQ_CLIENT_DUPLICATE: 'Duplicate client contract entry.',
+    HQ_CLIENT_PATH: 'Invalid client endpoint path.',
+    HQ_CLIENT_REFERENCE: 'Inconsistent client contract reference.',
+    HQ_CLIENT_IDENTITY: 'Client contract identity does not match.',
+    HQ_CLIENT_QUERY: 'Invalid client query.',
+});
+export class ProtocolClientContractError extends TypeError {
+    code;
+    path;
+    constructor(code, path = '') {
+        super(CLIENT_ERROR_MESSAGES[code]);
+        this.name = 'ProtocolClientContractError';
+        this.code = code;
+        this.path = path;
+    }
+}
+export function clientError(code, path = '') {
+    throw new ProtocolClientContractError(code, path);
+}

package/dist/client-contract/index.d.ts

@@ -0,0 +1,8 @@
+export { validateProtocolClientContract, prepareProtocolClientContract } from './validate.js';
+export { ProtocolClientContractError, CLIENT_ERROR_MESSAGES } from './errors.js';
+export type { ProtocolClientContractErrorCode } from './errors.js';
+export type { ClientDimension, ClientMeasure, ClientFilter, ClientTime, ClientQueryLimits, ClientDatasetEndpoint, ClientMetricEndpoint, ProtocolClientEndpoint, ProtocolClientContract, PreparedProtocolClientContract, ClientFieldType, ClientWireType, } from './types.js';
+export { validateProtocolClientQuery } from './query.js';
+export type { ClientQueryPlan } from './query.js';
+export { decodeProtocolClientContract } from './decode.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/client-contract/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client-contract/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,8BAA8B,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAC;AAC9F,OAAO,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACjF,YAAY,EAAE,+BAA+B,EAAE,MAAM,aAAa,CAAC;AACnE,YAAY,EACV,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAC3E,qBAAqB,EAAE,oBAAoB,EAAE,sBAAsB,EACnE,sBAAsB,EAAE,8BAA8B,EAAE,eAAe,EAAE,cAAc,GACxF,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AACzD,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC"}

package/dist/client-contract/index.js

@@ -0,0 +1,4 @@
+export { validateProtocolClientContract, prepareProtocolClientContract } from './validate.js';
+export { ProtocolClientContractError, CLIENT_ERROR_MESSAGES } from './errors.js';
+export { validateProtocolClientQuery } from './query.js';
+export { decodeProtocolClientContract } from './decode.js';

package/dist/client-contract/nodes.d.ts

@@ -0,0 +1,8 @@
+import type { ClientDimension, ClientFilter, ClientMeasure, ClientQueryLimits, ClientTime } from './types.js';
+export declare function dimension(input: unknown, path: string): ClientDimension;
+export declare function measure(input: unknown, path: string): ClientMeasure;
+export declare function filter(input: unknown, path: string): ClientFilter;
+export declare function fields<T>(input: unknown, path: string, validate: (v: unknown, p: string) => T): Record<string, T>;
+export declare function time(input: unknown, path: string): ClientTime | null;
+export declare function limits(input: unknown, path: string): ClientQueryLimits;
+//# sourceMappingURL=nodes.d.ts.map

package/dist/client-contract/nodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes.d.ts","sourceRoot":"","sources":["../../src/client-contract/nodes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAK9G,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,CAYvE;AACD,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAKnE;AACD,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAQjE;AACD,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CASjH;AACD,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CASpE;AACD,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAUtE"}

package/dist/client-contract/nodes.js

@@ -0,0 +1,68 @@
+import { clientError } from './errors.js';
+import { bool, choice, CLIENT_FIELD_TYPES, CLIENT_GRAINS, CLIENT_OPERATORS, integer, name, names, pointer, record, shape, timezone } from './primitives.js';
+export function dimension(input, path) {
+    const value = shape(input, ['type', 'wireType', 'nullable', 'groupable', 'orderable'], path);
+    const type = choice(value.type, CLIENT_FIELD_TYPES, pointer(path, 'type'));
+    const wires = type === 'number' ? ['number', 'string', 'number-or-string']
+        : type === 'boolean' ? ['boolean'] : ['string'];
+    const wireType = choice(value.wireType, wires, pointer(path, 'wireType'));
+    if (typeof value.nullable !== 'boolean' && value.nullable !== 'unknown') {
+        clientError('HQ_CLIENT_SHAPE', pointer(path, 'nullable'));
+    }
+    return { type, wireType, nullable: value.nullable,
+        groupable: bool(value.groupable, pointer(path, 'groupable')),
+        orderable: bool(value.orderable, pointer(path, 'orderable')) };
+}
+export function measure(input, path) {
+    const value = shape(input, ['wireType', 'nullable', 'having'], path);
+    if (value.wireType !== 'string')
+        clientError('HQ_CLIENT_SHAPE', pointer(path, 'wireType'));
+    if (value.nullable !== true)
+        clientError('HQ_CLIENT_SHAPE', pointer(path, 'nullable'));
+    return { wireType: 'string', nullable: true, having: bool(value.having, pointer(path, 'having')) };
+}
+export function filter(input, path) {
+    const value = shape(input, ['type', 'operators'], path);
+    const type = choice(value.type, CLIENT_FIELD_TYPES, pointer(path, 'type'));
+    const allowed = type === 'boolean' ? ['eq', 'neq', 'in', 'notIn']
+        : type === 'number' ? CLIENT_OPERATORS.filter(item => item !== 'like') : CLIENT_OPERATORS;
+    const operators = names(value.operators, pointer(path, 'operators'), allowed);
+    if (operators.length === 0)
+        clientError('HQ_CLIENT_SHAPE', pointer(path, 'operators'));
+    return { type, operators: operators.sort() };
+}
+export function fields(input, path, validate) {
+    const value = record(input, path);
+    if (Object.keys(value).length > 256)
+        clientError('HQ_CLIENT_LIMIT', path);
+    const result = Object.create(null);
+    for (const key of Object.keys(value).sort()) {
+        name(key, path, true);
+        result[key] = validate(value[key], pointer(path, key));
+    }
+    return result;
+}
+export function time(input, path) {
+    if (input === null)
+        return null;
+    const value = shape(input, ['grains', 'defaultTimezone', 'timezone', 'periodFormat'], path);
+    const grains = names(value.grains, pointer(path, 'grains'), CLIENT_GRAINS);
+    if (grains.length === 0)
+        clientError('HQ_CLIENT_SHAPE', pointer(path, 'grains'));
+    const defaultTimezone = timezone(value.defaultTimezone, pointer(path, 'defaultTimezone'));
+    const enabled = bool(value.timezone, pointer(path, 'timezone'));
+    if (value.periodFormat !== 'calendar-date-or-local-datetime-v1')
+        clientError('HQ_CLIENT_SHAPE', pointer(path, 'periodFormat'));
+    return { grains: grains.sort(), defaultTimezone, timezone: enabled, periodFormat: value.periodFormat };
+}
+export function limits(input, path) {
+    const bounds = { defaultLimit: [1, 100000], maxLimit: [1, 100000], maxOffset: [0, 1000000],
+        maxDimensions: [0, 100], maxMeasures: [0, 100], maxPredicates: [0, 100],
+        maxOrderBy: [0, 100], maxFilterValues: [1, 10000] };
+    const value = shape(input, Object.keys(bounds), path);
+    const result = Object.create(null);
+    for (const [key, [low, high]] of Object.entries(bounds)) {
+        result[key] = integer(value[key], low, high, pointer(path, key));
+    }
+    return result;
+}

package/dist/client-contract/primitives.d.ts

@@ -0,0 +1,15 @@
+export type ClientRecord = Record<string, unknown>;
+export declare const CLIENT_FIELD_TYPES: readonly ["string", "number", "boolean", "timestamp"];
+export declare const CLIENT_GRAINS: readonly ["minute", "hour", "day", "week", "month", "quarter", "year"];
+export declare const CLIENT_OPERATORS: string[];
+export declare function pointer(path: string, key: string | number): string;
+export declare function record(input: unknown, path: string): ClientRecord;
+export declare function shape(input: unknown, keys: readonly string[], path: string): ClientRecord;
+export declare function choice<T extends string>(input: unknown, choices: readonly T[], path: string): T;
+export declare function bool(input: unknown, path: string): boolean;
+export declare function integer(input: unknown, low: number, high: number, path: string): number;
+export declare function name(input: unknown, path: string, qualified?: boolean): string;
+export declare function names(input: unknown, path: string, allowed?: readonly string[]): string[];
+export declare function route(input: unknown, path: string): string;
+export declare function timezone(input: unknown, path: string): string;
+//# sourceMappingURL=primitives.d.ts.map

package/dist/client-contract/primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/client-contract/primitives.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACnD,eAAO,MAAM,kBAAkB,uDAAwD,CAAC;AACxF,eAAO,MAAM,aAAa,wEAAyE,CAAC;AACpG,eAAO,MAAM,gBAAgB,UAA4E,CAAC;AAC1G,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAElE;AACD,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAGjE;AACD,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAKzF;AACD,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAG/F;AACD,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAG1D;AACD,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKvF;AACD,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,UAAQ,GAAG,MAAM,CAO5E;AACD,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAOzF;AACD,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI1D;AACD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7D"}

package/dist/client-contract/primitives.js

@@ -0,0 +1,74 @@
+import { CLIENT_TIMEZONE_NAMES } from './timezone-names.js';
+import { parseProtocolIdentifier } from '../identifiers/identifiers.js';
+import { clientError } from './errors.js';
+export const CLIENT_FIELD_TYPES = ['string', 'number', 'boolean', 'timestamp'];
+export const CLIENT_GRAINS = ['minute', 'hour', 'day', 'week', 'month', 'quarter', 'year'];
+export const CLIENT_OPERATORS = ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'in', 'notIn', 'between', 'like'];
+export function pointer(path, key) {
+    return path + '/' + String(key).replaceAll('~', '~0').replaceAll('/', '~1');
+}
+export function record(input, path) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        clientError('HQ_CLIENT_SHAPE', path);
+    return input;
+}
+export function shape(input, keys, path) {
+    const value = record(input, path);
+    if (Object.keys(value).some(key => !keys.includes(key)))
+        clientError('HQ_CLIENT_UNKNOWN_FIELD', path);
+    if (keys.some(key => !Object.hasOwn(value, key)))
+        clientError('HQ_CLIENT_SHAPE', path);
+    return value;
+}
+export function choice(input, choices, path) {
+    if (typeof input !== 'string' || !choices.includes(input))
+        clientError('HQ_CLIENT_SHAPE', path);
+    return input;
+}
+export function bool(input, path) {
+    if (typeof input !== 'boolean')
+        clientError('HQ_CLIENT_SHAPE', path);
+    return input;
+}
+export function integer(input, low, high, path) {
+    if (!Number.isSafeInteger(input) || input < low || input > high) {
+        clientError('HQ_CLIENT_SHAPE', path);
+    }
+    return input;
+}
+export function name(input, path, qualified = false) {
+    if (typeof input !== 'string')
+        clientError('HQ_CLIENT_IDENTIFIER', path);
+    const parts = input.split('.');
+    if (parts.length > (qualified ? 2 : 1))
+        clientError('HQ_CLIENT_IDENTIFIER', path);
+    try {
+        for (const part of parts)
+            parseProtocolIdentifier(part);
+    }
+    catch {
+        clientError('HQ_CLIENT_IDENTIFIER', path);
+    }
+    return input;
+}
+export function names(input, path, allowed) {
+    if (!Array.isArray(input))
+        clientError('HQ_CLIENT_SHAPE', path);
+    const result = input.map((item, index) => allowed
+        ? choice(item, allowed, pointer(path, index))
+        : name(item, pointer(path, index), true));
+    if (new Set(result).size !== result.length)
+        clientError('HQ_CLIENT_DUPLICATE', path);
+    return result;
+}
+export function route(input, path) {
+    if (typeof input !== 'string' || !/^\/(?:[A-Za-z0-9_~.-]+\/)*[A-Za-z0-9_~.-]+$/.test(input)
+        || input.split('/').some(part => part === '.' || part === '..'))
+        clientError('HQ_CLIENT_PATH', path);
+    return input;
+}
+export function timezone(input, path) {
+    if (typeof input !== 'string' || !CLIENT_TIMEZONE_NAMES.has(input))
+        clientError('HQ_CLIENT_SHAPE', path);
+    return input;
+}

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

@@ -0,0 +1,10 @@
+import type { ProtocolClientEndpoint } from './types.js';
+export interface ClientQueryPlan {
+    readonly endpoint: ProtocolClientEndpoint;
+    readonly body: Readonly<Record<string, unknown>>;
+    readonly selectedMeasures: readonly string[];
+    readonly effectiveLimit: number;
+}
+/** Normalize HTTP or MCP input under a signed contract; routing never comes from a tool URL. */
+export declare function validateProtocolClientQuery(contract: unknown, endpointId: string, input: unknown, transport?: 'http' | 'mcp'): ClientQueryPlan;
+//# sourceMappingURL=query.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/client-contract/query.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAKzD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AA2ED,gGAAgG;AAChG,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,GAAE,MAAM,GAAG,KAAc,GACxF,eAAe,CAmBjB"}

package/dist/client-contract/query.js

@@ -0,0 +1,121 @@
+import { clientError, ProtocolClientContractError } from './errors.js';
+import { validateProtocolClientContract } from './validate.js';
+import { record, shape, integer, timezone } from './primitives.js';
+import { freezeClientData, snapshotClientData } from './safe-data.js';
+function array(input, maximum) {
+    if (!Array.isArray(input) || input.length > maximum)
+        clientError('HQ_CLIENT_QUERY');
+    return input;
+}
+function strings(input, allowed, maximum) {
+    const values = array(input, maximum);
+    if (values.some(v => typeof v !== 'string' || !allowed.includes(v))
+        || new Set(values).size !== values.length)
+        clientError('HQ_CLIENT_QUERY');
+    return values;
+}
+function predicateValue(value, type, operator, maximum) {
+    const values = operator === 'between' || operator === 'in' || operator === 'notIn'
+        ? array(value, operator === 'between' ? 2 : maximum) : [value];
+    if (values.length === 0 || (operator === 'between' && values.length !== 2))
+        clientError('HQ_CLIENT_QUERY');
+    for (const item of values) {
+        if (type === 'number' ? typeof item !== 'number' || !Number.isFinite(item)
+            : type === 'boolean' ? typeof item !== 'boolean' : typeof item !== 'string')
+            clientError('HQ_CLIENT_QUERY');
+    }
+}
+function bodyFor(endpoint, source, transport) {
+    const keys = ['dimensions', 'filters', 'orderBy', 'limit', 'offset', 'includeMeta',
+        ...(endpoint.kind === 'dataset' ? ['measures', 'having'] : []),
+        ...(endpoint.time ? ['by', ...(endpoint.time.timezone ? ['timezone'] : [])] : [])];
+    if (Object.keys(source).some(key => !keys.includes(key)))
+        clientError('HQ_CLIENT_QUERY');
+    const caps = endpoint.limits;
+    const dimensions = strings(source.dimensions === undefined ? [] : source.dimensions, Object.keys(endpoint.dimensions).filter(key => endpoint.dimensions[key].groupable), caps.maxDimensions);
+    const selectedMeasures = endpoint.kind === 'metric' ? Object.keys(endpoint.measures)
+        : strings(source.measures === undefined ? endpoint.defaultMeasures : source.measures, Object.keys(endpoint.measures), caps.maxMeasures);
+    if (!dimensions.length && !selectedMeasures.length && source.by === undefined)
+        clientError('HQ_CLIENT_QUERY');
+    const filters = array(source.filters === undefined ? [] : source.filters, caps.maxPredicates);
+    for (const item of filters) {
+        const filter = shape(item, ['field', 'operator', 'value'], '');
+        if (typeof filter.field !== 'string' || !Object.hasOwn(endpoint.filters, filter.field))
+            clientError('HQ_CLIENT_QUERY');
+        const definition = endpoint.filters[filter.field];
+        if (typeof filter.operator !== 'string' || !definition.operators.includes(filter.operator))
+            clientError('HQ_CLIENT_QUERY');
+        predicateValue(filter.value, definition.type, filter.operator, caps.maxFilterValues);
+    }
+    const having = array(source.having === undefined ? [] : source.having, caps.maxPredicates - filters.length);
+    for (const item of having) {
+        const condition = shape(item, ['measure', 'operator', 'value'], '');
+        if (typeof condition.measure !== 'string' || !selectedMeasures.includes(condition.measure)
+            || !endpoint.measures[condition.measure].having
+            || typeof condition.operator !== 'string'
+            || !['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'between', 'in', 'notIn'].includes(condition.operator))
+            clientError('HQ_CLIENT_QUERY');
+        predicateValue(condition.value, 'number', condition.operator, caps.maxFilterValues);
+    }
+    if (source.by !== undefined && (typeof source.by !== 'string' || !endpoint.time?.grains.includes(source.by)))
+        clientError('HQ_CLIENT_QUERY');
+    if (source.timezone !== undefined)
+        timezone(source.timezone, '/timezone');
+    const orderBy = array(source.orderBy === undefined ? [] : source.orderBy, caps.maxOrderBy);
+    const orderable = [...dimensions.filter(key => endpoint.dimensions[key].orderable),
+        ...selectedMeasures, ...(source.by === undefined ? [] : ['period'])];
+    const ordered = new Set();
+    for (const item of orderBy) {
+        const order = shape(item, ['field', 'direction'], '');
+        if (typeof order.field !== 'string' || !orderable.includes(order.field) || ordered.has(order.field)
+            || (order.direction !== 'asc' && order.direction !== 'desc'))
+            clientError('HQ_CLIENT_QUERY');
+        ordered.add(order.field);
+    }
+    // HTTP clamps a larger limit; an agent is refused one, so it never reads a
+    // silently shortened page as the whole answer.
+    const effectiveLimit = Math.min(source.limit === undefined ? caps.defaultLimit
+        : integer(source.limit, 1, transport === 'mcp' ? caps.maxLimit : Number.MAX_SAFE_INTEGER, '/limit'), caps.maxLimit);
+    const offset = source.offset === undefined ? 0 : integer(source.offset, 0, caps.maxOffset, '/offset');
+    if (source.includeMeta !== undefined && typeof source.includeMeta !== 'boolean')
+        clientError('HQ_CLIENT_QUERY');
+    if (source.includeMeta === true && !endpoint.metadata)
+        clientError('HQ_CLIENT_QUERY');
+    const body = { dimensions, filters, orderBy, limit: effectiveLimit, offset,
+        includeMeta: source.includeMeta ?? false,
+        ...(endpoint.kind === 'dataset' ? { measures: selectedMeasures, having } : {}),
+        ...(source.by === undefined ? {} : { by: source.by }),
+        ...(source.timezone === undefined ? {} : { timezone: source.timezone }) };
+    return freezeClientData({ endpoint, body, selectedMeasures, effectiveLimit });
+}
+/** Normalize HTTP or MCP input under a signed contract; routing never comes from a tool URL. */
+export function validateProtocolClientQuery(contract, endpointId, input, transport = 'http') {
+    const validated = validateProtocolClientContract(contract);
+    try {
+        const endpoint = validated.endpoints.find(item => item.id === endpointId);
+        if (!endpoint)
+            clientError('HQ_CLIENT_QUERY');
+        const source = record(snapshotClientData(input), '');
+        if (transport === 'mcp') {
+            if (source.dataset !== endpoint.dataset || (endpoint.kind === 'metric'
+                ? source.metric !== endpoint.id : Object.hasOwn(source, 'metric')))
+                clientError('HQ_CLIENT_QUERY');
+            delete source.dataset;
+            delete source.metric;
+            if (Object.hasOwn(source, 'by'))
+                clientError('HQ_CLIENT_QUERY');
+            if (Object.hasOwn(source, 'grain')) {
+                source.by = source.grain;
+                delete source.grain;
+            }
+        }
+        else if (transport !== 'http')
+            clientError('HQ_CLIENT_QUERY');
+        return bodyFor(endpoint, source, transport);
+    }
+    catch (error) {
+        if (error instanceof ProtocolClientContractError)
+            clientError('HQ_CLIENT_QUERY', error.path);
+        throw error;
+    }
+}

package/dist/client-contract/safe-data.d.ts

@@ -0,0 +1,6 @@
+export declare const CLIENT_MAX_BYTES = 1048576;
+/** Snapshot before validation; accessors/toJSON are never invoked. Reflection can trigger Proxy traps. */
+export declare function snapshotClientData(input: unknown): unknown;
+export declare function clientCanonical(value: unknown): string;
+export declare function freezeClientData<T>(value: T): T;
+//# sourceMappingURL=safe-data.d.ts.map

package/dist/client-contract/safe-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-data.d.ts","sourceRoot":"","sources":["../../src/client-contract/safe-data.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,gBAAgB,UAAY,CAAC;AAuE1C,0GAA0G;AAC1G,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM1D;AACD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAItD;AACD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAM/C"}