@uniweb/build 0.56.0 → 0.58.0

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/folder.yml` (ruled 2026-09-21 [Diego]). Every file in `records/` is a
+// record and sits at the top of the folder unless `folder.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: `folder.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 = {

package/src/uwx/index.js

@@ -61,7 +61,7 @@ export { buildFolderEntity,
 export {
   recordsToProject,
   declarationsToQueriesYml,
-  folderToRecordsYml,
+  folderToFolderYml,
   findRecordFileByUuid,
 } from './records-project.js'
 export {
@@ -116,23 +116,24 @@ export {
 } from './records.js'
 export { readEntityFile, parseFrontmatter } from './entity-source.js'
 
-// The folder's own vocabulary, so a verb can ask what `records.yml` SAYS without
-// re-reading or re-parsing it. ⛔ Note the allowlist: an export added to
-// `site/records-config.js` does not reach a caller until it is named here.
-// The pool's grammar — a schema ref to its directory and back. ⛔ Allowlist: an
-// export added to `site/entity-pool.js` does not reach a caller until it is here.
+// Where a site's records live, and the grammar of that directory — a schema ref to
+// its folder and back. ⛔ Allowlist: an export added to `site/entity-pool.js` does
+// not reach a caller until it is here.
 export {
   poolDirsForSchema,
   schemaForPoolDirs,
-  ENTITIES_DIR,
+  readEntityPool,
+  resolveRecordsDir,
+  RECORDS_DIR,
 } from '../site/entity-pool.js'
 
+// How the folder is organized, so a verb can ask what `records/folder.yml` SAYS without
+// re-reading or re-parsing it. ⛔ Note the allowlist: an export added to
+// `site/records-config.js` does not reach a caller until it is named here.
 export {
   readRecordsConfig,
-  RECORDS_YML_RELPATH,
-  FOLDER_MISSING,
-  FOLDER_EMPTY,
-  FOLDER_DECLARED,
+  FOLDER_YML,
+  folderYmlPath,
 } from '../site/records-config.js'
 export {
   findRecordFile,

package/src/uwx/project-writer.js

@@ -19,7 +19,7 @@ import { proseMirrorToMarkdown, serializeFrontmatter } from '@uniweb/content-wri
 import { parseFrontmatter } from './entity-source.js'
 import { renderEntityDocument } from './backfill.js'
 import { queriesYmlPath } from './queries-config.js'
-import { recordsYmlPath } from '../site/records-config.js'
+import { folderYmlPath } from '../site/records-config.js'
 import { DECLARATION_KEYS } from '../site/fetch-shapes.js'
 
 // Frontmatter keys that belong to the CCA framework / the developer's local
@@ -294,23 +294,25 @@ export function writeQueriesConfig(siteRoot, queries) {
 }
 
 /**
- * Write `records.yml` — the site's folder, as a LIST.
+ * Write the records folder's organization — `folder.yml` in the records directory
+ * (`records/`, or wherever `site.yml::paths.records` puts it), as a LIST.
  *
  * ⛔ A FULL WRITE, NOT A MERGE, and that is the one place this differs from every
- * other projected config. `records.yml` IS the folder: concrete refs on both
- * sides, nothing to invert, so a pull is a mirror rather than an update. There is
- * also nothing a shallow merge could mean here — the file is a sequence, and
- * merging two lists either duplicates entries or silently drops them.
+ * other projected config. The file mirrors the folder's sub-folders: concrete refs
+ * on both sides, nothing to invert, so a pull is a mirror rather than an update.
+ * There is also nothing a shallow merge could mean here — the file is a sequence,
+ * and merging two lists either duplicates entries or silently drops them.
  *
- * ⚠️ WHICH IS WHY AN EMPTY LIST IS NOT WRITTEN AS A FILE-WITH-NOTHING BY ACCIDENT.
- * An empty `records.yml` is DESTRUCTIVE on the next push — it says the folder holds
- * nothing. A pull that carried no folder must leave the file alone, so the caller
- * decides, and this only writes what it was actually given.
+ * The caller decides whether there is anything to write: a folder with no
+ * sub-folders is no file at all (`folderToFolderYml` removes it), since missing and
+ * empty mean the same. ⚠️ *Until 2026-09-21 this said an empty file was destructive
+ * on the next push; that stopped being true when the directory, not this file,
+ * became what decides which records the folder holds.*
  *
  * @returns {'updated'|'unchanged'}
  */
 export function writeRecordsConfig(siteRoot, entries) {
-  return writeYamlFile(recordsYmlPath(siteRoot), entries)
+  return writeYamlFile(folderYmlPath(siteRoot).abs, entries)
 }
 
 /**