@jarenjs/contract 0.73.0 → 0.75.0

package/README.md

@@ -739,3 +739,35 @@ Every subpath a consumer can import, derived from the manifest by
 Author JSON template catalogs and MessageSpec references with the
 [messages pen](../linq/docs/MESSAGES-PEN.md); existing locale render functions
 retain their pluralization and formatting behavior.
+
+## Structured query inputs and app reconnect
+
+Object- and array-typed query members use one JSON-encoded parameter,
+including empty arrays, nulls and nested values. Scalar strings stay
+literal; parsed JSON is validated without coercion. The client, URL
+builder, server dispatcher and OpenAPI projection share this codec.
+Malformed or repeated JSON members are `JC2012`. Handwritten callers
+must migrate repeated array keys (`tag=a&tag=b`) to one encoded JSON array;
+deploy matching client/server versions and revise the contract's `version`
+for revision negotiation. See [the wire rules](docs/CONTRACT-FORMAT.md#4-the-http-binding-and-member-locations).
+
+Opt into HTTP subscription recovery per operation:
+
+```javascript
+const binding = contractAppBinding(contract, {
+  subs: { 'board.feed': { reconnect: { max: 2 } } },
+});
+```
+
+The generated subscription forwards the option to `client.subscribe`.
+The slot stays live with its id and last value while reconnecting; replay
+continues from the last delivered sequence. Exhaustion surfaces `JC2097`.
+Stop, reset and app destruction stop recovery. Without the option,
+network loss is surfaced immediately; an explicit server end remains
+terminal. Port and local channel lifecycles are unchanged.
+
+The fixed-heap host-seam test measures the Node response's writable queue
+and the producer's unwritten chunk separately from bytes already accepted
+by TCP. The in-process Fetch leg can measure produced-minus-consumed
+bytes directly. Complete-byte hashes, cursor pulls and cancellation
+finalizers remain part of the same end-to-end test.

package/dist/types/app/binding.d.ts

@@ -33,6 +33,16 @@ export type ContractAppBindingOptions = {
      * - the operations the app uses; default every operation
      */
     ops?: readonly string[];
+    /**
+     * - per
+     * subscribe-operation options. Reconnect is opt-in; the slot stays live
+     * while the HTTP client resumes, and reports error after exhaustion.
+     */
+    subs?: Record<string, {
+        reconnect: {
+            max: number;
+        };
+    }>;
 };
 export type TaskSlot = {
     id: number;

package/dist/types/app/subscription.d.ts

@@ -42,6 +42,9 @@ export type StreamProps = {
     snapshot: string;
     patch: string;
     error: string;
+    reconnect?: {
+        max: number;
+    };
 };
 /**
  * @typedef {import('../compile.js').Contract} Contract
@@ -60,7 +63,7 @@ export type StreamProps = {
 /**
  * The props of one generated subs entry: the operation, the slot id and
  * input resolved from state, and the action names to dispatch.
- * @typedef {{ op: string, id: number, input: unknown, snapshot: string, patch: string, error: string }} StreamProps
+ * @typedef {{ op: string, id: number, input: unknown, snapshot: string, patch: string, error: string, reconnect?: { max: number } }} StreamProps
  */
 /**
  * Make the `contract-stream` subscription handler of an app over a

package/dist/types/client/http.d.ts

@@ -262,7 +262,7 @@ export type ClientRoute = {
     method: string;
     segments: readonly import('../path.js').PathSegment[];
     queryMembers: readonly string[];
-    queryRepeated: ReadonlySet<string>;
+    queryJson: ReadonlySet<string>;
     headerMembers: readonly string[];
     headerNames: readonly string[];
     /**

package/dist/types/compile.d.ts

@@ -38,6 +38,11 @@ export type InputTransport = {
         header: readonly string[];
         repeated: readonly string[];
     };
+    /**
+     * - query members with a declared
+     * object/array type, encoded as one JSON value (including nullable unions)
+     */
+    queryJson: readonly string[];
     schemas: Readonly<Record<string, any>>;
     required: readonly string[];
 };

package/dist/types/http/dispatch.d.ts

@@ -102,9 +102,9 @@ export type Route = {
     pathMembers: readonly string[];
     queryMembers: ReadonlySet<string>;
     /**
-     * - array-typed query members
+     * - JSON-encoded query members
      */
-    repeated: ReadonlySet<string>;
+    queryJson: ReadonlySet<string>;
     /**
      * - member names
      */

package/dist/types/http/wire.d.ts

@@ -292,18 +292,19 @@ export declare function formatEntityTag(tag: string, strong: boolean): string;
 /**
  * Decode a query string into the declared members of an input object:
  * only declared names are set (an undeclared key is never merged, so no
- * request can smuggle a member); a `repeated` member collects every
- * occurrence into an array, every other member is last-wins; a `+` is a
+ * request can smuggle a member); JSON members decode exactly one value,
+ * scalar members are last-wins; a `+` is a
  * space and escapes decode as `application/x-www-form-urlencoded`
  * (`URLSearchParams`). Returns `false` when the query is not decodable
- * (a malformed percent-escape or invalid UTF-8) — the `JC2012` case.
+ * (malformed percent-escape, UTF-8 or JSON, or a repeated JSON member)
+ * — the `JC2012` case.
  * @param {string} query - the part after `?`, possibly empty
  * @param {ReadonlySet<string>} declared - the query member names
- * @param {ReadonlySet<string>} repeated - the array-typed ones
  * @param {Record<string, unknown>} out - the input object under assembly
+ * @param {ReadonlySet<string>} json - schema-directed JSON members
  * @returns {boolean} false when not decodable
  */
-export declare function decodeQuery(query: string, declared: ReadonlySet<string>, repeated: ReadonlySet<string>, out: Record<string, unknown>): boolean;
+export declare function decodeQuery(query: string, declared: ReadonlySet<string>, out: Record<string, unknown>, json: ReadonlySet<string>): boolean;
 /**
  * The verdict of a compiled validator under either contract: the
  * default `{ valid, errors }` or a host-injected boolean validator.

package/docs/CONTRACT-FORMAT.md

@@ -261,25 +261,44 @@ top-level `input.properties` member gets exactly one location:
    does not declare);
 4. otherwise the default: `query` for a `read`, `body` for a `command`.
 
-Path, query and header members arrive as strings and are decoded by a
-normalizer compiled **over those members only** with `coerceTypes`
-(`@jarenjs/validate/normalize`); **a body member is never coerced**. The
-compiled operation carries this as
-`input.transport = { normalize, members: { path, query, header, repeated }, schemas, required }`
-(`null` when nothing travels as a string) beside `input.effective` —
-the object schema the declared `input` resolves to (itself, or the end
-of its `$ref` chain), whose `properties` are the operation's members;
-`schemas` holds each
-transport member's declared schema and `required` the transport members
-the input requires (what a URL builder validates without the body), and
-`repeated` lists the
-query and header members whose effective schema type is `array` — a
-decoder collects repeats of those into an array (a repeated query key; a
-repeated header line or a comma-separated header list, RFC 9110 §5.3)
-before normalizing; every other query member is last-wins and every
-other header member is one line (§7.4). The server validates the
-reassembled input object with the operation's compiled validator; the
-client validates the same object before it splits it.
+Scalar path, query and header members arrive as strings and are decoded
+by a normalizer compiled over those members with `coerceTypes`
+(`@jarenjs/validate/normalize`). **JSON query members and body members are
+never coerced**, including nested values.
+
+A query member whose effective declared `type` is `object` or `array`
+(or a type array including either) uses **one JSON value in one query
+parameter**. The client applies `JSON.stringify`, then `URLSearchParams`;
+the server percent-decodes and applies `JSON.parse` before validation.
+This includes nullable and scalar/structured unions: their values always
+use JSON encoding. Empty arrays, nulls, arrays of objects, numeric object
+keys and strings inside those unions round-trip without guessing from
+text. An absent member is omitted. Plain `string` members remain literal,
+even when their text looks like JSON. `$ref` chains are resolved at
+compilation; unconstrained schemas and unions expressed only with
+`anyOf`/`oneOf` do not imply a codec — declare a top-level `type` to choose
+one. Malformed JSON or multiple occurrences of a JSON member are `JC2012`;
+a well-formed value of the wrong type is `JC2006`. Undeclared query keys
+are ignored. Scalar query members remain last-wins.
+
+The compiled operation carries
+`input.transport = { normalize, members: { path, query, header, repeated }, queryJson, schemas, required }`
+(`null` when nothing travels as a string), beside `input.effective`, the
+resolved input object schema. `schemas` and `required` describe all
+transport members for URL validation; `queryJson` lists the JSON members
+excluded from scalar normalization. `repeated` identifies array-typed
+query/header members; JSON query encoding takes precedence. Array headers
+still collect repeated lines or comma-separated values (RFC 9110 §5.3)
+before normalization; other headers require one line (§7.4). The server
+validates the reassembled input; the client validates before splitting it.
+
+**Wire migration:** array query members use `tag=["a","b"]` (URL-encoded),
+replacing `tag=a&tag=b`. Update handwritten callers and deploy matching
+client/server versions together; published contracts should change their
+`version` so revision negotiation detects a mismatched deployment. The
+OpenAPI projection declares these parameters with
+`content: { "application/json": { schema: ... } }`, rather than an
+exploded array schema.
 
 An operation bound to `GET` or `HEAD` MUST NOT carry a body-located
 member (`JC0016`) — including a `command` whose members default to the
@@ -601,12 +620,12 @@ is `JC2008`.
    stripped by the decoder); then `JSON.parse` (a failure is `JC2005`).
 7. **Assemble** the input object through a prototype-safe setter only, in
    this order: path members (raw decoded strings), query members
-   (`URLSearchParams` semantics — `+` is a space; a member listed in
-   `transport.members.repeated` collects every occurrence into an array,
-   every other member is last-wins; an **undeclared query key is
-   ignored, never merged**; an undecodable query is `JC2012`), declared
-   header members (by their lowercased name; §7.4), then the transport
-   normalizer over exactly those members (`coerceTypes`), then the body,
+   (`URLSearchParams` semantics — `+` is a space; `queryJson` members
+   decode one JSON value, scalar members are last-wins; an **undeclared
+   query key is ignored, never merged**; malformed encoding/JSON or a
+   repeated JSON member is `JC2012`), declared header members (by their
+   lowercased name; §7.4), then the scalar transport normalizer (JSON
+   members excluded), then the body,
    **never coerced**: `http.body` names a member → the parsed value is
    that member; otherwise the parsed value must be an object (`JC2006`
    with `path: ""` otherwise) and each of its own members is set unless
@@ -747,7 +766,7 @@ below; `HTTP_ERRORS` (`@jarenjs/contract/http`) is the same table as data,
 | `JC2009` | 409 | `contract/idempotency-conflict` | see §8 | the ledger says `in-progress` (retryable, `retry-after: 1`) or `mismatch` (not retryable, `details: [{ "kind": "mismatch" }]`) |
 | `JC2010` | 500 | `contract/invalid-output` | no | the handler value fails the output validator, cannot be serialized, a raw response is malformed, or a declared error's details fail their schema — the server broke the contract |
 | `JC2011` | 400 | `contract/malformed-path` | no | the path carries a malformed percent-escape |
-| `JC2012` | 400 | `contract/malformed-query` | no | the query string is not decodable (a malformed escape, invalid UTF-8) |
+| `JC2012` | 400 | `contract/malformed-query` | no | the query string is not decodable (malformed escape/UTF-8/JSON, or a repeated JSON member) |
 | `JC2013` | 501 | `contract/not-implemented` | no | a `partial` server has no handler for the operation |
 | `JC2014` | 412 | `contract/precondition-failed` | no | `If-Match` does not match the armed tag (strong comparison), or `If-None-Match` matches on a non-GET/HEAD |
 | `JC2015` | 400 | `contract/invalid-header` | no | a declared scalar header member arrived repeated, or a header value is not a string |
@@ -1341,9 +1360,9 @@ is true exactly for a 304.
    by `policy.errors.details`; **nothing was sent**.
 3. **Split by location** (`http.in`): path variables → `encodeURIComponent`
    per segment into the canonical template; query members →
-   `URLSearchParams` (an array-typed member repeats the key per element;
-   `null`/`undefined` members are omitted; a scalar is its string, a
-   non-scalar its JSON); header members → the header named by the
+   `URLSearchParams` (`queryJson` members use one JSON value, including
+   null and empty arrays; undefined is omitted; scalar transport members
+   omit null/undefined and otherwise use their string); header members → the header named by the
    member lowercased (an array as a `, `-joined list); the body: `http.body`
    names a member → `JSON.stringify` of that member's value; otherwise
    the object of the body-located members, stringified. `method` from
@@ -1712,6 +1731,23 @@ The generated actions:
 - `<ns><op>/reset` — as for tasks: `status "idle"`, `kind`/`error`
   cleared, everything else kept.
 
+Reconnect is an opt-in **binding choice**, not a new stream policy:
+`contractAppBinding(contract, { subs: { "data.live": { reconnect: { max: 2 } } } })`
+embeds the per-operation option in its generated `withQuery` props and
+`createContractSubscription` forwards it to `client.subscribe`. During
+retry/backoff the slot stays `live`, retaining its id, value and sequence;
+replay patches continue against the same cached document. Exhaustion
+surfaces `JC2097` in the slot. Explicit server end and non-network errors
+are terminal. Stop/reset/destroy cancel the active stream and prevent
+further retries. Without the option a lost stream surfaces immediately.
+Unknown/unselected/non-subscribe operations and malformed reconnect
+options are `JC1007`. Reconnection is supplied by the HTTP client; port
+and local clients retain their existing terminal channel lifecycle.
+
+The subscription handler rejects stale sequence numbers **before**
+applying a patch to its cached document, and ignores callbacks after
+cleanup; the generated action guards provide the state-side check too.
+
 The binding additionally returns `subs` — one entry per subscribe
 operation — and names its handler in `subscription`:
 
@@ -1807,7 +1843,7 @@ point). The mapping:
 |---|---|
 | — | `openapi: "3.1.0"`, `jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema"`, `info` (title/version defaulting to the contract id/version), `servers` when given |
 | operation | `paths[<canonical path>][<lowercased method>]`, paths sorted by path then method; `operationId` = the id; `summary` = `doc`'s first line (`description` = the whole `doc` when it has more); `tags` = the id's first dotted segment |
-| `http.in` `path`/`query`/`header` members | `parameters` (name, `in`, `schema`; `required` from the effective input's `required`, a path parameter always required); an idempotent operation gains the `Idempotency-Key` header parameter (required under `"required"`) |
+| `http.in` `path`/`query`/`header` members | `parameters` (name, `in`, `schema`, or `content.application/json.schema` for JSON query members; `required` from the effective input's `required`, a path parameter always required); an idempotent operation gains the `Idempotency-Key` header parameter (required under `"required"`) |
 | body members | `requestBody`: the object of the body-located members (their `required` intersection, the input's `additionalProperties`); the whole input schema when every member is body-located; the member's own schema under `http.body`; `content[<http.media>]` |
 | `output`, `http.status` | `responses[<status>]` with the output schema; no content on `204`; opaque → `content[<media>]: { type: "string", format: "binary" }` |
 | declared `errors` | one response per status: the D7 wire-error schema (`code` **enum-pinned** to the codes of that status, `details` the declared schema when present) |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/contract",
   "private": false,
-  "version": "0.73.0",
+  "version": "0.75.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -102,9 +102,9 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.73.0",
-    "@jarenjs/json": "^0.73.0",
-    "@jarenjs/validate": "^0.73.0",
-    "@jarenjs/emit": "^0.73.0"
+    "@jarenjs/core": "^0.75.0",
+    "@jarenjs/json": "^0.75.0",
+    "@jarenjs/validate": "^0.75.0",
+    "@jarenjs/emit": "^0.75.0"
   }
 }

package/src/app/binding.js

@@ -34,6 +34,9 @@ import { ContractHostError } from '../errors.js';
  * @property {string} [statePath] - where the slice lives in app state, as a
  *   chain of identifier-safe segments; default `/contract`
  * @property {readonly string[]} [ops] - the operations the app uses; default every operation
+ * @property {Record<string, { reconnect: { max: number } }>} [subs] - per
+ *   subscribe-operation options. Reconnect is opt-in; the slot stays live
+ *   while the HTTP client resumes, and reports error after exhaustion.
  */
 
 /**
@@ -145,8 +148,9 @@ function replace(path, value) {
  * @param {Record<string, any>} actions
  * @param {any[]} subs
  * @param {Record<string, any>} properties
+ * @param {{ max: number } | undefined} reconnect
  */
-function appendSubscription(contract, op, id, namespace, slot, slotQuery, idQuery, nextId, actions, subs, properties) {
+function appendSubscription(contract, op, id, namespace, slot, slotQuery, idQuery, nextId, actions, subs, properties, reconnect) {
   const idGuard = { $eq: ['$payload.id', idQuery] };
 
   setObjectMember(actions, `${namespace}${id}/start`, {
@@ -224,6 +228,7 @@ function appendSubscription(contract, op, id, namespace, slot, slotQuery, idQuer
       snapshot: `${namespace}${id}/snapshot`,
       patch: `${namespace}${id}/patch`,
       error: `${namespace}${id}/error`,
+      ...(reconnect === undefined ? {} : { reconnect: { $const: { max: reconnect.max } } }),
     },
   });
 
@@ -302,6 +307,21 @@ export function contractAppBinding(contract, options = {}) {
   }
   const ops = options.ops === undefined ? contract.ids : options.ops;
   if (!Array.isArray(ops)) throw host('ops must be an array of operation ids');
+  const streamOptions = options.subs === undefined ? {} : options.subs;
+  if (streamOptions === null || typeof streamOptions !== 'object' || Array.isArray(streamOptions))
+    throw host('subs must be an operation-options object');
+  for (const id of Object.keys(streamOptions)) {
+    if (!ops.includes(id) || !Object.hasOwn(contract.operations, id) || contract.operations[id].kind !== 'subscribe')
+      throw host(`subs names '${id}', which is not a selected subscribe operation`);
+    const entry = streamOptions[id];
+    const reconnect = entry?.reconnect;
+    if (entry === null || typeof entry !== 'object' || Array.isArray(entry)
+      || Object.keys(entry).some((key) => key !== 'reconnect')
+      || reconnect === null || typeof reconnect !== 'object' || Array.isArray(reconnect)
+      || Object.keys(reconnect).some((key) => key !== 'max')
+      || !Number.isSafeInteger(reconnect.max) || reconnect.max < 0)
+      throw host(`subs['${id}'] must be { reconnect: { max } } with a non-negative safe integer max`);
+  }
   const queryRoot = '$' + statePath.replaceAll('/', '.');
 
   /** @type {Record<string, TaskSlot | StreamSlot>} */
@@ -328,7 +348,8 @@ export function contractAppBinding(contract, options = {}) {
     const done = `${namespace}${id}/done`;
 
     if (op.kind === 'subscribe') {
-      appendSubscription(contract, op, id, namespace, slot, slotQuery, idQuery, nextId, actions, subs, properties);
+      appendSubscription(contract, op, id, namespace, slot, slotQuery, idQuery, nextId, actions, subs, properties,
+        Object.hasOwn(streamOptions, id) ? streamOptions[id].reconnect : undefined);
       setObjectMember(slice, id, { id: 0, status: 'idle', kind: null, input: null, value: null, error: null, meta: null, seq: 0 });
       required.push(id);
       continue;

package/src/app/subscription.js

@@ -48,7 +48,7 @@ import { PORT_LOCAL_ERRORS } from '../pipeline.js';
 /**
  * The props of one generated subs entry: the operation, the slot id and
  * input resolved from state, and the action names to dispatch.
- * @typedef {{ op: string, id: number, input: unknown, snapshot: string, patch: string, error: string }} StreamProps
+ * @typedef {{ op: string, id: number, input: unknown, snapshot: string, patch: string, error: string, reconnect?: { max: number } }} StreamProps
  */
 
 /**
@@ -86,12 +86,18 @@ export function createContractSubscription(client, options = {}) {
     const { op, id } = p;
     /** @type {unknown} */
     let doc = null;
+    let seq = -1;
+    let stopped = false;
     const sub = client.subscribe(op, p.input === undefined ? null : p.input, {
+      ...(p.reconnect === undefined ? {} : { reconnect: p.reconnect }),
       onSnapshot: (/** @type {unknown} */ value, /** @type {{ seq: number }} */ info) => {
+        if (stopped) return;
         doc = value;
+        seq = info.seq;
         dispatch(p.snapshot, { id, value, seq: info.seq });
       },
       onPatch: (/** @type {{ patch: any[], seq: number }} */ emission) => {
+        if (stopped || emission.seq <= seq) return;
         try {
           doc = compileJSONPatch(/** @type {any} */ (emission.patch))(doc);
         }
@@ -107,10 +113,12 @@ export function createContractSubscription(client, options = {}) {
           });
           return;
         }
+        seq = emission.seq;
         dispatch(p.patch, { id, value: doc, seq: emission.seq });
       },
-      onError: (/** @type {Outcome} */ outcome) => dispatch(p.error, { id, outcome }),
+      onError: (/** @type {Outcome} */ outcome) => { if (!stopped) dispatch(p.error, { id, outcome }); },
       onEnd: () => {
+        if (stopped) return;
         // the server ended the stream: the slot must say the channel is
         // gone, so a view can offer a reconnect (a fresh start)
         dispatch(p.error, {
@@ -121,7 +129,7 @@ export function createContractSubscription(client, options = {}) {
         });
       },
     });
-    return () => sub.stop();
+    return () => { stopped = true; sub.stop(); };
   };
 }
 

package/src/client/http.js

@@ -289,7 +289,7 @@ function transportString(v) {
  * @property {string} method
  * @property {readonly import('../path.js').PathSegment[]} segments
  * @property {readonly string[]} queryMembers
- * @property {ReadonlySet<string>} queryRepeated
+ * @property {ReadonlySet<string>} queryJson
  * @property {readonly string[]} headerMembers
  * @property {readonly string[]} headerNames
  * @property {readonly string[]} bodyMembers - body-located members when the body is their object
@@ -315,8 +315,6 @@ function prepare(op) {
   const http = op.http;
   /** @type {string[]} */
   const queryMembers = [];
-  /** @type {Set<string>} */
-  const queryRepeated = new Set();
   /** @type {string[]} */
   const headerMembers = [];
   /** @type {string[]} */
@@ -324,14 +322,12 @@ function prepare(op) {
   /** @type {string[]} */
   const bodyMembers = [];
   const transport = op.input === null ? null : op.input.transport;
-  const repeated = new Set(transport === null ? [] : transport.members.repeated);
   const members = Object.keys(http.in);
   for (let i = 0; i < members.length; i++) {
     const m = members[i];
     const loc = http.in[m];
     if (loc === 'query') {
       queryMembers.push(m);
-      if (repeated.has(m)) queryRepeated.add(m);
     }
     else if (loc === 'header') {
       headerMembers.push(m);
@@ -345,7 +341,7 @@ function prepare(op) {
     method: http.method,
     segments: http.template.segments,
     queryMembers,
-    queryRepeated,
+    queryJson: new Set(transport === null ? [] : transport.queryJson),
     headerMembers,
     headerNames,
     bodyMembers,
@@ -535,13 +531,12 @@ export function openHttpClient(contract, options = {}) {
     for (let i = 0; i < route.queryMembers.length; i++) {
       const m = route.queryMembers[i];
       const v = value[m];
-      if (v === undefined || v === null) continue;
-      if (route.queryRepeated.has(m) && Array.isArray(v)) {
-        for (let j = 0; j < v.length; j++) {
-          if (v[j] !== undefined && v[j] !== null) params.append(m, transportString(v[j]));
-        }
+      if (route.queryJson.has(m)) {
+        if (v !== undefined) params.append(m, JSON.stringify(v));
+        continue;
       }
-      else params.append(m, transportString(v));
+      if (v === undefined || v === null) continue;
+      params.append(m, transportString(v));
     }
     const query = params.toString();
     return query.length === 0 ? path : path + '?' + query;

package/src/compile.js

@@ -370,20 +370,18 @@ function checkRefs(node, docPath, scope, isRoot) {
  */
 
 /**
- * The transport half of an operation's input: the members that travel
- * as strings (path, query, header) and the normalizer that decodes them
- * with `coerceTypes` scoped to exactly those members. `repeated` lists
- * the query and header members whose effective schema type is `array` —
- * a decoder collects repeats of those into an array (a repeated query
- * key; a repeated header line or a comma-separated header list) before
- * normalizing; every other query member is last-wins and every other
- * header member is a single line. Body members are never here.
- * `schemas` holds each transport member's declared schema (what the
- * normalizer was compiled over) and `required` the transport members the
- * input schema requires — what a URL builder validates without the body.
+ * The transport half of an operation's input. Scalar path/query/header
+ * members use a compiled coercing normalizer; queryJson members carry
+ * one JSON value and bypass coercion. `repeated` marks array types (the
+ * header decoder collects their repeated lines or comma-separated list;
+ * JSON query encoding takes precedence for query members). Body members
+ * are never here. `schemas` and `required` describe every transport
+ * member for URL validation, including those excluded from normalization.
  * @typedef {Object} InputTransport
  * @property {(value: any) => any} normalize
  * @property {{ path: readonly string[], query: readonly string[], header: readonly string[], repeated: readonly string[] }} members
+ * @property {readonly string[]} queryJson - query members with a declared
+ *   object/array type, encoded as one JSON value (including nullable unions)
  * @property {Readonly<Record<string, any>>} schemas
  * @property {readonly string[]} required
  */
@@ -1074,6 +1072,7 @@ export function compileContract(doc, options = {}) {
       const queryMembers = [];
       const headerMembers = [];
       const repeated = [];
+      const queryJson = [];
       /** @type {Record<string, any>} */
       const pick = {};
       for (let i = 0; i < p.members.length; i++) {
@@ -1089,18 +1088,24 @@ export function compileContract(doc, options = {}) {
           const eff = effectiveSchema(schema, scope);
           const type = isJsonObject(eff) ? eff.type : undefined;
           if (type === 'array' || (Array.isArray(type) && type.includes('array'))) repeated.push(m);
+          if (loc === 'query' && (type === 'object' || type === 'array'
+            || (Array.isArray(type) && (type.includes('object') || type.includes('array'))))) queryJson.push(m);
         }
       }
       if (pathMembers.length + queryMembers.length + headerMembers.length > 0) {
         // the sub-schema is rooted on the document itself, so every
         // same-document `$ref` a member schema carries resolves exactly as
         // it does for the validator
-        const sub = { ...src, type: 'object', properties: pick };
+        // JSON query values have the same typing discipline as a JSON
+        // body: validate them verbatim, never coerce their descendants.
+        const scalarPick = Object.fromEntries(Object.entries(pick).filter(([name]) => !queryJson.includes(name)));
+        const sub = { ...src, type: 'object', properties: scalarPick };
         const normalize = compileNormalizer(sub, { coerceTypes: true });
         const declaredRequired = Array.isArray(p.inputEffective.required) ? p.inputEffective.required : [];
         transport = {
           normalize,
           members: { path: pathMembers, query: queryMembers, header: headerMembers, repeated },
+          queryJson,
           schemas: pick,
           required: declaredRequired.filter((/** @type {unknown} */ r) => typeof r === 'string' && Object.hasOwn(pick, r)),
         };

package/src/http/dispatch.js

@@ -133,7 +133,7 @@ import {
  * @property {ReadonlySet<string>} nonBody - path/query/header member names, never taken from the body
  * @property {readonly string[]} pathMembers
  * @property {ReadonlySet<string>} queryMembers
- * @property {ReadonlySet<string>} repeated - array-typed query members
+ * @property {ReadonlySet<string>} queryJson - JSON-encoded query members
  * @property {readonly string[]} headerMembers - member names
  * @property {readonly string[]} headerNames - the lowercase header of each
  * @property {readonly boolean[]} headerArray - array-typed, per header member
@@ -597,7 +597,7 @@ function afterIdentity(server, request, route, trace, hit, isHead, method, path,
     const m = route.pathMembers[i];
     setObjectMember(input, m, params[m]);
   }
-  if (!decodeQuery(query, route.queryMembers, route.repeated, input)) {
+  if (!decodeQuery(query, route.queryMembers, input, route.queryJson)) {
     return refuse(server, 'JC2012', trace, {}, undefined, null, null);
   }
   /** @type {Record<string, string>} */

package/src/http/serve.js

@@ -158,8 +158,6 @@ function prepare(op, handler, tag) {
   const pathMembers = [];
   /** @type {Set<string>} */
   const queryMembers = new Set();
-  /** @type {Set<string>} */
-  const repeated = new Set();
   /** @type {string[]} */
   const headerMembers = [];
   /** @type {string[]} */
@@ -178,10 +176,6 @@ function prepare(op, handler, tag) {
       headerNames.push(headerNameOf(m));
       headerArray.push(transport.members.repeated.includes(m));
     }
-    for (let i = 0; i < transport.members.repeated.length; i++) {
-      const m = transport.members.repeated[i];
-      if (queryMembers.has(m)) repeated.add(m);
-    }
   }
   const members = Object.keys(http.in);
   for (let i = 0; i < members.length; i++) {
@@ -203,7 +197,7 @@ function prepare(op, handler, tag) {
     nonBody,
     pathMembers,
     queryMembers,
-    repeated,
+    queryJson: new Set(transport === null ? [] : transport.queryJson),
     headerMembers,
     headerNames,
     headerArray,

package/src/http/wire.js

@@ -340,18 +340,19 @@ export function formatEntityTag(tag, strong) {
 /**
  * Decode a query string into the declared members of an input object:
  * only declared names are set (an undeclared key is never merged, so no
- * request can smuggle a member); a `repeated` member collects every
- * occurrence into an array, every other member is last-wins; a `+` is a
+ * request can smuggle a member); JSON members decode exactly one value,
+ * scalar members are last-wins; a `+` is a
  * space and escapes decode as `application/x-www-form-urlencoded`
  * (`URLSearchParams`). Returns `false` when the query is not decodable
- * (a malformed percent-escape or invalid UTF-8) — the `JC2012` case.
+ * (malformed percent-escape, UTF-8 or JSON, or a repeated JSON member)
+ * — the `JC2012` case.
  * @param {string} query - the part after `?`, possibly empty
  * @param {ReadonlySet<string>} declared - the query member names
- * @param {ReadonlySet<string>} repeated - the array-typed ones
  * @param {Record<string, unknown>} out - the input object under assembly
+ * @param {ReadonlySet<string>} json - schema-directed JSON members
  * @returns {boolean} false when not decodable
  */
-export function decodeQuery(query, declared, repeated, out) {
+export function decodeQuery(query, declared, out, json) {
   if (query.length === 0) return true;
   // URLSearchParams never throws: it keeps a malformed escape as its
   // literal text and replaces invalid UTF-8; both are "not decodable"
@@ -368,12 +369,16 @@ export function decodeQuery(query, declared, repeated, out) {
   const params = new URLSearchParams(query);
   for (const [name, value] of params) {
     if (!declared.has(name)) continue;
-    if (repeated.has(name)) {
-      const list = out[name];
-      if (Array.isArray(list)) list.push(value);
-      else setObjectMember(out, name, [value]);
+    if (json.has(name)) {
+      // One JSON value per declared structured member. Scalar strings
+      // are untouched; repeated JSON members are ambiguous and refused.
+      const values = params.getAll(name);
+      if (values.length !== 1) return false;
+      try { setObjectMember(out, name, JSON.parse(value)); }
+      catch { return false; }
+      continue;
     }
-    else setObjectMember(out, name, value);
+    setObjectMember(out, name, value);
   }
   return true;
 }

package/src/project/openapi.js

@@ -324,7 +324,7 @@ function docLines(doc) {
 function operationView(op, projected, ctx) {
   const base = at('/operations', op.id);
   const http = op.http;
-  /** @type {{ name: string, in: string, required: boolean, schema: any }[]} */
+  /** @type {any[]} */
   const parameters = [];
   /** @type {Record<string, any>} */
   const bodyMembers = {};
@@ -351,6 +351,8 @@ function operationView(op, projected, ctx) {
       bodyCount++;
       if (name === http.body) bodyMemberRequired = required;
     }
+    else if (loc === 'query' && op.input?.transport?.queryJson.includes(name))
+      parameters.push({ name, in: loc, required, content: { 'application/json': { schema: mapped } } });
     else parameters.push({ name, in: loc, required, schema: mapped });
   }
   if (op.policy.idempotency !== 'none') {