@relyio/sdk 0.15.0 → 0.17.0

package/dist/{index-DQ7eTUPQ.d.ts → index-BBp8_tn9.d.ts}

@@ -1,6 +1,5 @@
-import { c$ as paths, d0 as MergedRelyIOConfig, cS as ApiResponse, cR as RequestConfig, aM as EntryMetadata, cs as BaseContent, ap as Reading, al as CheckedIncludes, d1 as ReadWhere, cx as WhereClause, aq as ReadWith, cD as UpdateInput, at as UntypedReading, cB as RevisedContent, cA as CreateInput, cC as RestoredContent, cl as SDKError, cY as BaseValidationError, cX as ValidationViolation, b2 as AssetServedBlocks, d2 as CheckedInclude, d3 as components, cq as AssetFileBlock, ct as BaseSingleton, cu as BaseSettingsGroup, aN as InferContentType, an as ContentReading, aT as InferSingleton, cm as RelyIOConfig, b0 as InferAssetType, ak as AssetReading, as as SingletonReading, aY as InferSettingsGroup, ar as SettingsReading, cn as RelyIOConfigUpdate } from './define-content-type-Ds5rCAYl.js';
-import { a as SchemaDefinition, b as SchemaContentTypeNames, j as SchemaEntryOf, f as SchemaLocaleCodes, c as SchemaSingletonNames, A as AggregateBlock, K as QueryParameterValue, F as FullTextSearch, e as SchemaQueryNames, J as InferQueryParams, L as AnyQueryParameters, h as SchemaAssetTypeNames, g as SchemaSettingsGroupNames } from './define-schema-CxpIYFFR.js';
-import { VisitorResyncReason } from './live-visitor.js';
+import { d2 as paths, cW as RetryConfig, d3 as MergedRelyIOConfig, cV as ApiResponse, aM as EntryMetadata, ap as Reading, cs as BaseContent, al as CheckedIncludes, d4 as ReadWhere, cx as WhereClause, d5 as components, aq as ReadWith, cI as UpdateInput, at as UntypedReading, cC as RevisedContent, cA as CreateInput, cB as CreatedContent, cH as ContentVersionRow, cG as ContentVersion, cF as RestoredContent, cl as SDKError, c$ as BaseValidationError, c_ as ValidationViolation, b2 as AssetServedBlocks, d6 as CheckedInclude, cw as WhereFieldCondition, cq as AssetFileBlock, ct as BaseSingleton, cD as WrittenSingleton, cu as BaseSettingsGroup, cE as WrittenSettingsGroup, aN as InferContentType, an as ContentReading, aT as InferSingleton, cm as RelyIOConfig, b0 as InferAssetType, ak as AssetReading, as as SingletonReading, aY as InferSettingsGroup, ar as SettingsReading, cn as RelyIOConfigUpdate } from './define-content-type-BGoQxqLf.js';
+import { a as SchemaDefinition, b as SchemaContentTypeNames, j as SchemaEntryOf, f as SchemaLocaleCodes, c as SchemaSingletonNames, A as AggregateBlock, K as QueryParameterValue, F as FullTextSearch, e as SchemaQueryNames, J as InferQueryParams, L as AnyQueryParameters, h as SchemaAssetTypeNames, g as SchemaSettingsGroupNames } from './define-schema-DgCX9YB7.js';
 import { DevUnreadableReason } from './dev-handshake/index.js';
 
 /**
@@ -201,6 +200,81 @@ type ActiveSandbox = Extract<SandboxState, {
     state: 'active';
 }>;
 
+/**
+ * The part of a request a retry decision is allowed to look at.
+ *
+ * `method` is typed as a plain `string` rather than as `RequestConfig['method']`
+ * on purpose. The five verbs that union names are the five the typed transport
+ * can express today; the question "may this be sent twice?" is a fact about
+ * HTTP, and an unrecognised verb has to reach the conservative arm rather than
+ * be unrepresentable.
+ */
+interface RetryableRequest {
+    method: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Whether a failed request may be sent again, and after how long.
+ *
+ * The two halves are separate because they fail separately. The incumbent loop
+ * had neither: it asked `error.retryable` and nothing else, so a `POST` that met
+ * a 500 was sent again twice — and `SERVICE_INDETERMINATE`, whose whole meaning
+ * is "the service could not decide", is marked retryable, which means the write
+ * may already have landed. Meanwhile the `Retry-After` the service sent was
+ * collected by the transport and read by nobody, so a 429 whose window is
+ * measured in minutes was retried after an exponential guess capped at ten
+ * seconds.
+ *
+ * `error` is `Error`, not `SDKError`, because that is what the loop actually
+ * holds: a `TypeError: fetch failed` is only mapped to an `SDKError` **after**
+ * the loop gives up, so a policy typed to `SDKError` could not see the transport
+ * failures it most needs to retry.
+ */
+interface RetryPolicy {
+    /**
+     * Never replays a request that could apply twice: a write is retried only
+     * when it carries `Idempotency-Key`, or the verb is idempotent.
+     *
+     * @param attempt - How many attempts have been made, 1 for the first.
+     */
+    shouldRetry(attempt: number, error: Error, request: RetryableRequest): boolean;
+    /** Honours `Retry-After` / `RateLimitError.resetAt` over exponential backoff. */
+    delayFor(attempt: number, error: Error): number;
+}
+/**
+ * Whether sending this request a second time can apply it a second time.
+ *
+ * Two ways to be safe, and they are genuinely different questions: the verb may
+ * be idempotent by definition, or the request may carry an `Idempotency-Key`
+ * that makes the service answer a replay from the original outcome rather than
+ * applying it again.
+ */
+declare function isReplaySafe(request: RetryableRequest): boolean;
+/**
+ * The policy the SDK ships with.
+ *
+ * Construction takes the same `RetryConfig` the SDK has always exported; what
+ * it no longer takes is a `retryCondition`, because a caller-supplied predicate
+ * over `(error, attempt)` structurally **cannot** see the request and so cannot
+ * express the rule this class exists for.
+ */
+declare class DefaultRetryPolicy implements RetryPolicy {
+    private readonly config;
+    constructor(config: RetryConfig);
+    shouldRetry(attempt: number, error: Error, request: RetryableRequest): boolean;
+    delayFor(attempt: number, error: Error): number;
+}
+/**
+ * The retry policy a client sends with, at `maxAttempts` attempts (the first included): the SDK's
+ * own, from `retryAttempts`, and the CLI's (REL-721).
+ *
+ * The backoff numbers are stated here once. The CLI ran a second policy beside this one —
+ * `axios-retry` with its own delays and its own reading of a refusal, which retried by numeric
+ * status — so a refusal one client gave up on, the other sent again. Now both ask this function, and
+ * a change to when a request is replayed reaches both.
+ */
+declare function retryPolicyFor(maxAttempts: number): RetryPolicy;
+
 /**
  * What a call site supplies beside the route it named.
  *
@@ -234,39 +308,35 @@ type SendOptions<P extends ApiPath, M extends ApiMethod<P>> = {
  * then the one unwrap — there is no second spelling and no runtime test of
  * which envelope arrived (`INV-API-CLIENT-IS-DERIVED`).
  *
- * The verb helpers below stay for the escape hatch `getHttpClient()` exposes;
- * nothing inside the SDK uses them.
+ * What the class makes public is what something outside it calls: `send` and `fetchPayload` are
+ * the requests; `configure`, `withHeaders` and `setApiKey` are the owning client's (`updateConfig()`,
+ * `with()`, `setApiKey()`). There are no verb helpers, no header or base-URL accessors and no
+ * untyped `request` (REL-717): a route is named by its document path, or it is not called.
  */
 declare class HttpClient {
     /** What every request reads off the configuration, derived by {@link configure} and nowhere else. */
-    private connection;
+    protected connection: Connection;
     /**
      * Set on a view {@link withHeaders} made: the client every request is sent through, and the
      * headers laid beneath each request's own. A view keeps no connection of its own that matters —
      * everything it is asked to change, it changes on that client.
      */
-    private view?;
+    protected view?: {
+        readonly client: ControlledHttpClient;
+        readonly headers: Readonly<Record<string, string>>;
+    };
     constructor(config: MergedRelyIOConfig);
+    protected announce(): void;
     /**
-     * A view of this client that sends every request through it with `headers` added — beneath the
-     * request's own, over this client's — and changes nothing else: its key, base URL, timeout,
-     * retries and `fetch` are this client's as they are when each request is sent, so a later
-     * `configure()` or `setApiKey()` on this client reaches the view, and one on the view reaches
-     * this client. `client.with({ dataset })` is one (REL-2417).
-     */
-    withHeaders(headers: Readonly<Record<string, string>>): HttpClient;
-    /**
-     * Run on `config` from now on: every later request — whoever holds this client — is sent to its
-     * `baseUrl`, with its headers, key and dataset, its timeout and retries, through its `fetch`, and
-     * logged by its `debug` options.
+     * Send bytes to an address that is not a RelyIO route — an asset upload's presigned `PUT` and its
+     * multipart parts — through the client's configured `fetch`, so a wrapper that records, proxies or
+     * forbids network access sees every request this client makes (REL-2671). Nothing else is added: no
+     * key, no retry, no timeout, because the address belongs to the storage service, not to RelyIO.
      *
-     * The client's own `updateConfig()` calls this rather than building a second client, so a
-     * `content()` or other sub-client taken before the update sends through the update too. Anything
-     * set on this client since it was last configured — `setDefaultHeaders()`, `setBaseUrl()` — is
-     * replaced by what `config` says.
+     * Static so the instances a customer holds stay `send` and `fetchPayload` (REL-3107). The `fetch`
+     * is read per call, from the client a view sends through, like the requests are.
      */
-    configure(config: MergedRelyIOConfig): void;
-    private announce;
+    static transfer(client: HttpClient, url: string, init: RequestInit): Promise<Response>;
     /**
      * Call a route the committed document declares, and get back the body that
      * document says it serves.
@@ -301,62 +371,7 @@ declare class HttpClient {
      * build that holds no key (REL-1120) — and so does one whose `setApiKey` was
      * given none.
      */
-    request<T = unknown>(config: RequestConfig): Promise<ApiResponse<T>>;
-    /**
-     * Make a GET request
-     */
-    get<T = unknown>(url: string, params?: Record<string, unknown>): Promise<ApiResponse<T>>;
-    /**
-     * Make a POST request
-     */
-    post<T = unknown>(url: string, data?: unknown, params?: Record<string, unknown>): Promise<ApiResponse<T>>;
-    /**
-     * Make a PUT request
-     */
-    put<T = unknown>(url: string, data?: unknown, params?: Record<string, unknown>): Promise<ApiResponse<T>>;
-    /**
-     * Make a DELETE request
-     */
-    delete<T = unknown>(url: string, params?: Record<string, unknown>): Promise<ApiResponse<T>>;
-    /**
-     * Make a PATCH request
-     */
-    patch<T = unknown>(url: string, data?: unknown, params?: Record<string, unknown>): Promise<ApiResponse<T>>;
-    /**
-     * Add headers to every later request, each replacing any header of the same name — the name
-     * matched without regard to case — until the client is next configured.
-     */
-    setDefaultHeaders(headers: Record<string, string>): void;
-    /**
-     * Replace the key every later request sends as `X-API-Key`, and the `apiKey` the configuration
-     * reports.
-     *
-     * The key is read the way construction reads it (`presentKey`): an absent, empty or blank key is
-     * no key, so the header is dropped and the next request is refused with `MissingApiKeyError`
-     * before anything is sent. A key header of any other spelling — one given in `headers` — goes
-     * too, from the headers sent and from the headers the configuration reports, so the old key is
-     * never sent beside the new one.
-     *
-     * The configuration is the one the owning `TypedRelyIOClient` holds (it hands its own to the
-     * constructor), so its `getConfig().apiKey` — what a surface reads to decide a key's kind — is the
-     * key sent from here on.
-     *
-     * This replaced `setAuthToken`, which added `Authorization: Bearer` beside an `X-API-Key` it
-     * never touched: the API reads `X-API-Key` first, so the old key was the one used (REL-1385).
-     */
-    setApiKey(apiKey: string): void;
-    /**
-     * Get current default headers
-     */
-    getDefaultHeaders(): Record<string, string>;
-    /**
-     * Update base URL
-     */
-    setBaseUrl(baseUrl: string): void;
-    /**
-     * Get current base URL
-     */
-    getBaseUrl(): string;
+    private request;
     /**
      * One attempt.
      *
@@ -388,6 +403,63 @@ declare class HttpClient {
     private headersToObject;
     private log;
 }
+/**
+ * The client the SDK's own factory holds: {@link HttpClient} plus the three things only the owning
+ * client does to it — `configure` (`updateConfig()`), `withHeaders` (`with()`) and `setApiKey`
+ * (`setApiKey()`). It is not exported from the package, so a customer holding the client from
+ * `getHttpClient()` sees `send` and `fetchPayload` and nothing else (REL-3107).
+ */
+declare class ControlledHttpClient extends HttpClient {
+    /**
+     * A view of this client that sends every request through it with `headers` added — beneath the
+     * request's own, over this client's — and changes nothing else: its key, base URL, timeout,
+     * retries and `fetch` are this client's as they are when each request is sent, so a later
+     * `configure()` or `setApiKey()` on this client reaches the view, and one on the view reaches
+     * this client. `client.with({ dataset })` is one (REL-2417).
+     */
+    withHeaders(headers: Readonly<Record<string, string>>): ControlledHttpClient;
+    /**
+     * Run on `config` from now on: every later request — whoever holds this client — is sent to its
+     * `baseUrl`, with its headers, key and dataset, its timeout and retries, through its `fetch`, and
+     * logged by its `debug` options.
+     *
+     * The client's own `updateConfig()` calls this rather than building a second client, so a
+     * `content()` or other sub-client taken before the update sends through the update too. Anything
+     * set on this client since it was last configured — `setApiKey()` — is replaced by what `config`
+     * says.
+     */
+    configure(config: MergedRelyIOConfig): void;
+    /**
+     * Replace the key every later request sends as `X-API-Key`, and the `apiKey` the configuration
+     * reports.
+     *
+     * The key is read the way construction reads it (`presentKey`): an absent, empty or blank key is
+     * no key, so the header is dropped and the next request is refused with `MissingApiKeyError`
+     * before anything is sent. A key header of any other spelling — one given in `headers` — goes
+     * too, from the headers sent and from the headers the configuration reports, so the old key is
+     * never sent beside the new one.
+     *
+     * The configuration is the one the owning `TypedRelyIOClient` holds (it hands its own to the
+     * constructor), so its `getConfig().apiKey` — what a surface reads to decide a key's kind — is the
+     * key sent from here on.
+     *
+     * This replaced `setAuthToken`, which added `Authorization: Bearer` beside an `X-API-Key` it
+     * never touched: the API reads `X-API-Key` first, so the old key was the one used (REL-1385).
+     */
+    setApiKey(apiKey: string): void;
+}
+/** Everything a request reads off the configuration, replaced whole whenever it changes. */
+interface Connection {
+    /**
+     * The configuration itself, for what is read per request — `fetch`, the `browser` options,
+     * `debug` — and the object `setApiKey` writes the key into, which the owning client reports.
+     */
+    readonly config: MergedRelyIOConfig;
+    readonly baseUrl: string;
+    readonly defaultHeaders: Readonly<Record<string, string>>;
+    readonly timeout: number;
+    readonly retryPolicy: RetryPolicy;
+}
 
 /**
  * API4's two request headers, as the SDK's writes send them.
@@ -453,6 +525,106 @@ declare function versionCheckOf(entry: ReadEntry): {
  */
 type ClientLocale = string | (() => string | undefined);
 
+/**
+ * Site-visitor live, declared once for everyone who speaks it (`live-layer-spec.md` decisions 15, 19
+ * and 20; phase LV5): the wire a visitor's browser meets at `live.relyio.com`, and the two internal
+ * routes the live Worker calls on `apps/services/api` to serve it.
+ *
+ * It sits in this package's root because three runtimes read it and this is the one package all
+ * three may import: `@relyio/sdk` through the customer-layer chokepoint (`INV-SS-CUSTOMER-FENCE`,
+ * which allows this root), the live Worker, and `apps/services/api`. Pure, like the rest of the root:
+ * no `node:` import, so it runs in workerd and a browser.
+ *
+ * ## The visitor front door — `wss://live.relyio.com/visitor/changes` and `GET` on the same path
+ *
+ * A visitor presents a **publishable** key (`rly_pub_…`, `sdk-surfaces-spec.md` decision 29) in the
+ * `key` query parameter — a browser cannot set a socket's headers, and a query parameter keeps the
+ * poll a simple request with no preflight. The door resolves the key's scope, checks the page's
+ * `Origin` against the key's allowed origins, and refuses a key it cannot use, an unlisted origin or
+ * a malformed request **before any object is addressed**. A secret or preview key is refused here:
+ * a preview key's live connection stays on the Content API's `/v1/changes`.
+ *
+ * Only the published lens exists at this door (`INV-SS-FEED-LENS-IS-THE-KEY`); no parameter names a
+ * lens. The dataset is `dataset` — an id or a name, as `X-RelyIO-Dataset` takes it — or the key's
+ * default. `types` and `ids` narrow what reaches this client, comma-separated, and the socket keeps
+ * them as its own filter (`INV-LV-VISITOR-AT-THE-EDGE`).
+ *
+ * ### The socket
+ *
+ * Every frame is text. From the client, only the keepalive {@link VISITOR_KEEPALIVE}, which the
+ * runtime answers without waking the feed; anything else is ignored. From the feed,
+ * {@link VisitorFrame}s:
+ *
+ * 1. Zero or more `feed.changes` / at most one `feed.resync`: the changes after the connect's
+ *    `since` (`INV-SS-CURSOR-REPLAYS`), or the named reason none can be listed.
+ * 2. `feed.opened` exactly once, with the cursor the socket is caught up to: every change after it
+ *    reaches this socket. A connect **without** `since` gets this first, and the client fetches what
+ *    it shows after receiving it — fetching after the feed holds the cursor is what makes the view
+ *    gap-free.
+ * 3. `feed.changes` as the dataset changes, each carrying ids only (`INV-SS-CHANGE-IS-IDS`) and the
+ *    cursor after it. The client keeps the last cursor it received and reconnects with it as
+ *    `since` — after a deploy or a dropped network alike — and is replayed what it missed.
+ *
+ * A change is at-least-once: a replay and the live frames that follow it may name one change twice.
+ * A client refetches what a change names, so a repeat costs a read and never a wrong view.
+ *
+ * A refusal is a socket closed at once with one of {@link VISITOR_CLOSE_CODES} and a reason string,
+ * because a browser cannot read the status of a refused WebSocket handshake; what a client does next
+ * is {@link VISITOR_CLOSE_RETRY}'s, per code.
+ *
+ * ### Admission (`INV-LV-LIVE-CEILINGS`)
+ *
+ * After the key, origin and dataset, the door asks the project's counter whether one more connection
+ * may open — against the project's plan allowance (Starter's 100), its safety ceiling (Pro's 50,000)
+ * and a per-address limit the Worker holds — and refuses before any feed is addressed. The counts are approximate
+ * by design: a feed reports its count within about a second of a change and at least every minute, so
+ * a refusal is decided on counts at most one reporting interval old.
+ *
+ * ### The poll
+ *
+ * `GET` on the same path with the same parameters and a `client` id (a random id the client keeps for
+ * the page's life, so one visitor polling counts once), answered **at once** — never held — with
+ * `{ data: VisitorPollAnswer }`. Where a WebSocket cannot open, a client polls about every
+ * {@link VISITOR_POLL_INTERVAL_MS}. A refusal is the one error envelope, `{ error: { code, messages } }`,
+ * at the code's status.
+ *
+ * ## The two internal routes (`apps/services/api`, `x-internal-secret`)
+ *
+ * - `POST /internal/live/visitor-key` — {@link VisitorKeyResolve} → {@link VisitorKeyResolution}:
+ *   what a presented key may reach, in the binding shape `./edge.ts` already declares for the Content
+ *   API's edge, plus the project's live regions the feed is placed by. The Worker keeps the answer
+ *   under the key's SHA-256, with the tag origin minted for it, as `apps/edge/api` keeps a binding, so
+ *   a revocation's purge evicts both.
+ * - `POST /internal/live/visitor-feed/{projectId}/{datasetId}/changes` — {@link VisitorLedgerRead} →
+ *   {@link VisitorLedgerPage}: the ledger page after a cursor in the `public` lens, the same read and
+ *   the same page shape the Studio service answers a dataset room with in the `preview` lens
+ *   (`@relyio/live-contracts`' `rest/live-room.ts`), plus one resync reason a room never meets —
+ *   a cursor a visitor's client supplied that this dataset's feed never issued.
+ */
+
+/**
+ * Why a ledger read cannot list the changes from a cursor to now:
+ *
+ * - `retention` — rows after the cursor may have been reaped (`@relyio/entry-changes`' retention).
+ * - `dataset-replaced` — the dataset was purged or populated wholesale.
+ * - `ahead-of-head` — the cursor is past the ledger's head: the ledger was reset under it.
+ * - `foreign-cursor` — the cursor is not one this dataset's feed issued (malformed, or another
+ *   dataset's). A room never meets it; a visitor's client supplies its own cursor.
+ */
+type VisitorLedgerResyncReason = 'retention' | 'dataset-replaced' | 'ahead-of-head' | 'foreign-cursor';
+/**
+ * Why a client is told to refetch everything: any reason the ledger gave, or `too-far-behind` — the
+ * client's cursor is further back than one replay lists (`VisitorFeed`'s `MAX_REPLAY_PAGES`), and a
+ * refetch is less than the replay would be.
+ */
+type VisitorResyncReason = VisitorLedgerResyncReason | 'too-far-behind';
+/**
+ * What a client does after a refusal: `stop` (the same request meets the same answer), `retry`
+ * (backoff and jitter from about a second) or `back-off` (full now: wait at least
+ * {@link VISITOR_ADMISSION_RETRY_AFTER_SECONDS}, with jitter, doubling while it repeats).
+ */
+type VisitorRetry = 'stop' | 'retry' | 'back-off';
+
 /**
  * Two read terms every read that takes them writes the same way: the children an entry embeds,
  * and the refusal of a condition on `_metadata`. Here once, for the list and entry reads
@@ -551,7 +723,7 @@ type FreshOption = true | NonNullable<Term<'/v1/{contentType}', 'get', '_fresh'>
  * - `children` — each entry's children, of every content type, under `_children`: `true` for one
  *   level, or a depth of 1 to 3 and at most `limit` per parent (REL-1118).
  */
-interface EntryReadOptions<R extends Reading, P extends readonly string[], L extends LocaleOption<ReadLocale<R>> | undefined = undefined> {
+interface EntryReadOptions<R extends Reading, P extends readonly string[], L extends LocaleOption<ReadLocale<R>> | undefined = undefined, C extends ChildrenRead | undefined = ChildrenRead | undefined> {
     /** Include paths: the references to expand into the entries they point at (REL-1801). */
     readonly include?: CheckedIncludes<R, P>;
     /** The locale, locales or `'*'` to read, over the client's locale (Q16). */
@@ -561,10 +733,16 @@ interface EntryReadOptions<R extends Reading, P extends readonly string[], L ext
     /** How fresh the answer must be: a feed position, or `true` for past every cache. */
     readonly fresh?: FreshOption;
     /** Embed each entry's children: `true`, or a depth and a per-parent limit (REL-1118). */
-    readonly children?: true | ChildrenOptions;
+    readonly children?: C;
+    /**
+     * Cancels the request when it aborts. The call then rejects with the platform's `AbortError` —
+     * not a `TimeoutError` — and a request already cancelled sends nothing. The client's timeout
+     * still applies.
+     */
+    readonly signal?: AbortSignal;
 }
 /** The options a list read takes beside how it pages: what it keeps, how, and how many a page holds. */
-interface ListReadOptions<T extends BaseContent, R extends Reading, P extends readonly string[], S extends readonly FieldKey<T>[] | undefined = undefined, L extends LocaleOption<ReadLocale<R>> | undefined = undefined> extends EntryReadOptions<R, P, L> {
+interface ListReadOptions<T extends BaseContent, R extends Reading, P extends readonly string[], S extends readonly FieldKey<T>[] | undefined = undefined, L extends LocaleOption<ReadLocale<R>> | undefined = undefined, C extends ChildrenRead | undefined = ChildrenRead | undefined> extends EntryReadOptions<R, P, L, C> {
     /**
      * The conditions an entry must meet, by the paths the API filters on (REL-2136). A condition on
      * `_metadata` is refused before anything is sent.
@@ -593,20 +771,20 @@ type Paging = {
     readonly cursor?: never;
 };
 /** What `list(options)` takes. */
-type ListOptions<T extends BaseContent, R extends Reading, P extends readonly string[], S extends readonly FieldKey<T>[] | undefined = undefined, L extends LocaleOption<ReadLocale<R>> | undefined = undefined> = ListReadOptions<T, R, P, S, L> & Paging;
+type ListOptions<T extends BaseContent, R extends Reading, P extends readonly string[], S extends readonly FieldKey<T>[] | undefined = undefined, L extends LocaleOption<ReadLocale<R>> | undefined = undefined, C extends ChildrenRead | undefined = ChildrenRead | undefined> = ListReadOptions<T, R, P, S, L, C> & Paging;
 /**
  * What `children(id, options)` takes (REL-1864): an entry read's options and the page of the list
  * — `limit` the page size, and the `cursor` a page handed back or a page number to choose which.
  * No `where`, `select` or `sort`: the route declares none, and the order is the hierarchy's.
  */
-type ChildrenListOptions<R extends Reading, P extends readonly string[], L extends LocaleOption<ReadLocale<R>> | undefined = undefined> = EntryReadOptions<R, P, L> & {
+type ChildrenListOptions<R extends Reading, P extends readonly string[], L extends LocaleOption<ReadLocale<R>> | undefined = undefined, C extends ChildrenRead | undefined = ChildrenRead | undefined> = EntryReadOptions<R, P, L, C> & {
     /** How many children a page holds, whether it is read by cursor or by number. */
     readonly limit?: Term<'/v1/{contentType}/{id}/children', 'get', 'limit'>;
 } & Paging;
 /** What `listAll(options)` takes: a list's options, paged by the walk itself. */
-type ListAllOptions<T extends BaseContent, R extends Reading, P extends readonly string[], S extends readonly FieldKey<T>[] | undefined = undefined, L extends LocaleOption<ReadLocale<R>> | undefined = undefined> = ListReadOptions<T, R, P, S, L>;
+type ListAllOptions<T extends BaseContent, R extends Reading, P extends readonly string[], S extends readonly FieldKey<T>[] | undefined = undefined, L extends LocaleOption<ReadLocale<R>> | undefined = undefined, C extends ChildrenRead | undefined = ChildrenRead | undefined> = ListReadOptions<T, R, P, S, L, C>;
 /** What `get(idOrSlug, options)` takes. */
-type GetOptions<R extends Reading, P extends readonly string[], L extends LocaleOption<ReadLocale<R>> | undefined = undefined> = EntryReadOptions<R, P, L>;
+type GetOptions<R extends Reading, P extends readonly string[], L extends LocaleOption<ReadLocale<R>> | undefined = undefined, C extends ChildrenRead | undefined = ChildrenRead | undefined> = EntryReadOptions<R, P, L, C>;
 /**
  * What a one-document read takes — `singleton(key).get(options)` and `settings(group).get(options)`
  * (REL-2419, REL-2409 decision Q18): a content read's options where their routes declare them.
@@ -627,6 +805,12 @@ interface DocumentReadOptions<R extends Reading, P extends readonly string[]> {
     readonly dataset?: string;
     /** How fresh the answer must be: a feed position, or `true` for past every cache. */
     readonly fresh?: FreshOption;
+    /**
+     * Cancels the request when it aborts. The call then rejects with the platform's `AbortError` —
+     * not a `TimeoutError` — and a request already cancelled sends nothing. The client's timeout
+     * still applies.
+     */
+    readonly signal?: AbortSignal;
 }
 /**
  * What `version()` takes on every handle (REL-2427): the version to read, and the locale whose
@@ -664,8 +848,27 @@ type Localized<E, L, C extends string> = L extends '*' | readonly string[] ? E e
         localizations: Localizations<E, L extends readonly string[] ? L[number] : C>;
     };
 } : E : E;
-/** What a read of `R` returns under its include paths `P`, selection `S` and locale `L`. */
-type ReadAs<R extends Reading, P extends readonly string[], S = undefined, L = undefined> = Localized<SelectedFields<ReadWith<R, P[number]>, S, P[number]>, L, ReadLocale<R>>;
+/** What a read's `children` takes: `true`, or a depth and a per-parent limit. */
+type ChildrenRead = true | ChildrenOptions;
+/**
+ * One child as the API serves it: an entry of any content type, the document's `Entry`. The
+ * children of an entry are of every content type (there is no filter by type), so no one schema
+ * types them.
+ */
+type ChildEntry = components['schemas']['Entry'];
+/**
+ * What `children` adds to a read (REL-2456): `_children`, the document's own shape
+ * (`components['schemas']['Entry']['_children']`, which the API serves beside the fields), on a read
+ * that asked for them — and nothing on one that did not, since the API serves none then.
+ */
+type WithChildren<E, C> = [C] extends [undefined] ? E : [C] extends [ChildrenRead] ? E & {
+    readonly _children: NonNullable<ChildEntry['_children']>;
+} : E;
+/**
+ * What a read of `R` returns under its include paths `P`, selection `S`, locale `L` and children
+ * `C` (what its `children` option was).
+ */
+type ReadAs<R extends Reading, P extends readonly string[], S = undefined, L = undefined, C = undefined> = WithChildren<Localized<SelectedFields<ReadWith<R, P[number]>, S, P[number]>, L, ReadLocale<R>>, C>;
 /**
  * Where a read reads and how fresh it must be, as an implementation reads them whatever the type
  * parameters checked: the clump every read takes — an entry read, a list, a one-document read, a
@@ -677,6 +880,12 @@ interface WrittenReadScope {
     readonly locale?: string | readonly string[];
     readonly dataset?: string;
     readonly fresh?: FreshOption;
+    /**
+     * Cancels the request when it aborts. The call then rejects with the platform's `AbortError` —
+     * not a `TimeoutError` — and a request already cancelled sends nothing. The client's timeout
+     * still applies.
+     */
+    readonly signal?: AbortSignal;
 }
 /**
  * A `sort` as an implementation reads it, whatever keys the type checked ({@link SortOption}): a
@@ -733,7 +942,7 @@ declare abstract class EntryHandle<T extends BaseContent, R extends Reading, Rev
      * })
      * ```
      */
-    list<const P extends readonly string[] = [], const S extends readonly FieldKey<T>[] | undefined = undefined, const L extends LocaleOption<ReadLocale<R>> | undefined = undefined>(options?: ListOptions<T, R, P, S, L>): Promise<EntryList<ReadAs<R, P, S, L>>>;
+    list<const P extends readonly string[] = [], const S extends readonly FieldKey<T>[] | undefined = undefined, const L extends LocaleOption<ReadLocale<R>> | undefined = undefined, const C extends ChildrenRead | undefined = undefined>(options?: ListOptions<T, R, P, S, L, C>): Promise<EntryList<ReadAs<R, P, S, L, C>>>;
     /**
      * Every entry of this type that `where` keeps, page after page, as an async iterable: the walk
      * follows each page's cursor and stops where the API says there is no more (REL-2415).
@@ -743,7 +952,7 @@ declare abstract class EntryHandle<T extends BaseContent, R extends Reading, Rev
      * Iterating throws when a page says there is more and hands back no cursor to read it by, rather
      * than ending the walk short.
      */
-    listAll<const P extends readonly string[] = [], const S extends readonly FieldKey<T>[] | undefined = undefined, const L extends LocaleOption<ReadLocale<R>> | undefined = undefined>(options?: ListAllOptions<T, R, P, S, L>): AsyncIterable<ReadAs<R, P, S, L>>;
+    listAll<const P extends readonly string[] = [], const S extends readonly FieldKey<T>[] | undefined = undefined, const L extends LocaleOption<ReadLocale<R>> | undefined = undefined, const C extends ChildrenRead | undefined = undefined>(options?: ListAllOptions<T, R, P, S, L, C>): AsyncIterable<ReadAs<R, P, S, L, C>>;
     private walk;
     /**
      * One entry by its id or slug, or `null` when there is no such entry (REL-2415).
@@ -762,7 +971,7 @@ declare abstract class EntryHandle<T extends BaseContent, R extends Reading, Rev
      * if (post === null) return notFound()
      * ```
      */
-    get<const P extends readonly string[] = [], const L extends LocaleOption<ReadLocale<R>> | undefined = undefined>(idOrSlug: string, options?: GetOptions<R, P, L>): Promise<ReadAs<R, P, undefined, L> | null>;
+    get<const P extends readonly string[] = [], const L extends LocaleOption<ReadLocale<R>> | undefined = undefined, const C extends ChildrenRead | undefined = undefined>(idOrSlug: string, options?: GetOptions<R, P, L, C>): Promise<ReadAs<R, P, undefined, L, C> | null>;
     /**
      * Update an entry you read, checked against the version it was read at (REL-2418).
      *
@@ -840,7 +1049,10 @@ interface CreateEntryOptions extends EntryPlacement, RetryableWriteOptions {
  */
 declare class ContentClient<T extends BaseContent = BaseContent, R extends Reading = UntypedReading<T>> extends EntryHandle<T, R, RevisedContent<T>, EntryPlacement> {
     /**
-     * Create a new content entry.
+     * Create a new content entry, published. The answer's `_metadata.warnings` lists each reference
+     * the content type declares `weak` that the create made live while the entry it points at is
+     * unpublished (`REFERENCE_NOT_PUBLISHED`) — `[]` when there are none; the create is never refused
+     * for them.
      *
      * `locale` defaults to the client's own, and `dataset` to the client's (`client.with({ dataset })`
      * sets it for every call).
@@ -850,22 +1062,19 @@ declare class ContentClient<T extends BaseContent = BaseContent, R extends Readi
      * const post = await relyio.content('post').create({ title: 'Hello' }, { slug: 'hello' })
      * ```
      */
-    create(data: CreateInput<T>, options?: CreateEntryOptions): Promise<T>;
+    create(data: CreateInput<T>, options?: CreateEntryOptions): Promise<CreatedContent<T>>;
     /**
      * Get version history for one locale of an entry.
      *
      * Versions are numbered per locale, so this is one locale's timeline: `locale` defaults to the
      * client's own, else the schema default; no fallback is applied, and a locale
      * with no history returns an empty array rather than another locale's rows. Every row names the
-     * locale it belongs to.
+     * locale it belongs to, and holds that locale's fields under `fields`.
      */
     versions(id: string, options?: {
         limit?: number;
         locale?: string;
-    }): Promise<Array<T & {
-        versionNumber: number;
-        locale: string;
-    }>>;
+    }): Promise<Array<ContentVersionRow<T>>>;
     /**
      * One version of an entry: `version(id, { version, locale })`.
      *
@@ -875,8 +1084,11 @@ declare class ContentClient<T extends BaseContent = BaseContent, R extends Readi
      * There is no `null`: a version the locale does not have, an entry that is not there, a type the
      * schema does not declare and a dataset with no schema all throw `ResourceNotFoundError`, its
      * `context.resourceType` naming which (REL-2409 Q12).
+     *
+     * It answers the version, not the entry: that locale's own fields as the version stored them, and
+     * `_metadata` with `status: 'version'` ({@link ContentVersion}).
      */
-    version(id: string, options: VersionOptions): Promise<T>;
+    version(id: string, options: VersionOptions): Promise<ContentVersion<T>>;
     /**
      * Revert one locale of an entry you read to a previous version: `restore(entry, { version })`,
      * checked against the version the entry carries, in the locale it was read in — as
@@ -930,7 +1142,7 @@ declare class ContentClient<T extends BaseContent = BaseContent, R extends Readi
      * }
      * ```
      */
-    children<const P extends readonly string[] = [], const L extends LocaleOption<ReadLocale<R>> | undefined = undefined>(id: string, options?: ChildrenListOptions<R, P, L>): Promise<EntryList<ReadAs<R, P, undefined, L>>>;
+    children<const P extends readonly string[] = [], const L extends LocaleOption<ReadLocale<R>> | undefined = undefined, const C extends ChildrenRead | undefined = undefined>(id: string, options?: ChildrenListOptions<R, P, L, C>): Promise<EntryList<ReadAs<R, P, undefined, L, C>>>;
 }
 
 /**
@@ -1343,6 +1555,23 @@ declare class AssetUploadBuilder<T extends BaseContent = BaseContent> {
     private putPartWithRetry;
     private emitProgress;
 }
+/**
+ * The `file.*` paths an asset list filters by (REL-2456): the facets of the binding the route admits
+ * on a public read (`QUERY_FILE_MEMBERS` in `@relyio/schema`), each taking the condition its value
+ * does. The binding's server-only members — `objectKey`, `streamVideoId`, `storageVersion`,
+ * `scan.*`, `extracted.text` — are refused by the API by name (REL-1501, REL-933), so they are no
+ * key here; nor is `urls`, which is computed and never stored.
+ */
+interface AssetFileWhere {
+    readonly 'file.status'?: WhereFieldCondition<AssetFileBlock['status']>;
+    readonly 'file.backend'?: WhereFieldCondition<AssetFileBlock['backend']>;
+    readonly 'file.mimeType'?: WhereFieldCondition<string>;
+    readonly 'file.fileName'?: WhereFieldCondition<string>;
+    readonly 'file.size'?: WhereFieldCondition<number>;
+    readonly 'file.extracted.width'?: WhereFieldCondition<number>;
+    readonly 'file.extracted.height'?: WhereFieldCondition<number>;
+    readonly 'file.extracted.duration'?: WhereFieldCondition<number>;
+}
 /**
  * An asset read typed by the asset type's reading `R`: what the type's include paths make of its
  * fields, beside the `file` and `urls` blocks every asset read carries (REL-1801).
@@ -1351,10 +1580,11 @@ interface AssetResponseReading<R extends Reading, T extends BaseContent = BaseCo
     readonly read: AssetEntryResponse<Extract<ReadWith<R, this['include']>, BaseContent>>;
     readonly checked: CheckedInclude<R, this['path']>;
     /**
-     * The asset type's own `where` — every path the API filters its fields by, never the `file` and
-     * `urls` blocks — or, where no schema types it, the conditions `T`'s keys take (REL-2195).
+     * The asset type's own `where` — every path the API filters its fields by — and the `file.*`
+     * facets the list admits ({@link AssetFileWhere}, REL-2456), or, where no schema types it, the
+     * conditions `T`'s keys take (REL-2195).
      */
-    readonly where: ReadWhere<WhereClause<T>, R>;
+    readonly where: ReadWhere<WhereClause<T>, R> & AssetFileWhere;
     /** The locale codes its `locale` may name: the asset type's reading's. */
     readonly locale: ReadLocale<R>;
 }
@@ -1423,11 +1653,21 @@ interface DocumentVersionsOptions {
     /** The locale whose timeline it is; the client's own, then the schema default, when left out. */
     readonly locale?: string;
 }
-/** One row of a one-document handle's history: the document as it was, in the locale it names. */
-type DocumentVersion<T> = T & {
-    versionNumber: number;
-    locale: string;
+/**
+ * One version of a singleton or a settings group, as `version({ version })` reads it — the
+ * document's `DocumentVersion` (REL-3181): which version of which locale, who wrote it and when, and
+ * the fields that locale stored, nested under `fields`. Every field is optional: a locale's row
+ * holds that locale's own fields, never the shared ones.
+ */
+type DocumentVersion<T> = Omit<components['schemas']['DocumentVersion'], 'fields'> & {
+    fields: Partial<Omit<T, '_metadata'>>;
 };
+/**
+ * One row of a one-document handle's history, as `versions()` lists it — the document's
+ * `DocumentVersionRow` (REL-3269): a version's number, locale, author and time, without its fields,
+ * which the list does not send. Read one with `version({ version })` for what it stored.
+ */
+type DocumentVersionRow = components['schemas']['DocumentVersionRow'];
 /**
  * The verbs a singleton's and a settings group's handle share (REL-2419, REL-2409 decision Q18):
  * `update`, `versions` and `version`, written once, as {@link EntryHandle} writes the entry routes'
@@ -1441,7 +1681,7 @@ type DocumentVersion<T> = T & {
  * Every call is in the locale it names, and otherwise in the client's own as it is when the call is
  * made; a write of a document you read writes the locale it was read in.
  */
-declare abstract class DocumentHandle<T> {
+declare abstract class DocumentHandle<T, W = T> {
     protected readonly httpClient: HttpClient;
     protected readonly name: string;
     /** The client's locale, asked on every call rather than copied when this handle was taken. */
@@ -1458,12 +1698,12 @@ declare abstract class DocumentHandle<T> {
      * read, the write is refused with `ResourceConflictError` naming both versions: re-read it with
      * `fresh: true` and retry.
      */
-    update(read: ReadEntry, data: DocumentFields<T>, options?: RetryableWriteOptions): Promise<T>;
+    update(read: ReadEntry, data: DocumentFields<T>, options?: RetryableWriteOptions): Promise<W>;
     /**
      * Write the document with no version check, on purpose, in `options.locale` or the client's own —
      * creating it, when nobody has yet.
      */
-    update(data: DocumentFields<T>, options?: DocumentWriteOptions): Promise<T>;
+    update(data: DocumentFields<T>, options?: DocumentWriteOptions): Promise<W>;
     /**
      * Version history for one locale of the document.
      *
@@ -1472,7 +1712,7 @@ declare abstract class DocumentHandle<T> {
      * returns an empty array rather than another locale's rows. Every row names the locale it belongs
      * to.
      */
-    versions(options?: DocumentVersionsOptions): Promise<Array<DocumentVersion<T>>>;
+    versions(options?: DocumentVersionsOptions): Promise<DocumentVersionRow[]>;
     /**
      * One version of the document: `version({ version, locale })`. `locale` defaults to the client's
      * own, then the schema default; version numbers are per locale, so version 2 is different content
@@ -1482,20 +1722,20 @@ declare abstract class DocumentHandle<T> {
      * schema does not declare and a dataset with no schema all throw `ResourceNotFoundError`, its
      * `context.resourceType` naming which (REL-2409 Q12).
      */
-    version(options: VersionOptions): Promise<T>;
-    /** `PATCH` the document's route with this write. */
-    protected abstract patch(write: DocumentWrite<T>, options?: RetryableWriteOptions): Promise<T>;
+    version(options: VersionOptions): Promise<DocumentVersion<T>>;
+    /** `PATCH` the document's route with this write, answering what the route answers a write. */
+    protected abstract patch(write: DocumentWrite<T>, options?: RetryableWriteOptions): Promise<W>;
     /** `GET` the document's version history route. */
     protected abstract readVersions(query: {
         limit: number;
         locale?: string;
     }): Promise<{
-        versions: Array<DocumentVersion<T>>;
+        versions: DocumentVersionRow[];
     }>;
     /** `GET` one version of the document. */
     protected abstract readVersion(versionNumber: string, query: {
         locale?: string;
-    }): Promise<T>;
+    }): Promise<DocumentVersion<T>>;
     /** The locale a write or a history read sends: the call's, else the client's. */
     protected localeOf(named: string | undefined): string | undefined;
     /** The write's body: its data, and the locale it names when it names one. */
@@ -1526,7 +1766,7 @@ declare abstract class DocumentHandle<T> {
  * if (homepage) await client.singleton('homepage').update(homepage, { title: 'Welcome' })
  * ```
  */
-declare class SingletonClient<T = BaseSingleton, R extends Reading = UntypedReading<T>> extends DocumentHandle<T> {
+declare class SingletonClient<T = BaseSingleton, R extends Reading = UntypedReading<T>> extends DocumentHandle<T, WrittenSingleton<T>> {
     /**
      * The singleton, or `null` when nobody has written it yet (REL-2419, REL-2409 Q18).
      *
@@ -1544,17 +1784,20 @@ declare class SingletonClient<T = BaseSingleton, R extends Reading = UntypedRead
      * ```
      */
     get<const P extends readonly string[] = []>(options?: DocumentReadOptions<R, P>): Promise<ReadWith<R, P[number]> | null>;
-    /** The API publishes on PATCH: there is no separate publish route. */
-    protected patch(write: DocumentWrite<T>, options?: RetryableWriteOptions): Promise<T>;
+    /**
+     * The API publishes on PATCH: there is no separate publish route. The answer's `_metadata` also
+     * lists the links the write left pointing nowhere and its `warnings` (REL-3097).
+     */
+    protected patch(write: DocumentWrite<T>, options?: RetryableWriteOptions): Promise<WrittenSingleton<T>>;
     protected readVersions(query: {
         limit: number;
         locale?: string;
     }): Promise<{
-        versions: Array<DocumentVersion<T>>;
+        versions: DocumentVersionRow[];
     }>;
     protected readVersion(versionNumber: string, query: {
         locale?: string;
-    }): Promise<T>;
+    }): Promise<DocumentVersion<T>>;
 }
 
 /**
@@ -1581,7 +1824,7 @@ declare class SingletonClient<T = BaseSingleton, R extends Reading = UntypedRead
  * await client.settings('email-config').update(emailConfig, { fromName: 'RelyIO' })
  * ```
  */
-declare class SettingsClient<T = BaseSettingsGroup, R extends Reading = UntypedReading<T>> extends DocumentHandle<T> {
+declare class SettingsClient<T = BaseSettingsGroup, R extends Reading = UntypedReading<T>> extends DocumentHandle<T, WrittenSettingsGroup<T>> {
     /**
      * The settings group (REL-2419, REL-2409 Q18).
      *
@@ -1606,25 +1849,25 @@ declare class SettingsClient<T = BaseSettingsGroup, R extends Reading = UntypedR
      * in the locale it was read in (REL-2419) — refused with `ResourceConflictError` if it changed
      * since the read.
      */
-    reset(read: ReadEntry, options?: RetryableWriteOptions): Promise<T>;
+    reset(read: ReadEntry, options?: RetryableWriteOptions): Promise<WrittenSettingsGroup<T>>;
     /**
      * Reset the group to its default values with no version check, in `options.locale` or the
      * client's own. The route reads its locale from `?locale=` and takes no body, so that is where it
      * is sent.
      */
-    reset(options?: DocumentWriteOptions): Promise<T>;
+    reset(options?: DocumentWriteOptions): Promise<WrittenSettingsGroup<T>>;
     /** The group's default values, as the schema declares them. */
     getDefaults(): Promise<T>;
-    protected patch(write: DocumentWrite<T>, options?: RetryableWriteOptions): Promise<T>;
+    protected patch(write: DocumentWrite<T>, options?: RetryableWriteOptions): Promise<WrittenSettingsGroup<T>>;
     protected readVersions(query: {
         limit: number;
         locale?: string;
     }): Promise<{
-        versions: Array<DocumentVersion<T>>;
+        versions: DocumentVersionRow[];
     }>;
     protected readVersion(versionNumber: string, query: {
         locale?: string;
-    }): Promise<T>;
+    }): Promise<DocumentVersion<T>>;
 }
 
 /**
@@ -1804,6 +2047,12 @@ interface SearchReadOptions<C extends string> {
     readonly dataset?: string;
     /** How fresh the answer must be: a feed position, or `true` for past every cache. */
     readonly fresh?: FreshOption;
+    /**
+     * Cancels the request when it aborts. The call then rejects with the platform's `AbortError` —
+     * not a `TimeoutError` — and a request already cancelled sends nothing. The client's timeout
+     * still applies.
+     */
+    readonly signal?: AbortSignal;
 }
 /**
  * What `search(q, options)` takes.
@@ -1993,6 +2242,12 @@ interface BatchWriteOptions {
     readonly returnData?: boolean;
     /** The dataset to write, by id or name, over the client's. */
     readonly dataset?: string;
+    /**
+     * Cancels the request when it aborts. The call then rejects with the platform's `AbortError` —
+     * not a `TimeoutError` — and a request already cancelled sends nothing. The client's timeout
+     * still applies.
+     */
+    readonly signal?: AbortSignal;
 }
 /**
  * One batch item, as the committed document describes the `multi` kind: an `outcome` —
@@ -2009,21 +2264,26 @@ type BatchBody = Wire<'/v1/batch', 'post', BatchResponse>;
 /**
  * Ad-hoc and named queries as single calls: `client.query(…)` (REL-2421; REL-2409 decision Q22).
  *
- * - `client.query({ from, … })` runs a query inline. It takes `list`'s option names, typed from the
- *   same option types — `include`, `select`, `sort`, `limit`, `page`, `locale`, `dataset`, `fresh` —
- *   plus its own: `aggregate`, `params` and `fullText`. `where` is `list`'s, typed as `list` types
- *   it (`{ views: { $gte: 10 } }`): the query route reads the `where` a list takes (REL-2439,
- *   REL-2409 decision D11), and refuses the bare form a saved query used to declare.
+ * - `client.query({ from, … })` runs a query inline. It takes `list`'s options, typed from the same
+ *   option types — `where`, `include`, `select`, `sort`, `limit`, `cursor`, `page`, `locale`,
+ *   `dataset`, `fresh` — plus its own: `aggregate`, `params` and `fullText`. `where` is `list`'s,
+ *   typed as `list` types it (`{ views: { $gte: 10 } }`): the query route reads the `where` a list
+ *   takes (REL-2439, REL-2409 decision D11), and refuses the bare form a saved query used to
+ *   declare. `locale` is a code, a list of codes or `'*'`, and `select` sits beside `include`, as
+ *   they do on `list` (REL-2460).
  * - `client.query(name, { params, … })` runs the saved query the schema declares under `name`, by
  *   that name alone (`POST /v1/queries/{name}`, D9). Its parameters are typed from the declaration
  *   ({@link InferQueryParams}): a name it does not declare does not compile, and the API refuses it
  *   too, naming it.
  *
- * Both answer the API's body, `{ data: { result, metadata } }`.
- *
- * The query route pages by `limit` and `offset` and answers no cursor, so a query pages by number:
- * `page` with `limit`, sent as the offset that page starts at. There is no `cursor`.
+ * An ad-hoc query answers a list's envelope, `{ data, page, meta }` — its records the entries
+ * `list` answers, an aggregate's rows or a singleton as a list of one, `page` the cursor page
+ * `{ nextCursor, hasMore }` and `meta` how the query ran. A named query answers the API's body,
+ * `{ data: { result, metadata } }`.
  *
+ * The cursor and the locale ride the POST's query string as they ride a list's (`?cursor=`,
+ * `?locale=`, `?locales=`); a `page` number is sent as the offset that page starts at, so it needs the
+ * `limit` that sizes it — the route has no default page size.
  */
 
 /** The content types a query reads: the schema's, or any where no schema types the client. */
@@ -2043,45 +2303,35 @@ type NamedQueryParams<S, N> = S extends AnySchemaDefinition ? InferQueryParams<S
  * route's `aggregate` block. Its source is `from`.
  */
 type QueryAggregate = Omit<AggregateBlock, 'source'>;
-/** How a query pages: by number, with `limit` its size — or not at all. */
+/**
+ * Which page of a query: the `cursor` a previous answer's `page` handed back, or a page number, one
+ * or the other as on `list`. A number is sent as the offset it starts at, `(page - 1) * limit`, so it
+ * needs the `limit` that sizes it: the route has no default page size to count from.
+ */
 type QueryPaging<T extends BaseContent, R extends Reading> = {
+    /** The page after the one a previous answer ended on: its `page.nextCursor`. */
+    readonly cursor?: string;
     readonly page?: never;
 } | {
     /** Which page, from 1: sent as the offset it starts at, `(page - 1) * limit`. */
     readonly page: number;
     readonly limit: NonNullable<ListReadOptions<T, R, []>['limit']>;
+    readonly cursor?: never;
 };
-/** `select` or `include`: the route refuses an include path beside a selection. */
-type SelectOrInclude<R extends Reading, P extends readonly string[], Sel> = {
-    readonly select?: Sel;
-    readonly include?: undefined;
-} | {
-    readonly select?: undefined;
-    readonly include?: CheckedIncludes<R, P>;
-};
+/** The options a query takes exactly as `list` takes them, typed by `list`'s own types. */
+type ListedOptions = 'where' | 'include' | 'select' | 'sort' | 'limit' | 'locale' | 'dataset' | 'fresh' | 'signal';
 /**
- * What `client.query({ from, … })` takes: `list`'s options, typed as `list` types them, and the
- * query's own.
+ * What `client.query({ from, … })` takes: `list`'s options — the very types, so a change to one is a
+ * change to both — and the query's own (REL-2460).
+ *
+ * `where` is `list`'s, a value, a list or `$`-prefixed operators (`{ views: { $gte: 10 } }`), and a
+ * condition on `_metadata` is refused before anything is sent. `locale` is a code, a list of codes or
+ * `'*'`. `select` sits beside `include`: the selected Fields, the expanded references and
+ * `_metadata`.
  */
-type AdhocQuery<K extends string, T extends BaseContent, R extends Reading, P extends readonly string[], Sel extends readonly FieldKey<T>[] | undefined, A extends QueryAggregate | undefined> = {
+type AdhocQuery<K extends string, T extends BaseContent, R extends Reading, P extends readonly string[], Sel extends readonly FieldKey<T>[] | undefined, L extends LocaleOption<ReadLocale<R>> | undefined, A extends QueryAggregate | undefined> = {
     /** The content type the query reads. */
     readonly from: K;
-    /**
-     * The conditions an entry must meet: the `where` `list` takes, typed as `list` types it — a value,
-     * a list, or `$`-prefixed operators (`{ views: { $gte: 10 } }`). A condition on `_metadata` is
-     * refused before anything is sent.
-     */
-    readonly where?: ListReadOptions<T, R, P>['where'];
-    /** The order, by Field or system date, the key order the priority. */
-    readonly sort?: SortOption<T>;
-    /** How many entries the query answers — a page's size where `page` names one. */
-    readonly limit?: ListReadOptions<T, R, P>['limit'];
-    /** The one locale the entries are composed in, over the client's. */
-    readonly locale?: ReadLocale<R>;
-    /** The dataset to read, by id or name, over the client's. */
-    readonly dataset?: string;
-    /** How fresh the answer must be: a feed position, or `true` for past every cache. */
-    readonly fresh?: FreshOption;
     /** Groups and metrics computed over the entries fetched; the answer is then their rows. */
     readonly aggregate?: A;
     /** Values for the `${param}` expressions the query writes. */
@@ -2090,7 +2340,7 @@ type AdhocQuery<K extends string, T extends BaseContent, R extends Reading, P ex
     };
     /** A text search over the Fields it names, beside the fetch. */
     readonly fullText?: FullTextSearch;
-} & QueryPaging<T, R> & SelectOrInclude<R, P, Sel>;
+} & Pick<ListReadOptions<T, R, P, Sel, L, undefined>, ListedOptions> & QueryPaging<T, R>;
 /** What `client.query(name, options)` takes beside the parameters. */
 interface NamedQueryReadOptions<L extends string> {
     /** The one locale the query composes in, over the client's. */
@@ -2098,10 +2348,17 @@ interface NamedQueryReadOptions<L extends string> {
     /** The dataset to read, by id or name, over the client's. */
     readonly dataset?: string;
     /**
-     * `true` reads past every cache. The route is not edge-kept, so a feed position has no cached
-     * answer to be fresher than and is not offered.
+     * How fresh the answer must be: a feed position (a change's `fresh`), or `true` for past every
+     * cache. The route is kept at the edge for as long as the query's own `cache` policy allows
+     * (REL-2451), so a position names a key no copy from before that change is under.
      */
-    readonly fresh?: true;
+    readonly fresh?: FreshOption;
+    /**
+     * Cancels the request when it aborts. The call then rejects with the platform's `AbortError` —
+     * not a `TimeoutError` — and a request already cancelled sends nothing. The client's timeout
+     * still applies.
+     */
+    readonly signal?: AbortSignal;
 }
 /** What `client.query(name, options)` takes: `params` required where the query requires one. */
 type NamedQueryOptions<Params, L extends string> = NamedQueryReadOptions<L> & (Record<never, never> extends Params ? {
@@ -2137,7 +2394,7 @@ interface QueryMetadata {
     /** Validation warnings */
     warnings?: string[];
 }
-/** The API's body for a query: the records it produced and how it ran. */
+/** The API's body for a saved query: the records it produced and how it ran. */
 interface QueryAnswer<T> {
     readonly data: {
         /** The records the query produced. */
@@ -2146,10 +2403,17 @@ interface QueryAnswer<T> {
     };
 }
 /**
- * One record of an ad-hoc query: an aggregate's row, the selected Fields of an entry, or the entry
- * as its include paths read it.
+ * The API's body for an ad-hoc query: a list's envelope (REL-2460), as `list` answers it —
+ * `data` the records, `page` the cursor dialect's `{ nextCursor, hasMore }` and no total, and
+ * `meta` how the query ran ({@link QueryMetadata}).
+ */
+type AdhocAnswer<T> = Wire<'/v1/query', 'post', T>;
+/**
+ * One record of an ad-hoc query: an aggregate's row, or the entry as `list` answers it — the
+ * selected Fields beside `_metadata`, the expanded references of its include paths, and the other
+ * locales under `_metadata.localizations` for a list of locales or `'*'`.
  */
-type AdhocRecord<R extends Reading, P extends readonly string[], Sel, A> = A extends QueryAggregate ? Readonly<Record<string, unknown>> : Sel extends readonly string[] ? Pick<ReadWith<R, P[number]>, Extract<keyof ReadWith<R, P[number]>, Sel[number]>> : ReadWith<R, P[number]>;
+type AdhocRecord<R extends Reading, P extends readonly string[], Sel, L, A> = A extends QueryAggregate ? Readonly<Record<string, unknown>> : ReadAs<R, P, Sel, L>;
 /**
  * `client.query`: callable two ways, beside the chained client it was before.
  *
@@ -2160,22 +2424,27 @@ type QueryCall<S extends AnySchemaDefinition | undefined> = AdhocQueryCall<S> &
 /** `client.query({ from, … })`. */
 type AdhocQueryCall<S extends AnySchemaDefinition | undefined> = {
     /**
-     * Run a query inline: `list`'s options plus `aggregate`, `params` and `fullText`. Answers the
-     * API's body, its `result` the entries — or the aggregate's rows.
+     * Run a query inline: `list`'s options plus `aggregate`, `params` and `fullText`. Answers a
+     * list's envelope, `{ data, page, meta }` — `data` the entries as `list` answers them, or the
+     * aggregate's rows, `page` the cursor page and `meta` how the query ran.
+     *
+     * Page it by the `cursor` an answer's `page.nextCursor` hands back, as a list is paged; `locale`
+     * is a code, a list of codes or `'*'`, and `select` sits beside `include`.
      *
      * @example
      * ```typescript
-     * const { data } = await relyio.query({
+     * const { data, page } = await relyio.query({
      *   from: 'post',
      *   where: { views: { $gte: 100 } },
      *   select: ['title', 'views'],
+     *   include: ['author(name)'],
      *   sort: { views: 'desc' },
      *   limit: 10,
-     *   page: 2,
      * })
+     * const next = page.nextCursor && (await relyio.query({ from: 'post', limit: 10, cursor: page.nextCursor }))
      * ```
      */
-    run<K extends QueryTypeName<S>, const P extends readonly string[] = [], const Sel extends readonly FieldKey<EntryOf<S, K>>[] | undefined = undefined, const A extends QueryAggregate | undefined = undefined>(query: AdhocQuery<K, EntryOf<S, K>, ReadingOf<S, K>, P, Sel, A>): Promise<QueryAnswer<AdhocRecord<ReadingOf<S, K>, P, Sel, A>[]>>;
+    run<K extends QueryTypeName<S>, const P extends readonly string[] = [], const Sel extends readonly FieldKey<EntryOf<S, K>>[] | undefined = undefined, const L extends LocaleOption<ReadLocale<ReadingOf<S, K>>> | undefined = undefined, const A extends QueryAggregate | undefined = undefined>(query: AdhocQuery<K, EntryOf<S, K>, ReadingOf<S, K>, P, Sel, L, A>): Promise<AdhocAnswer<AdhocRecord<ReadingOf<S, K>, P, Sel, L, A>>>;
 }['run'];
 /** `client.query(name, { params, … })`. */
 type NamedQueryCall<S extends AnySchemaDefinition | undefined> = {
@@ -2299,9 +2568,10 @@ type FeedChange = Change & {
 };
 /**
  * Why a cursor could no longer be replayed, or why everything must be refetched. `/v1/changes`
- * names `retention` and `dataset-replaced`; the live edge's `feed.resync` may name any reason its
- * wire declares (`VisitorResyncReason` in `@relyio/api-contract`, read from there rather than
- * restated). `unknown` when the message named none.
+ * names `retention` and `dataset-replaced` as its refusal's `details.reason`; the live edge's
+ * `feed.resync` may name any reason its wire declares (`VisitorResyncReason` in
+ * `@relyio/api-contract`, read from there rather than restated). `unknown` when the error named
+ * none of them.
  */
 type ChangesExpiredReason = VisitorResyncReason | 'unknown';
 /**
@@ -2309,9 +2579,11 @@ type ChangesExpiredReason = VisitorResyncReason | 'unknown';
  * ledger can no longer replay from (`INV-SS-CURSOR-REPLAYS`). The consumer
  * resyncs from the read path and starts again without a cursor.
  *
- * A `ResourceExpiredError`, so code that already catches that still does. The
- * refusal declares no details, so `reason` is read from the message the api
- * writes (`apps/services/api/src/changes/changes-request.ts` `refusalOf`).
+ * A `ResourceExpiredError`, so code that already catches that still does.
+ * `reason` is the refusal's `details.reason`, which the error mapper puts on
+ * `context.reason` (REL-3178) — never read from the message, which is English
+ * for a developer and names no reason. An error built by hand names its reason
+ * the same way, as `context.reason`.
  *
  * The live edge's `feed.resync` — a socket's frame or a poll's answer — is the
  * same instruction and arrives as the same error ({@link ChangesExpiredError.resync}),
@@ -2638,14 +2910,16 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
     /**
      * Run a query in one call (REL-2421, REL-2409 Q22):
      *
-     * - `query({ from, … })` runs one inline, with `list`'s option names — `where` (the query
-     *   route's dialect), `include`, `select`, `sort`, `limit`, `page`, `locale`, `dataset`, `fresh` —
-     *   plus `aggregate`, `params` and `fullText`;
+     * - `query({ from, … })` runs one inline, with `list`'s options — `where`, `include`, `select`
+     *   (beside `include`), `sort`, `limit`, `cursor`, `page`, `locale` (a code, a list or `'*'`),
+     *   `dataset`, `fresh` — plus `aggregate`, `params` and `fullText`. It answers a list's envelope,
+     *   `{ data, page, meta }` (REL-2460);
      * - `query(name, { params, … })` runs the saved query the schema declares under `name`, its
-     *   `params` typed from that declaration.
+     *   `params` typed from that declaration. It answers the API's body,
+     *   `{ data: { result, metadata } }`.
      *
-     * Both answer the API's body, `{ data: { result, metadata } }`. See {@link QueryCall}. Every query
-     * is sent in the client's locale as it is then, unless it names its own.
+     * See {@link QueryCall}. Every query is sent in the client's locale as it is then, unless it names
+     * its own.
      */
     get query(): QueryCall<TSchema>;
     /**
@@ -2921,9 +3195,9 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * - an option you name replaces the value the client holds;
      * - an option left out, or given as `undefined`, keeps the value the client holds;
      * - an option with no default given as `null` is cleared — `locale`, `dataset`, `apiKey`, `dev`,
-     *   `fetch`, `browser.onCorsError`, `realtime.wsUrl`, `debug.logger` — so the client runs as though
+     *   `fetch`, `browser.onCorsError`, `debug.logger` — so the client runs as though
      *   it had never been given one. An option with a default takes no `null`;
-     * - a bag of options you name — `browser`, `cache`, `realtime`, `debug` — keeps every field of it
+     * - a bag of options you name — `browser`, `cache`, `debug` — keeps every field of it
      *   you do not name, so `updateConfig({ browser: { includeCredentials: true } })` keeps a
      *   configured `onCorsError`;
      * - `headers` is laid over the headers the client sends, a name matched without regard to case: a
@@ -3087,4 +3361,4 @@ declare function createClient<TSchema extends AnySchemaDefinition>(config: Typed
  */
 type ClientSchema<T extends TypedRelyIOClient<AnySchemaDefinition>> = T extends TypedRelyIOClient<infer TSchema> ? TSchema : never;
 
-export { type ListAllOptions as $, type AnySchemaDefinition as A, type EntryWriteOptions as B, type Change as C, type DeployedLocale as D, type EntryPlacement as E, type FeedChange as F, SingletonClient as G, type Health as H, SettingsClient as I, type DocumentFields as J, type DocumentVersion as K, type LocaleCodeOf as L, type MatchRouteOptions as M, type DocumentVersionsOptions as N, type DocumentWriteOptions as O, type Project as P, type ChildrenOptions as Q, type Register as R, type SandboxState as S, TypedRelyIOClient as T, type ChildrenListOptions as U, type DocumentReadOptions as V, type Wire as W, type EntryList as X, type FieldKey as Y, type FreshOption as Z, type GetOptions as _, ChangesExpiredError as a, type PopulatedAssetReference as a$, type ListOptions as a0, type LocaleOption as a1, type Paging as a2, type ReadAs as a3, type ReadLocale as a4, type SortOption as a5, type VersionOptions as a6, type WrittenReadScope as a7, type WrittenSort as a8, type SearchResultItem as a9, type BatchUpdate as aA, type BatchReplace as aB, type BatchDelete as aC, type BatchSingletonWrite as aD, type BatchTarget as aE, type BatchDeleteTarget as aF, type AggregateMetric as aG, type QueryMetadata as aH, type AdhocQuery as aI, type AdhocRecord as aJ, type NamedQueryOptions as aK, type NamedQueryParams as aL, type QueryAggregate as aM, type QueryAnswer as aN, type QueryCall as aO, type QueryName as aP, type QueryTypeName as aQ, AssetClient as aR, AssetFileBuilder as aS, AssetUploadBuilder as aT, isAssetEntry as aU, type AssetVisibility as aV, type FileStatus as aW, type FileBackend as aX, type AssetFileExtracted as aY, type FileStatusResult as aZ, type AssetEntryResponse as a_, type SearchHitMetadata as aa, type SearchResponse as ab, type AutocompleteSuggestion as ac, type AutocompleteResponse as ad, type SimilarResult as ae, type SimilarResponse as af, type SearchTypeName as ag, type SearchEntry as ah, type AutocompleteOptions as ai, type SearchFacet as aj, type SearchFieldKey as ak, type SearchHighlight as al, type SearchOptions as am, type SearchPage as an, type SearchScope as ao, type SearchSelected as ap, type SearchSortOption as aq, type SearchWhere as ar, type SimilarOptions as as, type BatchOperationResult as at, type BatchSummary as au, type BatchResponse as av, type BatchWrite as aw, type BatchWriteOptions as ax, type BatchBody as ay, type BatchCreate as az, type ChangesExpiredReason as b, type PresignInput as b0, type PresignResult as b1, type ConfirmInput as b2, type ConfirmResult as b3, type ResolveUrlInput as b4, type ResolveUrlResult as b5, type CreateAssetOptions as b6, type AssetPlacement as b7, type UpdateAssetOptions as b8, type WaitUntilReadyOptions as b9, type MultipartCreateResult as ba, type MultipartPart as bb, type MultipartTarget as bc, type UploadProgress as bd, ResourceNotFoundError as be, ResourceConflictError as bf, ResourceExpiredError as bg, isResourceNotFound as bh, isMissingEntry as bi, type FileErrorCode as bj, type FileUploadErrorCode as bk, FileUploadError as bl, FileValidationError as bm, type FileValidationConstraints as bn, validateFile as bo, createClient as c, type TypedClientConfig as d, type ClientDefaults as e, type ClientSchema as f, type DeployedContentType as g, type RegisteredSchema as h, type ActiveSandbox as i, HttpClient as j, type SendOptions as k, type ApiPath as l, type ApiMethod as m, type ApiSuccessBody as n, matchRoute as o, type RouteMatch as p, type ReadEntry as q, type RetryableWriteOptions as r, type ChangesHeadOptions as s, type ChangesOptions as t, LIVE_KEEPALIVE_INTERVAL_MS as u, versionCheckOf as v, LIVE_SOCKET_OPEN_TIMEOUT_MS as w, type LiveChangesOptions as x, ContentClient as y, type CreateEntryOptions as z };
+export { type ChildrenOptions as $, type AnySchemaDefinition as A, LIVE_KEEPALIVE_INTERVAL_MS as B, type Change as C, type DeployedLocale as D, LIVE_SOCKET_OPEN_TIMEOUT_MS as E, type FeedChange as F, type LiveChangesOptions as G, type Health as H, ContentClient as I, type CreateEntryOptions as J, type EntryPlacement as K, type LocaleCodeOf as L, type MatchRouteOptions as M, type EntryWriteOptions as N, SingletonClient as O, type Project as P, SettingsClient as Q, type Register as R, type SandboxState as S, TypedRelyIOClient as T, type DocumentFields as U, type VisitorRetry as V, type Wire as W, type DocumentVersion as X, type DocumentVersionRow as Y, type DocumentVersionsOptions as Z, type DocumentWriteOptions as _, ChangesExpiredError as a, AssetClient as a$, type ChildrenListOptions as a0, type DocumentReadOptions as a1, type EntryList as a2, type FieldKey as a3, type FreshOption as a4, type GetOptions as a5, type ListAllOptions as a6, type ListOptions as a7, type LocaleOption as a8, type Paging as a9, type SearchSortOption as aA, type SearchWhere as aB, type SimilarOptions as aC, type BatchOperationResult as aD, type BatchSummary as aE, type BatchResponse as aF, type BatchWrite as aG, type BatchWriteOptions as aH, type BatchBody as aI, type BatchCreate as aJ, type BatchUpdate as aK, type BatchReplace as aL, type BatchDelete as aM, type BatchSingletonWrite as aN, type BatchTarget as aO, type BatchDeleteTarget as aP, type AggregateMetric as aQ, type QueryMetadata as aR, type AdhocQuery as aS, type AdhocRecord as aT, type NamedQueryOptions as aU, type NamedQueryParams as aV, type QueryAggregate as aW, type QueryAnswer as aX, type QueryCall as aY, type QueryName as aZ, type QueryTypeName as a_, type ChildEntry as aa, type ChildrenRead as ab, type ReadAs as ac, type WithChildren as ad, type ReadLocale as ae, type SortOption as af, type VersionOptions as ag, type WrittenReadScope as ah, type WrittenSort as ai, type SearchResultItem as aj, type SearchHitMetadata as ak, type SearchResponse as al, type AutocompleteSuggestion as am, type AutocompleteResponse as an, type SimilarResult as ao, type SimilarResponse as ap, type SearchTypeName as aq, type SearchEntry as ar, type AutocompleteOptions as as, type SearchFacet as at, type SearchFieldKey as au, type SearchHighlight as av, type SearchOptions as aw, type SearchPage as ax, type SearchScope as ay, type SearchSelected as az, type ChangesExpiredReason as b, AssetFileBuilder as b0, AssetUploadBuilder as b1, isAssetEntry as b2, type AssetVisibility as b3, type FileStatus as b4, type FileBackend as b5, type AssetFileExtracted as b6, type FileStatusResult as b7, type AssetEntryResponse as b8, type AssetFileWhere as b9, type PopulatedAssetReference as ba, type PresignInput as bb, type PresignResult as bc, type ConfirmInput as bd, type ConfirmResult as be, type ResolveUrlInput as bf, type ResolveUrlResult as bg, type CreateAssetOptions as bh, type AssetPlacement as bi, type UpdateAssetOptions as bj, type WaitUntilReadyOptions as bk, type MultipartCreateResult as bl, type MultipartPart as bm, type MultipartTarget as bn, type UploadProgress as bo, ResourceNotFoundError as bp, ResourceConflictError as bq, ResourceExpiredError as br, isResourceNotFound as bs, isMissingEntry as bt, type FileErrorCode as bu, type FileUploadErrorCode as bv, FileUploadError as bw, FileValidationError as bx, type FileValidationConstraints as by, validateFile as bz, createClient as c, type TypedClientConfig as d, type ClientDefaults as e, type ClientSchema as f, type DeployedContentType as g, type RegisteredSchema as h, type ActiveSandbox as i, HttpClient as j, type SendOptions as k, type ApiPath as l, type ApiMethod as m, type ApiSuccessBody as n, matchRoute as o, type RouteMatch as p, type ReadEntry as q, type RetryableWriteOptions as r, DefaultRetryPolicy as s, isReplaySafe as t, retryPolicyFor as u, versionCheckOf as v, type RetryPolicy as w, type RetryableRequest as x, type ChangesHeadOptions as y, type ChangesOptions as z };