@hypequery/protocol 0.10.1 → 0.11.0

package/README.md

@@ -1,99 +1,68 @@
 # @hypequery/protocol
 
-Public contracts and the TypeScript reference implementation for portable
-Hypequery artifacts.
-
-## Current status
-
-This package contains proposed version 1 tagged values, identifiers,
-expressions, query schemas and implementations, Dataset deployment contracts,
-and deployment bundle manifests. The API remains pre-stable while the
-language-neutral specifications and conformance fixtures are reviewed; these
-drafts do not yet establish a stable Cloud protocol.
-
-The normative source is
-[`specs/security-protocol`](../../specs/security-protocol/README.md).
-
-## Scope
-
-The package contains deterministic, framework-independent implementations of
-accepted protocol rules. The current implementation provides strict tagged
-value validation, RFC 8785 canonical encoding, duplicate-aware decoding,
-portable logical identifiers, closed expression and schema trees, query
-implementation artifacts, and a validated deployment envelope with a
-domain-separated identity.
-
-It will not connect to ClickHouse, execute queries, load project source, access
-credentials or the environment, perform network or filesystem I/O, implement
-authentication or tenancy, or contain CLI, HTTP, UI, and Cloud operations.
-
-Self-hosted Serve continues to run project source directly. Deployment bundles
-are required only by Cloud deployment and may be generated ephemerally for
-local compatibility and security diagnostics.
-
-## Public API
-
-Only the root package export is public. Deep imports from `src` or `dist` are
-unsupported. Package SemVer and protocol/artifact versions are separate; an
-installed npm version never determines an artifact's identity.
-
-The proposed tagged-value surface exports:
-
-- `validateCanonicalValue`
-- `encodeCanonicalValue` and `encodeCanonicalValueToString`
-- `decodeCanonicalValue`
-- `hashCanonicalValue`
-- `ProtocolValueError` and stable error-code types
-- tagged-value, option, and limit types
-
-The raw conformance digest is not a deployment identity or shared cache key.
-Those domains require separate, versioned, domain-separated contracts.
-
-The proposed identifier surface exports strict parse, guard, split, and join
-helpers for simple and dot-qualified logical identifiers. Identifiers are
-ASCII, case-sensitive, preserved exactly, and are not SQL identifiers.
-
-The proposed expression surface exports strict validators and immutable types
-for derived formulas, comparisons, filtered aggregations, all current dataset
-aggregations, and dataset/metric query envelopes. It intentionally excludes
-caller-supplied SQL and tenant identity; consumers validate names and policy
-against a dataset contract before execution.
-
-The proposed schema surface exports strict types and validation for portable
-query input/output schemas. It covers the current declarative Serve/Zod schema
-features without depending on Zod or embedding executable transforms and
-refinements. The reusable schema-value parser applies defaults and unknown
-property policy to bounded plain wire values and returns detached immutable
-values for execution adapters.
-
-The proposed query-implementation surface keeps trusted implementation details
-separate from public query intent. It covers Dataset SQL expressions, fixed
-semantic plans, compiled read-only ClickHouse statements with bound input or
-tenant parameters, and hashed Node/Python runtime references for Serve handlers
-that cannot be lowered portably. Validation does not execute or authorize SQL.
-
-The proposed deployment surface combines complete Dataset definitions, named
-Serve queries, endpoint policy, and runtime artifact identities into one strict
-versioned envelope. Dataset and Serve adapters live in their owning packages;
-the protocol package remains deterministic and framework-independent.
-Validated envelopes can be encoded as canonical RFC 8785 bytes and identified
-with the deployment-v1 domain-separated SHA-256 digest.
-
-The proposed deployment-bundle surface validates the portable manifest that
-binds a deployment identity to exact deployment and runtime artifact files. It
-provides canonical encoding and a separate bundle-v1 identity. Filesystem-safe
-writing remains in the CLI, while reusable filesystem verification and
-receiving-side intake live in `@hypequery/deployment`; this package performs no
-I/O.
-
-The proposed deployment-release surface binds one verified bundle identity to
-an explicit project and environment. Its deterministic identity serves as the
-idempotency key for authenticated deployment submission without putting
-credentials, timestamps, release state, or provider behavior into the envelope.
-
-## Runtime compatibility
-
-This package is ESM-only. Consumers must load it with `import`; CommonJS
-`require()` and a dual ESM/CommonJS build are intentionally out of scope.
-Older tools that ignore the package `exports` map and attempt to require the
-`main` entry may fail with `ERR_REQUIRE_ESM`.
+`@hypequery/protocol` is the deterministic TypeScript reference implementation for Hypequery’s portable, language-neutral artifacts. It validates and canonically encodes semantic expressions, query schemas, deployment contracts, bundle manifests, release envelopes, query events, and diagnostics without connecting to a database or executing user code.
+
+The normative source is [`specs/security-protocol`](../../specs/security-protocol/README.md). The package is pre-stable while the draft wire contracts and conformance fixtures are reviewed; the npm version is not an artifact version.
+
+## What the protocol solves
+
+Hypequery authoring tools, deployment systems, runtimes, and implementations in different languages need to agree on four things:
+
+1. which values and structures are accepted;
+2. the exact canonical bytes for an accepted artifact;
+3. the stable identity derived from those bytes;
+4. the failure code returned for rejected input.
+
+This package implements those rules in TypeScript. Python and other implementations are tested against the same fixtures with `@hypequery/protocol-conformance`.
+
+## Main surfaces
+
+- canonical tagged values and RFC 8785 encoding
+- strict simple and qualified logical identifiers
+- closed semantic expression and query envelopes
+- portable input and output schemas
+- trusted query implementation artifacts
+- dataset and named-query deployment contracts
+- closed deployment bundle manifests
+- project/environment release envelopes
+- compiled query settings, cancellation, events, and diagnostics
+
+The package performs no filesystem or network I/O. It does not load project source, choose credentials, connect to ClickHouse, authenticate users, resolve tenants, or host HTTP routes. Those jobs remain with the CLI, deployment package, and runtime adapters.
+
+## Canonical values
+
+The root export includes validation, encoding, decoding, hashing, errors, and the related immutable types:
+
+```ts
+import {
+  validateCanonicalValue,
+  encodeCanonicalValueToString,
+  decodeCanonicalValue,
+  hashCanonicalValue,
+  ProtocolValueError,
+} from '@hypequery/protocol';
+```
+
+Domain-specific identities remain separate. A raw canonical-value digest is not automatically a deployment, bundle, release, or cache identity.
+
+## Portable analytics definitions
+
+Expression validators cover derived formulas, comparisons, filtered aggregates, the full dataset aggregation surface, and metric/dataset query envelopes. Runtime callers provide semantic names and values; they cannot embed SQL or tenant identity in these portable query structures.
+
+Schema validators cover the declarative Serve/Zod features that can travel between runtimes without importing Zod or executable refinements. Schema application handles defaults and unknown properties on bounded wire values.
+
+## Deployment artifacts
+
+A deployment combines dataset definitions, named Serve queries, endpoint policy, and runtime artifact identities in one strict versioned envelope. Bundle manifests bind that deployment and every runtime file by path, byte length, and hash. Release envelopes bind a verified bundle to one explicit project and environment.
+
+Canonical encoders and domain-separated SHA-256 identities make these artifacts reproducible across language implementations. Filesystem-safe construction and verification live in `@hypequery/deployment` and the CLI.
+
+## Package use
+
+Only the root package export is public. Package SemVer and protocol versions are deliberately separate. The package is ESM-only and must be loaded with `import`.
+
+Self-hosted `@hypequery/serve` can continue to run application source directly. Portable deployment bundles are needed for deployment, compatibility checks, and cross-runtime handoff—not for ordinary local query execution.
+
+## License
+
+Apache-2.0.

package/dist/cache-keys/cache-keys.d.ts

@@ -0,0 +1,19 @@
+import { type DeriveProtocolCacheKeyOptions, type ProtocolCacheKeyErrorCode } from './types.js';
+export declare class ProtocolCacheKeyError extends Error {
+    readonly code: ProtocolCacheKeyErrorCode;
+    constructor(code: ProtocolCacheKeyErrorCode);
+}
+/**
+ * Derives the opaque namespace prefix. Truncated to 16 bytes because it is a
+ * grouping label for prefix operations, not an authentication tag.
+ */
+export declare function deriveProtocolCacheNamespaceToken(secret: Uint8Array, project: string, environment: string): string;
+/**
+ * Derives the opaque store key for one canonical preimage (RFC 0013).
+ *
+ * The preimage never appears in the result. An unkeyed digest would be
+ * offline-guessable — the schema is public and identifier value spaces are
+ * small — so the derivation is an HMAC under a per-namespace secret.
+ */
+export declare function deriveProtocolCacheKey(options: DeriveProtocolCacheKeyOptions): string;
+//# sourceMappingURL=cache-keys.d.ts.map

package/dist/cache-keys/cache-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-keys.d.ts","sourceRoot":"","sources":["../../src/cache-keys/cache-keys.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,6BAA6B,EAClC,KAAK,yBAAyB,EAC/B,MAAM,YAAY,CAAC;AAUpB,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;gBAE7B,IAAI,EAAE,yBAAyB;CAO5C;AA8FD;;;GAGG;AACH,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,MAAM,CAUR;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,6BAA6B,GAAG,MAAM,CA8BrF"}

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

@@ -0,0 +1,141 @@
+import { hmac } from '@noble/hashes/hmac';
+import { sha256 } from '@noble/hashes/sha2';
+import { validateProtocolDeploymentReleaseTarget } from '../releases/validate.js';
+import { PROTOCOL_CACHE_KEY_LIMITS, } from './types.js';
+const SCHEME = 'hq1';
+const NAMESPACE_DOMAIN = 'hypequery.cache.namespace.v1';
+const ENTRY_DOMAIN = 'hypequery.cache.entry.v1';
+const textEncoder = new TextEncoder();
+const BASE64URL = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+export class ProtocolCacheKeyError extends Error {
+    code;
+    constructor(code) {
+        // The message is the code and nothing else: an error here has the secret
+        // and the preimage in scope, and neither may reach a log.
+        super(code);
+        this.name = 'ProtocolCacheKeyError';
+        this.code = code;
+    }
+}
+function cacheKeyError(code) {
+    throw new ProtocolCacheKeyError(code);
+}
+/** RFC 4648 base64url without padding. */
+function base64url(bytes) {
+    let out = '';
+    for (let index = 0; index < bytes.length; index += 3) {
+        const b0 = bytes[index];
+        const b1 = bytes[index + 1];
+        const b2 = bytes[index + 2];
+        out += BASE64URL[b0 >> 2];
+        out += BASE64URL[((b0 & 0x03) << 4) | ((b1 ?? 0) >> 4)];
+        if (b1 === undefined)
+            break;
+        out += BASE64URL[((b1 & 0x0f) << 2) | ((b2 ?? 0) >> 6)];
+        if (b2 === undefined)
+            break;
+        out += BASE64URL[b2 & 0x3f];
+    }
+    return out;
+}
+/**
+ * Joins parts with a single 0x00 byte. RFC 0008 restricts deployment target
+ * tokens to an ASCII grammar that excludes 0x00, so the concatenation is
+ * injective — which is why the namespace must be validated before this runs.
+ */
+function joinNulSeparated(parts) {
+    const total = parts.reduce((sum, part) => sum + part.byteLength, 0) + parts.length - 1;
+    const out = new Uint8Array(total);
+    let offset = 0;
+    parts.forEach((part, index) => {
+        if (index > 0) {
+            out[offset] = 0x00;
+            offset += 1;
+        }
+        out.set(part, offset);
+        offset += part.byteLength;
+    });
+    return out;
+}
+function requireSecret(secret) {
+    if (!secret || secret.byteLength === 0)
+        cacheKeyError('HQ_CACHE_KEY_SECRET_MISSING');
+    if (secret.byteLength < PROTOCOL_CACHE_KEY_LIMITS.minSecretBytes) {
+        cacheKeyError('HQ_CACHE_KEY_SECRET_TOO_SHORT');
+    }
+    return secret;
+}
+function requireNamespace(namespace) {
+    try {
+        const target = validateProtocolDeploymentReleaseTarget(namespace);
+        return {
+            project: textEncoder.encode(target.project),
+            environment: textEncoder.encode(target.environment),
+        };
+    }
+    catch {
+        // Deliberately does not forward release-target validation details: a
+        // single code keeps callers from branching on namespace internals.
+        cacheKeyError('HQ_CACHE_KEY_INVALID_NAMESPACE');
+    }
+}
+function requireKeyVersion(keyVersion) {
+    if (typeof keyVersion !== 'number'
+        || !Number.isSafeInteger(keyVersion)
+        || keyVersion < PROTOCOL_CACHE_KEY_LIMITS.minKeyVersion
+        || keyVersion > PROTOCOL_CACHE_KEY_LIMITS.maxKeyVersion) {
+        cacheKeyError('HQ_CACHE_KEY_INVALID_VERSION');
+    }
+    return keyVersion;
+}
+function requirePreimage(preimage) {
+    if (typeof preimage === 'string'
+        && preimage.length > PROTOCOL_CACHE_KEY_LIMITS.maxPreimageBytes) {
+        cacheKeyError('HQ_CACHE_KEY_PREIMAGE_TOO_LARGE');
+    }
+    const bytes = typeof preimage === 'string' ? textEncoder.encode(preimage) : preimage;
+    if (bytes.byteLength > PROTOCOL_CACHE_KEY_LIMITS.maxPreimageBytes) {
+        cacheKeyError('HQ_CACHE_KEY_PREIMAGE_TOO_LARGE');
+    }
+    return bytes;
+}
+/**
+ * Derives the opaque namespace prefix. Truncated to 16 bytes because it is a
+ * grouping label for prefix operations, not an authentication tag.
+ */
+export function deriveProtocolCacheNamespaceToken(secret, project, environment) {
+    const key = requireSecret(secret);
+    const namespace = requireNamespace({ project, environment });
+    const input = joinNulSeparated([
+        textEncoder.encode(NAMESPACE_DOMAIN),
+        namespace.project,
+        namespace.environment,
+    ]);
+    const mac = hmac(sha256, key, input);
+    return base64url(mac.slice(0, PROTOCOL_CACHE_KEY_LIMITS.namespaceTokenBytes));
+}
+/**
+ * Derives the opaque store key for one canonical preimage (RFC 0013).
+ *
+ * The preimage never appears in the result. An unkeyed digest would be
+ * offline-guessable — the schema is public and identifier value spaces are
+ * small — so the derivation is an HMAC under a per-namespace secret.
+ */
+export function deriveProtocolCacheKey(options) {
+    const secret = requireSecret(options.secret);
+    const { project, environment } = requireNamespace(options.namespace);
+    const keyVersion = requireKeyVersion(options.keyVersion);
+    const preimage = requirePreimage(options.preimage);
+    const namespaceToken = base64url(hmac(sha256, secret, joinNulSeparated([textEncoder.encode(NAMESPACE_DOMAIN), project, environment])).slice(0, PROTOCOL_CACHE_KEY_LIMITS.namespaceTokenBytes));
+    // The namespace participates in the entry MAC directly, not only through the
+    // prefix, so two namespaces cannot collide even in a store that ignores
+    // prefixes.
+    const entryMac = hmac(sha256, secret, joinNulSeparated([textEncoder.encode(ENTRY_DOMAIN), project, environment, preimage]));
+    const key = `${SCHEME}.${keyVersion}.${namespaceToken}.${base64url(entryMac)}`;
+    /* c8 ignore next 3 -- unreachable with version-1 limits; a guard against a
+       future format change silently exceeding what stores accept. */
+    if (textEncoder.encode(key).byteLength > PROTOCOL_CACHE_KEY_LIMITS.maxStoreKeyBytes) {
+        cacheKeyError('HQ_CACHE_KEY_INVALID_VERSION');
+    }
+    return key;
+}

package/dist/cache-keys/index.d.ts

@@ -0,0 +1,4 @@
+export { ProtocolCacheKeyError, deriveProtocolCacheKey, deriveProtocolCacheNamespaceToken, } from './cache-keys.js';
+export { PROTOCOL_CACHE_KEY_LIMITS } from './types.js';
+export type { DeriveProtocolCacheKeyOptions, ProtocolCacheKeyErrorCode, ProtocolCacheKeyNamespace, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cache-keys/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache-keys/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,iCAAiC,GAClC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AACvD,YAAY,EACV,6BAA6B,EAC7B,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,YAAY,CAAC"}

package/dist/cache-keys/index.js

@@ -0,0 +1,2 @@
+export { ProtocolCacheKeyError, deriveProtocolCacheKey, deriveProtocolCacheNamespaceToken, } from './cache-keys.js';
+export { PROTOCOL_CACHE_KEY_LIMITS } from './types.js';

package/dist/cache-keys/types.d.ts

@@ -0,0 +1,26 @@
+/** Absolute limits for cache key version 1 (RFC 0013). */
+export declare const PROTOCOL_CACHE_KEY_LIMITS: {
+    readonly minSecretBytes: 32;
+    readonly maxPreimageBytes: 1048576;
+    readonly namespaceTokenBytes: 16;
+    readonly entryMacBytes: 32;
+    readonly maxStoreKeyBytes: 128;
+    readonly minKeyVersion: 1;
+    readonly maxKeyVersion: 2147483647;
+};
+export type ProtocolCacheKeyErrorCode = 'HQ_CACHE_KEY_SECRET_MISSING' | 'HQ_CACHE_KEY_SECRET_TOO_SHORT' | 'HQ_CACHE_KEY_INVALID_NAMESPACE' | 'HQ_CACHE_KEY_INVALID_VERSION' | 'HQ_CACHE_KEY_PREIMAGE_TOO_LARGE';
+/** The RFC 0008 deployment target a cache entry belongs to. */
+export interface ProtocolCacheKeyNamespace {
+    readonly project: string;
+    readonly environment: string;
+}
+export interface DeriveProtocolCacheKeyOptions {
+    /** At least 32 bytes, distinct per namespace, never derived from a name. */
+    readonly secret: Uint8Array;
+    readonly namespace: ProtocolCacheKeyNamespace;
+    /** Increments whenever the namespace secret is rotated. */
+    readonly keyVersion: number;
+    /** Canonical bytes identifying the query. Stays in memory. */
+    readonly preimage: Uint8Array | string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cache-keys/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cache-keys/types.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,eAAO,MAAM,yBAAyB;;;;;;;;CAQ5B,CAAC;AAEX,MAAM,MAAM,yBAAyB,GACjC,6BAA6B,GAC7B,+BAA+B,GAC/B,gCAAgC,GAChC,8BAA8B,GAC9B,iCAAiC,CAAC;AAEtC,+DAA+D;AAC/D,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,6BAA6B;IAC5C,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,yBAAyB,CAAC;IAC9C,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAAC;CACxC"}

package/dist/cache-keys/types.js

@@ -0,0 +1,10 @@
+/** Absolute limits for cache key version 1 (RFC 0013). */
+export const PROTOCOL_CACHE_KEY_LIMITS = {
+    minSecretBytes: 32,
+    maxPreimageBytes: 1_048_576,
+    namespaceTokenBytes: 16,
+    entryMacBytes: 32,
+    maxStoreKeyBytes: 128,
+    minKeyVersion: 1,
+    maxKeyVersion: 2_147_483_647,
+};

package/dist/index.d.ts

@@ -1,10 +1,12 @@
 export { DEFAULT_CANONICAL_VALUE_LIMITS, ProtocolValueError, decodeCanonicalValue, encodeCanonicalValue, encodeCanonicalValueToString, hashCanonicalValue, validateCanonicalValue, } from './values/index.js';
 export type { ArrayTaggedValue, BytesTaggedValue, CanonicalValue, CanonicalValueLimits, CanonicalValueOptions, DateTaggedValue, DatetimeTaggedValue, DecimalTaggedValue, EnumTaggedValue, IntegerTaggedValue, MapTaggedValue, ProtocolValueErrorCode, TaggedValue, TupleTaggedValue, UuidTaggedValue, } from './values/index.js';
 export { PROTOCOL_IDENTIFIER_LIMITS, ProtocolIdentifierError, isProtocolIdentifier, isProtocolQualifiedIdentifier, joinProtocolQualifiedIdentifier, parseProtocolIdentifier, parseProtocolQualifiedIdentifier, splitProtocolQualifiedIdentifier, } from './identifiers/index.js';
+export { PROTOCOL_CACHE_KEY_LIMITS, ProtocolCacheKeyError, deriveProtocolCacheKey, deriveProtocolCacheNamespaceToken, } from './cache-keys/index.js';
 export { DEFAULT_PROTOCOL_EXPRESSION_LIMITS, ProtocolExpressionError, validateProtocolExpression, validateProtocolSemanticQuery, } from './expressions/index.js';
 export { DEFAULT_PROTOCOL_SCHEMA_LIMITS, DEFAULT_PROTOCOL_SCHEMA_VALUE_LIMITS, ProtocolSchemaError, ProtocolSchemaValueError, applyProtocolSchemaValue, createProtocolSchemaValueParser, resolveProtocolSchemaValueLimits, validateProtocolSchema, } from './schemas/index.js';
 export type { ProtocolSchema, ProtocolSchemaErrorCode, ProtocolSchemaLimits, ProtocolSchemaOptions, ProtocolSchemaValueLimits, ProtocolSchemaValueOptions, ProtocolSchemaValueParser, } from './schemas/index.js';
 export type { ProtocolAggregation, ProtocolBinaryOperator, ProtocolComparisonOperator, ProtocolDatasetQuery, ProtocolExpression, ProtocolExpressionErrorCode, ProtocolExpressionLimits, ProtocolExpressionOptions, ProtocolFunctionName, ProtocolMetricQuery, ProtocolOrderBy, ProtocolSemanticQuery, ProtocolTimeGrain, } from './expressions/index.js';
+export type { DeriveProtocolCacheKeyOptions, ProtocolCacheKeyErrorCode, ProtocolCacheKeyNamespace, } from './cache-keys/index.js';
 export type { ProtocolIdentifier, ProtocolIdentifierErrorCode, ProtocolQualifiedIdentifier, } from './identifiers/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';

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

@@ -1,5 +1,6 @@
 export { DEFAULT_CANONICAL_VALUE_LIMITS, ProtocolValueError, decodeCanonicalValue, encodeCanonicalValue, encodeCanonicalValueToString, hashCanonicalValue, validateCanonicalValue, } from './values/index.js';
 export { PROTOCOL_IDENTIFIER_LIMITS, ProtocolIdentifierError, isProtocolIdentifier, isProtocolQualifiedIdentifier, joinProtocolQualifiedIdentifier, parseProtocolIdentifier, parseProtocolQualifiedIdentifier, splitProtocolQualifiedIdentifier, } from './identifiers/index.js';
+export { PROTOCOL_CACHE_KEY_LIMITS, ProtocolCacheKeyError, deriveProtocolCacheKey, deriveProtocolCacheNamespaceToken, } from './cache-keys/index.js';
 export { DEFAULT_PROTOCOL_EXPRESSION_LIMITS, ProtocolExpressionError, validateProtocolExpression, validateProtocolSemanticQuery, } from './expressions/index.js';
 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';

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

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/values/validate.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AA0VpB,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,qBAA0B,GAClC,cAAc,CAOhB;AAYD,kFAAkF;AAClF,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,QAAQ,CAAC,oBAAoB,CAAC,EACtC,sBAAsB,CAAC,EAAE,MAAM,GAC9B,cAAc,CAGhB;AAED,6EAA6E;AAC7E,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,QAAQ,CAAC,oBAAoB,CAAC,EACtC,sBAAsB,CAAC,EAAE,MAAM,GAC9B,cAAc,CAEhB"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/values/validate.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAqWpB,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,qBAA0B,GAClC,cAAc,CAOhB;AAYD,kFAAkF;AAClF,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,QAAQ,CAAC,oBAAoB,CAAC,EACtC,sBAAsB,CAAC,EAAE,MAAM,GAC9B,cAAc,CAGhB;AAED,6EAA6E;AAC7E,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,QAAQ,CAAC,oBAAoB,CAAC,EACtC,sBAAsB,CAAC,EAAE,MAAM,GAC9B,cAAc,CAEhB"}

package/dist/values/validate.js

@@ -40,10 +40,15 @@ function requireMetadataInteger(value, path) {
     }
     return value;
 }
+// Tab, line feed, and carriage return are permitted so authored prose can
+// span lines; JCS escapes them deterministically. Every other C0 control, DEL,
+// and the C1 range stay forbidden.
+const ALLOWED_CONTROL_CHARACTERS = new Set([0x09, 0x0a, 0x0d]);
 function validateUnicode(value, path, maxBytes) {
     for (let index = 0; index < value.length; index += 1) {
         const code = value.charCodeAt(index);
-        if (code <= 0x1f || (code >= 0x7f && code <= 0x9f)) {
+        if ((code <= 0x1f && !ALLOWED_CONTROL_CHARACTERS.has(code))
+            || (code >= 0x7f && code <= 0x9f)) {
             valueError('HQ_VALUE_CONTROL_CHARACTER', path);
         }
         if (code >= 0xd800 && code <= 0xdbff) {
@@ -139,7 +144,10 @@ function validateDatetimeTag(tag, path) {
     }
     const timezone = requireString(tag.timezone, `${path}.timezone`);
     validateUnicode(timezone, `${path}.timezone`, 64);
-    if (timezone !== 'UTC' && !/^[A-Za-z_]+(?:\/[A-Za-z0-9_+-]+)+$/.test(timezone)) {
+    // Single-component identifiers are valid: UTC, EST, GMT, CET, and MST7MDT
+    // are all real tzdb entries. Existence is checked at deployment time
+    // against the server's system.time_zones, not here.
+    if (!/^[A-Za-z][A-Za-z0-9_+-]*(?:\/[A-Za-z0-9_+-]+)*$/.test(timezone)) {
         valueError('HQ_VALUE_INVALID_FORMAT', `${path}.timezone`);
     }
     const value = requireString(tag.value, `${path}.value`);

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@hypequery/protocol",
-  "version": "0.10.1",
-  "description": "Public contracts and TypeScript reference implementation for portable Hypequery artifacts",
+  "version": "0.11.0",
+  "description": "Portable analytics contracts and TypeScript reference implementation for Hypequery",
+  "keywords": [
+    "hypequery",
+    "protocol",
+    "analytics",
+    "semantic-layer",
+    "typescript",
+    "canonical-json"
+  ],
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -26,10 +34,10 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/hypequery/hypequery.git",
+    "url": "git+https://github.com/hypequery/hypequery.git",
     "directory": "packages/protocol"
   },
-  "homepage": "https://github.com/hypequery/hypequery/tree/main/packages/protocol",
+  "homepage": "https://hypequery.com",
   "bugs": {
     "url": "https://github.com/hypequery/hypequery/issues"
   },