@uniweb/core 0.30.1 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.30.1",
+  "version": "0.32.0",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
@@ -47,8 +47,8 @@
     "vitest": "^4.1.7"
   },
   "dependencies": {
-    "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/theming": "^0.1.15"
+    "@uniweb/theming": "^0.1.15",
+    "@uniweb/semantic-parser": "^1.4.1"
   },
   "scripts": {
     "test": "vitest run"

package/src/data-keys.js

@@ -24,31 +24,42 @@
 
 import { fetchEntries } from './fetch-config.js'
 
+/** The suffix that asks for whole records: `'@std/article/*'`. */
+export const WHOLE_SUFFIX = '/*'
+
 /**
- * A declared key's schema ref, as `data:` spells it: a ref string (`'@std/article'`), an
- * entry naming one (`{ schema: '@/member' }`), or null for an inline shape — a field map
- * or a form — which names no schema.
+ * A declared key's schema ref, and whether its component expects WHOLE records — as `data:`
+ * spells it: a ref string (`'@std/article'`), an entry naming one (`{ schema: '@/member' }`),
+ * or neither for an inline shape — a field map or a form — which names no schema.
+ *
+ * ⭐ `/*` after the ref asks for whole records (`'@std/article/*'`) — the record as stored, one
+ * key per section — where a bare ref asks for briefs, the brief's fields at the top (ruled
+ * 2026-09-27 [Diego]). The runtime asks each key's question accordingly; a key declared whole
+ * that its fetch cannot fill whole is `null`.
  *
  * @param {*} value - one `data:` entry's value, authored or leaned
- * @returns {string|null}
+ * @returns {{ ref: string|null, whole: boolean }}
  */
-function refOf(value) {
-  if (typeof value === 'string') return value || null
-  if (value && typeof value === 'object' && typeof value.schema === 'string') return value.schema || null
-  return null
+export function dataRefOf(value) {
+  const raw = typeof value === 'string'
+    ? value
+    : (value && typeof value === 'object' && typeof value.schema === 'string' ? value.schema : '')
+  if (!raw) return { ref: null, whole: false }
+  if (raw.endsWith(WHOLE_SUFFIX)) return { ref: raw.slice(0, -WHOLE_SUFFIX.length) || null, whole: true }
+  return { ref: raw, whole: false }
 }
 
 /**
- * The keys a section's component receives, in order, each with its schema ref — its
- * component's `data:` first, then its foundation's. A key both declare is the
- * component's.
+ * The keys a section's component receives, in order, each with its schema ref and whether
+ * it expects whole records (`dataRefOf`) — its component's `data:` first, then its
+ * foundation's. A key both declare is the component's.
  *
  * `data: false`, a missing `data:` or anything that is not a map declares nothing. Each
  * value may be as authored or as the build leans it (`{ key: ref|null }`).
  *
  * @param {Object|false|null|undefined} componentData - the component's `data:`
  * @param {Object|false|null|undefined} [foundationData] - its foundation's `main.js` `data:`
- * @returns {Array<[string, string|null]>}
+ * @returns {Array<[string, string|null, boolean]>} `[key, ref, whole]`
  */
 export function declaredKeys(componentData, foundationData = null) {
   const out = []
@@ -58,7 +69,8 @@ export function declaredKeys(componentData, foundationData = null) {
     for (const [key, value] of Object.entries(data)) {
       if (!key || seen.has(key)) continue
       seen.add(key)
-      out.push([key, refOf(value)])
+      const { ref, whole } = dataRefOf(value)
+      out.push([key, ref, whole])
     }
   }
   return out
@@ -116,7 +128,7 @@ function parseRef(ref) {
  * The mapping says where an answer lands; it renames no fetch. A fetch keeps its `as`
  * for its question, its cache key and its prefetch.
  *
- * @param {Array<[string, string|null]>} declared - `declaredKeys`
+ * @param {Array<[string, string|null, boolean]>} declared - `declaredKeys`
  * @param {Array<*>} levels - each level's `fetch`, most specific first; falsy levels skipped
  * @param {Object} [options]
  * @param {Object|null} [options.queries] - the site's `config.queries`, for each fetch's

package/src/data-paths.js

@@ -11,7 +11,7 @@
  * literal in six places across three packages: the build wrote it
  * (the query processor), the build resolved the query shorthand to it
  * (`data-fetcher.js`), core injected the per-record default
- * (`fetch-config.js applyDeferredDetail`), core gated locale-prefixing on it
+ * (`fetch-config.js applyRecordFiles`), core gated locale-prefixing on it
  * (`fetch-config.js localizeConfig`), the dev server matched it with a regex
  * (`build/src/site/plugin.js`), and kit's `useEntityDetail` — `useWholeRecord`
  * since 2026-09-14 — requested it.
@@ -60,8 +60,7 @@ export const DATA_DIR = 'data'
 export const DATA_URL_PREFIX = `/${DATA_DIR}/`
 
 /**
- * URL of a query's cascade payload — every record it returns, with
- * `deferred:` fields stripped when the query declares them.
+ * URL of a query's list — every record it returns, each as its brief.
  *
  * @param {string} name - The query name.
  * @returns {string} e.g. `/data/articles.json`
@@ -71,11 +70,11 @@ export function queryDataUrl(name) {
 }
 
 /**
- * URL of one record's full payload — every field, including deferred ones.
- * Emitted per record only when the query declares `deferred:`.
+ * URL of one record's own file — the record whole, as stored. Emitted for every
+ * record of a compiled query (only for a `deferred:` query until 2026-09-27).
  *
  * Takes either a concrete slug — a caller holding the record — or the literal
- * placeholder `{slug}` (core's `applyDeferredDetail`, which builds a pattern
+ * placeholder `{slug}` (core's `applyRecordFiles`, which builds a pattern
  * that `substitutePlaceholders` resolves later against the dynamic-route
  * param). Both are plain interpolation; this function does not encode,
  * matching the behavior of the call sites it replaced.

package/src/datastore.js

@@ -119,8 +119,8 @@ function indexableWhole(entry) {
 }
 
 /**
- * ⭐ THE RECORD INDEX — records are held ONCE, by identity, with the depth they
- * were fetched at; a query's result holds their ids.
+ * ⭐ THE RECORD INDEX — records are held ONCE, by identity, with whether they
+ * were fetched whole or as briefs; a query's result holds their ids.
  *
  * [Diego, 2026-09-04]: "they need to be able to hydrate records on their own…
  * track if they already have the briefs, and don't confuse that with knowing the
@@ -129,15 +129,20 @@ function indexableWhole(entry) {
  * record was already held in full still fetched it again, or — with the record's
  * list already cached — delivered the brief as if it were the record.
  *
- * Three rules:
- *   R1  an entry whose `meta.depth` is `brief` or `full` and whose records all
- *       carry `$uuid` is filed by id; `get()` materializes it from the index, so
- *       every list holding a record sees the record's latest depth;
- *   R2  depth is MONOTONIC — a brief never overwrites a record held in full;
- *   R3  an upgrade MERGES the full record over the brief rather than replacing
- *       it, so nothing depends on the full being a superset of the brief.
- * An entry with no depth, or with a record lacking identity, is held inline
- * exactly as before — the file lane with no synced records changes nothing.
+ * Two rules:
+ *   R1  an entry whose `meta.whole` is a boolean and whose records all carry
+ *       `$uuid` is filed by id; `get()` materializes it from the index, so every
+ *       entry holding a record sees the latest copy of it;
+ *   R2  a record's BRIEF and its WHOLE record are held apart, each replaced only
+ *       by a fresher copy of its own kind — they are two shapes (a brief's fields at
+ *       the top, a whole record's sections at the top; ruled 2026-09-27 [Diego]), so
+ *       a list of briefs stays briefs when its record is fetched whole.
+ * ⛔ Until 2026-09-27 a whole record MERGED over the brief it found (`{ ...brief,
+ * ...whole }`) and every list holding the record showed the merge — one object
+ * holding a brief's fields beside section names.
+ * An entry whose `meta.whole` is not a boolean, or with a record lacking
+ * identity, is held inline exactly as before — the file lane with no synced
+ * records changes nothing.
  */
 export default class DataStore {
   constructor() {
@@ -149,7 +154,7 @@ export default class DataStore {
     this._listeners = new Set()
     // Key-scoped listeners: key → Set<Function>
     this._keyedListeners = new Map()
-    // $uuid → { whole, record } — the record index
+    // $uuid → { brief?, whole? } — the record index
     this._records = new Map()
     // bumps on every index write, so a materialized list knows it is stale
     this._recordsVersion = 0
@@ -216,7 +221,8 @@ export default class DataStore {
     if (!entry || !entry.ids) return entry
     // Indexed: materialize from the record index, once per index version.
     if (entry._at === this._recordsVersion && entry._data) return entry._data
-    const records = entry.ids.map((id) => this._records.get(id)?.record).filter(Boolean)
+    const slot = entry.meta?.whole === true ? 'whole' : 'brief'
+    const records = entry.ids.map((id) => this._records.get(id)?.[slot]).filter(Boolean)
     const data = entry.single ? (records[0] ?? null) : records
     const out = entry.meta !== undefined ? { data, meta: entry.meta } : { data }
     entry._at = this._recordsVersion
@@ -228,9 +234,9 @@ export default class DataStore {
    * Cache store. Fires listeners: first the global ones (all-writes), then
    * any subscribers registered for this specific key.
    *
-   * An entry carrying `meta.depth` whose records all carry `$uuid` is filed in
-   * the record index and stored as ids — see the class note. Anything else is
-   * stored as given.
+   * An entry whose `meta.whole` is a boolean and whose records all carry `$uuid`
+   * is filed in the record index and stored as ids — see the class note.
+   * Anything else is stored as given.
    *
    * @param {string} key
    * @param {{ data: any, meta?: Object }} entry
@@ -245,39 +251,34 @@ export default class DataStore {
   }
 
   /**
-   * The record held under an identity, with the depth it was fetched at — the
-   * question a detail page asks before fetching: "do I hold this in full?"
+   * The record held under an identity, with whether it was fetched whole — the
+   * question a detail page asks before fetching: "do I hold this whole?"
    *
    * @param {string} id - a `$uuid`
-   * @returns {{ depth: 'brief'|'full', record: Object } | null}
+   * @returns {{ whole: boolean, record: Object } | null}
    */
   getRecord(id) {
-    return (id && this._records.get(id)) || null
+    const held = id ? this._records.get(id) : null
+    if (held?.whole) return { whole: true, record: held.whole }
+    if (held?.brief) return { whole: false, record: held.brief }
+    return null
   }
 
   /**
-   * File one record at a depth, honouring R2 and R3. Returns the record now held.
+   * File one record, whole or a brief, honouring R2 — the fresher copy of its own
+   * kind replaces the one held. Returns the record now held.
    *
    * @param {Object} record
-   * @param {'brief'|'full'} depth
+   * @param {boolean} whole - true for a record fetched whole, false for a brief
    * @returns {Object}
    */
   upsertRecord(record, whole) {
     const id = recordIdentity(record)
     if (!id || typeof whole !== 'boolean') return record
-    const held = this._records.get(id)
-    if (!held) {
-      this._records.set(id, { whole, record })
-      this._recordsVersion += 1
-      return record
-    }
-    // R2 — a brief never displaces a whole record.
-    if (!whole && held.whole) return held.record
-    // R3 — a whole record merges over a brief; same kind takes the fresher copy.
-    const next = whole && !held.whole ? { ...held.record, ...record } : record
-    this._records.set(id, { whole, record: next })
+    const held = this._records.get(id) || {}
+    this._records.set(id, { ...held, [whole ? 'whole' : 'brief']: record })
     this._recordsVersion += 1
-    return next
+    return record
   }
 
   _index(entry) {

package/src/detail-url.js

@@ -38,18 +38,20 @@ import { substitutePlaceholders } from './substitute-placeholders.js'
  */
 function paramContext(paramName, paramValue, record) {
   const context = { [paramName]: paramValue, param: paramValue }
-  // ⭐ `{slug}` is the RECORD'S slug, whatever the route calls its param. The
-  // file lane keys a query's per-record files by `item.slug` (`writeQueryFiles`)
+  // ⭐ `{slug}` is the RECORD'S handle, `$name`, whatever the route calls its param.
+  // The file lane keys a query's per-record files by `$name` (`writeQueryFiles`)
   // and injects `/data/<name>/{slug}.json` — so on a site routing `[id]`, the
   // route's context carried `id` and `param` and `{slug}` stayed literal: the
   // detail URL was `/data/articles/{slug}.json`, a guaranteed 404, on every
-  // template page with `deferred:` fields (measured 2026-09-04). When the caller
+  // `[id]` page that read a record's own file (measured 2026-09-04). When the caller
   // holds the record — the entity store does (it matched it), and so does
   // kit's `useWholeRecord` — its slug fills the name the FILE was written under. A
   // caller with no record in hand leaves `{slug}` literal rather than guessing
   // the capture is one: a visibly unresolved address beats a plausible wrong one.
+  // ⭐ Whatever the route calls its param — and whatever field its query binds `:slug` to — a
+  // record's own file is named by its `$name`, so a record in hand with one fills `{slug}`.
   const handle = recordHandle(record)
-  if (paramName !== 'slug' && handle != null && handle !== '') {
+  if (handle != null && handle !== '') {
     context.slug = handle
   }
   return context
@@ -73,7 +75,7 @@ export const ROUTE_HANDLE_KEY = routeRecordKey('slug')
  *   - **an external query's `record:`** — its `url` (the query's when it names none),
  *     `method` (likewise), `body` and `transform` — ⛔ never the list's `body` or
  *     `transform`, since a record response is rarely wrapped the way the list is;
- *   - **a `deferred:` query's per-record file** — the `/data/<query>/{slug}.json`
+ *   - **a compiled query's per-record file** — the `/data/<query>/{slug}.json`
  *     pattern the resolver injected.
  *
  * ⛔ The `detail:` forms an author wrote until 2026-09-13 — `rest`, `query`, a URL
@@ -85,13 +87,19 @@ export const ROUTE_HANDLE_KEY = routeRecordKey('slug')
  * Returns `null` — never throws — when the config has no per-record source or the
  * route carries no value. A caller treats `null` as "find the record in the list".
  *
+ * ⭐ `whole` — whether the record is asked whole (the default) or as its brief (ruled
+ * 2026-09-27 [Diego]: a component declares which it expects). Only the records service answers
+ * one record as its brief; everywhere else a record's brief is what its list holds, so asking
+ * for a brief there is `null`.
+ *
  * @param {Object} queryConfig - a resolved config
  * @param {{ paramName: string, paramValue: string, record?: Object|null }} dynamicContext -
  *   the route's param and its value; `record`, when the caller already holds the
  *   matched record, lets `{slug}` resolve to the record's own slug (`paramContext`).
+ * @param {{ whole?: boolean }} [options]
  * @returns {Object|null} a request, or null
  */
-export function buildDetailConfig(queryConfig, dynamicContext) {
+export function buildDetailConfig(queryConfig, dynamicContext, { whole = true } = {}) {
   const { detail } = queryConfig
   if (!detail) return null
   const { paramName, paramValue, record = null } = dynamicContext
@@ -117,14 +125,15 @@ export function buildDetailConfig(queryConfig, dynamicContext) {
   // string — it is a URL segment — and the service compares it as one, as the local
   // match does.
   if (queryConfig.ask) {
-    const { narrow: _narrow, detail: _detail, match: _match, ...set } = queryConfig
+    const { narrow: _narrow, detail: _detail, match: _match, whole: _whole, ...set } = queryConfig
     return {
       ...set,
-      narrow: { match: { [routeRecordKey(paramName)]: String(paramValue) } },
-      whole: true,
+      narrow: { match: { [routeRecordKey(paramName, queryConfig.routeField)]: String(paramValue) } },
+      ...(whole ? { whole: true } : {}),
       dynamicContext: { paramName, paramValue },
     }
   }
+  if (!whole) return null
 
   // What every other record request carries beside its address:
   //   `as`             — the binding key, so the record lands where the list did;
@@ -152,7 +161,7 @@ export function buildDetailConfig(queryConfig, dynamicContext) {
     return out
   }
 
-  // ⭐ A `deferred:` QUERY'S PER-RECORD FILE — the pattern `applyDeferredDetail` injected.
+  // ⭐ A COMPILED QUERY'S PER-RECORD FILE — the pattern `applyRecordFiles` injected.
   if (typeof detail === 'string' && typeof queryConfig.path === 'string') {
     return { path: substitutePlaceholders(detail, context), ...common }
   }

package/src/entity-store.js

@@ -51,7 +51,7 @@ export default class EntityStore {
 
   /**
    * The options each fetch of a block is resolved with. The rule applied to a fetch
-   * (locale normalization, route variables, deferred-detail injection) lives in
+   * (locale normalization, route variables, the record files' pattern) lives in
    * `./fetch-config.js`, shared with every other host that has to answer the same
    * question. Do not re-inline it here — divergence between copies is what the
    * extraction exists to prevent.
@@ -237,7 +237,7 @@ export default class EntityStore {
       if (!Array.isArray(items) || items.length === 0) continue
       const template = recordRouteTemplate(cfg, website)
       if (!template) continue
-      const linked = items.map((item) => withRecordRoute(item, template))
+      const linked = items.map((item) => withRecordRoute(item, template, cfg.routeField))
       // an unchanged list keeps its identity, so a render that re-links changes nothing
       if (linked.some((item, i) => item !== items[i])) data[key] = linked
     }
@@ -402,8 +402,8 @@ function recordRouteTemplate(cfg, website) {
  * ⭐ The encoding is `fillRoutePattern`'s: the one encoder for a record's href, which the
  * route matcher decodes (F14, 2026-09-04).
  */
-function withRecordRoute(item, template) {
+function withRecordRoute(item, template, field = null) {
   if (!item || typeof item !== 'object') return item
-  const route = fillRoutePattern(template, item)
+  const route = fillRoutePattern(template, item, { field })
   return route === null || item.$route === route ? item : { ...item, $route: route }
 }

package/src/fetch-config.js

@@ -4,7 +4,7 @@
  * "Which fetch configs apply here?" is a framework concept. Authors declare
  * `fetch:` at the section, page, folder and site levels; the framework decides
  * which declaration wins per schema, how a local data path is localized, and
- * when a query with deferred fields gets a detail pattern injected.
+ * where a compiled query's records have their own files.
  *
  * Every host that renders a page needs that answer — the browser runtime, the
  * build-time prerenderer, and any server-side renderer. The rule had grown
@@ -54,7 +54,7 @@ import { queryDataUrl, isDataUrl, recordDataUrl } from './data-paths.js'
 import { resolveRecordsService } from './records-service.js'
 // A leaf that imports nothing — `recordRouteBase` is the one rule for which page
 // addresses a record, and a route query is chosen at exactly that page.
-import { recordRouteBase } from './route-match.js'
+import { recordRouteBase, routeFieldOf } from './route-match.js'
 
 /**
  * ⭐ HOW A SECTION ON A PARAMETRIC PAGE USES THE PAGE'S RECORD — `current:` on its
@@ -194,13 +194,15 @@ function localizeConfig(cfg, locale, defaultLocale) {
  *   - 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
- *     file the build emits beside the lean list, keyed by the record's slug. ⭐ On a
- *     locale other than the default it is `/<locale>/data/<query>/{slug}.json`, the
- *     way the list's own path is (`localizeConfig`): a localized build writes a
- *     translated copy of every per-record file beside the translated list. ⛔ Until
- *     2026-09-14 the pattern was never localized, so a translated record page asked
- *     for the default locale's file and showed an untranslated body.
+ *   - a compiled query → `/data/<query>/{slug}.json`, the per-record file the build
+ *     emits beside the list for every record — the record whole, as stored, where the
+ *     list holds its brief. ⭐ On a locale other than the default it is
+ *     `/<locale>/data/<query>/{slug}.json`, the way the list's own path is
+ *     (`localizeConfig`): a localized build writes a translated copy of every
+ *     per-record file beside the translated list. ⛔ Until 2026-09-14 the pattern was
+ *     never localized, so a translated record page asked for the default locale's file
+ *     and showed an untranslated body. ⛔ And until 2026-09-27 only a query with
+ *     `deferred:` had one: the list held every other query's records whole.
  *
  * ⛔ `detail:` is no longer AUTHORED (retired 2026-09-13 [Diego]; the build refuses
  * it): its `rest`, `query`, pattern and `{ body, envelope }` forms are an external
@@ -216,7 +218,7 @@ function localizeConfig(cfg, locale, defaultLocale) {
  * @param {string|null} [defaultLocale] - the site's default locale
  * @returns {Object} the original config, or a copy carrying `detail`
  */
-function applyDeferredDetail(cfg, queries, locale = null, defaultLocale = null) {
+function applyRecordFiles(cfg, queries, locale = null, defaultLocale = null) {
   if (cfg.detail !== undefined) return cfg
 
   // The records service answers a RECORD by the query's set narrowed to it, so
@@ -240,11 +242,9 @@ function applyDeferredDetail(cfg, queries, locale = null, defaultLocale = null)
   // is the only key there is. Two shapes, two answers; the deleted one had one
   // shape and pretended otherwise.
   const queryName = cfg.query || bindingKey(cfg)
-  if (!queryName || !queries) return cfg
+  if (!queryName || !queries || typeof cfg.path !== 'string') return cfg
   const collConfig = queries[queryName]
   if (!collConfig || typeof collConfig !== 'object') return cfg
-  const deferred = Array.isArray(collConfig.deferred) ? collConfig.deferred : null
-  if (!deferred || deferred.length === 0) return cfg
   const pattern = recordDataUrl(queryName, '{slug}')
   const localized = locale && locale !== defaultLocale && isDataUrl(pattern) ? `/${locale}${pattern}` : pattern
   return { ...cfg, detail: localized }
@@ -266,7 +266,7 @@ export function isExternalQuery(decl) {
 }
 
 /** Keys a binding may not carry, whatever a stale payload holds — the query supplies them. */
-const QUERY_SUPPLIED = ['scope', 'url', 'method', 'body', 'transform', 'record', 'detail', 'envelope']
+const QUERY_SUPPLIED = ['scope', 'url', 'method', 'body', 'transform', 'record', 'detail', 'envelope', 'routeField']
 
 /**
  * Resolve a query reference to something the fetcher can call.
@@ -412,6 +412,11 @@ function setAndNarrow(out, decl, queryWhere) {
     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
+    // The field its `where` binds the URL's last segment to — what a parametric page of it
+    // matches in place of `$name` (`routeFieldOf`, `./route-match.js`). On every page, so the
+    // query's own page links its records by the same field.
+    const routeField = routeFieldOf(decl)
+    if (routeField) next.routeField = routeField
   }
   const narrow = {}
   if (someWhere(where)) narrow.where = where
@@ -552,12 +557,12 @@ export function resolveFetchConfigs(sources, options = {}) {
       if (!key) continue
       if (configs.has(key)) continue
       if (!collectAll && !schemas.includes(key)) continue
-      // Address first: localization and deferred-detail both key on `path`,
+      // Address first: localization and the record files both key on `path`,
       // which a query ref does not have until this runs.
       const sourced = resolveQuerySource(cfg, services, { queries, locale, defaultLocale })
       const localized = localizeConfig(sourced, locale, defaultLocale)
       const bound = dropRootScope(bindRouteVariables(localized, variables))
-      configs.set(key, stampDepthAndLocale(applyDeferredDetail(bound, queries, locale, defaultLocale), locale, defaultLocale))
+      configs.set(key, stampDepthAndLocale(applyRecordFiles(bound, queries, locale, defaultLocale), locale, defaultLocale))
     }
   }
 
@@ -683,9 +688,9 @@ function bindWhere(where, variables) {
 
 /**
  * ⭐ `scope:` IS ITS OWN FIELD, on both lanes. The service takes it natively; on
- * the compiled file the evaluators apply it to each record's placement (`path`,
- * the folder `records/folder.yml` put it in) — `@uniweb/core`'s `applyScope`, the one the
- * build uses too. ⛔ Until 2026-09-11 it was folded here into
+ * the compiled file the evaluators apply it to the branch each record is held with
+ * (`$branch`, the folder `records/folder.yml` put it in) — `@uniweb/core`'s `applyScope`,
+ * the one the build uses too. ⛔ Until 2026-09-11 it was folded here into
  * `where: { path: { under } }`, an authored form that is now retired in its
  * favour [Diego]: a branch is a scope, and `where` stays the author's predicate.
  *
@@ -976,8 +981,8 @@ export function recordPages(pages, { routeOf, parentOf, fetchOf, sectionsOf, sit
  *
  * `depth` — `brief` when the config has a per-record source (`detail`), because
  * a list with a separate record address is a list of partial records: a live
- * lane answers a list at brief depth and a record in full, and a `deferred:`
- * query's compiled file is the stripped list. `full` otherwise. An explicit
+ * lane answers a list at brief depth and a record in full, and a compiled
+ * query's list holds briefs beside each record's own file. `full` otherwise. An explicit
  * `depth` on the config wins (the records service's client sets it).
  *
  * `locale` — stamped on an ASKED config only. A compiled path already carries

package/src/index.js

@@ -24,7 +24,7 @@ export { substitutePlaceholders } from './substitute-placeholders.js'
 // reads them and a consumer that needs them imports `@uniweb/core/records-service`.
 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'
+export { declaredKeys, sameSchema, fillDeclaredKeys, dataRefOf, WHOLE_SUFFIX } 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'
@@ -55,21 +55,23 @@ export {
   isDataUrl
 } from './data-paths.js'
 export { evaluate as evaluateWhere, match as matchWhere, whereOutsideLanguage } from './where.js'
-// A query's `scope:` over records that carry their placement — read by the runtime's
-// default fetcher and by `@uniweb/build` when it compiles a query's file.
-export { applyScope, withinScope } from './scope.js'
+// A query's `scope:` over compiled records, which hold their branch under `BRANCH_KEY` —
+// read by the runtime's default fetcher and by `@uniweb/build`, which writes it.
+export { applyScope, withinScope, withoutBranch, BRANCH_KEY } from './scope.js'
 // The one sort evaluator and the one href encoder — both read by `@uniweb/build`
 // (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 { evaluateQuery, mapQueryPaths } from './query-evaluation.js'
 export {
   fillRoutePattern,
   splitPathCapture,
   joinPathCapture,
   recordHandle,
+  routeFieldOf,
+  recordKeyValues,
   recordTitle,
   routeParamValue,
   routeParamValues,

package/src/page-data.js

@@ -80,13 +80,13 @@ export function fetchLevels({ own = null, page = null, parent = null, route = nu
  * 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<[string, string|null, boolean]>} 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
+ * @returns {Map<string, { cfg: Object, held: *, whole: boolean }>} declared key → its filling config,
+ *   and whether its component expects whole records, in the order `declared` lists the keys
  */
 export function blockFills({ declared, levels, holds = {}, queries = null, options = {} }) {
   const out = new Map()
@@ -102,11 +102,12 @@ export function blockFills({ declared, levels, holds = {}, queries = null, optio
     if (!firstOfKey.has(fetch.as)) firstOfKey.set(fetch.as, `${at}:${index}`)
   }))
 
+  const wholeKeys = new Set(declared.filter(([, , whole]) => whole).map(([key]) => key))
   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 })
+    out.set(key, { cfg, held, whole: wholeKeys.has(key) })
   }
   return out
 }
@@ -136,8 +137,8 @@ export function pageRecordConfig({ pageFetch = null, parent = null, route, site
 }
 
 /** The record a parametric page is about — the one `current: only` delivers. */
-function isPageRecord({ paramName, paramValue }) {
-  return (item) => matchesRouteParam(item, paramName, paramValue)
+function isPageRecord({ paramName, paramValue }, field = null) {
+  return (item) => matchesRouteParam(item, paramName, paramValue, field)
 }
 
 /**
@@ -153,14 +154,23 @@ function heldWhole(peekRecord, match) {
 
 /**
  * (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.
+ * become. Each `yield` is a request — or a list of requests asked together — and what comes back is
+ * `{ data, error }` (a list of them for a list) — a driver dispatching may report an error, a driver
+ * reading the cache never does, because the cache holds answers only.
+ *
+ * ⭐ **What is asked follows what the component expects** (`whole`, from its `data:` —
+ * `'@std/article/*'`; ruled 2026-09-27 [Diego]). Briefs by default: the records service's question
+ * as it is, a compiled file's list, and on a parametric page the record FOUND in its query's set.
+ * Whole records when declared: the question carries `whole: true`, and a list off the service is
+ * followed by each record's own request. A key declared whole that cannot be filled whole — its
+ * source has no request for one record — is `null`: the contract cannot be met. An external query's
+ * records have no data schema and so no brief: what its source answers is each record whole.
  *
  * ⛔ **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.
+ * must not be indistinguishable from a query with no records. ⛔ Until 2026-09-27 a parametric
+ * page's record was always asked whole, and a failed record request kept the brief the set held —
+ * one shape standing in for the other.
  *
  * @param {Object} cfg - the filling fetch, resolved
  * @param {Object} where
@@ -177,31 +187,43 @@ function heldWhole(peekRecord, match) {
  *   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 }>}
+ * @param {boolean} [where.whole] - the component expects whole records
+ * @returns {Generator<Object|Object[], { value?: *, error?: string, errorConfig?: Object }>}
  */
-export function* keyProgram(cfg, { dynamicContext = null, route = null, held = undefined, peekRecord = null, current: forced = null, opportunistic = false } = {}) {
+export function* keyProgram(cfg, { dynamicContext = null, route = null, held = undefined, peekRecord = null, current: forced = null, opportunistic = false, whole = 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 }
 
+  // ⭐ WHOLE OR BRIEF IS A QUESTION ABOUT RECORDS OF A DATA SCHEMA — the records service's, or a
+  // compiled query's. An external query's records have none, so they have no brief: a list is what
+  // its source answers, and a parametric page's record is its own request's answer (`record:`),
+  // whatever the component expects — as the records service answers a Model with no brief whole,
+  // even as a brief.
+  const external = !cfg.ask && typeof cfg.path !== 'string'
+  if (external) whole = false
+
   // 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 }
+    const asked = whole && cfg.ask ? { ...view, whole: true } : view
+    const answer = yield asked
+    if (answer.error) return { error: answer.error, errorConfig: asked }
     if (answer.data === undefined || answer.data === null) return {}
-    return { value: othersOf(answer.data, cfg, isPageRecord(dynamicContext)) }
+    const others = othersOf(answer.data, cfg, isPageRecord(dynamicContext, cfg.routeField))
+    if (!whole || cfg.ask) return { value: others }
+    return yield* wholeRecordsOf(cfg, others)
   }
 
   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)
+    // and `[]` if not — whole or its brief, as the component expects.
+    const detailCfg = buildDetailConfig(cfg, dynamicContext, { whole })
     // 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).
@@ -228,52 +250,104 @@ export function* keyProgram(cfg, { dynamicContext = null, route = null, held = u
     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
+    const match = items?.find((item) => matchesRouteParam(item, paramName, paramValue, cfg.routeField)) ?? null
     if (!match) return { value: [] } // not found
-    if (!cfg.detail) return { value: [match] }
+    if (external) return yield* ownRecord(cfg, dynamicContext, match, peekRecord, maybe)
+    // A brief is what the set holds: the record is found, and that is the answer.
+    if (!whole) 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] }
+    // ⭐ Held whole already? Then it IS the record — no second request.
+    const wholeHeld = heldWhole(peekRecord, match)
+    if (wholeHeld) return { value: [wholeHeld] }
 
     // ⭐ 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] }
+    // No request for one record: it cannot be had whole.
+    if (!detailCfg) return { value: null }
     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] }
+    if (detail.missing) return {}
+    if (detail.error) return { error: detail.error, errorConfig: detailCfg }
+    return { value: detail.data !== undefined && detail.data !== null ? [detail.data] : [] }
   }
 
   // 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 }
+  const asked = whole && cfg.ask ? { ...cfg, whole: true } : cfg
+  const answer = yield asked
+  if (answer.error) return { error: answer.error, errorConfig: asked }
   if (answer.data === undefined || answer.data === null) return {}
-  return { value: answer.data }
+  if (!whole || cfg.ask) return { value: answer.data }
+  return yield* wholeRecordsOf(cfg, 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 }
+/**
+ * An external query's record: its own request's answer (`record:`), found first in the list. The list
+ * already matched the record, so what it holds is a HELD value: a record with no request of its own,
+ * a failed request — or, for an opportunistic caller, one not yet held — keeps it rather than
+ * delivering `[[]]`.
+ */
+function* ownRecord(cfg, dynamicContext, match, peekRecord, maybe) {
+  // ⭐ Held in full already? Then it IS the record — no second request.
+  const held = heldWhole(peekRecord, match)
+  if (held) return { value: [held] }
+  // ⭐ 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)
+  if (detail.missing) return { value: [match] }
+  if (detail.error) return { value: [match], error: detail.error, errorConfig: detailCfg }
+  return { value: [detail.data !== undefined && detail.data !== null ? detail.data : match] }
+}
+
+/**
+ * A list's records WHOLE, each by its own request — a compiled file's per-record file, an external
+ * query's `record:` — asked together, in one step. `null` when a record has no such request: the list
+ * cannot be had whole, and a component expecting whole records is given none.
+ *
+ * @param {Object} cfg - the list's resolved config
+ * @param {*} records - the list's answer
+ * @returns {Generator<Object[], { value?: *, error?: string, errorConfig?: Object }>}
+ */
+function* wholeRecordsOf(cfg, records) {
+  if (!Array.isArray(records)) return { value: null }
+  if (records.length === 0) return { value: [] }
+  const requests = records.map((record) => recordRequest(cfg, record))
+  if (requests.some((request) => !request)) return { value: null }
+  const answers = yield requests
+  for (let i = 0; i < answers.length; i++) {
+    if (answers[i]?.error) return { error: answers[i].error, errorConfig: requests[i] }
+  }
+  if (answers.some((a) => a?.missing)) return {}
+  return { value: answers.map((a) => a?.data).filter((record) => record !== undefined && record !== null) }
+}
+
+/** The request for one record of a list, by its handle — `buildDetailConfig` with the record in hand. */
+function recordRequest(cfg, record) {
+  const handle = record && typeof record === 'object' ? record.$name : undefined
+  if (handle === undefined || handle === null || handle === '') return null
+  return buildDetailConfig(cfg, { paramName: 'slug', paramValue: String(handle), record })
+}
+
+/** A yielded step as `{ request, optional }` entries: one request, or several asked together. */
+function asSteps(value) {
+  return (Array.isArray(value) ? value : [value]).map((step) =>
+    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 {Map<string, { cfg: Object, held: *, whole?: boolean }>} 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 }))
+  for (const [key, { cfg, held, whole = false }] of fills) {
+    plan.set(key, keyProgram(cfg, { ...where, held, whole }))
   }
   return plan
 }
@@ -302,20 +376,25 @@ export function runPlanSync(plan, { peek }) {
         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
+      const answers = []
+      let missed = false
+      for (const { request, optional } of asSteps(step.value)) {
+        const cached = peek(request)
+        if (cached) answers.push({ data: cached.data })
+        // The program can do without this one and says what it makes of that.
+        else if (optional) answers.push({ missing: true })
+        else {
+          missed = true
+          break
         }
+      }
+      if (missed) {
         // 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 }
+      sent = Array.isArray(step.value) ? answers : answers[0]
     }
   }
 
@@ -327,7 +406,7 @@ export function runPlanSync(plan, { peek }) {
  *
  * ⭐ 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.
+ * later tick, and only that key waits; the requests of one step are issued together.
  *
  * @param {Map<string, Generator>} plan
  * @param {Object} io
@@ -352,8 +431,9 @@ export async function runPlan(plan, { dispatch, onFailure = null }) {
         }
         return
       }
-      const result = await dispatch(asStep(step.value).request)
-      sent = { data: result?.data, error: result?.error }
+      const results = await Promise.all(asSteps(step.value).map(({ request }) => dispatch(request)))
+      const answers = results.map((result) => ({ data: result?.data, error: result?.error }))
+      sent = Array.isArray(step.value) ? answers : answers[0]
     }
   }))
 

package/src/query-evaluation.js

@@ -24,9 +24,9 @@
  */
 
 import { match as matchWhere } from './where.js'
-import { applyScope } from './scope.js'
-import { sortRecords } from './sort.js'
-import { routeParamValues } from './route-match.js'
+import { applyScope, withoutBranch } from './scope.js'
+import { sortRecords, parseSort } from './sort.js'
+import { recordKeyValues } from './route-match.js'
 
 /**
  * Evaluate a resolved config's set and its narrowing over records.
@@ -42,7 +42,10 @@ import { routeParamValues } from './route-match.js'
  * @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
+  if (!Array.isArray(records)) return records
+  // ⛔ What this returns is an ANSWER, and no answer carries a record's branch: `scope` reads
+  // the one a compiled file holds, and it goes no further (`withoutBranch`, ruled 2026-09-27).
+  if (!config || typeof config !== 'object') return withoutBranch(records)
   const order = (items, expr) => sort(items, expr, { locale })
 
   let out = records
@@ -52,11 +55,48 @@ export function evaluateQuery(records, config, { locale = null, sort = sortRecor
   if (isLimit(config.limit)) out = out.slice(0, config.limit)
 
   const narrow = config.narrow
-  if (!narrow || typeof narrow !== 'object') return out
+  if (!narrow || typeof narrow !== 'object') return withoutBranch(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 withoutBranch(out)
+}
+
+/**
+ * A resolved config with every FIELD PATH it names mapped — the `where` keys and the `sort` field of
+ * its set and of its narrowing — so it can be evaluated over records held in another shape. A static
+ * build maps each path to where the record AS STORED holds it (`@uniweb/schemas/conform`'s
+ * `storedPath`), which is how the records service reads a path (ruled 2026-09-27
+ * [Diego]). A `$` key, and `narrow.match` — which names the record, not a
+ * field of it — are kept as they are.
+ *
+ * @param {Object} config - a resolved config, or a question
+ * @param {(path: string) => string} mapPath
+ * @returns {Object} a new config; the input is not mutated
+ */
+export function mapQueryPaths(config, mapPath) {
+  if (!config || typeof config !== 'object' || typeof mapPath !== 'function') return config
+  const level = (at) => {
+    const out = { ...at }
+    if (at.where && typeof at.where === 'object') out.where = mapWherePaths(at.where, mapPath)
+    const spec = at.sort ? parseSort(at.sort) : null
+    if (spec) out.sort = { field: mapPath(spec.field), desc: spec.desc }
+    return out
+  }
+  const out = level(config)
+  if (config.narrow && typeof config.narrow === 'object') out.narrow = level(config.narrow)
+  return out
+}
+
+function mapWherePaths(where, mapPath) {
+  if (!where || typeof where !== 'object' || Array.isArray(where)) return where
+  const out = {}
+  for (const [key, value] of Object.entries(where)) {
+    if (key === 'and' || key === 'or') out[key] = Array.isArray(value) ? value.map((sub) => mapWherePaths(sub, mapPath)) : value
+    else if (key === 'not') out[key] = mapWherePaths(value, mapPath)
+    else out[key.startsWith('$') ? key : mapPath(key)] = value
+  }
   return out
 }
 
@@ -68,20 +108,14 @@ function isLimit(limit) {
 /**
  * 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`).
+ * itself), and its value is compared as a STRING, member-wise on a list
+ * (`recordKeyValues`). ⛔ Until 2026-09-27 a key was mapped back to a param name, so a field
+ * called `slug` read the record's `$name`.
  */
 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)
+    return recordKeyValues(record, 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

@@ -228,8 +228,10 @@ export function splitPathCapture(capture) {
 }
 
 /**
- * The inverse of `splitPathCapture` — a record's own URL path under a
- * `[...path]` template, from its placement and its handle. `dir` may be empty.
+ * The inverse of `splitPathCapture` — a capture from its directory and its last
+ * segment. `dir` may be empty. ⛔ Not a record's URL: a record carries no branch, so its
+ * own URL under `[...path]` is its handle alone (`fillRoutePattern`). Until 2026-09-27 this
+ * composed a record's placement and handle into one.
  *
  * @param {{ dir?: string|null, slug?: string|null }} parts
  * @returns {string|null} null when there is no slug to name the record by
@@ -242,14 +244,19 @@ export function joinPathCapture({ dir, slug } = {}) {
 
 /**
  * A record's PLACEMENT HANDLE — the segment its folder entry is named by, which is
- * what a `[slug]` route (or the last segment of a `[...path]` one) matches.
- *
- * ⭐ Two lanes spell it differently and mean one thing. A host's records service
- * serves the entry's handle as `$name` — `$`-namespaced because a Model may
- * declare its own `name` or `slug` field (five of eight seeded briefs do), and
- * the placement must not be shadowed by one. The file lane derives it from the
- * source filename and calls it `slug`. `$name` wins when present: on a live
- * record a Model field named `slug` is the author's data, not the placement.
+ * what a `[slug]` route (or the last segment of a `[...path]` one) matches: `$name`,
+ * and nothing else.
+ *
+ * ⭐ `$name` is the name of the record as an entry in its folder [Diego, 2026-09-27]: a
+ * host's records service serves it, and the static build gives it as the record file's
+ * name. `$`-namespaced because a record's own fields are the author's data, and no field —
+ * `slug`, `name` — is the placement. A record that is an entry in no folder — an external
+ * API's — has none; its page is found by the field its route query binds the URL to
+ * (`routeFieldOf`, below).
+ * ⛔ Until 2026-09-27 a record with no `$name` fell back to its `slug` field, which
+ * gave one field name a meaning the framework must not assign [Diego, 2026-09-27:
+ * "remove any notion that we, runtime/core, read `slug` from a record's field as if it
+ * had any meaning to us"].
  *
  * @param {Object} record
  * @returns {string|undefined}
@@ -257,8 +264,7 @@ export function joinPathCapture({ dir, slug } = {}) {
 export function recordHandle(record) {
   if (!record || typeof record !== 'object') return undefined
   const name = record.$name
-  if (typeof name === 'string' && name.length) return name
-  return record.slug
+  return typeof name === 'string' && name.length ? name : undefined
 }
 
 /**
@@ -268,7 +274,7 @@ export function recordHandle(record) {
  * parametric page (`Website._createDynamicPage`, so the SPA and a host's render), the
  * static build's page expansion, and the record search index (`@uniweb/projections`).
  *
- *     title  →  name  →  the record's handle (`recordHandle`: `$name`, else `slug`)
+ *     title  →  name  →  the record's handle (`recordHandle`: `$name`)
  *
  * ⛔ Until then a page read `title` alone while the search index read `title || name`,
  * so a record with a `name` and no `title` — a person — titled its search result and
@@ -304,17 +310,17 @@ export function recordTitle(record) {
  * @param {string} paramName
  * @returns {string}
  */
-export function routeRecordKey(paramName) {
-  if (paramName === 'slug') return '$name'
+export function routeRecordKey(paramName, field = null) {
+  if (paramName === 'slug') return typeof field === 'string' && field ? field : '$name'
   if (paramName === 'uuid') return '$uuid'
   return paramName
 }
 
 /**
- * The value a record carries for a route param, by `routeRecordKey`'s map. The two
- * built-in keys fall back to the plain field a source without them carries: the
- * handle to `slug` (`recordHandle`), the identity to `uuid` — so a remote API that
- * routes `[uuid]` on its own `uuid` field keeps matching (ruled 2026-09-11).
+ * The value a record carries for a route param, by `routeRecordKey`'s map. The handle
+ * is `$name` alone (`recordHandle`); the identity falls back to the plain `uuid` field a
+ * source without `$uuid` carries — so a remote API that routes `[uuid]` on its own
+ * `uuid` field keeps matching (ruled 2026-09-11).
  *
  * ⛔ Every reader that matches a delivered record to a route param goes through
  * this — the entity store, the website's parametric page, the static build's
@@ -327,9 +333,9 @@ export function routeRecordKey(paramName) {
  * @param {string} paramName
  * @returns {*}
  */
-export function routeParamValue(record, paramName) {
+export function routeParamValue(record, paramName, field = null) {
   if (!record || typeof record !== 'object') return undefined
-  if (paramName === 'slug') return recordHandle(record)
+  if (paramName === 'slug') return typeof field === 'string' && field ? record[field] : recordHandle(record)
   if (paramName === 'uuid') {
     const id = record.$uuid
     return typeof id === 'string' && id.length ? id : record.uuid
@@ -361,8 +367,28 @@ export function routeParamValue(record, paramName) {
  * @param {string} paramName
  * @returns {string[]} the values, in the record's own order
  */
-export function routeParamValues(record, paramName) {
-  const raw = routeParamValue(record, paramName)
+export function routeParamValues(record, paramName, field = null) {
+  return stringValues(routeParamValue(record, paramName, field))
+}
+
+/**
+ * Every value a record holds under a record KEY — `$name`, `$uuid`, or a field of its own —
+ * as strings, member-wise: what a `narrow.match` key (`routeRecordKey`'s output) is compared
+ * with. ⛔ Not `routeParamValues` over a param name: a field called `slug` is the author's data,
+ * while the param `slug` names the record's `$name`.
+ *
+ * @param {Object} record
+ * @param {string} key
+ * @returns {string[]}
+ */
+export function recordKeyValues(record, key) {
+  if (!record || typeof record !== 'object') return []
+  if (key === '$name') return stringValues(recordHandle(record))
+  if (key === '$uuid') return stringValues(routeParamValue(record, 'uuid'))
+  return stringValues(record[key])
+}
+
+function stringValues(raw) {
   const out = []
   for (const value of Array.isArray(raw) ? raw : [raw]) {
     if (value === undefined || value === null || value === '') continue
@@ -382,11 +408,36 @@ export function routeParamValues(record, paramName) {
  * @param {Object} record
  * @param {string} paramName
  * @param {string|number} value - the URL segment
+ * @param {string|null} [field] - the field the route query binds `:slug` to (`routeFieldOf`)
  * @returns {boolean}
  */
-export function matchesRouteParam(record, paramName, value) {
+export function matchesRouteParam(record, paramName, value, field = null) {
   const target = String(value)
-  return routeParamValues(record, paramName).some((held) => held === target)
+  return routeParamValues(record, paramName, field).some((held) => held === target)
+}
+
+/**
+ * The record field a route query binds the URL's last segment to — `where: { code: ':slug' }`
+ * → `code` — or null when it binds none.
+ *
+ * ⭐ A PARAMETRIC PAGE'S RECORD IS ITS ROUTE QUERY'S TO FIND [Diego, 2026-09-27: "it's put to a
+ * parametric query to choose"]. By default a `[slug]` page (and a `[...path]` page's last segment)
+ * names a record by its `$name`, the name it has as an entry in its folder. A query whose records
+ * are named otherwise — an external API's, which are entries in no folder — says which of their
+ * fields the URL names by binding the segment in its own `where`; the page then matches that
+ * field, its records link by it, and a static build expands over it. On the query's own page the
+ * clause drops, since no URL binds it. Only a top-level clause whose whole value is `:slug` counts.
+ *
+ * @param {Object|null} decl - a query declaration (`config.queries[<name>]`)
+ * @returns {string|null}
+ */
+export function routeFieldOf(decl) {
+  const where = decl && typeof decl === 'object' ? decl.where : null
+  if (!where || typeof where !== 'object' || Array.isArray(where)) return null
+  for (const [key, value] of Object.entries(where)) {
+    if (value === ':slug' && key !== 'and' && key !== 'or' && key !== 'not' && !key.startsWith('$')) return key
+  }
+  return null
 }
 
 /**
@@ -527,34 +578,35 @@ export function recordRouteBase(route) {
  *
  * @param {string} pattern - a route pattern with `:param` placeholders
  * @param {Object} values - a record, read by param name
+ * @param {{ field?: string|null }} [options] - `field`: the record field `:slug` is filled from
+ *   when the route query binds it (`routeFieldOf`); by default the record's `$name`
  * @returns {string|null}
  */
-export function fillRoutePattern(pattern, values) {
+export function fillRoutePattern(pattern, values, { field = null } = {}) {
   if (typeof pattern !== 'string' || !values || typeof values !== 'object') return null
   let missing = false
   let head = pattern
   let tailHref = ''
   const tail = pattern.match(CATCH_ALL)
   if (tail) {
-    // A catch-all is filled from the record's placement and handle — the split
-    // rule in reverse (`joinPathCapture`) — with each SEGMENT encoded and the
-    // slashes between them kept as structure. `dir` is the placement; a record
-    // carries it as `path` (the folder `records/folder.yml` put it in), which is why
-    // `path` here is read as the DIRECTORY and never as a composed capture.
-    const handle = recordHandle(values)
-    if (joinPathCapture({ dir: values.dir ?? values.path, slug: handle }) === null) return null
-    const dir = String(values.dir ?? values.path ?? '')
-    const segments = dir.split('/').filter(Boolean).map((seg) => encodeURIComponent(seg))
-    // The handle is ONE segment whatever it contains: a `/` inside it is a value.
-    segments.push(encodeURIComponent(String(handle)))
-    tailHref = '/' + segments.join('/')
+    // ⭐ A catch-all is filled with the record's handle ALONE — one segment, whatever it
+    // contains (a `/` inside it is a value). A record carries no branch [Diego,
+    // 2026-09-27], so its own URL under `[...path]` is the one it has under `[slug]`:
+    // `/logbook/<name>`. A URL that names a directory still reaches the page, and
+    // `scope: :dir` is what makes the directory count. ⛔ Until 2026-09-27 this prefixed the
+    // record's `path`, so one record was linked at `/logbook/field/river-survey` on a static
+    // site and at `/logbook/river-survey` where a records service, which answers no branch,
+    // served it.
+    const [handle] = routeParamValues(values, 'slug', field)
+    if (handle === undefined) return null
+    tailHref = '/' + encodeURIComponent(String(handle))
     head = pattern.slice(0, tail.index)
   }
   const href = head.replace(new RegExp(`:(${PARAM_NAME})`, 'g'), (_, name) => {
     // ⭐ THE FIRST MEMBER of a `multi` field — a record has ONE canonical href, and
     // every member routes to it (`routeParamValues`). Baked whole, a `['a','b']`
     // field produced `/tags/a%2Cb`, a URL no lane matches.
-    const [value] = routeParamValues(values, name)
+    const [value] = routeParamValues(values, name, name === 'slug' ? field : null)
     if (value === undefined) {
       missing = true
       return ''

package/src/scope.js

@@ -1,11 +1,19 @@
 /**
- * A query's `scope:` — the folder branch it reads — evaluated over records that
- * carry their placement.
+ * A query's `scope:` — the folder branch it reads — evaluated over compiled records,
+ * which hold their branch.
  *
- * A record's `path` is the folder `records/folder.yml` placed it in (`build/src/site/
- * query-processor.js`). A scope contains that folder and every folder below it, at
- * SEGMENT boundaries: `field` holds `field` and `field/2025`, never `fieldwork`.
- * The root (`''`) holds everything.
+ * A compiled record holds the folder `records/folder.yml` placed it in under
+ * `$branch` (`BRANCH_KEY`, written by `build/src/site/query-processor.js`). A scope
+ * contains that folder and every folder below it, at SEGMENT boundaries: `field`
+ * holds `field` and `field/2025`, never `fieldwork`. The root (`''`) holds everything.
+ *
+ * ⛔ A RECORD DOES NOT CARRY ITS BRANCH (ruled 2026-09-27 [Diego]: *"branches are to
+ * organize the content pool … queries can filter by branch using `scope`"*). `$branch`
+ * is the compiled file's own key, there because the browser evaluates `scope` over that
+ * file. `evaluateQuery` reads it and answers no record with it (`withoutBranch`), just as
+ * a records service answers none. ⛔ Until then every compiled record carried `path`,
+ * which reached components, overwrote an authored field named `path`, and made a
+ * `[...path]` record's link `<branch>/<name>`.
  *
  * ⭐ Why this is its own field and not a `where` operator: a branch is a scope,
  * and `where` stays the author's predicate over the records' own fields. Ruled
@@ -18,6 +26,31 @@
  * Zero-dependency leaf.
  */
 
+/**
+ * The key a compiled record holds its branch under. The static lane's store only; no
+ * answer carries it.
+ */
+export const BRANCH_KEY = '$branch'
+
+/**
+ * Records as a query answers them: without the branch their compiled file holds. A list
+ * in which no record holds one is returned as it is.
+ *
+ * @param {Array<Object>} records
+ * @returns {Array<Object>}
+ */
+export function withoutBranch(records) {
+  if (!Array.isArray(records)) return records
+  if (!records.some((r) => r && typeof r === 'object' && Object.prototype.hasOwnProperty.call(r, BRANCH_KEY))) {
+    return records
+  }
+  return records.map((r) => {
+    if (!r || typeof r !== 'object' || !Object.prototype.hasOwnProperty.call(r, BRANCH_KEY)) return r
+    const { [BRANCH_KEY]: _branch, ...rest } = r
+    return rest
+  })
+}
+
 function trimSlashes(s) {
   return s.replace(/^\/+/, '').replace(/\/+$/, '')
 }
@@ -29,7 +62,7 @@ function trimSlashes(s) {
  * `2024`, the classic prefix bug, which silently returns records from a sibling
  * folder the author never named.
  *
- * @param {*} placement - a record's `path`
+ * @param {*} placement - a compiled record's branch (`BRANCH_KEY`)
  * @param {string} scope
  * @returns {boolean}
  */
@@ -52,5 +85,5 @@ export function withinScope(placement, scope) {
 export function applyScope(records, scope) {
   if (!Array.isArray(records)) return records
   if (typeof scope !== 'string' || trimSlashes(scope) === '') return records
-  return records.filter((r) => r && typeof r === 'object' && withinScope(r.path, scope))
+  return records.filter((r) => r && typeof r === 'object' && withinScope(r[BRANCH_KEY], scope))
 }