@uniweb/core 0.28.0 → 0.29.0

package/src/fetch-config.js

@@ -92,22 +92,67 @@ export function currentOf(cfg) {
 }
 
 /**
- * The list a `current: exclude` section asks for: its own view, one record longer,
- * so that removing the page's record still leaves `limit` others. The order is
- * narrow, sort, remove the record, limit — a `limit` counts the others.
+ * ⭐ HOW A FETCH ON A PARAMETRIC PAGE USES THE PAGE'S RECORD — `current:` FOLLOWS THE QUERY,
+ * NOT THE KEY (ruled 2026-09-14 [Diego]). The one test the entity store (`resolve`, `fetch`),
+ * the prefetch and the build's warning all make:
+ *
+ *   - **a fetch naming the route query** gets the page's record — `only` — unless its
+ *     `current:` says `exclude` or `include`, whatever its `as`: `{ query: articles, as:
+ *     related, current: exclude }` is the others under `related`;
+ *   - **a fetch naming another query** gets that query's records as it describes them,
+ *     and its `current:` is read when written: `exclude` takes the page's record out, `only`
+ *     keeps just that record;
+ *   - **a fetch naming no query** (a `path:` or `url:` config) is decided by its key, as
+ *     before: the route key's fetch gets the record. So is every fetch on a page whose
+ *     route query names none, since there is no query to compare.
+ *
+ * The page's record is found in any of them the way it is found in the route query's set —
+ * by the route's parameter (`matchesRouteParam`).
+ *
+ * ⛔ Until 2026-09-14 both were decided by the key: `current:` was read only under the route
+ * key, and there it defaulted to the record whatever query the fetch named. So `{ query:
+ * articles, as: related, current: exclude }` got every article, and `{ query: news, as:
+ * articles }` got the page's article out of `news`.
+ *
+ * @param {Object} cfg - a fetch config — resolved, or as authored with its `as`
+ * @param {{ key: string, config: Object }|null} route - the page's route query
+ *   (`pageRouteQuery`), or null off a parametric page
+ * @returns {'only'|'exclude'|'include'|null} null when the page's record plays no part: the
+ *   fetch gets its records as it describes them
+ */
+export function currentFor(cfg, route) {
+  if (!cfg || !route) return null
+  const named = (c) => (typeof c?.query === 'string' && c.query ? c.query : null)
+  const query = named(cfg)
+  const routeQueryName = named(route.config)
+  if (query === null || routeQueryName === null) return bindingKey(cfg) === route.key ? currentOf(cfg) : null
+  if (query === routeQueryName) return currentOf(cfg)
+  return CURRENT_MODES.includes(cfg.current) ? cfg.current : null
+}
+
+/**
+ * The list a `current: exclude` section asks for: its own view, with `narrow.limit`
+ * one higher, so that removing the page's record still leaves `limit` others. The
+ * order is the set, then the fetch's `where` and `sort`, remove the record, `limit` —
+ * so a fetch's `limit` counts the others.
+ *
+ * ⚠️ Only the fetch's own `limit` is raised. A query's `limit` defines its set (ruled
+ * 2026-09-14 [Diego]), so the others never reach past it: with no `limit` of the
+ * fetch's own, the section gets the set without the page's record.
  *
  * @param {Object} cfg - a resolved config under the route key
  * @returns {Object}
  */
 export function othersView(cfg) {
-  if (!cfg || typeof cfg.limit !== 'number' || cfg.limit <= 0) return cfg
-  return { ...cfg, limit: cfg.limit + 1 }
+  const limit = cfg?.narrow?.limit
+  if (typeof limit !== 'number' || limit <= 0) return cfg
+  return { ...cfg, narrow: { ...cfg.narrow, limit: limit + 1 } }
 }
 
 /**
  * The records a `current: exclude` section receives, from what `othersView` asked:
  * the list without the page's record — the first that matches the route's value, the
- * one `only` delivers — cut to the binding's `limit`.
+ * one `only` delivers — cut to the fetch's `narrow.limit`.
  *
  * @param {Array|*} records - what `othersView(cfg)` answered
  * @param {Object} cfg - the section's resolved config
@@ -118,7 +163,8 @@ export function othersOf(records, cfg, isCurrent) {
   if (!Array.isArray(records)) return records
   const at = records.findIndex(isCurrent)
   const others = at < 0 ? records : [...records.slice(0, at), ...records.slice(at + 1)]
-  return typeof cfg?.limit === 'number' && cfg.limit > 0 ? others.slice(0, cfg.limit) : others
+  const limit = cfg?.narrow?.limit
+  return typeof limit === 'number' && limit > 0 ? others.slice(0, limit) : others
 }
 
 /**
@@ -145,7 +191,7 @@ function localizeConfig(cfg, locale, defaultLocale) {
  * Say whether a resolved config has a PER-RECORD source — `detail` — so a
  * parametric page asks for its record on its own rather than finding it in the list.
  *
- *   - the records service → `true`: the record is the list's own question narrowed
+ *   - the records service → `true`: the record is the route query's set narrowed
  *     by the URL's value (`buildDetailConfig`);
  *   - an external query declaring `record:` → `true`: its own request;
  *   - a query declaring `deferred:` → `/data/<query>/{slug}.json`, the per-record
@@ -167,8 +213,8 @@ function localizeConfig(cfg, locale, defaultLocale) {
 function applyDeferredDetail(cfg, queries) {
   if (cfg.detail !== undefined) return cfg
 
-  // The records service answers a RECORD by the same question narrowed to it,
-  // so every asked config has a detail source; `buildDetailConfig` composes it.
+  // The records service answers a RECORD by the query's set narrowed to it, so
+  // every asked config has a detail source; `buildDetailConfig` composes it.
   if (cfg.ask) return { ...cfg, detail: true }
   // An external query's `record:` request.
   if (cfg.record && typeof cfg.record === 'object') return { ...cfg, detail: true }
@@ -271,13 +317,13 @@ function resolveQuerySource(cfg, services, { queries = null, locale = null, defa
     if (decl.record && typeof decl.record === 'object') out.record = decl.record
     // a live endpoint is the browser's to fetch, unless the binding says otherwise
     if (out.prerender === undefined) out.prerender = false
-    return narrowQuery(out, decl, decl.where)
+    return setAndNarrow(out, decl, decl.where)
   }
 
-  // ⭐ THE SERVICE FIRST. A host that answers questions gets the whole query —
-  // `schema`, `scope`, `where`, `sort`, `limit`, `depth` — and composes no
-  // per-query address at all (the records contract, §2). It needs the query's
-  // MODEL REF, which lives on the site's `config.queries` declaration; a
+  // ⭐ THE SERVICE FIRST. A host that answers questions gets the query as saved —
+  // `schema`, `scope`, `where`, `sort`, `limit` — and the fetch's `narrow` beside it,
+  // and composes no per-query address at all (the records contract, §2). It needs
+  // the query's MODEL REF, which lives on the site's `config.queries` declaration; a
   // payload that offers the service but carries no declaration cannot ask, and
   // says so. ⚠️ Dark until a host stamps the row; see `resolveRecordsService`.
   const ask = resolveRecordsService(services, locale ?? defaultLocale)
@@ -293,65 +339,88 @@ function resolveQuerySource(cfg, services, { queries = null, locale = null, defa
       // instead would turn a producer defect into a 404 that names the wrong
       // thing. The fetcher refuses an asked request with no `schema` before any
       // request is made, and the block's `dataError` says exactly this.
-      return { ...rest, ask, schema: null }
+      return setAndNarrow({ ...rest, ask, schema: null }, decl, decl?.where ?? null)
     }
-    return narrowQuery({ ...rest, ask, schema }, decl, decl.where)
+    return setAndNarrow({ ...rest, ask, schema }, decl, decl.where)
   }
 
   // ⭐ THE COMPILED FILE. The build applied the named query's fixed `where` when it
-  // wrote `/data/<query>.json`; what it could NOT apply is a clause bound to the
-  // route (`where: { tag: :dir }`) — a file is written once and the route differs
-  // per page — and it applies neither `scope` nor `limit`. So those travel here and
-  // are applied per page, exactly as the service applies them (`bindRouteVariables`,
-  // below). ⛔ Until 2026-09-11 nothing travelled: a named query's `scope: :dir` was
-  // ignored on this lane and `where: { tag: :dir }` was applied at build to the
-  // literal `':dir'`, compiling to no records (measured).
+  // wrote `/data/<query>.json`, in its `sort`; what it could NOT apply is a clause
+  // bound to the route (`where: { tag: :dir }`) — a file is written once and the
+  // route differs per page — and it applies neither `scope` nor `limit`. So the
+  // runtime makes the set per page from what travels here — `scope`, the routed
+  // clauses, the query's `sort` in the page's locale, its `limit` — exactly as the
+  // service makes it (`bindRouteVariables`, below; `evaluateQuery`). ⛔ Until
+  // 2026-09-11 nothing travelled: a named query's `scope: :dir` was ignored on this
+  // lane and `where: { tag: :dir }` was applied at build to the literal `':dir'`,
+  // compiling to no records (measured).
   const out = { ...cfg, path: queryDataUrl(cfg.query) }
   for (const key of QUERY_SUPPLIED) delete out[key]
-  return decl ? narrowQuery(out, decl, routeVariableClauses(decl.where)) : out
+  return setAndNarrow(out, decl, decl ? routeVariableClauses(decl.where) : null)
 }
 
 /**
- * ⭐ A BINDING NARROWS ITS QUERY, AND NEVER WIDENS IT — ruled 2026-09-13 [Diego]:
- * *"binding can narrow its query and pick its own order and count, but it can never
- * add records the query leaves out."* One composition, so the records service is
- * asked exactly what the compiled file is evaluated with:
- *
- *   - `scope` — the query's; a binding has none;
- *   - `where` — the query's and the binding's must BOTH hold, as `{ and: [ … ] }`;
- *   - `sort`, `limit` — the binding's, else the query's. A binding's `limit` is not
- *     bounded by the query's: a count is how many to show, never which records exist.
- *
- * ⛔ Until 2026-09-13 each field of a binding REPLACED the query's here, while the
- * static build had already baked the query's `where`, `sort` and `limit` into the
- * file — so a binding narrowed inside the query on a static site and replaced it on
- * a hosted one (measured: `where: { published: true }` plus `{ tag: x }` delivered
- * published records tagged x from the file and asked the service for `{ tag: x }`).
- *
- * @param {Object} out - the binding, addressed
- * @param {Object} decl - the query's declaration
+ * ⭐ A FETCH IS ITS QUERY'S SET, AND WHAT IT TAKES OF THE SET — two levels, ruled
+ * 2026-09-14 [Diego]:
+ *
+ *   - **the top level is the query as saved** — its `scope`, `where`, `sort` and
+ *     `limit`. They define THE SET: the records its `scope` and `where` select, in its
+ *     `sort`, up to its `limit`. A query's `limit` is part of what it selects, so a
+ *     parametric page has a URL for each record of its route query's set, and no other;
+ *   - **`narrow` is the fetch's own `where`, `sort` and `limit`**, applied to the set:
+ *     its `where` filters what the set holds, its `sort` re-orders what is left, and its
+ *     `limit` cuts the rest — never past the set. Absent when the fetch takes the whole
+ *     set.
+ *
+ * Every lane evaluates the set first and then `narrow` — the records service at the
+ * source, the default fetcher and the build over a file or a response
+ * (`@uniweb/core`'s `evaluateQuery`) — and every question about one query carries the
+ * same top level, so a record question checks the set with the query's own `sort` and
+ * `limit` (`buildDetailConfig` adds `narrow.match`).
+ *
+ * ⛔ Until 2026-09-14 the two levels were MERGED into one flat question — the fetch's
+ * `where` joined the query's with `and`, and its `sort` and `limit` replaced the
+ * query's. So *"the latest 3 about pandas, among the query's 100 most recent"* was
+ * asked as *"the latest 3 about pandas"*, whether or not they were among the 100; a
+ * fetch's `limit` could exceed its query's; and a record question dropped the query's
+ * `sort` and `limit`, so a record outside the 100 still had a page.
+ *
+ * A config that names a query ALWAYS carries the fetch's adaptations in `narrow`, with
+ * a declaration for the query or without one, so the top level never holds a
+ * fetch's field. A `narrow`, `match` or `cursor` a stale binding carries is not read:
+ * the resolver and the client compose those.
+ *
+ * @param {Object} out - the fetch, addressed
+ * @param {Object|null} decl - the query's declaration, when the payload carries one
  * @param {Object|null} queryWhere - the part of the query's `where` this lane still
- *   applies: all of it on the service, the routed clauses on the compiled file
+ *   applies: all of it on the service and for an external query, the routed clauses on
+ *   the compiled file
  * @returns {Object}
  */
-function narrowQuery(out, decl, queryWhere) {
-  const next = { ...out }
-  if (typeof decl.scope === 'string') next.scope = decl.scope
-  const where = bothHold(queryWhere, out.where)
-  if (where) next.where = where
-  else delete next.where
-  if (next.sort === undefined && decl.sort !== undefined && decl.sort !== null) next.sort = decl.sort
-  if (next.limit === undefined && typeof decl.limit === 'number' && decl.limit > 0) next.limit = decl.limit
+function setAndNarrow(out, decl, queryWhere) {
+  const { where, sort, limit, narrow: _narrow, match: _match, cursor: _cursor, ...next } = out
+  if (decl) {
+    if (typeof decl.scope === 'string') next.scope = decl.scope
+    if (someWhere(queryWhere)) next.where = queryWhere
+    if (decl.sort !== undefined && decl.sort !== null) next.sort = decl.sort
+    if (isCount(decl.limit)) next.limit = decl.limit
+  }
+  const narrow = {}
+  if (someWhere(where)) narrow.where = where
+  if (sort !== undefined && sort !== null && sort !== '') narrow.sort = sort
+  if (isCount(limit)) narrow.limit = limit
+  if (Object.keys(narrow).length > 0) next.narrow = narrow
   return next
 }
 
-/** Two where-objects that must both hold — `{ and: [a, b] }`, or whichever one there is. */
-function bothHold(a, b) {
-  const some = (w) => Boolean(w) && typeof w === 'object' && !Array.isArray(w) && Object.keys(w).length > 0
-  if (some(a) && some(b)) return { and: [a, b] }
-  if (some(b)) return b
-  if (some(a)) return a
-  return null
+/** A where-object that says something: a non-empty plain object. */
+function someWhere(where) {
+  return Boolean(where) && typeof where === 'object' && !Array.isArray(where) && Object.keys(where).length > 0
+}
+
+/** A `limit` that cuts: a number above 0. `0` and anything else mean every record. */
+function isCount(limit) {
+  return typeof limit === 'number' && limit > 0
 }
 
 /**
@@ -384,6 +453,47 @@ function bindingKey(cfg) {
   return cfg?.as
 }
 
+/**
+ * One fetch entry as the runtime reads it. ⭐ **A STRING IS A QUERY NAME, and `as`
+ * DEFAULTS TO THE QUERY'S NAME — on every lane** (ruled 2026-09-13 [Diego]: *"a string
+ * is a query name, so, `fetch: "members"` … means `fetch: {query: "members"}`"*, and
+ * *"`as` defaults to `query`"*). The build writes both out when it parses a content
+ * file (`parseFetchConfig`), so a static payload never needs this. A payload a backend
+ * publishes carries a page's and a section's `fetch` as stored — where a bare `"people"`
+ * and a `{ query }` with no `as` are ordinary — and ⛔ **both were skipped here, for
+ * having no `as`, until 2026-09-14** (measured): a hosted section bound that way
+ * received nothing, and a parametric page whose parent named its query that way had no
+ * route query.
+ *
+ * A string that is not a query name — a path, a data file — is not one: `/data/…` is
+ * never authored (the build refuses it), and guessing at it here would fetch a file no
+ * query declares.
+ *
+ * @param {*} entry - a string, an object, or anything else a stored `fetch` holds
+ * @returns {Object|null} the entry with its `as`, or null when it is not a fetch
+ */
+function fetchEntry(entry) {
+  if (typeof entry === 'string') {
+    const name = entry.trim()
+    return name && !/[\\/]|\.(json|ya?ml)$/i.test(name) ? { query: name, as: name } : null
+  }
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return null
+  if (entry.as === undefined && typeof entry.query === 'string' && entry.query) return { ...entry, as: entry.query }
+  return entry
+}
+
+/**
+ * A `fetch` as the runtime reads it — one entry, several, or none — each through
+ * `fetchEntry`, so a string and a `{ query }` with no `as` are read as the query they name.
+ *
+ * @param {*} fetch - a level's `fetch`, as a payload carries it
+ * @returns {Array<Object>}
+ */
+export function fetchEntries(fetch) {
+  if (!fetch) return []
+  return (Array.isArray(fetch) ? fetch : [fetch]).map(fetchEntry).filter(Boolean)
+}
+
 /**
  * Resolve the applicable fetch configs from an ordered list of sources.
  *
@@ -429,9 +539,7 @@ export function resolveFetchConfigs(sources, options = {}) {
   const collectAll = schemas.length === 0
 
   for (const source of sources) {
-    if (!source) continue
-    const configList = Array.isArray(source) ? source : [source]
-    for (const cfg of configList) {
+    for (const cfg of fetchEntries(source)) {
       const key = bindingKey(cfg)
       if (!key) continue
       if (configs.has(key)) continue
@@ -477,6 +585,11 @@ function unset(value) {
  * to an intentional list page. Only an authoring surface can catch that; this
  * function cannot.
  *
+ * ⭐ Both levels bind: the query's `scope` and `where`, and the fetch's own `where`
+ * inside `narrow` — a variable may be a value in either (`setAndNarrow`). A `narrow`
+ * left with nothing in it is dropped, so it cannot split a cache entry from the fetch
+ * that takes the whole set.
+ *
  * @param {Object} cfg - a resolved config
  * @param {Object|null} variables - `{ path, dir, slug, … }` from the route, or null off a parametric page
  * @returns {Object} the config, with placeholders bound or their clauses dropped
@@ -496,14 +609,24 @@ function bindRouteVariables(cfg, variables) {
       out = bound === null ? rest : { ...rest, where: soleMember(bound) }
     }
   }
+  const narrowWhere = cfg.narrow?.where
+  if (narrowWhere && typeof narrowWhere === 'object') {
+    const bound = bindWhere(narrowWhere, variables)
+    if (bound !== narrowWhere) {
+      const { where, ...narrowRest } = out.narrow
+      const narrow = bound === null ? narrowRest : { ...narrowRest, where: soleMember(bound) }
+      const { narrow: _unbound, ...rest } = out
+      out = Object.keys(narrow).length > 0 ? { ...rest, narrow } : rest
+    }
+  }
   return out
 }
 
 /**
  * An `and` or `or` left holding ONE member once its unbound clauses dropped is that
- * member. It is how a query whose `where` is all route clauses, joined with its
- * binding's (`narrowQuery`), asks the list page the binding's `where` alone — the same
- * question, and the same cache entry, as a binding of a query with no `where`.
+ * member — so an authored `{ and: [ { tag: :dir }, { featured: true } ] }` asks the
+ * list page, where `:dir` is unbound, `{ featured: true }`: the same question, and the
+ * same cache entry, as the where written without the routed clause.
  */
 function soleMember(where) {
   if (!where || typeof where !== 'object' || Array.isArray(where)) return where
@@ -622,23 +745,27 @@ export function withoutRouteVariables({ where = null, scope = null } = {}) {
 }
 
 /**
- * ⭐ THE RECORDS A ROUTE QUERY SELECTS, UNCUT — the list a parametric page finds its
- * record in, and the list its detail pages are made from. A `limit` is how many a
- * list shows, never which records have a page: a binding `limit: 3` on `/blog` leaves
- * `/blog/d` a record (ruled 2026-09-13 [Diego]). `sort` stays, as the selection's order.
- *
- * ⛔ Until 2026-09-13 the compiled-file lane looked the record up in the LIMITED list,
- * so `/blog/d` rendered "not found" wherever its route query had a `limit`, and the
- * static build made no page for it. The records service never had this: its record
- * question drops `limit` (`buildDetailConfig`).
+ * ⭐ THE SET — the records a route query selects, and the list a parametric page finds
+ * its record in and its pages are made from: the config as the query saved it, without
+ * the fetch's `narrow`. Its `sort` and `limit` are the query's and stay, because a
+ * query's `limit` is part of what it selects (ruled 2026-09-14 [Diego]): a parametric
+ * page has a URL for each record of its route query's set, and no other — a field
+ * note older than the 100 most recent has no page under a query of the 100 most
+ * recent. A fetch's narrowing never decides which pages exist: `limit: 3` on `/blog`
+ * leaves `/blog/d` a record, when the query selects it.
+ *
+ * ⛔ Until 2026-09-14 this dropped the `limit` of a merged config instead — the fetch's
+ * or the query's, indistinguishable once merged — so every record the query's `where`
+ * selected had a page, whatever its `limit`, and a fetch's `where` did decide. The
+ * records service's record question dropped `sort` and `limit` to the same effect.
  *
  * @param {Object} cfg - a resolved config
- * @returns {Object} the config itself when it has no `limit`, else a copy without one
+ * @returns {Object} the config itself when it has no `narrow`, else a copy without it
  */
 export function routeSelection(cfg) {
-  if (!cfg || typeof cfg !== 'object' || cfg.limit === undefined) return cfg
-  const { limit, ...rest } = cfg
-  return rest
+  if (!cfg || typeof cfg !== 'object' || cfg.narrow === undefined) return cfg
+  const { narrow, ...set } = cfg
+  return set
 }
 
 /**
@@ -660,10 +787,9 @@ export function siteReaches(parent) {
   return !parent
 }
 
-/** A `fetch` as a list: one declaration, several, or none. */
+/** A `fetch` as a list: one declaration, several, or none — each read as the runtime reads it. */
 function fetchList(fetch) {
-  if (!fetch) return []
-  return Array.isArray(fetch) ? fetch.filter(Boolean) : [fetch]
+  return fetchEntries(fetch)
 }
 
 /**
@@ -789,6 +915,54 @@ export function pageRouteQuery(page, { routeOf, parentOf, fetchOf, sectionsOf, s
   return found ? { ...found, capturing, nested: capturing !== page } : null
 }
 
+/**
+ * ⭐ THE PAGE A QUERY'S RECORDS LINK TO — ruled 2026-09-14 [Diego]: *a rendered record
+ * links to its query's page.* For each query, the parametric page whose ROUTE QUERY is
+ * that query (`routeQuery`), the first in page order:
+ *
+ *   - **by the query's name, never by its schema** — a page over the same schema may not
+ *     select the record, so its URL could name a record it answers "not found" for;
+ *   - **a page nested inside a parametric page is not a record's page** — its route does
+ *     not end in the parameter (`recordRouteBase`), so a record cannot fill it;
+ *   - **no page, no link** — a query absent from the map has none.
+ *
+ * A fetch picks another page with `detailPage:`, which the caller resolves; this is
+ * the page with none. ⛔ It replaces `route:` on a query, which the build baked into
+ * compiled records as `route` — a field in the author's namespace, overwritten.
+ *
+ * Shape-agnostic, like `pageRouteQuery`: the object graph and a content document hand in
+ * their own accessors, so the runtime, a host and the editor get one answer.
+ *
+ * @param {Array<Object>} pages - every page, in page order, in the caller's shape
+ * @param {Object} access
+ * @param {(page: Object) => string} access.routeOf - its route pattern
+ * @param {(page: Object) => Object|null} access.parentOf - its parent page, or null
+ * @param {(page: Object) => *} access.fetchOf - its `fetch`
+ * @param {(page: Object) => Array<Object>|undefined} access.sectionsOf - its raw sections
+ * @param {*} [access.site] - the site's `fetch`
+ * @returns {Map<string, { page: Object, route: string, key: string }>} query name → its
+ *   record page: the page, its route pattern, and the key its record is delivered under
+ */
+export function recordPages(pages, { routeOf, parentOf, fetchOf, sectionsOf, site = null }) {
+  const out = new Map()
+  for (const page of pages || []) {
+    const route = routeOf(page)
+    if (recordRouteBase(route) === null) continue
+    const parent = parentOf(page)
+    const found = routeQuery({
+      page: fetchOf(page),
+      parent: parent ? fetchOf(parent) : null,
+      // the site's binding is a route query for a top-level page only (`siteReaches`)
+      site: siteReaches(parent) ? site : null,
+      sections: sectionFetches(sectionsOf(page)),
+    })
+    const name = found?.config?.query
+    if (typeof name !== 'string' || !name || out.has(name)) continue
+    out.set(name, { page, route, key: found.key })
+  }
+  return out
+}
+
 /**
  * Say what a resolved config will GET, so the record index can file it.
  *

package/src/fetcher-dispatcher.js

@@ -343,7 +343,15 @@ export default class FetcherDispatcher {
 
       const entry = meta !== undefined ? { data, meta } : { data }
       this._dataStore.set(key, entry)
-      return { data, meta }
+      // ⭐ What the store now HOLDS, not what arrived: an entry the record index filed
+      // materializes each record at the depth the index holds it — so a list fetched
+      // after its record was fetched whole delivers that record whole, on this pass as
+      // on every later read (R3). ⛔ Until 2026-09-14 a miss returned what arrived, and
+      // the upgrade reached a list only once it was read back from the cache — which a
+      // parametric page on the records service happened to do, by asking its list
+      // beside its record, until its record question checked the set on its own.
+      const held = this._dataStore.get(key)
+      return held ? { data: held.data, meta: held.meta } : { data, meta }
     } catch (err) {
       if (this._dataStore.inflight.get(key) === inflight) {
         this._dataStore.inflight.delete(key)

package/src/index.js

@@ -22,8 +22,9 @@ export { default as ObservableState } from './observable-state.js'
 export { substitutePlaceholders } from './substitute-placeholders.js'
 // `resolveRecordsService` / `RECORDS_SERVICE` are NOT re-exported here: `./fetch-config.js`
 // reads them and a consumer that needs them imports `@uniweb/core/records-service`.
-export { resolveFetchConfigs, routeQuery, pageRouteQuery, routeSelection, sectionFetches, siteReaches, withoutRouteVariables, CURRENT_MODES } from './fetch-config.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'
 // `isWildcardLanguages` is likewise internal — `./locale-config.js` reads it
 // and nothing else does. Same subpath escape hatch: `@uniweb/core/locale-config`.
 export {
@@ -58,6 +59,9 @@ export { applyScope, withinScope } from './scope.js'
 // (materialization, the `route:` bake) and by `@uniweb/runtime` (the fallback),
 // which is what keeps the static and live lanes answering a query identically.
 export { parseSort, sortRecords, sortToWire } from './sort.js'
+// A config's set, then its `narrow` — the one order of work the runtime's default
+// fetcher and `@uniweb/build` both evaluate a fetch with.
+export { evaluateQuery } from './query-evaluation.js'
 export {
   fillRoutePattern,
   splitPathCapture,

package/src/query-evaluation.js

@@ -0,0 +1,87 @@
+/**
+ * ⭐ A QUERY'S SET, THEN WHAT A FETCH TAKES OF IT — evaluated over the records a
+ * source returned. The ONE order of work for every lane that evaluates locally: the
+ * runtime's default fetcher over a compiled file or an external query's response,
+ * and the build when it runs a page's fetch.
+ *
+ * A resolved config has two levels (ruled 2026-09-14 [Diego],
+ * `@uniweb/core/fetch-config`):
+ *
+ *   1. **the set** — the query as saved: `scope`, then `where`, ordered by `sort`,
+ *      cut by `limit`;
+ *   2. **`narrow`** — the fetch's narrowing of that set: `where` and `match` filter
+ *      what the set holds, `sort` re-orders what is left (the set's order when there
+ *      is none), and `limit` cuts the rest.
+ *
+ * So a narrowing never reaches past the set: its `limit` can cut the set and never
+ * extend it. A host's records service evaluates the same two levels at the source.
+ *
+ * ⚠️ `narrow.cursor` is not evaluated here: a cursor resumes a service's answer, and
+ * no local source issues one.
+ *
+ * INTENTIONALLY A LEAF — pure JS, no `node:*`, no DOM, no package-root import — so
+ * the build and a browser runtime evaluate with the same code.
+ */
+
+import { match as matchWhere } from './where.js'
+import { applyScope } from './scope.js'
+import { sortRecords } from './sort.js'
+import { routeParamValues } from './route-match.js'
+
+/**
+ * Evaluate a resolved config's set and its narrowing over records.
+ *
+ * @param {Array<Object>|*} records - what the source returned; anything but an array
+ *   is returned as it is (a single record is not filtered, sorted or cut)
+ * @param {Object} config - a resolved fetch config
+ * @param {Object} [options]
+ * @param {string|null} [options.locale] - the page's locale, which texts sort in
+ * @param {(items: Array, sort: *, options: { locale: string|null }) => Array} [options.sort] -
+ *   the sort to apply, `sortRecords` by default. A lane that answers a bad `sort:`
+ *   differently — the runtime delivers the records unsorted in production — passes its own.
+ * @returns {Array<Object>|*} the records the config selects, in its order
+ */
+export function evaluateQuery(records, config, { locale = null, sort = sortRecords } = {}) {
+  if (!Array.isArray(records) || !config || typeof config !== 'object') return records
+  const order = (items, expr) => sort(items, expr, { locale })
+
+  let out = records
+  if (typeof config.scope === 'string' && config.scope) out = applyScope(out, config.scope)
+  if (config.where) out = matchWhere(config.where, out)
+  if (config.sort) out = order(out, config.sort)
+  if (isLimit(config.limit)) out = out.slice(0, config.limit)
+
+  const narrow = config.narrow
+  if (!narrow || typeof narrow !== 'object') return out
+  if (narrow.where) out = matchWhere(narrow.where, out)
+  if (narrow.match && typeof narrow.match === 'object') out = out.filter(matching(narrow.match))
+  if (narrow.sort) out = order(out, narrow.sort)
+  if (isLimit(narrow.limit)) out = out.slice(0, narrow.limit)
+  return out
+}
+
+/** A count that cuts: a whole number above 0. Absent, `0` or anything else is every record. */
+function isLimit(limit) {
+  return typeof limit === 'number' && limit > 0
+}
+
+/**
+ * A `match` — the record a parametric page's URL names — as a filter: the key is the
+ * record field `routeRecordKey` maps a route param to (`$name`, `$uuid`, or the field
+ * itself), and its value is compared as a STRING, member-wise on a list, by the one
+ * rule every lane matches a route param with (`routeParamValues`).
+ */
+function matching(match) {
+  const entries = Object.entries(match)
+  return (record) => entries.every(([key, value]) => {
+    const target = String(value)
+    return routeParamValues(record, paramNameOf(key)).some((held) => held === target)
+  })
+}
+
+/** The inverse of `routeRecordKey`: `$name` is a `[slug]` page's handle, `$uuid` a `[uuid]` page's identity. */
+function paramNameOf(key) {
+  if (key === '$name') return 'slug'
+  if (key === '$uuid') return 'uuid'
+  return key
+}

package/src/route-match.js

@@ -479,12 +479,13 @@ export function recordRouteBase(route) {
  *
  * `/blog/:slug` + `{ slug: 'a post' }` → `/blog/a%20post`. Every value is
  * `encodeURIComponent`-ed, because the output is a URL: it is compared against
- * `location.pathname` (`isActive(item.route)`) and matched back through
+ * `location.pathname` (`isActive(item.$route)`) and matched back through
  * `matchDynamicRoute`, which decodes what it captures. A raw interpolation and an
  * encoded one compare unequal on the first slug with a space — and they used to
  * both exist: the build baked `${base}/${item.slug}` raw into `/data/*.json` while
  * the runtime interpolated with encoding, and which one a site got was
- * lane-dependent (measured 2026-09-04). Two producers of one field now call this.
+ * lane-dependent (measured 2026-09-04). The build bakes no link since 2026-09-14;
+ * the runtime's `$route` and a search index's record URL both call this.
  *
  * ⛔ NOT for a file path. The SSG writes `dist/<route>/index.html` from the DECODED
  * value on purpose — a server decodes the request path before looking a file up,

package/src/sort.js

@@ -104,9 +104,8 @@ export function sortToWire(sort) {
  * Numbers, ISO dates and booleans compare as values.
  *
  * ⭐ A RECORD WITH NO VALUE FOR THE KEY SORTS LAST, IN EITHER DIRECTION, and records
- * that compare equal keep their order — the language both lanes answer
- * (`kb/frontend/contracts/site-queries.md` §1.4, as the records service built it on
- * 2026-09-13). "No value" is what `exists: false` means: missing, `null`, `""` — and a
+ * that compare equal keep their order — the language both lanes answer (as a host's
+ * records service answers it since 2026-09-13). "No value" is what `exists: false` means: missing, `null`, `""` — and a
  * list, since nothing says which member orders the record (a dotted path that meets
  * a list reads no value). ⛔ Until 2026-09-14 a missing value sorted as the empty
  * string — first ascending, last descending — so a static site and a hosted one put