@uniweb/build 0.55.1 → 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

@@ -1,159 +1,38 @@
 /**
- * `assets.json` — the site's committed map from a local asset path to the
- * backend's content-addressed id.
- *
- * ## Why it is COMMITTED, and why that is the whole point
- *
- * The same map used to be built on every push and thrown away
- * (`assetsByLocalUrl`, in memory, consumed by the content rewrite and dropped).
- * Rebuilt per push it is a private detail; committed it is a **log every machine
- * collaborating on this site can read**:
- *
- *   - a teammate who clones knows which bytes the project expects to exist and
- *     can fetch the ones they lack, instead of discovering a missing image at
- *     render;
- *   - `pull` can put an asset back at **the path its author wrote**, rather than
- *     inventing one — without this, a push turns `/images/hero.png` into an
- *     opaque id and nothing remembers it was ever called that;
- *   - a re-push of unchanged media is visibly a no-op rather than a silent one.
- *
- * ⇒ It is project state, not cache. `.uniweb/` is gitignored in both scaffolded
- * templates, which is why this does not live there.
- *
- * ## ⛔ Diff stability is a hard requirement, not tidiness
- *
- * A committed file that reorders itself produces a spurious diff on every push
- * and trains people to stop reading it — at which point a real change to what a
- * site ships passes unnoticed. Keys are therefore **sorted**, the shape is flat,
- * and the writer is a no-op when nothing changed (it does not rewrite an
- * identical file, so `git status` stays clean on a push that moved no assets).
- *
- * ## What it deliberately does NOT hold
- *
- * ⛔ **No serve URL.** A URL is a host's route layout, and storing one here would
- * re-create — in a committed file, on every machine — exactly the coupling that
- * deleting `buildAssetUrl` removed from this CLI. The id plus the host's
- * `config.assets.url` pattern is the whole address, and only the host owns the
- * second half.
- *
- * ⚖️ **What it holds instead is a FINGERPRINT of the served URL** (`served`), and the
- * difference is the point: a hash can recognize an address and cannot compose one.
- * It exists for references that are a BARE STRING — `info.preview`, `info.favicon`,
- * `seo.image`, a section param — where there is no object to stamp `assetId` beside,
- * so the stored value is the serve URL alone. `pull` hashes such a string and, when
- * it matches, puts back the path the author wrote. Should the host ever serve an
- * asset at a new address, the fingerprint simply stops matching and the pull leaves
- * the URL — the honest projection — until the next push records the new one.
- *
- * ⛔ **No mime or size.** The store validates those and they are its to change;
- * a second copy here is a second thing to disagree.
+ * Asset reference helpers — two pure functions, no file.
+ *
+ * ⚠️ **The MAP moved to `sync.json` on 2026-09-20** (`sync-store.js`,
+ * `backends.<origin>.assets`). It lived here as `assets.json`, a single flat
+ * `local path → id` file that assumed ONE backend — which is exactly what it
+ * could not represent once a project syncs with several: an id is minted by a
+ * backend and means nothing to any other one. `readAssetMap` / `updateAssetMap` /
+ * `refForAssetId` / `ASSET_MAP_FILE` went with it.
+ *
+ * What stays here is what never touched the filesystem:
+ *
+ * - **`servedFingerprint`** — hashes a serve URL. It exists for references that are
+ *   a BARE STRING (`info.preview`, `seo.image`, a section param), where there is no
+ *   object to stamp an id beside, so the stored value is the address alone. ⛔ A
+ *   fingerprint rather than the URL because a hash can RECOGNIZE an address and
+ *   cannot COMPOSE one — route layout is the host's and never ours to rebuild.
+ * - **`restoreAssetRefs`** — puts an author's own paths back into a document pulled
+ *   from a backend. Without it a push/pull cycle rewrites every image in a
+ *   developer's source to a backend route: a mangling of files they own, by a round
+ *   trip that changed nothing.
+ *
+ * ⭐ **`restoreAssetRefs` no-ops on an empty map**, which is what makes the store's
+ * `backend` parameter honest: a projection not tied to a backend has no known
+ * assets, so it restores nothing rather than guessing.
+ *
+ * @module
  */
 
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { createHash } from 'node:crypto'
 import { ASSET_SLOTS } from '@uniweb/semantic-parser'
-import { join } from 'node:path'
-
-export const ASSET_MAP_FILE = 'assets.json'
-
-/** Current on-disk shape. Bumped only for a breaking layout change. */
-const VERSION = 1
-
-const mapPath = (siteDir) => join(siteDir, ASSET_MAP_FILE)
-
-/**
- * Read the site's asset map. A missing, unreadable or malformed file reads as
- * empty rather than throwing: the map is an accelerator and a record, and a
- * corrupt one must never be the reason a push fails. The next write repairs it.
- *
- * @param {string} siteDir
- * @returns {Record<string, { id: string, ext: string }>} local ref → identity
- */
-export function readAssetMap(siteDir) {
-  const p = mapPath(siteDir)
-  if (!existsSync(p)) return {}
-  try {
-    const parsed = JSON.parse(readFileSync(p, 'utf8'))
-    const assets = parsed?.assets
-    if (!assets || typeof assets !== 'object') return {}
-    const out = {}
-    for (const [ref, v] of Object.entries(assets)) {
-      if (v && typeof v.id === 'string' && v.id) {
-        out[ref] = { id: v.id, ext: typeof v.ext === 'string' ? v.ext : '' }
-        if (typeof v.served === 'string' && v.served) out[ref].served = v.served
-      }
-    }
-    return out
-  } catch {
-    return {}
-  }
-}
-
-/**
- * Merge `entries` into the site's map and write it if anything changed.
- *
- * MERGE, not replace: a push carries only the refs that page's content touched,
- * so replacing would drop every asset this run happened not to mention — which
- * is most of them on a partial push. An entry whose id changed is overwritten
- * (the bytes at that path changed); an identical entry is left alone.
- *
- * @param {string} siteDir
- * @param {Record<string, { id: string, ext: string }>} entries
- * @returns {{ added: string[], changed: string[], written: boolean }}
- */
-export function updateAssetMap(siteDir, entries) {
-  const prior = readAssetMap(siteDir)
-  const added = []
-  const changed = []
-
-  for (const [ref, v] of Object.entries(entries || {})) {
-    if (!v?.id) continue
-    const was = prior[ref]
-    // A new `served` fingerprint is a change too: the host serves these bytes at
-    // another address now, and the old fingerprint would stop recognizing it. An
-    // entry that carries none — a download learns identity, not an upload's URL —
-    // keeps the one already recorded for the same bytes.
-    const served = v.served || (was && was.id === v.id ? was.served : undefined)
-    if (!was) added.push(ref)
-    else if (was.id !== v.id || (served || '') !== (was.served || '')) changed.push(ref)
-    else continue
-    prior[ref] = { id: v.id, ext: v.ext || '', ...(served ? { served } : {}) }
-  }
-
-  if (!added.length && !changed.length) return { added, changed, written: false }
-
-  // Sorted keys + a trailing newline: a committed file that reorders itself
-  // produces a diff on every push and teaches people to skip reading it.
-  const assets = {}
-  for (const ref of Object.keys(prior).sort()) assets[ref] = prior[ref]
-  writeFileSync(
-    mapPath(siteDir),
-    JSON.stringify({ version: VERSION, assets }, null, 2) + '\n'
-  )
-  return { added, changed, written: true }
-}
-
-/**
- * The local ref a given asset id is known at, or null.
- *
- * This is the direction `pull` needs and the reason the map is worth
- * committing: stored content carries an id, and only this can say the author
- * called it `/images/hero.png`. Without it a pull must invent a path.
- *
- * @param {Record<string, { id: string, ext: string }>} map
- * @param {string} id
- * @returns {string|null}
- */
-export function refForAssetId(map, id) {
-  if (!id) return null
-  for (const [ref, v] of Object.entries(map || {})) {
-    if (v.id === id) return ref
-  }
-  return null
-}
 
 /**
- * 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

@@ -318,13 +318,21 @@ 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[] }}
+ * @returns {{ updated: string[], unchanged: string[], deferred: object[], warnings: string[], mapped: Object<string,string> }}
+ *   `mapped` is own id → the uuid this backend minted, for the caller to record per backend.
  */
 export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
   const updated = []
   const unchanged = []
   const deferred = []
   const warnings = []
+  // ⭐ own id → the uuid THIS backend minted. The caller files it under the backend in
+  // `sync.json::backends.<origin>.records`; this function knows no backend.
+  const mapped = {}
+  // Files holding only records that already carry their own id. Counted ONCE per file
+  // at the end: an array-form file holds several records, and "examined, nothing
+  // written" is a statement about the file, not about each record in it.
+  const ownIdFiles = new Set()
   // 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)
@@ -338,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
@@ -347,6 +355,22 @@ export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
       deferred.push({ index: i, id: entry.id, reason: 'no source file on disk' })
       continue
     }
+
+    // ⭐ Every record the backend returned is mapped: own id → the uuid it minted.
+    // A record new to EVERY backend has no own id yet, so the minted uuid becomes it
+    // (written below) and the mapping is identity — which is exactly the behaviour
+    // before identity was keyed by backend, so a single-backend project is unchanged.
+    mapped[entry.ownId || uuid] = uuid
+
+    // ⛔ A record that already carries its OWN id is NOT rewritten. Its id is stable
+    // and travels with the file; this backend's uuid belongs in the map, not in the
+    // author's file. And it must not be: variant A below re-renders the WHOLE file from
+    // the backend's document, which carries THIS backend's `$uuid` — so a second
+    // backend would silently overwrite the record's identity with its own.
+    if (entry.ownId) {
+      ownIdFiles.add(entry.sourceFile)
+      continue
+    }
     if (entry.multiRecord) {
       // Many records in one file → group by file, written once. BibTeX and
       // array-form YAML/JSON both re-render canonically (sync owns the output);
@@ -405,5 +429,8 @@ export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
     else warnings.push(`${file}: ${res.message}`)
   }
 
-  return { updated, unchanged, deferred, warnings }
+  for (const file of ownIdFiles) {
+    if (!updated.includes(file) && !unchanged.includes(file)) unchanged.push(file)
+  }
+  return { updated, unchanged, deferred, warnings, mapped }
 }

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