uniweb 0.59.2 → 0.61.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')
 }
-const readMap = (siteDir, key) => {
-  const v = readSyncCacheFile(siteDir)[key]
+/**
+ * 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, backend, key) => {
+  const v = readSyncCacheFile(siteDir, backend)[key]
   return v && typeof v === 'object' ? v : {}
 }
 
@@ -210,17 +276,17 @@ const readMap = (siteDir, key) => {
  * Drop every cache map that describes a BACKEND site, when this clone is bound to
  * none. Returns the names dropped (empty when there was nothing to do).
  *
- * `.uniweb/sync-cache.json` holds five maps keyed by *unit path* — item uuids,
- * 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
+ * Five maps are keyed by *unit path* — item uuids (`sync.json`'s `items`) and, in
+ * `.uniweb/backend-cache.json`, content hashes, the injections those hashes were
+ * taken over, entity base versions and unit bases — and a unit path (`site.yml`,
+ * `pages/about/about.md`) is the same string for every site. So nothing in them
+ * self-invalidates when the site's uuid goes away: they keep 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
- * recovery after a site is deleted in the app. Following it left the stale maps in
- * place, and the next publish failed two ways:
+ * Which was a state we ACTIVELY TOLD PEOPLE TO ENTER. Until 2026-09-21 the 404
+ * guidance on a uuid-bound lane said to clear `$uuid` to re-publish as a new site —
+ * the documented recovery after a site is deleted in the app. Following it left the
+ * stale maps in place, and the next publish failed two ways:
  *
  *   - **item uuids** — the new site's document carried the OLD site's item
  *     identities, and the backend correctly refused: *"item uuid … is already
@@ -232,6 +298,9 @@ const readMap = (siteDir, key) => {
  *     not change** — a partial site, published successfully, with nothing to
  *     indicate it.
  *
+ * The guidance is `uniweb forget --backend <url>` now, which removes the uuid and the
+ * maps together, so following it no longer leads here.
+ *
  * Call this BEFORE `ensureSiteExists`, which mints a uuid and would otherwise make
  * the clone look bound before the check runs.
  */
@@ -241,21 +310,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 +325,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,26 +366,27 @@ 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 []
   }
 
-  // Two ways the cache can describe a site this clone is not working with:
+  // Two ways the maps can describe a site this clone is not working with:
   //
-  //   1. UNBOUND — no `$uuid` at all, so there is no backend site for any of it to
-  //      be about. This is the state the documented "clear `$uuid` to re-publish as
-  //      a new site" recovery puts you in.
-  //   2. BOUND TO A DIFFERENT SITE — `$uuid` names one site and the cache was
-  //      written for another. Reachable in one step: the create mints a uuid and
+  //   1. UNBOUND — no site uuid for this backend, so there is no backend site for any
+  //      of it to be about. This was the state the old "clear `$uuid` to re-publish
+  //      as a new site" recovery put you in; `uniweb forget` clears the maps with it.
+  //   2. BOUND TO A DIFFERENT SITE — this backend's site uuid names one site and the
+  //      cache was written for another. Reachable in one step: the create mints a uuid and
   //      writes it BEFORE the push, so a push that then fails leaves exactly this.
   //      Without the identity stamp it is invisible, and every later publish fails
   //      the same way with no path out but deleting `.uniweb/` by hand.
@@ -316,12 +398,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 +427,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 +435,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 +452,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')
 }
 
 /**
@@ -374,10 +461,11 @@ export function readSyncCache(siteDir) {
  * exact shape `emitSyncPackages` takes back as opts.
  *
  * ⛔ **Only the ones nothing else records.** `assetIds` is deliberately NOT banked
- * here even though the emit applies it: `assets.json` is COMMITTED project state
- * holding exactly that map (local ref → `{id, ext}`), written by the same push, and
- * a gitignored second copy would be a second thing to disagree — the reason that
- * file itself refuses to hold a serve URL. It also has the worse lifetime of the
+ * here even though the emit applies it: this backend's `assets` in `sync.json` is
+ * COMMITTED project state holding exactly that map (local ref → `{id, ext}`), written
+ * by the same push, and a gitignored second copy would be a second thing to
+ * disagree — the reason that map itself holds a fingerprint of a serve URL and never
+ * the URL. It also has the worse lifetime of the
  * two: `clearRemoteSyncState` wipes this cache, and the committed map correctly
  * survives. ⇒ Bank what a reader cannot re-derive; re-derive the rest.
  *
@@ -395,11 +483,11 @@ export function readSyncCache(siteDir) {
  * zero HTTP requests, a property the cross-client flows rely on). ⚠️ Note the serve
  * URL is REPLAYED, never composed: we re-use the string the host handed us, which is
  * a different act from reconstructing one, and the distinction is the same one that
- * keeps `assets.json` id-only. An asset genuinely new to the site has no recorded
+ * keeps the asset map in `sync.json` to ids and a fingerprint. 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')
 }
 
 /**
@@ -410,11 +498,12 @@ export function readAppliedInjections(siteDir) {
  * leftover from an earlier push describing hashes it no longer matches.
  *
  * `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.
+ * committed source of truth in `sync.json` (this backend's `assets`), and the reader
+ * re-derives it there.
  */
-export function writeSyncCache(siteDir, hashes, applied) {
-  const { assetIds: _inAssetsJson, ...bankable } = applied || {}
-  updateSyncCache(siteDir, { hashes, applied: bankable })
+export function writeSyncCache(siteDir, backend, hashes, applied) {
+  const { assetIds: _inSyncJson, ...bankable } = applied || {}
+  updateSyncCache(siteDir, backend, { hashes, applied: bankable })
 }
 
 /**
@@ -431,8 +520,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 +536,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 +592,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 +602,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,45 +624,45 @@ 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)
 }
 
 /**
  * The org this site was created under, as `@handle`, or null.
  *
- * Read back from `site.yml::$org` (stored bare — see `writeSiteOrg`) and re-dressed
- * with the `@` the CLI and the wire both use. Callers pass it as `--as-org`'s default
- * so an org named once, at create, does not have to be re-typed on every later push.
+ * Read back from `backend`'s `site.org` in `sync.json` (stored bare — see
+ * `writeSiteOrg`) and re-dressed with the `@` the CLI and the wire both use. Callers
+ * pass it as `--as-org`'s default so an org named once, at create, does not have to
+ * be re-typed on every later push.
  *
  * Deliberately NOT a fallback for the flag: an explicit `--as-org` always wins and
  * rides verbatim, so this can only add a value where the CLI previously sent none.
  *
  * @param {string} siteDir
+ * @param {string} backend - the origin whose record to read
  * @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 +677,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
@@ -615,15 +704,20 @@ function recordSiteOrg(siteDir, asOrg) {
  * to several orgs could put a company site, and the storage it bills, somewhere
  * they never named.
  *
- * `register` has refused to guess a scope for the foundation lane since it shipped
- * (`deriveScope` → `package.json::uniweb.scope`). This is the same refusal, one
- * lane over.
+ * `register` resolves a foundation's scope in the same order — explicit, then
+ * recorded (`package.json::uniweb.scope`), then asked (`deriveScope`) — with one
+ * difference: non-interactive, it PICKS the one org you belong to, else your
+ * personal org, else the primary, and says which. This refuses instead, because a
+ * site's owner is the one-shot decision above. ⚠️ Until 2026-09-21 this said
+ * `register` "has refused to guess a scope", which is wrong for a non-interactive
+ * run by anyone with an org.
  *
  * Order, and only the last step is new:
  *   1. `--as-org @org`      — explicit, rides verbatim
  *   2. `--personal`         — explicit "no org, I mean it" → sends NO `as_org`
- *   3. `site.yml::$org`     — recorded at this site's own create
- *   4. the site already exists (`$uuid`) → null; ownership is settled, ask nothing
+ *   3. the recorded org     — `sync.json`, written at this site's own create
+ *   4. the site already exists on this backend (a recorded uuid) → null; ownership
+ *      is settled, ask nothing
  *   5. otherwise ASK (TTY) or REFUSE (non-interactive)
  *
  * ⛔ **`--personal` sends no `as_org`, and is NOT the same as `--as-org @<handle>`.**
@@ -648,19 +742,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 +913,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 +940,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 +994,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 +1032,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.
@@ -992,25 +1074,23 @@ async function recordAndDescribeOwner({
 /**
  * Guarantee we have per-item identity before an identity-bearing push.
  *
- * Fires only when the site HAS been pushed before (`$uuid` in site.yml) but the
- * cache is empty — a fresh `git clone`, or a deleted `.uniweb/`. One read of the
- * backend's current document, no file writes, no `uniweb pull`. A first-ever push
- * legitimately has nothing to fetch and is left alone.
+ * Fires only when the site HAS been pushed to this backend before (its uuid is in
+ * `sync.json`) but that backend's item map there is empty. One read of the
+ * backend's current document, recorded into that map — no content file is written,
+ * and no `uniweb pull`. A first-ever push legitimately has nothing to fetch and is
+ * left alone. (The map sat in the gitignored cache until 2026-09-20, so a fresh
+ * `git clone` or a deleted `.uniweb/` was what emptied it; it is committed now.)
  *
  * @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 +1099,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 +1112,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,20 +1135,19 @@ 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
   //     for a cache written before this was banked (and for a never-pushed site),
   //     which is the pre-fix behaviour and self-heals on the next push. It can never
   //     point at the wrong document: it is written with the hashes it belongs to.
-  //   · RE-DERIVED — asset identity, from the COMMITTED `assets.json` the same push
-  //     wrote. Reading the live file rather than a snapshot is what makes a moved
-  //     map (a teammate's push, a pull) read as changed instead of matching a copy
-  //     of itself.
-  //   · RECORDED — the site's own org, from `site.yml::$org`, written by the push
-  //     that banked these hashes.
+  //   · RE-DERIVED — asset identity, from this backend's COMMITTED asset map in
+  //     `sync.json`, which the same push wrote. Reading the live file rather than a
+  //     snapshot is what makes a moved map (a teammate's push, a pull) read as
+  //     changed instead of matching a copy of itself.
+  //   · RECORDED — the site's own org, from `sync.json` (this backend's `site.org`).
   //
   // ⛔ THE ORG IS NOT OPTIONAL HERE, AND OMITTING IT WAS SILENT. It is what resolves
   // a foundation-relative `@/member` into the `@org/member` the push shipped and
@@ -1083,7 +1162,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 || [] }
@@ -1098,25 +1177,34 @@ export async function probeUnpushed(siteDir, { sendAll = false } = {}) {
  *
  *   · BANKED     the injections the push applied before hashing — serve URLs and
  *                the pinned foundation ref, which only a round trip produces.
- *   · RE-DERIVED asset identity, from the COMMITTED `assets.json`, so a moved map
- *                reads as changed rather than matching a copy of itself.
+ *   · RE-DERIVED asset identity, from this backend's COMMITTED asset map in
+ *                `sync.json`, so a moved map reads as changed rather than matching
+ *                a copy of itself.
  *   · RECORDED   the site's org, which resolves a foundation-relative `@/x` into
  *                the `@org/x` the push keyed its hashes by, and the collection
- *                identity a push stamps — so `status` hashes the same document a
- *                push would send rather than one missing a section's `$uuid`s.
+ *                identity a push stamps, so the document is the one a push builds.
+ *                ⚠️ Identity is parity, not correctness: `entityContentHash` strips
+ *                `$`-sigils, so a query's `$uuid` never moves a hash (measured
+ *                2026-09-21). This read no backend from 2026-09-20 to 2026-09-21 —
+ *                an empty map — which is why no `status` ever showed it, and why this
+ *                bullet was then misread as naming a live defect.
  *
  * Offline by design — measured at zero HTTP requests, a property the cross-client
  * flows rely on.
  */
 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 queryUuids = readQueryUuids(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, backend)
   return emitSyncPackages(siteDir, {
+    backend,
     resolveModel: makeModelResolver({ client: null, offline: true }),
     priorHashes,
     sendAll,
@@ -1148,9 +1236,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 +1292,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 +1319,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 +1432,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,10 +1444,17 @@ 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
-        // 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.
+        // it. The uuid sent here is the one this project recorded for THIS origin
+        // (sync.json), so another backend's uuid cannot reach it; what does is a site
+        // this origin no longer has — deleted there, or a backend rebuilt at the same
+        // address. Being logged in to a backend you did not mean is still the cheaper
+        // thing to rule out, so it still comes first. (Until 2026-09-21 this paragraph
+        // leaned on a scope check against `site.yml::$backend`; both were deleted on
+        // 2026-09-20.)
+        //
+        // ⛔ The fix for a deletion was "clear `$uuid` from site.yml" until 2026-09-21 — a
+        // key that left site.yml the day before, so the advice named nothing to clear.
+        // The binding is this backend's section of sync.json, and `forget` drops it.
         note(
           `The backend at ${client.origin} has no site with uuid ${boundUuid}.`
         )
@@ -1370,7 +1465,7 @@ export async function pushSyncPackages({
           `  wrong backend  →  uniweb login --backend <the right one>   (nothing is lost)`
         )
         note(
-          `  deleted in the app  →  clearing \`$uuid\` from site.yml re-publishes it as a NEW site`
+          `  deleted there  →  uniweb forget --backend ${client.origin}, then push again: it creates a NEW site`
         )
         note('Deleting this folder removes only your local copy, either way.')
       } else if (res.status === 409) {
@@ -1379,8 +1474,8 @@ export async function pushSyncPackages({
         note(
           "This site's record structure is already established on the backend and can't be changed " +
             'in place — e.g. adding or removing a schema-backed query, or switching one between ' +
-            'static (data-bundle) and schema-backed delivery. To change it: delete the deployed site and ' +
-            'redeploy, or clear `$uuid` in site.yml to deploy a fresh one.'
+            'static (data-bundle) and schema-backed delivery. To change it, push it as a new site: ' +
+            `uniweb forget --backend ${client.origin}, then push again (the old site stays until it is deleted).`
         )
       }
       if (body) note(body.slice(0, 800))
@@ -1415,8 +1510,8 @@ export async function pushSyncPackages({
 
   // Lane 1 — site-content (the site is born here; it must exist before its folder). A
   // known site uuid → UPDATE by uuid; none → CREATE (the backend mints + adopts the site
-  // and returns its uuid, which we record into site.yml). `boundSiteUuid` carries the
-  // minted/known uuid forward to key the folder push.
+  // and returns its uuid, which we record in sync.json, under this backend).
+  // `boundSiteUuid` carries the minted/known uuid forward to key the folder push.
   let boundSiteUuid = siteContentUuid
   // Post-write tokens harvested from every lane, persisted once at the end so a
   // partial push (lane 1 ok, lane 2 refused) still banks what actually landed —
@@ -1452,8 +1547,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).
@@ -1484,12 +1579,13 @@ export async function pushSyncPackages({
       // ⭐ BANK COLLECTION-DECLARATION IDENTITY, the sibling of the folder's
       // placements below. These items have no file to back-fill into — they all
       // come from one `collections/collections.yml` — so the only place their
-      // `$uuid` can live is the cache, keyed by the name the backend enforces
-      // unique. Without it every push after the first re-sends the whole
+      // `$uuid` can live is `sync.json` (this backend's `queries` map), keyed by the
+      // name the backend enforces unique. Without it every push after the first re-sends the whole
       // `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,14 +1601,14 @@ 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')
+      wrote.push('recorded the site in sync.json')
       // The OTHER create path (a media-less push never reaches `ensureSiteExists`,
       // which is gated on the site having local media). Both mint a site, so both
-      // owe the same record — recording it in only one place would make `$org`
-      // present or absent depending on whether the site happens to have images.
+      // owe the same record — recording it in only one place would make the recorded
+      // owner present or absent depending on whether the site happens to have images.
       // The backend echoes `org`/`hosts_free` top-level here too, beside `report`
       // and `site` (NOT beside `finalized`, which lives at report.finalized).
       const createdOrg = await recordAndDescribeOwner({
@@ -1523,7 +1619,7 @@ export async function pushSyncPackages({
         note
       })
       if (createdOrg)
-        wrote.push(`recorded site $org (${createdOrg}) in site.yml`)
+        wrote.push(`recorded its owner (${createdOrg}) in sync.json`)
       const createdFinalized = extractFinalized(payload)
       harvest(createdFinalized)
       siteFinalizedDoc = createdFinalized?.[0]?.document || null
@@ -1554,12 +1650,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 +1674,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 +1683,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 +1696,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.