@uniweb/build 0.55.1 → 0.57.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.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 = {

package/src/uwx/index.js

@@ -44,7 +44,6 @@ export {
   emitSiteSyncPackage,
   writeSiteEntityUuid,
   writeSiteOrg,
-  writeSiteBackend,
   extensionDeclaration,
   isExtensionUrl,
   isSiteRelativeExtensionUrl,
@@ -77,14 +76,27 @@ export {
   localeFilePath,
 } from './locale-sync.js'
 export { emitSyncPackages } from './sync-package.js'
-export {
-  readAssetMap,
-  updateAssetMap,
+// ⚠️ The asset MAP is `sync.json::backends.<origin>.assets` (sync-store.js, below).
+// `readAssetMap` / `updateAssetMap` / `refForAssetId` / `ASSET_MAP_FILE` were removed
+// on 2026-09-20: a single flat file cannot hold ids minted by more than one backend.
+export { restoreAssetRefs, servedFingerprint } from './asset-map.js'
+// `sync.json` — what each backend minted, keyed by origin. Absorbs `assets.json`
+// above, `site.yml`'s identity keys and three maps out of the sync cache.
+// Spec: kb/framework/reference/sync-json.md
+export {
+  SYNC_STORE_FILE,
+  readSyncStore,
+  readBackendState,
+  listSyncedBackends,
+  updateBackendState,
+  updateBackendMap,
+  carryServed,
+  clearBackend,
+  clearBackendSections,
+  forgetSyncStore,
   refForAssetId,
-  restoreAssetRefs,
-  ASSET_MAP_FILE,
-  servedFingerprint,
-} from './asset-map.js'
+  normalizeOrigin as normalizeBackendOrigin,
+} from './sync-store.js'
 export {
   diffSiteUnits,
   describeSiteDiff,
@@ -104,23 +116,23 @@ 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.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,
 } from '../site/records-config.js'
 export {
   findRecordFile,