@uniweb/build 0.64.2 → 0.66.0

package/src/site/query-processor.js

@@ -58,15 +58,17 @@ import { createHash } from 'node:crypto'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { parseBibtex } from '@citestyle/bibtex'
-import { DATA_DIR, withoutRouteVariables } from '@uniweb/core'
+import { DATA_DIR, withoutRouteVariables, mapQueryPaths, BRANCH_KEY } from '@uniweb/core'
 import { applyWhere, applySort, refuseUnder, refuseOutsideLanguage, refuseQueryRoute, refuseLimit } from './data-fetcher.js'
 import { resolveAssetPath, walkContentAssets, isLocalAssetPath } from './assets.js'
 import { readEntityPool, groupPoolBySchema, poolDirsForSchema } from './entity-pool.js'
-import { readRecordsConfig, resolveFolder } from './records-config.js'
+import { readRecordsConfig, resolveFolder, folderTreeOrder } from './records-config.js'
 import { isDraftRecord } from './record-draft.js'
-import { resolveRecordSchemas } from './queries-config.js'
+import { refuseNotOneRecord } from './record-file.js'
+import { resolveRecordSchemas, resolveQueriesConfig, foundationSections } from './queries-config.js'
+import { dataKeyTypes } from '../uwx/data-key-types.js'
 import { parseFrontmatter } from '../utils/frontmatter.js'
-import { toDeliveredRecord, contentBodyField, misplacedFields, mapReferences, recordLayout } from '@uniweb/schemas/conform'
+import { toDeliveredRecord, toStoredRecord, storedPath, briefFieldMap, contentBodyField, misplacedFields, mapReferences, recordLayout } from '@uniweb/schemas/conform'
 import { collectNestedRefs } from '@uniweb/schemas/format'
 
 // Try to import content-reader for markdown parsing
@@ -125,7 +127,6 @@ function parseQueryConfig(name, config) {
       filter: null,
       limit: 0,
       excerpt: { maxLength: 160 },
-      deferred: null,
     }
   }
 
@@ -153,14 +154,6 @@ function parseQueryConfig(name, config) {
       maxLength: config.excerpt?.maxLength || 160,
       field: config.excerpt?.field || null
     },
-    // `deferred:` lists fields that are heavy (article body, full nested
-    // arrays). Those fields are stripped from the cascade payload that
-    // ships with `query: <name>` declarations, and per-record full files
-    // are emitted at public/data/<name>/<slug>.json. Components that
-    // need the full record fetch the per-record file on demand, either
-    // automatically on dynamic-route pages (entity-store routes the
-    // singular detail there) or via kit's useWholeRecord hook.
-    deferred: Array.isArray(config.deferred) ? config.deferred.slice() : null,
     // `queryable:` declares the queryable surface — which fields a
     // foundation can offer for filtering UI, with their type and
     // type-specific metadata (enum options, range bounds). Foundations
@@ -458,15 +451,13 @@ async function processDataItemAssets(data, itemPath, siteRoot, recordsRoot, base
  * YAML items are pure data — no ProseMirror conversion, no body, no excerpt,
  * no image extraction, no lastModified.
  *
- * A YAML file containing a top-level array returns all items (single-file
- * collection); each item must carry its own `slug`. A YAML file containing
- * a mapping returns a single item with `slug` derived from the filename.
- * Mirrors `processJsonItem` for parity across pure-data formats.
+ * A YAML file holds ONE record, named by the file (`record-file.js` refuses a list
+ * or a `slug:`). Mirrors `processJsonItem` for parity across pure-data formats.
  *
  * @param {string} dir - Collection directory path
  * @param {string} filename - YAML filename (.yml or .yaml)
  * @param {Object} config - the parsed query (`includeDrafts`, `dataSchema`)
- * @returns {Promise<Object|Array|null>} Processed item(s), or null for a draft this run withholds
+ * @returns {Promise<Object|null>} The processed record, or null for a draft this run withholds
  */
 async function processDataItem(dir, filename, siteRoot, recordsRoot, basePath, config) {
   const filepath = join(dir, filename)
@@ -477,26 +468,11 @@ async function processDataItem(dir, filename, siteRoot, recordsRoot, basePath, c
 }
 
 /**
- * The records a YAML or JSON file holds, delivered (`deliverRecord`): an array → one
- * record per entry, each carrying its own `slug`; a mapping → one record, its `slug` the
- * file's name unless it states one.
+ * The record a YAML or JSON file holds, delivered (`deliverRecord`) and named by the file.
  */
 async function processDataRecords(data, fileSlug, filepath, where, siteRoot, recordsRoot, basePath, config) {
-  // Array → multiple items (single-file collection). A draft entry is dropped
-  // BEFORE its assets are copied, so nothing of it ships.
-  if (Array.isArray(data)) {
-    const out = []
-    for (const [i, item] of data.entries()) {
-      if (withheld(item, `${where} [${i}]`, config.includeDrafts)) continue
-      if (item && typeof item === 'object') {
-        await processDataItemAssets(item, filepath, siteRoot, recordsRoot, basePath)
-      }
-      out.push(deliverRecord(item, config, `${where} [${i}]`))
-    }
-    return out
-  }
-
-  // Mapping → single item
+  // ONE record per file, named by the file (`record-file.js`).
+  refuseNotOneRecord(data, where, fileSlug)
   if (withheld(data, where, config.includeDrafts)) return null
   const item = { slug: fileSlug, ...data }
   await processDataItemAssets(item, filepath, siteRoot, recordsRoot, basePath)
@@ -507,13 +483,12 @@ async function processDataRecords(data, fileSlug, filepath, where, siteRoot, rec
  * Process a single data item from a JSON file
  *
  * JSON items are pure data — like YAML items, no ProseMirror conversion.
- * A JSON file containing an array returns all items (single-file collection).
- * A JSON file containing an object returns a single item with slug from filename.
+ * A JSON file holds ONE record, named by the file (`record-file.js`).
  *
  * @param {string} dir - Collection directory path
  * @param {string} filename - JSON filename
  * @param {Object} config - the parsed query (`includeDrafts`, `dataSchema`)
- * @returns {Promise<Object|Array|null>} Processed item(s), or null for a draft this run withholds
+ * @returns {Promise<Object|null>} The processed record, or null for a draft this run withholds
  */
 async function processJsonItem(dir, filename, siteRoot, recordsRoot, basePath, config) {
   const filepath = join(dir, filename)
@@ -527,8 +502,8 @@ async function processJsonItem(dir, filename, siteRoot, recordsRoot, basePath, c
  * Process a single BibTeX file into an array of CSL-JSON bibliography items.
  *
  * Each `@entry{key, ...}` becomes one item. The BibTeX cite key is preserved
- * as `id` (CSL-JSON convention) and copied to `slug` so per-record file
- * emission and runtime lookups behave the same as for other formats.
+ * as `id` (CSL-JSON convention) and names the record — its `$name` — as a file's
+ * name does for other formats.
  *
  * No asset processing — bibliography records reference URLs and DOIs, not
  * local files.
@@ -537,7 +512,7 @@ async function processJsonItem(dir, filename, siteRoot, recordsRoot, basePath, c
  * @param {string} filename - BibTeX filename (.bib)
  * @param {string} siteRoot - Site root, for messages
  * @param {boolean} [includeDrafts] - keep `draft: true` records (a preview)
- * @returns {Promise<Array<Object>>} Array of CSL-JSON items, each with `slug`
+ * @returns {Promise<Array<Object>>} Array of CSL-JSON items, each with `$name`
  */
 async function processBibtexItem(dir, filename, siteRoot, includeDrafts = false) {
   const filepath = join(dir, filename)
@@ -546,7 +521,7 @@ async function processBibtexItem(dir, filename, siteRoot, includeDrafts = false)
   const entries = parseBibtex(raw)
   return entries
     .filter(entry => entry && entry.id && !withheld(entry, `${where} @${entry.id}`, includeDrafts))
-    .map(entry => ({ slug: entry.id, ...entry }))
+    .map(entry => ({ ...entry, $name: String(entry.id) }))
 }
 
 /**
@@ -575,6 +550,7 @@ async function processContentItem(dir, filename, config, siteRoot, basePath, rec
 
   // Parse frontmatter and body
   const { frontmatter, body } = parseFrontmatter(raw, filepath)
+  refuseNotOneRecord(frontmatter, relative(siteRoot, filepath), slug)
 
   // A draft is left out — before its assets are copied, so nothing of it ships.
   if (withheld(frontmatter, relative(siteRoot, filepath), config.includeDrafts)) {
@@ -598,6 +574,15 @@ async function processContentItem(dir, filename, config, siteRoot, basePath, rec
   return deliverRecord({ slug, ...frontmatter }, config, relative(siteRoot, filepath), { doc: content, markdown: body })
 }
 
+/**
+ * ⭐ WHAT A QUERY'S FILES HOLD, beside the merged view this module evaluates a query over (ruled
+ * 2026-09-27 [Diego]): each record's BRIEF, which its list holds — the brief's fields at the top —
+ * and the record WHOLE, as stored, which its own file holds — a key per section, the brief's
+ * included. Carried on each compiled item under these keys, which `JSON.stringify` never writes.
+ */
+export const BRIEF_RECORD = Symbol.for('uniweb.query.brief')
+export const WHOLE_RECORD = Symbol.for('uniweb.query.whole')
+
 /**
  * One record as its file holds it → the record a component receives.
  *
@@ -605,7 +590,7 @@ async function processContentItem(dir, filename, config, siteRoot, basePath, rec
  * backend: the brief's fields at the top and every other section under its own name
  * (`@uniweb/schemas/conform`'s `toDeliveredRecord`), with a markdown body in the
  * schema's content body field — the ProseMirror document for a `format: prosemirror`
- * field (`article_body.content`, for `@std/article`), the markdown source for a markup
+ * field (`body.content`, for `@std/article`), the markdown source for a markup
  * `text` one. A component is written against one shape, so both lanes deliver the same
  * one — ruled 2026-09-24 [Diego] as a requirement that the shape be one AND a good one,
  * not as an instruction to adopt the host's. ⚠️ It was built by adopting the host's as it
@@ -627,14 +612,19 @@ async function processContentItem(dir, filename, config, siteRoot, basePath, rec
  * ⛔ A record written in the retired flat form (`misplacedFields`) STOPS THE BUILD, as it
  * stops a push: which section a key belongs in is not a guess to make.
  *
- * @param {*} record - the record as its file holds it, `slug` included
+ * @param {*} record - the record as its file holds it, with `slug`: the file's name, added by its reader
  * @param {Object} config - the parsed query (`dataSchema`, `excerpt`)
- * @param {string} where - the file, and the entry in a file of several, for a message
+ * @param {string} where - the file, for a message
  * @param {{ doc: Object, markdown: string }|null} [body] - a markdown record's body
  * @returns {*} the delivered record (anything but a record, as it came)
  */
-function deliverRecord(record, config, where, body = null) {
-  if (!record || typeof record !== 'object' || Array.isArray(record)) return record
+function deliverRecord(file, config, where, body = null) {
+  if (!file || typeof file !== 'object' || Array.isArray(file)) return file
+  // ⭐ The record's NAME rides as `$name`, and nowhere else. `slug` is how its reader hands the
+  // file's name to here — the file's stem — and never a key of what a component
+  // receives: a records service serves no `slug`, and a field of that name has no meaning to
+  // the framework [Diego, 2026-09-27]. ⛔ Until then the delivered record carried `slug` too.
+  const { slug: handle, ...record } = file
   const schema = config.dataSchema || null
   let out
   if (!schema) {
@@ -657,12 +647,58 @@ function deliverRecord(record, config, where, body = null) {
       out.image = out.image || extractFirstImage(body.doc)
     }
     if (config.references) out = config.references.deliver(schema, out, where)
+    out[WHOLE_RECORD] = storedRecord(record, schema, config, where, body, out)
+  }
+  if (handle !== undefined && handle !== null && handle !== '') {
+    out.$name = String(handle)
+    if (out[WHOLE_RECORD]) {
+      const { $uuid, ...rest } = out[WHOLE_RECORD]
+      out[WHOLE_RECORD] = { ...($uuid !== undefined ? { $uuid } : {}), $name: out.$name, ...rest }
+    }
   }
-  const handle = record.slug
-  if (handle !== undefined && handle !== null && handle !== '') out.$name = String(handle)
   return out
 }
 
+/**
+ * The record WHOLE, as stored — what its own file serves and a whole question answers: its file's
+ * fields under their sections (`toStoredRecord`), its markdown body in the content body field's
+ * section, its references hydrated as a host hydrates them. An excerpt and an image the build
+ * derives go in its brief only where the brief declares them.
+ */
+function storedRecord(record, schema, config, where, body, merged) {
+  let file = { ...record }
+  if (body) placeBodyInFile(file, schema, body)
+  if (config.references) file = config.references.deliver(schema, file, where, { file: true })
+  const stored = toStoredRecord(schema, file)
+  const layout = recordLayout(schema)
+  const briefName = schema.fields ? 'brief' : (layout?.flat ? layout.sections[0][0] : layout?.brief)
+  const declared = schema.fields ?? (layout?.sections.find(([n]) => n === briefName)?.[1]?.fields || {})
+  if (briefName && stored[briefName] && typeof stored[briefName] === 'object') {
+    for (const key of ['excerpt', 'image']) {
+      if (declared[key] && stored[briefName][key] == null && merged[key] != null) {
+        stored[briefName] = { ...stored[briefName], [key]: merged[key] }
+      }
+    }
+  }
+  return stored
+}
+
+/** A markdown body placed where the record's FILE holds its content body field (`fileSection`). */
+function placeBodyInFile(file, schema, body) {
+  const blank = !body.markdown || !body.markdown.trim()
+  const target = contentBodyField(schema)
+  if (!target || blank) return
+  const value = target.field?.type === 'text' ? body.markdown : body.doc
+  if (!target.fileSection) {
+    if (file[target.key] == null) file[target.key] = value
+    return
+  }
+  const held = file[target.fileSection]
+  if (held != null && (typeof held !== 'object' || Array.isArray(held))) return
+  if (held?.[target.key] != null) return
+  file[target.fileSection] = { ...(held || {}), [target.key]: value }
+}
+
 /**
  * Put a markdown body where the delivered record carries its schema's content body
  * field (`contentBodyField`) — unless the record already states that field, or the body
@@ -724,8 +760,8 @@ export function flatFormRefusal(where, ref, schema, misplaced) {
  * Every source file in a collection, as paths relative to the collection root —
  * `hello.md`, `2024/spring.md`, `2024/q1/notes.yml`.
  *
- * Nesting is how an author gives a collection an internal structure, and it is
- * what the `path` field and the `under` predicate address. Before this walk the
+ * Nesting is how an author organizes the files; the folder branch a record sits in, which a
+ * query's `scope:` reads, is `records/folder.yml`'s to say (`records-config.js`). Before this walk the
  * scan was a flat `readdir`, so a record in a subdirectory was not ignored with
  * a warning — it was invisible, and the site simply rendered without it.
  *
@@ -762,18 +798,18 @@ async function collectSourceFiles(dir, rel = '') {
 function warnDuplicateSlugs(items, queryName) {
   const seen = new Map()
   for (const item of items) {
-    if (!item || item.slug === undefined) continue
-    const slug = String(item.slug)
-    const where = item.path ? `${item.path}/` : ''
-    if (seen.has(slug)) {
+    if (!item || item.$name === undefined) continue
+    const name = String(item.$name)
+    const where = item[BRANCH_KEY] ? `${item[BRANCH_KEY]}/` : ''
+    if (seen.has(name)) {
       console.warn(
-        `[query-processor] Query "${queryName}" has more than one record with ` +
-          `slug "${slug}" (${seen.get(slug)}${slug}, ${where}${slug}). Its detail route and ` +
-          `per-record file resolve to only one of them — give them distinct slugs.`
+        `[query-processor] Query "${queryName}" has more than one record named ` +
+          `"${name}" (${seen.get(name)}${name}, ${where}${name}). Its detail route and ` +
+          `per-record file resolve to only one of them — give them distinct names.`
       )
       continue
     }
-    seen.set(slug, where)
+    seen.set(name, where)
   }
 }
 
@@ -851,7 +887,7 @@ function referenceHydrator({ poolBySchema, dataSchemas, siteDir, recordsRoot, ba
         if (!targets.has(ref)) targets.set(ref, await load(ref))
       }
     },
-    deliver(schema, record, where) {
+    deliver(schema, record, where, { file = false } = {}) {
       return mapReferences(
         schema,
         record,
@@ -865,7 +901,7 @@ function referenceHydrator({ poolBySchema, dataSchemas, siteDir, recordsRoot, ba
           }
           return value
         },
-        { delivered: true }
+        { delivered: !file }
       )
     },
   }
@@ -891,11 +927,19 @@ function pickBrief(record, keys) {
     return out
   }
   for (const [key, value] of Object.entries(record)) {
-    if (!key.startsWith('$') && !['slug', 'path', 'excerpt', 'image', 'draft'].includes(key)) out[key] = value
+    if (!key.startsWith('$') && !['slug', 'excerpt', 'image', 'draft'].includes(key)) out[key] = value
   }
   return out
 }
 
+// A query's records in folder-tree order (`folderTreeOrder`), before anything reads them — so
+// `where`, `sort` (stable) and `limit` start from the order a records service answers in.
+function inFolderOrder(pooled, rank) {
+  if (!rank || pooled.length < 2) return pooled
+  const at = (e) => rank.get(e.id) ?? Number.POSITIVE_INFINITY
+  return [...pooled].sort((a, b) => at(a) - at(b))
+}
+
 /**
  * Collect and process all of a query's records
  *
@@ -909,7 +953,7 @@ async function collectItems(siteDir, config, recordsRoot, basePath, locale = nul
   // sync lane makes, from the same reader, so the two lanes cannot disagree
   // about which files are a query's records. They used to: this one recursed
   // into a collection directory and sync did not.
-  const pooled = config.poolEntities || []
+  const pooled = inFolderOrder(config.poolEntities || [], config.folderRank)
   if (pooled.length === 0) return []
 
   // The records this query's references name, read before its own — delivering one
@@ -922,10 +966,17 @@ async function collectItems(siteDir, config, recordsRoot, basePath, locale = nul
   // BibTeX → CSL-JSON bibliography items).
   let items = await readPooledRecords(pooled, config, siteDir, recordsRoot, basePath)
 
-  // ⭐ `path` IS THE FOLDER `folder.yml` PLACED THE RECORD IN — `''` at the top —
+  // ⭐ `$branch` IS THE FOLDER `folder.yml` PLACED THE RECORD IN — `''` at the top —
   // and it is the whole reason folders exist: `scope: archive` is how a query asks
   // for a slice. Structure is query scope, not navigation.
   //
+  // ⛔ THE COMPILED FILE'S OWN KEY, NOT THE RECORD'S (ruled 2026-09-27 [Diego]): the
+  // browser evaluates `scope` over this file, so the file holds each record's branch, and
+  // no answer carries it — `@uniweb/core`'s `evaluateQuery` reads it and drops it, as a
+  // records service answers no branch. ⛔ Until then it was `path`: it reached every
+  // component, wrote over an authored field named `path`, and made a `[...path]` record's
+  // link `<branch>/<name>`.
+  //
   // ⛔ THIS WAS HARDCODED TO `''` FOR A WHILE, AND THE COMMENT SAID "until the
   // folder producer lands". It landed, and this was not revisited — so every
   // folder slice matched NOTHING on the delivery lane, silently, which is the one
@@ -935,13 +986,13 @@ async function collectItems(siteDir, config, recordsRoot, basePath, locale = nul
   // ⚠️ It stays a SCALAR. `@uniweb/core`'s `withinScope` matches strings only, so
   // an array would match nothing — one placement per record is the ruling.
   items = items.map((result, i) => {
-    const path = pooled[i] ? (config.placements?.get(pooled[i].id)?.path ?? '') : ''
-    if (Array.isArray(result)) return result.map((item) => item && { ...item, path })
-    return result && { ...result, path }
+    const branch = pooled[i] ? (config.placements?.get(pooled[i].id)?.path ?? '') : ''
+    if (Array.isArray(result)) return result.map((item) => item && { ...item, [BRANCH_KEY]: branch })
+    return result && { ...result, [BRANCH_KEY]: branch }
   })
 
-  // Flatten one level: array-form YAML/JSON files and every .bib file
-  // contribute their entries individually.
+  // Flatten one level: a .bib file contributes its entries individually. Every other
+  // record file is one record (`record-file.js`).
   items = items.flat()
 
   // Filter out nulls (drafts this run withholds)
@@ -949,19 +1000,12 @@ async function collectItems(siteDir, config, recordsRoot, basePath, locale = nul
 
   // ⭐ `$name` IS THE RECORD HANDLE ON EVERY SITE (ruled 2026-09-11 [Diego]) — the
   // field a `[slug]` or `[...path]` page matches, and the one the records service
-  // serves. It is the record's FINAL slug — a frontmatter `slug:` (which wins over the
-  // filename), a BibTeX cite key and an array-form file's own `slug` all count — exactly
-  // what our sync sends as the entry's name (`uwx/entity-source.js`). `deliverRecord`
-  // sets it for a markdown, YAML or JSON record, before the brief is lifted (a brief's
-  // own `slug` FIELD must not become the handle); a BibTeX entry gets it here. `slug`
-  // stays: foundations and templates read it.
-  items = items.map((item) => (
-    item && typeof item === 'object' && item.$name === undefined &&
-    item.slug !== undefined && item.slug !== null && item.slug !== ''
-      ? { ...item, $name: String(item.slug) }
-      : item
-  ))
-
+  // serves: the name its file gives it — the file's stem, or a BibTeX entry's cite key
+  // (a file's own `slug:` renamed it, and a list file held several, until 2026-09-27;
+  // both are refused now, `record-file.js`) — exactly what our sync
+  // sends as the entry's name (`uwx/entity-source.js`). `deliverRecord` and
+  // `processBibtexItem` set it. ⛔ Until 2026-09-27 the delivered record carried `slug`
+  // beside it, and this filled `$name` from it; no record carries `slug` now.
   warnDuplicateSlugs(items, config.name)
 
   // ⛔ ORDER MATCHES `data-fetcher.js::applyPostProcessing` — where, then sort. Two
@@ -982,16 +1026,27 @@ async function collectItems(siteDir, config, recordsRoot, basePath, locale = nul
   //
   // ⛔ `scope` is NEVER baked, fixed or routed — the runtime applies it, as the
   // records service does, so a routed `scope: :dir` binds per page.
+  //
+  // ⭐ A PATH READS THE RECORD AS STORED, as the records service reads it (ruled 2026-09-27
+  // [Diego]): `details` is the brief's field and `details.pages` the
+  // section's, even where the two share a name — which the merged view the records are carried in
+  // cannot hold apart. A record with no data schema is read as it is.
   const fixed = withoutRouteVariables({ where: config.where })
-  if (fixed.where) {
-    items = applyWhere(items, fixed.where)
+  const asked = config.dataSchema
+    ? mapQueryPaths({ where: fixed.where, sort: config.sort }, (path) => storedPath(config.dataSchema, path))
+    : { where: fixed.where, sort: config.sort }
+  const read = (item) => (item && item[WHOLE_RECORD]) || item
+  if (asked.where) {
+    const kept = new Set(applyWhere(items.map(read), asked.where))
+    items = items.filter((item) => kept.has(read(item)))
   }
 
   // The query's `sort` orders the file; the runtime applies whichever sort wins —
   // a binding's own, else this one — so the order here only spares it the work.
   // Texts collate in the site's default language; each page re-sorts in its own.
-  if (config.sort) {
-    items = applySort(items, config.sort, { locale })
+  if (asked.sort) {
+    const itemOf = new Map(items.map((item) => [read(item), item]))
+    items = applySort([...itemOf.keys()], asked.sort, { locale }).map((held) => itemOf.get(held))
   }
 
   // ⛔ `limit` IS NEVER BAKED. A query's `limit` is part of its set (ruled 2026-09-14
@@ -1004,9 +1059,44 @@ async function collectItems(siteDir, config, recordsRoot, basePath, locale = nul
   // file — before a page's `scope` or routed clauses, which the runtime has applied
   // since 2026-09-11, could select anything from it.
 
+  // ⭐ EACH RECORD'S BRIEF — what its list holds: the brief's fields at the top, beside the record's
+  // own keys, what the build derives (`excerpt`, `image`), and the branch the list holds for `scope`
+  // (`$branch`, which no answer carries). A record of a schema with no
+  // brief, or of one with a single section, is its brief as it is.
+  const briefOf = briefBuilder(config.dataSchema)
+  if (briefOf) {
+    items = items.map((item) =>
+      item && typeof item === 'object' && !Array.isArray(item) ? { ...item, [BRIEF_RECORD]: briefOf(item) } : item
+    )
+  }
+
   return items
 }
 
+/**
+ * A record's BRIEF, built from the record AS STORED — its brief section's fields — beside the keys of
+ * the merged view that are neither a section nor a brief field. ⛔ Not the merged view less the other
+ * sections: sections are namespaces (ruled 2026-09-26 [Diego]), so a brief field may share a
+ * section's name, and the merged view holds only one of the two. Null when a list is the record as
+ * it is.
+ */
+function briefBuilder(schema) {
+  const layout = schema ? recordLayout(schema) : null
+  if (!layout || schema.fields || layout.flat || !layout.brief) return null
+  const sections = new Set(layout.sections.map(([name]) => name))
+  const fields = new Set(Object.keys(briefFieldMap(schema) || {}))
+  return (item) => {
+    const stored = item[WHOLE_RECORD]
+    const held = stored?.[layout.brief]
+    const brief = held && typeof held === 'object' && !Array.isArray(held) ? held : null
+    const out = {}
+    for (const [key, value] of Object.entries(item)) {
+      if (!sections.has(key) && !(brief && fields.has(key))) out[key] = value
+    }
+    return brief ? { ...out, ...brief } : out
+  }
+}
+
 /**
  * Compile every query over the site's records
  *
@@ -1045,7 +1135,7 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
   }
 
   // ⭐ EVERY FILE IN `records/` IS A RECORD (ruled 2026-09-21 [Diego]), so every one
-  // is compiled; `records/folder.yml` only says which folder each sits in (`path`),
+  // is compiled; `records/folder.yml` only says which folder each sits in (`$branch`),
   // which is what a query's `scope` reads. ⛔ Until 2026-09-21 `records.yml`, at the
   // site root, listed the records, and an unlisted file was left out of
   // `/data/<name>.json` here.
@@ -1063,6 +1153,10 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
   const folder = resolveFolder(recordsCfg.entries, pool.entities, { dir: pool.dir })
   for (const e of folder.errors) console.error(`[query-processor] ${e}`)
   for (const w of folder.warnings) console.warn(`[query-processor] ${w}`)
+  // ⭐ A QUESTION WITH NO `sort` ANSWERS IN FOLDER-TREE ORDER (ruled 2026-09-27 [Diego]) — the
+  // order a backend's records service answers in, over the tree a push places there. ⛔ Until then
+  // this lane answered in the order the directory walk found the files.
+  const folderRank = new Map(folderTreeOrder(folder.nodes).map((id, i) => [id, i]))
 
   const poolBySchema = groupPoolBySchema(pool.entities)
   const recordsRoot = resolve(siteDir, pool.dir)
@@ -1083,6 +1177,7 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
     const parsed = parseQueryConfig(name, config)
     parsed.poolEntities = parsed.schema ? poolBySchema.get(parsed.schema) || [] : []
     parsed.placements = folder.placements
+    parsed.folderRank = folderRank
     parsed.includeDrafts = includeDrafts
     parsed.dataSchema = (parsed.schema && dataSchemas[parsed.schema]) || null
     parsed.references = references
@@ -1123,13 +1218,51 @@ async function querySchemas(siteDir, queriesConfig) {
         `their files hold them rather than as a component receives them: ${message}`
     )
   }
+  await typeByDataKey(siteDir, queriesConfig, schemas)
   return schemas
 }
 
 /**
- * Reconcile a deferred collection's per-record directory with the records it
- * should hold this run — delete the `<slug>.json` files that are no longer
- * backed by a record.
+ * ⭐ A QUERY NAMED FOR A DATA KEY HOLDS RECORDS OF THE KEY'S TYPE (ruled 2026-09-25 [Diego],
+ * `uwx/data-key-types.js`). `articles:` with no `schema:` names `@/articles`; when no data schema
+ * has that name while the foundation's section types declare `data: { articles: '@/post' }`, its
+ * records are `@/post` records — a push sends them as such, and they are delivered as such here,
+ * where they still live and are keyed by the name (`records/articles/`). Never for a schema the
+ * query asked for explicitly: that one is the author's, and does not resolve. ⛔ Until 2026-09-27
+ * this lane compiled them as if they had no data schema, while a push typed them.
+ *
+ * @param {string} siteDir
+ * @param {Object} queriesConfig
+ * @param {Object} schemas - resolved data schemas by ref; a typed query's ref is added to it
+ */
+async function typeByDataKey(siteDir, queriesConfig, schemas) {
+  const untyped = Object.entries(queriesConfig).filter(
+    ([name, c]) => c && typeof c === 'object' && c.url === undefined && c.schema === `@/${name}` && !schemas[c.schema]
+  )
+  if (untyped.length === 0) return
+  // `config.queries` carries no trace of whether its author wrote the schema; the declarations do.
+  let declarations = {}
+  try {
+    declarations = (await resolveQueriesConfig(siteDir)).declarations || {}
+  } catch {
+    // a declaration the build refuses is reported where the build reads it
+  }
+  const pending = untyped.filter(([name]) => declarations[name]?.schemaExplicit !== true)
+  if (pending.length === 0) return
+  const keyTypes = dataKeyTypes(await foundationSections(siteDir))
+  const wanted = new Map()
+  for (const [name, c] of pending) {
+    const type = keyTypes.get(name)
+    if (type) wanted.set(c.schema, type)
+  }
+  if (wanted.size === 0) return
+  const { schemas: types } = await resolveRecordSchemas(siteDir, wanted.values())
+  for (const [ref, type] of wanted) if (types[type]) schemas[ref] = types[type]
+}
+
+/**
+ * Reconcile a query's per-record directory with the records it should hold this
+ * run — delete the `<$name>.json` files that are no longer backed by a record.
  *
  * Why this is not optional. `public/data/` is a persistent, normally-committed
  * directory, so anything written there survives until something removes it.
@@ -1141,11 +1274,9 @@ async function querySchemas(siteDir, queriesConfig) {
  * that was public a moment ago.
  *
  * `public/data/` is the build's output directory and nothing else — authors
- * provide structured data through `collections/`, which is the only supported
+ * provide structured data through `records/`, which is the only supported
  * way. So `<name>/` is entirely ours and the reconciliation is total: anything
- * in it that this run did not write is stale by definition. `expected` is
- * empty when a collection stops declaring `deferred:`, which correctly clears
- * a directory that will otherwise never be written again.
+ * in it that this run did not write is stale by definition.
  *
  * NOT covered: a collection removed from `site.yml` entirely. There is no
  * declaration left to reconcile against, so pruning it would mean the build
@@ -1206,62 +1337,46 @@ export async function writeQueryFiles(siteDir, byQuery, queriesConfig = null) {
   for (const [name, items] of Object.entries(byQuery)) {
     const rawConfig = queriesConfig?.[name]
     const parsed = rawConfig ? parseQueryConfig(name, rawConfig) : null
-    const deferred = parsed?.deferred
-
-    if (deferred && deferred.length > 0) {
-      // `deferred:` is set — emit two payloads:
-      //   1. The cascade JSON at /data/<name>.json with deferred fields stripped.
-      //      This is what `query: <name>` declarations deliver everywhere.
-      //   2. Per-record full files at /data/<name>/<slug>.json with every field.
-      //      Dynamic-route singular fetches and kit's useWholeRecord read these.
-      const recordsDir = join(dataDir, name)
-      await mkdir(recordsDir, { recursive: true })
-
-      const written = new Set()
-      for (const item of items) {
-        if (!item || typeof item !== 'object' || !item.slug) continue
-        const filename = `${item.slug}.json`
-        await writeFile(join(recordsDir, filename), JSON.stringify(item, null, 2))
-        written.add(filename)
-      }
-      const perRecordCount = written.size
-      const pruned = await pruneOrphanedRecords(dataDir, name, written)
-
-      const stripped = items.map((item) => {
-        if (!item || typeof item !== 'object') return item
-        const out = { ...item }
-        for (const field of deferred) delete out[field]
-        return out
-      })
-      const cascadePath = join(dataDir, `${name}.json`)
-      await writeFile(cascadePath, JSON.stringify(stripped, null, 2))
+
+    // ⭐ TWO PAYLOADS FOR EVERY QUERY (ruled 2026-09-27 [Diego]):
+    //   1. Each record WHOLE, as stored, at /data/<name>/<$name>.json — a key per section, the
+    //      brief's included — what a whole question answers: a parametric page's record for a
+    //      component that declares `'@x/y/*'`, and kit's `useWholeRecord`.
+    //   2. The list at /data/<name>.json — each record's BRIEF, the brief's fields at the top —
+    //      what `query: <name>` delivers everywhere else. ⛔ `deferred:`, which left fields of the
+    //      brief out of it, was retired the same day [Diego].
+    // ⛔ Until then only a `deferred:` query had per-record files, and they held the merged view:
+    // the brief's fields at the top beside the other sections' names.
+    const recordsDir = join(dataDir, name)
+    await mkdir(recordsDir, { recursive: true })
+    const written = new Set()
+    for (const item of items) {
+      if (!item || typeof item !== 'object' || Array.isArray(item)) continue
+      const handle = item.$name
+      if (handle === undefined || handle === null || handle === '') continue
+      const filename = `${handle}.json`
+      // The record's own file answers it whole, so it holds no branch (the list does, for `scope`).
+      const { [BRANCH_KEY]: _branch, ...own } = item
+      await writeFile(join(recordsDir, filename), JSON.stringify(item[WHOLE_RECORD] ?? own, null, 2))
+      written.add(filename)
+    }
+    const pruned = await pruneOrphanedRecords(dataDir, name, written)
+
+    const list = items.map((item) =>
+      item && typeof item === 'object' && !Array.isArray(item) ? { ...(item[BRIEF_RECORD] ?? item) } : item
+    )
+    const cascadePath = join(dataDir, `${name}.json`)
+    await writeFile(cascadePath, JSON.stringify(list, null, 2))
+    console.log(
+      `[query-processor] Generated ${cascadePath} (${items.length} items) + ${written.size} per-record files`
+    )
+    if (pruned.length > 0) {
+      // A deletion is always worth naming. These files were public a moment
+      // ago, so "which ones went" is the question an author will have.
       console.log(
-        `[query-processor] Generated ${cascadePath} (${items.length} items, ` +
-        `deferred: [${deferred.join(', ')}]) + ${perRecordCount} per-record files`
+        `[query-processor] Removed ${pruned.length} stale per-record ` +
+        `file(s) from ${recordsDir}: ${pruned.join(', ')}`
       )
-      if (pruned.length > 0) {
-        // A deletion is always worth naming. These files were public a moment
-        // ago, so "which ones went" is the question an author will have.
-        console.log(
-          `[query-processor] Removed ${pruned.length} stale per-record ` +
-          `file(s) from ${recordsDir}: ${pruned.join(', ')}`
-        )
-      }
-    } else {
-      const filepath = join(dataDir, `${name}.json`)
-      await writeFile(filepath, JSON.stringify(items, null, 2))
-      console.log(`[query-processor] Generated ${filepath} (${items.length} items)`)
-
-      // This collection is not deferred, so it has no per-record files. If it
-      // used to, the directory is still there and will never be written again
-      // — every file in it is stale. Same reconciliation, empty expected set.
-      const pruned = await pruneOrphanedRecords(dataDir, name, new Set())
-      if (pruned.length > 0) {
-        console.log(
-          `[query-processor] Removed ${pruned.length} per-record file(s) ` +
-          `from ${join(dataDir, name)} — "${name}" no longer declares deferred:`
-        )
-      }
     }
   }
 }