@uniweb/build 0.60.0 → 0.62.0

package/src/site/queries-config.js

@@ -30,8 +30,10 @@
 
 import { join } from 'node:path'
 import { existsSync, readFileSync } from 'node:fs'
-import { briefFields, flatRecordFields } from '@uniweb/schemas/conform'
+import { recordLayout } from '@uniweb/schemas/conform'
 import { detectFoundationType } from './foundation-ref.js'
+import { buildDataSchemaMap, SCHEMA_NOT_FOUND } from '../resolve-data-schema.js'
+import { resolveFoundationSrcPath } from '../utils/foundation-source-root.js'
 import { refuseQueryRoute, refuseLimit } from './data-fetcher.js'
 import { readFile } from 'node:fs/promises'
 import yaml from 'js-yaml'
@@ -325,13 +327,17 @@ export function toConfigQueries(declarations) {
  * schema should not have to say it twice, in a second vocabulary, with nothing
  * checking the two against each other.
  *
- * ⇒ `deferred` = the schema's flat-record fields MINUS its brief fields.
+ * ⇒ `deferred` = every top-level section of the schema other than its brief — the keys
+ * a delivered record holds them under (`article_body` for `@std/article`), which is
+ * exactly what a host's records service leaves out of a list and adds for `whole`.
+ * ⛔ It was the flat form's fields minus the brief's until 2026-09-24; a delivered
+ * record carries those under their section, so stripping them by name stripped nothing.
  *
  * Derived from the SCHEMA, never from a record. That is what keeps the
  * build-derived keys safe without a reserved list: `slug`, `route`, `path`,
- * `excerpt`, `image` and `lastModified` are not schema fields, so they are never
- * in the difference and never stripped. `content` is not exempt — it is
- * schema-governed, and usually the heavy field the split exists for.
+ * `excerpt`, `image` and `lastModified` are not sections, so they are never
+ * stripped. A markdown body goes where its content field is — inside `article_body`,
+ * say — so it is deferred with that section.
  *
  * ⛔ Silent on every path that cannot answer, because none of them is an error:
  *
@@ -342,8 +348,8 @@ export function toConfigQueries(declarations) {
  *     sync lane already applies. `dist/meta/schema.json` carries the schemas
  *     COMPONENTS reference, so a collection whose schema no component binds is
  *     simply not there;
- *   - the schema states no brief (`briefFields` → null, e.g. a root list) → there
- *     is no lean shape to honour, so records stay whole.
+ *   - the schema has no brief, or only one section (`recordLayout`) → there is no
+ *     lean shape to honour, so records stay whole.
  *
  * The last two are why this reads the built artifact rather than resolving
  * schemas itself: it is the same input the sync lane uses, so both lanes agree
@@ -365,7 +371,7 @@ async function deriveDeferredFromSchemas(siteRoot, siteYml, declarations) {
 }
 
 /**
- * The `deferred:` a schema implies — every record field its **brief** does not name.
+ * The `deferred:` a schema implies — every top-level section but its **brief**, by name.
  *
  * ⛔ ONE IMPLEMENTATION, TWO CALLERS, and that is the point. `deriveDeferredFromSchemas`
  * above uses it to FILL an unstated `deferred:`; `uwx/records-project.js` uses it to
@@ -382,14 +388,63 @@ async function deriveDeferredFromSchemas(siteRoot, siteYml, declarations) {
  *   derivation to recognize
  */
 export function deferredFromSchema(schema) {
-  if (!schema) return null
-  const brief = briefFields(schema)
-  if (!brief) return null
-  const all = Object.keys(flatRecordFields(schema) || {})
-  const heavy = all.filter((f) => !brief.has(f))
+  const layout = schema ? recordLayout(schema) : null
+  if (!layout || layout.flat || !layout.brief) return null
+  const heavy = layout.sections.map(([name]) => name).filter((name) => name !== layout.brief)
   return heavy.length ? heavy : null
 }
 
+/**
+ * The data schemas a site's records are shaped by, keyed by ref — each resolved from
+ * the LOCAL foundation's SOURCE by the resolver its build uses (`buildDataSchemaMap`),
+ * so the static lane delivers a record in the shape a component is written against
+ * (`query-processor.js`) whether or not the foundation has been built.
+ *
+ * ⛔ Not `dist/meta/schema.json`, which `foundationDataSchemas` below reads for the
+ * sync lane: a dev server does not build the foundation, so a site that had never been
+ * built would compile its records in one shape under `pnpm dev` and another in
+ * production — and a component reads them in exactly one.
+ *
+ * A `@/name` ref the foundation defines no schema for is absent without a word: a query
+ * is named after no schema when its records have none. Any other ref that does not
+ * resolve is absent too, and reported in `failures`. With no local foundation only
+ * `@std/*` refs resolve — from the build's own copy of the standard schemas — since
+ * nothing else is on disk.
+ *
+ * @param {string} siteRoot
+ * @param {Iterable<string>} refs - the `schema:` refs of the site's queries
+ * @param {{ siteYml?: object }} [opts] - an already-read site.yml
+ * @returns {Promise<{ schemas: object, failures: Array<{ ref: string, message: string }> }>}
+ */
+export async function resolveRecordSchemas(siteRoot, refs, opts = {}) {
+  const wanted = [...new Set([...(refs || [])].filter((r) => typeof r === 'string' && r))]
+  const schemas = {}
+  const failures = []
+  if (wanted.length === 0) return { schemas, failures }
+  const siteYml = opts.siteYml || (await readYamlFile(join(siteRoot, 'site.yml')))
+  const srcDir = localFoundationSrcDir(siteRoot, siteYml)
+  for (const ref of wanted) {
+    if (!srcDir && !ref.startsWith('@std/')) continue
+    try {
+      Object.assign(schemas, await buildDataSchemaMap([ref], { srcDir: srcDir ?? siteRoot }))
+    } catch (err) {
+      if (err?.code !== SCHEMA_NOT_FOUND) failures.push({ ref, message: err?.message || String(err) })
+    }
+  }
+  return { schemas, failures }
+}
+
+/** The source directory of the site's foundation when it is local, else null. */
+function localFoundationSrcDir(siteRoot, siteYml) {
+  if (!siteYml?.foundation) return null
+  try {
+    const info = detectFoundationType(siteYml.foundation, siteRoot)
+    return info?.type === 'local' && info.path ? resolveFoundationSrcPath(info.path) : null
+  } catch {
+    return null // a declaration the resolver refuses is reported by the build that reads it
+  }
+}
+
 /** The data schemas a site's foundation declares, or null when unresolvable. */
 export function foundationDataSchemas(siteRoot, siteYml) {
   return loadFoundationDataSchemas(siteRoot, siteYml)

package/src/site/query-processor.js

@@ -64,7 +64,10 @@ import { resolveAssetPath, walkContentAssets, isLocalAssetPath } from './assets.
 import { readEntityPool, groupPoolBySchema, poolDirsForSchema } from './entity-pool.js'
 import { readRecordsConfig, resolveFolder } from './records-config.js'
 import { isDraftRecord } from './record-draft.js'
+import { resolveRecordSchemas } from './queries-config.js'
 import { parseFrontmatter } from '../utils/frontmatter.js'
+import { toDeliveredRecord, contentBodyField, misplacedFields, mapReferences, recordLayout } from '@uniweb/schemas/conform'
+import { collectNestedRefs } from '@uniweb/schemas/format'
 
 // Try to import content-reader for markdown parsing
 let markdownToProseMirror
@@ -451,33 +454,42 @@ async function processDataItemAssets(data, itemPath, siteRoot, recordsRoot, base
  *
  * @param {string} dir - Collection directory path
  * @param {string} filename - YAML filename (.yml or .yaml)
- * @param {boolean} [includeDrafts] - keep `draft: true` records (a preview)
+ * @param {Object} config - the parsed query (`includeDrafts`, `dataSchema`)
  * @returns {Promise<Object|Array|null>} Processed item(s), or null for a draft this run withholds
  */
-async function processDataItem(dir, filename, siteRoot, recordsRoot, basePath, includeDrafts = false) {
+async function processDataItem(dir, filename, siteRoot, recordsRoot, basePath, config) {
   const filepath = join(dir, filename)
   const where = relative(siteRoot, filepath)
   const raw = await readFile(filepath, 'utf-8')
   const data = yaml.load(raw, YAML_OPTIONS) || {}
+  return processDataRecords(data, basename(filename, extname(filename)), filepath, where, siteRoot, recordsRoot, basePath, config)
+}
 
+/**
+ * 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.
+ */
+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 kept = data.filter((item, i) => !withheld(item, `${where} [${i}]`, includeDrafts))
-    for (const item of kept) {
+    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 kept
+    return out
   }
 
   // Mapping → single item
-  if (withheld(data, where, includeDrafts)) return null
-  const slug = basename(filename, extname(filename))
-  const item = { slug, ...data }
+  if (withheld(data, where, config.includeDrafts)) return null
+  const item = { slug: fileSlug, ...data }
   await processDataItemAssets(item, filepath, siteRoot, recordsRoot, basePath)
-  return item
+  return deliverRecord(item, config, where)
 }
 
 /**
@@ -489,33 +501,15 @@ async function processDataItem(dir, filename, siteRoot, recordsRoot, basePath, i
  *
  * @param {string} dir - Collection directory path
  * @param {string} filename - JSON filename
- * @param {boolean} [includeDrafts] - keep `draft: true` records (a preview)
+ * @param {Object} config - the parsed query (`includeDrafts`, `dataSchema`)
  * @returns {Promise<Object|Array|null>} Processed item(s), or null for a draft this run withholds
  */
-async function processJsonItem(dir, filename, siteRoot, recordsRoot, basePath, includeDrafts = false) {
+async function processJsonItem(dir, filename, siteRoot, recordsRoot, basePath, config) {
   const filepath = join(dir, filename)
   const where = relative(siteRoot, filepath)
   const raw = await readFile(filepath, 'utf-8')
-  const slug = basename(filename, '.json')
   const data = JSON.parse(raw)
-
-  // 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 kept = data.filter((item, i) => !withheld(item, `${where} [${i}]`, includeDrafts))
-    for (const item of kept) {
-      if (item && typeof item === 'object') {
-        await processDataItemAssets(item, filepath, siteRoot, recordsRoot, basePath)
-      }
-    }
-    return kept
-  }
-
-  // Object → single item
-  if (withheld(data, where, includeDrafts)) return null
-  const item = { slug, ...data }
-  await processDataItemAssets(item, filepath, siteRoot, recordsRoot, basePath)
-  return item
+  return processDataRecords(data, basename(filename, '.json'), filepath, where, siteRoot, recordsRoot, basePath, config)
 }
 
 /**
@@ -590,20 +584,127 @@ async function processContentItem(dir, filename, config, siteRoot, basePath, rec
   // This modifies content in place, updating paths to site-root-relative
   await processRecordAssets(content, filepath, siteRoot, recordsRoot, basePath)
 
-  // Extract excerpt
-  const excerpt = extractExcerpt(frontmatter, content, config.excerpt)
+  return deliverRecord({ slug, ...frontmatter }, config, relative(siteRoot, filepath), { doc: content, markdown: body })
+}
 
-  // Extract first image (frontmatter takes precedence)
-  // Note: paths in the frontmatter and the content have already been rewritten above
-  const image = frontmatter.image || extractFirstImage(content)
+/**
+ * One record as its file holds it → the record a component receives.
+ *
+ * ⭐ THE SHAPE A HOST'S RECORDS SERVICE ANSWERS — measured 2026-09-24 on a local
+ * 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
+ * `text` one. A component is written against one shape, so a static site hands it that
+ * one (ruled 2026-09-24 [Diego]: the same as hosted). ⛔ Until then a record reached a
+ * component as its file held it, its body in `content` at the top — a shape no host
+ * delivers.
+ *
+ * `$name` is the record's handle, taken BEFORE the lift: a brief may declare a `slug`
+ * field of its own (`@std/article`'s does), and the lift puts that one over the file's.
+ *
+ * A record whose query has no data schema (`resolveRecordSchemas`) is delivered as its
+ * file holds it, a markdown body as `content`, which is what the static lane always did;
+ * so is a body its schema has no field for — a push refuses that one. A markdown record
+ * also gets `excerpt` and `image` where it states none, derived from its body: the
+ * static lane's own, and not what a host adds.
+ *
+ * Its references are delivered hydrated, as a host delivers them (`referenceHydrator`).
+ *
+ * ⛔ 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 {Object} config - the parsed query (`dataSchema`, `excerpt`)
+ * @param {string} where - the file, and the entry in a file of several, 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
+  const schema = config.dataSchema || null
+  let out
+  if (!schema) {
+    out = body
+      ? {
+          ...record,
+          excerpt: extractExcerpt(record, body.doc, config.excerpt),
+          // paths in the record and the body have already been rewritten
+          image: record.image || extractFirstImage(body.doc),
+          content: body.doc,
+        }
+      : { ...record }
+  } else {
+    const misplaced = misplacedFields(schema, record)
+    if (misplaced.length) throw new Error(flatFormRefusal(where, config.schema, schema, misplaced))
+    out = { ...toDeliveredRecord(schema, record) }
+    if (body) {
+      placeBody(out, schema, body)
+      out.excerpt = extractExcerpt(out, body.doc, config.excerpt)
+      out.image = out.image || extractFirstImage(body.doc)
+    }
+    if (config.references) out = config.references.deliver(schema, out, where)
+  }
+  const handle = record.slug
+  if (handle !== undefined && handle !== null && handle !== '') out.$name = String(handle)
+  return out
+}
 
-  return {
-    slug,
-    ...frontmatter,
-    excerpt,
-    image,
-    content
+/**
+ * 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
+ * is empty. With no such field the body stays `content`, at the top.
+ */
+function placeBody(out, schema, body) {
+  const blank = !body.markdown || !body.markdown.trim()
+  const target = contentBodyField(schema)
+  if (!target) {
+    if (!blank) out.content = body.doc
+    return
   }
+  if (blank) return
+  const value = target.field?.type === 'text' ? body.markdown : body.doc
+  if (!target.section) {
+    if (out[target.key] == null) out[target.key] = value
+    return
+  }
+  const held = out[target.section]
+  // A section that is not a record is the file's to fix — `uniweb validate` names it.
+  if (held != null && (typeof held !== 'object' || Array.isArray(held))) return
+  if (held?.[target.key] != null) return
+  out[target.section] = { ...(held || {}), [target.key]: value }
+}
+
+/**
+ * The message a record written in the retired flat form stops the build with — each
+ * misplaced key (`misplacedFields`) moved under the section that declares it.
+ *
+ * @param {string} where - the file, for the message
+ * @param {string|null} ref - the schema's ref, as the query names it
+ * @param {Object} schema - the normalized schema
+ * @param {Array<{ key: string, sections: string[] }>} misplaced
+ * @returns {string}
+ */
+export function flatFormRefusal(where, ref, schema, misplaced) {
+  const under = new Map()
+  const either = []
+  for (const { key, sections } of misplaced) {
+    if (sections.length === 1) {
+      if (!under.has(sections[0])) under.set(sections[0], [])
+      under.get(sections[0]).push(key)
+    } else {
+      either.push(`"${key}" under ${sections.map((n) => `"${n}:"`).join(' or ')}`)
+    }
+  }
+  const moves = [
+    ...[...under].map(([section, keys]) => `${keys.map((k) => `"${k}"`).join(', ')} under "${section}:"`),
+    ...either,
+  ]
+  const names = Object.keys(schema.sections || {}).map((n) => `"${n}"`).join(', ')
+  return (
+    `[uniweb] ${where}: ${ref || schema.name} records are written by section, each section ` +
+    `under its own name (${names}) — move ${moves.join('; ')}.`
+  )
 }
 
 /**
@@ -663,6 +764,125 @@ function warnDuplicateSlugs(items, queryName) {
   }
 }
 
+/**
+ * Read a set of pooled record files, each by its format (markdown → content items,
+ * YAML/JSON → data items, BibTeX → CSL-JSON), delivering each as `config` says. A
+ * record's co-located assets are copied by their path under the records directory
+ * (`recordAssetPath`).
+ *
+ * @returns {Promise<Array>} one result per file — a record, a list of them, or null
+ */
+function readPooledRecords(pooled, config, siteDir, recordsRoot, basePath) {
+  return Promise.all(
+    pooled.map((e) => {
+      const dir = resolve(recordsRoot, ...e.dirs)
+      const file = `${e.slug}${e.ext}`
+      if (e.ext === '.bib') {
+        return processBibtexItem(dir, file, siteDir, config.includeDrafts)
+      }
+      if (e.ext === '.json') {
+        return processJsonItem(dir, file, siteDir, recordsRoot, basePath, config)
+      }
+      if (e.ext === '.yml' || e.ext === '.yaml') {
+        return processDataItem(dir, file, siteDir, recordsRoot, basePath, config)
+      }
+      return processContentItem(dir, file, config, siteDir, basePath, recordsRoot)
+    })
+  )
+}
+
+/**
+ * References, delivered as a host's records service delivers them — measured 2026-09-24
+ * on a local backend: `{ entity, brief }`, the record a reference names reduced to its
+ * brief's fields, `entity` being its id (here, the one its file carries, if any). So a
+ * component reads `talk.speaker.brief.name` on a static site and a hosted one alike.
+ * ⚠️ A host also sends `model`, the Model's id on that backend; nothing a static build
+ * holds corresponds to it, and whether it stays is backend's to say.
+ *
+ * The records a reference names are read here, once per data schema, whether or not a
+ * query selects them — and without their own references delivered, as a host delivers
+ * one level.
+ *
+ * A reference names its record by handle — its file's name, or `slug:` — or by the id
+ * its file carries. One that names no record of its schema is delivered as written, with
+ * a warning; `uniweb validate` reports it too.
+ */
+function referenceHydrator({ poolBySchema, dataSchemas, siteDir, recordsRoot, basePath, includeDrafts }) {
+  const targets = new Map() // schema ref → Map(name or own id → the delivered reference)
+  const warned = new Set()
+
+  const load = async (ref) => {
+    const schema = dataSchemas[ref] || null
+    const pooled = poolBySchema.get(ref) || []
+    const byName = new Map()
+    if (!schema || pooled.length === 0) return byName
+    const config = { schema: ref, dataSchema: schema, includeDrafts, excerpt: { maxLength: 160 }, references: null }
+    const keys = briefKeysOf(schema)
+    for (const result of await readPooledRecords(pooled, config, siteDir, recordsRoot, basePath)) {
+      for (const record of [result].flat()) {
+        if (!record || typeof record !== 'object') continue
+        const delivered = {
+          ...(typeof record.$uuid === 'string' ? { entity: record.$uuid } : {}),
+          brief: pickBrief(record, keys),
+        }
+        if (record.$name !== undefined) byName.set(String(record.$name), delivered)
+        if (typeof record.$uuid === 'string') byName.set(record.$uuid, delivered)
+      }
+    }
+    return byName
+  }
+
+  return {
+    async prepare(refs) {
+      for (const ref of refs || []) {
+        if (!targets.has(ref)) targets.set(ref, await load(ref))
+      }
+    },
+    deliver(schema, record, where) {
+      return mapReferences(
+        schema,
+        record,
+        (value, { path, ref }) => {
+          const hit = typeof value === 'string' ? targets.get(ref)?.get(value) : undefined
+          if (hit) return hit
+          const key = `${where} ${path}`
+          if (typeof value === 'string' && !warned.has(key)) {
+            warned.add(key)
+            console.warn(`[query-processor] ${where}: "${path}" names "${value}", and no record of ${ref} is called that.`)
+          }
+          return value
+        },
+        { delivered: true }
+      )
+    },
+  }
+}
+
+// The keys of a record's brief — the fields of the section a reference hydrates to: the
+// one section of a flat schema, else the brief. Null when there is none (a list at the
+// root), and the whole record stands in for it, as a host answers such a Model.
+function briefKeysOf(schema) {
+  const layout = recordLayout(schema)
+  if (!layout) return null
+  if (schema.fields) return Object.keys(schema.fields)
+  const def = layout.flat ? layout.sections[0][1] : layout.sections.find(([name]) => name === layout.brief)?.[1]
+  return def ? [...Object.keys(def.fields || {}), ...Object.keys(def.sections || {})] : null
+}
+
+// A delivered record's brief: its brief's fields that it has, or — with no brief — every
+// field but the record's own keys.
+function pickBrief(record, keys) {
+  const out = {}
+  if (keys) {
+    for (const key of keys) if (record[key] !== undefined) out[key] = record[key]
+    return out
+  }
+  for (const [key, value] of Object.entries(record)) {
+    if (!key.startsWith('$') && !['slug', 'path', 'excerpt', 'image', 'draft'].includes(key)) out[key] = value
+  }
+  return out
+}
+
 /**
  * Collect and process all of a query's records
  *
@@ -679,28 +899,15 @@ async function collectItems(siteDir, config, recordsRoot, basePath, locale = nul
   const pooled = config.poolEntities || []
   if (pooled.length === 0) return []
 
-  // A record's co-located assets are copied by their path under the records
-  // directory (`recordAssetPath`).
-  const dirOf = (e) => resolve(recordsRoot, ...e.dirs)
+  // The records this query's references name, read before its own — delivering one
+  // is synchronous (`deliverRecord`).
+  if (config.dataSchema && config.references) {
+    await config.references.prepare(collectNestedRefs(config.dataSchema))
+  }
 
   // Process every record file (markdown → content items, YAML/JSON → data items,
   // BibTeX → CSL-JSON bibliography items).
-  let items = await Promise.all(
-    pooled.map((e) => {
-      const dir = dirOf(e)
-      const file = `${e.slug}${e.ext}`
-      if (e.ext === '.bib') {
-        return processBibtexItem(dir, file, siteDir, config.includeDrafts)
-      }
-      if (e.ext === '.json') {
-        return processJsonItem(dir, file, siteDir, recordsRoot, basePath, config.includeDrafts)
-      }
-      if (e.ext === '.yml' || e.ext === '.yaml') {
-        return processDataItem(dir, file, siteDir, recordsRoot, basePath, config.includeDrafts)
-      }
-      return processContentItem(dir, file, config, siteDir, basePath, recordsRoot)
-    })
-  )
+  let items = await readPooledRecords(pooled, config, siteDir, recordsRoot, basePath)
 
   // ⭐ `path` 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
@@ -729,13 +936,15 @@ 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: set here, after every format has been
-  // read and flattened, so 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`). `slug` stays:
-  // foundations and templates read it.
+  // 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.slug !== undefined && item.slug !== null && item.slug !== ''
+    item && typeof item === 'object' && item.$name === undefined &&
+    item.slug !== undefined && item.slug !== null && item.slug !== ''
       ? { ...item, $name: String(item.slug) }
       : item
   ))
@@ -799,6 +1008,8 @@ async function collectItems(siteDir, config, recordsRoot, basePath, locale = nul
  * @param {boolean} [options.includeDrafts=false] - keep `draft: true` records: a preview
  *   (`pnpm dev`) or a check (`uniweb validate`). Off for anything a site DELIVERS — a
  *   draft is a record that is not delivered while the site is published.
+ * @param {Object} [options.dataSchemas] - normalized data schemas by ref, to deliver the
+ *   records in; resolved from the site's foundation when absent (`resolveRecordSchemas`)
  * @returns {Promise<Object>} Map of query name to items array
  *
  * @example
@@ -807,7 +1018,8 @@ async function collectItems(siteDir, config, recordsRoot, basePath, locale = nul
  * })
  * // { articles: [...] }
  */
-export async function processQueries(siteDir, queriesConfig, recordsDir, basePath = '/', { locale = null, includeDrafts = false } = {}) {
+export async function processQueries(siteDir, queriesConfig, recordsDir, basePath = '/', options = {}) {
+  const { locale = null, includeDrafts = false } = options
   if (!queriesConfig || typeof queriesConfig !== 'object') {
     return {}
   }
@@ -842,6 +1054,12 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
   const poolBySchema = groupPoolBySchema(pool.entities)
   const recordsRoot = resolve(siteDir, pool.dir)
 
+  // ⭐ THE DATA SCHEMA EACH QUERY'S RECORDS ARE DELIVERED IN (`deliverRecord`) — resolved
+  // from the foundation's source once for every query. A query with none compiles its
+  // records as their files hold them.
+  const dataSchemas = options.dataSchemas ?? (await querySchemas(siteDir, queriesConfig))
+  const references = referenceHydrator({ poolBySchema, dataSchemas, siteDir, recordsRoot, basePath, includeDrafts })
+
   const results = {}
 
   for (const [name, config] of Object.entries(queriesConfig)) {
@@ -853,6 +1071,8 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
     parsed.poolEntities = parsed.schema ? poolBySchema.get(parsed.schema) || [] : []
     parsed.placements = folder.placements
     parsed.includeDrafts = includeDrafts
+    parsed.dataSchema = (parsed.schema && dataSchemas[parsed.schema]) || null
+    parsed.references = references
     if (parsed.poolEntities.length === 0) {
       const dirs = parsed.schema ? poolDirsForSchema(parsed.schema) : null
       console.warn(
@@ -870,6 +1090,29 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
   return results
 }
 
+/**
+ * The data schemas of the site's record queries, by ref (`resolveRecordSchemas`). A ref
+ * that is not a schema-less query's name and still does not resolve is warned about:
+ * its records are compiled as their files hold them, which is not the shape a
+ * component receives from a host.
+ */
+async function querySchemas(siteDir, queriesConfig) {
+  const refs = []
+  for (const config of Object.values(queriesConfig)) {
+    if (config && typeof config === 'object' && config.url !== undefined) continue
+    const ref = typeof config === 'string' ? config : config?.schema
+    if (typeof ref === 'string') refs.push(ref)
+  }
+  const { schemas, failures } = await resolveRecordSchemas(siteDir, refs)
+  for (const { ref, message } of failures) {
+    console.warn(
+      `[query-processor] Data schema ${ref} did not resolve, so its records are compiled as ` +
+        `their files hold them rather than as a component receives them: ${message}`
+    )
+  }
+  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