@uniweb/runtime 0.15.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -36,7 +36,7 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "^0.20.0",
+    "@uniweb/core": "^0.22.0",
     "@uniweb/theming": "^0.1.15"
   },
   "devDependencies": {
@@ -44,7 +44,7 @@
     "esbuild": "^0.21.0 || ^0.23.0 || ^0.24.0 || ^0.25.0 || ^0.27.0",
     "vite": "^7.3.1",
     "vitest": "^4.1.7",
-    "@uniweb/build": "0.37.1"
+    "@uniweb/build": "0.39.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/collect-records.js

@@ -0,0 +1,99 @@
+/**
+ * Every record a site's declared queries return — for a host building something
+ * over the whole corpus rather than rendering one page.
+ *
+ * ## Why this is framework's and not the caller's
+ *
+ * A host that indexes a site has to ask the same questions the site's pages ask.
+ * ⛔ **If it composes its own, the index and the page can disagree**, and the way
+ * they disagree is the worst one available: the index offers a result whose page
+ * then renders empty. That is the two-answers-to-one-question failure the GET
+ * lane was retired for, reintroduced one lane over.
+ *
+ * ⇒ So the composition is not duplicated here either. This walks the site's
+ * `config.queries`, hands each one to `resolveFetchConfigs` — **the same rule a
+ * page render uses**, applying each saved query's own `scope` / `where` / `sort`
+ * / `limit` — and asks through the same client. What differs from a page is two
+ * fields and nothing else: `depth: 'brief'` (an index wants what a list shows)
+ * and `exhaustive: true` (a corpus is not a page, so it follows `cursors` to the
+ * end; the records contract bounds a single answer at 100).
+ *
+ * ## What the caller supplies
+ *
+ * ⭐ **The transport, and nothing else.** A host outside a browser decides how a
+ * site-relative address is dispatched — through its own origin, a service
+ * binding, a forwarding table that turns `/_…` into an upstream — and hands that
+ * in as `fetch`. **Framework decides what to ask and how to read the answer;
+ * the host decides how the bytes travel.** That split is the whole of the
+ * boundary here.
+ *
+ * ⛔ **A site with no records service is not an error.** It has no live records,
+ * so this returns empty rather than throwing: a static site's corpus comes from
+ * its own compiled artifacts, which the caller already has.
+ */
+
+import { resolveFetchConfigs } from '@uniweb/core/fetch-config'
+import { resolveRecordsService } from '@uniweb/core/records-service'
+import { createDefaultFetcher } from './default-fetcher.js'
+
+/**
+ * Ask a site's records service for every record its declared queries return.
+ *
+ * @param {Object} content - the render payload (`config.services`, `config.queries`)
+ * @param {Object} options
+ * @param {string} options.locale - the locale to ask in; it is a route segment
+ *   of the service's address, so there is no asking without one
+ * @param {Function} options.fetch - the transport, `(url, init) => Response`
+ * @param {AbortSignal} [options.signal]
+ * @param {string[]} [options.only] - restrict to these query names
+ * @returns {Promise<{records: Object, errors: Object|null, meta: Object}>}
+ *   `records` is keyed by query NAME, each a flat array; `errors` is keyed the
+ *   same and is null when nothing failed; `meta[name]` carries `{ depth, pages,
+ *   truncated? }` — `truncated` meaning the loop hit its own bound, never that
+ *   the site has more.
+ */
+export async function collectSiteRecords(content, { locale, fetch, signal, only = null } = {}) {
+  const config = content?.config
+  const services = config?.services ?? null
+  const queries = config?.queries ?? null
+
+  // No service, no queries, or no locale to ask in ⇒ nothing to collect. Each is
+  // an ordinary state of a site, not a fault: the caller reads its own artifacts.
+  if (!queries || typeof queries !== 'object') return empty()
+  if (!resolveRecordsService(services, locale)) return empty()
+
+  const names = Object.keys(queries).filter((n) => (only ? only.includes(n) : true))
+  if (names.length === 0) return empty()
+
+  // One synthetic source per query — `as` is the query's own name, so the answer
+  // comes back under the name the caller asked by.
+  const configs = resolveFetchConfigs(
+    names.map((name) => ({ query: name, as: name })),
+    { services, queries, locale, defaultLocale: config?.defaultLanguage ?? locale },
+  )
+
+  const fetcher = createDefaultFetcher({ fetch, basePath: config?.base ?? '' })
+  const records = {}
+  const errors = {}
+  const meta = {}
+
+  await Promise.all([...configs].map(async ([name, cfg]) => {
+    // ⛔ Only a config the service answers. A query that resolved to a compiled
+    // `path` has no live lane, and reading that file is the caller's business,
+    // not ours — it is in the site's own URL space and they already serve it.
+    if (!cfg.ask) return
+    const result = await fetcher.resolve({ ...cfg, depth: 'brief', exhaustive: true }, { signal })
+    if (result?.error) {
+      errors[name] = result.error
+      return
+    }
+    records[name] = Array.isArray(result?.data) ? result.data : []
+    if (result?.meta) meta[name] = result.meta
+  }))
+
+  return { records, errors: Object.keys(errors).length ? errors : null, meta }
+}
+
+function empty() {
+  return { records: {}, errors: null, meta: {} }
+}

package/src/default-fetcher.js

@@ -6,22 +6,19 @@
  * starter/docs/marketing templates hitting /data/*.json — ride on this path
  * with zero config, and so does a site a host serves live.
  *
- * ⭐ It speaks exactly THREE lanes, and takes NO site-level vocabulary for a
+ * ⭐ It speaks exactly TWO lanes, and takes NO site-level vocabulary for a
  * backend of the author's own:
  *
  *   - a compiled file — `path:` under the site's base (`/data/<query>.json`,
  *     a per-record file), or a plain JSON `url:` the author wrote;
- *   - the host's ADDRESS DOOR — `endpoint:`, resolved upstream from the
- *     `config.records` stamp (`@uniweb/core/query-address`), unwrapped with
- *     the stamp's own `envelope.records`;
- *   - the host's QUESTION DOOR — `door:`, one POST per tick carrying every
- *     question the page asked, answered per key (the records door's contract,
- *     as this client reads it).
+ *   - the host's RECORDS SERVICE — `ask:`, one POST per tick carrying every
+ *     question the page asked, answered per key (the records contract, as this
+ *     client reads it).
  *
  * `where:` / `sort:` / `limit:` are evaluated HERE, locally, over what the
- * first two lanes return — with `@uniweb/core`'s one evaluator, the same the
- * build uses to materialize a file — and by the source on the third. Nothing
- * decides that per site: the LANE decides.
+ * first lane returns — with `@uniweb/core`'s one evaluator, the same the build
+ * uses to materialize a file — and at the source when asked. Nothing decides
+ * that per site: the LANE decides.
  *
  * ⛔ RETIRED 2026-09-04 [Diego]: `fetcher.baseUrl`, `headers`, `envelope`,
  * `supports`, `request.style` / `request.rename` and the `json-body`
@@ -67,9 +64,6 @@ import {
  *   for subpath deployments. Remote URLs pass through unchanged.
  * @param {boolean} [options.dev=false] - Dev-mode diagnostics: a bad `sort:`
  *   throws instead of delivering the records unsorted.
- * @param {Object|null} [options.records=null] - The host's `config.records`
- *   stamp; its `envelope.records` names the key a list sits under on the
- *   address door.
  * @param {Function|null} [options.fetch=null] - The transport. A host executing
  *   fetches outside a browser (an SSR isolate) decides how a site-relative
  *   address is dispatched — through its own origin or a service binding — and
@@ -77,51 +71,49 @@ import {
  *   test stub installed later is honoured.
  * @returns {{ cacheKey: (req: Object) => string, resolve: (req: Object, ctx: Object) => Promise<{ data, error?, meta? }> }}
  */
-export function createDefaultFetcher({ basePath = '', dev = false, records = null, fetch: fetchImpl = null } = {}) {
+export function createDefaultFetcher({ basePath = '', dev = false, fetch: fetchImpl = null } = {}) {
   const doFetch = (input, init) => (fetchImpl || globalThis.fetch)(input, init)
   const pathPrefix = basePath && basePath !== '/' ? basePath.replace(/\/$/, '') : ''
 
-  // ⭐ The LIVE LANE's envelope is the backend's. `config.records` is stamped by the backend
-  // that answers a records request, so where the array sits in ITS response is its to
-  // declare: `records.envelope.records` — the KEY says what it holds, the VALUE is the JSON
-  // key the array sits under (`{ records: "entries" }` ⇒ body.entries). That spelling is the
-  // agreed one (2026-08-30: `collection` retired; ⛔ not `list`, which is a URL pattern on the
-  // same stamp). It applies only to a request that resolved to that lane (`endpoint` set).
-  // Ruled 2026-09-03 [Diego]: the backend sets `config.records`; the fetch comes from the
-  // runtime.
-  const stampedArrayKey = (records?.envelope && typeof records.envelope === 'object'
-    && typeof records.envelope.records === 'string' && records.envelope.records.length)
-    ? records.envelope.records
-    : null
-  const laneEnvelope = stampedArrayKey ? { list: stampedArrayKey } : null
 
-  // ⭐ THE QUESTION DOOR — a batch of the misses, one POST, merged per key.
+  // ⭐ THE RECORDS SERVICE — a batch of the misses, one POST, merged per key.
   //
   // The entity store dispatches every config a page needs in one synchronous
-  // loop before awaiting any of them, so a door request enqueued here and
-  // flushed on the next microtask carries every miss of that page in one body
-  // The batch response is never cached as
-  // one: each request gets its own answer, keyed by its own question.
-  const doorQueues = new Map()
-  const askDoor = (request, ctx) =>
-    new Promise((resolve) => {
-      const url = resolveServiceUrl(request.door, pathPrefix)
-      let queue = doorQueues.get(url)
+  // loop before awaiting any of them, so a question enqueued here and flushed
+  // on the next microtask carries every miss of that page in one body. The
+  // batch response is never cached as one: each request gets its own answer,
+  // keyed by its own question.
+  const askQueues = new Map()
+  const askRecords = (request, ctx) => {
+    // ⛔ A question needs the query's Model ref. A payload that offers the
+    // service and carries no `config.queries` entry for the query cannot ask;
+    // that is a producer defect and it is said here, per key, with no request.
+    if (typeof request.schema !== 'string' || !request.schema) {
+      return Promise.resolve({
+        data: null,
+        error: `the payload offers the records service but carries no Model ref for query ` +
+          `"${request.query ?? request.as}" (config.queries) — it cannot be asked`,
+      })
+    }
+    return new Promise((resolve) => {
+      const url = resolveServiceUrl(request.ask, pathPrefix)
+      let queue = askQueues.get(url)
       if (!queue) {
         queue = []
-        doorQueues.set(url, queue)
+        askQueues.set(url, queue)
         queueMicrotask(() => {
-          doorQueues.delete(url)
-          flushDoor(url, queue, doFetch)
+          askQueues.delete(url)
+          flushAsked(url, queue, doFetch)
         })
       }
       queue.push({ request, ctx, resolve })
     })
+  }
 
   return {
     /**
-     * The cache identity is the request's ADDRESS — or, on a question door,
-     * the QUESTION (`deriveCacheKey` hashes every operator of an address-less
+     * The cache identity is the request's ADDRESS — or, when asked of the
+     * records service, the QUESTION (`deriveCacheKey` hashes every operator of an address-less
      * request). Operators evaluated here run over a shared cached value and
      * must NOT split the cache: two pages declaring different `where:` clauses
      * against the same path share one entry — the file is fetched once and
@@ -133,8 +125,8 @@ export function createDefaultFetcher({ basePath = '', dev = false, records = nul
 
     async resolve(request, ctx = {}) {
       if (!request) return { data: null }
-      if (request.door) return askDoor(request, ctx)
-      const { path, url, endpoint, transform, body: rawBody } = request
+      if (request.ask) return askRecords(request, ctx)
+      const { path, url, transform, body: rawBody } = request
 
       // Normalize method. Only GET and POST are supported by the default
       // fetcher — mutations (PUT/PATCH/DELETE) are a different feature
@@ -146,24 +138,7 @@ export function createDefaultFetcher({ basePath = '', dev = false, records = nul
       }
 
       let target
-      if (endpoint) {
-        // The host's address door, resolved upstream from the pattern it
-        // published. FINAL ON ARRIVAL: the site `base` is applied to a rooted
-        // address — the same rule every other site-relative address follows,
-        // shared with `resolveServiceUrl` rather than spelled a second time —
-        // and nothing else is joined onto it. A pattern may carry a site id,
-        // its own root, any layout at all; none of it is ours.
-        target = resolveServiceUrl(endpoint, pathPrefix)
-        // ⭐ The locale rides as a query param on the address door — the config
-        // carries one only on a non-default-locale live request (F1). Until
-        // 2026-09-04 nothing put it on the wire, so localized fields arrived as
-        // `{lang: …}` maps; hosting confirmed that day that an appended `?locale=`
-        // passes through their reshape verbatim, on both the browser and the
-        // isolate path, and backend answers it with the locale's strings.
-        if (typeof request.locale === 'string' && request.locale) {
-          target += (target.includes('?') ? '&' : '?') + 'locale=' + encodeURIComponent(request.locale)
-        }
-      } else if (path) {
+      if (path) {
         // Local file under public/ — basePath applies for subpath deploys.
         target = pathPrefix && path.startsWith('/') && !path.startsWith('//')
           ? pathPrefix + path
@@ -172,7 +147,7 @@ export function createDefaultFetcher({ basePath = '', dev = false, records = nul
         // A URL the author wrote, sent exactly as written.
         target = url
       } else {
-        return { data: [], error: 'No path, url or endpoint specified' }
+        return { data: [], error: 'No path, url or ask specified' }
       }
 
       const init = { signal: ctx.signal, method }
@@ -196,11 +171,10 @@ export function createDefaultFetcher({ basePath = '', dev = false, records = nul
         const response = await doFetch(target, init)
 
         // A per-request envelope (set by the object form of `detail:`) describes
-        // this one response; on the address door the stamp describes the lane.
-        const requestEnvelope = (request.envelope && typeof request.envelope === 'object')
+        // this one response.
+        const envelope = (request.envelope && typeof request.envelope === 'object')
           ? request.envelope
-          : null
-        const envelope = requestEnvelope ?? (endpoint && laneEnvelope ? laneEnvelope : {})
+          : {}
 
         if (!response.ok) {
           // If `envelope.error` names a path, try to extract a human message
@@ -256,11 +230,10 @@ export function createDefaultFetcher({ basePath = '', dev = false, records = nul
         // it returned.
         data = applyOperators(data, request, { dev })
 
-        // ⭐ Say what depth was delivered, so the record index can file it. On
-        // the address door that is what the config asked for — a list at brief
-        // depth when the query has a per-record source, a record in full — so
-        // the config's `depth` is echoed. A door that reports `depths` per key
-        // will override this with what it actually served.
+        // ⭐ Say what depth was delivered, so the record index can file it — what
+        // the config asked for, echoed: a list at brief depth when the query has
+        // a per-record source, a record in full. (The service reports `depths` per
+        // key and overrides this with what it actually served.)
         const depth = request.depth === 'brief' || request.depth === 'full' ? request.depth : undefined
         return depth ? { data: data ?? [], meta: { depth } } : { data: data ?? [] }
       } catch (error) {
@@ -274,16 +247,16 @@ export function createDefaultFetcher({ basePath = '', dev = false, records = nul
 }
 
 /**
- * One question of a door batch, in the door's own vocabulary
- * (the records door's contract, §2): `schema` required, `scope` a bare
- * path, `sort` one key spelled `date` / `-date`, `depth` brief or full. The
- * where-object crosses as authored except for the two spellings the language
- * settled differently from the evaluator's: `nin` is `not_in` there, and a
- * top-level `path: { under }` — the file lane's way of naming a folder branch —
- * is the door's `scope`. Anything the door does not accept (`like`, a dotted
- * path) is sent as written and refused there by name: loud, never approximated.
+ * One question of a batch, in the records service's own vocabulary
+ * (the records contract, §2): `schema` required, `scope` a bare path, `sort`
+ * one key spelled `date` / `-date`, `depth` brief or full. The where-object
+ * crosses as authored except for the two spellings the language settled
+ * differently from the evaluator's: `nin` is `not_in` there, and a top-level
+ * `path: { under }` — the file lane's way of naming a folder branch — is
+ * `scope`. Anything the service does not accept (`like`, a dotted path) is
+ * sent as written and refused there by name: loud, never approximated.
  */
-function doorQuestion(request) {
+function toQuestion(request) {
   const q = { schema: request.schema }
   let where = request.where && typeof request.where === 'object' ? request.where : null
   let scope = typeof request.scope === 'string' && request.scope ? request.scope : null
@@ -298,31 +271,61 @@ function doorQuestion(request) {
   if (sort) q.sort = sort
   if (typeof request.limit === 'number' && request.limit > 0) q.limit = request.limit
   if (request.depth === 'brief' || request.depth === 'full') q.depth = request.depth
+  // ⭐ `cursor` is the ONLY field here that is not the author's: it is opaque and
+  // it comes from a previous answer's `cursors` (the records contract §2). ⛔ And
+  // `exhaustive` deliberately does NOT cross — it is a client instruction about
+  // how many times to ask, not part of the question being asked.
+  if (typeof request.cursor === 'string' && request.cursor) q.cursor = request.cursor
   return q
 }
 
-const DOOR_OPERATOR = { nin: 'not_in' }
+const OPERATOR_ALIAS = { nin: 'not_in' }
 function renameOperators(where) {
   if (Array.isArray(where)) return where.map(renameOperators)
   if (!where || typeof where !== 'object') return where
   const out = {}
   for (const [key, value] of Object.entries(where)) {
-    out[DOOR_OPERATOR[key] ?? key] = value && typeof value === 'object' ? renameOperators(value) : value
+    out[OPERATOR_ALIAS[key] ?? key] = value && typeof value === 'object' ? renameOperators(value) : value
   }
   return out
 }
 
 /**
- * Send one batch to a door and hand each question its own answer.
+ * Send one batch to the records service and hand each question its own answer.
+ *
+ * The response is `{ data, depths?, errors?, cursors?, limits? }` (contract §5):
+ * `data` answers exactly the keys sent, `[]` when nothing matched; a key that
+ * ERRORED is absent from `data` and present in `errors`; `depths` says what was
+ * actually served, which the record index files rather than what was asked for.
+ * A key missing from both is a protocol violation and is reported as an error,
+ * never as silence.
+ *
+ * ⭐ `cursors` AND `limits` ARE READ — 2026-09-06 [Diego], reversing the ruling
+ * that had them "received and IGNORED, because framework has no paging concept."
+ * ⛔ **That ruling described our client and was silently wrong about our USERS:**
+ * the service bounds every answer at 100 (the records contract §4.2/§5), and a
+ * `cursors` entry is how it says there is more. Discarding both meant a hosted
+ * list of 500 rendered 100 — no error, no warning, no way for an author to tell
+ * a bound from the end of the data. **The silent class, on a visitor's page.**
  *
- * The response is `{ data, depths?, errors? }` (contract §5): `data` answers
- * exactly the keys sent, `[]` when nothing matched; a key that ERRORED is absent
- * from `data` and present in `errors`; `depths` says what was actually served,
- * which the record index files rather than what was asked for. A key missing
- * from both is a protocol violation and is reported as an error, never as
- * silence.
+ * Two behaviours, deliberately not one:
+ *
+ *   - **a page render REPORTS** — `meta.truncated` and `meta.bound` ride the
+ *     answer, and nothing pages automatically. Auto-paging here would put
+ *     unbounded round trips in front of paint for a section that may only show
+ *     ten rows.
+ *   - **an exhaustive caller PAGES** — `request.exhaustive` follows `cursors`
+ *     until the service stops issuing them. `collectSiteRecords` is the caller
+ *     that wants it (a corpus is not a page), and `maxPages` bounds the loop so
+ *     a service that always answers with a cursor cannot spin.
  */
-async function flushDoor(url, queue, doFetch) {
+
+/** Pages an exhaustive request will follow before giving up and reporting truncation. */
+const MAX_PAGES = 50
+async function flushAsked(url, queue, doFetch) {
+  // One shared page loop: the batch is sent, and any entry that asked to be
+  // exhaustive and came back with a cursor is re-sent alone until it is done.
+  const pending = new Map()
   const body = {}
   const keys = []
   for (const entry of queue) {
@@ -330,7 +333,7 @@ async function flushDoor(url, queue, doFetch) {
     let key = base
     for (let n = 2; key in body; n += 1) key = `${base}#${n}`
     keys.push(key)
-    body[key] = doorQuestion(entry.request)
+    body[key] = toQuestion(entry.request)
   }
   let parsed
   try {
@@ -340,7 +343,19 @@ async function flushDoor(url, queue, doFetch) {
       body: JSON.stringify(body),
     })
     if (!response.ok) {
-      const error = `HTTP ${response.status}: ${response.statusText}`
+      // A protocol violation is refused for the WHOLE request with a problem body
+      // whose `detail` names the key and the fault (an unknown operator, an empty
+      // binding key, a non-BCP-47 locale segment…). Surface that sentence on every
+      // key of the batch rather than the bare status: the author reads
+      // `block.dataError` and the status alone says nothing they can act on.
+      let detail = null
+      try {
+        const problem = safeParseJSON(await response.text())
+        if (problem && typeof problem.detail === 'string' && problem.detail) detail = problem.detail
+      } catch { /* an unreadable body falls back to the status line */ }
+      const error = detail
+        ? `HTTP ${response.status}: ${detail}`
+        : `HTTP ${response.status}: ${response.statusText}`
       for (const entry of queue) entry.resolve({ data: null, error })
       return
     }
@@ -353,22 +368,79 @@ async function flushDoor(url, queue, doFetch) {
   const data = parsed && typeof parsed.data === 'object' && parsed.data ? parsed.data : {}
   const errors = parsed && typeof parsed.errors === 'object' && parsed.errors ? parsed.errors : {}
   const depths = parsed && typeof parsed.depths === 'object' && parsed.depths ? parsed.depths : {}
+  // Both absent when empty, never `{}` (the records contract §5).
+  const cursors = parsed && typeof parsed.cursors === 'object' && parsed.cursors ? parsed.cursors : {}
+  const limits = parsed && typeof parsed.limits === 'object' && parsed.limits ? parsed.limits : {}
   queue.forEach((entry, i) => {
     const key = keys[i]
     if (key in errors) {
+      // A per-key error is `{ code, detail }` — `schema_not_found`,
+      // `field_not_in_brief`, `scope_not_found`… The sentence is `detail`; `code`
+      // rides beside it for a reader that wants to branch on it.
       const e = errors[key]
-      entry.resolve({ data: null, error: typeof e === 'string' ? e : (e?.message || JSON.stringify(e)) })
+      const detail = typeof e === 'string' ? e : (e?.detail || e?.message || JSON.stringify(e))
+      const out = { data: null, error: detail }
+      if (e && typeof e === 'object' && typeof e.code === 'string') out.code = e.code
+      entry.resolve(out)
       return
     }
     if (!(key in data)) {
-      entry.resolve({ data: null, error: `the records door answered without the key "${key}"` })
+      entry.resolve({ data: null, error: `the records service answered without the key "${key}"` })
       return
     }
     const depth = depths[key] === 'brief' || depths[key] === 'full'
       ? depths[key]
       : (entry.request.depth === 'brief' || entry.request.depth === 'full' ? entry.request.depth : undefined)
-    entry.resolve(depth ? { data: data[key], meta: { depth } } : { data: data[key] })
+
+    const cursor = typeof cursors[key] === 'string' && cursors[key] ? cursors[key] : null
+    const bound = typeof limits[key] === 'number' ? limits[key] : undefined
+    const rows = Array.isArray(data[key]) ? data[key] : data[key]
+
+    // An exhaustive caller collects the page and asks for the next one.
+    if (cursor && entry.request.exhaustive && Array.isArray(rows)) {
+      const acc = entry.collected ? entry.collected.concat(rows) : rows.slice()
+      const page = (entry.page || 1) + 1
+      if (page <= MAX_PAGES) {
+        pending.set(entry, { cursor, collected: acc, page, depth, bound })
+        return
+      }
+      // The loop's own bound, not the service's: report rather than spin.
+      entry.resolve({ data: acc, meta: withMeta({ depth, bound, truncated: true, pages: MAX_PAGES }) })
+      return
+    }
+
+    const collected = entry.collected ? entry.collected.concat(Array.isArray(rows) ? rows : []) : rows
+    const meta = withMeta({
+      depth,
+      bound,
+      // ⭐ A cursor IS the truncation signal, and it is the only one for a query
+      // that declared no `limit`: `limits` is reported only when an author's own
+      // limit was clamped (the records contract §5).
+      truncated: cursor ? true : undefined,
+      pages: entry.page && entry.page > 1 ? entry.page : undefined,
+    })
+    entry.resolve(meta ? { data: collected, meta } : { data: collected })
   })
+
+  if (pending.size === 0) return
+  // Re-ask each unfinished key on its own — the cursor is per key, so a batch
+  // would have to correlate several independent positions through one body.
+  await Promise.all([...pending].map(([entry, state]) => {
+    const next = {
+      ...entry,
+      request: { ...entry.request, cursor: state.cursor },
+      collected: state.collected,
+      page: state.page,
+    }
+    return flushAsked(url, [next], doFetch)
+  }))
+}
+
+/** Build a `meta` from the fields that are actually present, or `undefined`. */
+function withMeta(fields) {
+  const out = {}
+  for (const [k, v] of Object.entries(fields)) if (v !== undefined) out[k] = v
+  return Object.keys(out).length ? out : undefined
 }
 
 /**

package/src/isolate-api.js

@@ -17,7 +17,8 @@
  * ⛔ A floor is a promise about a VERSION, not a rename guard. A site on a newer
  * runtime with a renamed export is still a missing symbol; the test above is what
  * makes that fail before it ships, and the announcement to the consumer is still
- * ours to send (`framework/CLAUDE.md` § Decoupling is the architecture).
+ * ours to send, because a consumer that bundles this package by workspace link
+ * gets the change at commit time, with no version to pin against.
  *
  * ⛔ Not `runtime-pin.json`. That file is emitted per FOUNDATION build and records an
  * observed fact ("built against"), never a guarantee; an isolate-API floor is a
@@ -27,8 +28,46 @@
  * "since" is the first PUBLISHED version (git tag) whose `@uniweb/runtime/ssr`
  * exported the name — measured with `git log --reverse -S<name> -- src/ssr.js` and
  * `git tag --contains`, 2026-09-04.
+ *
+ * ## ⭐ `UNRELEASED` — and why the mechanism needed it
+ *
+ * ⛔ **This file had no way to stamp an export that has not shipped, and the gap
+ * was invisible because it was written retrospectively** (2026-09-04, at 0.14.2,
+ * stamping names that had all already published). The first genuinely new export
+ * hit it immediately: the test demands every export be stamped, a stamp must be
+ * `<=` package.json's version, and the version an export will ship in **does not
+ * exist until the publish that creates it** — versions are derived from commits
+ * at publish time and never hand-edited.
+ *
+ * ⚠️ **The tempting fix is the dangerous one.** Stamping the current version
+ * (`0.16.0`) would satisfy every check and be **false**: backend reads
+ * `isolateApiFloor` from the channel index and refuses to serve a site below it,
+ * so a floor of 0.16.0 would promise an export that 0.16.0 does not contain —
+ * and a host at the floor is entitled to skip feature detection. That is a
+ * guarantee broken in the one direction the floor exists to prevent.
+ *
+ * ⇒ **`UNRELEASED` says the true thing: this export exists in the tree and in no
+ * published version.** It is stamped like any other name, so nothing rides out
+ * unnoticed, and it is EXCLUDED from the floor — which therefore never promises
+ * more than a published artifact delivers. **The floor rises one step after the
+ * publish, not one step before it**, and the sequence is:
+ *
+ *   1. land the export stamped `UNRELEASED` — the floor does not move;
+ *   2. publish (Diego; agents never publish);
+ *   3. replace `UNRELEASED` with the version that publish produced — the floor
+ *      moves here, and the runtime channel's `isolateApiFloor` follows at the
+ *      next channel publish;
+ *   4. tell backend, which holds the number and must ratchet it.
+ *
+ * ⚖️ **Step 3 is a real obligation, not bookkeeping**: an export left
+ * `UNRELEASED` after it ships keeps the floor below its own API forever, so a
+ * host feature-detects something it could have relied on. The guard is the
+ * test's own message.
  */
 
+/** An export present in the tree and in no published version. Excluded from the floor. */
+export const UNRELEASED = 'UNRELEASED'
+
 /** Every export of `@uniweb/runtime/ssr`, with the version it first shipped in. */
 export const ISOLATE_API = Object.freeze({
   // props preparation
@@ -66,13 +105,22 @@ export const ISOLATE_API = Object.freeze({
   // the composed render entry
   createPageRenderer: '0.14.2',
   prefetchAndHydrate: '0.14.2',
+  // the whole corpus, for a host that indexes rather than renders
+  collectSiteRecords: UNRELEASED,
 })
 
 /**
  * The runtime version at or above which EVERY name in `ISOLATE_API` is exported —
  * the absolute floor a host may rely on with no feature detection.
  */
-export const ISOLATE_API_FLOOR = Object.values(ISOLATE_API).reduce((max, v) => (compareVersions(v, max) > 0 ? v : max), '0.0.0')
+export const ISOLATE_API_FLOOR = Object.values(ISOLATE_API)
+  .filter((v) => v !== UNRELEASED)
+  .reduce((max, v) => (compareVersions(v, max) > 0 ? v : max), '0.0.0')
+
+/** The exports that exist here and in no published version — empty is the steady state. */
+export const UNRELEASED_EXPORTS = Object.freeze(
+  Object.entries(ISOLATE_API).filter(([, v]) => v === UNRELEASED).map(([name]) => name),
+)
 
 /** Compare two `x.y.z` versions numerically. Returns <0, 0 or >0. */
 export function compareVersions(a, b) {

package/src/page-renderer.js

@@ -18,8 +18,8 @@
  *
  *   - **Shell assembly.** The shell arrives built. The import map, the CDN base and
  *     cache headers are host layout, and a runtime that assembled them would be
- *     modelling a deployment it cannot see (hosting drew this line themselves,
- *     2026-09-03; `framework/CLAUDE.md` § *Serve locations are read, never constructed*).
+ *     modelling a deployment it cannot see (the host drew this line itself,
+ *     2026-09-03: a serve location is read from the payload, never constructed here).
  *   - **Init and hydration.** The two lanes differ REALLY here, not incidentally: a
  *     build initializes once and hydrates every collection up front, an isolate
  *     initializes per locale and prefetches per route. Folding either in would fit