@uniweb/core 0.18.0 → 0.20.0

package/src/entity-store.js

@@ -15,46 +15,56 @@
  */
 
 import { isFetchRefinement, resolveFetchConfigs } from './fetch-config.js'
+import { fillRoutePattern } from './route-match.js'
+import { sortRecords } from './sort.js'
 
 /**
  * A fetch config's binding key — the `content.data.<key>` a component reads.
  * `as` is the name; `schema` is what it was called until 2026-09-02 and still
  * arrives on any payload published before then. See `fetch-config.js`.
  */
-const bindingKeyOf = (cfg) => cfg?.as ?? cfg?.schema
+const bindingKeyOf = (cfg) => cfg?.as
 import { buildDetailConfig } from './detail-url.js'
 
 /**
  * Is `block.fetch` a per-instance refinement of the ancestor's fetch config
- * rather than a new source? The canonical spelling is `refine: true`; the
- * legacy spelling `inherit: true` is still honored for one release with a
- * dev-mode warning.
+ * rather than a new source? The spelling is `refine: true`.
  *
  * The predicate itself lives in `./fetch-config.js` with the rest of the
  * cascade rule; this alias keeps the local call sites reading as they did.
  */
 const isRefinement = isFetchRefinement
 
-let inheritDeprecationWarned = false
-function warnInheritDeprecation(block) {
-  if (inheritDeprecationWarned) return
-  inheritDeprecationWarned = true
-  // Dev-only; production builds typically strip console.warn. We gate on
-  // the presence of the deprecated key and fire once per process.
-  console.warn(
-    "[uniweb] 'fetch: { inherit: true }' is deprecated; rename to 'fetch: { refine: true }'. " +
-    'Accepted for one release; will be removed in the next minor. ' +
-    `First seen on block ${block?.id ?? '(unknown)'} of page ${block?.page?.route ?? '(unknown)'}.`
-  )
+/**
+ * `fetch: { inherit: true }` was the earlier spelling of `refine: true`, kept
+ * "for one release" from April 2026 and removed on 2026-09-02. It is refused
+ * rather than ignored: ignored, the declaration would read as a source with no
+ * location and the block would render empty with nothing to say why. Dev
+ * throws, so a page does not render on the old spelling; production logs once
+ * and the caller drops the declaration, so the block receives the cascaded
+ * data unrefined.
+ */
+let inheritRefusalLogged = false
+function refuseInheritAlias(block, dev) {
+  const message =
+    "[uniweb] 'fetch: { inherit: true }' is no longer accepted; write 'fetch: { refine: true }'. " +
+    `Seen on block ${block?.id ?? '(unknown)'} of page ${block?.page?.route ?? '(unknown)'}.`
+  if (dev) throw new Error(message)
+  if (inheritRefusalLogged) return
+  inheritRefusalLogged = true
+  console.error(message)
 }
 
 export default class EntityStore {
   /**
    * @param {Object} options
    * @param {import('./website.js').default} options.website
+   * @param {boolean} [options.dev=false] - dev mode: a retired spelling throws
+   *   instead of logging once.
    */
-  constructor({ website }) {
+  constructor({ website, dev = false }) {
     this.website = website
+    this.dev = dev
     Object.seal(this)
   }
 
@@ -77,18 +87,13 @@ export default class EntityStore {
     return null
   }
 
+  /**
+   * A refine block's `order: { orderBy, sortOrder }` — the same one-key sort the
+   * build and the fetcher fallback run (`./sort.js`), so the three cannot drift.
+   */
   _sortItems(items, order) {
-    if (!order?.orderBy || !Array.isArray(items) || items.length === 0) return items
-    const { orderBy, sortOrder = 'ASC' } = order
-    const desc = sortOrder === 'DESC'
-    return [...items].sort((a, b) => {
-      const av = a[orderBy] ?? ''
-      const bv = b[orderBy] ?? ''
-      const cmp = typeof av === 'string' && typeof bv === 'string'
-        ? av.localeCompare(bv)
-        : (av > bv ? 1 : av < bv ? -1 : 0)
-      return desc ? -cmp : cmp
-    })
+    if (!order?.orderBy) return items
+    return sortRecords(items, { field: order.orderBy, desc: order.sortOrder === 'DESC' })
   }
 
   /**
@@ -116,16 +121,25 @@ export default class EntityStore {
    * exists to prevent.
    */
   _findFetchConfigs(block, requested) {
-    if (block.fetch?.inherit === true && block.fetch?.refine !== true) {
-      warnInheritDeprecation(block)
+    let blockFetch = block.fetch
+    if (blockFetch?.inherit !== undefined) {
+      refuseInheritAlias(block, this.dev)
+      blockFetch = null
     }
 
     const page = block.page
     const website = block.website
+    const dynamicContext = block.dynamicContext || page?.dynamicContext
+    // The route's variables, for a query that binds `:path` / `:dir` / `:slug`.
+    // A baked page carries `params` when it has more than the one capture;
+    // otherwise the capture itself is the only variable.
+    const variables = dynamicContext
+      ? (dynamicContext.params ?? { [dynamicContext.paramName]: dynamicContext.paramValue })
+      : null
 
     return resolveFetchConfigs(
       [
-        block.fetch && !isRefinement(block.fetch) ? block.fetch : null,
+        blockFetch && !isRefinement(blockFetch) ? blockFetch : null,
         page?.fetch,
         page?.parent?.fetch,
         website?.config?.fetch,
@@ -142,6 +156,7 @@ export default class EntityStore {
         // local dev, which is why `resolveQuerySource` treats absence as
         // the ordinary case and reads the compiled artifact without comment.
         records: website?.config?.records ?? null,
+        variables,
       },
     )
   }
@@ -244,6 +259,16 @@ export default class EntityStore {
         } else {
           allCached = false
         }
+      } else if (isRouteQuery && cfg.door) {
+        // A question door: the record's own answer is cached under its own key.
+        const detailCfg = this._buildDetailConfig(cfg, dynamicContext)
+        const detailCached = detailCfg ? dispatcher?.peek(detailCfg, ctx) : null
+        if (detailCached) {
+          const answer = Array.isArray(detailCached.data) ? detailCached.data : (detailCached.data ? [detailCached.data] : [])
+          data[schema] = answer.slice(0, 1)
+        } else {
+          allCached = false
+        }
       } else if (isRouteQuery) {
         // Detail page: deliver the focused record as a length-1 array under the
         // query key. A deferred/remote query fetches the full per-record;
@@ -258,9 +283,15 @@ export default class EntityStore {
           if (!match) {
             data[schema] = []
           } else if (cfg.detail) {
-            const detailCfg = this._buildDetailConfig(cfg, dynamicContext)
+            // ⭐ Held in full already? Then it IS the record — no detail probe.
+            // The list is materialized from the record index, so `match` is the
+            // record at its latest depth; the index says which depth that is.
+            const held = heldInFull(dispatcher, match)
+            const detailCfg = held ? null : this._buildDetailConfig(cfg, { ...dynamicContext, record: match })
             const detailCached = detailCfg ? dispatcher?.peek(detailCfg, ctx) : null
-            if (detailCfg && detailCached) {
+            if (held) {
+              data[schema] = [held]
+            } else if (detailCfg && detailCached) {
               data[schema] = [detailCached.data]
             } else if (detailCfg) {
               allCached = false
@@ -295,13 +326,23 @@ export default class EntityStore {
    * Async fetch — dispatches missing configs through the FetcherDispatcher
    * and assembles the result. List-first detail ordering preserved.
    *
+   * ⛔ A FAILED FETCH DELIVERS NOTHING UNDER ITS KEY, AND SAYS SO. Until 2026-09-04
+   * a failure wrote `[]` into `content.data` — the fetcher returns `{ data: [], error }`,
+   * `[]` is neither `undefined` nor `null`, and nothing read `error` — so a key
+   * whose request failed was indistinguishable from one that succeeded with no
+   * records, by the framework's own rule that `[]` is a value. Now the key is
+   * ABSENT from `data`, the message is on `errors[key]`, and in dev it is logged
+   * where the author is looking. A detail fetch that fails keeps the record the
+   * list already matched (the brief) rather than clobbering it.
+   *
    * @param {Object} [options]
    * @param {AbortSignal} [options.signal] - Forwarded to the dispatcher.
-   * @returns {Promise<{ data: Object|null }>}
+   * @returns {Promise<{ data: Object|null, errors: Object|null }>} `data` keyed by
+   *   binding key; `errors` keyed the same way, `null` when every fetch succeeded.
    */
   async fetch(block, meta, { signal } = {}) {
     const dispatcher = this.website?.fetcher
-    if (!dispatcher) return { data: null }
+    if (!dispatcher) return { data: null, errors: null }
 
     let requested = this._getRequestedSchemas(meta)
     if (requested === null && block.fetch) {
@@ -309,10 +350,10 @@ export default class EntityStore {
       const schemas = blockFetchList.filter(bindingKeyOf).map(bindingKeyOf)
       if (schemas.length > 0) requested = schemas
     }
-    if (requested === null) return { data: null }
+    if (requested === null) return { data: null, errors: null }
 
     const configs = this._findFetchConfigs(block, requested)
-    if (configs.size === 0) return { data: null }
+    if (configs.size === 0) return { data: null, errors: null }
 
     const dynamicContext = block.dynamicContext || block.page?.dynamicContext
     const inheritDetail = this._shouldInheritDetail(meta, block)
@@ -321,7 +362,12 @@ export default class EntityStore {
     const ctx = this._ctx(block, { signal })
 
     const data = {}
+    const errors = {}
     const parallelFetches = []
+    const fail = (key, cfg, message) => {
+      errors[key] = message
+      reportFetchFailure(this.dev, block, key, cfg, message)
+    }
 
     const routeSchema = dynamicContext?.schema
 
@@ -332,6 +378,10 @@ export default class EntityStore {
         let records = peekArray(dispatcher, cfg, ctx)
         if (records === null) {
           const result = await dispatcher.dispatch(cfg, ctx)
+          if (result?.error) {
+            fail(schema, cfg, result.error)
+            continue
+          }
           records = Array.isArray(result?.data) ? result.data : null
         }
         const { paramName, paramValue } = dynamicContext
@@ -340,6 +390,25 @@ export default class EntityStore {
           : (records ?? [])
         if (order) filtered = this._sortItems(filtered, order)
         data[schema] = limit && Array.isArray(filtered) ? filtered.slice(0, limit) : filtered
+      } else if (isRouteQuery && cfg.door) {
+        // ⭐ A QUESTION DOOR needs no list to find the record: the record is the
+        // same question narrowed by the route's handle, so list and record are
+        // asked together — one round trip, and no client-side scan gating the
+        // fetch (F13, the live half). The list is asked too, because sections
+        // beside the record read it (`refine: true, detail: false`) and the
+        // index files its briefs; the record's own answer is the answer.
+        const detailCfg = this._buildDetailConfig(cfg, dynamicContext)
+        parallelFetches.push(dispatcher.dispatch(cfg, ctx).then((result) => {
+          if (result?.error) fail(schema, cfg, result.error)
+        }))
+        parallelFetches.push(dispatcher.dispatch(detailCfg, ctx).then((result) => {
+          if (result?.error) {
+            fail(schema, detailCfg, result.error)
+            return
+          }
+          const answer = Array.isArray(result?.data) ? result.data : (result?.data ? [result.data] : [])
+          data[schema] = answer.slice(0, 1) // a route resolves to ONE; `[]` is not found
+        }))
       } else if (isRouteQuery) {
         // Detail page: focused record as a length-1 array under the query key.
         const { paramName, paramValue } = dynamicContext
@@ -347,6 +416,10 @@ export default class EntityStore {
         let records = peekArray(dispatcher, cfg, ctx)
         if (records === null) {
           const result = await dispatcher.dispatch(cfg, ctx)
+          if (result?.error) {
+            fail(schema, cfg, result.error)
+            continue
+          }
           records = Array.isArray(result?.data) ? result.data : null
         }
 
@@ -359,11 +432,25 @@ export default class EntityStore {
           continue
         }
 
-        if (cfg.detail) {
-          const detailCfg = this._buildDetailConfig(cfg, dynamicContext)
+        const held = cfg.detail ? heldInFull(dispatcher, match) : null
+        if (held) {
+          // R1: the record index holds it in full — a detail fetch would only
+          // re-fetch what the page already has.
+          data[schema] = [held]
+        } else if (cfg.detail) {
+          const detailCfg = this._buildDetailConfig(cfg, { ...dynamicContext, record: match })
           if (detailCfg) {
             parallelFetches.push(
               dispatcher.dispatch(detailCfg, ctx).then((result) => {
+                // The list already matched the record, so the brief is a HELD
+                // value: a failed detail fetch keeps it and reports, rather than
+                // delivering `[[]]` — which is what `result.data ?? match` did,
+                // because a failure's `data` is `[]`, not null.
+                if (result?.error) {
+                  fail(schema, detailCfg, result.error)
+                  data[schema] = [match]
+                  return
+                }
                 const record = (result?.data !== undefined && result?.data !== null)
                   ? result.data
                   : match
@@ -379,8 +466,15 @@ export default class EntityStore {
       } else {
         parallelFetches.push(
           dispatcher.dispatch(cfg, ctx).then((result) => {
+            if (result?.error) {
+              fail(schema, cfg, result.error)
+              return
+            }
             if (result?.data !== undefined && result?.data !== null) {
-              data[schema] = result.data
+              // The same refine `order` the sync path applies (`resolve`), so a
+              // block sorts identically on a cache hit and on the fetch that
+              // filled it — it did not until 2026-09-04.
+              data[schema] = order ? this._sortItems(result.data, order) : result.data
             }
           })
         )
@@ -389,10 +483,45 @@ export default class EntityStore {
 
     if (parallelFetches.length > 0) await Promise.all(parallelFetches)
     this._applyDetailRoutes(data, configs, block.website)
-    return { data }
+    return { data, errors: Object.keys(errors).length ? errors : null }
   }
 }
 
+/**
+ * Say where a fetch failed, once per key per page, where the author is looking.
+ *
+ * Dev only: production has no reader for a console line, and the page has the
+ * structured answer already — the key is absent from `data`, the message is on
+ * `errors[key]`, and the runtime sets `block.dataError`. What must never happen
+ * again is the third option this path used to take: an empty array under the
+ * key, and silence.
+ */
+const reportedFailures = new Set()
+function reportFetchFailure(dev, block, key, cfg, message) {
+  if (!dev) return
+  const where = cfg?.endpoint || cfg?.url || cfg?.path || '(no address)'
+  const page = block?.page?.route ?? '(unknown page)'
+  const memo = `${page}::${key}::${where}`
+  if (reportedFailures.has(memo)) return
+  reportedFailures.add(memo)
+  console.error(
+    `[uniweb] fetch for content.data.${key} failed on ${page} (${where}): ${message}. ` +
+      `The key is left absent — not [] — and block.dataError carries this message.`
+  )
+}
+
+/**
+ * The record the index holds in FULL for a list match, or null — the R1 gate.
+ * A record with no identity (`$uuid`) is never indexed, so the answer for it is
+ * null and the detail fetch proceeds as before.
+ */
+function heldInFull(dispatcher, match) {
+  const id = match?.$uuid
+  if (typeof id !== 'string' || !id || typeof dispatcher?.peekRecord !== 'function') return null
+  const held = dispatcher.peekRecord(id)
+  return held?.depth === 'full' ? held.record : null
+}
+
 /**
  * Sync-peek helper: return the cached array for a config, or null on miss.
  */
@@ -411,17 +540,12 @@ function peekArray(dispatcher, cfg, ctx) {
  * (the file lane bakes one via the query processor) is returned untouched. A
  * `:param` with no matching record field → no `route` (graceful; degrades to the
  * component's own fallback rather than emitting a broken href).
+ *
+ * ⭐ The encoding is `fillRoutePattern`'s, shared with the build's bake, so the
+ * two producers of `item.route` agree — they did not (F14, 2026-09-04).
  */
 function addDetailRoute(item, template) {
   if (!item || typeof item !== 'object' || item.route !== undefined) return item
-  let missing = false
-  const route = template.replace(/:(\w+)/g, (_, name) => {
-    const value = item[name]
-    if (value == null) {
-      missing = true
-      return ''
-    }
-    return encodeURIComponent(String(value))
-  })
-  return missing ? item : { ...item, route }
+  const route = fillRoutePattern(template, item)
+  return route === null ? item : { ...item, route }
 }

package/src/fetch-config.js

@@ -28,21 +28,22 @@
  */
 
 import { queryDataUrl, isDataUrl, recordDataUrl } from './data-paths.js'
-import { resolveQueryAddress, resolveRecordAddressPattern } from './query-address.js'
+import { resolveQueryAddress, resolveRecordAddressPattern, resolveQueryDoor } from './query-address.js'
 
 /**
  * Is this fetch declaration a per-instance *refinement* of an ancestor's
  * config rather than a new source of its own?
  *
- * The canonical spelling is `refine: true`. The legacy spelling `inherit: true`
- * is still honored; callers that want to warn about it should test for the key
- * themselves — this predicate stays silent so it is safe in any environment.
+ * The spelling is `refine: true`. Its earlier alias, `inherit: true`, was
+ * accepted with a warning from April 2026 and removed on 2026-09-02: the build
+ * refuses it with an error, and `EntityStore` refuses it in dev. This predicate
+ * stays silent so it is safe in any environment.
  *
  * @param {Object} cfg - a fetch declaration
  * @returns {boolean}
  */
 export function isFetchRefinement(cfg) {
-  return cfg?.refine === true || cfg?.inherit === true
+  return cfg?.refine === true
 }
 
 /**
@@ -99,6 +100,10 @@ function localizeConfig(cfg, locale, defaultLocale) {
 function applyDeferredDetail(cfg, queries, records) {
   if (cfg.detail !== undefined) return cfg
 
+  // A question door answers a RECORD by the same question narrowed to it, so
+  // every door config has a detail source; `buildDetailConfig` composes it.
+  if (cfg.door) return { ...cfg, detail: true }
+
   // ⭐ A lane's record address is injected whenever the lane declares one —
   // NOT only for a `deferred:` query, and the difference is load-bearing.
   //
@@ -169,9 +174,32 @@ function applyDeferredDetail(cfg, queries, records) {
  * `query`, ignoring any `path`), so the two agree rather than disagreeing on a
  * shape nobody hand-writes.
  */
-function resolveQuerySource(cfg, records) {
+function resolveQuerySource(cfg, records, { queries = null, locale = null, defaultLocale = null } = {}) {
   if (typeof cfg.query !== 'string' || cfg.query.length === 0) return cfg
 
+  // ⭐ THE QUESTION DOOR 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 door's contract, §2). It
+  // needs the query's MODEL REF, which lives on the site's `config.queries`
+  // declaration; a payload that carries the door but not the declaration
+  // cannot ask, and falls through to the address door below. ⚠️ Dark until a
+  // host stamps the door; see `resolveQueryDoor`.
+  const door = resolveQueryDoor(records, locale ?? defaultLocale)
+  if (door) {
+    const decl = queries && typeof queries === 'object' ? queries[cfg.query] : null
+    const schema = typeof decl?.schema === 'string' && decl.schema ? decl.schema : null
+    if (schema) {
+      const { path, url, ...rest } = cfg
+      const asked = { ...rest, door, schema }
+      // A saved query's own narrowing applies unless the fetch overrides it.
+      if (asked.scope === undefined && typeof decl.scope === 'string') asked.scope = decl.scope
+      if (asked.where === undefined && decl.where && typeof decl.where === 'object') asked.where = decl.where
+      if (asked.sort === undefined && decl.sort !== undefined && decl.sort !== null) asked.sort = decl.sort
+      if (asked.limit === undefined && typeof decl.limit === 'number' && decl.limit > 0) asked.limit = decl.limit
+      return asked
+    }
+  }
+
   const endpoint = resolveQueryAddress(cfg.query, records)
   if (endpoint) {
     // Drop the transitional `path`: two addresses on one request is an
@@ -185,23 +213,31 @@ function resolveQuerySource(cfg, records) {
 /**
  * The binding key of a fetch config — the `content.data.<key>` a component reads.
  *
- * ⭐ **`as` is the name; `schema` is what it was called until 2026-09-02.** The old
- * spelling still arrives on every payload published before then and on any seed
- * built against an older release, so this is not a deprecation window — it is a
- * permanent reader of stored data. *(Renaming it was not cosmetic: `schema`
- * already means the MODEL REF one record over, on a `queries` declaration, and
- * one word for two things is what let a binding-key override silently break
- * detail resolution.)*
+ * ⭐ **`as` is the name.** It was called `schema` until 2026-09-02, which
+ * collided with the MODEL REF of the same name on a `queries` declaration — one
+ * word for two things, which is what let a binding-key override silently break
+ * detail resolution.
+ *
+ * ⛔ **The `?? cfg.schema` alias that briefly rode alongside it is GONE**
+ * (2026-09-02, ruled by Diego: *"they are not in prod so I saw no point in it.
+ * We need to move forward."*). It was removed in the same pass as frontend's and
+ * hosting's, and every producer here now emits `as` alone.
  *
- * ⛔ Do not "simplify" this to `cfg.as`. The `??` here is earned — it spans
- * stored payloads we cannot rewrite — unlike the one deleted from
- * `applyDeferredDetail`, which spanned two producers we control.
+ * ⚠️ **The consequence, stated plainly: a payload synced before that carries
+ * `schema` and resolves to NOTHING here.** No data, no error — this is the
+ * silent class, and the remedy is a re-push, not a code change. If a
+ * seed or a dev site renders a section empty, check what its stored payload
+ * spells before looking anywhere else.
+ *
+ * ⭐ The one place `schema` is still read is `parseFetchConfig` in
+ * `@uniweb/build`, and it is a different thing: normalizing an AUTHOR's older
+ * spelling in a content file at the boundary, so that one name travels inside.
  *
  * @param {Object} cfg
  * @returns {string|undefined}
  */
 function bindingKey(cfg) {
-  return cfg?.as ?? cfg?.schema
+  return cfg?.as
 }
 
 /**
@@ -228,6 +264,10 @@ function bindingKey(cfg) {
  * @param {Object|null} [options.records] - the site's `config.records`, a host's
  *   live-records lane. Absent means the compiled artifact answers, which is
  *   the whole of what a site with no backend needs.
+ * @param {Object|null} [options.variables] - the route's variables on a template
+ *   page (`{ path, dir, slug }` under `[...path]`, the capture under `[slug]`);
+ *   a `:path` / `:dir` / `:slug` placeholder in `where:` or `scope:` binds to
+ *   them, and an unbound one drops its clause. Null off a template page.
  * @returns {Map<string, Object>} schema name → resolved config
  */
 export function resolveFetchConfigs(sources, options = {}) {
@@ -237,6 +277,7 @@ export function resolveFetchConfigs(sources, options = {}) {
     defaultLocale = null,
     queries = null,
     records = null,
+    variables = null,
   } = options
 
   const configs = new Map()
@@ -252,11 +293,144 @@ export function resolveFetchConfigs(sources, options = {}) {
       if (!collectAll && !schemas.includes(key)) continue
       // Address first: localization and deferred-detail both key on `path`,
       // which a query ref does not have until this runs.
-      const sourced = resolveQuerySource(cfg, records)
+      const sourced = resolveQuerySource(cfg, records, { queries, locale, defaultLocale })
       const localized = localizeConfig(sourced, locale, defaultLocale)
-      configs.set(key, applyDeferredDetail(localized, queries, records))
+      const bound = foldScope(bindRouteVariables(localized, variables))
+      configs.set(key, stampDepthAndLocale(applyDeferredDetail(bound, queries, records), locale, defaultLocale))
     }
   }
 
   return configs
 }
+
+/**
+ * The three route variables a query may reference, and only these — `:path`,
+ * `:dir`, `:slug` — as a VALUE in `where:` or as the whole `scope:`. Ruled
+ * 2026-09-04 [Diego]: standard names, never author-chosen; a placeholder fills
+ * a value, never a key or an operator, never `schema`.
+ */
+const ROUTE_VARIABLE = /^:(path|dir|slug)$/
+
+/**
+ * Bind a query's route placeholders from the page's variables.
+ *
+ * ⭐ UNBOUND ⇒ THE CLAUSE DROPS. That is what lets ONE saved query serve both
+ * the list page and the detail page: `where: { tag: :dir }` narrows on
+ * `/blog/rust/my-post` and vanishes on `/blog`, where there is no `:dir`. A
+ * variable bound to an empty string (`:dir` on a single-segment capture) is
+ * bound, and binds the empty value. Backend's records door states the same
+ * rule from its side (the records door's contract, §6b).
+ *
+ * ⚠️ The price, stated where it is paid: a MISSPELLED variable is byte-identical
+ * to an intentional list page. Only an authoring surface can catch that; this
+ * function cannot.
+ *
+ * @param {Object} cfg - a resolved config
+ * @param {Object|null} variables - `{ path, dir, slug, … }` from the route, or null off a template page
+ * @returns {Object} the config, with placeholders bound or their clauses dropped
+ */
+function bindRouteVariables(cfg, variables) {
+  let out = cfg
+  if (typeof cfg.scope === 'string' && ROUTE_VARIABLE.test(cfg.scope)) {
+    const name = cfg.scope.slice(1)
+    const value = variables?.[name]
+    const { scope, ...rest } = out
+    out = value === undefined || value === null ? rest : { ...rest, scope: String(value) }
+  }
+  if (cfg.where && typeof cfg.where === 'object') {
+    const bound = bindWhere(cfg.where, variables)
+    if (bound !== cfg.where) {
+      const { where, ...rest } = out
+      out = bound === null ? rest : { ...rest, where: bound }
+    }
+  }
+  return out
+}
+
+/** Walk a where-object: bind `:var` VALUES, drop clauses whose variable is unbound. */
+function bindWhere(where, variables) {
+  if (Array.isArray(where)) {
+    let changed = false
+    const next = []
+    for (const item of where) {
+      const b = item && typeof item === 'object' ? bindWhere(item, variables) : item
+      if (b !== item) changed = true
+      if (b !== null) next.push(b)
+    }
+    if (!changed) return where
+    return next.length ? next : null
+  }
+  if (!where || typeof where !== 'object') return where
+  let changed = false
+  const next = {}
+  for (const [key, value] of Object.entries(where)) {
+    if (typeof value === 'string' && ROUTE_VARIABLE.test(value)) {
+      const bound = variables?.[value.slice(1)]
+      changed = true
+      if (bound === undefined || bound === null) continue // unbound ⇒ drop
+      next[key] = String(bound)
+      continue
+    }
+    if (value && typeof value === 'object') {
+      const b = bindWhere(value, variables)
+      if (b !== value) changed = true
+      if (b === null) continue // an operator object or sub-predicate emptied out
+      next[key] = b
+      continue
+    }
+    next[key] = value
+  }
+  if (!changed) return where
+  return Object.keys(next).length ? next : null
+}
+
+/**
+ * `scope:` on a lane that cannot be ASKED — the compiled file, an address door —
+ * is the same question as `where: { path: { under: scope } }`: a record's
+ * `path` is the folder `records.yml` placed it in, and the evaluator's `under`
+ * is segment-aware containment. Folding it keeps the language the INTERSECTION
+ * of both lanes: an author
+ * writes `scope: :dir` once and it means the same branch on a static site and
+ * on a door that takes `scope` natively. A config addressed to a question door
+ * (`door`) keeps `scope` as the door's own field.
+ */
+function foldScope(cfg) {
+  if (typeof cfg.scope !== 'string' || cfg.scope === '' || cfg.door) return cfg
+  const { scope, ...rest } = cfg
+  const under = { path: { under: scope } }
+  const where = cfg.where && typeof cfg.where === 'object' && Object.keys(cfg.where).length
+    ? { and: [cfg.where, under] }
+    : under
+  return { ...rest, where }
+}
+
+/**
+ * Say what a resolved config will GET, so the record index can file it.
+ *
+ * `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
+ * `depth` on the config wins (a question door's client sets it).
+ *
+ * `locale` — stamped on a LIVE-lane config only. A compiled path already carries
+ * its locale (`/fr/data/…`), but a live address does not, and two locales'
+ * records must not share a cache entry (F1). Absent on the default locale, so a
+ * site with one language sees no new field.
+ */
+function stampDepthAndLocale(cfg, locale, defaultLocale) {
+  let out = cfg
+  if (out.depth !== 'brief' && out.depth !== 'full') {
+    out = { ...out, depth: out.detail ? 'brief' : 'full' }
+  }
+  if (out.endpoint && locale && locale !== defaultLocale && out.locale === undefined) {
+    out = { ...out, locale }
+  }
+  // A door is asked in exactly one locale — it is in the route — so the config
+  // carries it whatever the locale is; two locales' answers never share an entry.
+  if (out.door && out.locale === undefined) {
+    const asked = locale ?? defaultLocale
+    if (asked) out = { ...out, locale: asked }
+  }
+  return out
+}