@hypequery/protocol-conformance 0.9.1 → 0.10.0

package/fixtures/manifest.json

@@ -5,113 +5,235 @@
     {
       "name": "tagged-values-v1",
       "rfc": "0001",
-      "codePrefixes": ["HQ_VALUE_"],
+      "codePrefixes": [
+        "HQ_VALUE_"
+      ],
       "files": [
-        { "path": "tagged-values-v1/success.json", "role": "success" },
-        { "path": "tagged-values-v1/rejections.json", "role": "rejection" }
+        {
+          "path": "tagged-values-v1/success.json",
+          "role": "success"
+        },
+        {
+          "path": "tagged-values-v1/rejections.json",
+          "role": "rejection"
+        }
       ]
     },
     {
       "name": "identifiers-v1",
       "rfc": "0002",
-      "codePrefixes": ["HQ_IDENTIFIER_"],
+      "codePrefixes": [
+        "HQ_IDENTIFIER_"
+      ],
       "files": [
-        { "path": "identifiers-v1/success.json", "role": "success" },
-        { "path": "identifiers-v1/rejections.json", "role": "rejection" }
+        {
+          "path": "identifiers-v1/success.json",
+          "role": "success"
+        },
+        {
+          "path": "identifiers-v1/rejections.json",
+          "role": "rejection"
+        }
       ]
     },
     {
       "name": "expressions-v1",
       "rfc": "0003",
-      "codePrefixes": ["HQ_EXPRESSION_"],
+      "codePrefixes": [
+        "HQ_EXPRESSION_"
+      ],
       "files": [
         {
           "path": "expressions-v1/success.json",
           "role": "success",
-          "sections": ["/expressions", "/queries"]
+          "sections": [
+            "/expressions",
+            "/queries"
+          ]
         },
-        { "path": "expressions-v1/rejections.json", "role": "rejection" }
+        {
+          "path": "expressions-v1/rejections.json",
+          "role": "rejection"
+        }
       ]
     },
     {
       "name": "query-schemas-v1",
       "rfc": "0004",
-      "codePrefixes": ["HQ_SCHEMA_"],
+      "codePrefixes": [
+        "HQ_SCHEMA_"
+      ],
       "files": [
-        { "path": "query-schemas-v1/success.json", "role": "success" },
-        { "path": "query-schemas-v1/rejections.json", "role": "rejection" }
+        {
+          "path": "query-schemas-v1/success.json",
+          "role": "success"
+        },
+        {
+          "path": "query-schemas-v1/rejections.json",
+          "role": "rejection"
+        }
       ]
     },
     {
       "name": "query-implementations-v1",
       "rfc": "0005",
-      "codePrefixes": ["HQ_QUERY_IMPLEMENTATION_"],
+      "codePrefixes": [
+        "HQ_QUERY_IMPLEMENTATION_"
+      ],
       "files": [
-        { "path": "query-implementations-v1/success.json", "role": "success" },
-        { "path": "query-implementations-v1/rejections.json", "role": "rejection" }
+        {
+          "path": "query-implementations-v1/success.json",
+          "role": "success"
+        },
+        {
+          "path": "query-implementations-v1/rejections.json",
+          "role": "rejection"
+        }
       ]
     },
     {
       "name": "deployments-v1",
       "rfc": "0006",
-      "codePrefixes": ["HQ_DEPLOYMENT_"],
+      "codePrefixes": [
+        "HQ_DEPLOYMENT_"
+      ],
       "files": [
-        { "path": "deployments-v1/success.json", "role": "success" },
-        { "path": "deployments-v1/rejections.json", "role": "rejection" },
-        { "path": "deployments-v1/identity.json", "role": "identity" }
+        {
+          "path": "deployments-v1/success.json",
+          "role": "success"
+        },
+        {
+          "path": "deployments-v1/rejections.json",
+          "role": "rejection"
+        },
+        {
+          "path": "deployments-v1/identity.json",
+          "role": "identity"
+        }
       ]
     },
     {
       "name": "deployment-bundles-v1",
       "rfc": "0007",
-      "codePrefixes": ["HQ_BUNDLE_"],
+      "codePrefixes": [
+        "HQ_BUNDLE_"
+      ],
       "files": [
-        { "path": "deployment-bundles-v1/success.json", "role": "success" },
-        { "path": "deployment-bundles-v1/rejections.json", "role": "rejection" },
-        { "path": "deployment-bundles-v1/identity.json", "role": "identity" }
+        {
+          "path": "deployment-bundles-v1/success.json",
+          "role": "success"
+        },
+        {
+          "path": "deployment-bundles-v1/rejections.json",
+          "role": "rejection"
+        },
+        {
+          "path": "deployment-bundles-v1/identity.json",
+          "role": "identity"
+        }
       ]
     },
     {
       "name": "deployment-releases-v1",
       "rfc": "0008",
-      "codePrefixes": ["HQ_RELEASE_"],
+      "codePrefixes": [
+        "HQ_RELEASE_"
+      ],
       "files": [
-        { "path": "deployment-releases-v1/success.json", "role": "success" },
-        { "path": "deployment-releases-v1/rejections.json", "role": "rejection" },
-        { "path": "deployment-releases-v1/identity.json", "role": "identity" }
+        {
+          "path": "deployment-releases-v1/success.json",
+          "role": "success"
+        },
+        {
+          "path": "deployment-releases-v1/rejections.json",
+          "role": "rejection"
+        },
+        {
+          "path": "deployment-releases-v1/identity.json",
+          "role": "identity"
+        }
       ]
     },
     {
       "name": "query-events-v1",
       "rfc": "0011",
-      "codePrefixes": ["HQ_EVENT_"],
+      "codePrefixes": [
+        "HQ_EVENT_"
+      ],
       "files": [
-        { "path": "query-events-v1/success.json", "role": "success" },
-        { "path": "query-events-v1/rejections.json", "role": "rejection" }
+        {
+          "path": "query-events-v1/success.json",
+          "role": "success"
+        },
+        {
+          "path": "query-events-v1/rejections.json",
+          "role": "rejection"
+        }
       ]
     },
     {
       "name": "query-diagnostics-v1",
       "rfc": "0011",
-      "codePrefixes": ["HQ_DIAGNOSTICS_"],
+      "codePrefixes": [
+        "HQ_DIAGNOSTICS_"
+      ],
       "files": [
-        { "path": "query-diagnostics-v1/success.json", "role": "success" },
-        { "path": "query-diagnostics-v1/rejections.json", "role": "rejection" }
+        {
+          "path": "query-diagnostics-v1/success.json",
+          "role": "success"
+        },
+        {
+          "path": "query-diagnostics-v1/rejections.json",
+          "role": "rejection"
+        }
       ]
     },
     {
       "name": "sql-portability-v1",
       "rfc": "0003",
-      "codePrefixes": ["HQ_SQL_PORT_"],
+      "codePrefixes": [
+        "HQ_SQL_PORT_"
+      ],
       "files": [
-        { "path": "sql-portability-v1/portable.json", "role": "portable" },
-        { "path": "sql-portability-v1/non-portable.json", "role": "non-portable" }
+        {
+          "path": "sql-portability-v1/portable.json",
+          "role": "portable"
+        },
+        {
+          "path": "sql-portability-v1/non-portable.json",
+          "role": "non-portable"
+        }
+      ]
+    },
+    {
+      "name": "cache-keys-v1",
+      "rfc": "0013",
+      "codePrefixes": [
+        "HQ_CACHE_KEY_"
+      ],
+      "files": [
+        {
+          "path": "cache-keys-v1/success.json",
+          "role": "success"
+        },
+        {
+          "path": "cache-keys-v1/rejections.json",
+          "role": "rejection"
+        }
       ]
     }
   ],
   "fuzz": [
-    { "path": "fuzz-seeds-v1/value-sources.json", "family": "tagged-values-v1" },
-    { "path": "fuzz-seeds-v1/structured-values.json" },
-    { "path": "fuzz-seeds-v1/sql-expressions.json", "family": "sql-portability-v1" }
+    {
+      "path": "fuzz-seeds-v1/value-sources.json",
+      "family": "tagged-values-v1"
+    },
+    {
+      "path": "fuzz-seeds-v1/structured-values.json"
+    },
+    {
+      "path": "fuzz-seeds-v1/sql-expressions.json",
+      "family": "sql-portability-v1"
+    }
   ]
 }

package/fixtures/query-diagnostics-v1/README.md

@@ -1,49 +1,8 @@
 # Query diagnostics v1 fixtures
 
-- `success.json` contains complete diagnostics projections accepted by the v1
-  validator.
-- `rejections.json` maps generated invalid inputs to stable failure codes.
+These fixtures exercise the privileged diagnostics projection in RFC 0011.
 
-These fixtures exercise RFC 0011. The diagnostics projection is privileged
-(RFC 0009): it may carry the non-executable RFC 0010 debug form
-(`debugQuery`), terminal reason, attempt count, runtime identity, and a safe
-message. Rejections prove result rows (`unknown-result-field`) and
-credentials (`unknown-credentials-field`) have no representable field, and
-that `newer-version` fails closed for older consumers. Note that
-`full-diagnostics.debugQuery` uses the deliberately non-executable
-placeholder syntax of RFC 0010 and carries no parameter values.
+- `success.json` contains accepted diagnostic records.
+- `rejections.json` maps invalid or generated records to stable failure codes.
 
-## Generated rejection semantics
-
-Every rejection is a deterministic transform of this pinned base projection
-(RFC 0012):
-
-```json
-{
-  "kind": "hypequery-query-diagnostics",
-  "version": 1,
-  "eventId": "0000000000000000000000000000000000000000000000000000000000000000",
-  "queryId": "1111111111111111111111111111111111111111111111111111111111111111",
-  "terminalReason": "completed",
-  "attempts": 1
-}
-```
-
-Generator types expand as follows:
-
-- `wrong-root-type`: an empty array instead of an object;
-- `missing-required-field`: the base without `attempts`;
-- `unknown-result-field`: the base plus `"rows": [[1, 2]]`;
-- `unknown-credentials-field`: the base plus `"password": "hunter2"`;
-- `newer-version`: the base with `"version": 2`;
-- `malformed-query-id`: the base with `"queryId": "bad"`;
-- `unknown-terminal-reason`: the base with `"terminalReason": "exploded"`;
-- `zero-attempts`: the base with `"attempts": 0`;
-- `control-character-message`: the base plus a `safeMessage` of `bad`,
-  U+0007 (BEL), then `message`;
-- `oversized-debug-query`: the base plus a `debugQuery` of 4097 repetitions
-  of `x`;
-- `unsafe-accessor`: the base with `kind` served by an enumerable computed
-  accessor returning `"hypequery-query-diagnostics"` instead of a plain
-  data property. Host-model conditional (RFC 0012): implementations whose
-  input model cannot express computed accessors skip this case.
+Coverage includes required fields, versions, IDs, terminal reasons, attempt counts, safe-message controls, debug-query limits, unknown result or credential fields, and unsafe accessors. Debug queries are deliberately non-executable and contain no parameter values.

package/fixtures/query-events-v1/README.md

@@ -1,60 +1,8 @@
 # Query event v1 fixtures
 
-- `success.json` contains complete events accepted by the v1 validator.
-- `rejections.json` maps generated invalid inputs to stable failure codes.
+This RFC 0011 family pins bounded, non-sensitive analytics query events.
 
-These fixtures exercise RFC 0011. Rejections include payloads attempting to
-carry SQL text (`unknown-sql-field`), parameter values
-(`unknown-parameters-field`), and a raw tenant identifier
-(`unknown-raw-tenant-field`): the default event has no field that can accept
-them, so each fails closed as an unknown field. `newer-version` proves an
-older consumer rejects an unknown version cleanly; consumers may skip such
-records without failing an event stream.
+- `success.json` contains accepted events.
+- `rejections.json` maps invalid or generated events to stable codes.
 
-## Generated rejection semantics
-
-Every rejection is a deterministic transform of this pinned base event
-(RFC 0012):
-
-```json
-{
-  "kind": "hypequery-query-event",
-  "version": 1,
-  "eventId": "0000000000000000000000000000000000000000000000000000000000000000",
-  "occurredAt": "2026-07-20T12:34:56.789Z",
-  "target": { "project": "project_1", "environment": "production" },
-  "queryName": "daily_revenue",
-  "operation": "query",
-  "outcome": "success",
-  "durationMs": 182
-}
-```
-
-Generator types expand as follows:
-
-- `wrong-root-type`: an empty array instead of an object;
-- `missing-required-field`: the base without `durationMs`;
-- `unknown-sql-field`: the base plus `"sql": "SELECT 1"`;
-- `unknown-parameters-field`: the base plus
-  `"parameters": { "start": "2026-01-01" }`;
-- `unknown-raw-tenant-field`: the base plus `"tenantId": "acme"`;
-- `newer-version`: the base with `"version": 2`;
-- `malformed-event-id`: the base with `"eventId": "bad"`;
-- `invalid-occurred-at`: the base with
-  `"occurredAt": "2026-13-40T99:99:99Z"`;
-- `failure-without-category`: the base with `"outcome": "failure"` and no
-  `errorCategory`;
-- `success-with-category`: the base plus `"errorCategory": "internal"`
-  while `outcome` stays `"success"`;
-- `unknown-error-category`: the base with `"outcome": "failure"` plus
-  `"errorCategory": "exploded"`;
-- `negative-duration`: the base with `"durationMs": -1`;
-- `invalid-target`: the base with
-  `"target": { "project": "has space", "environment": "production" }`;
-- `invalid-query-name`: the base with `"queryName": "not an identifier"`;
-- `oversized-correlation-id`: the base plus a `correlationId` of 2049
-  repetitions of `x`;
-- `unsafe-accessor`: the base with `kind` served by an enumerable computed
-  accessor returning `"hypequery-query-event"` instead of a plain data
-  property. Host-model conditional (RFC 0012): implementations whose input
-  model cannot express computed accessors skip this case.
+The default event cannot represent SQL, parameter values, or raw tenant IDs. Coverage also includes versions, event IDs, timestamps, outcomes, error categories, durations, targets, query names, correlation limits, and unsafe accessors.

package/fixtures/query-implementations-v1/README.md

@@ -1,33 +1,7 @@
-# Query implementation extension 1 fixtures
+# Query implementation v1 fixtures
 
-`success.json` contains trusted SQL expressions and all three closed named-query
-implementation kinds. `rejections.json` maps invalid artifacts to stable RFC
-0005 failure codes. Generator entries create values that JSON cannot represent
-concisely or safely.
+This family covers RFC 0005 trusted SQL expressions and the closed named-query implementation kinds.
 
-These fixtures validate artifact structure only. They do not assert that SQL is
-valid ClickHouse SQL or authorize it for execution; the trusted ClickHouse
-adapter performs those checks.
+`success.json` contains accepted structures. `rejections.json` selects either the SQL-expression or implementation surface and pins invalid values, bounded generators, and stable error codes.
 
-## Generated rejection semantics
-
-Rejection entries carry a `surface` (`sql-expression` or `implementation`)
-selecting the validated artifact kind, exactly one of `value` or
-`generator`, and the required stable `error` code. Generator types expand as
-follows (RFC 0012):
-
-- `parameters`: a compiled SQL implementation
-  `{ "kind": "compiled-sql", "dialect": "clickhouse", "operation":
-  "select", "statement": "SELECT 1", "parameters": [...], "readSources":
-  [], "tenant": { "kind": "not-required" } }` whose parameters are `count`
-  entries `{ "name": "param<i>", "source": { "kind": "input", "path":
-  "param<i>" }, "clickHouseType": "String" }` for `i` from 0 to
-  `count - 1`;
-- `sql-expression`: `{ "kind": "sql-expression", "dialect": "clickhouse",
-  "sql": ..., "output": { "kind": "string" }, "dependencies": [] }` with a
-  `sql` of `bytes` repetitions of `a`;
-- `unsafe-accessor`: an object with `kind` served by an enumerable computed
-  accessor returning `"semantic-plan"` instead of a plain data property,
-  and no other properties. Host-model conditional (RFC 0012):
-  implementations whose input model cannot express computed accessors skip
-  this case.
+Structural validation does not prove SQL is valid or authorize execution. The trusted database adapter owns those checks.

package/fixtures/query-schemas-v1/README.md

@@ -1,25 +1,7 @@
-# Portable query schema fixtures, version 1
+# Portable query schema v1 fixtures
 
-These fixtures accompany RFC 0004. Success fixtures cover every schema kind
-and every currently portable Serve/Zod feature. Rejection fixtures cover every
-stable failure code; generators describe oversized or unsafe inputs that
-cannot be represented directly in JSON.
+These RFC 0004 fixtures cover the declarative Serve/Zod schema features that can travel between runtimes without executable transforms.
 
-## Generated rejection semantics
+`success.json` exercises every portable schema kind. `rejections.json` pins stable errors for invalid values plus generated depth, width, description-size, and unsafe-accessor boundaries.
 
-Rejection entries carry exactly one of `value` or `generator` and the
-required stable `error` code. Generator types expand as follows (RFC 0012):
-
-- `nested-array`: wraps `{ "kind": "any" }` in
-  `{ "kind": "array", "items": ... }` `depth` times;
-- `union-tree`: one `{ "kind": "union", "variants": [...] }` node whose
-  variants are 10 union nodes, each with 100 `{ "kind": "any" }` variants
-  (1011 nodes total);
-- `enum-values`: `{ "kind": "enum", "values": [...] }` with `count` values
-  `v0` through `v<count - 1>`;
-- `description`: `{ "kind": "string", "description": ... }` with a
-  description of `bytes` repetitions of `a`;
-- `unsafe-accessor`: an object with `kind` served by an enumerable computed
-  accessor returning `"string"` instead of a plain data property, and no
-  other properties. Host-model conditional (RFC 0012): implementations
-  whose input model cannot express computed accessors skip this case.
+Every rejection contains exactly one literal value or deterministic generator.

package/fixtures/sql-portability-v1/README.md

@@ -1,15 +1,6 @@
 # SQL portability v1 fixtures
 
-- `portable.json` maps SQL expression fragments in the supported subset to
-  their RFC 0003 expression AST and sorted dependency identifiers.
-- `non-portable.json` maps inputs outside the subset to the first
-  incompatibility issue code and its start offset.
+- `portable.json` maps accepted SQL expression fragments to RFC 0003 expression trees and sorted dependencies.
+- `non-portable.json` maps unsupported input to the first issue code and source offset.
 
-These fixtures exercise the R1A-07 SQL portability compiler. The supported
-subset is deliberately small: qualified and backtick-quoted identifiers,
-numeric/string/boolean/null literals, `+ - * /`, the comparison operators,
-literal `IN`/`NOT IN` lists, `BETWEEN` with literal bounds, `LIKE`,
-`AND`/`OR`/`NOT`, parentheses, and the RFC 0003 function allowlist
-(`nullIfZero`, `coalesce`, `round`, `floor`, `ceil`). Statements, casts,
-subqueries, lambdas, comments, unlisted functions, backslash escapes, and
-non-literal `IN`/`BETWEEN` operands are non-portable by construction.
+The portable subset covers identifiers, literals, arithmetic, comparisons, literal `IN` lists, literal `BETWEEN`, `LIKE`, boolean logic, parentheses, and the approved formula functions. Statements, subqueries, casts, lambdas, comments, unapproved functions, and dynamic list/range operands remain non-portable by construction.

package/fixtures/tagged-values-v1/README.md

@@ -34,11 +34,22 @@ Generators expand as follows:
 - `array`: creates one tagged array containing `items` copies of `value`;
 - `array-tree`: creates one tagged array containing `branches` tagged arrays,
   each containing `itemsPerBranch` copies of `value`;
-- `repeat-string`: concatenates `count` copies of the UTF-8 string `utf8`.
+- `repeat-string`: concatenates `count` copies of the UTF-8 string `utf8`;
+- `unsafe-accessor`: builds an object whose `$hypequery` member is served by a
+  computed accessor rather than a plain data property. Implementations whose
+  input model cannot express computed accessors respond `skipped`, and must
+  then declare their own hostile-object suite per RFC 0012.
 
 `error` is the required stable failure code. `phase` identifies the earliest
 stage that must reject the input. A consumer may reject earlier only when it
 returns the same code and does not partially execute or hash the value.
 
+## What these fixtures cannot express
+
+Metadata integers are accepted by value, not by lexical form: `1`, `1.0`, and
+`1e0` all denote `1` and all canonicalize to `1`. The manifest cannot carry
+that distinction — writing `1.0` into a `value` field serializes back to `1` —
+so per-language unit tests cover the coercion of an integral host float.
+
 Fixture runners must not pass `sourceUtf8` through an ordinary JSON dictionary
 parser before duplicate-key detection.

package/fixtures/tagged-values-v1/rejections.json

@@ -294,5 +294,94 @@
       "count": 65537
     },
     "error": "HQ_VALUE_TOO_LARGE"
+  },
+  {
+    "id": "datetime64-nanoseconds-overflow",
+    "phase": "model",
+    "value": {
+      "$hypequery": {
+        "type": "datetime",
+        "version": 1,
+        "clickhouseType": "DateTime64",
+        "precision": 9,
+        "timezone": "UTC",
+        "value": "2262-04-11T23:47:16.854775808Z"
+      }
+    },
+    "error": "HQ_VALUE_OUT_OF_RANGE"
+  },
+  {
+    "id": "timezone-fixed-offset",
+    "phase": "model",
+    "value": {
+      "$hypequery": {
+        "type": "datetime",
+        "version": 1,
+        "clickhouseType": "DateTime",
+        "precision": 0,
+        "timezone": "+02:00",
+        "value": "2026-07-13T14:30:45Z"
+      }
+    },
+    "error": "HQ_VALUE_INVALID_FORMAT"
+  },
+  {
+    "id": "control-character-vertical-tab",
+    "phase": "model",
+    "value": "before\u000bafter",
+    "error": "HQ_VALUE_CONTROL_CHARACTER"
+  },
+  {
+    "id": "value-unsafe-accessor",
+    "phase": "model",
+    "generator": {
+      "type": "unsafe-accessor"
+    },
+    "error": "HQ_VALUE_UNSAFE_OBJECT"
+  },
+  {
+    "id": "timezone-offset-shaped",
+    "phase": "model",
+    "value": {
+      "$hypequery": {
+        "type": "datetime",
+        "version": 1,
+        "clickhouseType": "DateTime",
+        "precision": 0,
+        "timezone": "+0200",
+        "value": "2026-07-13T14:30:45Z"
+      }
+    },
+    "error": "HQ_VALUE_INVALID_FORMAT"
+  },
+  {
+    "id": "timezone-leading-underscore",
+    "phase": "model",
+    "value": {
+      "$hypequery": {
+        "type": "datetime",
+        "version": 1,
+        "clickhouseType": "DateTime",
+        "precision": 0,
+        "timezone": "_Foo/Bar",
+        "value": "2026-07-13T14:30:45Z"
+      }
+    },
+    "error": "HQ_VALUE_INVALID_FORMAT"
+  },
+  {
+    "id": "timezone-too-long",
+    "phase": "model",
+    "value": {
+      "$hypequery": {
+        "type": "datetime",
+        "version": 1,
+        "clickhouseType": "DateTime",
+        "precision": 0,
+        "timezone": "Aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "value": "2026-07-13T14:30:45Z"
+      }
+    },
+    "error": "HQ_VALUE_TOO_LARGE"
   }
 ]