@uniweb/build 0.56.0 → 0.57.0

package/src/site/records-config.js

@@ -1,48 +1,36 @@
-// `records.yml` — the site's FOLDER: what is in it, and where.
+// `records.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 `records.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:
-//
-//     - 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.
-//
-// ⭐ 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.)
+// 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.
 //
-// ⛔ NO QUERIES IN HERE. A computed subset is a named query, in `queries.yml`.
-// Curation enumerates; queries compute. Two constructs, two jobs.
+// ⭐ THE SHAPE IS A LIST OF FOLDERS, each holding records by path — one file, or a
+// pattern matching many — and further folders:
 //
-// ⭐ 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'
@@ -50,6 +38,7 @@ 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'
+import { RECORDS_DIR } from './entity-pool.js'
 
 export const RECORDS_YML_RELPATH = 'records.yml'
 
@@ -58,13 +47,8 @@ export function recordsYmlPath(siteRoot) {
   return join(siteRoot, RECORDS_YML_RELPATH)
 }
 
-/** 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 `records.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,62 +85,67 @@ export function slugForEntity(entity) {
 }
 
 /**
- * Read `records.yml`.
+ * Read `records.yml` — the folder's organization.
  *
- * ⛔ 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".
+ * ⭐ 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.
  *
- * @returns {Promise<{ state: string, entries: Array, error: string|null }>}
+ * ⛔ A MALFORMED FILE IS STILL AN ERROR: what it meant to organize cannot be guessed.
+ *
+ * @returns {Promise<{ exists: boolean, entries: Array, error: string|null }>}
  */
 export async function readRecordsConfig(siteRoot) {
   const file = join(siteRoot, RECORDS_YML_RELPATH)
-  if (!existsSync(file)) return { state: FOLDER_MISSING, entries: [], error: null }
+  if (!existsSync(file)) return { exists: false, entries: [], error: null }
 
   let doc
   try {
     doc = yaml.load(await readFile(file, 'utf8'), YAML_OPTIONS)
   } catch (err) {
-    return { state: FOLDER_MISSING, entries: [], error: `${RECORDS_YML_RELPATH}: ${err.message}` }
+    return { exists: true, entries: [], error: `${RECORDS_YML_RELPATH}: ${err.message}` }
   }
 
-  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 }
   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`,
+        `${RECORDS_YML_RELPATH} 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`,
     }
   }
-  return { state: FOLDER_DECLARED, entries: doc, error: null }
+  return { exists: true, entries: doc, error: null }
 }
 
 /**
- * Resolve the folder's entries against the entity pool.
+ * Place the site's records in its folder: the sub-folders `records.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} 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 } = {}) {
   const errors = []
   const warnings = []
   const placements = new Map()
@@ -167,7 +156,7 @@ export function resolveFolder(entries, pool) {
   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)
   }
 
@@ -177,7 +166,7 @@ export function resolveFolder(entries, pool) {
     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.`
+          `A record sits in one folder; a computed subset is a named query, not a second placement.`
       )
       return null
     }
@@ -193,6 +182,17 @@ 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(
+          `${RECORDS_YML_RELPATH}: ${where} ("${pattern}") lists records at the top level. Every file in ` +
+            `${dir}/ is a record already — ${RECORDS_YML_RELPATH} 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.`)
         return []
@@ -201,23 +201,23 @@ export function resolveFolder(entries, pool) {
         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.`
+            `${RECORDS_YML_RELPATH}: ${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. ` +
+          `${RECORDS_YML_RELPATH}: ${where} pattern "${pattern}" matches no record in ${dir}/. ` +
             `Check the schema folder name and the extension.`
         )
         return []
@@ -230,7 +230,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(
+        `${RECORDS_YML_RELPATH}: ${where} is neither ${pathSegs.length ? 'a path nor ' : ''}a \`folder:\` entry.`
+      )
       return []
     }
 
@@ -247,11 +249,12 @@ export function resolveFolder(entries, pool) {
         errors.push(`${RECORDS_YML_RELPATH}: ${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.)*
       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 : []
@@ -283,23 +286,28 @@ 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:\`.`
+        (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/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

@@ -346,8 +346,8 @@ 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

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
+// 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.yml`,
-// so both lanes now read the same flat pool. The warning went with the ambiguity.
+// 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

package/src/uwx/folder.js

@@ -12,29 +12,41 @@
 //         or `$ref: "<id>"` while brand-new (resolved within this payload).
 //       - a BRANCH is a sub-folder: `{ kind: 'branch', name, label?, $children }`.
 //
-// ⭐ `name` IS THE HANDLE — the URL segment, sibling-unique, the records service's `$name` —
-// and `label` is the display text, a localized map (`{ en: "Blog" }`). The store
+// ⭐ A LEAF'S `name` IS ITS RECORD'S HANDLE — the slug, the records service's `$name` —
+// and a branch's `name` is the segment a query's `scope:` names. `label` is a branch's
+// display text, a localized map (`{ en: "Blog" }`).
+//
+// ⛔ A FOLDER IS NOT A URL MAP, AND ITS NAMES ARE NOT UNIQUE ACROSS SCHEMAS. It is a
+// content pool organized for the curator's convenience [Diego, 2026-09-21]; a slug is
+// resolved by a (parametric) query over one schema, never by where a record sits, and
+// mapping a URL to a folder path takes an explicit `scope: :dir` on a query. So
+// `article/intro` and `person/intro` side by side in one folder is ordinary. *(This
+// note called `name` "the URL segment, sibling-unique" until 2026-09-21, and that
+// wording led straight to a push refusing two such records.)* The store
 // renamed the pair on 2026-09-04 (`path_segment` → `name`; the old display `name`
 // → `label`); this emitter writes the new shape only and the pull reader
 // (`records-project.js`) reads the new shape only. No alias on either side: the
 // old key's PRESENCE was the version signal, and there is no population to
 // carry.
 //
-// ⭐ THE ORGANIZATION IS AUTHORED, IN `records.yml`, AND IT IS THE ONLY SOURCE.
-// It used to be DERIVED — one branch per collection, mirroring the `collections/`
-// subfolders, with an optional `collections.yml::folders` virtual tree layered
-// over it. Both are gone, and the difference is the point: a folder is a thing
-// the author states, not a shadow of a directory layout. `records.yml` also
-// decides WHAT syncs at all, since listing an entity is what makes it a record.
+// ⭐ WHAT IS IN THE FOLDER IS THE RECORDS DIRECTORY; HOW IT IS ORGANIZED IS
+// `records.yml` (ruled 2026-09-21 [Diego]). Every file in `records/` is a record and
+// sits at the top of the folder unless `records.yml` places it in a sub-folder. The
+// organization used to be DERIVED — one branch per collection, mirroring the
+// `collections/` subfolders — and the difference is the point: a sub-folder is a
+// thing the author states, never a shadow of the schema folders, which declare a
+// model and nothing else.
 //
-// ⛔ SO THERE IS NO DEFAULT. A site with no `records.yml` has no folder and syncs
-// no records — which is the model's `missing ⇒ inert` ruling, not an empty folder.
-// Do not reintroduce a fallback grouping: it would resurrect exactly the
-// three-jobs-in-one-directory conflation the layout was changed to remove.
+// ⛔ A SITE WITH NO RECORDS DIRECTORY SENDS NO FOLDER, which is inert: the backend's
+// folder is left as it is, so a site whose records live only there is not emptied
+// by a push of its pages. A directory holding no records sends an EMPTY folder,
+// which removes what is there — the CLI asks first. (Until 2026-09-21 both states
+// were `records.yml`'s — missing and empty — when that file was the membership list.)
 //
 // The folder carries NO `$uuid` of its own: the backend owns the site's
 // `@uniweb/folder` and resolves it from the site-content uuid (the folder sync lane
-// is keyed by `site.yml::$uuid`). The framework never holds a folder uuid.
+// is keyed by the site's uuid on that backend, from `sync.json`). The framework
+// never holds a folder uuid.
 
 export const FOLDER_MODEL_NAME = '@uniweb/folder'
 export const FOLDER_ENTITY_KEY = '@folder'
@@ -57,7 +69,7 @@ function refLeaf(entity) {
 }
 
 /**
- * Turn the resolved `records.yml` tree into folder `contents`.
+ * Turn the placed records into folder `contents`.
  *
  * ⛔ A LEAF WHOSE ENTITY IS MISSING IS DROPPED AND REPORTED, never emitted empty.
  * A `ref` with neither `entry` nor `$ref` is a placement pointing at nothing —
@@ -91,9 +103,19 @@ function contentsFromNodes(nodes, byEntityId, missing, sourceLocale) {
   return out
 }
 
+// The uuid of the record a leaf references — once minted, `entry: { model, entity }`
+// (a bare uuid is tolerated). A brand-new record's leaf carries `$ref` instead.
+function recordOf(item) {
+  if (item?.kind !== 'ref') return null
+  const e = item.entry
+  const uuid = e && typeof e === 'object' ? e.entity : e
+  return typeof uuid === 'string' && uuid ? uuid : null
+}
+
 /**
- * Walk a folder document's `contents` tree, visiting every item with the
- * slash-joined `name` chain that addresses it.
+ * Walk a folder document's `contents` tree, visiting every item with the keys that
+ * address it: its slash-joined `name` chain, whether that chain is UNIQUE among its
+ * siblings, and — for a leaf — the uuid of the record it references.
  *
  * ⛔ IT MUST RECURSE INTO `$children`. `contents` is SELF-NESTING: a walk of the
  * top level sees the branches and misses every record under them — which is 6 of
@@ -101,11 +123,15 @@ function contentsFromNodes(nodes, byEntityId, missing, sourceLocale) {
  * before it could be got wrong.)*
  */
 function walkFolderItems(contents, cb, prefix = '') {
-  for (const item of contents || []) {
-    if (!item || typeof item !== 'object') continue
+  const items = (contents || []).filter((item) => item && typeof item === 'object')
+  const count = new Map()
+  for (const item of items) {
+    if (typeof item.name === 'string') count.set(item.name, (count.get(item.name) || 0) + 1)
+  }
+  for (const item of items) {
     const seg = typeof item.name === 'string' ? item.name : null
     const path = seg ? (prefix ? `${prefix}/${seg}` : seg) : prefix
-    if (seg) cb(path, item)
+    if (seg) cb({ path, unique: count.get(seg) === 1, record: recordOf(item) }, item)
     walkFolderItems(item.$children, cb, path)
   }
 }
@@ -113,18 +139,24 @@ function walkFolderItems(contents, cb, prefix = '') {
 /**
  * Harvest per-item identity from the folder document the backend returns.
  *
- * ⭐ THE KEY IS THE `name` CHAIN, and it is the right one because the backend's
- * own model declares `name` SIBLING-UNIQUE — so the chain is
- * unique within the folder, stable across pushes, and derivable identically on
- * both sides without either lane holding the other's ids.
+ * ⭐ A PLACEMENT IS KEYED BY THE RECORD IT REFERENCES — `@<record uuid>` — because a
+ * record has one placement, so that key is unique in the folder whatever the names
+ * are. A branch, and a leaf whose name no sibling shares, is ALSO keyed by its `name`
+ * chain, which is what every placement map banked before 2026-09-21 holds.
+ *
+ * ⛔ The chain alone assumed no two siblings share a name. Two records of different
+ * schemas can (`article/intro`, `person/intro`), and keyed by `intro` both would
+ * have been stamped with one uuid on the next push.
  *
  * @param {object} doc - a stored `@uniweb/folder` document (`{ contents: [...] }`)
- * @returns {Record<string,string>} path → `$uuid`
+ * @returns {Record<string,string>} key → `$uuid` — `@<record uuid>`, or a `name` chain
  */
 export function collectFolderItemUuids(doc) {
   const out = {}
-  walkFolderItems(doc?.contents, (path, item) => {
-    if (typeof item.$uuid === 'string' && item.$uuid) out[path] = item.$uuid
+  walkFolderItems(doc?.contents, ({ path, unique, record }, item) => {
+    if (typeof item.$uuid !== 'string' || !item.$uuid) return
+    if (record) out[`@${record}`] = item.$uuid
+    if (unique) out[path] = item.$uuid
   })
   return out
 }
@@ -143,15 +175,23 @@ export function collectFolderItemUuids(doc) {
  * from the site-content uuid. This is about its ITEMS, and the two were conflated
  * by a comment in this file that was true of the entity and false of its contents.
  *
+ * ⭐ A leaf takes the uuid banked under its record (`@<record uuid>`) first, and its
+ * `name` chain only when no sibling shares the name — the one key an older map has.
+ * ⛔ No uuid is stamped twice: two items claiming one row is the failure the record
+ * key exists to prevent, so a second claimant goes out without one, as a new row.
+ *
  * @returns {{ stamped: number, unknown: number }}
  */
 export function stampFolderItemUuids(doc, pathToUuid = {}) {
   let stamped = 0
   let unknown = 0
-  walkFolderItems(doc?.contents, (path, item) => {
-    const uuid = pathToUuid[path]
-    if (uuid) {
+  const claimed = new Set()
+  walkFolderItems(doc?.contents, ({ path, unique, record }, item) => {
+    let uuid = record ? pathToUuid[`@${record}`] : undefined
+    if (!uuid && unique) uuid = pathToUuid[path]
+    if (uuid && !claimed.has(uuid)) {
       item.$uuid = uuid
+      claimed.add(uuid)
       stamped++
     } else {
       unknown++
@@ -169,8 +209,9 @@ export function stampFolderItemUuids(doc, pathToUuid = {}) {
  * @param {object} params
  * @param {object[]} params.recordEntities - the record entities (full set, BEFORE
  *        send-only-changed filtering), each `{ id, uuid, slug, model }`
- * @param {Array} params.folderNodes - the resolved `records.yml` tree
- * @param {boolean} [params.declared] - whether `records.yml` EXISTS. See below.
+ * @param {Array} params.folderNodes - the placed records: `records.yml`'s sub-folders,
+ *        then every record at the top
+ * @param {boolean} [params.declared] - whether the records DIRECTORY exists. See below.
  * @param {Record<string,string>} [params.itemUuids] - path → `$uuid`, harvested
  *        from the folder document a previous push returned. Absent on a first
  *        push, where every item is genuinely new.
@@ -181,17 +222,16 @@ export function stampFolderItemUuids(doc, pathToUuid = {}) {
 export function buildFolderEntity({ recordEntities, folderNodes = [], declared, itemUuids = null, sourceLocale = 'en' }) {
   // ⛔ `missing` AND `empty` ARE DIFFERENT, AND THE ASYMMETRY IS DELIBERATE.
   //
-  //   no records.yml       → null. INERT: nothing is sent, and the server's
-  //                          folder is left exactly as it is.
-  //   records.yml, empty   → a folder with `contents: []`. DESTRUCTIVE: it says
-  //                          the folder holds nothing, so the backend removes
-  //                          what is there.
+  //   no records directory  → null. INERT: nothing is sent, and the backend's
+  //                           folder is left exactly as it is.
+  //   a directory, no records → a folder with `contents: []`. DESTRUCTIVE: it says
+  //                           the folder holds nothing, so the backend removes
+  //                           what is there.
   //
-  // ⭐ 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 to avoid the
-  // placeholder hazard (an empty file created meaning to fill it in): that would
-  // delete a capability to avoid writing a prompt. The CLI asks, with a count.
+  // ⭐ The safe state is the ABSENCE of the directory, so a site that never had
+  // records — or keeps them only on the backend — cannot empty the backend's folder
+  // by pushing. ⛔ Do not "simplify" these into one behaviour: that would delete a
+  // capability to avoid writing a prompt. The CLI asks, with a count.
   const empty = !Array.isArray(folderNodes) || folderNodes.length === 0
   if (empty && !declared) return null
 
@@ -200,17 +240,17 @@ export function buildFolderEntity({ recordEntities, folderNodes = [], declared,
 
   const missing = []
   const contents = contentsFromNodes(folderNodes, byEntityId, missing, sourceLocale)
-  // ⚠️ `id` IS THE ENTITY'S POOL PATH, NOT A FOLDER PATH — say so, because the two
-  // read identically and a reader who takes it for a placement concludes the
-  // emitter is dropping a branch it never had. *(Measured 2026-08-31: the backend
-  // lane read `folder: "articles/outdoor-hygge"` as a placement under an
+  // ⚠️ `id` IS THE RECORD'S PATH IN THE RECORDS DIRECTORY, NOT A FOLDER PATH — say
+  // so, because the two read identically and a reader who takes it for a placement
+  // concludes the emitter is dropping a branch it never had. *(Measured 2026-08-31:
+  // the backend lane read `folder: "articles/outdoor-hygge"` as a placement under an
   // `articles` branch and opened a channel about a missing branch node; the string
-  // was naming `entities/articles/outdoor-hygge.md`.)*
+  // was naming the file `articles/outdoor-hygge.md`.)*
   const warnings = missing.map(
     (id) =>
-      `records.yml: "${id}" — a path under entities/ — is listed, but no record ` +
-      `entity was produced for it (check that its schema resolves). The placement ` +
-      `was dropped rather than sent pointing at nothing.`
+      `the record "${id}" — a path under the records directory — is placed in the ` +
+      `folder, but no record entity was produced for it. The placement was dropped ` +
+      `rather than sent pointing at nothing.`
   )
 
   const document = {