@uniweb/build 0.56.0 → 0.58.0

package/src/site/query-processor.js

@@ -61,8 +61,9 @@ import { parseBibtex } from '@citestyle/bibtex'
 import { DATA_DIR, withoutRouteVariables } from '@uniweb/core'
 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'
+import { readEntityPool, groupPoolBySchema, poolDirsForSchema } from './entity-pool.js'
+import { readRecordsConfig, resolveFolder } from './records-config.js'
+import { isDraftRecord } from './record-draft.js'
 import { parseFrontmatter } from '../utils/frontmatter.js'
 
 // Try to import content-reader for markdown parsing
@@ -98,7 +99,7 @@ try {
  * parseQueryConfig('articles', {
  *   schema: '@/article',
  *   sort: 'date desc',
- *   filter: 'published != false',
+ *   where: { featured: true },
  *   limit: 100
  * })
  */
@@ -109,7 +110,7 @@ function parseQueryConfig(name, config) {
   // shows) would have crashed on the shortest thing an author can write.
   if (config === null || config === undefined) config = {}
   if (typeof config === 'string') {
-    // The string shorthand names the SCHEMA — `entities/{schema}/` supplies the
+    // The string shorthand names the SCHEMA — `records/{schema}/` supplies the
     // records, so there is no directory for a query to name.
     return {
       name,
@@ -131,11 +132,11 @@ function parseQueryConfig(name, config) {
   refuseLimit(config.limit, `queries.${name}`)
   return {
     name,
-    // The query's schema selects its records from the pool — `entities/{schema}/`
-    // declares the model, so the entities of a schema ARE the query's records.
+    // The query's schema selects its records — `records/{schema}/` declares the
+    // model, so the site's records of a schema are the query's records.
     schema: config.schema || null,
     url: config.url || null,
-    // The folder branch the query reads (`records.yml` placement). ⛔ Not read
+    // The folder branch the query reads (`folder.yml` placement). ⛔ Not read
     // here until 2026-09-11: a named query's `scope` was ignored on this lane.
     scope: typeof config.scope === 'string' ? config.scope : null,
     sort: config.sort || null,
@@ -266,25 +267,25 @@ function isExternalUrl(src) {
  * 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
+ * ⭐ ITS PATH UNDER THE RECORDS 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`).
+ * `records/article/` → `shared/logo.svg`).
  *
- * A file OUTSIDE the entities root has no such path, so it is named for where it is:
+ * A file OUTSIDE the records 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
+ * its path relative to the records 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
+ * @param {string} recordsRoot - the site's records root, absolute
  * @returns {string} a `/`-separated path below `records/`
  */
-function recordAssetPath(resolved, entitiesRoot) {
-  const rel = relative(entitiesRoot, resolved)
+function recordAssetPath(resolved, recordsRoot) {
+  const rel = relative(recordsRoot, resolved)
   const posix = rel.split(sep).join('/')
   const inside = rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel)
   if (inside) return posix
@@ -297,8 +298,8 @@ function recordAssetPath(resolved, entitiesRoot) {
  *
  * @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)
+async function publishRecordAsset(resolved, siteRoot, recordsRoot, basePath) {
+  const path = recordAssetPath(resolved, recordsRoot)
   const copied = join(siteRoot, 'public', 'records', ...path.split('/'))
   await mkdir(dirname(copied), { recursive: true })
   await copyFile(resolved, copied)
@@ -308,18 +309,18 @@ async function publishRecordAsset(resolved, siteRoot, entitiesRoot, basePath) {
 /**
  * Process assets in collection content
  * - Resolves relative paths to site-root-relative paths
- * - Copies co-located assets to public/records/, by their path under the entities
+ * - Copies co-located assets to public/records/, by their path under the records
  *   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} entitiesRoot - The site's entities root, absolute
+ * @param {string} recordsRoot - The site's records directory, 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, entitiesRoot, basePath) {
+async function processRecordAssets(content, itemPath, siteRoot, recordsRoot, basePath) {
   const assets = {}
   const publicDir = join(siteRoot, 'public')
 
@@ -344,7 +345,7 @@ async function processRecordAssets(content, itemPath, siteRoot, entitiesRoot, ba
       // Check if file exists at resolved location
       if (existsSync(result.resolved)) {
         // Copy to public/records/, and point the content at the copy
-        const { url, copied } = await publishRecordAsset(result.resolved, siteRoot, entitiesRoot, basePath)
+        const { url, copied } = await publishRecordAsset(result.resolved, siteRoot, recordsRoot, basePath)
         finalPath = url
 
         assets[src] = {
@@ -376,14 +377,14 @@ async function processRecordAssets(content, itemPath, siteRoot, entitiesRoot, ba
     if (node.attrs.poster && !isExternalUrl(node.attrs.poster)) {
       const posterResult = resolveAssetPath(node.attrs.poster, itemPath, siteRoot)
       if (posterResult.resolved && existsSync(posterResult.resolved)) {
-        node.attrs.poster = (await publishRecordAsset(posterResult.resolved, siteRoot, entitiesRoot, basePath)).url
+        node.attrs.poster = (await publishRecordAsset(posterResult.resolved, siteRoot, recordsRoot, basePath)).url
       }
     }
 
     if (node.attrs.preview && !isExternalUrl(node.attrs.preview)) {
       const previewResult = resolveAssetPath(node.attrs.preview, itemPath, siteRoot)
       if (previewResult.resolved && existsSync(previewResult.resolved)) {
-        node.attrs.preview = (await publishRecordAsset(previewResult.resolved, siteRoot, entitiesRoot, basePath)).url
+        node.attrs.preview = (await publishRecordAsset(previewResult.resolved, siteRoot, recordsRoot, basePath)).url
       }
     }
   }
@@ -395,24 +396,24 @@ async function processRecordAssets(content, itemPath, siteRoot, entitiesRoot, ba
  * 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/, by their path under the entities
+ * - Copies co-located assets to public/records/, by their path under the records
  *   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 record's file
  * @param {string} siteRoot - Site root directory
- * @param {string} entitiesRoot - The site's entities root, absolute
+ * @param {string} recordsRoot - The site's records directory, absolute
  * @param {string} basePath - Site base path (e.g., '/' or '/docs/')
  */
-async function processDataItemAssets(data, itemPath, siteRoot, entitiesRoot, basePath) {
+async function processDataItemAssets(data, itemPath, siteRoot, recordsRoot, 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)) {
-          parent[key] = (await publishRecordAsset(resolved, siteRoot, entitiesRoot, basePath)).url
+          parent[key] = (await publishRecordAsset(resolved, siteRoot, recordsRoot, basePath)).url
         }
       } else if (val.startsWith('/')) {
         // Absolute site path — just prepend base
@@ -450,28 +451,32 @@ async function processDataItemAssets(data, itemPath, siteRoot, entitiesRoot, bas
  *
  * @param {string} dir - Collection directory path
  * @param {string} filename - YAML filename (.yml or .yaml)
- * @returns {Promise<Object|Array|null>} Processed item(s) or null if unpublished
+ * @param {boolean} [includeDrafts] - keep `draft: true` records (a preview)
+ * @returns {Promise<Object|Array|null>} Processed item(s), or null for a draft this run withholds
  */
-async function processDataItem(dir, filename, siteRoot, entitiesRoot, basePath) {
+async function processDataItem(dir, filename, siteRoot, recordsRoot, basePath, includeDrafts = false) {
   const filepath = join(dir, filename)
+  const where = relative(siteRoot, filepath)
   const raw = await readFile(filepath, 'utf-8')
   const data = yaml.load(raw, YAML_OPTIONS) || {}
 
-  // Array → multiple items (single-file collection)
+  // 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)) {
-    for (const item of 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, entitiesRoot, basePath)
+        await processDataItemAssets(item, filepath, siteRoot, recordsRoot, basePath)
       }
     }
-    return data
+    return kept
   }
 
   // Mapping → single item
-  if (data.published === false) return null
+  if (withheld(data, where, includeDrafts)) return null
   const slug = basename(filename, extname(filename))
   const item = { slug, ...data }
-  await processDataItemAssets(item, filepath, siteRoot, entitiesRoot, basePath)
+  await processDataItemAssets(item, filepath, siteRoot, recordsRoot, basePath)
   return item
 }
 
@@ -484,28 +489,32 @@ async function processDataItem(dir, filename, siteRoot, entitiesRoot, basePath)
  *
  * @param {string} dir - Collection directory path
  * @param {string} filename - JSON filename
- * @returns {Promise<Object|Array|null>} Processed item(s) or null if unpublished
+ * @param {boolean} [includeDrafts] - keep `draft: true` records (a preview)
+ * @returns {Promise<Object|Array|null>} Processed item(s), or null for a draft this run withholds
  */
-async function processJsonItem(dir, filename, siteRoot, entitiesRoot, basePath) {
+async function processJsonItem(dir, filename, siteRoot, recordsRoot, basePath, includeDrafts = false) {
   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)
+  // 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)) {
-    for (const item of 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, entitiesRoot, basePath)
+        await processDataItemAssets(item, filepath, siteRoot, recordsRoot, basePath)
       }
     }
-    return data
+    return kept
   }
 
   // Object → single item
-  if (data.published === false) return null
+  if (withheld(data, where, includeDrafts)) return null
   const item = { slug, ...data }
-  await processDataItemAssets(item, filepath, siteRoot, entitiesRoot, basePath)
+  await processDataItemAssets(item, filepath, siteRoot, recordsRoot, basePath)
   return item
 }
 
@@ -521,17 +530,28 @@ async function processJsonItem(dir, filename, siteRoot, entitiesRoot, basePath)
  *
  * @param {string} dir - Collection directory path
  * @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`
  */
-async function processBibtexItem(dir, filename) {
+async function processBibtexItem(dir, filename, siteRoot, includeDrafts = false) {
   const filepath = join(dir, filename)
+  const where = relative(siteRoot, filepath)
   const raw = await readFile(filepath, 'utf-8')
   const entries = parseBibtex(raw)
   return entries
-    .filter(entry => entry && entry.id)
+    .filter(entry => entry && entry.id && !withheld(entry, `${where} @${entry.id}`, includeDrafts))
     .map(entry => ({ slug: entry.id, ...entry }))
 }
 
+/**
+ * Is this record left out of this run? A draft is, unless the run previews drafts.
+ * `isDraftRecord` also refuses the retired `published: false` — on every run.
+ */
+function withheld(data, where, includeDrafts) {
+  return isDraftRecord(data, where) && !includeDrafts
+}
+
 /**
  * Process a single content item from a markdown file
  *
@@ -540,10 +560,10 @@ async function processBibtexItem(dir, 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
+ * @param {string} recordsRoot - The site's records directory, absolute
+ * @returns {Promise<Object|null>} Processed item, or null for a draft this run withholds
  */
-async function processContentItem(dir, filename, config, siteRoot, basePath, entitiesRoot) {
+async function processContentItem(dir, filename, config, siteRoot, basePath, recordsRoot) {
   const filepath = join(dir, filename)
   const raw = await readFile(filepath, 'utf-8')
   const slug = basename(filename, extname(filename))
@@ -551,8 +571,8 @@ async function processContentItem(dir, filename, config, siteRoot, basePath, ent
   // Parse frontmatter and body
   const { frontmatter, body } = parseFrontmatter(raw, filepath)
 
-  // Skip unpublished items by default
-  if (frontmatter.published === false) {
+  // A draft is left out — before its assets are copied, so nothing of it ships.
+  if (withheld(frontmatter, relative(siteRoot, filepath), config.includeDrafts)) {
     return null
   }
 
@@ -561,14 +581,14 @@ async function processContentItem(dir, filename, config, siteRoot, basePath, ent
   // 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)
+  await processDataItemAssets(frontmatter, filepath, siteRoot, recordsRoot, 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, entitiesRoot, basePath)
+  await processRecordAssets(content, filepath, siteRoot, recordsRoot, basePath)
 
   // Extract excerpt
   const excerpt = extractExcerpt(frontmatter, content, config.excerpt)
@@ -644,47 +664,47 @@ function warnDuplicateSlugs(items, queryName) {
 }
 
 /**
- * Collect and process all items in a collection folder
+ * Collect and process all of a query's records
  *
  * @param {string} siteDir - Site root directory
- * @param {Object} config - Parsed collection config
+ * @param {Object} config - Parsed query config, carrying its `poolEntities`
+ * @param {string} recordsRoot - The site's records directory, absolute
  * @returns {Promise<Array>} Array of processed items
  */
-async function collectItems(siteDir, config, entitiesDir, basePath, locale = null) {
-  // ⭐ THE QUERY NAMES A SCHEMA AND THE POOL FOLLOWS — the same resolution the
+async function collectItems(siteDir, config, recordsRoot, basePath, locale = null) {
+  // ⭐ THE QUERY NAMES A SCHEMA AND THE RECORDS FOLLOW — the same resolution the
   // 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 || []
   if (pooled.length === 0) return []
 
-  // 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)
+  // A record's co-located assets are copied by their path under the records
+  // directory (`recordAssetPath`).
+  const dirOf = (e) => resolve(recordsRoot, ...e.dirs)
 
-  // Process all entity files (markdown → content items, YAML/JSON → data items,
+  // 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)
+        return processBibtexItem(dir, file, siteDir, config.includeDrafts)
       }
       if (e.ext === '.json') {
-        return processJsonItem(dir, file, siteDir, entitiesRoot, basePath)
+        return processJsonItem(dir, file, siteDir, recordsRoot, basePath, config.includeDrafts)
       }
       if (e.ext === '.yml' || e.ext === '.yaml') {
-        return processDataItem(dir, file, siteDir, entitiesRoot, basePath)
+        return processDataItem(dir, file, siteDir, recordsRoot, basePath, config.includeDrafts)
       }
-      return processContentItem(dir, file, config, siteDir, basePath, entitiesRoot)
+      return processContentItem(dir, file, config, siteDir, basePath, recordsRoot)
     })
   )
 
-  // ⭐ `path` IS THE PLACEMENT `records.yml` GAVE THE RECORD, and it is the whole
-  // reason folders exist: `where: { path: { under: 'archive' } }` is how a query
-  // asks for a slice. Structure is query scope, not navigation.
+  // ⭐ `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
+  // for a slice. Structure is query scope, not navigation.
   //
   // ⛔ 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
@@ -692,8 +712,8 @@ async function collectItems(siteDir, config, entitiesDir, basePath, locale = nul
   // failure mode the whole design is built to prevent. Measured before the fix: a
   // two-record site with an `archive` folder returned `[]` for its own slice.
   //
-  // ⚠️ It stays a SCALAR. `matchUnder` in `core/src/where.js` is string-only, so
-  // an array would match nothing — one placement per entity is the ruling.
+  // ⚠️ 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 })
@@ -704,7 +724,7 @@ async function collectItems(siteDir, config, entitiesDir, basePath, locale = nul
   // contribute their entries individually.
   items = items.flat()
 
-  // Filter out nulls (unpublished items)
+  // Filter out nulls (drafts this run withholds)
   items = items.filter(Boolean)
 
   // ⭐ `$name` IS THE RECORD HANDLE ON EVERY SITE (ruled 2026-09-11 [Diego]) — the
@@ -766,69 +786,61 @@ async function collectItems(siteDir, config, entitiesDir, basePath, locale = nul
 }
 
 /**
- * Process all content collections defined in site.yml
+ * Compile every query over the site's records
  *
  * @param {string} siteDir - Site root directory
  * @param {Object} queriesConfig - the resolved QUERY declarations
- * @param {string} [entitiesDir] - pool directory override (`site.yml::paths.entities`)
+ * @param {string} [recordsDir] - the records directory (`site.yml::paths.records`),
+ *   site-root-relative or absolute; resolved from `site.yml` when absent
  * @param {string} [basePath='/']
  * @param {Object} [options]
  * @param {string|null} [options.locale] - the site's default language, which a query's `sort`
  *   collates texts in when it orders the compiled file
- * @returns {Promise<Object>} Map of collection name to items array
+ * @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.
+ * @returns {Promise<Object>} Map of query name to items array
  *
  * @example
- * const collections = await processQueries('/path/to/site', {
- *   articles: { path: 'collections/articles', sort: 'date desc' },
- *   products: 'collections/products'
+ * const byQuery = await processQueries('/path/to/site', {
+ *   articles: { schema: '@/article', sort: 'date desc' },
  * })
- * // { articles: [...], products: [...] }
+ * // { articles: [...] }
  */
-export async function processQueries(siteDir, queriesConfig, entitiesDir, basePath = '/', { locale = null } = {}) {
+export async function processQueries(siteDir, queriesConfig, recordsDir, basePath = '/', { locale = null, includeDrafts = false } = {}) {
   if (!queriesConfig || typeof queriesConfig !== 'object') {
     return {}
   }
 
-  // ⭐ ONE POOL WALK FOR EVERY QUERY. Two queries over the same schema read one
-  // set of files; a query reads none of another schema's.
-  const pool = await readEntityPool(siteDir, { dir: entitiesDir })
+  // ⭐ ONE WALK FOR EVERY QUERY. Two queries over the same schema read one set of
+  // files; a query reads none of another schema's.
+  const pool = await readEntityPool(siteDir, recordsDir ? { dir: recordsDir } : {})
   if (pool.errors.length) {
     for (const e of pool.errors) console.warn(`[query-processor] ${e}`)
   }
 
-  // ⛔ `records.yml` DECIDES WHAT IS PUBLISHED ON THIS LANE TOO, and it did not
-  // until now. Only the sync lane honoured it, so removing a record from
-  // `records.yml` left it shipping in `/data/<name>.json` on every static host —
-  // an author unpublishes a draft and it stays public. Measured before the fix.
-  //
-  // ⚖️ MISSING IS NOT EMPTY HERE EITHER, but it means something different from
-  // what it means to sync. There is no server folder to leave alone, so a site
-  // 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.)
+  // ⭐ 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`),
+  // 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.
   //
-  // ⛔ 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)
+  // ⛔ A MALFORMED FILE STILL STOPS THE BUILD. It read as absent here until
+  // 2026-09-14 while the sync lane refused the same file (`uwx/records.js`); what an
+  // author meant to organize cannot be guessed.
+  const recordsCfg = await readRecordsConfig(siteDir, { dir: pool.dir })
   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.`
+        `  ${recordsCfg.file} says which folder each record sits in, and a query's \`scope:\` reads that — fix it to build.`
     )
   }
-  const managed = recordsCfg.state !== FOLDER_MISSING
-  const folder = managed ? resolveFolder(recordsCfg.entries, pool.entities) : null
-  if (folder) {
-    for (const e of folder.errors) console.error(`[query-processor] ${e}`)
-  }
-  const published = folder
-    ? pool.entities.filter((e) => folder.placements.has(e.id))
-    : pool.entities
+  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}`)
 
-  const poolBySchema = groupPoolBySchema(published)
+  const poolBySchema = groupPoolBySchema(pool.entities)
+  const recordsRoot = resolve(siteDir, pool.dir)
 
   const results = {}
 
@@ -839,15 +851,18 @@ export async function processQueries(siteDir, queriesConfig, entitiesDir, basePa
     if (config && typeof config === 'object' && config.url !== undefined) continue
     const parsed = parseQueryConfig(name, config)
     parsed.poolEntities = parsed.schema ? poolBySchema.get(parsed.schema) || [] : []
-    parsed.placements = folder?.placements ?? null
+    parsed.placements = folder.placements
+    parsed.includeDrafts = includeDrafts
     if (parsed.poolEntities.length === 0) {
+      const dirs = parsed.schema ? poolDirsForSchema(parsed.schema) : null
       console.warn(
-        `[query-processor] Query "${name}" matches no records — nothing ` +
-          `published declares ${parsed.schema || '(no schema)'}. ` +
-          (managed ? 'Check records.yml lists them.' : 'Check entities/.')
+        `[query-processor] Query "${name}" matches no records — ` +
+          (dirs
+            ? `${pool.dir}/${dirs.join('/')}/ holds none for ${parsed.schema}.`
+            : `it declares no schema whose records live in ${pool.dir}/.`)
       )
     }
-    const items = await collectItems(siteDir, parsed, entitiesDir, basePath, locale)
+    const items = await collectItems(siteDir, parsed, recordsRoot, basePath, locale)
     results[name] = items
     console.log(`[query-processor] Processed ${name}: ${items.length} items`)
   }
@@ -862,8 +877,8 @@ export async function processQueries(siteDir, queriesConfig, entitiesDir, basePa
  *
  * Why this is not optional. `public/data/` is a persistent, normally-committed
  * directory, so anything written there survives until something removes it.
- * Without this, unpublishing a record (`published: false`, which the build
- * honours automatically) or deleting its source file drops it from the cascade
+ * Without this, making a record a draft (`draft: true`, which the build honours
+ * automatically) or deleting its source file drops it from the cascade
  * listing — it vanishes from the site — while its per-record file stays on
  * disk with the full body, gets committed, and gets deployed. The author has
  * every reason to believe the content is gone. It is still fetchable at a URL

package/src/site/record-draft.js

@@ -0,0 +1,40 @@
+// A record's `draft: true` — it is a record (it sits in the site's folder) but is
+// not delivered while the site is published (ruled 2026-09-21 [Diego]).
+//
+// ⭐ ONE RULE, READ BY BOTH LANES. The build leaves a draft out of what it delivers —
+// the compiled query files a static host serves — and keeps it in `pnpm dev`, where
+// the author previews it, as a hidden page stays previewable. A backend holds the
+// same state as an entity's `disabled`, which withdraws it from every delivery read.
+//
+// ⚖️ NOT THE SAME AS A LEADING `_`. A file named `_x.md` is not a record at all: it
+// is not read, not pushed, not in the folder. A draft IS a record — the folder has
+// it — and only its delivery is withheld.
+//
+// ⛔ `published: false` WAS THE FILE LANE'S SPELLING until 2026-09-21, and it is
+// refused by name rather than read. It was odd per record (a record is not
+// published — the site is), and nothing on a backend honoured it. Ignoring it now
+// would deliver every record written with it, silently.
+
+/**
+ * Is this record a draft?
+ *
+ * @param {object} data - the record's fields (a markdown record's frontmatter)
+ * @param {string} where - the record, for messages (`records/article/x.md`)
+ * @returns {boolean}
+ * @throws on the retired `published: false`, and on a `draft:` that is not a boolean
+ */
+export function isDraftRecord(data, where) {
+  if (!data || typeof data !== 'object') return false
+  if (data.published === false) {
+    throw new Error(
+      `[uniweb] ${where}: \`published: false\` is retired — a record kept out of what the site ` +
+        `delivers is \`draft: true\`. It stays a record, in the folder.`
+    )
+  }
+  const draft = data.draft
+  if (draft === undefined || draft === null) return false
+  if (typeof draft !== 'boolean') {
+    throw new Error(`[uniweb] ${where}: \`draft:\` is true or false, not ${JSON.stringify(draft)}.`)
+  }
+  return draft
+}