@hypequery/protocol 0.10.0 → 0.10.2

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/bundles/types.d.ts

@@ -13,6 +13,8 @@ export interface ProtocolDeploymentBundleSourceRevision {
     readonly kind: 'git';
     readonly commit: string;
     readonly dirty: boolean;
+    /** Checked-out branch at build time; absent for detached HEADs. */
+    readonly branch?: string;
 }
 export interface ProtocolDeploymentBundleSource {
     /** Directory within the closed bundle that contains project-relative source files. */

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/bundles/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,kCAAmC,SAAQ,4BAA4B;IACtF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gCAAiC,SAAQ,4BAA4B;IACpF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC;CACrC;AAED,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,8BAA8B;IAC7C,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,4BAA4B,EAAE,CAAC;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,sCAAsC,CAAC;CAC5D;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,kCAAkC,CAAC;IACxD,QAAQ,CAAC,SAAS,EAAE,SAAS,gCAAgC,EAAE,CAAC;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,8BAA8B,CAAC;CAClD;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,8BAA8B,CAAC,CAAC;CAC3D;AAED,MAAM,MAAM,iCAAiC,GACzC,gBAAgB,GAChB,yBAAyB,GACzB,2BAA2B,GAC3B,yBAAyB,GACzB,wBAAwB,GACxB,6BAA6B,GAC7B,0BAA0B,GAC1B,qBAAqB,GACrB,yBAAyB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/bundles/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,kCAAmC,SAAQ,4BAA4B;IACtF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gCAAiC,SAAQ,4BAA4B;IACpF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC;CACrC;AAED,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,8BAA8B;IAC7C,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,4BAA4B,EAAE,CAAC;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,sCAAsC,CAAC;CAC5D;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,kCAAkC,CAAC;IACxD,QAAQ,CAAC,SAAS,EAAE,SAAS,gCAAgC,EAAE,CAAC;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,8BAA8B,CAAC;CAClD;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,8BAA8B,CAAC,CAAC;CAC3D;AAED,MAAM,MAAM,iCAAiC,GACzC,gBAAgB,GAChB,yBAAyB,GACzB,2BAA2B,GAC3B,yBAAyB,GACzB,wBAAwB,GACxB,6BAA6B,GAC7B,0BAA0B,GAC1B,qBAAqB,GACrB,yBAAyB,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/bundles/validate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAIV,gCAAgC,EAChC,+BAA+B,EAGhC,MAAM,YAAY,CAAC;AA4NpB,wBAAgB,wCAAwC,CACtD,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,+BAAoC,GAC5C,gCAAgC,CA+ClC"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/bundles/validate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAIV,gCAAgC,EAChC,+BAA+B,EAGhC,MAAM,YAAY,CAAC;AAmPpB,wBAAgB,wCAAwC,CACtD,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,+BAAoC,GAC5C,gCAAgC,CA+ClC"}

package/dist/bundles/validate.js

@@ -113,9 +113,9 @@ function validateArtifact(input, path, limits) {
         byteLength: byteLength(value.byteLength, `${path}.byteLength`, limits.maxArtifactBytes),
     });
 }
-function validateSourceRevision(input, path) {
+function validateSourceRevision(input, path, limits) {
     const value = requireRecord(input, path);
-    exactFields(value, ['kind', 'commit', 'dirty'], path);
+    exactFields(value, ['kind', 'commit', 'dirty'], path, ['branch']);
     if (value.kind !== 'git') {
         if (typeof value.kind !== 'string')
             bundleError('HQ_BUNDLE_TYPE', `${path}.kind`);
@@ -128,10 +128,33 @@ function validateSourceRevision(input, path) {
     }
     if (typeof value.dirty !== 'boolean')
         bundleError('HQ_BUNDLE_TYPE', `${path}.dirty`);
+    let branch;
+    if (value.branch !== undefined) {
+        if (typeof value.branch !== 'string')
+            bundleError('HQ_BUNDLE_TYPE', `${path}.branch`);
+        if (textEncoder.encode(value.branch).byteLength > limits.maxPathBytes) {
+            bundleError('HQ_BUNDLE_TOO_LARGE', `${path}.branch`);
+        }
+        const invalidCharacter = [...value.branch].some(character => {
+            const code = character.charCodeAt(0);
+            return code <= 0x20 || code === 0x7f || '~^:?*[\\'.includes(character);
+        });
+        const segments = value.branch.split('/');
+        if (!value.branch || value.branch === '@' || value.branch.startsWith('-')
+            || value.branch.startsWith('/') || value.branch.endsWith('/')
+            || value.branch.endsWith('.') || value.branch.includes('//')
+            || value.branch.includes('..') || value.branch.includes('@{')
+            || invalidCharacter
+            || segments.some(segment => segment.startsWith('.') || segment.endsWith('.lock'))) {
+            bundleError('HQ_BUNDLE_INVALID_VALUE', `${path}.branch`);
+        }
+        branch = value.branch;
+    }
     return freezeRecord({
         kind: 'git',
         commit: value.commit,
         dirty: value.dirty,
+        ...(branch ? { branch } : {}),
     });
 }
 function validateSource(input, path, limits) {
@@ -172,7 +195,7 @@ function validateSource(input, path, limits) {
         files,
         ...(value.revision === undefined
             ? {}
-            : { revision: validateSourceRevision(value.revision, `${path}.revision`) }),
+            : { revision: validateSourceRevision(value.revision, `${path}.revision`, limits) }),
     });
 }
 function hasTreeCollision(paths) {

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@hypequery/protocol",
-  "version": "0.10.0",
-  "description": "Public contracts and TypeScript reference implementation for portable Hypequery artifacts",
+  "version": "0.10.2",
+  "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"
   },