@uniweb/core 0.20.0 → 0.22.0

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@uniweb/core",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
     "./base-path": "./src/base-path.js",
-    "./collection-address": "./src/query-address.js",
-    "./query-address": "./src/query-address.js",
+    "./records-service": "./src/records-service.js",
     "./data-paths": "./src/data-paths.js",
     "./datastore": "./src/datastore.js",
     "./detail-url": "./src/detail-url.js",

package/src/datastore.js

@@ -21,7 +21,7 @@
  *
  * ⭐ TWO IDENTITIES, decided by whether the request carries an ADDRESS.
  *
- * An ADDRESSED request — `path`, `url` or `endpoint` — is identified by where it
+ * An ADDRESSED request — `path` or `url` — is identified by where it
  * goes: the address, the binding key, the unwrap, and for a POST its method and
  * body. Post-processing fields (`limit`, `sort`, `where`) are applied after the
  * fetch over one shared copy and must not split the cache; `query` and `depth`
@@ -30,15 +30,15 @@
  * asking for `{ path, as }` must hit the entry the page's declaration filled —
  * that shared cache is a documented property of `useFetched`.
  *
- * An ADDRESS-LESS request — a QUESTION sent to a records door — is identified by
- * the question: `query`, `schema`, `scope`, `where`, `sort`, `limit`, `depth`.
+ * An ADDRESS-LESS request — a QUESTION sent to the records service — is
+ * identified by the question: `query`, `schema`, `scope`, `where`, `sort`, `limit`, `depth`.
  * ⛔ The reason: with no per-query address, two pages
  * binding one `as` to two queries would otherwise share an entry, and a list
  * (brief) and a record (full) of one query would collide — the one defect on
  * this path that delivers WRONG data rather than none.
  *
- * `locale` is hashed on both when present: a live lane's address does not carry
- * the locale, and two locales' records must not share an entry (F1).
+ * `locale` is hashed on both when present: two locales' answers must not share
+ * an entry, and an asked config always carries the locale it was asked in.
  *
  * @param {Object} request - Normalized request (or fetch config)
  * @returns {string} A stable JSON string usable as a cache-Map key
@@ -47,18 +47,18 @@ export function deriveCacheKey(request) {
   // ⭐ `as` is the binding key — the name it has had since 2026-09-02, when the
   // compatibility alias for the older `schema` spelling was removed alongside
   // frontend's and hosting's.
-  const { path, url, endpoint, transform, locale } = request || {}
+  const { path, url, transform, locale } = request || {}
   const as = request?.as
   const method = request?.method && request.method.toUpperCase() !== 'GET'
     ? request.method.toUpperCase()
     : undefined
   const body = method === 'POST' ? request?.body : undefined
-  if (path || url || endpoint) {
+  if (path || url) {
     // ⚠️ The field NAME is part of the hash, so renaming it moves every key ONCE.
     // In-memory stores repopulate; a consumer with a persistent cache takes one
     // cold pass. Chosen over hashing under the old name, which would have hidden
     // the rename inside the one function whose job is to be canonical.
-    return JSON.stringify({ path, url, endpoint, as, transform, method, body, locale })
+    return JSON.stringify({ path, url, as, transform, method, body, locale })
   }
   const { query, schema, scope, where, sort, limit, depth } = request || {}
   return JSON.stringify({ query, schema, scope, where, sort, limit, depth, as, transform, locale })

package/src/detail-url.js

@@ -22,6 +22,7 @@
  * a matched route pattern says nothing about the record behind it.
  */
 
+import { recordHandle } from './route-match.js'
 import { substitutePlaceholders } from './substitute-placeholders.js'
 
 /**
@@ -54,8 +55,9 @@ function paramContext(paramName, paramValue, record) {
   // `useEntityDetail` — 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.
-  if (paramName !== 'slug' && record && typeof record === 'object' && record.slug != null && record.slug !== '') {
-    context.slug = record.slug
+  const handle = recordHandle(record)
+  if (paramName !== 'slug' && handle != null && handle !== '') {
+    context.slug = handle
   }
   return context
 }
@@ -89,12 +91,12 @@ function paramContext(paramName, paramValue, record) {
  */
 /**
  * The key a route param narrows a QUESTION by — the entry's own handle, which
- * a records door guarantees unique among siblings (the records door's contract
+ * the records service guarantees unique among siblings (the records contract
  * §1b: `$name`, "addressed AND filtered"). ⚠️ One constant, because the spelling
  * moved four times in one day (`path_segment` → `$slug` → `$name` → `meta::name`
- * → `$name`); the door is dark until a host stamps it, so this is the one place
- * to change if it moves again. Not read by the file lane or the address door,
- * which narrow by the route's own param (`item[paramName]`).
+ * → `$name`); the service is dark until a host stamps it, so this is the one
+ * place to change if it moves again. Not read by the file lane, which narrows
+ * by the route's own param (`item[paramName]`).
  */
 export const ROUTE_HANDLE_KEY = '$name'
 
@@ -104,13 +106,13 @@ export function buildDetailConfig(queryConfig, dynamicContext) {
   const { paramName, paramValue, record = null } = dynamicContext
   if (!paramName || paramValue === undefined) return null
 
-  // ⭐ A QUESTION DOOR: the record is the list's own question, narrowed to one
-  // entry by its handle and asked in full — the list page and the detail page
-  // are the same query, differing only by whether the parameter is bound
-  // (the records door's contract, §1a). `sort` and `limit` are the
-  // list's and drop; `scope` and the authored `where` stay, so a scoped query
-  // cannot be escaped through the URL.
-  if (queryConfig.door) {
+  // ⭐ THE RECORDS SERVICE: the record is the list's own question, narrowed to
+  // one entry by its handle and asked in full — the list page and the detail
+  // page are the same query, differing only by whether the parameter is bound
+  // (the records contract, §1a). `sort` and `limit` are the list's and drop;
+  // `scope` and the authored `where` stay, so a scoped query cannot be escaped
+  // through the URL.
+  if (queryConfig.ask) {
     const { sort, limit, detail: _detail, ...rest } = queryConfig
     return {
       ...rest,
@@ -120,21 +122,16 @@ export function buildDetailConfig(queryConfig, dynamicContext) {
     }
   }
 
-  // Three address kinds now, and the detail request must come back as the SAME
-  // kind: an `endpoint` carries remote semantics the fetcher decides on, so
-  // returning a detail as `path` would silently drop operator pushdown and the
-  // site's static headers for exactly the request that is one record.
-  const baseUrl = queryConfig.endpoint || queryConfig.url || queryConfig.path
+  // Two address kinds, and the detail request comes back as the SAME kind as
+  // the list: a `url` the author wrote stays a `url`, a compiled `path` stays a
+  // `path`.
+  const baseUrl = queryConfig.url || queryConfig.path
   if (!baseUrl) return null
-  const addressKey = queryConfig.endpoint
-    ? 'endpoint'
-    : queryConfig.url
-      ? 'url'
-      : 'path'
+  const addressKey = queryConfig.url ? 'url' : 'path'
 
   // What every detail config carries beside its address:
   //   `as`             — the binding key, so the record lands where the list did;
-  //   `query`          — the query it is one record of (identity on a door);
+  //   `query`          — the query it is one record of (identity when asked);
   //   `depth: 'full'`  — what it asks for, and what the record index files it as;
   //   `dynamicContext` — the route param, which the default fetcher already keys
   //                      a SINGLE-RECORD response on (`envelope.item`, body

package/src/entity-store.js

@@ -15,7 +15,7 @@
  */
 
 import { isFetchRefinement, resolveFetchConfigs } from './fetch-config.js'
-import { fillRoutePattern } from './route-match.js'
+import { fillRoutePattern, routeParamValue } from './route-match.js'
 import { sortRecords } from './sort.js'
 
 /**
@@ -152,10 +152,11 @@ export default class EntityStore {
         // after the payload key was renamed — a dead option name, silently: the
         // resolver simply saw no queries and stopped injecting `detail:`.
         queries: website?.config?.queries ?? null,
-        // A host's live-records lane. Absent on every static site and on
-        // local dev, which is why `resolveQuerySource` treats absence as
-        // the ordinary case and reads the compiled artifact without comment.
-        records: website?.config?.records ?? null,
+        // The host's services; its `records` row is the live-records lane.
+        // Absent on every static site and on local dev, which is why
+        // `resolveQuerySource` treats absence as the ordinary case and reads
+        // the compiled artifact without comment.
+        services: website?.config?.services ?? null,
         variables,
       },
     )
@@ -252,15 +253,15 @@ export default class EntityStore {
           const { paramName, paramValue } = dynamicContext
           const items = cached.data
           let filtered = Array.isArray(items)
-            ? items.filter((item) => String(item[paramName]) !== String(paramValue))
+            ? items.filter((item) => String(routeParamValue(item, paramName)) !== String(paramValue))
             : items
           if (order) filtered = this._sortItems(filtered, order)
           data[schema] = limit && Array.isArray(filtered) ? filtered.slice(0, limit) : filtered
         } else {
           allCached = false
         }
-      } else if (isRouteQuery && cfg.door) {
-        // A question door: the record's own answer is cached under its own key.
+      } else if (isRouteQuery && cfg.ask) {
+        // The records service: the record's own answer is cached under its own key.
         const detailCfg = this._buildDetailConfig(cfg, dynamicContext)
         const detailCached = detailCfg ? dispatcher?.peek(detailCfg, ctx) : null
         if (detailCached) {
@@ -278,7 +279,7 @@ export default class EntityStore {
           const { paramName, paramValue } = dynamicContext
           const items = cached.data
           const match = Array.isArray(items)
-            ? items.find((item) => String(item[paramName]) === String(paramValue))
+            ? items.find((item) => String(routeParamValue(item, paramName)) === String(paramValue))
             : null
           if (!match) {
             data[schema] = []
@@ -386,12 +387,12 @@ export default class EntityStore {
         }
         const { paramName, paramValue } = dynamicContext
         let filtered = Array.isArray(records)
-          ? records.filter((item) => String(item[paramName]) !== String(paramValue))
+          ? records.filter((item) => String(routeParamValue(item, paramName)) !== String(paramValue))
           : (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
+      } else if (isRouteQuery && cfg.ask) {
+        // ⭐ THE RECORDS SERVICE 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
@@ -424,7 +425,7 @@ export default class EntityStore {
         }
 
         const match = records?.find(
-          (item) => String(item[paramName]) === String(paramValue)
+          (item) => String(routeParamValue(item, paramName)) === String(paramValue)
         ) ?? null
 
         if (!match) {

package/src/fetch-config.js

@@ -14,12 +14,30 @@
  *
  * INTENTIONALLY A LEAF: safe to load anywhere — including environments with no
  * DOM, no filesystem, and a hard bundle-size ceiling. The rule that protects
- * that is **no transitive graph**: import nothing from the package root (which
- * pulls semantic-parser and theming) and nothing that itself imports. A
- * zero-dependency sibling leaf is admissible and `./data-paths.js` is the only
- * one taken — the path convention it holds has to be identical here and in the
- * build that emits the files, and a second copy of that string is precisely
- * the drift this module exists to prevent.
+ * that is **import nothing from the package root** (which pulls semantic-parser
+ * and theming) and nothing that reaches it transitively.
+ *
+ * ⚠️ **This said "and nothing that itself imports — `./data-paths.js` is the
+ * only one taken", and both halves had stopped being true.** `query-address.js`
+ * was added as an import and itself imports; on 2026-09-06 it became
+ * `records-service.js` and the chain grew again. **The admissible set, named
+ * rather than counted:**
+ *
+ *     fetch-config → data-paths                                    (leaf)
+ *                  → records-service → substitute-placeholders     (leaf)
+ *                                    → services → base-path        (leaf)
+ *
+ * Every module in it is pure JS with no `node:*`, no DOM and no package-root
+ * import — the property that actually matters. "Depth 1" was a proxy for it
+ * that stopped holding without anything failing, which is why the rule is now
+ * stated as the property.
+ *
+ * ⛔ **Two edges are deliberate and must not be inlined**, for one reason:
+ * `data-paths.js` holds the `/data/<name>.json` convention, which has to be
+ * identical here and in the build that emits the files; `services.js` holds
+ * `readEndpoint`, the ONE rule for reading a service declaration. A second copy
+ * of either is precisely the drift this module exists to prevent. ⇒ **If you
+ * add an edge, say here why it holds.**
  *
  * WHAT THIS DOES NOT OWN: where the sources come from. A caller holding a live
  * object graph reads them off the graph; a caller holding a content document
@@ -28,7 +46,7 @@
  */
 
 import { queryDataUrl, isDataUrl, recordDataUrl } from './data-paths.js'
-import { resolveQueryAddress, resolveRecordAddressPattern, resolveQueryDoor } from './query-address.js'
+import { resolveRecordsService } from './records-service.js'
 
 /**
  * Is this fetch declaration a per-instance *refinement* of an ancestor's
@@ -97,31 +115,13 @@ function localizeConfig(cfg, locale, defaultLocale) {
  * @param {Object|null} queries - the site's `config.queries` map
  * @returns {Object} the original config, or a copy carrying `detail`
  */
-function applyDeferredDetail(cfg, queries, records) {
+function applyDeferredDetail(cfg, queries) {
   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 }
+  // The records service answers a RECORD by the same question narrowed to it,
+  // so every asked config has a detail source; `buildDetailConfig` composes it.
+  if (cfg.ask) 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.
-  //
-  // A live lane answers a list request at brief depth and a record request in
-  // full, so a detail page that filtered the list would render the brief and
-  // silently miss the body. And it cannot fall back to the rule below: the
-  // `deferred:` declaration lives in `config.queries`, which a host's
-  // projection is not obliged to carry — so on such a host that rule can never
-  // fire, and this is the only way a detail page reaches a whole record.
-  if (cfg.endpoint) {
-    // ⛔ `cfg.query`, not `cfg.query ?? cfg.schema`. The `??` was unreachable:
-    // `endpoint` is set in exactly one place (`resolveQuerySource`), which returns
-    // early unless `cfg.query` is a non-empty string — so reaching here proves it.
-    // It read as a tolerance for two producer shapes and was really a vestige of
-    // the build lane not emitting `query`, which it now does.
-    const recordPattern = resolveRecordAddressPattern(cfg.query, records)
-    if (recordPattern) return { ...cfg, detail: recordPattern }
-  }
 
   // ⛔ **`config.queries` is keyed by QUERY NAME, so look it up by the query.**
   // This read `cfg.schema` — the BINDING KEY, which merely defaults to the query
@@ -159,9 +159,15 @@ function applyDeferredDetail(cfg, queries, records) {
  * The author names a query; this decides where its records live, and there are
  * exactly two answers:
  *
- *   - a host declared a live lane (`config.records`) → an `endpoint`, final on
- *     arrival, which the fetcher calls without composing anything further;
- *   - nobody did → the `path` of the artifact the build emitted.
+ *   - a host offers the `records` service (`config.services.records`) → an
+ *     `ask` address, and the whole query goes to it (`schema` from the
+ *     payload's `config.queries`; an `ask` with no Model ref is a loud per-key
+ *     error, never a fallthrough);
+ *   - nobody does → the `path` of the artifact the build emitted.
+ *
+ * ⛔ There is no third answer, and there has not been one since the GET lane
+ * the runtime evaluated locally was retired (2026-09-04). `records-service.js`
+ * says why the wrapper it lived in went with it.
  *
  * ⭐ The second is not a fallback in the apologetic sense. It is the answer for
  * every site with no backend, which is the framework's default rather than a
@@ -174,38 +180,37 @@ 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, { queries = null, locale = null, defaultLocale = null } = {}) {
+function resolveQuerySource(cfg, services, { 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) {
+  // ⭐ THE SERVICE FIRST. A host that answers questions gets the whole query —
+  // `schema`, `scope`, `where`, `sort`, `limit`, `depth` — and composes no
+  // per-query address at all (the records contract, §2). It needs the query's
+  // MODEL REF, which lives on the site's `config.queries` declaration; a
+  // payload that offers the service but carries no declaration cannot ask, and
+  // says so. ⚠️ Dark until a host stamps the row; see `resolveRecordsService`.
+  const ask = resolveRecordsService(services, locale ?? defaultLocale)
+  if (ask) {
     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
     // ambiguity the fetcher would have to break by accident of field order.
     const { path, url, ...rest } = cfg
-    return { ...rest, endpoint }
+    if (!schema) {
+      // ⛔ LOUD, not a fallthrough. A payload that offers the service and carries no
+      // Model ref for the query cannot ask, and reading the compiled file
+      // instead would turn a producer defect into a 404 that names the wrong
+      // thing. The fetcher refuses an asked request with no `schema` before any
+      // request is made, and the block's `dataError` says exactly this.
+      return { ...rest, ask, schema: null }
+    }
+    const asked = { ...rest, ask, 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
   }
   return { ...cfg, path: queryDataUrl(cfg.query) }
 }
@@ -261,9 +266,9 @@ function bindingKey(cfg) {
  * @param {string|null} [options.locale] - the locale being rendered
  * @param {string|null} [options.defaultLocale] - the site's default locale
  * @param {Object|null} [options.queries] - the site's `config.queries`
- * @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.services] - the site's `config.services`. The
+ *   `records` row is 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
@@ -276,7 +281,7 @@ export function resolveFetchConfigs(sources, options = {}) {
     locale = null,
     defaultLocale = null,
     queries = null,
-    records = null,
+    services = null,
     variables = null,
   } = options
 
@@ -293,10 +298,10 @@ 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, { queries, locale, defaultLocale })
+      const sourced = resolveQuerySource(cfg, services, { queries, locale, defaultLocale })
       const localized = localizeConfig(sourced, locale, defaultLocale)
       const bound = foldScope(bindRouteVariables(localized, variables))
-      configs.set(key, stampDepthAndLocale(applyDeferredDetail(bound, queries, records), locale, defaultLocale))
+      configs.set(key, stampDepthAndLocale(applyDeferredDetail(bound, queries), locale, defaultLocale))
     }
   }
 
@@ -318,8 +323,8 @@ const ROUTE_VARIABLE = /^:(path|dir|slug)$/
  * 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).
+ * bound, and binds the empty value. The backend answering the records service
+ * states the same rule from its side (the records 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
@@ -385,17 +390,17 @@ function bindWhere(where, variables) {
 }
 
 /**
- * `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
+ * `scope:` on a lane that cannot be ASKED — the compiled file — 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.
+ * on a service that takes `scope` natively. A config carrying `ask` keeps
+ * `scope` as the service's own field.
  */
 function foldScope(cfg) {
-  if (typeof cfg.scope !== 'string' || cfg.scope === '' || cfg.door) return cfg
+  if (typeof cfg.scope !== 'string' || cfg.scope === '' || cfg.ask) return cfg
   const { scope, ...rest } = cfg
   const under = { path: { under: scope } }
   const where = cfg.where && typeof cfg.where === 'object' && Object.keys(cfg.where).length
@@ -411,24 +416,20 @@ function foldScope(cfg) {
  * 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).
+ * `depth` on the config wins (the records service'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.
+ * `locale` — stamped on an ASKED config only. A compiled path already carries
+ * its locale (`/fr/data/…`); the service is asked in one locale (it is in the
+ * route), and two locales' answers must not share a cache entry.
  */
 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
+  // The service 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) {
+  if (out.ask && out.locale === undefined) {
     const asked = locale ?? defaultLocale
     if (asked) out = { ...out, locale: asked }
   }

package/src/index.js

@@ -20,15 +20,8 @@ export { default as ObservableState } from './observable-state.js'
 
 // Utilities
 export { substitutePlaceholders } from './substitute-placeholders.js'
-// ⛔ `resolveQueryAddress` / `resolveRecordAddressPattern` are NOT re-exported
-// here. They are read by `./fetch-config.js` and by nothing else in any repo
-// (measured 2026-09-01 over every .js/.jsx/.mjs/.ts/.tsx file in the
-// workspace). A consumer that needs them imports `@uniweb/core/query-address`,
-// which is a declared subpath and a zero-dependency leaf — the same reach
-// `route-match` and `section-id` already have. Re-exporting an internal from
-// the package entry is not free: the import-map bridge enumerates this file's
-// surface and emits a live named re-export for every one, so nothing here can
-// ever be tree-shaken on the hosted lane.
+// `resolveRecordsService` / `RECORDS_SERVICE` are NOT re-exported here: `./fetch-config.js`
+// reads them and a consumer that needs them imports `@uniweb/core/records-service`.
 export { resolveFetchConfigs } from './fetch-config.js'
 export { buildDetailConfig, ROUTE_HANDLE_KEY } from './detail-url.js'
 // `isWildcardLanguages` is likewise internal — `./locale-config.js` reads it
@@ -52,7 +45,7 @@ export { evaluate as evaluateWhere, match as matchWhere } from './where.js'
 // (materialization, the `route:` bake) and by `@uniweb/runtime` (the fallback),
 // which is what keeps the static and live lanes answering a query identically.
 export { parseSort, sortRecords, sortToWire } from './sort.js'
-export { fillRoutePattern, splitPathCapture, joinPathCapture } from './route-match.js'
+export { fillRoutePattern, splitPathCapture, joinPathCapture, recordHandle, routeParamValue } from './route-match.js'
 export { isRichSchema } from './schemas.js'
 // ⛔ `Tracker` is NOT on the package entry. It is a FEATURE, not part of the
 // object graph this package exists to define, and putting it here made every

package/src/records-service.js

@@ -0,0 +1,113 @@
+/**
+ * Where a site's queries are answered — the `records` service.
+ *
+ * ## The one idea
+ *
+ * A site names a query; it never names where its records live. Where they live
+ * is a **deployment** fact, and the two possible answers have different owners:
+ *
+ *   1. **A host that answers questions** offers the `records` service — an
+ *      address with a `{locale}` slot, which takes a POST carrying the whole
+ *      query. It owns every segment of it; the runtime substitutes the one slot
+ *      and sends the question. ⛔ The question is composed elsewhere
+ *      (`fetch-config.js`); this file only says where it goes.
+ *   2. **Nobody** — and the answer is the artifact the build itself emitted,
+ *      `/data/<name>.json`, which is not an address at all but a path in the
+ *      site's own URL space.
+ *
+ * Absence of (1) is therefore not an error and not a decline: it falls THROUGH
+ * to (2). That is what makes a site with no backend the default rather than a
+ * special case.
+ *
+ * ## ⭐ It is a SERVICE, and that is the whole of its shape
+ *
+ * *[Diego, 2026-09-06: "`records` does sound like a service. It is the service
+ * of having a dynamic record provider."]* So it sits in `config.services`
+ * beside `search`, `submit` and `assistant`, is read with the same
+ * `readEndpoint` rule (string shorthand or `{ endpoint }`), and follows the
+ * same law: **presence is the switch.** A host that offers a records lane
+ * stamps the row; one that does not, does not.
+ *
+ * ⛔ **It did NOT used to be.** Until 2026-09-06 it was `config.records`, an
+ * object of its own whose only surviving key was `query` — a wrapper left over
+ * from the day there were two lanes to choose between. One host-stamped address
+ * read by two mechanisms was the accident; a service row is the shape it always
+ * had.
+ *
+ * ## ⛔ The HOST tier only — and the reason is mechanical, not a policy
+ *
+ * `resolveService` reads the site's authored tier first and the host's second.
+ * This does not, because it cannot: its caller `resolveFetchConfigs` is a leaf
+ * that runs in an SSR isolate over a plain content object with no `Website` to
+ * hand. It reads `config.services` directly, so the authored tier is not
+ * available here. ⇒ **A site does not declare its own record provider**, which
+ * is also the standing ruling — a third-party source is a foundation transport,
+ * not site-level config *(2026-09-04, the retired `fetcher:` vocabulary)*.
+ *
+ * ## ⛔ A pattern, not a base — and the reason is a deleted function
+ *
+ * A base assumes the layout is "root plus one segment". A pattern assumes
+ * nothing, so a host can carry a site id, a locale segment, a different root
+ * for records than for the site, or none of those, and move any of it without a
+ * framework release. This is the `config.assets.url` rule applied to records:
+ * the CLI once composed `{assetBase}dist/{id}/base.{ext}` — a backend's path
+ * layout, inside a published CLI — and it was deleted rather than
+ * parameterized. Substituting `{locale}` is the WHOLE of what this does.
+ *
+ * Zero-dependency beyond two sibling leaves, so the SSR pipeline and a Worker
+ * isolate can both import it.
+ */
+
+import { substitutePlaceholders } from './substitute-placeholders.js'
+import { readEndpoint } from './services.js'
+
+const warnedPatterns = new Set()
+
+function warnOnce(key, message) {
+  if (warnedPatterns.has(key)) return
+  warnedPatterns.add(key)
+  console.warn(`[records-service] ${message}`)
+}
+
+/** Test seam — reset the once-per-pattern memo so suites do not leak. */
+export function _resetRecordsServiceWarnings() {
+  warnedPatterns.clear()
+}
+
+/**
+ * The service name a host stamps to say it answers queries.
+ *
+ * One constant, changed in one place should it ever move.
+ */
+export const RECORDS_SERVICE = 'records'
+
+/**
+ * The address a query is asked at, substituted for one locale, or `null` when
+ * no host offers the service.
+ *
+ * A row present with no address is a host saying "not for this site" —
+ * indistinguishable, for a caller, from no row at all. Both fall through to the
+ * compiled artifact.
+ *
+ * The locale is a ROUTE SEGMENT there, never a query param: a request that
+ * cannot name one does not address the service at all.
+ *
+ * @param {Object|null} services - `config.services`
+ * @param {string|null} locale - the locale being rendered; required
+ * @returns {string|null}
+ */
+export function resolveRecordsService(services, locale) {
+  if (!services || typeof services !== 'object' || Array.isArray(services)) return null
+  const endpoint = readEndpoint(services[RECORDS_SERVICE])
+  if (!endpoint) return null
+  if (typeof locale !== 'string' || locale.length === 0) return null
+  if (!endpoint.includes('{locale}')) {
+    warnOnce(
+      `records:${endpoint}`,
+      `config.services.${RECORDS_SERVICE} carries no {locale} placeholder; the service takes the ` +
+        `locale as a route segment. Ignoring it.`
+    )
+    return null
+  }
+  return substitutePlaceholders(endpoint, { locale })
+}

package/src/route-match.js

@@ -238,6 +238,48 @@ export function joinPathCapture({ dir, slug } = {}) {
   return d ? `${d}/${slug}` : String(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.
+ *
+ * @param {Object} record
+ * @returns {string|undefined}
+ */
+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
+}
+
+/**
+ * The value a record carries for a route param. `slug` — the default param, and
+ * the last segment of a `[...path]` route — is the placement handle
+ * (`recordHandle`); any other param is a field the site chose to route by.
+ *
+ * ⛔ Every reader that matches a delivered record to a route param goes through
+ * this — the entity store, the website's dynamic page, the kit's detail hook,
+ * the href encoder below. Until 2026-09-04 each read `item[paramName]` directly,
+ * so a record served with `$name` and no `slug` matched nothing: a template page
+ * on a live lane rendered `[]` and a list linked to no record.
+ *
+ * @param {Object} record
+ * @param {string} paramName
+ * @returns {*}
+ */
+export function routeParamValue(record, paramName) {
+  if (!record || typeof record !== 'object') return undefined
+  if (paramName === 'slug') return recordHandle(record)
+  return record[paramName]
+}
+
 /**
  * Fill a route pattern's params from a record — the ONE encoder for a record's href.
  *
@@ -274,16 +316,17 @@ export function fillRoutePattern(pattern, values) {
     // slashes between them kept as structure. `dir` is the placement; a record
     // carries it as `path` (the folder `records.yml` put it in), which is why
     // `path` here is read as the DIRECTORY and never as a composed capture.
-    if (joinPathCapture({ dir: values.dir ?? values.path, slug: values.slug }) === null) return null
+    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(values.slug)))
+    segments.push(encodeURIComponent(String(handle)))
     tailHref = '/' + segments.join('/')
     head = pattern.slice(0, tail.index)
   }
   const href = head.replace(new RegExp(`:(${PARAM_NAME})`, 'g'), (_, name) => {
-    const value = values[name]
+    const value = routeParamValue(values, name)
     if (value === undefined || value === null || value === '') {
       missing = true
       return ''

package/src/services.js

@@ -96,7 +96,7 @@ const ABSOLUTE_URL_RE = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i
  * @param {*} declaration
  * @returns {string} the endpoint, or '' when there is none
  */
-function readEndpoint(declaration) {
+export function readEndpoint(declaration) {
   if (typeof declaration === 'string') return declaration.trim()
   if (typeof declaration?.endpoint === 'string') return declaration.endpoint.trim()
   return ''

package/src/sort.js

@@ -7,11 +7,11 @@
  * entity store's refine-order sort — and two of them split on commas and honoured
  * several keys while the one shipped wire dialect documented the same, so a site
  * authoring `sort: order asc, title asc` worked on the static lane and would have
- * been refused by the records door, which takes one key. The language is the
+ * been refused by the records service, which takes one key. The language is the
  * INTERSECTION of what both lanes honour, so a comma is refused here rather than
  * half-honoured somewhere.
  *
- * Author spelling, unchanged: `date`, `date asc`, `date desc`. The records door's
+ * Author spelling, unchanged: `date`, `date asc`, `date desc`. The records service's
  * spelling is `date` / `-date`; `-date` is accepted on the way in so a value that
  * came off the wire round-trips, and `sortToWire` produces it on the way out.
  *
@@ -67,7 +67,7 @@ export function parseSort(sort) {
 }
 
 /**
- * The door's spelling of a sort: `date` ascending, `-date` descending.
+ * The service's spelling of a sort: `date` ascending, `-date` descending.
  *
  * @param {string|{field:string, desc?:boolean}|null|undefined} sort
  * @returns {string|null}

package/src/website.js

@@ -11,7 +11,7 @@ import FetcherDispatcher from './fetcher-dispatcher.js'
 import ObservableState from './observable-state.js'
 import { normalizeSeo } from './seo.js'
 import { resolveDefaultLocale, localeLabel } from './locale-config.js'
-import { matchDynamicRoute, decodeRouteValue, routePatternToRegex, splitPathCapture } from './route-match.js'
+import { matchDynamicRoute, decodeRouteValue, routePatternToRegex, splitPathCapture, routeParamValue } from './route-match.js'
 import { resolveFetchConfigs } from './fetch-config.js'
 import { buildDetailConfig } from './detail-url.js'
 import { resolveService } from './services.js'
@@ -615,8 +615,8 @@ export default class Website {
       //
       // ⛔ RESOLVED THE WAY THE ENTITY STORE RESOLVES IT, not the raw declaration.
       // Until 2026-09-04 this peeked `parentPage.fetch` as authored — `{ query,
-      // path, as }` — while the store writes under the RESOLVED config: on a live
-      // lane that carries `endpoint` and no `path`, and on a non-default locale a
+      // path, as }` — while the store writes under the RESOLVED config: on the
+      // asked lane that carries `ask` and no `path`, and on a non-default locale a
       // `/fr/data/…` path. Two different keys for one dataset, so the probe
       // missed on exactly those lanes: no title, no not-found, and the page was
       // never cached (`recordsLoaded` false on every visit). Silent, on a
@@ -635,7 +635,7 @@ export default class Website {
           locale: this.getActiveLocale(),
           defaultLocale: this.getDefaultLocale(),
           queries: this.config?.queries ?? null,
-          records: this.config?.records ?? null,
+          services: this.config?.services ?? null,
           variables,
         }).get(pluralSchema)
         if (fetchConfig) {
@@ -649,8 +649,11 @@ export default class Website {
             ? buildDetailConfig(fetchConfig, { paramName, paramValue })
             : null
           const detailCached = detailCfg ? this.fetcher.peek(detailCfg, ctx) : null
-          const record = detailCached?.data
-          if (record && typeof record === 'object' && !Array.isArray(record)) currentItem = record
+          // The service answers the record question as a list of one (a question's
+          // answer is always a list); a per-record file answers the bare record.
+          const raw = detailCached?.data
+          const record = Array.isArray(raw) ? raw[0] : raw
+          if (record && typeof record === 'object') currentItem = record
 
           const cached = this.fetcher.peek(fetchConfig, ctx)
           items = Array.isArray(cached?.data) ? cached.data : []
@@ -658,7 +661,7 @@ export default class Website {
       }
 
       if (!currentItem) {
-        currentItem = items.find(item => String(item[paramName]) === String(paramValue)) ?? null
+        currentItem = items.find(item => String(routeParamValue(item, paramName)) === String(paramValue)) ?? null
       }
 
       if (currentItem) {

package/src/query-address.js

@@ -1,176 +0,0 @@
-/**
- * Resolve a query request to an address the fetcher can call.
- *
- * ## The one idea
- *
- * A site names a query; it never names where its records live. Where
- * it lives is a **deployment** fact, and the two possible answers have different
- * owners:
- *
- *   1. **A host that serves records live** declares a pair of URL *patterns*
- *      at `config.records`. It owns every segment of them.
- *   2. **Nobody** — and the answer is the artifact the build itself emitted,
- *      `/data/<name>.json`, which is not an address at all but a path in the
- *      site's own URL space.
- *
- * Absence of (1) is therefore not an error and not a decline: it falls THROUGH
- * to (2). That is what makes a site with no backend the default rather than a
- * special case, and it is why this does not go through `resolveService` — a
- * service's absence means the site has no such feature and the caller draws
- * nothing, which is right for `submit` and wrong here, where the fallback is a
- * file the build knows it wrote.
- *
- * ## ⛔ Patterns, not a base — and the reason is a deleted function
- *
- * A base assumes the layout is "root plus one segment". A pattern assumes
- * nothing, so a host can carry a site id, a locale segment, a different root
- * for records than for the list, or none of those, and move any of it
- * without a framework release.
- *
- * This is the `config.assets.url` rule applied to records. That pattern exists
- * because the CLI once composed `{assetBase}dist/{id}/base.{ext}` — a backend's
- * path layout, inside a published CLI, on a release cadence the backend could
- * not move. It was deleted rather than parameterized. Composing a segment of
- * our own here would rebuild exactly that coupling, on a lane where the wrong
- * answer is *stale or missing content* rather than a visible 404.
- *
- * ⇒ Substituting `{path}` and `{param}` is the WHOLE of what this does.
- *
- * Zero-dependency beyond two sibling leaves, so the SSR pipeline and a Worker
- * isolate can both import it.
- */
-
-import { substitutePlaceholders } from './substitute-placeholders.js'
-
-/**
- * The placeholder a list pattern must carry.
- *
- * ⛔ IT IS `{path}`, NOT `{query}`, AND THAT IS NOT COSMETIC. A *query* is
- * framework's own build concept — a named set our build compiles to one file. A host
- * serving records has no such thing: it has content organised somewhere, and what we
- * substitute is a **path** to it. Naming the slot for our file vocabulary put that
- * vocabulary into a string a HOST writes, which makes them reason in our shape.
- */
-const PATH_SLOT = '{path}'
-/** The placeholder a record pattern must carry to address a specific record. */
-const PARAM_SLOT = '{param}'
-
-const warnedPatterns = new Set()
-
-function warnOnce(key, message) {
-  if (warnedPatterns.has(key)) return
-  warnedPatterns.add(key)
-  console.warn(`[query-address] ${message}`)
-}
-
-/** Test seam — reset the once-per-pattern memo so suites do not leak. */
-export function _resetQueryAddressWarnings() {
-  warnedPatterns.clear()
-}
-
-/**
- * Is this a usable lane declaration?
- *
- * A declaration present with no pattern is a host saying "not for this site" —
- * indistinguishable, for a caller, from no declaration at all. Both fall
- * through to the artifact.
- */
-function readPattern(lane, key) {
-  if (!lane || typeof lane !== 'object' || Array.isArray(lane)) return null
-  const pattern = lane[key]
-  return typeof pattern === 'string' && pattern.length > 0 ? pattern : null
-}
-
-/**
- * The address for a whole query's records, or `null` to fall through to the artifact.
- *
- * ⚠️ A pattern that does not carry `{path}` is REFUSED rather than used.
- * Substituting nothing would yield one identical URL for every query on the
- * site — every schema reading the same records, with a 200 on each request. That
- * is the failure this check exists for; an unusable pattern must degrade to the
- * artifact, which is at least correct.
- *
- * @param {string} query - the query's authored name (the wiring key).
- * @param {Object|null} lane - `config.records`.
- * @returns {string|null} the address, or null when nothing usable is declared.
- */
-export function resolveQueryAddress(query, lane) {
-  if (typeof query !== 'string' || query.length === 0) return null
-  const pattern = readPattern(lane, 'list')
-  if (!pattern) return null
-  if (!pattern.includes(PATH_SLOT)) {
-    warnOnce(
-      `list:${pattern}`,
-      `config.records.list carries no ${PATH_SLOT} placeholder, so every ` +
-        `query would resolve to the same address. Ignoring it and reading the ` +
-        `compiled file instead.`
-    )
-    return null
-  }
-  return substitutePlaceholders(pattern, { path: query })
-}
-
-/**
- * The QUESTION door a host declares — a POST address with a `{locale}` slot —
- * substituted for one locale, or `null` when the lane declares none.
- *
- * The stamp key is `config.records.query` — read here as a provisional spelling
- * on 2026-09-04 and NAMED THE SAME DAY by the door's owner (their site-records
- * contract, §11.4: stamped since 2026-09-04, value `/_records/_query/{locale}`).
- * One constant, changed in one place should it ever move. Everything downstream
- * wakes only when a host stamps it AND the payload carries the query's Model ref
- * (`config.queries`), and stays dark otherwise. The locale is a ROUTE SEGMENT
- * there, never a query param: a request that cannot name one does not address
- * this door at all.
- *
- * @param {Object|null} lane - `config.records`
- * @param {string|null} locale - the locale being rendered; required
- * @returns {string|null}
- */
-export const QUERY_DOOR_KEY = 'query'
-
-export function resolveQueryDoor(lane, locale) {
-  const pattern = readPattern(lane, QUERY_DOOR_KEY)
-  if (!pattern) return null
-  if (typeof locale !== 'string' || locale.length === 0) return null
-  if (!pattern.includes('{locale}')) {
-    warnOnce(
-      `query:${pattern}`,
-      `config.records.${QUERY_DOOR_KEY} carries no {locale} placeholder; the door takes the ` +
-        `locale as a route segment. Ignoring it.`
-    )
-    return null
-  }
-  return substitutePlaceholders(pattern, { locale })
-}
-
-/**
- * The address pattern for ONE record of a query, with `{param}` left in
- * place for the dynamic-route substitution that happens later.
- *
- * Returning a pattern rather than a finished URL is deliberate: the route param
- * is not known here, and the framework already has one place that resolves it
- * (`buildDetailConfig` / `substitutePlaceholders` at fetch time). Resolving it
- * twice, in two places, is how the two copies drift.
- *
- * @param {string} query
- * @param {Object|null} lane - `config.records`.
- * @returns {string|null} a pattern still containing `{param}`, or null.
- */
-export function resolveRecordAddressPattern(query, lane) {
-  if (typeof query !== 'string' || query.length === 0) return null
-  const pattern = readPattern(lane, 'record')
-  if (!pattern) return null
-  if (!pattern.includes(PARAM_SLOT)) {
-    warnOnce(
-      `record:${pattern}`,
-      `config.records.record carries no ${PARAM_SLOT} placeholder, so every record ` +
-        `would resolve to the same address. Ignoring it and reading the per-record ` +
-        `file instead.`
-    )
-    return null
-  }
-  // Only `{path}` is substituted here — `{param}` survives for the
-  // dynamic-route resolution that owns it.
-  return substitutePlaceholders(pattern, { path: query })
-}