@uniweb/build 0.56.0 → 0.58.0

package/src/site/records-config.js

@@ -1,70 +1,71 @@
-// `records.yml` — the site's FOLDER: what is in it, and where.
+// `records/folder.yml` — how the site's records folder is ORGANIZED. Optional.
 //
-// ⭐ LISTING AN ENTITY HERE IS WHAT MAKES IT A RECORD. An entity in `entities/`
-// exists; a record is a leaf entry in the site's folder. The backend's own gauge:
-// "An entity in no folder is not a record either: it exists, but cannot be
-// publicly fetched; placing a ref to it in a published folder is what makes one."
-// ⇒ An unreferenced entity is a draft, for free, with no flag to set.
+// ⭐ IT DOES NOT SAY WHAT IS IN THE FOLDER (ruled 2026-09-21 [Diego]). Every file in
+// `records/` is a record — placing it there is what makes one (`entity-pool.js`).
+// This file only sorts records into sub-folders, so a site whose records are one
+// flat set has no `folder.yml` at all, which is the common case.
 //
-// ⛔ IT IS A DATABASE, NOT A PAGE SYSTEM. Records are data. They usually have no
-// structure at all — a flat pool, and THE COMMON CASE IS THREE LINES:
+// ⭐ IT LIVES IN THE DIRECTORY IT ORGANIZES (ruled 2026-09-21 [Diego]) — the one file
+// at the top of `records/` that is not a record. The directory is the site's folder
+// on the file side, and this is that folder's organization: its paths are relative
+// to the directory, it moves with `paths.records`, and it travels with a records
+// directory that sites share — as a pages directory's own `folder.yml` does.
+// ⛔ It was `records.yml` at the site root until 2026-09-21, and a file there is
+// refused by name (`entity-pool.js::refuseRetiredFolderFile`), not read.
 //
-//     - person/*.md
-//     - publication/*.md
-//     - project/*.md
+// ⛔ UNTIL 2026-09-21 THIS FILE WAS THE MEMBERSHIP LIST: a bare string at the top
+// level listed an entity and made it a record, an unlisted one was left out, and
+// the file's absence or emptiness decided what a push did. All of that moved to
+// the directory. A top-level path is refused rather than read — it would claim to
+// select records while selecting nothing.
 //
 // ⛔ AND STRUCTURE IS QUERY SCOPE, NOT NAVIGATION. A `folder:` is an addressable
-// dimension a query slices on — `where: { path: { under: 'archive' } }` — never a
-// menu, a listing or a URL tree. The question is not "does this site want
-// sub-pages?" but "will a query ever ask for a SLICE rather than the whole pool?"
-// Most will not, which is why flat is the norm rather than a simplification.
+// dimension a query slices on — `scope: archive` — never a menu, a listing or a URL
+// tree. The question is not "does this site want sub-pages?" but "will a query ever
+// ask for a SLICE rather than the whole set?" Most will not, which is why flat is
+// the norm rather than a simplification.
 //
-// ⭐ THE SHAPE IS A LIST, and an entity gets no ceremony: a bare string IS an
-// entity path, one file or a pattern matching many. Only the exceptions announce
-// themselves — `url:`, `asset:`, `folder:`. (An earlier design keyed a map by
-// entry name; it charged every entry a key, a kind and often a label to buy
-// navigation ergonomics most sites never use. Measured on a realistic file: 7 of
-// 11 entries are just a path.)
+// ⭐ THE SHAPE IS A LIST OF FOLDERS, each holding records by path — one file, or a
+// pattern matching many — and further folders:
 //
-// ⛔ NO QUERIES IN HERE. A computed subset is a named query, in `queries.yml`.
-// Curation enumerates; queries compute. Two constructs, two jobs.
-//
-// ⭐ AND IT IS THE SYNC CONTROL. What syncs is exactly what this file references —
-// no flag, no inference. `missing` and `empty` differ deliberately:
+//     - folder: archive
+//       label: Publication Archive
+//       records:
+//         - publication/2025-*.md
 //
-//     missing  → inert. Do not sync; leave the server's folder untouched.
-//     empty    → destructive. Sync an empty folder, removing what is there.
+// Every record no folder names sits at the top of the site's folder.
 //
-// The safe state is the ABSENCE of a file and the destructive act requires
-// affirmatively creating one, so a live folder cannot be wiped by deleting
-// something. ⛔ Do not "simplify" these into one behaviour — it would delete a
-// capability. The placeholder hazard (someone creates an empty file meaning to
-// fill it in) is guarded at the CLI with a count and a confirmation; the format
-// stays honest and the CLI does the asking.
+// ⛔ NO QUERIES IN HERE. A computed subset is a named query, in `queries.yml`.
+// Organizing places records; queries compute. Two constructs, two jobs.
 //
-// Model: entity · record · query · folder.
+// Model: record · folder · query.
 
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
+import { resolve } from 'node:path'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { compareByNumericPrefix } from '../utils/numeric-prefix.js'
+import { RECORDS_DIR, FOLDER_YML, resolveRecordsDir } from './entity-pool.js'
 
-export const RECORDS_YML_RELPATH = 'records.yml'
+export { FOLDER_YML }
 
-/** Path to the records.yml file (whether or not it exists yet). */
-export function recordsYmlPath(siteRoot) {
-  return join(siteRoot, RECORDS_YML_RELPATH)
+/**
+ * Where the folder's organization lives — `folder.yml` in the records directory
+ * (`site.yml::paths.records`, else `records/`) — whether or not it exists yet.
+ *
+ * @param {string} siteRoot
+ * @param {string} [dir] - the records directory as written, when the caller has it;
+ *   otherwise it is resolved here, which also refuses the retired layouts
+ * @returns {{ abs: string, rel: string }} `rel` for messages (`records/folder.yml`)
+ */
+export function folderYmlPath(siteRoot, dir) {
+  const rel = dir ?? resolveRecordsDir(siteRoot).rel
+  return { abs: resolve(siteRoot, rel, FOLDER_YML), rel: `${rel}/${FOLDER_YML}` }
 }
 
-/** What `records.yml` says about syncing, before any entry is resolved. */
-export const FOLDER_MISSING = 'missing'
-export const FOLDER_EMPTY = 'empty'
-export const FOLDER_DECLARED = 'declared'
-
 /**
- * Match one entity path against a `records.yml` pattern.
+ * Match one record path against a `folder.yml` pattern.
  *
  * ⛔ `*` DOES NOT CROSS A `/`, which is what a reader expects of a file pattern
  * and is NOT what `@uniweb/core`'s `globMatch` does. That one backs the `like`
@@ -101,73 +102,88 @@ export function slugForEntity(entity) {
 }
 
 /**
- * Read `records.yml`.
+ * Read `folder.yml` — the folder's organization, in the records directory.
+ *
+ * ⭐ MISSING AND EMPTY MEAN THE SAME: no sub-folders, every record at the top.
+ * ⛔ Until 2026-09-21 they differed — missing left a backend's folder alone, empty
+ * removed what was there — because this file decided what was in the folder. The
+ * `records/` directory decides that now, so no state of this file removes a record.
  *
- * ⛔ THE THREE STATES ARE NOT TWO. `missing` and `empty` mean different things
- * and the difference is load-bearing (see the header), so this reports which it
- * saw rather than collapsing them into "no entries".
+ * ⛔ A MALFORMED FILE IS STILL AN ERROR: what it meant to organize cannot be guessed.
  *
- * @returns {Promise<{ state: string, entries: Array, error: string|null }>}
+ * @param {string} siteRoot
+ * @param {object} [opts]
+ * @param {string} [opts.dir] - the records directory as written (`readEntityPool`'s
+ *   `dir`), when the caller has it; otherwise it is resolved from `site.yml`
+ * @returns {Promise<{ exists: boolean, entries: Array, error: string|null, file: string }>}
+ *   `file` is where it was looked for, as the author would write it
  */
-export async function readRecordsConfig(siteRoot) {
-  const file = join(siteRoot, RECORDS_YML_RELPATH)
-  if (!existsSync(file)) return { state: FOLDER_MISSING, entries: [], error: null }
+export async function readRecordsConfig(siteRoot, { dir } = {}) {
+  const { abs, rel: file } = folderYmlPath(siteRoot, dir)
+  if (!existsSync(abs)) return { exists: false, entries: [], error: null, file }
 
   let doc
   try {
-    doc = yaml.load(await readFile(file, 'utf8'), YAML_OPTIONS)
+    doc = yaml.load(await readFile(abs, 'utf8'), YAML_OPTIONS)
   } catch (err) {
-    return { state: FOLDER_MISSING, entries: [], error: `${RECORDS_YML_RELPATH}: ${err.message}` }
+    return { exists: true, entries: [], error: `${file}: ${err.message}`, file }
   }
 
-  if (doc === null || doc === undefined || (Array.isArray(doc) && doc.length === 0)) {
-    return { state: FOLDER_EMPTY, entries: [], error: null }
-  }
+  if (doc === null || doc === undefined) return { exists: true, entries: [], error: null, file }
   if (!Array.isArray(doc)) {
     return {
-      state: FOLDER_MISSING,
+      exists: true,
       entries: [],
       error:
-        `${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`,
+        `${file} must be a LIST of folders, not ${typeof doc === 'object' ? 'a mapping' : 'a single value'}. ` +
+        `For example:\n  - folder: archive\n    records:\n      - publication/2025-*.md`,
+      file,
     }
   }
-  return { state: FOLDER_DECLARED, entries: doc, error: null }
+  return { exists: true, entries: doc, error: null, file }
 }
 
 /**
- * Resolve the folder's entries against the entity pool.
+ * Place the site's records in its folder: the sub-folders `folder.yml` declares,
+ * and the top of the folder for every record no sub-folder names.
  *
  * Every rule here is a guard, and each one exists because its failure was
  * SILENT. `entries: [artcles]` used to produce a real, reachable, empty path
  * with no warning at all.
  *
- * ⛔ ONE PLACEMENT PER ENTITY. Two entries matching one file is a hard error, not
+ * ⛔ ONE PLACEMENT PER RECORD. Two entries matching one file is a hard error, not
  * a second placement. The wire could carry many-to-many — `folder.js` nests, and
- * placements are keyed by their `name` chain — but `core/src/where.js`'s
- * `matchUnder` is STRING-ONLY, so a record with two paths would match nothing
- * under `where: { path: { under: … } }`, silently. Widening `under` is a
- * predicate the backend also evaluates natively, so it is a cross-lane change to
- * agree first, not to infer. Until then the file lane is the floor: one folder.
+ * a placement is banked by the record it references — but a record's `path` is one string:
+ * `@uniweb/core`'s `withinScope` matches nothing that is not a string, so a record
+ * with two paths would fall outside every `scope:`, silently. The records service
+ * evaluates `scope` natively, so widening it is a cross-lane change to agree first,
+ * not to infer. Until then the file lane is the floor: one folder.
  *
- * @param {Array} entries - the parsed `records.yml` list
- * @param {Array} pool - entities from `readEntityPool`
+ * @param {Array} entries - the parsed `folder.yml` list
+ * @param {Array} pool - records from `readEntityPool`
+ * @param {object} [opts]
+ * @param {string} [opts.dir] - the records directory as written, for messages
  * @returns {{ nodes: Array, placements: Map, errors: string[], warnings: string[] }}
- *   `nodes` is the folder tree (branches + entity placements, in file order);
- *   `placements` maps an entity id to its `{ entity, path, slug }`.
+ *   `nodes` is the folder tree — the declared sub-folders in file order, then every
+ *   record no sub-folder names; `placements` maps EVERY record's id to its
+ *   `{ entity, path, slug }`, `path` being `''` at the top of the folder.
  */
-export function resolveFolder(entries, pool) {
+export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
+  // The file as the author sees it, for every message below.
+  const file = `${dir}/${FOLDER_YML}`
   const errors = []
   const warnings = []
   const placements = new Map()
   // Which entry claimed a file, so the second one can name the first.
   const claimedBy = new Map()
+  // Which entry declared a folder, by its path, for the same reason.
+  const folderAt = new Map()
 
   const byRelPath = new Map()
   for (const e of pool || []) {
     // ⚠️ KEYED BY THE FILE AS IT EXISTS, prefix and all — an author writing
     // `post/01-lab-opens.md` is naming a file they can see, not the slug it
-    // produces. `poolPath` is that path, relative to `entities/`.
+    // produces. `poolPath` is that path, relative to `records/`.
     byRelPath.set(e.poolPath, e)
   }
 
@@ -176,8 +192,8 @@ export function resolveFolder(entries, pool) {
     const prior = claimedBy.get(key)
     if (prior) {
       errors.push(
-        `${RECORDS_YML_RELPATH}: "${entity.relPath}" is placed twice — by ${prior} and by ${where}. ` +
-          `An entity occupies one folder; a computed subset is a named query, not a second placement.`
+        `${file}: "${entity.relPath}" is placed twice — by ${prior} and by ${where}. ` +
+          `A record sits in one folder; a computed subset is a named query, not a second placement.`
       )
       return null
     }
@@ -193,31 +209,42 @@ export function resolveFolder(entries, pool) {
 
     if (typeof entry === 'string') {
       const pattern = entry.trim()
+      // ⛔ A PATH AT THE TOP LEVEL SELECTED RECORDS until 2026-09-21 — it was how a
+      // file became one. Every file in the directory is a record now, so the line
+      // would claim to choose while choosing nothing: refused, with the reason.
+      if (pathSegs.length === 0) {
+        errors.push(
+          `${file}: ${where} ("${pattern}") lists records at the top level. Every file in ` +
+            `${dir}/ is a record already — ${file} only sorts records into folders. ` +
+            `Remove the entry, or put it under a \`folder:\`.`
+        )
+        return []
+      }
       if (!pattern) {
-        errors.push(`${RECORDS_YML_RELPATH}: ${where} is an empty string.`)
+        errors.push(`${file}: ${where} is an empty string.`)
         return []
       }
       if (!isPattern(pattern)) {
         const hit = byRelPath.get(pattern)
         if (!hit) {
           errors.push(
-            `${RECORDS_YML_RELPATH}: ${where} names "${pattern}", which is not in entities/. ` +
-              `A bare string is a path under entities/, extension included.`
+            `${file}: ${where} names "${pattern}", which is not in ${dir}/. ` +
+              `A path is relative to ${dir}/, extension included.`
           )
           return []
         }
         const leaf = place(hit, pathSegs, where)
         return leaf ? [leaf] : []
       }
-      // ⛔ A PATTERN MATCHING NOTHING IS AN ERROR. `entities/artcle/*.md` is the
-      // old empty-branch defect respelled, and it produced a real, reachable,
-      // empty path with no warning.
+      // ⛔ A PATTERN MATCHING NOTHING IS AN ERROR. `artcle/*.md` is the old
+      // empty-branch defect respelled, and it produced a real, reachable, empty
+      // path with no warning.
       const matches = [...byRelPath.entries()]
         .filter(([rel]) => matchEntityPattern(pattern, rel))
         .map(([, e]) => e)
       if (matches.length === 0) {
         errors.push(
-          `${RECORDS_YML_RELPATH}: ${where} pattern "${pattern}" matches no entity. ` +
+          `${file}: ${where} pattern "${pattern}" matches no record in ${dir}/. ` +
             `Check the schema folder name and the extension.`
         )
         return []
@@ -230,7 +257,9 @@ export function resolveFolder(entries, pool) {
     }
 
     if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
-      errors.push(`${RECORDS_YML_RELPATH}: ${where} is neither a path nor a typed entry.`)
+      errors.push(
+        `${file}: ${where} is neither ${pathSegs.length ? 'a path nor ' : ''}a \`folder:\` entry.`
+      )
       return []
     }
 
@@ -244,20 +273,35 @@ export function resolveFolder(entries, pool) {
       const raw = entry.folder
       const segment = raw === null || raw === undefined ? '' : String(raw).trim()
       if (!segment) {
-        errors.push(`${RECORDS_YML_RELPATH}: ${where} declares a folder with no name.`)
+        errors.push(`${file}: ${where} declares a folder with no name.`)
         return []
       }
-      // ⭐ `name` is the handle (the URL segment, sibling-unique); `label` is the
+      // ⭐ A folder's `name` is the segment a query's `scope:` names; `label` is its
       // display text. The store renamed the pair on 2026-09-04 — `path_segment` →
-      // `name`, and the old `name` (display) → `label` — so one word means one
-      // thing from records.yml (`folder:` / `label:`) to the wire to the service's
-      // `$name`.
+      // `name`, and the old `name` (display) → `label`. ⛔ Not a URL segment: a folder
+      // is the curator's organization and maps to no route unless a query binds
+      // `scope: :dir` [Diego]. *("the URL segment, sibling-unique" stood here until
+      // 2026-09-21.)*
+      // ⛔ TWO FOLDERS AT ONE LEVEL CANNOT SHARE A NAME. A query's `scope:` names a
+      // folder by its path, so a second `archive` beside the first would make one scope
+      // of both, and a backend refuses a folder holding the pair. Records at one level
+      // may share a name; folders may not.
+      const at = [...pathSegs, segment].join('/')
+      const prior = folderAt.get(at)
+      if (prior) {
+        errors.push(
+          `${file}: folder "${segment}" is declared twice at one level — by ${prior} and by ${where}. ` +
+            `A query's \`scope:\` names a folder by its path, so merge them into one entry.`
+        )
+        return []
+      }
+      folderAt.set(at, where)
       const branch = { kind: 'branch', name: segment }
       if (entry.label !== undefined && entry.label !== null) branch.label = String(entry.label)
       const kids = Array.isArray(entry.records) ? entry.records : []
       if (kids.length === 0) {
         warnings.push(
-          `${RECORDS_YML_RELPATH}: folder "${segment}" (${where}) holds no records. ` +
+          `${file}: folder "${segment}" (${where}) holds no records. ` +
             `A folder exists to be QUERIED — if no query needs the slice, do not make it.`
         )
       }
@@ -274,7 +318,7 @@ export function resolveFolder(entries, pool) {
     if (entry.url !== undefined || entry.asset !== undefined) {
       const kind = entry.url !== undefined ? 'url' : 'asset'
       errors.push(
-        `${RECORDS_YML_RELPATH}: ${where} declares \`${kind}:\`, which the folder producer ` +
+        `${file}: ${where} declares \`${kind}:\`, which the folder producer ` +
           `does not emit yet. A folder holds urls and assets by design, but nothing would ` +
           `be sent for this entry — so it is refused rather than dropped.`
       )
@@ -282,24 +326,29 @@ export function resolveFolder(entries, pool) {
     }
 
     errors.push(
-      `${RECORDS_YML_RELPATH}: ${where} has no recognized kind. ` +
-        `A bare string is an entity path; anything else says \`folder:\`, \`url:\` or \`asset:\`.`
+      `${file}: ${where} has no recognized kind. ` +
+        (pathSegs.length
+          ? `Inside a folder, a path names records; anything else says \`folder:\`.`
+          : `An entry is a \`folder:\` — its \`records:\` are paths under ${dir}/.`)
     )
     return []
   }
 
-  const nodes = (entries || []).flatMap((entry, i) => resolveEntry(entry, [], i, ''))
+  const branches = (entries || []).flatMap((entry, i) => resolveEntry(entry, [], i, ''))
 
-  // ⚠️ REPORT WHAT NOTHING REFERENCES. It is a legitimate draft state, so it is
-  // not an error — but silence is how every defect in this area survived.
-  for (const e of pool || []) {
-    if (!placements.has(e.id)) {
-      warnings.push(
-        `${e.relPath} is in entities/ but referenced by nothing in ${RECORDS_YML_RELPATH} — ` +
-          `it exists, but it is not a record and no query can reach it.`
-      )
-    }
-  }
+  // ⭐ EVERY RECORD NO FOLDER NAMES SITS AT THE TOP — placement in the directory is
+  // what made it a record, so there is nothing for it to be left out of. In the
+  // directory's order, numeric-aware within a schema folder, the same order a
+  // pattern's matches take.
+  const unplaced = (pool || []).filter((e) => !placements.has(e.id))
+  const dirKey = (e) => (e.dirs || []).join('/')
+  unplaced.sort((a, b) => {
+    const da = dirKey(a)
+    const db = dirKey(b)
+    if (da !== db) return da < db ? -1 : 1
+    return compareByNumericPrefix(a.slug, b.slug)
+  })
+  const top = unplaced.map((e) => place(e, [], 'the directory')).filter(Boolean)
 
-  return { nodes, placements, errors, warnings }
+  return { nodes: [...branches, ...top], placements, errors, warnings }
 }

package/src/utils/numeric-prefix.js

@@ -1,6 +1,6 @@
 // The `01-` filename convention — ONE rule, for pages and for records.
 //
-// ⛔ IT WAS PRIVATE TO THE PAGES LANE, and `records.yml` needs exactly the same
+// ⛔ IT WAS PRIVATE TO THE PAGES LANE, and `records/folder.yml` needs exactly the same
 // rule: a leading `01-` orders a file and is stripped from the name it produces.
 // Two copies would drift, and the drift would be invisible — a section ordering
 // one way and a record another, both plausible, with nothing comparing them.

package/src/uwx/asset-map.js

@@ -31,7 +31,8 @@ import { createHash } from 'node:crypto'
 import { ASSET_SLOTS } from '@uniweb/semantic-parser'
 
 /**
- * The fingerprint `assets.json` keeps of the URL a host serves an asset at.
+ * The fingerprint the asset map in `sync.json` keeps of the URL a host serves an
+ * asset at.
  *
  * A hash, never the URL: it can recognize an address a pull brings back and it
  * cannot be used to compose one — see the header. Prefixed so a reader of the

package/src/uwx/backfill.js

@@ -228,6 +228,8 @@ function briefHasContentBody(declaration) {
  * entity: the entity `$uuid` + the brief section's fields (localized unwrapped,
  * date/scalars verbatim), with the brief record's own `$uuid` DROPPED (the backend
  * matches a single-section item by singularity) and `$model`/`$id`/`$meta` omitted.
+ * A disabled entity (`$disabled: true`) writes `draft: true`, and an enabled one writes
+ * no `draft:` at all.
  * For markdown, the content body field becomes the body; for YAML/JSON it stays a field.
  *
  * @param {object} params
@@ -283,6 +285,11 @@ export function renderEntityDocument({ document, declaration, format, sourceLoca
     }
     record[key] = value
   }
+  // ⭐ A DISABLED ENTITY IS A DRAFT ON THE FILE SIDE. It is kept in the folder and never
+  // publicly delivered, which is exactly what `draft: true` means. An enabled entity
+  // carries no key and writes no `draft:`, so a record re-enabled on the backend
+  // comes back without the line.
+  if (document.$disabled === true) record.draft = true
 
   if (format === 'json') return JSON.stringify(record, null, 2) + '\n'
   if (format === 'md') return `---\n${yaml.dump(record)}---\n${body}`
@@ -318,8 +325,9 @@ function writeIfChanged(filePath, text) {
  *        order: `{ id, model, slug, sourceFile, format?, multiRecord?, declaration? }`.
  * @param {object[]} params.finalized - response entries `{ index, uuid, changed?, document? }`.
  * @param {string} [params.sourceLocale]
- * @returns {{ updated: string[], unchanged: string[], deferred: object[], warnings: string[], mapped: Object<string,string> }}
+ * @returns {{ updated: string[], unchanged: string[], deferred: object[], warnings: string[], mapped: Object<string,string>, notKeptAsDrafts: string[] }}
  *   `mapped` is own id → the uuid this backend minted, for the caller to record per backend.
+ *   `notKeptAsDrafts` names records sent as drafts whose returned document is not disabled.
  */
 export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
   const updated = []
@@ -336,6 +344,8 @@ export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
   // Multi-record files are written ONCE per file, applying every (slug → uuid).
   const arrayFiles = new Map() // array-form YAML/JSON: sourceFile -> Map(slug -> uuid)
   const bibFiles = new Map() // BibTeX: sourceFile -> Map(cite key -> uuid)
+  // Records sent as drafts that the backend stored enabled. See the check below.
+  const notKeptAsDrafts = []
 
   for (const fin of finalized || []) {
     const uuid = fin.uuid
@@ -346,11 +356,20 @@ export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
       warnings.push(`finalized index ${i} has no matching submitted entity`)
       continue
     }
-    // Skip the non-record entities: the site-content entity (its uuid is back-filled
-    // into site.yml by the caller, via writeSiteEntityUuid) and the folder entity
+    // Skip the non-record entities: the site-content entity (its uuid is recorded in
+    // sync.json by the caller, via writeSiteEntityUuid) and the folder entity
     // (no uuid to back-fill — the backend owns the site's folder, keyed by the
     // site-content uuid). Both are positional placeholders with no record source file.
     if (entry.kind === 'site' || entry.kind === 'folder') continue
+    // ⛔ A DRAFT THE BACKEND DID NOT KEEP AS ONE. A backend is obliged to echo
+    // `$disabled: true` on the document of an entity it stored disabled. One that predates
+    // the key skips it without a word and stores the record enabled, so it is delivered
+    // once the site is published. Rendering that document over the file (variant A) would
+    // then erase `draft: true` from the author's file as well, so the file keeps its own
+    // text and the caller is told. Only a returned document that lacks the flag counts:
+    // with no document there is nothing to judge.
+    const draftNotKept = entry.draft === true && fin.document && fin.document.$disabled !== true
+    if (draftNotKept) notKeptAsDrafts.push(entry.sourceFile || entry.id)
     if (!entry.sourceFile) {
       deferred.push({ index: i, id: entry.id, reason: 'no source file on disk' })
       continue
@@ -389,6 +408,7 @@ export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
     // the declaration, and it's lossless for the format (md needs a content body
     // field for its body). Otherwise variant B: back-fill the uuid in place.
     const canRenderA =
+      !draftNotKept &&
       fin.document &&
       entry.declaration &&
       (entry.format !== 'md' || briefHasContentBody(entry.declaration))
@@ -432,5 +452,5 @@ export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
   for (const file of ownIdFiles) {
     if (!updated.includes(file) && !unchanged.includes(file)) unchanged.push(file)
   }
-  return { updated, unchanged, deferred, warnings, mapped }
+  return { updated, unchanged, deferred, warnings, mapped, notKeptAsDrafts }
 }

package/src/uwx/entity-source.js

@@ -10,9 +10,9 @@
 // ⭐ THE FLAT-VS-RECURSIVE DIVERGENCE THIS FILE USED TO WARN ABOUT IS CLOSED.
 // It reported records below a collection's top level as building and rendering
 // locally while being absent from the synced set — the delivery lane recursed,
-// this one was one level deep. `entities/{schema}/` has no nesting to disagree
-// about (`site/entity-pool.js` refuses it), and placement moved to `records.yml`,
-// so both lanes now read the same flat pool. The warning went with the ambiguity.
+// this one was one level deep. `records/{schema}/` has no nesting to disagree
+// about (`site/entity-pool.js` refuses it), and placement moved to `records/folder.yml`,
+// so both lanes now read the same flat directory. The warning went with the ambiguity.
 //
 // A collection `.md` is NOT a page-section `.md`: its frontmatter is structured
 // DATA whose schema is the collection type's data schema (the `model:` Model), and
@@ -55,7 +55,7 @@ function formatFor(ext) {
 /**
  * Read ONE entity file into its raw source record(s).
  *
- * ⭐ THE FILE IS THE UNIT NOW. `entities/{schema}/` supplies the model, so
+ * ⭐ THE FILE IS THE UNIT NOW. `records/{schema}/` supplies the model, so
  * nothing above this needs a directory scan to know what a file is — the pool
  * reader (`site/entity-pool.js`) already walked the tree and paired each file
  * with its schema. A single-record file yields one record; array-form YAML/JSON