@jarenjs/contract 0.75.0 → 0.83.2

package/src/app/index.js

@@ -12,7 +12,7 @@
 
 export { contractAppBinding } from './binding.js';
 export { createContractEffect } from './effect.js';
-export { createContractSubscription } from './subscription.js';
+export { createContractSubscription, createRunPageHandler } from './subscription.js';
 
 /**
  * @typedef {import('./binding.js').ContractAppBinding} ContractAppBinding

package/src/app/subscription.js

@@ -21,6 +21,8 @@
  * slot must say so, so a view can offer a reconnect (a new `start`).
  */
 
+import { deepFreeze } from '@jarenjs/core/object';
+import { canonicalizeJson } from '@jarenjs/json/canonical';
 import { compileJSONPatch } from '@jarenjs/json/patch';
 
 import { ContractHostError } from '../errors.js';
@@ -136,3 +138,22 @@ export function createContractSubscription(client, options = {}) {
 // re-exported so a host settling its own outcomes beside the handler
 // needs no second import path
 export { CLIENT_ERRORS };
+
+/**
+ * Authorize each bounded run-page read before touching durable history. Register
+ * as an ordinary read handler; callers may poll or resume from their last cursor.
+ * @param {{ page: (id: string, options: any) => any, authorize: (input: any, context: any) => any, maxPage?: number }} options
+ */
+export function createRunPageHandler(options) {
+  const maxPage = options?.maxPage ?? 128;
+  if (typeof options?.page !== 'function' || typeof options.authorize !== 'function' || !Number.isSafeInteger(maxPage) || maxPage < 1)
+    throw new ContractHostError('JC1008', 'run pages need page/authorize capabilities and a finite limit');
+  return async (input, context) => {
+    input = deepFreeze(JSON.parse(canonicalizeJson(input)));
+    if (await options.authorize(input, context) !== true) throw new ContractHostError('JC1008', 'run observation refused');
+    if (typeof input?.id !== 'string' || !input.id || !Number.isSafeInteger(input.after) || input.after < 0
+      || !Number.isSafeInteger(input.limit) || input.limit < 1 || input.limit > maxPage)
+      throw new ContractHostError('JC1008', 'run observation needs id, revision cursor and bounded limit');
+    return options.page(input.id, { after: input.after, limit: input.limit });
+  };
+}

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
@@ -444,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} */

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/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/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 };
+      }
+    },
+  });
+}

package/src/provider/execute.js

@@ -0,0 +1,191 @@
+//@ts-check
+/** One bounded, single-attempt transport seam with explicit replay safety. */
+import { createScheduler } from '@jarenjs/core/schedule';
+import { backoffDelay, createAttemptBudget, parseRetryAfter, sleep as defaultSleep } from '@jarenjs/core/retry';
+import { ContractHostError } from '../errors.js';
+
+/** @param {string} reason @returns {ContractHostError} */
+export const providerHostError = (reason) => new ContractHostError('JC1012', reason);
+
+/**
+ * @typedef {Object} ProviderRequest
+ * @property {string} url
+ * @property {string} [method]
+ * @property {Record<string, string>} [headers] - public headers only; credentials belong to host transport
+ * @property {string} [body]
+ * @property {'safe-read' | 'provider-idempotent' | 'single-send'} safety
+ * @property {string} [idempotencyKey] - required evidence for provider-idempotent
+ * @property {string} [account] - opaque scheduler scope, never credentials
+ */
+
+/**
+ * @typedef {Object} ProviderExecutorOptions
+ * @property {(request: ProviderRequest, context: { signal: AbortSignal, attempt: number, maxAttempts: 1 }) => Promise<Response>} [transport]
+ * @property {number} [attempts]
+ * @property {number} [overallMs]
+ * @property {number} [attemptMs]
+ * @property {number} [maxBytes] - response bytes across all attempts
+ * @property {number} [maxRequestBytes]
+ * @property {number} [baseMs]
+ * @property {number} [maxMs]
+ * @property {'http' | 'milliseconds' | 'none'} [retryAfter]
+ * @property {string} [retryAfterHeader]
+ * @property {number} [concurrency]
+ * @property {number} [maxQueue]
+ * @property {number} [maxScopes]
+ * @property {number} [spacingMs]
+ * @property {() => number} [now]
+ * @property {() => number} [random]
+ * @property {(ms: number, signal?: AbortSignal) => Promise<void>} [sleep]
+ */
+
+/**
+ * Injected transports must issue exactly one request and honor the supplied
+ * signal; SDK retry loops must be disabled. Shutdown awaits transport and body
+ * settlement even when a transport ignores its signal. JSON outcomes never
+ * contain exceptions, request headers, controllers or live response handles.
+ * @param {ProviderExecutorOptions} [options]
+ */
+export function createProviderExecutor(options = {}) {
+  const { attempts = 3, overallMs = 30000, attemptMs = 10000, maxBytes = 262144,
+    maxRequestBytes = 262144, baseMs = 500, maxMs = 8000, now = Date.now,
+    random = Math.random, sleep = defaultSleep, retryAfter = 'http', retryAfterHeader = 'retry-after' } = options;
+  for (const [key, value] of Object.entries({ attempts, overallMs, attemptMs, maxBytes, maxRequestBytes })) {
+    if (!Number.isSafeInteger(value) || value < 1) throw providerHostError(`${key} must be a positive finite integer`);
+  }
+  if (![baseMs, maxMs].every((value) => Number.isFinite(value) && value >= 0)
+    || typeof now !== 'function' || typeof random !== 'function' || typeof sleep !== 'function'
+    || !['http', 'milliseconds', 'none'].includes(retryAfter) || typeof retryAfterHeader !== 'string')
+    throw providerHostError('invalid retry policy');
+  const transport = options.transport ?? ((request, context) => fetch(request.url, {
+    method: request.method, headers: request.headers, body: request.body, signal: context.signal, redirect: 'manual',
+  }));
+  if (typeof transport !== 'function') throw providerHostError('transport must be a single-attempt function');
+  const scheduler = createScheduler({ ...options, now, sleep });
+  const closer = new AbortController();
+  /** @type {Set<Promise<any>>} */
+  const running = new Set();
+  const encoder = new TextEncoder();
+
+  /** @param {ProviderRequest} request @param {any} context */
+  async function execute(request, context) {
+    if (!request || !['safe-read', 'provider-idempotent', 'single-send'].includes(request.safety))
+      throw providerHostError('request must declare replay safety');
+    if (request.safety === 'provider-idempotent' && (typeof request.idempotencyKey !== 'string' || !request.idempotencyKey))
+      throw providerHostError('provider-idempotent requires the provider key');
+    let url;
+    try { url = new URL(request.url); }
+    catch { throw providerHostError('request URL must be absolute HTTP(S)'); }
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password)
+      throw providerHostError('request URL must be absolute HTTP(S) without credentials');
+    if (request.body !== undefined && typeof request.body !== 'string') throw providerHostError('only bounded text requests are supported');
+    const budget = context.budget ?? createAttemptBudget(attempts, request.safety);
+    if (budget.safety !== request.safety || typeof budget.take !== 'function') throw providerHostError('attempt budget safety must match the request');
+    const signal = AbortSignal.any([closer.signal, ...(context.signal ? [context.signal] : [])]);
+    if (context.deadline !== undefined && (typeof context.deadline !== 'number' || Number.isNaN(context.deadline)))
+      throw providerHostError('deadline must be a numeric instant');
+    const deadline = Math.min(now() + overallMs, context.deadline ?? Infinity);
+    const byteLimit = Math.min(maxBytes, context.maxBytes ?? maxBytes);
+    if (!Number.isSafeInteger(byteLimit) || byteLimit < 0) throw providerHostError('per-request byte credit must be a nonnegative finite integer');
+    const scope = JSON.stringify([url.origin, request.account ?? '']);
+    let count = 0;
+    let bytes = 0;
+    /** @param {string} state @param {string} reason @param {any} [extra] */
+    const outcome = (state, reason, extra = {}) => ({ state, reason, attempts: count, bytes, ...extra });
+    if (request.safety === 'provider-idempotent' && options.transport === undefined)
+      return outcome('refused', 'idempotency-transport-required');
+    if (encoder.encode(request.body ?? '').byteLength > maxRequestBytes) return outcome('refused', 'request-byte-limit');
+    for (;;) {
+      if (signal.aborted) return outcome('cancelled', 'cancelled');
+      if (now() >= deadline) return outcome('refused', 'deadline');
+      let result;
+      try {
+        result = await scheduler.run(async () => {
+          const controller = new AbortController();
+          const attemptSignal = AbortSignal.any([signal, controller.signal]);
+          const timerStop = new AbortController();
+          const until = Math.min(deadline, now() + attemptMs);
+          const timer = sleep(Math.max(0, until - now()), timerStop.signal).then(() => controller.abort(), () => {});
+          try {
+            if (context.beforeDispatch && await context.beforeDispatch(request) !== true) return outcome('refused', 'authority-changed');
+            if (attemptSignal.aborted || now() >= until) return outcome(signal.aborted ? 'cancelled' : 'refused', signal.aborted ? 'cancelled' : 'deadline');
+            if (count >= attempts || !budget.take()) return outcome('refused', 'attempt-budget');
+            count++;
+            let response;
+            try { response = await transport(request, { signal: attemptSignal, attempt: budget.used, maxAttempts: 1 }); }
+            catch { return outcome(request.safety === 'single-send' ? 'unresolved' : 'failed', 'transport', { retryable: true }); }
+            if (!response || typeof response.status !== 'number' || typeof response.headers?.get !== 'function')
+              return outcome('failed', 'transport-shape');
+            const rate = parseRetryAfter(response.headers.get(retryAfterHeader), { dialect: retryAfter, now: now() });
+            if (rate !== undefined) scheduler.observe(scope, rate);
+            const reader = response.body?.getReader();
+            let text = '';
+            let readFailure = false;
+            if (reader) {
+              const cancel = () => { reader.cancel().catch(() => {}); };
+              attemptSignal.addEventListener('abort', cancel, { once: true });
+              const decoder = new TextDecoder('utf-8', { fatal: true });
+              try {
+                for (;;) {
+                  if (attemptSignal.aborted) { await reader.cancel(); break; }
+                  const part = await reader.read();
+                  if (part.done) { text += decoder.decode(); break; }
+                  bytes += part.value.byteLength;
+                  if (bytes > byteLimit) { await reader.cancel(); return outcome('refused', 'byte-limit'); }
+                  text += decoder.decode(part.value, { stream: true });
+                }
+              }
+              catch { readFailure = true; await reader.cancel().catch(() => {}); }
+              finally { attemptSignal.removeEventListener('abort', cancel); reader.releaseLock(); }
+            }
+            if (signal.aborted) return outcome('cancelled', 'cancelled');
+            if (attemptSignal.aborted || now() >= until)
+              return outcome(request.safety === 'single-send' ? 'unresolved' : 'failed', 'deadline', { retryable: true });
+            if (readFailure) return outcome(request.safety === 'single-send' ? 'unresolved' : 'failed', 'body', { retryable: true });
+            const status = response.status;
+            const ok = status >= 200 && status < 300;
+            return outcome(ok ? 'ok' : 'failed', ok ? 'response' : 'http', {
+              status, text, retryAfterMs: rate ?? null,
+              retryable: status === 408 || status === 429 || status >= 500,
+            });
+          }
+          finally { timerStop.abort(); await timer; }
+        }, { scope, deadline, signal });
+      }
+      catch (error) {
+        const message = error instanceof Error ? error.message : '';
+        const reason = ['closed', 'cancelled', 'deadline', 'queue-full', 'scope-limit'].includes(message) ? message : 'host-fault';
+        return outcome(signal.aborted ? 'cancelled' : 'refused', signal.aborted ? 'cancelled' : reason);
+      }
+      if (signal.aborted) return outcome('cancelled', 'cancelled');
+      if (!result.retryable || request.safety === 'single-send' || !budget.remaining || count >= attempts) return result;
+      const delay = backoffDelay({ baseMs, maxMs, random }, count, result.retryAfterMs ?? undefined);
+      if (delay >= deadline - now()) return outcome('refused', 'deadline', { retryAfterMs: result.retryAfterMs ?? null });
+      try { await sleep(delay, signal); }
+      catch { return outcome('cancelled', 'cancelled'); }
+    }
+  }
+
+  return Object.freeze({
+    /** @param {ProviderRequest} request
+     * @param {{ signal?: AbortSignal, deadline?: number, maxBytes?: number, budget?: ReturnType<typeof createAttemptBudget>, beforeDispatch?: (request: ProviderRequest) => boolean | Promise<boolean> }} [context]
+     * @returns {Promise<any>} */
+    execute(request, context = {}) {
+      // Admission and dispatch use one immutable request, even if its caller
+      // changes the original object while queued or refreshing authority.
+      const captured = request && Object.freeze({ ...request,
+        ...(request.headers === undefined ? {} : { headers: Object.freeze({ ...request.headers }) }) });
+      const promise = execute(captured, context);
+      running.add(promise);
+      promise.then(() => running.delete(promise), () => running.delete(promise));
+      return promise;
+    },
+    /** Stop new work and drain requests, body readers and retry waits. */
+    async close() {
+      closer.abort();
+      await scheduler.close();
+      await Promise.allSettled([...running]);
+    },
+    stats: scheduler.stats,
+  });
+}

package/src/provider/index.js

@@ -0,0 +1,5 @@
+//@ts-check
+/** Bounded provider protocols with host-injected transport and authority. */
+export { createProviderExecutor } from './execute.js';
+export { compileProvider } from './compile.js';
+export { withProviderRun } from './run.js';