uniweb 0.59.1 → 0.60.0

package/src/backend/site-sync.js

@@ -11,11 +11,10 @@
  * own way.
  */
 
-import { writeFileSync, readFileSync, mkdirSync } from 'node:fs'
+import { writeFileSync, readFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import yaml from 'js-yaml'
 import { hasUncommittedContent } from '../utils/git.js'
-import { recordSiteBackend } from '../utils/site-identity.js'
 import { humanBytes } from '../utils/bytes.js'
 import { isAuthoredPreview } from '../utils/preview.js'
 import {
@@ -30,7 +29,10 @@ import {
   collectUnitUuids,
   collectFolderItemUuids,
   collectQueryUuids,
-  readAssetMap,
+  readBackendState,
+  updateBackendMap,
+  clearBackendSections,
+  normalizeBackendOrigin,
   removeYamlScalar
 } from '@uniweb/build/uwx'
 
@@ -75,7 +77,7 @@ async function explainStaleSiteContent({ client, siteDir, localBuffer, uuid }) {
     const localDoc = entityDocFromUwx(localBuffer)
     if (!remoteDoc || !localDoc) return []
     return describeSiteDiff(
-      diffSiteUnits(localDoc, remoteDoc, readUnitBases(siteDir))
+      diffSiteUnits(localDoc, remoteDoc, readUnitBases(siteDir, client.origin))
     )
   } catch {
     return []
@@ -173,36 +175,100 @@ export function makeModelResolver({ client, offline = false }) {
   }
 }
 
-// "Send only changed" cache: content hashes from the last successful sync, keyed
-// `<model> <id>`. Gitignored, per-clone, deletable (a deleted cache just means one full
-// re-sync, which the backend then no-ops). NOT identity — the minted `$uuid` lives in
-// the source files; this is a pure wire-efficiency cache.
-function syncCachePath(siteDir) {
-  return join(siteDir, '.uniweb', 'sync-cache.json')
+// `.uniweb/backend-cache.json` — what a backend had and what we last sent it, so the
+// next transfer can skip work. Gitignored, per clone, safe to delete.
+//
+// ⭐ **Everything here is regenerable and losing it never produces a WRONG result** —
+// only a slower transfer or a round trip. That is the membership test; anything
+// failing it belongs in `sync.json` (which is where the uuid maps went on
+// 2026-09-20 — see `readItemUuids` below).
+//
+// ⚠️ It was `sync-cache.json` and its header called it "a pure wire-efficiency
+// cache — NOT identity, the minted `$uuid` lives in the source files". That was
+// true of `hashes`, which it was written for, and the uuid maps were added later
+// under the same sentence without anyone revisiting it. They were backend-minted
+// identity in a cache, and the `queryUuids` docblock one screen below said so.
+//
+// ⛔ **Keyed by backend ORIGIN.** Every map describes ONE backend: hashes are what we
+// last sent *to it*, base versions are the versions *it* had. Shared across backends
+// they report every entity as changed against the second one.
+//
+// Spec: kb/framework/reference/backend-cache-json.md
+function backendCachePath(siteDir) {
+  return join(siteDir, '.uniweb', 'backend-cache.json')
 }
-function readSyncCacheFile(siteDir) {
+function readCacheFile(siteDir) {
   try {
-    const obj = JSON.parse(readFileSync(syncCachePath(siteDir), 'utf8'))
-    return obj && typeof obj === 'object' ? obj : {}
+    const obj = JSON.parse(readFileSync(backendCachePath(siteDir), 'utf8'))
+    return obj && typeof obj === 'object' && obj.backends ? obj : { backends: {} }
   } catch {
-    return {} // missing / unreadable → treat everything as changed
+    return { backends: {} } // missing / unreadable → treat everything as changed
   }
 }
+const cacheKeyFor = (backend) => normalizeBackendOrigin(backend) || ''
+function readSyncCacheFile(siteDir, backend) {
+  const key = cacheKeyFor(backend)
+  if (!key) return {}
+  const section = readCacheFile(siteDir).backends[key]
+  return section && typeof section === 'object' ? section : {}
+}
 // The cache holds several maps written on DIFFERENT events — content hashes and the
 // injections that produced them on a successful push, base versions on push AND
 // pull, unit hashes on push and pull — so every writer must preserve the ones it
 // isn't touching. One merge point rather than a hand-rolled preserve per writer,
 // because getting that wrong silently disarms whichever map got clobbered.
-function updateSyncCache(siteDir, patch) {
-  const p = syncCachePath(siteDir)
+function updateSyncCache(siteDir, backend, patch) {
+  const key = cacheKeyFor(backend)
+  // ⛔ No backend, no cache. Writing under a blank key would pool every backend's
+  // state into one section, which is the bug this keying exists to remove.
+  if (!key) return
+  const p = backendCachePath(siteDir)
   mkdirSync(dirname(p), { recursive: true })
-  const prior = readSyncCacheFile(siteDir)
-  const out = { version: 1, ...prior, ...patch }
-  delete out.version
-  writeFileSync(p, JSON.stringify({ version: 1, ...out }, null, 2) + '\n')
+  const file = readCacheFile(siteDir)
+  file.backends[key] = { ...(file.backends[key] || {}), ...patch }
+  const sorted = {}
+  for (const k of Object.keys(file.backends).sort()) sorted[k] = file.backends[k]
+  writeFileSync(p, JSON.stringify({ version: 1, backends: sorted }, null, 2) + '\n')
+}
+/**
+ * Remove ONE backend's section from `.uniweb/backend-cache.json`. Every other
+ * backend's section is untouched — which is the point of keying by origin.
+ *
+ * @returns {boolean} whether a section was removed
+ */
+export function forgetBackendCache(siteDir, backend) {
+  const key = cacheKeyFor(backend)
+  if (!key) return false
+  const file = readCacheFile(siteDir)
+  if (!file.backends[key]) return false
+  delete file.backends[key]
+  const p = backendCachePath(siteDir)
+  // The last section gone ⇒ the file goes, as `sync.json` does in the same case.
+  if (!Object.keys(file.backends).length) {
+    unlinkSync(p)
+    return true
+  }
+  const sorted = {}
+  for (const k of Object.keys(file.backends).sort()) sorted[k] = file.backends[k]
+  writeFileSync(p, JSON.stringify({ version: 1, backends: sorted }, null, 2) + '\n')
+  return true
+}
+
+/**
+ * Delete `.uniweb/backend-cache.json` outright — `uniweb forget --all`. Every section
+ * describes a site the COPY does not own; the file is regenerable by definition.
+ *
+ * @returns {boolean} whether there was a file to remove
+ */
+export function forgetAllBackendCaches(siteDir) {
+  const p = backendCachePath(siteDir)
+  if (!existsSync(p)) return false
+  unlinkSync(p)
+  return true
 }
-const readMap = (siteDir, key) => {
-  const v = readSyncCacheFile(siteDir)[key]
+
+const readMap = (siteDir, backend, key) => {
+  const v = readSyncCacheFile(siteDir, backend)[key]
   return v && typeof v === 'object' ? v : {}
 }
 
@@ -214,8 +280,8 @@ const readMap = (siteDir, key) => {
  * content hashes, the injections those hashes were taken over, entity base versions,
  * unit bases — and a unit path (`site.yml`, `pages/about/about.md`) is the same
  * string for every site. So the cache does not
- * self-invalidate when `site.yml::$uuid` goes away: it keeps describing the site
- * this folder used to be.
+ * self-invalidate when the site's uuid goes away (a delete in the app, or
+ * `uniweb forget`): it keeps describing the site this folder used to be.
  *
  * Which is a state we ACTIVELY TELL PEOPLE TO ENTER. The 404 guidance on a
  * uuid-bound lane says to clear `$uuid` to re-publish as a new site — the documented
@@ -241,21 +307,12 @@ const readMap = (siteDir, key) => {
  * guard and the `item_uuid_conflict` recovery — the guard decides WHETHER, this
  * decides WHAT, and they must not drift.
  */
-export function clearRemoteSyncState(siteDir, siteUuid = null) {
-  const prior = readSyncCacheFile(siteDir)
-  const dropped = [
-    'itemUuids',
-    'queryUuids',
-    'hashes',
-    'baseVersions',
-    'unitBases',
-    'applied'
-  ].filter((k) => prior[k] && Object.keys(prior[k]).length)
-  updateSyncCache(siteDir, {
-    itemUuids: {},
-    // Remote-derived exactly like itemUuids — it holds the OLD site's collection
-    // ids, and surviving the drop it would offer them for the new site's sections.
-    queryUuids: {},
+export function clearRemoteSyncState(siteDir, backend, siteUuid = null) {
+  const prior = readSyncCacheFile(siteDir, backend)
+  const dropped = ['hashes', 'baseVersions', 'unitBases', 'applied'].filter(
+    (k) => prior[k] && Object.keys(prior[k]).length
+  )
+  updateSyncCache(siteDir, backend, {
     hashes: {},
     baseVersions: {},
     unitBases: {},
@@ -265,19 +322,40 @@ export function clearRemoteSyncState(siteDir, siteUuid = null) {
     applied: {},
     siteUuid: siteUuid || null
   })
-  return dropped
+  // ⛔ THE IDENTITY MAPS ARE CLEARED WITH THE REST, and must be. They live in
+  // `sync.json` now rather than the cache, but they describe the same dead site:
+  // leaving them behind is what makes the backend refuse — "item uuid … is already
+  // stored on entity N; cross-entity move is not supported" — on the very next push.
+  // Two files, one invalidation.
+  const identity = clearBackendSections(siteDir, backend, [
+    'items',
+    'queries',
+    'folders'
+  ])
+  // Reported under the names the cache used, so the message a user sees is the same
+  // one it always was.
+  const NAMED = { items: 'itemUuids', queries: 'queryUuids', folders: 'folderItemUuids' }
+  return [...dropped, ...identity.map((k) => NAMED[k])]
 }
 
-export function clearRemoteSyncStateIfUnbound(siteDir) {
-  let current = null
-  try {
-    const y = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))
-    if (typeof y?.$uuid === 'string') current = y.$uuid
-  } catch {
-    /* unreadable site.yml — treat as unbound and clear, which is the safe side */
-  }
+export function clearRemoteSyncStateIfUnbound(siteDir, backend) {
+  // ⭐ "Bound" is a question about THIS backend: the identity is `sync.json`'s, keyed
+  // by origin. A project bound on one backend and not another is an ordinary state
+  // now, not a contradiction — which is why the stamp below still earns its keep even
+  // though cross-backend confusion became unrepresentable. What it still catches is a
+  // site DELETED on this backend and re-created: same origin, new uuid.
+  const current = readBackendState(siteDir, backend).site?.uuid || null
 
-  const prior = readSyncCacheFile(siteDir)
+  const prior = readSyncCacheFile(siteDir, backend)
+  // ⛔ TWO FILES, ONE QUESTION. The cache holds the speed-ups and `sync.json` holds
+  // the identity maps, but "is any of this describing a site this clone is not
+  // working with?" is asked of BOTH — a clone whose only stale state is identity is
+  // exactly the one the backend refuses on the next push.
+  const identityPrior = {
+    itemUuids: readItemUuids(siteDir, backend),
+    queryUuids: readQueryUuids(siteDir, backend),
+    folderItemUuids: readFolderItemUuids(siteDir, backend)
+  }
   const REMOTE_MAPS = [
     'itemUuids',
     'hashes',
@@ -285,15 +363,16 @@ export function clearRemoteSyncStateIfUnbound(siteDir) {
     'unitBases',
     'applied'
   ]
+  const lookup = { ...prior, ...identityPrior }
   const populated = REMOTE_MAPS.filter(
-    (k) => prior[k] && Object.keys(prior[k]).length
+    (k) => lookup[k] && Object.keys(lookup[k]).length
   )
   if (!populated.length) {
     // Nothing to invalidate, but still stamp identity so a LATER divergence is
     // detectable. A cache that never records its site can only be checked by the
     // unbound rule, which misses the bound-but-wrong case below.
     if (current && prior.siteUuid !== current) {
-      updateSyncCache(siteDir, { siteUuid: current })
+      updateSyncCache(siteDir, backend, { siteUuid: current })
     }
     return []
   }
@@ -316,12 +395,12 @@ export function clearRemoteSyncStateIfUnbound(siteDir) {
     !current || (prior.siteUuid && prior.siteUuid !== current) ? populated : []
   if (!stale.length) {
     if (current && prior.siteUuid !== current) {
-      updateSyncCache(siteDir, { siteUuid: current })
+      updateSyncCache(siteDir, backend, { siteUuid: current })
     }
     return []
   }
 
-  clearRemoteSyncState(siteDir, current)
+  clearRemoteSyncState(siteDir, backend, current)
   return stale
 }
 
@@ -345,7 +424,7 @@ export function clearRemoteSyncStateIfUnbound(siteDir) {
  * @param {string} siteDir
  * @returns {string[]} the keys removed
  */
-export function dropSiteBoundValues(siteDir) {
+export function dropSiteBoundValues(siteDir, backend) {
   const file = join(siteDir, 'site.yml')
   let y
   try {
@@ -353,7 +432,12 @@ export function dropSiteBoundValues(siteDir) {
   } catch {
     return []
   }
-  if (!y || typeof y !== 'object' || typeof y.$uuid === 'string') return []
+  // ⛔ "Bound" is a question about THIS backend, answered by sync.json. This read
+  // `site.yml::$uuid` until 2026-09-20 and kept doing so after step 4 moved the key —
+  // so every project read as unbound and every push stripped a bound site's
+  // generated preview. A write, from a stale read, with nothing to notice it.
+  if (!y || typeof y !== 'object') return []
+  if (readBackendState(siteDir, backend).site?.uuid) return []
   const dropped = []
   if (
     y.preview !== undefined &&
@@ -365,8 +449,8 @@ export function dropSiteBoundValues(siteDir) {
   return dropped
 }
 
-export function readSyncCache(siteDir) {
-  return readMap(siteDir, 'hashes')
+export function readSyncCache(siteDir, backend) {
+  return readMap(siteDir, backend, 'hashes')
 }
 
 /**
@@ -398,8 +482,8 @@ export function readSyncCache(siteDir) {
  * keeps `assets.json` id-only. An asset genuinely new to the site has no recorded
  * mapping and still reads as changed, which is correct.
  */
-export function readAppliedInjections(siteDir) {
-  return readMap(siteDir, 'applied')
+export function readAppliedInjections(siteDir, backend) {
+  return readMap(siteDir, backend, 'applied')
 }
 
 /**
@@ -412,9 +496,9 @@ export function readAppliedInjections(siteDir) {
  * `assetIds` is dropped rather than stored — see readAppliedInjections: it has a
  * committed source of truth in `assets.json`, and the reader re-derives it there.
  */
-export function writeSyncCache(siteDir, hashes, applied) {
+export function writeSyncCache(siteDir, backend, hashes, applied) {
   const { assetIds: _inAssetsJson, ...bankable } = applied || {}
-  updateSyncCache(siteDir, { hashes, applied: bankable })
+  updateSyncCache(siteDir, backend, { hashes, applied: bankable })
 }
 
 /**
@@ -431,8 +515,8 @@ export function writeSyncCache(siteDir, hashes, applied) {
  * post-write `finalized[].version` the backend returns. Without the push half a
  * second consecutive push would be stale by construction and refused.
  */
-export function readBaseVersions(siteDir) {
-  return readMap(siteDir, 'baseVersions')
+export function readBaseVersions(siteDir, backend) {
+  return readMap(siteDir, backend, 'baseVersions')
 }
 
 /**
@@ -447,19 +531,19 @@ export function readBaseVersions(siteDir) {
  * reports tokens for a subset of the site. Replacing would drop the tokens of every
  * record that wasn't in this package and silently degrade those to ungated.
  */
-export function readItemBaseVersions(siteDir) {
-  return readMap(siteDir, 'itemBaseVersions')
+export function readItemBaseVersions(siteDir, backend) {
+  return readMap(siteDir, backend, 'itemBaseVersions')
 }
-export function mergeItemBaseVersions(siteDir, versions) {
+export function mergeItemBaseVersions(siteDir, backend, versions) {
   if (!versions || !Object.keys(versions).length) return
-  updateSyncCache(siteDir, {
+  updateSyncCache(siteDir, backend, {
     itemBaseVersions: { ...readItemBaseVersions(siteDir), ...versions }
   })
 }
-export function mergeBaseVersions(siteDir, versions) {
+export function mergeBaseVersions(siteDir, backend, versions) {
   if (!versions || !Object.keys(versions).length) return
-  updateSyncCache(siteDir, {
-    baseVersions: { ...readBaseVersions(siteDir), ...versions }
+  updateSyncCache(siteDir, backend, {
+    baseVersions: { ...readBaseVersions(siteDir, backend), ...versions }
   })
 }
 
@@ -503,8 +587,8 @@ export function mergeBaseVersions(siteDir, versions) {
  * refuses an all-blank `multi` section, so a producer that skips that step fails
  * loudly instead of quietly rebuilding the site's identity.
  */
-export function readItemUuids(siteDir) {
-  return readMap(siteDir, 'itemUuids')
+export function readItemUuids(siteDir, backend) {
+  return readBackendState(siteDir, backend).items || {}
 }
 /**
  * Placement identity for the site's `@uniweb/folder` — path chain → `$uuid`.
@@ -513,8 +597,8 @@ export function readItemUuids(siteDir) {
  * different trees: `pages/…/page.yml` there, `members/alice` here. One map with
  * two key languages is a map nobody can validate.
  */
-export function readFolderItemUuids(siteDir) {
-  return readMap(siteDir, 'folderItemUuids')
+export function readFolderItemUuids(siteDir, backend) {
+  return readBackendState(siteDir, backend).folders || {}
 }
 
 /**
@@ -535,20 +619,25 @@ export function readFolderItemUuids(siteDir) {
  * its own join key. ⛔ Not `$id`: it holds the same string but is a payload-local
  * handle the backend skips on parse and never stores.
  */
-export function readQueryUuids(siteDir) {
-  return readMap(siteDir, 'queryUuids')
+export function readQueryUuids(siteDir, backend) {
+  return readBackendState(siteDir, backend).queries || {}
 }
-export function writeQueryUuids(siteDir, map) {
+// ⭐ THE THREE UUID MAPS LIVE IN `sync.json`, NOT THE CACHE (2026-09-20). They are
+// backend-minted identity: without them a push re-sends a section uuid-less and the
+// backend refuses an all-blank section over stored rows rather than replacing every
+// one. A refusal is the good case; the bad one is duplication. Losing them costs a
+// round trip, not a slow push — which is the line between the two files.
+export function writeQueryUuids(siteDir, backend, map) {
   if (!map || !Object.keys(map).length) return
-  updateSyncCache(siteDir, { queryUuids: map })
+  updateBackendMap(siteDir, backend, 'queries', map)
 }
-export function writeFolderItemUuids(siteDir, map) {
+export function writeFolderItemUuids(siteDir, backend, map) {
   if (!map || !Object.keys(map).length) return
-  updateSyncCache(siteDir, { folderItemUuids: map })
+  updateBackendMap(siteDir, backend, 'folders', map)
 }
-export function writeItemUuids(siteDir, map) {
+export function writeItemUuids(siteDir, backend, map) {
   if (!map || !Object.keys(map).length) return
-  updateSyncCache(siteDir, { itemUuids: map })
+  updateBackendMap(siteDir, backend, 'items', map)
 }
 
 /**
@@ -564,16 +653,9 @@ export function writeItemUuids(siteDir, map) {
  * @param {string} siteDir
  * @returns {string|null}
  */
-export function readSiteOrg(siteDir) {
-  try {
-    const y = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))
-    const h = y && typeof y === 'object' ? y.$org : null
-    return typeof h === 'string' && h.trim()
-      ? `@${h.trim().replace(/^@/, '')}`
-      : null
-  } catch {
-    return null
-  }
+export function readSiteOrg(siteDir, backend) {
+  const org = readBackendState(siteDir, backend).site?.org
+  return typeof org === 'string' && org ? `@${org.replace(/^@/, '')}` : null
 }
 
 /**
@@ -588,14 +670,14 @@ export function readSiteOrg(siteDir) {
  * @param {string|null|undefined} asOrg - the `--as-org` value, `@handle` or bare
  * @returns {string|null}
  */
-function recordSiteOrg(siteDir, asOrg) {
+function recordSiteOrg(siteDir, backend, asOrg) {
   const handle = String(asOrg || '')
     .replace(/^@/, '')
     .replace(/\/.*$/, '')
     .trim()
   if (!handle) return null
   try {
-    writeSiteOrg(siteDir, handle)
+    writeSiteOrg(siteDir, backend, handle)
     return `@${handle}`
   } catch {
     // The uuid is the load-bearing back-fill; losing the org note must never
@@ -648,19 +730,13 @@ export async function resolveSiteOrgForCreate({
   if (flag) return { asOrg: flag }
   if (personal) return { asOrg: null }
 
-  const recorded = readSiteOrg(siteDir)
+  const recorded = readSiteOrg(siteDir, client?.origin)
   if (recorded) return { asOrg: recorded }
 
-  // Already created ⇒ nothing to decide. This is what keeps every existing site
-  // silent: ownership was settled at its create, and re-asking would be theatre.
-  let siteYml = {}
-  try {
-    const y = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))
-    if (y && typeof y === 'object') siteYml = y
-  } catch {
-    /* unreadable — treat as un-created and let the resolution below decide */
-  }
-  if (typeof siteYml.$uuid === 'string') return { asOrg: null }
+  // Already created ⇒ nothing to decide: ownership was settled at its create and
+  // re-asking would be theatre. ⭐ "Created" is a question about THIS backend now —
+  // the same project may be brand new on one and long-established on another.
+  if (readBackendState(siteDir, client?.origin).site?.uuid) return { asOrg: null }
 
   // An offline preview (`--dry-run` / `-o`) must never authenticate, and it is
   // creating nothing, so there is no decision to force. Say what is unresolved
@@ -825,8 +901,8 @@ function describeCreateRefusal(body) {
  * keep and can be cleared. (The reverse ordering was justified by a claim that
  * `ensureItemUuids` mints on the backend, which it does not — see push.js.)
  *
- * A no-op when `site.yml::$uuid` is already set, so only the first publish of a
- * site pays for it. The uuid is written back immediately, keeping the window in
+ * A no-op when the site already has a uuid on this backend (sync.json), so only the
+ * first publish of a site pays for it. The uuid is written back immediately, keeping the window in
  * which a crash could strand a site as small as one file write.
  *
  * @returns {Promise<{ uuid: string|null, created: boolean, reason?: string }>}
@@ -852,8 +928,9 @@ export async function ensureSiteExists({
   } catch {
     /* unreadable site.yml — treat as un-synced and let the create decide */
   }
-  if (typeof siteYml.$uuid === 'string') {
-    return { uuid: siteYml.$uuid, created: false, org: readSiteOrg(siteDir) }
+  const known = readBackendState(siteDir, client.origin).site?.uuid
+  if (known) {
+    return { uuid: known, created: false, org: readSiteOrg(siteDir, client.origin) }
   }
 
   // Both are required by the create. Catching it here turns a 400 into a sentence
@@ -905,11 +982,11 @@ export async function ensureSiteExists({
       reason: 'the create returned no site uuid'
     }
   }
-  writeSiteEntityUuid(siteDir, minted)
+  writeSiteEntityUuid(siteDir, client.origin, minted)
   // Stamp the cache with the site it now describes, so a push that fails after
   // this point cannot leave a cache pointing at a different site with no way to
   // detect it.
-  updateSyncCache(siteDir, { siteUuid: minted })
+  updateSyncCache(siteDir, client.origin, { siteUuid: minted })
   const org = await recordAndDescribeOwner({
     client,
     siteDir,
@@ -943,23 +1020,16 @@ async function recordAndDescribeOwner({
   const echoed = payload && 'org' in payload ? payload.org : undefined
   const owner =
     echoed === undefined ? asOrg : typeof echoed === 'string' ? echoed : null
-  const org = recordSiteOrg(siteDir, owner)
-
-  // The SYNC SCOPE, recorded here for the same reason `$org` is: this function is the
-  // one place BOTH create paths meet (`ensureSiteExists` for a site with local media,
-  // the content-lane create for one without). Recording it at either call site instead
-  // would make `$backend` present or absent depending on whether the site happens to
-  // have images — the exact drift the comment at the second call site warns about.
-  //
-  // A no-op on the default backend, so the common case writes nothing.
-  const scope = await recordSiteBackend(siteDir, client.origin)
-  if (scope)
-    note?.(`Bound this project to ${scope} (recorded $backend in site.yml).`)
+  const org = recordSiteOrg(siteDir, client.origin, owner)
 
+  // ⛔ No sync scope to record. It WAS `site.yml::$backend`, written here because this
+  // function is the one place both create paths meet. The scope is now the KEY the
+  // identity is stored under (`sync.json::backends.<origin>`), so recording it
+  // separately would be recording the name of the drawer inside the drawer.
   note?.(
     org
-      ? `Created the site on the backend under ${org} (recorded $uuid + $org in site.yml).`
-      : `Created the site on the backend, owned personally (recorded $uuid in site.yml).`
+      ? `Created the site on ${client.origin} under ${org} — recorded in sync.json.`
+      : `Created the site on ${client.origin}, owned personally — recorded in sync.json.`
   )
 
   // What the create echoed about this site's OWNER, and nothing beyond it.
@@ -1000,17 +1070,13 @@ async function recordAndDescribeOwner({
  * @returns {Promise<Object<string,string>>} the map (possibly empty)
  */
 export async function ensureItemUuids({ client, siteDir, note }) {
-  const cached = readItemUuids(siteDir)
+  const cached = readItemUuids(siteDir, client.origin)
   if (Object.keys(cached).length) return cached
   // A site that has never been pushed has no identity to recover — and nothing to
   // lose, since every item is genuinely new.
-  let siteContentUuid = null
-  try {
-    const y = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))
-    siteContentUuid = typeof y?.$uuid === 'string' ? y.$uuid : null
-  } catch {
-    /* unreadable site.yml — nothing to recover against */
-  }
+  // The site to recover identity against — this backend's, from sync.json. It read
+  // `site.yml::$uuid`, so after step 4 it found nothing and never recovered.
+  const siteContentUuid = readBackendState(siteDir, client.origin).site?.uuid || null
   if (!siteContentUuid) return cached
   try {
     const res = await client.pullSiteContent(siteContentUuid)
@@ -1019,7 +1085,7 @@ export async function ensureItemUuids({ client, siteDir, note }) {
     if (!doc) return cached
     const harvested = collectUnitUuids(doc)
     if (Object.keys(harvested).length) {
-      writeItemUuids(siteDir, harvested)
+      writeItemUuids(siteDir, client.origin, harvested)
       note?.(
         `Recovered identity for ${Object.keys(harvested).length} item(s) from the backend.`
       )
@@ -1032,14 +1098,14 @@ export async function ensureItemUuids({ client, siteDir, note }) {
   }
 }
 
-export function readUnitBases(siteDir) {
-  const v = readMap(siteDir, 'unitBases')
+export function readUnitBases(siteDir, backend) {
+  const v = readMap(siteDir, backend, 'unitBases')
   return { local: v.local || {}, remote: v.remote || {} }
 }
-export function writeUnitBases(siteDir, patch) {
+export function writeUnitBases(siteDir, backend, patch) {
   if (!patch) return
-  updateSyncCache(siteDir, {
-    unitBases: { ...readUnitBases(siteDir), ...patch }
+  updateSyncCache(siteDir, backend, {
+    unitBases: { ...readUnitBases(siteDir, backend), ...patch }
   })
 }
 
@@ -1055,8 +1121,8 @@ export function writeUnitBases(siteDir, patch) {
  * @param {string} siteDir
  * @returns {Promise<{ changed: number, unchanged: number, warnings: string[] }>}
  */
-export async function probeUnpushed(siteDir, { sendAll = false } = {}) {
-  const priorHashes = readSyncCache(siteDir)
+export async function probeUnpushed(siteDir, { backend = null, sendAll = false } = {}) {
+  const priorHashes = readSyncCache(siteDir, backend)
   // Re-emit the document the last push HASHED, not the one the author wrote — see
   // readAppliedInjections. Two sources, on purpose:
   //   · BANKED — the serve URLs and pinned refs only a round-trip produces. Empty
@@ -1083,7 +1149,7 @@ export async function probeUnpushed(siteDir, { sendAll = false } = {}) {
   // and others never settling, which reads like a content problem rather than a
   // resolution one. Measured on matinee 2026-08-29: `status` reported 4 changed
   // immediately after a successful push; passing the org took it to 1.
-  const pkg = await comparisonEmit(siteDir, { priorHashes, sendAll })
+  const pkg = await comparisonEmit(siteDir, { backend, priorHashes, sendAll })
   const changed =
     (pkg.siteContent?.entityCount || 0) + (pkg.records?.entityCount || 0)
   return { changed, unchanged: pkg.skipped || 0, warnings: pkg.warnings || [] }
@@ -1110,13 +1176,17 @@ export async function probeUnpushed(siteDir, { sendAll = false } = {}) {
  */
 async function comparisonEmit(
   siteDir,
-  { priorHashes = {}, sendAll = false } = {}
+  { backend = null, priorHashes = {}, sendAll = false } = {}
 ) {
-  const applied = readAppliedInjections(siteDir)
-  const assetIds = readAssetMap(siteDir)
-  const org = readSiteOrg(siteDir)
+  const applied = readAppliedInjections(siteDir, backend)
+  // ⛔ Per backend: an asset id is minted by one and means nothing to another, so a
+  // comparison against the wrong one reports every media ref as changed. Absent is
+  // honest rather than a default — no backend, no known ids.
+  const assetIds = backend ? readBackendState(siteDir, backend).assets || {} : {}
+  const org = readSiteOrg(siteDir, backend)
   const queryUuids = readQueryUuids(siteDir)
   return emitSyncPackages(siteDir, {
+    backend,
     resolveModel: makeModelResolver({ client: null, offline: true }),
     priorHashes,
     sendAll,
@@ -1148,9 +1218,9 @@ async function comparisonEmit(
  * on-disk state IS the agreed state: it came from the backend. A push with no edits
  * in between should send nothing, and clearing would make it send everything.
  */
-export async function rebankSyncHashes(siteDir) {
-  const pkg = await comparisonEmit(siteDir, { sendAll: true })
-  writeSyncCache(siteDir, pkg.hashes || {}, pkg.applied || {})
+export async function rebankSyncHashes(siteDir, backend = null) {
+  const pkg = await comparisonEmit(siteDir, { backend, sendAll: true })
+  writeSyncCache(siteDir, backend, pkg.hashes || {}, pkg.applied || {})
   return Object.keys(pkg.hashes || {}).length
 }
 
@@ -1204,7 +1274,7 @@ export async function pushSyncPackages({
       res = await doRequest()
     } catch (err) {
       error(`Could not reach the backend at ${client.origin}: ${err.message}`)
-      note('Set the origin with --backend <url> or UNIWEB_REGISTER_URL.')
+      note('Is that the backend you meant? Switch with: uniweb login --backend <url>')
       return null
     }
     if (!res.ok) {
@@ -1231,7 +1301,7 @@ export async function pushSyncPackages({
       // an unstamped legacy cache on a bound site, which the guard deliberately
       // leaves alone rather than wiping every existing clone. This is the exit.
       if (problem?.reason === 'item_uuid_conflict') {
-        const dropped = clearRemoteSyncState(siteDir, boundUuid)
+        const dropped = clearRemoteSyncState(siteDir, client.origin, boundUuid)
         error(
           `${label} push refused — this copy's sync cache is describing a different site.`
         )
@@ -1344,7 +1414,7 @@ export async function pushSyncPackages({
       error(`${label} push rejected: HTTP ${res.status} ${res.statusText}`)
       if (res.status === 401 || res.status === 403) {
         note(
-          "Credentials weren't accepted — supply a bearer with --token <bearer> (or UNIWEB_TOKEN)."
+          "Credentials weren't accepted — log in again (`uniweb login --backend <url>`), or check UNIWEB_TOKEN."
         )
       } else if (res.status === 404 && boundUuid) {
         // The clone is bound to a site the backend does not have. There is no CLI
@@ -1356,7 +1426,9 @@ export async function pushSyncPackages({
         // this branch named only the deletion and went straight to "clear `$uuid`" — and
         // that advice, followed for the OTHER cause, destroys a live binding: the site is
         // fine, you are simply pointed at the wrong backend, and clearing the uuid orphans
-        // it. `assertSiteBackendScope` now catches most of that before any request goes
+        // it. (A wrong-BACKEND binding can no longer occur — identity is read per
+        // origin from sync.json — so what reaches here is a site deleted on this backend.)
+        // Before any request goes
         // out, so reaching here usually does mean a deletion; "usually" is not "always"
         // (a project predating `$backend` records no scope to check), which is why the
         // cheap cause is still named before the destructive fix.
@@ -1452,8 +1524,8 @@ export async function pushSyncPackages({
   }
   // Both grains land together, at every point the old code banked the entity one.
   const mergeHarvested = () => {
-    mergeBaseVersions(siteDir, newVersions)
-    mergeItemBaseVersions(siteDir, newItemVersions)
+    mergeBaseVersions(siteDir, client.origin, newVersions)
+    mergeItemBaseVersions(siteDir, client.origin, newItemVersions)
   }
   // The backend's post-write copy of the site-content document, kept for the
   // remote-side unit base (see writeUnitBases).
@@ -1489,7 +1561,8 @@ export async function pushSyncPackages({
       // `collections` section uuid-less and is refused.
       if (siteFinalizedDoc) {
         const recordIds = collectQueryUuids(siteFinalizedDoc)
-        if (Object.keys(recordIds).length) writeQueryUuids(siteDir, recordIds)
+        if (Object.keys(recordIds).length)
+          writeQueryUuids(siteDir, client.origin, recordIds)
       }
       finalizedTotal += finalized.length
     } else {
@@ -1505,8 +1578,8 @@ export async function pushSyncPackages({
         note(JSON.stringify(payload).slice(0, 800))
         return { exitCode: 1, finalizedTotal, wrote }
       }
-      writeSiteEntityUuid(siteDir, minted)
-      updateSyncCache(siteDir, { siteUuid: minted })
+      writeSiteEntityUuid(siteDir, client.origin, minted)
+      updateSyncCache(siteDir, client.origin, { siteUuid: minted })
       boundSiteUuid = minted
       wrote.push('recorded site $uuid in site.yml')
       // The OTHER create path (a media-less push never reaches `ensureSiteExists`,
@@ -1554,12 +1627,18 @@ export async function pushSyncPackages({
     }
     harvest(finalized)
     const bf = backfillEntityUuids({ index: records.index, finalized })
+    // ⭐ Record which uuid THIS backend minted for each record, keyed by the record's
+    // own id. The file keeps that own id; the next push to this backend sends the
+    // mapped uuid, and a push to another backend sends none so that one mints its own.
+    if (bf.mapped && Object.keys(bf.mapped).length) {
+      updateBackendMap(siteDir, client.origin, 'records', bf.mapped)
+    }
     for (const w of bf.warnings) note(`! ${w}`)
     for (const d of bf.deferred) note(`↷ ${d.id ?? `#${d.index}`}: ${d.reason}`)
     if (bf.updated.length)
       wrote.push(`wrote ${bf.updated.length} record file(s)`)
-    // ⭐ BANK THE FOLDER'S PLACEMENT IDENTITY. The records back-fill their own
-    // `$uuid` into their source files (above); the folder's ITEMS have nowhere to
+    // ⭐ BANK THE FOLDER'S PLACEMENT IDENTITY. The records carry their own `$uuid`
+    // in their source files and map it per backend (above); the folder's ITEMS have nowhere to
     // be written, so they are banked here from the document the backend just
     // returned.
     //
@@ -1572,7 +1651,7 @@ export async function pushSyncPackages({
     if (folderDoc) {
       const placements = collectFolderItemUuids(folderDoc)
       if (Object.keys(placements).length)
-        writeFolderItemUuids(siteDir, placements)
+        writeFolderItemUuids(siteDir, client.origin, placements)
     }
     finalizedTotal += finalized.length
   }
@@ -1581,7 +1660,7 @@ export async function pushSyncPackages({
   // then bank the post-write tokens so the NEXT push carries a current base.
   // Entities absent from finalized[] (skipped, or not editable) keep their cached
   // value — absence is not invalidation.
-  writeSyncCache(siteDir, hashes, applied)
+  writeSyncCache(siteDir, client.origin, hashes, applied)
   mergeHarvested()
   // Re-base the page attribution: our emitted document and the backend's post-write
   // copy of it are the two sides' new agreed state. Only when the site-content lane
@@ -1594,12 +1673,12 @@ export async function pushSyncPackages({
     // the stored row — the only remote-side base a push can produce.
     const theirs = siteFinalizedDoc?.pages ? siteFinalizedDoc : null
     if (theirs) patch.remote = computeUnitHashes(theirs)
-    if (Object.keys(patch).length) writeUnitBases(siteDir, patch)
+    if (Object.keys(patch).length) writeUnitBases(siteDir, client.origin, patch)
     // The backend's post-write document carries `$uuid` per item at every nesting
     // level, so the push that just landed also re-arms identity for the next one.
     // Replaced wholesale: an item that no longer exists must not keep a uuid that
     // would re-target something else.
-    if (theirs) writeItemUuids(siteDir, collectUnitUuids(theirs))
+    if (theirs) writeItemUuids(siteDir, client.origin, collectUnitUuids(theirs))
     else {
       // ⛔ BANKING IS BEST-EFFORT AND ITS FAILURE USED TO BE SILENT — say it here,
       // because the cost lands two commands away and names something else.