@uniweb/build 0.51.0 → 0.52.0

package/src/site/queries-config.js

@@ -32,9 +32,10 @@ import { join } from 'node:path'
 import { existsSync, readFileSync } from 'node:fs'
 import { briefFields, flatRecordFields } from '@uniweb/schemas/conform'
 import { detectFoundationType } from './foundation-ref.js'
-import { refuseQueryRoute } from './data-fetcher.js'
+import { refuseQueryRoute, refuseLimit } from './data-fetcher.js'
 import { readFile } from 'node:fs/promises'
 import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 
 // Read its own YAML rather than importing the site build's helper. That import
 // pointed the wrong way — a config resolver reaching into the collector that
@@ -44,7 +45,7 @@ import yaml from 'js-yaml'
 async function readYamlFile(filePath) {
   if (!existsSync(filePath)) return {}
   try {
-    return yaml.load(await readFile(filePath, 'utf8')) || {}
+    return yaml.load(await readFile(filePath, 'utf8'), YAML_OPTIONS) || {}
   } catch {
     return {}
   }
@@ -203,8 +204,9 @@ const RECORD_KEYS = ['url', 'method', 'body', 'transform']
  * `transform` (a dot-path to its records), `where` / `sort` / `limit` evaluated over
  * them, and `record:` — `{ url, method, body, transform }` — for one record on a
  * parametric page. What describes the site's records — `schema`, `scope`,
- * `deferred`, `excerpt` — is refused beside `url:`. ⛔ `detailUrl:` is
- * retired everywhere: its one real case is `record.url`.
+ * `deferred`, `excerpt` — is refused beside `url:`. ⛔ `detailUrl:` and `detail:` are
+ * retired everywhere: their one real case is `record.url`. ⛔ And `limit:` is a whole
+ * number, 0 or more (`refuseLimit`).
  *
  * ⛔ `route:` is retired everywhere too (2026-09-14 [Diego]): a record links to the page
  * whose route query is its query, as `$route`, which the runtime fills at render time
@@ -222,7 +224,16 @@ export function refuseQueryDeclaration(decl) {
         `on an external query — one with \`url:\`.`
     )
   }
+  // ⛔ `detail:` too — retired on a fetch 2026-09-13, and accepted here in silence until
+  // 2026-09-14, carried into `config.queries` where nothing read it.
+  if (decl.detail !== undefined) {
+    throw new Error(
+      `[uniweb] ${where}: \`detail:\` is retired. An API's single-record request is \`record: { url: … }\` ` +
+        `on an external query — one with \`url:\`.`
+    )
+  }
   refuseQueryRoute(decl, where)
+  refuseLimit(decl.limit, where)
   const external = decl.url !== undefined
   if (!external) {
     for (const key of ['method', 'body', 'transform', 'record']) {

package/src/site/query-processor.js

@@ -52,12 +52,14 @@
  */
 
 import { readFile, readdir, stat, writeFile, mkdir, copyFile, rm } from 'node:fs/promises'
-import { join, basename, extname, dirname, relative, resolve, sep } from 'node:path'
+import { join, basename, extname, dirname, relative, resolve, sep, isAbsolute } from 'node:path'
 import { existsSync } from 'node:fs'
+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 { applyWhere, applySort, refuseUnder, refuseOutsideLanguage, refuseQueryRoute } from './data-fetcher.js'
+import { applyWhere, applySort, refuseUnder, refuseOutsideLanguage, refuseQueryRoute, refuseLimit } from './data-fetcher.js'
 import { resolveAssetPath, walkContentAssets, isLocalAssetPath } from './assets.js'
 import { readEntityPool, groupPoolBySchema, ENTITIES_DIR } from './entity-pool.js'
 import { readRecordsConfig, resolveFolder, FOLDER_MISSING } from './records-config.js'
@@ -126,6 +128,7 @@ function parseQueryConfig(name, config) {
   refuseUnder(config.where, `queries.${name}`)
   refuseOutsideLanguage(config.where, `queries.${name}`)
   refuseQueryRoute(config, `queries.${name}`)
+  refuseLimit(config.limit, `queries.${name}`)
   return {
     name,
     // The query's schema selects its records from the pool — `entities/{schema}/`
@@ -254,29 +257,71 @@ function isExternalUrl(src) {
   return /^(https?:)?\/\//.test(src) || src.startsWith('data:')
 }
 
+/**
+ * Where a record's co-located asset is published — its path below `public/records/`.
+ *
+ * ⭐ THE RECORD'S OWN HOME, keyed by where the file sits in the pool. It was
+ * `public/collections/<queryName>/`, which meant the SAME image was copied once per
+ * query that returned the record, under two URLs. Third instance of the same
+ * conflation (after the freeform locale tree and the translation manifest): an asset
+ * belongs to a record, and which query selects it is not a fact about it.
+ *
+ * ⭐ ITS PATH UNDER THE ENTITIES ROOT, whole. ⛔ Until 2026-09-14 it was the record's
+ * schema folder plus the asset's BASENAME, so `./a/pic.png` and `./b/pic.png` under
+ * one schema folder were copied to one file — the last one won — and a record showed
+ * another record's picture. Now a file beside its record keeps the URL it always had
+ * (`article/pic.png`), a file in a subfolder keeps its subfolder (`article/img/pic.png`),
+ * and one elsewhere under the root keeps its own path (`../shared/logo.svg` from
+ * `entities/article/` → `shared/logo.svg`).
+ *
+ * A file OUTSIDE the entities root has no such path, so it is named for where it is:
+ * `_external/<hash>-<name>`, the hash being the first 8 hex digits of the sha-256 of
+ * its path relative to the entities root — the same on every machine with the same
+ * layout, and different for two files that share a name.
+ *
+ * @param {string} resolved - the asset's absolute path
+ * @param {string} entitiesRoot - the site's entities root, absolute
+ * @returns {string} a `/`-separated path below `records/`
+ */
+function recordAssetPath(resolved, entitiesRoot) {
+  const rel = relative(entitiesRoot, resolved)
+  const posix = rel.split(sep).join('/')
+  const inside = rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel)
+  if (inside) return posix
+  const hash = createHash('sha256').update(posix).digest('hex').slice(0, 8)
+  return `_external/${hash}-${basename(resolved)}`
+}
+
+/**
+ * Copy one of a record's assets to its home under `public/records/` (`recordAssetPath`).
+ *
+ * @returns {Promise<{ url: string, copied: string }>} its URL under `basePath`, and the copy
+ */
+async function publishRecordAsset(resolved, siteRoot, entitiesRoot, basePath) {
+  const path = recordAssetPath(resolved, entitiesRoot)
+  const copied = join(siteRoot, 'public', 'records', ...path.split('/'))
+  await mkdir(dirname(copied), { recursive: true })
+  await copyFile(resolved, copied)
+  return { url: `${basePath}records/${path}`, copied }
+}
+
 /**
  * Process assets in collection content
  * - Resolves relative paths to site-root-relative paths
- * - Copies co-located assets to public/records/<schema>/
+ * - Copies co-located assets to public/records/, by their path under the entities
+ *   root (`recordAssetPath`)
  * - Updates paths in the content in place
  *
  * @param {Object} content - ProseMirror document
  * @param {string} itemPath - Path to the markdown file
  * @param {string} siteRoot - Site root directory
- * @param {string} queryName - Name of the collection (e.g., 'articles')
+ * @param {string} entitiesRoot - The site's entities root, absolute
+ * @param {string} basePath - Site base path (e.g., '/' or '/docs/')
  * @returns {Promise<Object>} Asset manifest for this item
  */
-async function processRecordAssets(content, itemPath, siteRoot, poolDirs, basePath) {
+async function processRecordAssets(content, itemPath, siteRoot, entitiesRoot, basePath) {
   const assets = {}
-  const itemDir = dirname(itemPath)
   const publicDir = join(siteRoot, 'public')
-  // ⭐ THE RECORD'S OWN HOME, keyed by its pool position — `public/records/<schema
-  // dirs>/`. It was `public/collections/<queryName>/`, which meant the SAME image
-  // was copied once per query that returned the record, under two URLs. Third
-  // instance of the same conflation (after the freeform locale tree and the
-  // translation manifest): an asset belongs to a record, and which query selects
-  // it is not a fact about it.
-  const targetDir = join(publicDir, 'records', poolDirs)
 
   // Walk content and collect asset paths
   const assetNodes = []
@@ -298,23 +343,14 @@ async function processRecordAssets(content, itemPath, siteRoot, poolDirs, basePa
     if (src.startsWith('./') || src.startsWith('../')) {
       // Check if file exists at resolved location
       if (existsSync(result.resolved)) {
-        // Copy to public/collections/<collection>/
-        const assetFilename = basename(result.resolved)
-        const targetPath = join(targetDir, assetFilename)
-
-        // Ensure target directory exists
-        await mkdir(targetDir, { recursive: true })
-
-        // Copy the asset
-        await copyFile(result.resolved, targetPath)
-
-        // Update path to site-root-relative
-        finalPath = `${basePath}records/${poolDirs}/${assetFilename}`
+        // Copy to public/records/, and point the content at the copy
+        const { url, copied } = await publishRecordAsset(result.resolved, siteRoot, entitiesRoot, basePath)
+        finalPath = url
 
         assets[src] = {
           original: src,
           resolved: result.resolved,
-          copied: targetPath,
+          copied,
           publicPath: finalPath
         }
       }
@@ -340,22 +376,14 @@ async function processRecordAssets(content, itemPath, siteRoot, poolDirs, basePa
     if (node.attrs.poster && !isExternalUrl(node.attrs.poster)) {
       const posterResult = resolveAssetPath(node.attrs.poster, itemPath, siteRoot)
       if (posterResult.resolved && existsSync(posterResult.resolved)) {
-        const posterFilename = basename(posterResult.resolved)
-        const posterTarget = join(targetDir, posterFilename)
-        await mkdir(targetDir, { recursive: true })
-        await copyFile(posterResult.resolved, posterTarget)
-        node.attrs.poster = `${basePath}records/${poolDirs}/${posterFilename}`
+        node.attrs.poster = (await publishRecordAsset(posterResult.resolved, siteRoot, entitiesRoot, basePath)).url
       }
     }
 
     if (node.attrs.preview && !isExternalUrl(node.attrs.preview)) {
       const previewResult = resolveAssetPath(node.attrs.preview, itemPath, siteRoot)
       if (previewResult.resolved && existsSync(previewResult.resolved)) {
-        const previewFilename = basename(previewResult.resolved)
-        const previewTarget = join(targetDir, previewFilename)
-        await mkdir(targetDir, { recursive: true })
-        await copyFile(previewResult.resolved, previewTarget)
-        node.attrs.preview = `${basePath}records/${poolDirs}/${previewFilename}`
+        node.attrs.preview = (await publishRecordAsset(previewResult.resolved, siteRoot, entitiesRoot, basePath)).url
       }
     }
   }
@@ -364,30 +392,27 @@ async function processRecordAssets(content, itemPath, siteRoot, poolDirs, basePa
 }
 
 /**
- * Process assets in a data item (YAML/JSON)
+ * Process assets in a record's data — a YAML/JSON record, or a markdown record's
+ * frontmatter
  * - Recursively walks the data object looking for local asset paths
- * - Copies co-located assets to public/records/<schema>/
+ * - Copies co-located assets to public/records/, by their path under the entities
+ *   root (`recordAssetPath`)
  * - Rewrites paths to absolute URLs (with base path)
  *
  * @param {Object} data - Parsed data object (mutated in place)
- * @param {string} itemPath - Path to the data file
+ * @param {string} itemPath - Path to the record's file
  * @param {string} siteRoot - Site root directory
- * @param {string} queryName - Name of the collection
+ * @param {string} entitiesRoot - The site's entities root, absolute
  * @param {string} basePath - Site base path (e.g., '/' or '/docs/')
  */
-async function processDataItemAssets(data, itemPath, siteRoot, poolDirs, basePath) {
-  const targetDir = join(siteRoot, 'public', 'records', poolDirs)
-
+async function processDataItemAssets(data, itemPath, siteRoot, entitiesRoot, basePath) {
   async function walk(parent, key) {
     const val = parent[key]
     if (typeof val === 'string' && isLocalAssetPath(val)) {
       if (val.startsWith('./') || val.startsWith('../')) {
         const resolved = resolve(dirname(itemPath), val)
         if (existsSync(resolved)) {
-          const filename = basename(resolved)
-          await mkdir(targetDir, { recursive: true })
-          await copyFile(resolved, join(targetDir, filename))
-          parent[key] = `${basePath}records/${poolDirs}/${filename}`
+          parent[key] = (await publishRecordAsset(resolved, siteRoot, entitiesRoot, basePath)).url
         }
       } else if (val.startsWith('/')) {
         // Absolute site path — just prepend base
@@ -427,16 +452,16 @@ async function processDataItemAssets(data, itemPath, siteRoot, poolDirs, basePat
  * @param {string} filename - YAML filename (.yml or .yaml)
  * @returns {Promise<Object|Array|null>} Processed item(s) or null if unpublished
  */
-async function processDataItem(dir, filename, siteRoot, poolDirs, basePath) {
+async function processDataItem(dir, filename, siteRoot, entitiesRoot, basePath) {
   const filepath = join(dir, filename)
   const raw = await readFile(filepath, 'utf-8')
-  const data = yaml.load(raw) || {}
+  const data = yaml.load(raw, YAML_OPTIONS) || {}
 
   // Array → multiple items (single-file collection)
   if (Array.isArray(data)) {
     for (const item of data) {
       if (item && typeof item === 'object') {
-        await processDataItemAssets(item, filepath, siteRoot, poolDirs, basePath)
+        await processDataItemAssets(item, filepath, siteRoot, entitiesRoot, basePath)
       }
     }
     return data
@@ -446,7 +471,7 @@ async function processDataItem(dir, filename, siteRoot, poolDirs, basePath) {
   if (data.published === false) return null
   const slug = basename(filename, extname(filename))
   const item = { slug, ...data }
-  await processDataItemAssets(item, filepath, siteRoot, poolDirs, basePath)
+  await processDataItemAssets(item, filepath, siteRoot, entitiesRoot, basePath)
   return item
 }
 
@@ -461,7 +486,7 @@ async function processDataItem(dir, filename, siteRoot, poolDirs, basePath) {
  * @param {string} filename - JSON filename
  * @returns {Promise<Object|Array|null>} Processed item(s) or null if unpublished
  */
-async function processJsonItem(dir, filename, siteRoot, poolDirs, basePath) {
+async function processJsonItem(dir, filename, siteRoot, entitiesRoot, basePath) {
   const filepath = join(dir, filename)
   const raw = await readFile(filepath, 'utf-8')
   const slug = basename(filename, '.json')
@@ -471,7 +496,7 @@ async function processJsonItem(dir, filename, siteRoot, poolDirs, basePath) {
   if (Array.isArray(data)) {
     for (const item of data) {
       if (item && typeof item === 'object') {
-        await processDataItemAssets(item, filepath, siteRoot, poolDirs, basePath)
+        await processDataItemAssets(item, filepath, siteRoot, entitiesRoot, basePath)
       }
     }
     return data
@@ -480,7 +505,7 @@ async function processJsonItem(dir, filename, siteRoot, poolDirs, basePath) {
   // Object → single item
   if (data.published === false) return null
   const item = { slug, ...data }
-  await processDataItemAssets(item, filepath, siteRoot, poolDirs, basePath)
+  await processDataItemAssets(item, filepath, siteRoot, entitiesRoot, basePath)
   return item
 }
 
@@ -514,9 +539,11 @@ async function processBibtexItem(dir, filename) {
  * @param {string} filename - Markdown filename
  * @param {Object} config - Collection configuration
  * @param {string} siteRoot - Site root directory for asset resolution
+ * @param {string} basePath - Site base path (e.g., '/' or '/docs/')
+ * @param {string} entitiesRoot - The site's entities root, absolute
  * @returns {Promise<Object|null>} Processed item or null if unpublished
  */
-async function processContentItem(dir, filename, config, siteRoot, basePath, poolDirs) {
+async function processContentItem(dir, filename, config, siteRoot, basePath, entitiesRoot) {
   const filepath = join(dir, filename)
   const raw = await readFile(filepath, 'utf-8')
   const slug = basename(filename, extname(filename))
@@ -529,18 +556,25 @@ async function processContentItem(dir, filename, config, siteRoot, basePath, poo
     return null
   }
 
+  // ⭐ THE FRONTMATTER IS THE RECORD'S DATA, so a co-located path in it is published
+  // exactly as a YAML or JSON record's field is. ⛔ Until 2026-09-14 it was neither
+  // copied nor rewritten: `image: ./cover.jpg` reached the compiled record as written,
+  // a path relative to a file no visitor can reach, while the same line in a `.yml`
+  // record was published.
+  await processDataItemAssets(frontmatter, filepath, siteRoot, entitiesRoot, basePath)
+
   // Parse markdown body to ProseMirror
   const content = markdownToProseMirror(body)
 
   // Process assets (resolve paths, copy co-located files)
   // This modifies content in place, updating paths to site-root-relative
-  await processRecordAssets(content, filepath, siteRoot, poolDirs, basePath)
+  await processRecordAssets(content, filepath, siteRoot, entitiesRoot, basePath)
 
   // Extract excerpt
   const excerpt = extractExcerpt(frontmatter, content, config.excerpt)
 
   // Extract first image (frontmatter takes precedence)
-  // Note: paths in content have already been updated by processRecordAssets
+  // Note: paths in the frontmatter and the content have already been rewritten above
   const image = frontmatter.image || extractFirstImage(content)
 
   return {
@@ -624,7 +658,10 @@ async function collectItems(siteDir, config, entitiesDir, basePath, locale = nul
   const pooled = config.poolEntities || []
   if (pooled.length === 0) return []
 
-  const dirOf = (e) => resolve(siteDir, entitiesDir || ENTITIES_DIR, ...e.dirs)
+  // A record's co-located assets are published by their path under this root
+  // (`recordAssetPath`).
+  const entitiesRoot = resolve(siteDir, entitiesDir || ENTITIES_DIR)
+  const dirOf = (e) => resolve(entitiesRoot, ...e.dirs)
 
   // Process all entity files (markdown → content items, YAML/JSON → data items,
   // BibTeX → CSL-JSON bibliography items).
@@ -636,12 +673,12 @@ async function collectItems(siteDir, config, entitiesDir, basePath, locale = nul
         return processBibtexItem(dir, file)
       }
       if (e.ext === '.json') {
-        return processJsonItem(dir, file, siteDir, e.dirs.join('/'), basePath)
+        return processJsonItem(dir, file, siteDir, entitiesRoot, basePath)
       }
       if (e.ext === '.yml' || e.ext === '.yaml') {
-        return processDataItem(dir, file, siteDir, e.dirs.join('/'), basePath)
+        return processDataItem(dir, file, siteDir, entitiesRoot, basePath)
       }
-      return processContentItem(dir, file, config, siteDir, basePath, e.dirs.join('/'))
+      return processContentItem(dir, file, config, siteDir, basePath, entitiesRoot)
     })
   )
 
@@ -769,8 +806,19 @@ export async function processQueries(siteDir, queriesConfig, entitiesDir, basePa
   // with no `records.yml` is simply not managing publication, and its whole pool
   // is delivered. (Making missing mean "publish nothing" would turn every site
   // without the file into a silently empty one.)
+  //
+  // ⛔ AND A MALFORMED FILE IS NOT A MISSING ONE. It read as `missing` here until
+  // 2026-09-14 — invalid YAML, or a mapping where the list goes — so the whole pool was
+  // delivered, drafts included, with one warning, while the sync lane refused the same
+  // file (`uwx/records.js`). An author who wrote `records.yml` is managing publication;
+  // what it says cannot be guessed, so the build stops.
   const recordsCfg = await readRecordsConfig(siteDir)
-  if (recordsCfg.error) console.warn(`[query-processor] ${recordsCfg.error}`)
+  if (recordsCfg.error) {
+    throw new Error(
+      `[uniweb] ${recordsCfg.error}\n` +
+        `  records.yml decides which entities are records, so nothing in entities/ is published until it is fixed.`
+    )
+  }
   const managed = recordsCfg.state !== FOLDER_MISSING
   const folder = managed ? resolveFolder(recordsCfg.entries, pool.entities) : null
   if (folder) {

package/src/site/records-config.js

@@ -48,6 +48,7 @@ import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { compareByNumericPrefix } from '../utils/numeric-prefix.js'
 
 export const RECORDS_YML_RELPATH = 'records.yml'
@@ -114,7 +115,7 @@ export async function readRecordsConfig(siteRoot) {
 
   let doc
   try {
-    doc = yaml.load(await readFile(file, 'utf8'))
+    doc = yaml.load(await readFile(file, 'utf8'), YAML_OPTIONS)
   } catch (err) {
     return { state: FOLDER_MISSING, entries: [], error: `${RECORDS_YML_RELPATH}: ${err.message}` }
   }
@@ -127,7 +128,7 @@ export async function readRecordsConfig(siteRoot) {
       state: FOLDER_MISSING,
       entries: [],
       error:
-        `${RECORDS_YML_RELPATH} must be a LIST of what is in the folder, not a mapping. ` +
+        `${RECORDS_YML_RELPATH} must be a LIST of what is in the folder, not ${typeof doc === 'object' ? 'a mapping' : 'a single value'}. ` +
         `The common case is three lines:\n  - person/*.md\n  - publication/*.md`,
     }
   }

package/src/utils/frontmatter.js

@@ -39,6 +39,7 @@
  */
 
 import yaml from 'js-yaml'
+import { YAML_OPTIONS } from './yaml-schema.js'
 
 /**
  * Split YAML frontmatter from a markdown body.
@@ -65,7 +66,7 @@ export function parseFrontmatter(raw, filepath) {
   }
 
   try {
-    const frontmatter = yaml.load(parts[1]) || {}
+    const frontmatter = yaml.load(parts[1], YAML_OPTIONS) || {}
     const body = parts.slice(2).join('---\n')
     return { frontmatter, body }
   } catch (err) {

package/src/utils/yaml-schema.js

@@ -0,0 +1,44 @@
+/**
+ * How the build reads YAML — ONE set of types, passed to every `yaml.load`.
+ *
+ * ⛔ AN UNQUOTED DATE IS THE STRING THE AUTHOR WROTE. js-yaml's default schema resolves
+ * `date: 2025-06-01` (and `2025-06-01T10:20:30Z`) to a JS `Date`, so the same value
+ * reached the build as a string when quoted and as a Date when not. A Date is neither a
+ * string nor a number to `@uniweb/core`'s query evaluator, so, measured before this
+ * schema existed:
+ *
+ *   - a query's fixed `where: { date: { gte: '2025-01-01' } }` compiled to no records,
+ *     with no warning;
+ *   - `sort: date desc` left the compiled file in filename order;
+ *   - the compiled JSON said `2025-06-01T00:00:00.000Z` where the author wrote
+ *     `2025-06-01`.
+ *
+ * ⭐ So this is js-yaml's default schema minus its IMPLICIT timestamp type: numbers,
+ * booleans, null and `<<` merge keys resolve exactly as before, and a date or timestamp
+ * stays the text it was written as. An explicit `!!timestamp` tag is accepted and yields
+ * that text too, so no reader of site content ever receives a Date.
+ *
+ * ⚠️ READING ONLY. The writers that dump YAML (`uwx/project-writer.js`, `uwx/backfill.js`)
+ * keep js-yaml's default, which QUOTES a string that looks like a date or a number — so
+ * a written file reads back as the same string in any YAML reader, not only this one.
+ *
+ * @module @uniweb/build/utils/yaml-schema
+ */
+
+import yaml from 'js-yaml'
+
+/** `!!timestamp`, explicit only, constructed as the text it was written as. */
+const timestampAsWritten = new yaml.Type('tag:yaml.org,2002:timestamp', {
+  kind: 'scalar',
+  resolve: (data) => yaml.types.timestamp.resolve(data),
+  construct: (data) => data,
+})
+
+/** The build's YAML types: the default schema's, with no implicit timestamp. */
+export const YAML_SCHEMA = yaml.CORE_SCHEMA.extend({
+  implicit: [yaml.types.merge],
+  explicit: [timestampAsWritten, yaml.types.binary, yaml.types.omap, yaml.types.pairs, yaml.types.set],
+})
+
+/** `yaml.load(text, YAML_OPTIONS)` — the options every reader passes. */
+export const YAML_OPTIONS = Object.freeze({ schema: YAML_SCHEMA })

package/src/uwx/backfill.js

@@ -21,6 +21,7 @@
 import { readFileSync, writeFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { proseMirrorToMarkdown } from '@uniweb/content-writer'
 import { parseFrontmatter } from './entity-source.js'
 import { isProseMirrorField, isContentBodyField } from './data-schema.js'
@@ -85,7 +86,7 @@ export function backfillUuid(filePath, uuid) {
   } else if (ext === '.yml' || ext === '.yaml') {
     let obj
     try {
-      obj = yaml.load(text)
+      obj = yaml.load(text, YAML_OPTIONS)
     } catch (err) {
       return { status: 'error', message: `invalid YAML in ${filePath}: ${err.message}` }
     }
@@ -127,7 +128,7 @@ export function backfillArrayFile(filePath, uuidBySlug) {
   }
   let arr
   try {
-    arr = ext === '.json' ? JSON.parse(text) : yaml.load(text)
+    arr = ext === '.json' ? JSON.parse(text) : yaml.load(text, YAML_OPTIONS)
   } catch (err) {
     return { status: 'error', message: `invalid ${ext || '(no extension)'} in ${filePath}: ${err.message}` }
   }

package/src/uwx/entity-source.js

@@ -23,6 +23,7 @@
 import { readFile } from 'node:fs/promises'
 import { basename, extname } from 'node:path'
 import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { parseBibtex } from '@citestyle/bibtex'
 
 const SOURCE_EXTENSIONS = new Set(['.md', '.yml', '.yaml', '.json', '.bib'])
@@ -89,7 +90,7 @@ async function readOneFile(filepath) {
   }
 
   // yaml / json
-  const data = format === 'json' ? JSON.parse(raw) : yaml.load(raw)
+  const data = format === 'json' ? JSON.parse(raw) : yaml.load(raw, YAML_OPTIONS)
   if (Array.isArray(data)) {
     // Many records in one file — each carries its own slug. Write-back deferred.
     return data

package/src/uwx/project-writer.js

@@ -14,6 +14,7 @@ import { readFileSync, writeFileSync, renameSync, readdirSync, existsSync, mkdir
 import { join, resolve, dirname } from 'node:path'
 import { randomBytes } from 'node:crypto'
 import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { proseMirrorToMarkdown, serializeFrontmatter } from '@uniweb/content-writer'
 import { parseFrontmatter } from './entity-source.js'
 import { renderEntityDocument } from './backfill.js'
@@ -203,7 +204,7 @@ export function writeSectionFile({ filePath, content, params, reserved = DEFAULT
 function mergeYamlConfig(filePath, changes, { replace = [] } = {}) {
   let existing = {}
   try {
-    existing = yaml.load(readFileSync(filePath, 'utf8')) || {}
+    existing = yaml.load(readFileSync(filePath, 'utf8'), YAML_OPTIONS) || {}
   } catch {
     // missing / invalid → start fresh
   }
@@ -263,7 +264,7 @@ export function writeYamlFile(filePath, obj) {
 export function writeMergedYaml(filePath, projected, managedKeys) {
   let existing = {}
   try {
-    existing = yaml.load(readFileSync(filePath, 'utf8')) || {}
+    existing = yaml.load(readFileSync(filePath, 'utf8'), YAML_OPTIONS) || {}
   } catch {
     // missing / invalid → start fresh
   }

package/src/uwx/records-project.js

@@ -35,6 +35,7 @@
 import { readFileSync, readdirSync, existsSync } from 'node:fs'
 import { join, resolve, relative, extname, basename, sep } from 'node:path'
 import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { parseFrontmatter } from './entity-source.js'
 import { writeRecordFile, writeQueriesConfig, writeRecordsConfig } from './project-writer.js'
 import { defaultSchema, deferredFromSchema, foundationDataSchemas } from './queries-config.js'
@@ -66,7 +67,7 @@ function readFileUuid(filePath, format) {
   }
   try {
     if (format === 'md') return parseFrontmatter(raw, filePath).frontmatter?.$uuid ?? null
-    const parsed = format === 'json' ? JSON.parse(raw) : yaml.load(raw)
+    const parsed = format === 'json' ? JSON.parse(raw) : yaml.load(raw, YAML_OPTIONS)
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
     return parsed.$uuid ?? null
   } catch {
@@ -176,7 +177,7 @@ function locate(document, folderIndex) {
 /** `site.yml::$org`, bare (`acme`), or null. Stored bare — see `writeSiteOrg`. */
 function readSiteOrg(siteRoot) {
   try {
-    const y = yaml.load(readFileSync(join(siteRoot, 'site.yml'), 'utf8')) || {}
+    const y = yaml.load(readFileSync(join(siteRoot, 'site.yml'), 'utf8'), YAML_OPTIONS) || {}
     return typeof y.$org === 'string' && y.$org ? y.$org : null
   } catch {
     return null
@@ -207,6 +208,10 @@ function setIf(obj, key, value) {
 // resolves as `items` — a round trip that silently relocates a query's pool.
 // Wire keys `declToFileShape` consumes explicitly — mapped, renamed, or folded into
 // the file-side `path`/`url`. `$id`/`$uuid`/`name` are identity, not content.
+// ⛔ `detail_url` and `detail` are consumed and never written back: both are retired on a
+// query and the build refuses them, so a pull that restored a stored one would hand the
+// author a file that does not build. (`detail:` was pushed as an unmodelled field until
+// 2026-09-14, so a store can hold it.)
 const DECL_WIRE_CONSUMED = new Set([
   'name',
   '$id',
@@ -219,6 +224,7 @@ const DECL_WIRE_CONSUMED = new Set([
   'excerpt',
   'deferred',
   'detail_url',
+  'detail',
   'queryable'
 ])
 
@@ -342,7 +348,7 @@ export function declarationsToQueriesYml({ document, siteRoot, org }) {
   // where dropping an AUTHORED one would.
   let siteYml = null
   try {
-    siteYml = yaml.load(readFileSync(join(siteRoot, 'site.yml'), 'utf8')) || null
+    siteYml = yaml.load(readFileSync(join(siteRoot, 'site.yml'), 'utf8'), YAML_OPTIONS) || null
   } catch {
     siteYml = null
   }

package/src/uwx/records.js

@@ -41,6 +41,7 @@
 
 import { readFileSync, existsSync } from 'node:fs'
 import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { detectFoundationType } from '../site/foundation-ref.js'
 import { join, resolve } from 'node:path'
 
@@ -167,9 +168,11 @@ function encodeFieldValue(value, field, sourceLocale, translations) {
       ? localize(value, sourceLocale)
       : localizeScalar(value, sourceLocale, translations)
   }
-  // A YAML scalar date parses to a Date. The backend validates `date` as
-  // `YYYY-MM-DD` and `datetime` as RFC3339 — emitting full ISO for a `date`
-  // field is rejected before storage, so split by kind.
+  // A Date handed in by a caller. The backend validates `date` as `YYYY-MM-DD` and
+  // `datetime` as RFC3339 — emitting full ISO for a `date` field is rejected before
+  // storage, so split by kind. ⚠️ A record READ from a file never carries one: the
+  // build's YAML resolves no timestamps (`utils/yaml-schema.js`), so an unquoted
+  // `2026-03-01` is the string as written, the same value a quoted one always was.
   if (DATE_KINDS.has(field.type) && value instanceof Date) {
     return field.type === 'date' ? value.toISOString().slice(0, 10) : value.toISOString()
   }
@@ -429,7 +432,7 @@ function syncableQueries(declarations) {
 function resolveFoundationDir(siteRoot, opts) {
   if (opts.foundationDir) return resolve(opts.foundationDir)
   try {
-    const siteYml = yaml.load(readFileSync(join(siteRoot, 'site.yml'), 'utf8')) || {}
+    const siteYml = yaml.load(readFileSync(join(siteRoot, 'site.yml'), 'utf8'), YAML_OPTIONS) || {}
     if (!siteYml.foundation) return null
     const info = detectFoundationType(siteYml.foundation, siteRoot)
     return info?.type === 'local' && info.path ? info.path : null

package/src/uwx/site-project.js

@@ -38,6 +38,7 @@ import { readFileSync, existsSync, unlinkSync, renameSync, rmSync, readdirSync,
 import { isMarkdownFile, isIgnoredFolder } from '../utils/content-files.js'
 import { createHash } from 'node:crypto'
 import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { writeSiteConfig, writeThemeFile, writeIfChanged, writeSectionFile, writeMergedYaml } from './project-writer.js'
 import { declarationsToQueriesYml } from './records-project.js'
 import { authorableDeclaration, DECLARATION_KEYS } from '../site/fetch-shapes.js'
@@ -203,7 +204,7 @@ const SETTINGS_TO_SITE_YML = {
 /** An authored YAML config as it stands, or null when there is none to read. */
 function readAuthoredYaml(filePath) {
   try {
-    const value = yaml.load(readFileSync(filePath, 'utf8'))
+    const value = yaml.load(readFileSync(filePath, 'utf8'), YAML_OPTIONS)
     return value && typeof value === 'object' && !Array.isArray(value) ? value : null
   } catch {
     return null