@uniweb/core 0.29.4 → 0.29.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.29.4",
+  "version": "0.29.5",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
@@ -13,6 +13,7 @@
     "./detail-url": "./src/detail-url.js",
     "./fetch-config": "./src/fetch-config.js",
     "./layout-name": "./src/layout-name.js",
+    "./page-data": "./src/page-data.js",
     "./icon-corpus": "./src/icon-corpus.js",
     "./locale-config": "./src/locale-config.js",
     "./route-match": "./src/route-match.js",
@@ -46,7 +47,7 @@
     "vitest": "^4.1.7"
   },
   "dependencies": {
-    "@uniweb/semantic-parser": "^1.4.0",
+    "@uniweb/semantic-parser": "^1.4.1",
     "@uniweb/theming": "^0.1.15"
   },
   "scripts": {

package/src/entity-store.js

@@ -14,10 +14,10 @@
  * and in-flight dedup.
  */
 
-import { resolveFetchConfigs, fetchEntries, pageRouteQuery, routeSelection, currentFor, othersView, othersOf, siteReaches } from './fetch-config.js'
-import { declaredKeys, fillDeclaredKeys } from './data-keys.js'
-import { fillRoutePattern, matchesRouteParam } from './route-match.js'
-import { buildDetailConfig } from './detail-url.js'
+import { resolveFetchConfigs, pageRouteQuery } from './fetch-config.js'
+import { declaredKeys } from './data-keys.js'
+import { fillRoutePattern } from './route-match.js'
+import { fetchLevels, blockFills, pageRecordConfig, planFor, runPlan, runPlanSync } from './page-data.js'
 
 export default class EntityStore {
   /**
@@ -33,24 +33,20 @@ export default class EntityStore {
   }
 
   /**
-   * The fetches that reach a block, one level each, most specific first: its own, its
-   * page's, its parent page's, a nested page's route binding, and the site's.
-   *
-   * ⭐ A page nested inside a parametric page receives its capturing page's route binding
-   * — the cascade reaches one parent up, and the binding may sit above that
-   * (`pageRouteQuery`). Its key only; the rest does not cascade. The site's binding
-   * reaches a layout section and a top-level page's sections, and nothing deeper
-   * (`siteReaches`).
+   * The fetches that reach a block — `fetchLevels` (`./page-data.js`), the one rule, read
+   * off this block's graph. ⛔ Do not spell the levels out here: every lane that has
+   * needed this answer has written its own list, and each list has drifted
+   * (`kb/framework/plans/what-a-page-needs.md`).
    */
   _levels(block, route = this._route(block)) {
     const page = block.page
-    return [
-      block.fetch,
-      page?.fetch,
-      page?.parent?.fetch,
-      route?.nested ? route.config : null,
-      siteReaches(page?.parent) ? block.website?.config?.fetch : null,
-    ]
+    return fetchLevels({
+      own: block.fetch,
+      page: page?.fetch,
+      parent: page?.parent ?? null,
+      route,
+      site: block.website?.config?.fetch,
+    })
   }
 
   /**
@@ -117,29 +113,73 @@ export default class EntityStore {
    */
   _fills(block, meta, route) {
     const website = block.website
-    const declared = website?.declaredKeys ? website.declaredKeys(meta) : declaredKeys(meta?.data)
-    const out = new Map()
-    if (declared.length === 0) return out
-    const holds = block.heldData || {}
-    const levels = this._levels(block, route)
-    const fills = fillDeclaredKeys(declared, levels, {
+    return blockFills({
+      declared: website?.declaredKeys ? website.declaredKeys(meta) : declaredKeys(meta?.data),
+      levels: this._levels(block, route),
+      holds: block.heldData || {},
       queries: website?.config?.queries ?? null,
-      held: declared.map(([key]) => key).filter((key) => holds[key] !== undefined),
+      options: this._resolveOptions(block),
     })
-    // where the first fetch of each key reaching the block sits — the one a held answer
-    // belongs to
-    const firstOfKey = new Map()
-    levels.forEach((level, at) => fetchEntries(level).forEach((fetch, index) => {
-      if (!firstOfKey.has(fetch.as)) firstOfKey.set(fetch.as, `${at}:${index}`)
-    }))
-    const options = this._resolveOptions(block)
-    for (const [key, { fetch, level, index }] of fills) {
-      const cfg = resolveFetchConfigs([fetch], options).get(fetch.as)
-      if (!cfg) continue
-      const held = firstOfKey.get(fetch.as) === `${level}:${index}` ? holds[fetch.as] : undefined
-      out.set(key, { cfg, held })
-    }
-    return out
+  }
+
+  /**
+   * The plan for a block — one program per declared key (`planFor`, `./page-data.js`),
+   * which both `resolve` and `fetch` run. They differ in where an answer comes from and in
+   * nothing else.
+   */
+  _plan(block, fills, route, dispatcher = this.website?.fetcher) {
+    return planFor(fills, {
+      dynamicContext: block.dynamicContext || block.page?.dynamicContext,
+      route,
+      peekRecord: (id) => dispatcher?.peekRecord?.(id),
+    })
+  }
+
+  /** The filling config of each key — what `_applyRecordRoutes` links records by. */
+  _configs(fills) {
+    return new Map([...fills].map(([key, { cfg }]) => [key, cfg]))
+  }
+
+  /**
+   * ⭐ THE PAGE'S OWN RECORD, ASKED — the question `Website#_createDynamicPage` peeks to name the
+   * page and to know whether it exists at all.
+   *
+   * A host's data step asks it whether or not a section declares the route key, because a page's
+   * existence is not a section's business: a parametric page with no section reading its record is
+   * a pseudo-error, but its 404 is not. The question is `pageRecordConfig`'s, so the asker and the
+   * page cannot ask two different things.
+   *
+   * @param {Object} page - a concrete parametric page (it carries `dynamicContext`)
+   * @param {Object} [options]
+   * @param {Object} [options.dispatcher] - fetch through this one (a host's data step)
+   * @returns {Promise<{ data: Object, errors: Object|null }|null>} null off a parametric page, or
+   *   when the page's route query resolves to nothing
+   */
+  async fetchPageRecord(page, { dispatcher = this.website?.fetcher } = {}) {
+    const dynamicContext = page?.dynamicContext
+    if (!dynamicContext || !dispatcher) return null
+
+    // A block-shaped probe standing for the page itself: its levels, its route query.
+    const probe = { fetch: null, page, website: this.website, dynamicContext: null }
+    const route = this._route(probe)
+    const cfg = route && pageRecordConfig({
+      pageFetch: page.fetch,
+      parent: page.parent ?? null,
+      route,
+      site: this.website?.config?.fetch,
+      options: this._resolveOptions(probe),
+    })
+    if (!cfg) return null
+
+    const plan = planFor(new Map([[route.key, { cfg }]]), {
+      dynamicContext,
+      route,
+      // The page is about ONE record, whatever a section's `current:` says.
+      current: 'only',
+      peekRecord: (id) => dispatcher.peekRecord?.(id),
+    })
+    const ctx = this._ctx(probe)
+    return runPlan(plan, { dispatch: (request) => dispatcher.dispatch(request, ctx) })
   }
 
   /**
@@ -233,17 +273,6 @@ export default class EntityStore {
     if (Object.keys(linked).some((key) => linked[key] !== held[key])) block.parsedContent.data = linked
   }
 
-  /**
-   * Build a detail-URL fetch config from a query config + dynamic context.
-   *
-   * Delegates to the exported resolver so a host fetching this record
-   * server-side reaches the identical rule — see `./detail-url.js` for why the
-   * four `detail:` forms are a contract rather than an implementation detail.
-   */
-  _buildDetailConfig(queryConfig, dynamicContext) {
-    return buildDetailConfig(queryConfig, dynamicContext)
-  }
-
   /**
    * Build the `ctx` handed to the dispatcher for a given block.
    * @private
@@ -269,99 +298,21 @@ export default class EntityStore {
     const route = this._route(block)
     const fills = this._fills(block, meta, route)
     if (fills.size === 0) return { status: 'none', data: null }
-    const configs = new Map([...fills].map(([key, { cfg }]) => [key, cfg]))
 
-    const dynamicContext = block.dynamicContext || block.page?.dynamicContext
     const ctx = this._ctx(block)
+    const result = runPlanSync(this._plan(block, fills, route), {
+      peek: (request) => dispatcher?.peek(request, ctx),
+    })
+    if (result.status !== 'ready') return { status: 'pending', data: null }
 
-    const data = {}
-    let allCached = true
-
-    for (const [schema, { cfg, held }] of fills) {
-      if (held !== undefined) {
-        // The block holds this fetch's answer already — a static build prerendered it.
-        data[schema] = held
-        continue
-      }
-      // How this fetch uses the page's record: by the query it names (`currentFor`).
-      const current = dynamicContext ? currentFor(cfg, route) : null
-      if (current === 'exclude') {
-        // The query's records without this page's, `limit` counting the others.
-        const cached = dispatcher?.peek(othersView(cfg), ctx)
-        if (cached) {
-          data[schema] = othersOf(cached.data, cfg, isPageRecord(dynamicContext))
-        } else {
-          allCached = false
-        }
-      } else if (current === 'only' && cfg.ask) {
-        // The records service: the record's own answer is cached under its own key.
-        const detailCfg = this._buildDetailConfig(cfg, dynamicContext)
-        const detailCached = detailCfg ? dispatcher?.peek(detailCfg, ctx) : null
-        if (detailCached) {
-          const answer = Array.isArray(detailCached.data) ? detailCached.data : (detailCached.data ? [detailCached.data] : [])
-          data[schema] = answer.slice(0, 1)
-        } else {
-          allCached = false
-        }
-      } else if (current === 'only') {
-        // Detail page: deliver the focused record as a length-1 array under the
-        // query key. A deferred/remote query fetches the full per-record;
-        // others use the matched record. Not found → []. Found in the set of the
-        // query the fetch names — the route query's, or another's under `current: only`
-        // — never in a list a fetch narrowed (`routeSelection`).
-        const cached = dispatcher?.peek(routeSelection(cfg), ctx)
-        if (cached) {
-          const { paramName, paramValue } = dynamicContext
-          const items = cached.data
-          const match = Array.isArray(items)
-            ? items.find((item) => matchesRouteParam(item, paramName, paramValue))
-            : null
-          if (!match) {
-            data[schema] = []
-          } else if (cfg.detail) {
-            // ⭐ Held in full already? Then it IS the record — no detail probe.
-            // The list is materialized from the record index, so `match` is the
-            // record at its latest depth; the index says which depth that is.
-            const held = heldWhole(dispatcher, match)
-            const detailCfg = held ? null : this._buildDetailConfig(cfg, { ...dynamicContext, record: match })
-            const detailCached = detailCfg ? dispatcher?.peek(detailCfg, ctx) : null
-            if (held) {
-              data[schema] = [held]
-            } else if (detailCfg && detailCached) {
-              data[schema] = [detailCached.data]
-            } else if (detailCfg) {
-              allCached = false
-            } else {
-              data[schema] = [match]
-            }
-          } else {
-            data[schema] = [match]
-          }
-        } else {
-          allCached = false
-        }
-      } else {
-        // A fetch the page's record plays no part in (`currentFor`), and `current:
-        // include`: the records as the fetch describes them, the page's among the rest.
-        const cached = dispatcher?.peek(cfg, ctx)
-        if (cached) {
-          data[schema] = cached.data
-        } else {
-          allCached = false
-        }
-      }
-    }
-
-    if (allCached) {
-      this._applyRecordRoutes(data, configs, block.website)
-      return { status: 'ready', data }
-    }
-    return { status: 'pending', data: null }
+    this._applyRecordRoutes(result.data, this._configs(fills), block.website)
+    return result
   }
 
   /**
-   * Async fetch — dispatches missing configs through the FetcherDispatcher
-   * and assembles the result. List-first detail ordering preserved.
+   * Async fetch — the same plan, run by dispatching. List-first detail ordering preserved:
+   * a record found in its query's set is asked for in full only after the set answers, and
+   * only that key waits.
    *
    * ⛔ A FAILED FETCH DELIVERS NOTHING UNDER ITS KEY, AND SAYS SO. Until 2026-09-04
    * a failure wrote `[]` into `content.data` — the fetcher returns `{ data: [], error }`,
@@ -374,146 +325,27 @@ export default class EntityStore {
    *
    * @param {Object} [options]
    * @param {AbortSignal} [options.signal] - Forwarded to the dispatcher.
+   * @param {Object} [options.dispatcher] - ⭐ Fetch through this one instead of the graph's: a
+   *   host's data step holds the request's transport and a cache of its own (`Website#dispatcherFor`).
+   *   The plan is the same; only where the answers come from and land differs.
    * @returns {Promise<{ data: Object|null, errors: Object|null }>} `data` keyed by
    *   binding key; `errors` keyed the same way, `null` when every fetch succeeded.
    */
-  async fetch(block, meta, { signal } = {}) {
-    const dispatcher = this.website?.fetcher
+  async fetch(block, meta, { signal, dispatcher = this.website?.fetcher } = {}) {
     if (!dispatcher) return { data: null, errors: null }
 
     const route = this._route(block)
     const fills = this._fills(block, meta, route)
     if (fills.size === 0) return { data: null, errors: null }
-    const configs = new Map([...fills].map(([key, { cfg }]) => [key, cfg]))
 
-    const dynamicContext = block.dynamicContext || block.page?.dynamicContext
     const ctx = this._ctx(block, { signal })
+    const { data, errors } = await runPlan(this._plan(block, fills, route, dispatcher), {
+      dispatch: (request) => dispatcher.dispatch(request, ctx),
+      onFailure: (key, cfg, message) => reportFetchFailure(this.dev, block, key, cfg, message),
+    })
 
-    const data = {}
-    const errors = {}
-    const parallelFetches = []
-    const fail = (key, cfg, message) => {
-      errors[key] = message
-      reportFetchFailure(this.dev, block, key, cfg, message)
-    }
-
-    for (const [schema, { cfg, held }] of fills) {
-      if (held !== undefined) {
-        // The block holds this fetch's answer already — a static build prerendered it.
-        data[schema] = held
-        continue
-      }
-      // How this fetch uses the page's record: by the query it names (`currentFor`).
-      const current = dynamicContext ? currentFor(cfg, route) : null
-      if (current === 'exclude') {
-        // The query's records without this page's, the fetch's `limit` counting
-        // the others: its `narrow.limit` asked one higher (`othersView`), so removing
-        // the record still leaves enough.
-        const view = othersView(cfg)
-        parallelFetches.push(dispatcher.dispatch(view, ctx).then((result) => {
-          if (result?.error) {
-            fail(schema, view, result.error)
-            return
-          }
-          if (result?.data !== undefined && result?.data !== null) {
-            data[schema] = othersOf(result.data, cfg, isPageRecord(dynamicContext))
-          }
-        }))
-      } else if (current === 'only' && cfg.ask) {
-        // ⭐ THE RECORDS SERVICE needs no list to find the record: the record is the
-        // query's set narrowed by the route's handle, so its one question
-        // answers the record if the set holds it and `[]` if not — no client-side
-        // scan gating the fetch (F13, the live half).
-        //
-        // ⛔ The list was asked beside it until 2026-09-14, for the record index to
-        // file its briefs, while the record question dropped the query's `sort` and
-        // `limit` and so could not say whether the set held the record. It checks the
-        // set now, and the list sent the whole set to render one record of it.
-        const detailCfg = this._buildDetailConfig(cfg, dynamicContext)
-        parallelFetches.push(dispatcher.dispatch(detailCfg, ctx).then((result) => {
-          if (result?.error) {
-            fail(schema, detailCfg, result.error)
-            return
-          }
-          const answer = Array.isArray(result?.data) ? result.data : (result?.data ? [result.data] : [])
-          data[schema] = answer.slice(0, 1) // a route resolves to ONE; `[]` is not found
-        }))
-      } else if (current === 'only') {
-        // Detail page: focused record as a length-1 array under the fetch's key,
-        // found in its query's set (`routeSelection`) — a record past a
-        // fetch's `limit` still has its page, and one past the query's has none.
-        const { paramName, paramValue } = dynamicContext
-        const selection = routeSelection(cfg)
-
-        let records = peekArray(dispatcher, selection, ctx)
-        if (records === null) {
-          const result = await dispatcher.dispatch(selection, ctx)
-          if (result?.error) {
-            fail(schema, selection, result.error)
-            continue
-          }
-          records = Array.isArray(result?.data) ? result.data : null
-        }
-
-        const match = records?.find(
-          (item) => matchesRouteParam(item, paramName, paramValue)
-        ) ?? null
-
-        if (!match) {
-          data[schema] = []
-          continue
-        }
-
-        const held = cfg.detail ? heldWhole(dispatcher, match) : null
-        if (held) {
-          // R1: the record index holds it in full — a detail fetch would only
-          // re-fetch what the page already has.
-          data[schema] = [held]
-        } else if (cfg.detail) {
-          const detailCfg = this._buildDetailConfig(cfg, { ...dynamicContext, record: match })
-          if (detailCfg) {
-            parallelFetches.push(
-              dispatcher.dispatch(detailCfg, ctx).then((result) => {
-                // The list already matched the record, so the brief is a HELD
-                // value: a failed detail fetch keeps it and reports, rather than
-                // delivering `[[]]` — which is what `result.data ?? match` did,
-                // because a failure's `data` is `[]`, not null.
-                if (result?.error) {
-                  fail(schema, detailCfg, result.error)
-                  data[schema] = [match]
-                  return
-                }
-                const record = (result?.data !== undefined && result?.data !== null)
-                  ? result.data
-                  : match
-                data[schema] = [record]
-              })
-            )
-          } else {
-            data[schema] = [match]
-          }
-        } else {
-          data[schema] = [match]
-        }
-      } else {
-        // Any other key — and `current: include`, the list as the binding describes it.
-        parallelFetches.push(
-          dispatcher.dispatch(cfg, ctx).then((result) => {
-            if (result?.error) {
-              fail(schema, cfg, result.error)
-              return
-            }
-            if (result?.data !== undefined && result?.data !== null) {
-              data[schema] = result.data
-            }
-          })
-        )
-      }
-    }
-
-    if (parallelFetches.length > 0) await Promise.all(parallelFetches)
-    this._applyRecordRoutes(data, configs, block.website)
-    return { data, errors: Object.keys(errors).length ? errors : null }
+    this._applyRecordRoutes(data, this._configs(fills), block.website)
+    return { data, errors }
   }
 }
 
@@ -540,32 +372,6 @@ function reportFetchFailure(dev, block, key, cfg, message) {
   )
 }
 
-/**
- * The record the index holds in FULL for a list match, or null — the R1 gate.
- * A record with no identity (`$uuid`) is never indexed, so the answer for it is
- * null and the detail fetch proceeds as before.
- */
-function heldWhole(dispatcher, match) {
-  const id = match?.$uuid
-  if (typeof id !== 'string' || !id || typeof dispatcher?.peekRecord !== 'function') return null
-  const held = dispatcher.peekRecord(id)
-  return held?.whole === true ? held.record : null
-}
-
-/** Matches the record a parametric page is about — the one `current: only` delivers. */
-function isPageRecord({ paramName, paramValue }) {
-  return (item) => matchesRouteParam(item, paramName, paramValue)
-}
-
-/**
- * Sync-peek helper: return the cached array for a config, or null on miss.
- */
-function peekArray(dispatcher, cfg, ctx) {
-  const cached = dispatcher.peek(cfg, ctx)
-  if (!cached) return null
-  return Array.isArray(cached.data) ? cached.data : null
-}
-
 /**
  * The route template a fetch's records link to — its `detailPage`, else its query's page.
  *

package/src/index.js

@@ -25,6 +25,9 @@ export { substitutePlaceholders } from './substitute-placeholders.js'
 export { resolveFetchConfigs, routeQuery, pageRouteQuery, routeSelection, sectionFetches, siteReaches, withoutRouteVariables, CURRENT_MODES, currentFor } from './fetch-config.js'
 export { buildDetailConfig, ROUTE_HANDLE_KEY } from './detail-url.js'
 export { declaredKeys, sameSchema, fillDeclaredKeys } from './data-keys.js'
+// ⭐ What a page needs — the one rule. `fetchLevels` is the part every lane has an answer for
+// (which fetches reach a block); the drivers and the per-key program are `@uniweb/core/page-data`.
+export { fetchLevels } from './page-data.js'
 // `isWildcardLanguages` is likewise internal — `./locale-config.js` reads it
 // and nothing else does. Same subpath escape hatch: `@uniweb/core/locale-config`.
 export {

package/src/page-data.js

@@ -0,0 +1,361 @@
+/**
+ * WHAT A PAGE NEEDS — the one rule, and the two ways to run it.
+ *
+ * ⭐ *Which requests does rendering this block need, and what does its component receive?* The
+ * answer has four parts, and this module is all four in one place:
+ *
+ *   - **(a) levels** — `fetchLevels`: which fetches reach a block at all.
+ *   - **(b) fills** — `blockFills`: which of them fills each key the component declares
+ *     (`fillDeclaredKeys`, `./data-keys.js`), and the resolved config of each.
+ *   - **(c) requests** — `keyProgram`: what a filling fetch asks on THIS page, by `current:`.
+ *   - **(d) assembly** — the same program: how each answer becomes the key's value.
+ *
+ * ⭐ **(c) is written in STEPS, because one request depends on an answer.** Off the records
+ * service, a parametric page's record is FOUND in its query's set and only then asked for in full,
+ * so the second request cannot be worked out before the first is answered. A flat list of configs
+ * computed up front cannot express that — it has to guess, and the guess is wrong wherever the
+ * record's own fields name the address (measured 2026-09-19: an `[id]` route with a `deferred:`
+ * query asked for `{slug}` unfilled). A generator says it once, and both drivers get it.
+ *
+ * ⛔ **Two drivers, never two rules.** `runPlanSync` answers from the cache alone — SSR, and the
+ * browser's first render — and stops at the first miss, which is what `pending` means. `runPlan`
+ * dispatches. They differ in where an answer comes from and in nothing else, so a render cannot
+ * look for something its fetch never asked for.
+ *
+ * *The copies this replaces, and what each of them got wrong:*
+ * `kb/framework/plans/what-a-page-needs.md`. The import boundary that stops the next one:
+ * `framework/_contracts/page-data-rule-boundary.test.js`.
+ *
+ * @module
+ */
+
+import { resolveFetchConfigs, fetchEntries, routeSelection, currentFor, othersView, othersOf, siteReaches } from './fetch-config.js'
+import { fillDeclaredKeys } from './data-keys.js'
+import { matchesRouteParam } from './route-match.js'
+import { buildDetailConfig } from './detail-url.js'
+
+/**
+ * (a) The fetches that reach a block, most specific first: its own, its page's, its parent page's,
+ * a nested page's route binding, and the site's where it reaches.
+ *
+ * ⭐ A page nested inside a parametric page receives its capturing page's route binding — the
+ * cascade reaches one parent up, and the binding may sit above that. Its key only; the rest does
+ * not cascade. The site's binding reaches a layout area and a top-level page's sections, and
+ * nothing deeper (`siteReaches`, which is why this takes the parent PAGE and not its fetch).
+ *
+ * Plain data in and out, so a caller holding payload objects gets the same answer as one holding
+ * the object graph.
+ *
+ * ⭐ `includeRoute` is for a caller looking for the PAGE'S OWN record rather than feeding a section:
+ * the route query's declaration may sit on a section, and so be in no other level, and the page
+ * still has to find the record it is about. A block sees that declaration only when it is nested,
+ * because otherwise it is already among the levels above.
+ *
+ * @param {Object} where
+ * @param {*} [where.own] - the block's own `fetch`
+ * @param {*} [where.page] - its page's `fetch`
+ * @param {Object|null} [where.parent] - its parent PAGE, or null
+ * @param {{ config: *, nested: boolean }|null} [where.route] - the page's route query
+ * @param {*} [where.site] - the site's `fetch`
+ * @param {boolean} [where.includeRoute] - include the route query's declaration wherever it came from
+ * @returns {Array<*>} one level each, falsy where a level declares nothing
+ */
+export function fetchLevels({ own = null, page = null, parent = null, route = null, site = null, includeRoute = false } = {}) {
+  return [
+    own,
+    page,
+    parent?.fetch ?? null,
+    includeRoute || route?.nested ? route?.config ?? null : null,
+    siteReaches(parent) ? site : null,
+  ]
+}
+
+/**
+ * (b) Each declared key paired with the fetch that fills it, resolved.
+ *
+ * ⭐ A declared key the block already HOLDS — a tagged data block, or its own fetch's prerendered
+ * answer under that name — is not filled from a request. `held` carries it, and only for the first
+ * fetch of that key reaching the block: the one whose answer a build put there.
+ *
+ * Each filling fetch is resolved on its own, so two fetches of one `as` can fill two keys.
+ *
+ * @param {Object} input
+ * @param {Array<[string, string|null]>} input.declared - `declaredKeys(meta)`
+ * @param {Array<*>} input.levels - `fetchLevels`
+ * @param {Object} [input.holds] - what the block already holds, by key
+ * @param {Object|null} [input.queries] - the site's `config.queries`
+ * @param {Object} [input.options] - what each fetch is resolved with (`resolveFetchConfigs`)
+ * @returns {Map<string, { cfg: Object, held: * }>} declared key → its filling config, in the order
+ *   `declared` lists the keys
+ */
+export function blockFills({ declared, levels, holds = {}, queries = null, options = {} }) {
+  const out = new Map()
+  if (!declared || declared.length === 0) return out
+
+  const fills = fillDeclaredKeys(declared, levels, {
+    queries,
+    held: declared.map(([key]) => key).filter((key) => holds[key] !== undefined),
+  })
+  // where the first fetch of each key reaching the block sits — the one a held answer belongs to
+  const firstOfKey = new Map()
+  levels.forEach((level, at) => fetchEntries(level).forEach((fetch, index) => {
+    if (!firstOfKey.has(fetch.as)) firstOfKey.set(fetch.as, `${at}:${index}`)
+  }))
+
+  for (const [key, { fetch, level, index }] of fills) {
+    const cfg = resolveFetchConfigs([fetch], options).get(fetch.as)
+    if (!cfg) continue
+    const held = firstOfKey.get(fetch.as) === `${level}:${index}` ? holds[fetch.as] : undefined
+    out.set(key, { cfg, held })
+  }
+  return out
+}
+
+/**
+ * The fetch a parametric page's OWN record is asked for with — its route query, resolved.
+ *
+ * ⭐ A page's existence is not a section's business: it is asked whether or not a section declares
+ * the route key, which is why this is its own entry point and why the levels include the route
+ * query's declaration wherever it came from (`includeRoute`). Its two callers — the page naming
+ * itself from the cache, and a host's data step asking for it — cannot drift apart.
+ *
+ * @param {Object} where
+ * @param {*} [where.pageFetch] - the parametric page's own `fetch`
+ * @param {Object|null} [where.parent] - its parent page
+ * @param {{ key: string, config: * }} where.route - its route query (`pageRouteQuery`)
+ * @param {*} [where.site] - the site's `fetch`
+ * @param {Object} [where.options] - what the fetch is resolved with (`resolveFetchConfigs`)
+ * @returns {Object|undefined} the resolved config, or undefined when the page declares none
+ */
+export function pageRecordConfig({ pageFetch = null, parent = null, route, site = null, options = {} }) {
+  if (!route?.key) return undefined
+  return resolveFetchConfigs(
+    fetchLevels({ page: pageFetch, parent, route, site, includeRoute: true }),
+    { ...options, schemas: [route.key] },
+  ).get(route.key)
+}
+
+/** The record a parametric page is about — the one `current: only` delivers. */
+function isPageRecord({ paramName, paramValue }) {
+  return (item) => matchesRouteParam(item, paramName, paramValue)
+}
+
+/**
+ * The record held under an identity IN FULL, or null — the R1 gate. A record with no identity
+ * (`$uuid`) is never indexed, so the answer for it is null and the detail request proceeds.
+ */
+function heldWhole(peekRecord, match) {
+  const id = match?.$uuid
+  if (typeof id !== 'string' || !id || typeof peekRecord !== 'function') return null
+  const held = peekRecord(id)
+  return held?.whole === true ? held.record : null
+}
+
+/**
+ * (c) + (d) One declared key's program: the requests it needs, in order, and what its answers
+ * become. Each `yield` is a request; what comes back is `{ data, error }` — a driver dispatching
+ * may report an error, a driver reading the cache never does, because the cache holds answers
+ * only.
+ *
+ * ⛔ **A failed request delivers NOTHING under its key, and says so.** The key is absent from the
+ * returned value and the message rides on `error`, because `[]` is a value: a request that failed
+ * must not be indistinguishable from a query with no records. The one exception is the record's
+ * own request on a page that already matched it in the set — there the brief is kept.
+ *
+ * @param {Object} cfg - the filling fetch, resolved
+ * @param {Object} where
+ * @param {Object|null} where.dynamicContext - the route's param and value, off a parametric page
+ * @param {{ key: string, config: Object, nested: boolean }|null} where.route - the page's route query
+ * @param {*} [where.held] - what the block already holds for this key
+ * @param {Function} [where.peekRecord] - the record index, for the R1 gate
+ * @param {'only'|'exclude'|'include'|null} [where.current] - override how this page's record is
+ *   used. ⭐ For a caller asking for the PAGE'S OWN record: a page is about one record whatever a
+ *   section's declaration says about how that section uses it.
+ * @param {boolean} [where.opportunistic] - answer from whatever is already cached and never
+ *   report a miss. ⭐ For a caller that runs BEFORE any fetch and must not cause one: the page
+ *   naming itself from its record. On a question door the record has its own answer, but a list
+ *   page may already hold the set, and the record is in it — so a miss falls through to the set,
+ *   and a record found there answers with the brief it holds. No value at all means *unknown*,
+ *   which is not the same as `[]`, *not in the set*.
+ * @returns {Generator<Object, { value?: *, error?: string, errorConfig?: Object }>}
+ */
+export function* keyProgram(cfg, { dynamicContext = null, route = null, held = undefined, peekRecord = null, current: forced = null, opportunistic = false } = {}) {
+  /** A step this caller can do without: a miss answers `{ missing: true }` instead of stopping. */
+  const maybe = (request) => (opportunistic ? { request, optional: true } : request)
+  // The block holds this fetch's answer already — a static build prerendered it.
+  if (held !== undefined) return { value: held }
+
+  // How this fetch uses the page's record: by the query it names (`currentFor`).
+  const current = forced ?? (dynamicContext ? currentFor(cfg, route) : null)
+
+  if (current === 'exclude') {
+    // The query's records without this page's, its `limit` counting the others.
+    const view = othersView(cfg)
+    const answer = yield view
+    if (answer.error) return { error: answer.error, errorConfig: view }
+    if (answer.data === undefined || answer.data === null) return {}
+    return { value: othersOf(answer.data, cfg, isPageRecord(dynamicContext)) }
+  }
+
+  if (current === 'only' && cfg.ask) {
+    // ⭐ THE RECORDS SERVICE needs no list to find the record: the record is the query's set
+    // narrowed by the route's handle, so its one question answers the record if the set holds it
+    // and `[]` if not.
+    const detailCfg = buildDetailConfig(cfg, dynamicContext)
+    // No per-record source, or a route carrying no value: an unanswerable question, and asking it
+    // is worse than leaving the key absent. ⚠️ `resolve` reported this as `pending` and `fetch`
+    // dispatched a null config; neither was intended (unified 2026-09-19).
+    if (!detailCfg && !opportunistic) return {}
+    const answer = detailCfg ? yield maybe(detailCfg) : { missing: true }
+    if (!answer.missing) {
+      if (answer.error) return { error: answer.error, errorConfig: detailCfg }
+      const list = Array.isArray(answer.data) ? answer.data : (answer.data ? [answer.data] : [])
+      return { value: list.slice(0, 1) } // a route resolves to ONE; `[]` is not found
+    }
+    // Opportunistic, and the record's own answer is not held: the set may be, and the record is
+    // in it. Falls through to the set below, which is where every other lane finds it.
+  }
+
+  if (current === 'only') {
+    // Off the service the record is FOUND in the set — the query as saved, without the fetch's
+    // `narrow` (`routeSelection`): a record past a fetch's `limit` still has its page, and one
+    // past the query's has none.
+    const selection = routeSelection(cfg)
+    const answer = yield maybe(selection)
+    // Opportunistic and nothing held: UNKNOWN, which is not `[]`. A caller naming a page from its
+    // record leaves the name alone rather than calling the record missing.
+    if (answer.missing) return {}
+    if (answer.error) return { error: answer.error, errorConfig: selection }
+    const items = Array.isArray(answer.data) ? answer.data : null
+    const { paramName, paramValue } = dynamicContext
+    const match = items?.find((item) => matchesRouteParam(item, paramName, paramValue)) ?? null
+    if (!match) return { value: [] } // not found
+    if (!cfg.detail) return { value: [match] }
+
+    // ⭐ Held in full already? Then it IS the record — no second request. The list is materialized
+    // from the record index, so `match` is the record at its latest depth.
+    const whole = heldWhole(peekRecord, match)
+    if (whole) return { value: [whole] }
+
+    // ⭐ THE STEP THAT NEEDS THE ANSWER: the record's own address can name its own fields, so it
+    // is built with the record in hand and never from the route's value alone.
+    const detailCfg = buildDetailConfig(cfg, { ...dynamicContext, record: match })
+    if (!detailCfg) return { value: [match] }
+    const detail = yield maybe(detailCfg)
+    // The list already matched the record, so the brief is a HELD value: a failed detail — or,
+    // for an opportunistic caller, one not yet held — keeps it rather than delivering `[[]]`.
+    if (detail.missing) return { value: [match] }
+    if (detail.error) return { value: [match], error: detail.error, errorConfig: detailCfg }
+    const record = detail.data !== undefined && detail.data !== null ? detail.data : match
+    return { value: [record] }
+  }
+
+  // A fetch the page's record plays no part in, and `current: include`: the records as the fetch
+  // describes them, the page's among the rest.
+  const answer = yield cfg
+  if (answer.error) return { error: answer.error, errorConfig: cfg }
+  if (answer.data === undefined || answer.data === null) return {}
+  return { value: answer.data }
+}
+
+/** A yielded step: a request, or a request a caller can do without (`opportunistic`). */
+function asStep(step) {
+  return step && step.request ? { request: step.request, optional: !!step.optional } : { request: step, optional: false }
+}
+
+/**
+ * Every filling key's program, ready to run.
+ *
+ * @param {Map<string, { cfg: Object, held: * }>} fills - `blockFills`
+ * @param {Object} where - passed to each `keyProgram`
+ * @returns {Map<string, Generator>}
+ */
+export function planFor(fills, where = {}) {
+  const plan = new Map()
+  for (const [key, { cfg, held }] of fills) {
+    plan.set(key, keyProgram(cfg, { ...where, held }))
+  }
+  return plan
+}
+
+/**
+ * Run a plan against the CACHE alone — SSR, and the browser's first render.
+ *
+ * Stops a key at its first miss and reports `pending` for the block, which is what the caller
+ * falls through to `runPlan` for. A key whose program needs no request is answered here.
+ *
+ * @param {Map<string, Generator>} plan
+ * @param {Object} io
+ * @param {(request: Object) => ({ data: * }|null|undefined)} io.peek
+ * @returns {{ status: 'ready'|'pending', data: Object|null }}
+ */
+export function runPlanSync(plan, { peek }) {
+  const data = {}
+  let complete = true
+
+  for (const [key, program] of plan) {
+    let sent
+    for (;;) {
+      const step = program.next(sent)
+      if (step.done) {
+        const out = step.value ?? {}
+        if (out.value !== undefined) data[key] = out.value
+        break
+      }
+      const { request, optional } = asStep(step.value)
+      const cached = peek(request)
+      if (!cached) {
+        if (optional) {
+          // The program can do without this one and says what it makes of that.
+          sent = { missing: true }
+          continue
+        }
+        // Not cached: this key is not answerable without a request, so the block is not ready.
+        program.return()
+        complete = false
+        break
+      }
+      sent = { data: cached.data }
+    }
+  }
+
+  return complete ? { status: 'ready', data } : { status: 'pending', data: null }
+}
+
+/**
+ * Run a plan by DISPATCHING — the browser filling a block, and a host's data step.
+ *
+ * ⭐ Every key's first request is issued in the same tick, which is what lets a question door batch
+ * a page's questions into one POST. A key whose second request depends on its first answer takes a
+ * later tick, and only that key waits.
+ *
+ * @param {Map<string, Generator>} plan
+ * @param {Object} io
+ * @param {(request: Object) => Promise<{ data: *, error?: string }>} io.dispatch
+ * @param {(key: string, cfg: Object|null, message: string) => void} [io.onFailure]
+ * @returns {Promise<{ data: Object, errors: Object|null }>}
+ */
+export async function runPlan(plan, { dispatch, onFailure = null }) {
+  const data = {}
+  const errors = {}
+
+  await Promise.all([...plan].map(async ([key, program]) => {
+    let sent
+    for (;;) {
+      const step = program.next(sent)
+      if (step.done) {
+        const out = step.value ?? {}
+        if (out.value !== undefined) data[key] = out.value
+        if (out.error) {
+          errors[key] = out.error
+          onFailure?.(key, out.errorConfig ?? null, out.error)
+        }
+        return
+      }
+      const result = await dispatch(asStep(step.value).request)
+      sent = { data: result?.data, error: result?.error }
+    }
+  }))
+
+  return { data, errors: Object.keys(errors).length ? errors : null }
+}

package/src/website.js

@@ -11,10 +11,10 @@ import FetcherDispatcher from './fetcher-dispatcher.js'
 import ObservableState from './observable-state.js'
 import { normalizeSeo } from './seo.js'
 import { resolveDefaultLocale, localeLabel } from './locale-config.js'
-import { matchDynamicRoute, decodeRouteValue, matchesRouteParam, recordTitle, routeBinding, routeParamName, parentRouteOf } from './route-match.js'
-import { resolveFetchConfigs, pageRouteQuery, recordPages, routeSelection, siteReaches } from './fetch-config.js'
+import { matchDynamicRoute, decodeRouteValue, recordTitle, routeBinding, routeParamName, parentRouteOf } from './route-match.js'
+import { resolveFetchConfigs, pageRouteQuery, recordPages } from './fetch-config.js'
 import { declaredKeys } from './data-keys.js'
-import { buildDetailConfig } from './detail-url.js'
+import { pageRecordConfig, planFor, runPlanSync } from './page-data.js'
 import { findLayoutEntry } from './layout-name.js'
 import { resolveService } from './services.js'
 
@@ -197,6 +197,34 @@ export default class Website {
     this.assets = assets
   }
 
+  /**
+   * ⭐ A DISPATCHER OF THIS SITE'S TRANSPORTS OVER A CACHE OF THE CALLER'S — for a caller that
+   * fetches this site's data without touching what the page is rendering from, and with a
+   * transport of its own.
+   *
+   * The one caller is a host's data step: it is handed the transport per request (a function does
+   * not survive every isolate boundary, so it cannot be wired in at construction), and it must
+   * fetch fresh rather than serve whatever an earlier request left in the graph's cache. What it
+   * must NOT do is answer with the framework default where the site chose a foundation transport,
+   * which is what building a plain fetcher of its own would do — hence this.
+   *
+   * @param {Object} options
+   * @param {import('./datastore.js').default} options.dataStore - the caller's cache
+   * @param {{ resolve: Function }|null} [options.defaultFetcher] - its transport, for every
+   *   request the site routes to no named transport
+   * @returns {FetcherDispatcher}
+   */
+  dispatcherFor({ dataStore, defaultFetcher = null }) {
+    return new FetcherDispatcher({
+      foundation: this._foundation,
+      extensions: this._extensions,
+      dataStore,
+      defaultFetcher,
+      transport: this._transport,
+      dev: this._dev,
+    })
+  }
+
   /**
    * Rebuild in place. Content-only rebuilds preserve the dispatcher and all
    * state (site and per-page). Passing `foundation` or `extensions` reassembles
@@ -624,60 +652,58 @@ export default class Website {
       // missed on exactly those lanes: no title, no not-found, and the page was
       // never cached (`recordsLoaded` false on every visit). Silent, on a
       // visitor's page — the "write key ≠ read key" failure.
-      let items = []
+      // ⭐ THE PAGE'S RECORD, BY THE RULE ITS SECTIONS ARE FED BY — the plan for the route
+      // key, run against the cache (`./page-data.js`). It is the `current: only` program on
+      // either lane: the records service asks the record alone and its answer is definitive,
+      // and off the service the record is found in the query's SET — the query as saved, its
+      // `limit` included, never a list a fetch narrowed — and only then asked for in full.
+      //
+      // ⛔ This walked and probed on its own until 2026-09-19, which is how it came to peek a
+      // key the store never wrote (no title, no not-found, never cached — F3, 2026-09-04) and
+      // to read a list a fetch had narrowed, calling a record past that `limit` "Not found"
+      // (2026-09-13). Both were fixed here and nowhere else, twice over.
       let currentItem = null
-      // ⭐ On the records service the record's own question checks the route query's
-      // set (`buildDetailConfig`), so once it has answered, its answer is definitive —
-      // the record, or `[]` for not found — with no list to consult.
-      let recordAnswered = false
+      // The cache could answer: a record, or its absence from a set that IS loaded.
+      let answered = false
 
       if (this.fetcher) {
-        // The same sources the store walks for a section that declares nothing,
-        // plus the route binding itself — which sits above the parent on a nested
-        // page, or on a section when the key came from the sections.
-        const fetchConfig = resolveFetchConfigs(
-          [originalData.fetch, parentPage?.fetch, route.config, siteReaches(parentPage) ? this.config?.fetch : null],
-          {
-            schemas: [route.key],
+        const fetchConfig = pageRecordConfig({
+          pageFetch: originalData.fetch,
+          parent: parentPage ?? null,
+          route,
+          site: this.config?.fetch,
+          options: {
             locale: this.getActiveLocale(),
             defaultLocale: this.getDefaultLocale(),
             queries: this.config?.queries ?? null,
             services: this.config?.services ?? null,
             variables,
           },
-        ).get(route.key)
+        })
         if (fetchConfig) {
           const ctx = { website: this }
-          // ⭐ The page is about ONE record, so ask for that record first: a
-          // cached detail fetch (a live lane's record address, a deferred
-          // query's per-record file) carries the title even when the list was
-          // never fetched — a cold load on a detail URL — where a scan of the
-          // list finds nothing and silently sets no title (F3, 2026-09-04).
-          const detailCfg = fetchConfig.detail
-            ? buildDetailConfig(fetchConfig, { paramName, paramValue })
-            : null
-          const detailCached = detailCfg ? this.fetcher.peek(detailCfg, ctx) : null
-          // The service answers the record question as a list of one (a question's
-          // answer is always a list); a per-record file answers the bare record.
-          const raw = detailCached?.data
-          const record = Array.isArray(raw) ? raw[0] : raw
-          if (record && typeof record === 'object') currentItem = record
-          if (fetchConfig.ask && detailCached && Array.isArray(raw)) recordAnswered = true
-
-          // ⭐ The route query's set (`routeSelection`) — the query as saved, its `limit`
-          // included, never a list a fetch narrowed: a record past a fetch's `limit` is a
-          // record, and one past the query's is not (ruled 2026-09-14 [Diego]). ⛔ Until
-          // 2026-09-13 this read the cut list and declared a record past a list's
-          // `limit` "Not found".
-          const cached = this.fetcher.peek(routeSelection(fetchConfig), ctx)
-          items = Array.isArray(cached?.data) ? cached.data : []
+          const plan = planFor(new Map([[route.key, { cfg: fetchConfig }]]), {
+            dynamicContext: { paramName, paramValue },
+            route,
+            peekRecord: (id) => this.fetcher.peekRecord?.(id),
+            // A page is about ONE record, whatever a section's `current:` says about how that
+            // section uses it.
+            current: 'only',
+            // This runs before anything has been fetched and must not cause a fetch: it names the
+            // page from whatever is held — the record's own answer, or the record inside a set a
+            // list page already holds — and says nothing when neither is.
+            opportunistic: true,
+          })
+          const out = runPlanSync(plan, { peek: (request) => this.fetcher.peek(request, ctx) })
+          const found = out.data?.[route.key]
+          if (found !== undefined) {
+            // The cache answered: the record, or `[]` for a set that does not hold it.
+            answered = true
+            currentItem = found.length > 0 ? found[0] : null
+          }
         }
       }
 
-      if (!currentItem) {
-        currentItem = items.find(item => matchesRouteParam(item, paramName, paramValue)) ?? null
-      }
-
       if (currentItem) {
         // ⭐ The record names the page by the one rule its search result is named by
         // too (`recordTitle`: `title`, `name`, then its handle). ⛔ Until 2026-09-14 this
@@ -687,21 +713,19 @@ export default class Website {
         if (currentItem.description || currentItem.excerpt) {
           pageData.description = currentItem.description || currentItem.excerpt
         }
-      } else if (items.length > 0 || recordAnswered) {
-        // The set is loaded and this ID isn't in it, or the record question answered
-        // `[]` — definitive not found
+      } else if (answered) {
+        // The cache answered and the record is not there: the set is loaded and this ID is
+        // not in it, or the record question answered `[]` — definitive not found.
         pageData.title = 'Not found'
         pageData.notFound = true
       }
 
-      // Track whether the records were available at creation time.
-      // Note: the matched record and the sibling list are intentionally NOT
-      // stored on dynamicContext — nothing reads them (its shape is
-      // { templateRoute, params, paramName, paramValue }; the record reaches
-      // components via content.data, the others via
-      // `fetch: { query, current: exclude }`). The local
-      // `currentItem`/`items` above drive title/description/notFound.
-      pageData._recordsLoaded = items.length > 0 || currentItem !== null || recordAnswered
+      // Track whether the records were available at creation time — which is exactly
+      // whether the plan could be answered from the cache. Note: the matched record and the
+      // sibling list are intentionally NOT stored on dynamicContext — nothing reads them
+      // (its shape is { templateRoute, params, paramName, paramValue }; the record reaches
+      // components via content.data, the others via `fetch: { query, current: exclude }`).
+      pageData._recordsLoaded = answered
     }
 
     // Create the page instance