@uniweb/runtime 0.17.1 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -36,7 +36,7 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "^0.23.0",
+    "@uniweb/core": "^0.24.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.40.0"
+    "@uniweb/build": "0.41.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/collect-records.js

@@ -12,11 +12,22 @@
  *
  * ⇒ 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).
+ * page render uses**, applying each saved query's own `scope` and `where` — and
+ * asks through the same client.
+ *
+ * ## ⛔ `limit` IS DROPPED, and it is the one place a corpus must diverge
+ *
+ * A saved query's `limit` is the LIST PAGE's presentation: `limit: 20` means the
+ * page shows twenty. **Its detail pages still exist for every record matching
+ * `scope` + `where`** — so a corpus that honoured `limit` would index twenty and
+ * miss every page beyond them, which is worse than indexing nothing because the
+ * gap is invisible.
+ *
+ * ⚠️ **This shipped wrong in 0.17.0 and was found by the consumer, not by us**
+ * (2026-09-06): the config was passed through unchanged, `limit` crossed as the
+ * question's own, and the corpus was capped. The claim that this surface met
+ * "the population its detail pages can reach" was made *"read charitably"* — a
+ * phrase doing work that one `sed` would have done better.
  *
  * ## What the caller supplies
  *
@@ -46,13 +57,29 @@ import { createDefaultFetcher } from './default-fetcher.js'
  * @param {Function} options.fetch - the transport, `(url, init) => Response`
  * @param {AbortSignal} [options.signal]
  * @param {string[]} [options.only] - restrict to these query names
+ * @param {'brief'|'full'} [options.depth='brief'] - what to ask for. `brief` is
+ *   what a list shows; **`full` is what an index wants** — a brief index cannot
+ *   match body text the record's own detail page displays, and a reader who
+ *   finds a word on the page and not in search meets the inconsistency two
+ *   rankings would produce. The cost is the caller's and is bounded by `maxPages`.
+ * @param {number} [options.maxPages] - the caller's own bound on the walk. The
+ *   default is a bound, not a target; a caller that knows its per-request budget
+ *   passes its own.
  * @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.
+ *   same and is null when nothing failed; `meta[name]` carries
+ *   `{ depth, pages, partial?, bound? }`.
+ *
+ *   ⭐ **`partial` means NOT THE WHOLE POPULATION**, and a key can be in BOTH
+ *   `records` and `errors`: a walk that failed or was aborted with pages already
+ *   in hand keeps them, marked. ⛔ Losing them would be indistinguishable from
+ *   "this query has no records", and on an abort every in-flight key fails at
+ *   once — so discarding would lose the corpus, not a key.
  */
-export async function collectSiteRecords(content, { locale, fetch, signal, only = null } = {}) {
+export async function collectSiteRecords(
+  content,
+  { locale, fetch, signal, only = null, whole = false, maxPages } = {},
+) {
   const config = content?.config
   const services = config?.services ?? null
   const queries = config?.queries ?? null
@@ -82,12 +109,18 @@ export async function collectSiteRecords(content, { locale, fetch, signal, only
     // `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 : []
+    // `limit` is the list page's, never the corpus's — see the header.
+    const { limit, ...population } = cfg
+    const asked = { ...population, whole, exhaustive: true }
+    if (typeof maxPages === 'number' && maxPages > 0) asked.maxPages = maxPages
+
+    const result = await fetcher.resolve(asked, { signal })
+    if (result?.error) errors[name] = result.error
+    // ⭐ Data and an error are not exclusive: a partial walk reports both, and
+    // the caller decides whether partial is usable. Only a walk that collected
+    // nothing leaves the key out of `records` entirely.
+    if (Array.isArray(result?.data)) records[name] = result.data
+    else if (!result?.error) records[name] = []
     if (result?.meta) meta[name] = result.meta
   }))
 

package/src/default-fetcher.js

@@ -230,12 +230,13 @@ export function createDefaultFetcher({ basePath = '', dev = false, fetch: fetchI
         // it returned.
         data = applyOperators(data, request, { dev })
 
-        // ⭐ 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
+        // ⭐ Say whether WHOLE records were delivered, so the record index can
+        // file them — what the config asked for, echoed: briefs when the query
+        // has a per-record source, whole records otherwise. (The service reports
+        // `whole` 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 ?? [] }
+        const whole = typeof request.whole === 'boolean' ? request.whole : undefined
+        return whole === undefined ? { data: data ?? [] } : { data: data ?? [], meta: { whole } }
       } catch (error) {
         if (error?.name === 'AbortError') {
           return { data: [], error: 'aborted' }
@@ -270,12 +271,16 @@ function toQuestion(request) {
   const sort = sortToWire(request.sort)
   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
+  // ⛔ ONLY WHEN TRUE. The brief is the default and absent means the brief, so
+  // sending `whole: false` would be noise on every list question the client makes.
+  if (request.whole === true) q.whole = true
   // ⭐ `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
+  // ⛔ `maxPages` does not cross either, for the same reason `exhaustive` does not:
+  // both say how many times to ask, never what is being asked.
   return q
 }
 
@@ -310,7 +315,7 @@ function renameOperators(where) {
  *
  * Two behaviours, deliberately not one:
  *
- *   - **a page render REPORTS** — `meta.truncated` and `meta.bound` ride the
+ *   - **a page render REPORTS** — `meta.partial` 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.
@@ -320,8 +325,16 @@ function renameOperators(where) {
  *     a service that always answers with a cursor cannot spin.
  */
 
-/** Pages an exhaustive request will follow before giving up and reporting truncation. */
-const MAX_PAGES = 50
+/**
+ * Pages an exhaustive request follows before stopping and reporting the answer
+ * as partial. A caller sets its own with `request.maxPages`.
+ *
+ * ⚖️ **20 is a bound, not a target** — it is the value a real caller chose for a
+ * real per-request budget (a search index, 20 × 100), taken as the default
+ * because any bound prevents a runaway and a low one fails visibly rather than
+ * expensively. A caller that knows its budget passes its own.
+ */
+const DEFAULT_MAX_PAGES = 20
 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.
@@ -362,24 +375,42 @@ async function flushAsked(url, queue, doFetch) {
     parsed = await response.json()
   } catch (error) {
     const message = error?.name === 'AbortError' ? 'aborted' : (error?.message || String(error))
-    for (const entry of queue) entry.resolve({ data: null, error: message })
+    // ⛔ AN ABORT KEEPS WHAT ARRIVED. On an exhaustive walk every in-flight key
+    // fails at once here, so discarding held pages loses the whole corpus rather
+    // than one key — the "rejection that loses every key" a caller cannot have.
+    for (const entry of queue) {
+      const held = Array.isArray(entry.collected) && entry.collected.length ? entry.collected : null
+      entry.resolve(held
+        ? { data: held, error: message, meta: withMeta({ partial: true, pages: entry.page }) }
+        : { data: null, error: message })
+    }
     return
   }
   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 : {}
+  // ⭐ `whole[key]` is present only for keys delivered as WHOLE entities — so a
+  // key's ABSENCE is the brief, and a key present that never asked is the
+  // brief-less Model saying so. Absent entirely when every key is briefs.
+  const wholes = parsed && typeof parsed.whole === 'object' && parsed.whole ? parsed.whole : {}
   // 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]
+    // ⛔ A FAILURE MUST NOT DISCARD PAGES ALREADY COLLECTED. An exhaustive walk
+    // that fails on page 7 has six pages in hand, and a caller that asked for a
+    // corpus would rather have them marked partial than lose the key — losing it
+    // is indistinguishable from "this query has no records".
+    const held = Array.isArray(entry.collected) && entry.collected.length ? entry.collected : null
     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]
       const detail = typeof e === 'string' ? e : (e?.detail || e?.message || JSON.stringify(e))
-      const out = { data: null, error: detail }
+      const out = held
+        ? { data: held, error: detail, meta: withMeta({ partial: true, pages: entry.page }) }
+        : { data: null, error: detail }
       if (e && typeof e === 'object' && typeof e.code === 'string') out.code = e.code
       entry.resolve(out)
       return
@@ -388,9 +419,9 @@ async function flushAsked(url, queue, doFetch) {
       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)
+    const whole = typeof wholes[key] === 'boolean'
+      ? wholes[key]
+      : (typeof entry.request.whole === 'boolean' ? entry.request.whole : undefined)
 
     const cursor = typeof cursors[key] === 'string' && cursors[key] ? cursors[key] : null
     const bound = typeof limits[key] === 'number' ? limits[key] : undefined
@@ -400,23 +431,36 @@ async function flushAsked(url, queue, doFetch) {
     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 })
+      const cap = typeof entry.request.maxPages === 'number' && entry.request.maxPages > 0
+        ? entry.request.maxPages
+        : DEFAULT_MAX_PAGES
+      if (page <= cap) {
+        pending.set(entry, { cursor, collected: acc, page, whole, 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 }) })
+      // The caller's own bound, not the service's: report rather than spin.
+      entry.resolve({ data: acc, meta: withMeta({ whole, bound, partial: true, pages: cap }) })
       return
     }
 
     const collected = entry.collected ? entry.collected.concat(Array.isArray(rows) ? rows : []) : rows
     const meta = withMeta({
-      depth,
+      whole,
       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,
+      // ⭐ ONE FLAG, MEANING **NOT THE WHOLE POPULATION** — asked for by name, so
+      // a caller has one boolean to branch on rather than three signals to
+      // combine. It is set in every case that means it:
+      //   · a cursor came back and this caller does not page (a page render);
+      //   · a cursor came back and the caller's `maxPages` stopped the walk;
+      //   · the walk failed or aborted with pages already in hand;
+      //   · the service reported it BOUNDED the answer and offered no cursor.
+      // ⚠️ The last is why `limits` is read at all: a cursor is the signal for a
+      // query that declared no `limit`, and `limits` is the signal for one whose
+      // author limit was clamped (the records contract §5). Neither alone covers
+      // both. ⛔ Named `truncated` when it shipped in 0.17.0 this morning; renamed
+      // the same day, before any consumer adopted it, because "truncated" says
+      // something was cut and this also means "there is more you did not ask for".
+      partial: (cursor || bound !== undefined) ? true : undefined,
       pages: entry.page && entry.page > 1 ? entry.page : undefined,
     })
     entry.resolve(meta ? { data: collected, meta } : { data: collected })