@jarenjs/contract 0.73.0 → 0.83.2

package/src/client/http.js

@@ -26,6 +26,7 @@
  * Everything per operation is decided once at `open`.
  */
 
+import { backoffDelay as sharedBackoff, sleep as defaultSleep } from '@jarenjs/core/retry';
 import { isJsonObject, setObjectMember } from '@jarenjs/core/object';
 import { compileMessageCatalog } from '@jarenjs/core/message';
 import { canonicalSha256 } from '@jarenjs/json/canonical';
@@ -199,9 +200,6 @@ const storageUpdates = new WeakMap();
 /** The backoff ceiling of a retry, in ms. */
 const BACKOFF_MAX = 8000;
 
-/** The jitter added to a backoff, in ms (upper bound, exclusive). */
-const BACKOFF_JITTER = 250;
-
 /**
  * @param {string} code
  * @param {string} reason
@@ -211,42 +209,6 @@ function host(code, reason) {
   return new ContractHostError(code, `openHttpClient: ${reason}`);
 }
 
-/**
- * An `AbortError`-named error, the platform's when a signal carries one.
- * @param {AbortSignal | null} signal
- * @returns {unknown}
- */
-function abortReason(signal) {
-  if (signal !== null && signal.reason !== undefined) return signal.reason;
-  const err = new Error('The operation was aborted.');
-  err.name = 'AbortError';
-  return err;
-}
-
-/**
- * Abortable delay; rejects with the abort reason.
- * @param {number} ms
- * @param {AbortSignal} [signal]
- * @returns {Promise<void>}
- */
-function defaultSleep(ms, signal) {
-  return new Promise((resolve, reject) => {
-    if (signal !== undefined && signal.aborted) {
-      reject(abortReason(signal));
-      return;
-    }
-    const onAbort = () => {
-      clearTimeout(timer);
-      reject(abortReason(signal ?? null));
-    };
-    const timer = setTimeout(() => {
-      if (signal !== undefined) signal.removeEventListener('abort', onAbort);
-      resolve();
-    }, ms);
-    if (signal !== undefined) signal.addEventListener('abort', onAbort, { once: true });
-  });
-}
-
 /**
  * A rejection value's `name`, read guardedly; `null` when it has none.
  * @param {unknown} err
@@ -289,7 +251,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 +277,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 +284,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 +303,7 @@ function prepare(op) {
     method: http.method,
     segments: http.template.segments,
     queryMembers,
-    queryRepeated,
+    queryJson: new Set(transport === null ? [] : transport.queryJson),
     headerMembers,
     headerNames,
     bodyMembers,
@@ -448,7 +406,8 @@ export function openHttpClient(contract, options = {}) {
    * @returns {number}
    */
   function backoffDelay(n) {
-    return Math.min(1000 * 2 ** n, BACKOFF_MAX) + Math.floor(hostFact('random', runtime.random) * BACKOFF_JITTER);
+    return sharedBackoff({ policy: 'contract-compat', baseMs: 1000, maxMs: BACKOFF_MAX,
+      random: () => hostFact('random', runtime.random) }, n + 1);
   }
   const now = options.now === undefined ? runtime.now : options.now;
   /** @type {Catalog | null} */
@@ -535,13 +494,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/command.js

@@ -0,0 +1,70 @@
+//@ts-check
+/** Opt-in business settlement shared by handlers on every invocation carrier. */
+import { deepFreeze } from '@jarenjs/core/object';
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { ContractFailure, ContractHostError, ContractRuntimeError } from './errors.js';
+import { runOperation, validateOperationInput } from './pipeline.js';
+
+/**
+ * Compile once around the existing neutral operation pipeline. Identity and
+ * current authorization are application policy, never inferred from a receipt.
+ * Handlers receive the repository's transaction as ctx.host; current-state reads
+ * belong to a separate read operation. Transport TTL policy remains independent.
+ * @param {import('./compile.js').CompiledOperation} operation
+ * @param {{ repository: { execute: Function }, identity: (input: any, context: any) => any,
+ * authorize: (input: any, context: any) => any, handler: (input: any, context: any) => any,
+ * commitFailures?: string[], references?: (result: any, context: any) => any[],
+ * refuse?: (reason: string, context: any) => any }} options
+ */
+export function createCommand(operation, options) {
+  if (!operation || operation.kind !== 'command' || operation.http.opaque || operation.policy.idempotency !== 'none' || typeof options?.repository?.execute !== 'function'
+    || ['identity', 'authorize', 'handler'].some((name) => typeof options[name] !== 'function'))
+    throw new ContractHostError('JC1013', 'command settlement needs a JSON command, receipt repository, identity, authorization and handler');
+  const failures = new Set(options.commitFailures ?? []);
+  if ([...failures].some((code) => !Object.hasOwn(operation.errors, code))) throw new ContractHostError('JC1013', 'committed failure codes must be declared');
+  const route = { op: operation, handler: options.handler, raw: false, validateInput: operation.input?.validate ?? null,
+    validateOutput: operation.output.validate, details: operation.policy.errors.details, errors: operation.errors,
+    retryOn: new Set(operation.policy.retry?.on ?? []) };
+  const refused = (reason) => ({ state: 'refused', reason, historic: false });
+  /** @param {any} input @param {any} [context] */
+  async function execute(input, context = {}) {
+    // Freeze before asynchronous authority checks so callers cannot change the
+    // authorized request or the request whose hash the application computes.
+    const value = deepFreeze(JSON.parse(canonicalizeJson(input ?? null)));
+    if (await options.authorize(value, context) !== true) return refused('unauthorized');
+    if (validateOperationInput(route, value) !== null) throw new ContractRuntimeError('JC2110', 'command input failed validation', { msgid: 'contract/command-failed' });
+    const identity = options.identity(value, context);
+    if (identity?.op !== operation.id) throw new ContractHostError('JC1013', 'identity operation must match the compiled command');
+    try {
+      return await options.repository.execute(identity, async (tx) => {
+        if (context.signal?.aborted) throw refused('cancelled');
+        const hostContext = Object.freeze({ ...context, host: tx, fail: ContractFailure });
+        const result = await runOperation(route, value, hostContext);
+        if (result.kind === 'contract') throw new ContractRuntimeError('JC2110', 'command validation or handler failed', { msgid: 'contract/command-failed', cause: result.cause });
+        if (result.kind === 'failure' && !failures.has(result.code)) throw { state: 'uncommitted', historic: false, outcome: result };
+        if (context.signal?.aborted) throw refused('cancelled');
+        // Canonicalization rejects non-JSON values before any transaction commits.
+        const outcome = JSON.parse(canonicalizeJson(result.kind === 'failure' ? { ...result, details: result.details ?? null } : result));
+        return { outcome, references: options.references?.(outcome, hostContext) ?? [] };
+      }, context.lease === undefined ? {} : { lease: context.lease });
+    }
+    catch (error) {
+      if (error?.state === 'uncommitted' || error?.state === 'refused') return error;
+      throw error;
+    }
+  }
+  return Object.freeze({
+    execute,
+    /** A deliberate carrier wrapper around the one settlement implementation.
+     * @param {any} input @param {any} context */
+    async handler(input, context) {
+      const settled = await execute(input, context);
+      if (settled.state === 'refused') {
+        if (options.refuse) return options.refuse(settled.reason, context);
+        throw new ContractRuntimeError('JC2110', 'command refused', { msgid: 'contract/command-failed' });
+      }
+      const outcome = settled.receipt?.outcome ?? settled.outcome;
+      return outcome.kind === 'failure' ? ContractFailure(outcome.code, outcome.params, outcome.details, { retryable: outcome.retryable }) : outcome.value;
+    },
+  });
+}

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/errors.js

@@ -52,6 +52,7 @@ export const CONTRACT_CODES = Object.freeze({
   JC0018: 'a subscribe operation declares a policy.task other than switch — a subscription slot is replaced, never queued',
   JC0019: 'a subscribe operation is bound to a method other than GET — a stream is fetched, not sent',
   JC0020: 'a subscribe operation declares a policy.idempotency other than none — a subscription registers, it does not commit',
+  JC0021: 'a provider protocol descriptor is malformed or names an undeclared transform capability',
   // ——— projection compile (ContractCompileError, docPath into the contract document) ———
   JC0060: 'the OpenAPI projection met a schema keyword it cannot map honestly: a boolean required (draft-04 style) or a same-document $ref that lands outside $defs (both dropped and reported under lenient), or a components member inside a schema',
   JC0061: 'the public projection is not canonicalizable, so no revision exists — a string with an unpaired surrogate, say; docPath points at the offending value inside the projection',
@@ -67,6 +68,8 @@ export const CONTRACT_CODES = Object.freeze({
   JC1009: 'encodeSseEvent (the stream wire): an event, id or data string the SSE frame cannot carry — a bare carriage return inside data, a line terminator inside event or id',
   JC1010: 'client.subscribe was asked for an operation that is not a subscribe operation (invoke carries reads and commands; subscribe carries streams)',
   JC1011: 'a ledger commit or fail named a ref that settles no started record: the key expired, was reclaimed under a newer generation, or was settled already — the settlement is refused; the binding reports it to onError and the response still goes out',
+  JC1012: 'a provider executor, descriptor host or run capability is malformed',
+  JC1013: 'a durable command settlement capability is malformed',
   // ——— http request-time (ContractRuntimeError, mapped onto the wire) ———
   JC2001: 'no operation matches the request method and path (404)',
   JC2002: 'the path shape is served under other methods (405, Allow lists them)',
@@ -108,6 +111,7 @@ export const CONTRACT_CODES = Object.freeze({
   JC2095: 'a requested resume was refused — informational, carried as resumed:false in the fresh snapshot\'s event data, never an outcome',
   JC2096: 'the stream\'s bounded queue would overflow — the consumer reads slower than the source emits, or a replay page outran it (kind network, retryable; the stream ends with an error event carrying this code and the carrier tears the connection down)',
   JC2097: 'the client\'s reconnect budget is exhausted: every attempt after a network loss failed the same way (kind network, not retryable; details carry the attempts made and the last network code, client-side)',
+  JC2110: 'a durable command was refused or failed validation',
 });
 
 /**

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') {

package/src/provider/compile.js

@@ -0,0 +1,200 @@
+//@ts-check
+/** Compile JSON protocol declarations to bounded pull-based page execution. */
+import { deepFreeze, isJsonObject } from '@jarenjs/core/object';
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { compileJsonQuery } from '@jarenjs/json/query';
+import { compileJsltStylesheet } from '@jarenjs/json/jslt';
+import { ContractCompileError } from '../errors.js';
+import { providerHostError } from './execute.js';
+
+const clone = (value) => JSON.parse(canonicalizeJson(value));
+const fail = (reason, path = '') => { throw new ContractCompileError('JC0021', reason, path); };
+
+/**
+ * Compile selectors/transforms once using the existing Query/JSLT engines.
+ * Named callbacks receive cloned protocol data only, never the run host.
+ * These are trusted host functions, not a sandbox for arbitrary JavaScript.
+ * @param {any} document
+ * @param {{ callbacks?: Record<string, (value: any) => any>, compileSchema?: (schema: any) => (value: any) => boolean }} [options]
+ */
+export function compileProvider(document, options = {}) {
+  let doc;
+  try { doc = clone(document); }
+  catch { fail('provider descriptor must be JSON'); }
+  if (!isJsonObject(doc) || doc.$provider !== '0.1') fail('provider descriptor requires $provider:0.1');
+  const known = ['id', '$provider', 'apiVersion', 'endpoint', 'protocol', 'method', 'safety', 'headers', 'query', 'body', 'graphql', 'response', 'pagination', 'limits', 'capability', 'inputSchema'];
+  for (const key of Object.keys(doc)) if (!known.includes(key)) fail('unknown provider member', `/${key}`);
+  for (const name of ['id', 'apiVersion', 'endpoint']) if (typeof doc[name] !== 'string' || !doc[name]) fail(`${name} must be nonempty`, `/${name}`);
+  let endpoint;
+  try { endpoint = new URL(doc.endpoint); }
+  catch { fail('endpoint must be an absolute HTTP(S) URL', '/endpoint'); }
+  if (!['http:', 'https:'].includes(endpoint.protocol) || endpoint.username || endpoint.password || endpoint.hash)
+    fail('endpoint must be HTTP(S), without embedded credentials or a fragment', '/endpoint');
+  if (!['rest', 'graphql'].includes(doc.protocol) || !['safe-read', 'provider-idempotent', 'single-send'].includes(doc.safety))
+    fail('protocol and replay safety must be declared');
+  if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'].includes(doc.method)) fail('unsupported HTTP method', '/method');
+  if (doc.headers !== undefined && (!isJsonObject(doc.headers) || Object.entries(doc.headers).some(([name, value]) =>
+    typeof value !== 'string' || /authorization|cookie|token|secret|api[-_]key/i.test(name) || /[\r\n]/.test(name + value))))
+    fail('headers must be public static strings; authentication belongs to host transport', '/headers');
+  if (doc.capability !== undefined && !['json', 'upload', 'media', 'bulk', 'binary'].includes(doc.capability)) fail('unknown capability', '/capability');
+  const limits = doc.limits ?? {};
+  if (!isJsonObject(limits)) fail('limits must be an object', '/limits');
+  for (const [name, fallback] of Object.entries({ pages: 3, rows: 256, bytes: 262144 })) {
+    if (limits[name] === undefined) limits[name] = fallback;
+    if (!Number.isSafeInteger(limits[name]) || limits[name] < 1) fail('limits must be positive finite integers', `/limits/${name}`);
+  }
+  if (Object.keys(limits).some((name) => !['pages', 'rows', 'bytes'].includes(name))) fail('unknown limit', '/limits');
+  const pagination = doc.pagination ?? {};
+  if (!isJsonObject(pagination) || Object.keys(pagination).some((name) => !['cursorParam', 'cursorVariable', 'empty'].includes(name))
+    || (pagination.empty !== undefined && !['complete', 'incomplete'].includes(pagination.empty))) fail('invalid pagination', '/pagination');
+  for (const name of ['cursorParam', 'cursorVariable']) if (pagination[name] !== undefined && (typeof pagination[name] !== 'string' || !pagination[name])) fail('cursor target must be nonempty', `/pagination/${name}`);
+  if (!isJsonObject(doc.response) || !Object.hasOwn(doc.response, 'rows') || !Object.hasOwn(doc.response, 'id')) fail('response needs rows and id selectors', '/response');
+  for (const key of Object.keys(doc.response)) if (!['rows', 'id', 'cursor', 'hasMore', 'errors', 'cost', 'version', 'transform', 'schema'].includes(key)) fail('unknown response member', `/response/${key}`);
+  const schema = (value, path) => {
+    if (value === undefined) return () => true;
+    if (typeof options.compileSchema !== 'function') fail('schema validation requires a declared compiler capability', path);
+    try {
+      const validate = options.compileSchema(value);
+      if (typeof validate !== 'function') fail('schema compiler must return a validator', path);
+      return validate;
+    }
+    catch { fail('schema could not be compiled', path); }
+  };
+  const validInput = schema(doc.inputSchema, '/inputSchema');
+  const validResponse = schema(doc.response.schema, '/response/schema');
+
+  const selector = (spec, path, fallback) => {
+    if (spec === undefined) return () => fallback;
+    try {
+      if (isJsonObject(spec) && Object.hasOwn(spec, 'callback')) {
+        if (Object.keys(spec).length !== 1 || typeof spec.callback !== 'string'
+          || !Object.hasOwn(options.callbacks ?? {}, spec.callback) || typeof options.callbacks[spec.callback] !== 'function') fail('undeclared callback', path);
+        const callback = options.callbacks[spec.callback];
+        return (data) => clone(callback(clone(data)));
+      }
+      return compileJsonQuery(spec);
+    }
+    catch (error) { if (error instanceof ContractCompileError) throw error; fail('invalid selector', path); }
+  };
+  const rowsOf = selector(doc.response.rows, '/response/rows', []);
+  const idOf = selector(doc.response.id, '/response/id', null);
+  const cursorOf = selector(doc.response.cursor, '/response/cursor', null);
+  const moreOf = selector(doc.response.hasMore, '/response/hasMore', undefined);
+  const errorsOf = selector(doc.response.errors ?? (doc.protocol === 'graphql' ? '$.errors' : undefined), '/response/errors', null);
+  const costOf = selector(doc.response.cost, '/response/cost', null);
+  const versionOf = selector(doc.response.version, '/response/version', null);
+  const queryOf = selector(doc.query, '/query', {});
+  const bodyOf = selector(doc.body, '/body', undefined);
+  let transform = (row) => row;
+  if (doc.response.transform !== undefined) {
+    const spec = doc.response.transform;
+    if (spec?.kind === 'jslt') {
+      try { transform = compileJsltStylesheet(spec.expression); }
+      catch { fail('invalid JSLT transform', '/response/transform'); }
+    }
+    else if (spec?.kind === 'query') transform = selector(spec.expression, '/response/transform', null);
+    else if (spec?.callback) transform = selector(spec, '/response/transform', null);
+    else fail('transform must name query, jslt or a declared callback', '/response/transform');
+  }
+  let variablesOf;
+  if (doc.protocol === 'graphql') {
+    if (doc.method !== 'POST' || !isJsonObject(doc.graphql) || typeof doc.graphql.query !== 'string' || !doc.graphql.query.trim()
+      || Object.keys(doc.graphql).some((name) => !['query', 'variables'].includes(name))) fail('GraphQL requires POST and a query with optional variables', '/graphql');
+    variablesOf = selector(doc.graphql.variables, '/graphql/variables', {});
+  }
+  else if (doc.graphql !== undefined) fail('graphql belongs to the GraphQL dialect', '/graphql');
+  if (['GET', 'HEAD'].includes(doc.method) && doc.body !== undefined) fail('GET/HEAD cannot carry a body', '/body');
+  deepFreeze(doc);
+
+  /** @param {any} input @param {any} context */
+  async function* pages(input, context) {
+    if (!context || typeof context.executor?.execute !== 'function') throw providerHostError('provider pages require an executor');
+    let pageCount = 0, rowCount = 0, byteCount = 0, attempts = 0;
+    let cursor = context.cursor ?? null;
+    const cursors = new Set(cursor === null ? [] : [canonicalizeJson(cursor)]);
+    const ids = new Set();
+    const end = (state, reason) => ({ state, reason, pages: pageCount, rows: rowCount, bytes: byteCount, attempts, cursor });
+    if (doc.capability && doc.capability !== 'json') { yield end('refused', 'unsupported-capability'); return; }
+    if (!validInput(input)) { yield end('refused', 'input-schema'); return; }
+    for (;;) {
+      if (context.signal?.aborted) { yield end('incomplete', 'cancelled'); return; }
+      if (pageCount >= limits.pages) { yield end('incomplete', 'page-limit'); return; }
+      const data = { input: clone(input), cursor, apiVersion: doc.apiVersion, partition: context.partition ?? null, sourceVersion: context.sourceVersion ?? null };
+      let request;
+      try {
+        const url = new URL(doc.endpoint);
+        const query = queryOf(data);
+        if (!isJsonObject(query)) throw new Error('query must return an object');
+        for (const [name, value] of Object.entries(query)) {
+          if (value !== null && !['string', 'number', 'boolean'].includes(typeof value)) throw new Error('query values must be scalar');
+          if (value !== null) url.searchParams.set(name, String(value));
+        }
+        if (cursor !== null && pagination.cursorParam) url.searchParams.set(pagination.cursorParam, String(cursor));
+        let body = bodyOf(data);
+        if (doc.protocol === 'graphql') {
+          const variables = clone(variablesOf(data));
+          if (!isJsonObject(variables)) throw new Error('variables must be an object');
+          if (pagination.cursorVariable) Object.defineProperty(variables, pagination.cursorVariable, { value: cursor, enumerable: true, configurable: true, writable: true });
+          body = { query: doc.graphql.query, variables };
+        }
+        request = { url: url.href, method: doc.method, headers: { ...doc.headers, ...(body === undefined ? {} : { 'content-type': 'application/json' }) },
+          ...(body === undefined ? {} : { body: canonicalizeJson(body) }), safety: doc.safety,
+          account: context.account, idempotencyKey: context.idempotencyKey };
+      }
+      catch { yield end('refused', 'request-transform'); return; }
+      const response = await context.executor.execute(request, { ...context, maxBytes: limits.bytes - byteCount });
+      attempts += response.attempts;
+      byteCount += response.bytes;
+      if (response.state !== 'ok') { yield { ...end(response.state === 'refused' && response.reason !== 'byte-limit' ? 'refused' : 'incomplete', response.reason), response }; return; }
+      if (byteCount > limits.bytes) { yield end('incomplete', 'byte-limit'); return; }
+      let raw, rows, rowIds, next, hasMore, errors, cost, version;
+      try {
+        raw = JSON.parse(response.text);
+        if (!validResponse(raw)) throw new Error('response schema failed');
+        rows = rowsOf(raw);
+        if (!Array.isArray(rows)) throw new Error('rows must be an array');
+        rowIds = rows.map((row) => idOf(row));
+        if (rowIds.some((id) => (typeof id !== 'string' || !id) && (typeof id !== 'number' || !Number.isSafeInteger(id)))) throw new Error('ids must be nonempty strings or safe integers');
+        rows = rows.map((row) => clone(transform(clone(row))));
+        next = cursorOf(raw) ?? null;
+        if (next !== null && !['string', 'number'].includes(typeof next)) throw new Error('cursor must be a scalar');
+        hasMore = moreOf(raw);
+        if (hasMore !== undefined && typeof hasMore !== 'boolean') throw new Error('hasMore must be boolean');
+        hasMore ??= next !== null;
+        errors = errorsOf(raw) ?? null;
+        cost = costOf(raw) ?? null;
+        version = versionOf(raw) ?? null;
+      }
+      catch { yield { ...end('incomplete', 'response-transform'), text: response.text }; return; }
+      pageCount++;
+      rowCount += rows.length;
+      let reason = null;
+      if (errors !== null && (!Array.isArray(errors) || errors.length)) reason = 'partial-errors';
+      else if (rowCount > limits.rows) reason = 'row-limit';
+      else if (!rows.length && (hasMore || pagination.empty !== 'complete')) reason = 'empty-page';
+      else if (rowIds.some((id) => ids.has(canonicalizeJson(id))) || new Set(rowIds.map((id) => canonicalizeJson(id))).size !== rowIds.length) reason = 'no-progress';
+      else if (hasMore && (next === null || cursors.has(canonicalizeJson(next)))) reason = 'no-progress';
+      const complete = reason === null && !hasMore;
+      yield { state: 'page', raw, text: response.text, rows, ids: rowIds, cursor, continuation: hasMore ? next : null,
+        complete, errors, cost, version, reason, bytes: response.bytes, attempts: response.attempts };
+      if (reason !== null) { yield end('incomplete', reason); return; }
+      if (complete) { yield end('complete', 'complete'); return; }
+      for (const id of rowIds) ids.add(canonicalizeJson(id));
+      cursors.add(canonicalizeJson(next));
+      cursor = next;
+    }
+  }
+  return Object.freeze({
+    document: doc,
+    pages,
+    /** Collect a bounded pull; streaming consumers should iterate pages instead.
+     * @param {any} input @param {any} context @returns {Promise<any>} */
+    async pull(input, context) {
+      const observations = [];
+      for await (const page of pages(input, context)) {
+        if (page.state === 'page') observations.push(page);
+        else return { ...page, observations };
+      }
+    },
+  });
+}