uniweb 1.0.0 → 1.0.2

package/src/backend/site-sync.js

@@ -0,0 +1,2515 @@
+/**
+ * site-sync — the reusable core of `uniweb push`: given a site's emitted sync
+ * packages, submit them over the two directional lanes (site-content first, then the
+ * folder keyed by the site's uuid), back-fill the minted uuids into the source files,
+ * and persist the send-only-changed cache. Extracted from the push command so
+ * `uniweb publish` (the composite path) reuses the exact same lane submission.
+ *
+ * The command keeps flag parsing, the emit, and the `-o`/`--dry-run` preview;
+ * everything from "the packages are built, now POST them" lives here. Logging is
+ * injected via `report` ({ info, note, error, dim }) so each caller styles output its
+ * own way.
+ */
+
+import { writeFileSync, readFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs'
+import { join, dirname, relative, isAbsolute, basename } from 'node:path'
+import yaml from 'js-yaml'
+import { hasUncommittedContent } from '../utils/git.js'
+import { recordWritten } from '../utils/pull-written.js'
+import { humanBytes } from '../utils/bytes.js'
+import { isAuthoredPreview } from '../utils/preview.js'
+import {
+  describeRequestError,
+  describeWorkspace,
+  WorkspaceMismatchError,
+  workspaceHandle,
+  workspaceHeader
+} from './client.js'
+import {
+  backfillEntityUuids,
+  writeSiteEntityUuid,
+  updateBackendState,
+  emitSyncPackages,
+  readZip,
+  diffSiteUnits,
+  describeSiteDiff,
+  computeUnitHashes,
+  collectUnitUuids,
+  collectFolderItemUuids,
+  collectQueryUuids,
+  siteItemsByKey,
+  sameServiceRow,
+  heldServices,
+  readBackendState,
+  updateBackendMap,
+  clearBackendSections,
+  normalizeBackendOrigin,
+  writeSiteConfig,
+  harvestRecordItems,
+  storedRecordItems,
+  reprintRecordItems,
+  matchStoredRecords,
+  parseCatalogRef,
+  readRegisteredFoundation,
+  writeRegisteredFoundation,
+  backfillLinkUuids,
+  LINK_MODEL,
+  bankedFileUuids,
+  existingSectionFile,
+  layoutUnitFile
+} from '@uniweb/build/uwx'
+
+// First entity `$`-document out of a `.uwx` we produced or the backend served.
+// Deliberately NOT pull.js's `readPullDocuments`: that one is tolerant of JSON
+// envelopes for a lane whose shape may change, and importing it here would be a
+// cycle (pull.js already imports this module). Both lanes here are always ZIPs.
+function entityDocFromUwx(buf) {
+  if (!buf || buf.length < 2 || buf[0] !== 0x50 || buf[1] !== 0x4b) return null
+  for (const [name, data] of readZip(buf)) {
+    if (name === 'manifest.json' || !name.endsWith('.json')) continue
+    try {
+      return JSON.parse(data.toString('utf8'))
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+
+// Every entity `$`-document of a `.uwx` — the folder lane holds the folder and its records.
+function entityDocsFromUwx(buf) {
+  const docs = []
+  if (!buf || buf.length < 2 || buf[0] !== 0x50 || buf[1] !== 0x4b) return docs
+  for (const [name, data] of readZip(buf)) {
+    if (name === 'manifest.json' || !name.endsWith('.json')) continue
+    try {
+      docs.push(JSON.parse(data.toString('utf8')))
+    } catch {
+      // not a document
+    }
+  }
+  return docs
+}
+
+/**
+ * Turn an entity-grained staleness refusal into a file-level account.
+ *
+ * The gate can only report that the site-content document moved. What the user
+ * needs is which FILES — content is split one section per file, so two people
+ * editing different sections of the same page have not conflicted — and, since we
+ * cache per-unit hashes of the last agreed state, which side moved them. Fetches the backend's current document (a plain
+ * read; it writes nothing locally, unlike `uniweb pull`) and diffs.
+ *
+ * Best-effort by design: this runs on a path that has ALREADY failed, so any
+ * problem fetching or parsing must degrade to the plain refusal rather than
+ * replace a clear error with a confusing one.
+ *
+ * @returns {string[]} lines to print, or [] when nothing useful can be said.
+ */
+async function explainStaleSiteContent({ client, siteDir, localBuffer, uuid }) {
+  try {
+    if (!uuid) return []
+    const res = await client.pullSiteContent(uuid)
+    if (!res?.ok) return []
+    const remoteDoc = entityDocFromUwx(Buffer.from(await res.arrayBuffer()))
+    const localDoc = entityDocFromUwx(localBuffer)
+    if (!remoteDoc || !localDoc) return []
+    return describeSiteDiff(
+      diffSiteUnits(localDoc, remoteDoc, readUnitBases(siteDir, client.origin))
+    )
+  } catch {
+    return []
+  }
+}
+
+/**
+ * The items a `stale_base` refusal names by key — `stale_keys`, one
+ * `{ section, key }` per clashing item of a Section matched by a field of its own
+ * (`services` and `queries` by `name`) — as one line per Section.
+ *
+ * @param {*} staleKeys - the refusal's `stale_keys`
+ * @returns {string[]}
+ */
+export function describeStaleKeys(staleKeys) {
+  const bySection = new Map()
+  for (const entry of Array.isArray(staleKeys) ? staleKeys : []) {
+    const section = typeof entry?.section === 'string' && entry.section ? entry.section : null
+    if (!section) continue
+    const key = entry?.key
+    // A single-item Section (`settings`) is named by the Section alone, `key: {}`.
+    const single = key && typeof key === 'object' && !Object.keys(key).length
+    const name =
+      key && typeof key === 'object'
+        ? typeof key.name === 'string' ? key.name : Object.values(key).filter((v) => typeof v === 'string').join(' ')
+        : typeof key === 'string' ? key : null
+    if (!single && !name) continue
+    if (!bySection.has(section)) bySection.set(section, [])
+    if (name) bySection.get(section).push(name)
+  }
+  return [...bySection].map(([section, names]) =>
+    `Changed on your site since your last pull — ${section}${names.length ? `: ${names.join(', ')}` : ''}`
+  )
+}
+
+// A unit in the form it is compared in across the two representations: keys sorted,
+// `$`-keys dropped (`$uuid`, `$id` — identity and payload handles, not content).
+const canonicalUnit = (v) =>
+  Array.isArray(v)
+    ? v.map(canonicalUnit)
+    : v && typeof v === 'object'
+      ? Object.fromEntries(
+          Object.keys(v)
+            .filter((k) => !k.startsWith('$'))
+            .sort()
+            .map((k) => [k, canonicalUnit(v[k])])
+        )
+      : v
+
+/**
+ * Whether the backend's post-write copy of a unit is the content we sent.
+ *
+ * Compared on OUR keys only. The two are not byte-comparable — the backend's copy
+ * carries fields we don't emit (`params`, `theme_override`, its own `$uuid`) and
+ * orders keys its own way, which is why `site-diff.js` never hashes one side against
+ * the other — but what we emit, it stores verbatim: measured 2026-09-23 against a
+ * live `uniwebd`, 15 of 15 units equal on our keys after a push.
+ */
+function writtenAsSent(sent, written) {
+  if (!sent || !written) return false
+  const onOurKeys = {}
+  for (const k of Object.keys(sent)) if (!k.startsWith('$')) onOurKeys[k] = written[k]
+  return JSON.stringify(canonicalUnit(sent)) === JSON.stringify(canonicalUnit(onOurKeys))
+}
+
+/**
+ * The post-write tokens a site-content push may bank: only those that describe
+ * content this copy HOLDS.
+ *
+ * ⛔ BANKING EVERY RETURNED TOKEN LOST OTHER WRITERS' WORK — measured 2026-09-23 on a
+ * live `uniwebd`, two copies of one site:
+ *
+ *   1. B edits section X and pushes.
+ *   2. A, which has not pulled, pushes an edit to section Y. The per-item gate reads
+ *      A's X as untouched (`pkg == base`) and keeps B's X — correct. But the response
+ *      carries X's token for B's content, and A banked it.
+ *   3. A's next push of X then reads as "only you changed it" (`host == base`) and
+ *      overwrites B's edit, with no refusal.
+ *
+ * The entity token did the same to ADDITIONS: a section B added survived A's first
+ * push (created after A's base ⇒ KEEP), A banked a base newer than it, and A's next
+ * push deleted it (created at-or-before the base ⇒ "you dropped it").
+ *
+ * So a unit's token is banked only when its post-write copy is what we sent — our own
+ * write, or a unit nobody touched. A unit the backend kept for someone else keeps the
+ * token we already hold, which is the one for OUR content, so the next push that
+ * changes it is `pkg != base, host != base` and refused. And while the backend holds
+ * units we don't, the entity token stays where it was, so the next push keeps them.
+ *
+ * ⭐ SINCE 2026-10-07 A HELD VERSION IS ALSO WHAT LETS A PUSH DELETE, so the rule covers
+ * every item, not only units. The site-content entity sends every version this copy
+ * holds, for items present and items the files dropped (`withBaseVersion`), and the
+ * backend deletes only the items a push holds a version for, while the site left them
+ * unchanged [Diego: "yes, apply it to pages too"; kb/framework/plans/services-exchange.md].
+ * A version banked for an item this copy never saw would therefore delete it. The map
+ * returned is the WHOLE set this copy now holds, in every Section but `secrets`
+ * (`siteItemsByKey`), and it replaces the one held before:
+ *
+ *   - an item the backend holds as we sent it → its new version;
+ *   - an item we sent that it kept for someone else → the version we held, for OUR content;
+ *   - an item it holds that we did not send → the version we held, if we had seen it, and
+ *     none if we had not (a unit of it is `foreign`);
+ *   - an item we held that it no longer holds → none: the push deleted it, or the site did.
+ *
+ * ⛔ Until then only units were compared, and every other item's version was banked as
+ * the backend returned it — harmless only while none of them was ever sent.
+ *
+ * A service is compared by its switch and its whole `config` (`sameServiceRow`), every
+ * other item on the keys we sent (`writtenAsSent`).
+ *
+ * With either document missing there is nothing to compare, and with no versions
+ * returned (an older backend) nothing to bank: `itemVersions` is null, and the versions
+ * held stay as they were. The contract is that `finalized[].document` is always there.
+ *
+ * @param {object} p
+ * @param {object|null} p.sent - the site-content document this push sent
+ * @param {object|null} p.written - the backend's post-write copy of it
+ * @param {string|null} [p.version] - the entity's post-write version
+ * @param {Object<string,string>|null} [p.itemVersions] - the post-write version of every item
+ * @param {Object<string,string>} [p.held] - the versions this copy held before the push
+ * @returns {{ version: string|null, itemVersions: Object<string,string>|null,
+ *   held: string[], kept: string[], foreign: string[] }} `itemVersions`: the versions
+ *   this copy now holds, or null to leave them as they were; `held`: units the backend
+ *   holds as we sent them; `kept`: units it kept someone else's content for;
+ *   `foreign`: units it holds that we did not send. All paths.
+ */
+export function heldTokens({ sent, written, version = null, itemVersions = null, held: before = {} }) {
+  if (!sent || !written) return { version, itemVersions: null, held: [], kept: [], foreign: [] }
+  const prior = before && typeof before === 'object' ? before : {}
+  const ours = siteItemsByKey(sent)
+  const theirs = siteItemsByKey(written)
+  const same = (key, a, b) => (key.startsWith('services:') ? sameServiceRow(a, b) : writtenAsSent(a, b))
+  const held = []
+  const kept = []
+  const foreign = []
+  const items = {}
+  for (const [key, item] of theirs) {
+    if (!item.uuid) continue
+    const unit = key.startsWith('unit:') ? key.slice('unit:'.length) : null
+    const mine = ours.get(key)
+    if (mine && same(key, mine.record, item.record)) {
+      if (unit) held.push(unit)
+      const token = itemVersions?.[item.uuid] ?? prior[item.uuid]
+      if (token) items[item.uuid] = token
+      continue
+    }
+    if (unit) (mine ? kept : foreign).push(unit)
+    if (prior[item.uuid]) items[item.uuid] = prior[item.uuid]
+  }
+  return {
+    version: foreign.length ? null : version,
+    itemVersions: itemVersions ? items : null,
+    held: held.sort(),
+    kept: kept.sort(),
+    foreign: foreign.sort()
+  }
+}
+
+/**
+ * The versions a pull leaves this copy holding: one for every site-content item the
+ * pulled document carries, in every Section but `secrets` (`siteItemsByKey`) — the
+ * whole set, replacing what was held. A pull is how a copy sees the site, so an item
+ * the site no longer has is forgotten, and the next push does not send its version.
+ *
+ * @param {object|null} doc - the pulled site-content document
+ * @param {Object<string,string>|null} itemVersions - the pull manifest's `item_versions`
+ * @returns {Object<string,string>|null} null when there is nothing to bank (no document, or
+ *   an older backend that sends no item versions)
+ */
+export function pulledItemVersions(doc, itemVersions) {
+  if (!doc || !itemVersions || typeof itemVersions !== 'object') return null
+  const out = {}
+  for (const { uuid } of siteItemsByKey(doc).values()) {
+    if (uuid && typeof itemVersions[uuid] === 'string') out[uuid] = itemVersions[uuid]
+  }
+  return out
+}
+
+// The files a unit projects to, under the site's own roots — `site.yml::paths` can
+// relocate `pages` and `layout`. `site.yml` stands for the `info` unit, which projects
+// to three files.
+//
+// ⭐ A section unit's path names it by its id (`pages/about/about.md`), and the author's
+// file may carry an ordering prefix or a child mark (`1-about.md`, `@about.md`), which a
+// pull writes back into in place. So the unit is looked up as a pull finds it
+// (`existingSectionFile`). ⛔ Until 2026-10-07 the id path was taken as the file: a push
+// recorded no file for a numbered section, and the next `pull --merge` merged against an
+// older version — a false conflict on a line only the other side had changed (measured
+// on the starter's `1-welcome.md`).
+export function unitFilesOf(siteDir, unitPath) {
+  if (unitPath === 'site.yml') return ['site.yml', 'theme.yml', 'head.html']
+  let paths = {}
+  try {
+    paths = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))?.paths || {}
+  } catch {
+    /* no or unreadable site.yml — the defaults are right */
+  }
+  // A layout unit names its layout and area (`footer.md`, `default/header/1-alert.md`); the author may
+  // keep it as `default/footer.md` or `default/header/0-alert.md`, where a pull writes it back
+  // (`layoutUnitFile`). ⛔ Until 2026-10-08 it was looked up beside the unit's own path only.
+  if (unitPath.startsWith('layout/')) {
+    const base = join(siteDir, paths.layout || 'layout')
+    return [relative(siteDir, layoutUnitFile(base, unitPath.slice('layout/'.length)))]
+  }
+  if (unitPath.startsWith('pages/')) {
+    const rel = `${paths.pages || 'pages'}${unitPath.slice('pages'.length)}`
+    if (!rel.endsWith('.md') || existsSync(join(siteDir, rel))) return [rel]
+    const id = basename(rel, '.md')
+    const found = existingSectionFile(join(siteDir, dirname(rel)), id, id, { child: true })
+    return [found ? relative(siteDir, found) : rel]
+  }
+  return []
+}
+
+/**
+ * Record, as synced, the files of the units a push left on the backend as we sent them.
+ *
+ * ⭐ WHAT A PUSH DELIVERED IS THE NEXT MERGE'S ANCESTOR. `pull --merge` finds the
+ * version a file last synced at by the hash in `pull-written.json`. A pull records what
+ * it wrote; this records what a push delivered — the units `heldTokens` says the
+ * backend holds as ours, never one it kept for someone else. Without it, after a merge
+ * and a push the ancestor was the pull's raw output, which nobody commits: the next
+ * merge found no common version and put both whole files under conflict markers, for
+ * edits on different lines (measured 2026-09-23).
+ */
+function recordPushedUnits(siteDir, unitPaths) {
+  const files = new Set()
+  for (const p of unitPaths) for (const f of unitFilesOf(siteDir, p)) files.add(f)
+  const present = [...files].map((f) => join(siteDir, f)).filter((abs) => existsSync(abs))
+  if (present.length) recordWritten(siteDir, present)
+}
+
+// Pull the finalized entities out of the restore response. The backend returns
+// `{ report: { finalized: [ { index, uuid, changed, document }, … ] } }` — each entry
+// carries its position in the SUBMITTED sequence (`index`, the correlation key — `$id`
+// is not echoed), the minted entity `uuid`, a `changed` flag, and the full `document`
+// (verbatim stored content with every `$uuid` filled in). A couple of shapes are
+// tolerated; only entries with a valid `index` + `uuid` are usable.
+export function extractFinalized(payload) {
+  const list = Array.isArray(payload?.report?.finalized)
+    ? payload.report.finalized
+    : Array.isArray(payload?.finalized)
+      ? payload.finalized
+      : Array.isArray(payload)
+        ? payload
+        : null
+  if (!list) return null
+  return list
+    .map((d) => ({
+      index: d?.index,
+      uuid: d?.uuid ?? d?.document?.$uuid ?? null,
+      changed: d?.changed,
+      // Post-write optimistic-concurrency token, read back from the stored row.
+      // Do not branch on `changed`: the backend pins "zero-write ⇒ version unmoved"
+      // with a test, so a no-op resubmit returns the value we already hold. ⛔ But a
+      // site-content push banks it only while the stored document holds nothing we
+      // don't — see `heldTokens`, and what banking it unconditionally deleted.
+      version: typeof d?.version === 'string' ? d.version : null,
+      // Per-item post-write tokens, `{ recordUuid: <opaque> }` (backend `d7e46335`).
+      // Same map shape and same key name the PULL manifest entry stamps, deliberately
+      // — one kind of value, cached from whichever lane last handed it over, echoed
+      // as `item_base_versions`. Absent on an older backend ⇒ null ⇒ the cached
+      // tokens are left alone and gating degrades to the entity grain.
+      itemVersions:
+        d?.item_versions && typeof d.item_versions === 'object'
+          ? d.item_versions
+          : null,
+      document: d?.document ?? null
+    }))
+    .filter((e) => Number.isInteger(e.index) && e.uuid)
+}
+
+// Pull the minted site-content uuid out of a CREATE response. The exact shape is an
+// open backend item, so the extractor is deliberately tolerant of a bare
+// `{ siteContentUuid }` / `{ $uuid }` / `{ uuid }`, or the same `report.finalized[]`
+// envelope the update/folder lanes return (the site entity is submitted alone, so its
+// minted uuid is the first finalized entry). Returns null if none is present.
+export function extractMintedSiteUuid(payload) {
+  // `POST /dev/site` (the empty-site create) answers with the snake_case spelling;
+  // the content-lane CREATE has historically used the others. Both are the same
+  // identity — the uuid `/dev/site/content/pull/{uuid}` accepts.
+  if (typeof payload?.site_content_uuid === 'string')
+    return payload.site_content_uuid
+  if (typeof payload?.siteContentUuid === 'string')
+    return payload.siteContentUuid
+  if (typeof payload?.$uuid === 'string') return payload.$uuid
+  if (typeof payload?.uuid === 'string') return payload.uuid
+  const finalized = extractFinalized(payload)
+  if (finalized && finalized.length) {
+    const site = finalized.find((f) => f.index === 0) || finalized[0]
+    return site?.uuid ?? null
+  }
+  return null
+}
+
+// One-line summary from the authoritative per-entity `changed` flag (`false` = a true
+// no-op). Falls back silently when the backend omits it.
+function changedSummary(finalized) {
+  const changed = finalized.filter((f) => f.changed === true).length
+  const unchanged = finalized.filter((f) => f.changed === false).length
+  const parts = []
+  if (changed) parts.push(`${changed} changed`)
+  if (unchanged) parts.push(`${unchanged} unchanged`)
+  return parts.length ? parts.join(', ') : null
+}
+
+// Resolve a Model NOT defined by the local foundation by reading its declaration (the
+// `@uniweb/data-schema` form) from the backend via the client. Cached per run; HTTP
+// 404 → null (the emitter then says "register it first"). The bearer is acquired lazily
+// by the client, so a fully-local sync never authenticates.
+//
+// `offline` (set for `-o` / `--dry-run`, and for `status`) never touches the backend — an
+// offline emit must never authenticate. It answers with the Models a push or a pull KEPT for
+// this backend (`keptModels`), or null. ⭐ With `siteDir`, an online read keeps each Model it
+// reads, per backend — so a clone, whose foundation is not in the project to declare them, can
+// still compare offline. ⛔ Until 2026-09-26 nothing was kept, and `uniweb status` in a clone
+// could not resolve a Model ("… could not be resolved").
+export function makeModelResolver({ client, offline = false, siteDir = null, backend = null }) {
+  const origin = backend ?? client?.origin ?? null
+  const kept = siteDir && origin ? keptModels(siteDir, origin) : {}
+  const cache = new Map()
+  return async (modelName) => {
+    if (cache.has(modelName)) return cache.get(modelName)
+    let decl
+    if (offline) {
+      decl = kept[modelName] ?? null
+    } else {
+      decl = await client.readDataSchema(modelName)
+      if (decl && siteDir && origin) keepModels(siteDir, origin, { [modelName]: decl })
+    }
+    cache.set(modelName, decl)
+    return decl
+  }
+}
+
+/**
+ * The Models a push or a pull read from this backend, by name — kept in `.uniweb/backend-cache.json`
+ * so an offline emit resolves what an online one did. Regenerable: losing them costs `status` its
+ * comparison until the next push or pull, never a wrong answer.
+ */
+export function keptModels(siteDir, backend) {
+  const models = readSyncCacheFile(siteDir, backend).models
+  return models && typeof models === 'object' ? models : {}
+}
+
+/** Keep Models read from this backend, beside the ones already kept. */
+export function keepModels(siteDir, backend, models) {
+  if (!models || !Object.keys(models).length) return
+  updateSyncCache(siteDir, backend, { models: { ...keptModels(siteDir, backend), ...models } })
+}
+
+// `.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). ⚠️ One exception since 2026-10-07, and it
+// is said where it lives: the item versions are what lets a push delete, so without
+// them a dropped page is kept until the next pull (`readItemBaseVersions`).
+//
+// ⚠️ 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 readCacheFile(siteDir) {
+  try {
+    const obj = JSON.parse(readFileSync(backendCachePath(siteDir), 'utf8'))
+    return obj && typeof obj === 'object' && obj.backends ? obj : { backends: {} }
+  } catch {
+    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, 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 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, backend, key) => {
+  const v = readSyncCacheFile(siteDir, backend)[key]
+  return v && typeof v === 'object' ? v : {}
+}
+
+/**
+ * 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).
+ *
+ * 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 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
+ *     stored on entity 156 — item uuids are globally unique; cross-entity move is
+ *     not supported"*. A raw 400 for following our own advice.
+ *   - **content hashes** — worse, because it is silent. Send-only-changed would
+ *     skip every entity whose content had not changed since the OLD site's last
+ *     push, so the NEW site would come up **missing exactly the content that did
+ *     not change** — a partial site, published successfully, with nothing to
+ *     indicate it.
+ *
+ * The guidance is `uniweb forget --server <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.
+ */
+/**
+ * Drop the five remote-derived maps unconditionally, stamping the site they now
+ * describe (or clearing the stamp when there is none). Shared by the pre-flight
+ * guard and the `item_uuid_conflict` recovery — the guard decides WHETHER, this
+ * decides WHAT, and they must not drift.
+ */
+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: {},
+    // Remote-derived like the rest, and doubly so: it holds the OLD site's asset
+    // serve URLs. Surviving the drop, it would rewrite the new site's media to
+    // bytes owned by the site this folder used to be.
+    applied: {},
+    siteUuid: siteUuid || null
+  })
+  // ⛔ 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, 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, 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',
+    'baseVersions',
+    'unitBases',
+    'applied'
+  ]
+  const lookup = { ...prior, ...identityPrior }
+  const populated = REMOTE_MAPS.filter(
+    (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, backend, { siteUuid: current })
+    }
+    return []
+  }
+
+  // Two ways the maps can describe a site this clone is not working with:
+  //
+  //   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.
+  //
+  // A cache with NO `siteUuid` and a bound site is left alone: that is every
+  // pre-existing clone, and assuming it matches is right far more often than
+  // wiping it would be.
+  const stale =
+    !current || (prior.siteUuid && prior.siteUuid !== current) ? populated : []
+  if (!stale.length) {
+    if (current && prior.siteUuid !== current) {
+      updateSyncCache(siteDir, backend, { siteUuid: current })
+    }
+    return []
+  }
+
+  clearRemoteSyncState(siteDir, backend, current)
+  return stale
+}
+
+/**
+ * Drop the `site.yml` values that describe ONE PARTICULAR backend site, when this
+ * project is bound to none (no `$uuid`) — a brand-new site, or the state our own
+ * "clear `$uuid` to re-publish as a new site" recovery puts you in. Today that is
+ * one value: `preview` in the APP's form — a timestamp naming the previous site's
+ * generated card image, which is keyed by that site's uuid and would dangle on this
+ * one.
+ *
+ * ⛔ An AUTHOR's preview is theirs and stays: a URL, or a path to an image in the
+ * project, is as good for the new site as for the old.
+ *
+ * (`$url`, where the previous site was live, was dropped here too until it was
+ * retired on 2026-09-17. A leftover line is inert — nothing reads or sends it.)
+ *
+ * The site.yml sibling of `clearRemoteSyncStateIfUnbound`, called beside it for the
+ * same reason — before the create mints a uuid and makes the project look bound.
+ *
+ * @param {string} siteDir
+ * @returns {string[]} the keys removed
+ */
+export function dropSiteBoundValues(siteDir, backend) {
+  const file = join(siteDir, 'site.yml')
+  let y
+  try {
+    y = yaml.load(readFileSync(file, 'utf8'))
+  } catch {
+    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 &&
+    !isAuthoredPreview(y.preview) &&
+    writeSiteConfig(siteDir, { preview: null }) === 'updated'
+  ) {
+    dropped.push('preview')
+  }
+  return dropped
+}
+
+export function readSyncCache(siteDir, backend) {
+  return readMap(siteDir, backend, 'hashes')
+}
+
+/**
+ * The hash-affecting injections the emit that produced those hashes applied, in the
+ * 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: 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.
+ *
+ * ⛔ Read this whenever you re-emit to COMPARE against `hashes`. A push hashes the
+ * DELIVERED document — local `/images/x.png` rewritten to the backend serve URL it
+ * just uploaded to, `info.foundation` replaced by the version-pinned ref — and banks
+ * that. An offline re-emit produces the AUTHORED document, which is a different
+ * document, so it matches nothing and every entity reads as changed forever. That is
+ * not hypothetical: it is what `uniweb status` did on any site with one local image
+ * (backend↔framework, 2026-08-19) — `push` said "1 entity unchanged" and
+ * `status --json` said `changed: 1`, from the same cache, seconds apart.
+ *
+ * ⭐ What is left is what only a backend round-trip produces — an asset **serve URL**
+ * and a released foundation version — and `status` is offline by design (measured at
+ * 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 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, backend) {
+  return readMap(siteDir, backend, 'applied')
+}
+
+/**
+ * ⭐ THE REGISTERED FOUNDATION A CLONE KEEPS. A site whose foundation is a catalog ref has no build of
+ * it in the project, and the section types' `data:` it declares are what type a query named for a
+ * data key — `team:` read as `@acme/member` (`typed_by_data_key`). Read once from the backend,
+ * through the site, and kept under `.uniweb/` (`@uniweb/build`'s `registered-foundation.js`), where
+ * the build, the push and the pull read it; a registered version never changes, so a kept copy is
+ * never read again.
+ *
+ * Null when the foundation is not a catalog ref, the site is not on this backend yet, or the read
+ * fails: nothing is then typed by it — a pull writes such a query's schema out, and a push sends
+ * what that says — so both go on.
+ */
+export async function ensureRegisteredFoundation({ client, siteDir, siteUuid, ref }) {
+  if (!parseCatalogRef(ref)) return null
+  const kept = readRegisteredFoundation(siteDir, ref)
+  if (kept) return kept
+  const reply = siteUuid ? await client.readRegisteredFoundation(siteUuid, ref) : null
+  if (!reply) return null
+  // ⛔ ONLY WHAT WE READ — the section types. The reply carries more than we asked for, a serve
+  // location among it, and a serve location is decided at publish and read from the response that
+  // carries it, never kept. Until 2026-09-26 the whole reply was kept.
+  const sectionTypes = { schema: reply.schema }
+  writeRegisteredFoundation(siteDir, ref, sectionTypes)
+  return sectionTypes
+}
+
+// The Sections whose declared keys a push reads before it sends an optional one.
+const DEPLOYMENT_FIELD_LISTS = ['queryFields', 'pageFields', 'settingsFields']
+
+/**
+ * The keys this deployment's `queries`, page and `settings` Sections declare, as it says so itself —
+ * `GET /dev/config` → `siteContent.queryFields` / `pageFields` / `settingsFields` — so a push sends
+ * an optional key only to a deployment that takes it (`typed_by_data_key`; `og_title` and
+ * `og_description`): one that does not declare a key refuses a push carrying it. Offline — a dry
+ * run, `--output` — the lists the last push to this backend banked, so the package is the one that
+ * push would build.
+ *
+ * Only the lists in hand are returned, as emit options: with none, nothing optional is sent, which
+ * every deployment accepts.
+ */
+export async function deploymentFields({ client, siteDir, offline = false }) {
+  const source = offline
+    ? readAppliedInjections(siteDir, client.origin)
+    : (await client.discover())?.siteContent
+  const out = {}
+  for (const name of DEPLOYMENT_FIELD_LISTS) if (Array.isArray(source?.[name])) out[name] = source[name]
+  return out
+}
+
+/**
+ * Bank the content hashes and the injections that produced them. ⛔ ONE call, both
+ * maps: they describe the same document, so writing either alone leaves the cache
+ * self-inconsistent — and the failure is silent, since a hash never says which
+ * document it is of. `applied` is written even when empty, so it can never be a
+ * 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 `sync.json` (this backend's `assets`), and the reader
+ * re-derives it there.
+ */
+export function writeSyncCache(siteDir, backend, hashes, applied) {
+  const { assetIds: _inSyncJson, ...bankable } = applied || {}
+  updateSyncCache(siteDir, backend, { hashes, applied: bankable })
+}
+
+/**
+ * The push gate's optimistic-concurrency tokens: `{ <backend-uuid>: <version> }`.
+ *
+ * Lives beside the content hashes because it is the same kind of thing — "the
+ * backend state this clone last agreed with" — and is already per-entity, which
+ * the per-lane `pull-cache.json` (two ETags) is not. Gitignored, per-clone,
+ * deletable: losing it means the next push is unconditional, i.e. today's
+ * behavior, never a wrong-but-plausible token.
+ *
+ * Fed from BOTH directions, which is what makes the gate usable: `pull` records
+ * the manifest's `extra.version`, and every successful push records the
+ * 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, backend) {
+  return readMap(siteDir, backend, 'baseVersions')
+}
+
+/**
+ * Per-ITEM staleness tokens: `{ <item $uuid>: <opaque version> }` — one for every item
+ * of the site-content entity this copy has seen.
+ *
+ * The entity token gates the whole document, so a stale base on any one record
+ * refuses the entire push — which fires on the common case of two people editing
+ * different sections and teaches them to reach for `--force`. These gate per item
+ * instead. Same contract as the entity token: opaque, cached, echoed, never parsed.
+ *
+ * ⭐ AND THEY ARE WHAT LETS A PUSH DELETE (2026-10-07): the backend deletes only the
+ * items a push holds a version for, so every one held is sent, present or dropped
+ * (`withBaseVersion`). Hence the set is REPLACED, never merged — by a pull
+ * (`pulledItemVersions`) and by a push of the site-content lane (`heldTokens`) — and
+ * holds only items this copy has seen. ⚠️ The one thing losing this cache now costs that
+ * is not a round trip: until the next pull, a page or section the files dropped is kept
+ * on the site rather than deleted, since there is no version to send for it.
+ * ⛔ *It was merged until then, across both lanes, for a push that sent only units.*
+ */
+export function readItemBaseVersions(siteDir, backend) {
+  return readMap(siteDir, backend, 'itemBaseVersions')
+}
+/**
+ * Replace the item versions this copy holds — a push's (`heldTokens`) or a pull's
+ * (`pulledItemVersions`) whole set. ⛔ Not a merge: an item that left the set must
+ * leave the map, or its version is sent again and asks the backend to delete it.
+ */
+export function writeItemBaseVersions(siteDir, backend, versions) {
+  if (!versions || typeof versions !== 'object') return
+  updateSyncCache(siteDir, backend, { itemBaseVersions: { ...versions } })
+}
+export function mergeItemBaseVersions(siteDir, backend, versions) {
+  if (!versions || !Object.keys(versions).length) return
+  // ⛔ The read names the backend. Without it the read keyed nothing, came back `{}`,
+  // and this "merge" replaced the map with the last response — dropping the token
+  // `heldTokens` withholds for a unit the backend kept for someone else, and with it
+  // the precondition that refuses the next push of that unit (2026-09-23).
+  updateSyncCache(siteDir, backend, {
+    itemBaseVersions: { ...readItemBaseVersions(siteDir, backend), ...versions }
+  })
+}
+export function mergeBaseVersions(siteDir, backend, versions) {
+  if (!versions || !Object.keys(versions).length) return
+  updateSyncCache(siteDir, backend, {
+    baseVersions: { ...readBaseVersions(siteDir, backend), ...versions }
+  })
+}
+
+/**
+ * Per-unit content hashes of the last synced state, kept in BOTH representations —
+ * the bases for the file-level attribution shown after a staleness refusal
+ * (`diffSiteUnits`). A unit is a projected file: a page's `page.yml`, each section
+ * `.md`, each layout section.
+ *
+ * Two maps, not one, because our document and the backend's are not byte-comparable
+ * (they carry fields we don't emit and their own key order). A hash from one side
+ * compared against a base from the other differs for a unit nobody touched, so each
+ * side gets a base in its own representation:
+ *   `local`  ← our emitted document
+ *   `remote` ← the backend's own copy (`finalized[].document`, or a pull)
+ *
+ * Replaced wholesale rather than merged: a unit that no longer exists is a unit with
+ * no base, and a stale entry would attribute its next difference to the wrong side.
+ *
+ * Purely an explanation aid — losing either map costs detail in one message, never a
+ * wrong push.
+ */
+/**
+ * Per-item identity: `{ <unit path>: <backend $uuid> }`.
+ *
+ * The backend's reconcile matches a record by `$uuid`. `pages`, `page_sections` and
+ * `layout_sections` are all `multi` sections, where a record WITHOUT a uuid is read
+ * as new — inserted, with its stored counterpart deleted as host-only. So pushing
+ * without this map replaces every page and section row on every push. The content
+ * still lands, which is why it went unnoticed, but the app's per-item concurrency
+ * handles are left pointing at rows that no longer exist.
+ *
+ * Cached here rather than written into `page.yml` / section frontmatter: identity is
+ * a sync concern and author files should not carry sync uuids. Populated from
+ * whatever the backend last told us — a pull, or a push response's
+ * `finalized[].document`, which carries `$uuid` for every item at every nesting
+ * level, so a push alone bootstraps it and no pull is required.
+ *
+ * Losing it (gitignored, per-clone) means the next push would be identity-blind,
+ * which is why `push` repopulates it first — see `ensureItemUuids`. The backend also
+ * 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, backend) {
+  return readBackendState(siteDir, backend).items || {}
+}
+/**
+ * Placement identity for the site's `@uniweb/folder` — path chain → `$uuid`.
+ *
+ * Kept separate from `itemUuids` (which is site-content units) because they key
+ * 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, backend) {
+  return readBackendState(siteDir, backend).folders || {}
+}
+
+/**
+ * Collection-declaration identity: `{ <collection name>: <backend $uuid> }`.
+ *
+ * ⛔ THE THIRD MAP, AND EACH ONE EXISTS FOR THE SAME REASON. `itemUuids` is keyed by
+ * the file an item projects to. Two kinds of item have no file of their own — a
+ * folder's placements, and a collection DECLARATION (they all live in one
+ * `collections/collections.yml`) — so a path-keyed map has no shape either could
+ * occupy, and a push re-sends that whole section uuid-less.
+ *
+ * The backend refuses an all-blank section over stored items rather than applying it,
+ * because applying it would insert every record fresh and delete every stored row —
+ * content survives, identity does not. So `push` worked once and every push after was
+ * refused. Measured 2026-08-29; collab framework↔backend.
+ *
+ * ⭐ Keyed by NAME, which the backend enforces unique within the section and uses as
+ * 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, backend) {
+  return readBackendState(siteDir, backend).queries || {}
+}
+// ⭐ 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
+  updateBackendMap(siteDir, backend, 'queries', map)
+}
+export function writeFolderItemUuids(siteDir, backend, map) {
+  if (!map || !Object.keys(map).length) return
+  updateBackendMap(siteDir, backend, 'folders', map)
+}
+export function writeItemUuids(siteDir, backend, map) {
+  if (!map || !Object.keys(map).length) return
+  updateBackendMap(siteDir, backend, 'items', map)
+}
+
+/**
+ * The identity of each record's list items:
+ * `{ <record $uuid>: { <place>: "<item $uuid> <fingerprint>" } }`.
+ *
+ * ⛔ THE FOURTH MAP, FOR THE SAME REASON AS THE OTHER THREE. An item of a record's `many`
+ * section — or of a list nested in one, or of a tree's `$children` — is a `multi` row with no
+ * file and no name, so neither a path-keyed map nor the record's own file can hold it. Sent
+ * without it, the record is refused whole (`identity_required`), since applying it would
+ * replace every stored item: measured 2026-09-25 on an edit of a talk's title. Banked per
+ * record from a push's finalized documents (paired by place with what was sent) and from a
+ * pull; matched on the next send by content, then by place (`@uniweb/build`'s
+ * `record-items.js`). Each record's entry is replaced whole.
+ */
+export function readRecordItemUuids(siteDir, backend) {
+  return readBackendState(siteDir, backend).recordItems || {}
+}
+export function writeRecordItemUuids(siteDir, backend, map) {
+  if (!map || !Object.keys(map).length) return
+  updateBackendMap(siteDir, backend, 'recordItems', map)
+}
+
+// The records' list items, banked from the documents the backend returned for them —
+// `returned` by `$uuid` — paired by place with the lists as sent, which ride on each record's
+// index entry (`lists`). A record keeps an entry only while it has list items, or had one.
+function bankRecordItems(siteDir, backend, pairs) {
+  const prior = readRecordItemUuids(siteDir, backend)
+  const bank = {}
+  for (const { uuid, lists, returned } of pairs) {
+    if (!uuid || !lists || !returned) continue
+    const items = harvestRecordItems(lists, returned)
+    if (Object.keys(items).length || prior[uuid]) bank[uuid] = items
+  }
+  writeRecordItemUuids(siteDir, backend, bank)
+  return Object.keys(bank).length
+}
+
+/**
+ * Recover the list-item identity of records the backend holds and this copy never banked —
+ * `uuids`, the emit's `recordItemIdentity.unbanked` — from the backend's own documents: one read
+ * of the folder lane, and nothing written but `sync.json`. The send that follows matches their
+ * items by place alone (`storedRecordItems`): what was sent before is unknown here.
+ *
+ * Best-effort, like `ensureItemUuids`: a failure leaves them unbanked, and the backend refuses
+ * the send rather than replace their items.
+ *
+ * @returns {Promise<number>} how many records were recovered
+ */
+export async function recoverRecordItemUuids({ client, siteDir, uuids, note }) {
+  const siteUuid = readBackendState(siteDir, client.origin).site?.uuid || null
+  if (!siteUuid || !uuids?.length) return 0
+  try {
+    const res = await client.pullFolder(siteUuid)
+    if (!res?.ok) return 0
+    const wanted = new Set(uuids)
+    const bank = {}
+    for (const doc of entityDocsFromUwx(Buffer.from(await res.arrayBuffer()))) {
+      if (wanted.has(doc?.$uuid)) bank[doc.$uuid] = storedRecordItems(doc)
+    }
+    writeRecordItemUuids(siteDir, client.origin, bank)
+    const n = Object.keys(bank).length
+    if (n) note?.(`Recovered the identity of the list items of ${n} record(s) from the backend.`)
+    return n
+  } catch {
+    return 0
+  }
+}
+
+/**
+ * Recover the records lane's identity this copy lacks for the site it is bound to — which stored
+ * record each of its records is (`records`), each placement's in the folder (`folders`), and the
+ * list items of the records it matches (`recordItems`) — from one read of the backend's folder
+ * lane. What the copy already holds is kept.
+ *
+ * ⛔ Until 2026-09-25 nothing recovered these, and a copy whose `sync.json` had lost them — a
+ * blog site whose push was refused after its content landed, with an older CLI — was refused on
+ * every push after: its folder sent three placements with no `$uuid` while three were stored
+ * ("one section carries no item identity (section contents)"). Unrefused, its records would have
+ * gone up with none, and the backend would have made a second entity of each.
+ *
+ * Reads only when the package names a record the map does not, or the folder map is empty; a
+ * record new to the backend costs that read and finds nothing (`matchStoredRecords`).
+ *
+ * @param {object} params
+ * @param {object[]} params.index - the records the package sends (`pkg.records.index`)
+ * @returns {Promise<number>} how many records and placements were recovered
+ */
+export async function recoverRecordsIdentity({ client, siteDir, index, note }) {
+  const state = readBackendState(siteDir, client.origin)
+  const siteUuid = state.site?.uuid || null
+  const recordMap = state.records || {}
+  const records = (index || []).filter((e) => e?.ownId && e.model && e.slug)
+  const folders = readFolderItemUuids(siteDir, client.origin)
+  const unmapped = records.some((e) => !recordMap[e.ownId])
+  if (!siteUuid || !records.length || (!unmapped && Object.keys(folders).length)) return 0
+  try {
+    const res = await client.pullFolder(siteUuid)
+    if (!res?.ok) return 0
+    const docs = entityDocsFromUwx(Buffer.from(await res.arrayBuffer()))
+    const folderDoc = docs.find((d) => d?.$schema === '@uniweb/folder')
+    if (!folderDoc) return 0
+    const learned = matchStoredRecords({ index: records, recordMap, folderDoc })
+    const matched = Object.keys(learned).length
+    if (matched) {
+      updateBackendMap(siteDir, client.origin, 'records', learned)
+      const stored = new Map(docs.map((d) => [d?.$uuid, d]))
+      const items = {}
+      for (const theirs of Object.values(learned)) {
+        const doc = stored.get(theirs)
+        if (doc) items[theirs] = storedRecordItems(doc)
+      }
+      writeRecordItemUuids(siteDir, client.origin, items)
+    }
+    const placements = collectFolderItemUuids(folderDoc)
+    const missing = Object.fromEntries(Object.entries(placements).filter(([k]) => !folders[k]))
+    writeFolderItemUuids(siteDir, client.origin, missing)
+    const placed = Object.keys(missing).length
+    if (matched || placed) {
+      note?.(`Recovered the identity of ${matched} record(s) and ${placed} folder placement(s) from the backend.`)
+    }
+    return matched + placed
+  } catch {
+    return 0
+  }
+}
+
+/**
+ * The workspace this site was created in on `backend` — its owner, as the create
+ * answered it — in the header's form: `@handle`, a unit's bare uuid when that unit has
+ * no handle, or null for the personal workspace (or no record).
+ *
+ * ⭐ A RECORD, NOT A ROUTE (2026-09-23). A command works in the workspace chosen with the
+ * login (`workspace.js`); this says where the site was made, and routes nothing. (Until
+ * then it was the workspace every request named, adopted from a `409` when stale.)
+ *
+ * Read from `backend`'s section of `sync.json`: `site.org` holds a handle, stored bare
+ * and re-dressed with its `@`; `site.unit` holds a unit's uuid. At most one is set
+ * (`writeSiteWorkspace`). ⛔ Two keys, because the `@` is the only thing telling the two
+ * apart — our own handle grammar admits a uuid-shaped handle — and a bare value at rest
+ * has lost it.
+ *
+ * @param {string} siteDir
+ * @param {string} backend - the origin whose record to read
+ * @returns {string|null}
+ */
+export function readSiteWorkspace(siteDir, backend) {
+  const site = readBackendState(siteDir, backend).site || {}
+  const org = typeof site.org === 'string' ? site.org.trim().replace(/^@/, '') : ''
+  if (org) return `@${org}`
+  const unit = typeof site.unit === 'string' ? site.unit.trim() : ''
+  return unit || null
+}
+
+/**
+ * Record the workspace this site was created in on `backend` — a handle in `site.org`
+ * (bare), a handle-less unit in `site.unit`, clearing the other; null clears both (the
+ * personal workspace, named by naming none). Returns what was recorded, in the header's
+ * form.
+ *
+ * @param {string} siteDir
+ * @param {string} backend
+ * @param {string|null|undefined} workspace - `@handle`, a unit's uuid, or null
+ * @returns {string|null}
+ */
+function writeSiteWorkspace(siteDir, backend, workspace) {
+  const w = workspaceHeader(workspace)
+  updateBackendState(siteDir, backend, {
+    site: {
+      org: w?.startsWith('@') ? w.slice(1) : undefined,
+      unit: w && !w.startsWith('@') ? w : undefined
+    }
+  })
+  return w
+}
+
+/**
+ * Record the workspace a just-minted site was created under.
+ *
+ * Only what we were TOLD is recorded — the create's echo, else the workspace the
+ * create named; a personal site has none, and guessing one would be worse than the
+ * gap. Returns the recorded workspace for the caller's "here's what resolved" line,
+ * or null when there is none.
+ *
+ * @param {string} siteDir
+ * @param {string|null|undefined} owner - in the header's form, or null
+ * @returns {string|null}
+ */
+function recordSiteWorkspace(siteDir, backend, owner) {
+  try {
+    return writeSiteWorkspace(siteDir, backend, owner)
+  } catch {
+    // The uuid is the load-bearing back-fill; losing the org note must never
+    // fail a push that already succeeded on the backend.
+    return null
+  }
+}
+
+/**
+ * Turn a typed site-create refusal into a sentence, or null to fall through to the
+ * generic HTTP line.
+ *
+ * ⭐ Why this exists separately from `describeAssetRefusal`. The asset lane grew a
+ * typed describer because a raw status dump is useless to the person who has to act
+ * on it; the create lane had the same hole and nobody had met it, because until the
+ * backend shipped account capacity a create could not be refused for space at all.
+ * So this is the same fix on the second door, written before anyone hits it rather
+ * than after.
+ *
+ * ⛔ Branch on `reason`, never on the status. `507` alone cannot be told from any
+ * other 507 and carries none of the numbers a user needs, and `detail` is prose the
+ * backend may reword.
+ *
+ * ⚖️ The wording deliberately DIVERGES from the asset lane's on one point. There the
+ * allowance belongs to the site's owner, who may not be the person pushing. Here
+ * there is no site yet, so the only workspace in play is the one the site would be
+ * created in — one named with `--org` included. Saying "the site owner's workspace"
+ * would be incoherent for a site that does not exist.
+ *
+ * @param {string} body - the raw response body
+ * @returns {string|null}
+ */
+function describeCreateRefusal(body) {
+  if (!body) return null
+  let p
+  try {
+    p = JSON.parse(body)
+  } catch {
+    return null // prose refusal, or an upstream error page
+  }
+  if (!p || typeof p !== 'object' || typeof p.reason !== 'string') return null
+
+  const attach = describeAttachRefusal(p)
+  if (attach) return [attach.headline, ...attach.steps].join('\n  ')
+
+  if (p.reason === 'storage_quota_exceeded') {
+    const parts = []
+    const used = humanBytes(p.used_bytes)
+    const limit = humanBytes(p.limit_bytes)
+    const needed = humanBytes(p.needed_bytes)
+    if (used && limit) parts.push(`${used} of ${limit} used`)
+    if (needed) parts.push(`a new site needs ${needed}`)
+    return (
+      'storage quota reached — the workspace this site would belong to has no room for it' +
+      (parts.length ? ` (${parts.join('; ')})` : '') +
+      '. Quota is returned by deleting a site or entity, not by editing content.'
+    )
+  }
+  // An unrecognised typed reason still beats a status dump: name it, and let the
+  // backend's own prose follow when it sent any.
+  const detail = typeof p.detail === 'string' ? p.detail : ''
+  return `the backend refused the site create (${p.reason})${detail ? ` — ${detail}` : ''}`
+}
+
+/**
+ * The backend's refusals to ATTACH a foundation to a site, as what happened and what to
+ * do next — or null for any other problem document.
+ *
+ * A site takes any version of a foundation it already uses, and a new one only from a
+ * scope its author owns. The create, the first push and a push that changes the site's
+ * foundation can each be refused:
+ *
+ *   `foundation_not_licensed`    not yours to attach. `templates` names the app
+ *                                templates that carry it: start from one in the app,
+ *                                then clone the site you made. With none, register a
+ *                                foundation under a scope you own.
+ *   `foundation_not_registered`  this backend has no such version.
+ *
+ * ⛔ Branch on `reason`, never on the status: a `403` is also a rejected credential, and
+ * "log in again" is the wrong advice for a foundation that is not yours. ⚠️ Until
+ * 2026-10-06 a push printed exactly that for this refusal, and the create printed the
+ * reason's bare name.
+ *
+ * @param {object|null} problem - a parsed problem document
+ * @returns {{ headline: string, steps: string[] } | null}
+ */
+export function describeAttachRefusal(problem) {
+  if (!problem || typeof problem !== 'object') return null
+  const named = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null)
+
+  if (problem.reason === 'foundation_not_licensed') {
+    const pkg = named(problem.package) || 'This foundation'
+    const templates = (Array.isArray(problem.templates) ? problem.templates : [])
+      .map((t) => named(t?.name))
+      .filter(Boolean)
+    const SHOWN = 5
+    const list =
+      templates
+        .slice(0, SHOWN)
+        .map((n) => `“${n}”`)
+        .join(', ') + (templates.length > SHOWN ? ` and ${templates.length - SHOWN} more` : '')
+    const steps = templates.length
+      ? [
+          `Start from ${templates.length === 1 ? list : `one of ${list}`} in the app — ` +
+            `${templates.length === 1 ? 'that template carries' : 'those templates carry'} it — ` +
+            "then `uniweb clone <your site's uuid>`."
+        ]
+      : ['Register a foundation under a scope you own, and name it in site.yml.']
+    return { headline: `${pkg} is not yours to attach.`, steps }
+  }
+
+  if (problem.reason === 'foundation_not_registered') {
+    const f = named(problem.foundation) || 'The foundation this site names'
+    return {
+      headline: `${f} is not registered on this backend.`,
+      steps: ['Register it here first (`uniweb register` in its directory), or name a version this backend has.']
+    }
+  }
+  return null
+}
+
+/**
+ * Guarantee the site EXISTS on the backend before anything is uploaded against it.
+ *
+ * Ordering is the point, and it is load-bearing rather than incidental. Uploaded
+ * bytes are metered against an owning entity and reclaimed by deleting it, so an
+ * upload made before any site exists is charged and can never be freed — there is
+ * nothing to delete. Creating the site first turns the artifact of a failed first
+ * publish from *unfreeable bytes* into *an empty site*, which costs nothing to
+ * 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 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 }>}
+ *   `uuid: null` means the site could not be created; the caller decides whether
+ *   that is fatal (it is, for any flow that uploads).
+ */
+export async function ensureSiteExists({
+  client,
+  siteDir,
+  name,
+  foundation,
+  note
+}) {
+  // One read serves both the binding check and the create's defaults, so callers
+  // that have no reason to hold site.yml (push) need not load it just to pass it
+  // back. An explicit argument still wins — publish supplies the PINNED foundation
+  // ref from the bring-along, which site.yml may not carry.
+  let siteYml = {}
+  try {
+    const y = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))
+    if (y && typeof y === 'object') siteYml = y
+  } catch {
+    /* unreadable site.yml — treat as un-synced and let the create decide */
+  }
+  const known = readBackendState(siteDir, client.origin).site?.uuid
+  if (known) {
+    return { uuid: known, created: false, org: readSiteWorkspace(siteDir, client.origin) }
+  }
+
+  // Both are required by the create. Catching it here turns a 400 into a sentence
+  // naming the file and the key — the difference between "fix this line of
+  // site.yml" and reading a status code.
+  const siteName = name ?? siteYml.name
+  const siteFoundation = foundation ?? siteYml.foundation
+  const missing = [!siteName && 'name', !siteFoundation && 'foundation'].filter(
+    Boolean
+  )
+  if (missing.length) {
+    return {
+      uuid: null,
+      created: false,
+      reason: `site.yml is missing ${missing.join(' and ')} — the backend requires ${missing.length > 1 ? 'them' : 'it'} to create a site`
+    }
+  }
+
+  let res
+  try {
+    // The owner is the workspace the client names — the command's (`workspace.js`).
+    res = await client.createSite({
+      name: siteName,
+      foundation: siteFoundation
+    })
+  } catch (err) {
+    return { uuid: null, created: false, reason: err.message }
+  }
+  if (!res?.ok) {
+    const body = await res?.text?.().catch(() => '')
+    return {
+      uuid: null,
+      created: false,
+      // 404 here means the backend predates the route, which is a materially
+      // different problem from being refused — say which.
+      reason:
+        res?.status === 404
+          ? 'this backend has no /dev/site route (it predates the empty-site create)'
+          : (describeCreateRefusal(body) ??
+            `HTTP ${res?.status} ${res?.statusText || ''}${body ? ` — ${body.slice(0, 200)}` : ''}`)
+    }
+  }
+  const payload = await res.json().catch(() => null)
+  const minted = extractMintedSiteUuid(payload)
+  if (!minted) {
+    return {
+      uuid: null,
+      created: false,
+      reason: 'the create returned no site uuid'
+    }
+  }
+  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, client.origin, { siteUuid: minted })
+  const org = await recordAndDescribeOwner({ client, siteDir, payload, note })
+  return { uuid: minted, created: true, org }
+}
+
+/**
+ * Record and announce who owns a just-created site, from the backend's own echo.
+ *
+ * The echo reports what the site **is**; the workspace the create named
+ * (`client.workspace`) is only what we asked for. They agree in the normal case and the
+ * echo is the one to trust — it is read back off the created entity.
+ *
+ * ⚠️ `org: null` is MEANINGFUL (personal), not missing. An older backend omits the
+ * key entirely, which is the only case that falls back to what we asked for.
+ *
+ * @returns {Promise<string|null>} the display handle recorded, or null for personal
+ */
+async function recordAndDescribeOwner({ client, siteDir, payload, note }) {
+  const echoed = payload && 'org' in payload ? payload.org : undefined
+  const owner =
+    echoed === undefined
+      ? client.workspace
+      : typeof echoed === 'string'
+        ? workspaceHandle(echoed)
+        : null
+  const org = recordSiteWorkspace(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 ${client.origin} under ${describeWorkspace(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.
+  //
+  // `hosts_free` is a property of the SCOPE — is this owner exempt? — and it is the only
+  // billing fact the CLI holds. This used to JOIN it with `siteSubscriptionRequired`
+  // from the discovery document, a property of the DEPLOYMENT. That leaf left the wire:
+  // every deployment charges, so it read true everywhere and the join was testing a
+  // constant.
+  //
+  // ⛔ AND THE WARNING WENT WITH IT — this is NOT a fallback to keying on the scope
+  // alone, which is the exact thing the join existed to prevent. Whether a given publish
+  // is charged is derived per-site at publish time, on a side the CLI cannot see, so any
+  // prediction made here can only be approximately right and would go stale silently.
+  // The backend's typed 402 (`reason: "no_subscription"`) is exact, per-site, and
+  // arrives when it matters; `backend/payment-handoff.js` already turns it into a
+  // checkout. Deciding whether payment is due is not the CLI's job.
+  //
+  // ⇒ What survives is the reassuring direction only, and only when it was stated:
+  // `false` is an answer we deliberately do not speak to, and missing is not an answer
+  // at all. Do not reintroduce a "you will be charged" line here.
+  if (payload?.hosts_free === true) {
+    note?.(
+      'This owner is hosted free — publishing will not require a subscription.'
+    )
+  }
+  return org
+}
+
+/**
+ * Stop a push or publish before it sends anything, when a record cannot be sent as
+ * written — the emit's `refusals` (`@uniweb/build`'s `recordsToEntities`).
+ *
+ * ⛔ Checked BEFORE the site is created or a byte uploaded, not only before the send:
+ * both are writes of their own, which a refused records lane does not undo. (The lane
+ * itself is one transaction on the backend since 2026-09-24, so a refusal there writes
+ * nothing. Before that, a refused lane left the folder's entries and entities with no
+ * data behind, and every later push of the site's records was refused — measured
+ * 2026-09-23, from one record written by section.)
+ *
+ * @param {string[]|undefined} refusals
+ * @param {{ error: (m: string) => void, note: (m: string) => void }} report
+ * @returns {boolean} true when the caller must stop
+ */
+export function refuseUnsendableRecords(refusals, { error, note }) {
+  if (!refusals?.length) return false
+  const n = refusals.length
+  error(
+    `${n === 1 ? 'A record' : `${n} records`} cannot be pushed as written — no content was sent.`
+  )
+  for (const r of refusals) note(`  ${r}`)
+  return true
+}
+
+/**
+ * Guarantee we have per-item identity before an identity-bearing push.
+ *
+ * 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.)
+ *
+ * ⚠️ A PARTIAL map is not this function's: it runs before the package is built, when
+ * nothing yet says which items went without identity. `recoverUnbankedIdentity` runs
+ * after, and fills in what is missing.
+ *
+ * @returns {Promise<Object<string,string>>} the map (possibly empty)
+ */
+export async function ensureItemUuids({ client, siteDir, note }) {
+  const cached = readItemUuids(siteDir, client.origin)
+  if (Object.keys(cached).length) return cached
+  const harvested = await storedItemUuids({ client, siteDir })
+  if (!harvested || !Object.keys(harvested).length) return cached
+  writeItemUuids(siteDir, client.origin, harvested)
+  note?.(`Recovered identity for ${Object.keys(harvested).length} item(s) from the backend.`)
+  return harvested
+}
+
+/**
+ * Each page and section `$uuid` the backend holds for the site this copy is bound to, by
+ * the path it projects to — one read of its own document. Null when the copy is bound to
+ * no site there (a site never pushed has no identity to recover, and nothing to lose,
+ * since every item is genuinely new) or the read fails.
+ *
+ * Best-effort: a failure leaves the push identity-blind, which the backend refuses rather
+ * than silently applying. Better to hit that than to guess.
+ *
+ * @returns {Promise<Object<string,string>|null>}
+ */
+async function storedItemUuids({ client, siteDir }) {
+  // 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 null
+  try {
+    const res = await client.pullSiteContent(siteContentUuid)
+    if (!res?.ok) return null
+    const doc = entityDocFromUwx(Buffer.from(await res.arrayBuffer()))
+    return doc ? collectUnitUuids(doc) : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Fill in the page and section identity this copy LACKS for the site it is bound to, from
+ * the backend's own document. What the copy already holds is kept.
+ *
+ * ⛔ `ensureItemUuids` recovers only an EMPTY map, and a map can be partial: until
+ * 2026-09-25 a push whose records were refused after its pages landed saved the pages'
+ * identity nowhere (`pushSyncPackages`), leaving the map with `site.yml` alone. Every push
+ * after that sent the pages with no `$uuid` while the backend held them, and was refused —
+ * "one section carries no item identity (section pages)" — with nothing ever recovering it.
+ *
+ * @returns {Promise<number>} how many pages and sections were recovered
+ */
+export async function recoverItemUuids({ client, siteDir, note }) {
+  const cached = readItemUuids(siteDir, client.origin)
+  const harvested = await storedItemUuids({ client, siteDir })
+  if (!harvested) return 0
+  const missing = Object.keys(harvested).filter((path) => !cached[path])
+  if (!missing.length) return 0
+  writeItemUuids(siteDir, client.origin, { ...harvested, ...cached })
+  note?.(`Recovered identity for ${missing.length} item(s) from the backend.`)
+  return missing.length
+}
+
+/**
+ * Recover the identity a package just built went out without, when the backend may hold it —
+ * a page or section (`itemIdentity.unknown`), a record or a folder placement
+ * (`recoverRecordsIdentity`), or a record's list items (`recordItemIdentity.unbanked`) — and say
+ * what to build the package again with.
+ *
+ * A page added since the last push is also without identity, and costs one read that finds
+ * nothing. That is the price of never sending as new an item the backend already holds.
+ *
+ * @returns {Promise<object|null>} emit options to build the package again with, or null
+ *   when nothing was recovered
+ */
+export async function recoverUnbankedIdentity({ client, siteDir, pkg, note }) {
+  let again = null
+  if (pkg?.itemIdentity?.unknown > 0 && (await recoverItemUuids({ client, siteDir, note }))) {
+    again = { ...again, itemUuids: readItemUuids(siteDir, client.origin) }
+  }
+  // The records the package sends, and the folder placing them. The emit reads the `records`
+  // map from sync.json itself, so it needs no option — only the build again.
+  // Link records are matched as records are — by Model and name (`@uniweb/link`, `link-records.js`).
+  const links = (pkg?.records?.links || []).map((l) => ({ ownId: l.ownId, model: LINK_MODEL, slug: l.slug }))
+  if (await recoverRecordsIdentity({ client, siteDir, index: [...(pkg?.records?.index || []), ...links], note })) {
+    again = {
+      ...again,
+      folderItemUuids: readFolderItemUuids(siteDir, client.origin),
+      recordItemUuids: readRecordItemUuids(siteDir, client.origin)
+    }
+  }
+  const unbanked = pkg?.recordItemIdentity?.unbanked
+  if (unbanked?.length && (await recoverRecordItemUuids({ client, siteDir, uuids: unbanked, note }))) {
+    again = { ...again, recordItemUuids: readRecordItemUuids(siteDir, client.origin) }
+  }
+  return again
+}
+
+export function readUnitBases(siteDir, backend) {
+  const v = readMap(siteDir, backend, 'unitBases')
+  return { local: v.local || {}, remote: v.remote || {} }
+}
+export function writeUnitBases(siteDir, backend, patch) {
+  if (!patch) return
+  updateSyncCache(siteDir, backend, {
+    unitBases: { ...readUnitBases(siteDir, backend), ...patch }
+  })
+}
+
+/**
+ * Offline-probe how many of a site's entities differ from the last successful push.
+ * Runs the SAME emit + send-only-changed diff `uniweb push` runs, but with an
+ * OFFLINE Model resolver — no auth, no submit, no backend round-trip. Used by
+ * `uniweb status` only. (It was also `uniweb publish`'s pre-flight back when publish
+ * went live WITHOUT pushing and so had to warn about unpushed content; publish now
+ * always pushes, which makes the warning moot.) Throws if the producer can't build
+ * the sync packages (e.g. an unresolved data Model); callers report it.
+ *
+ * @param {string} siteDir
+ * @returns {Promise<{ changed: number, unchanged: number, warnings: string[] }>}
+ */
+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 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.
+  //
+  // ⛔ A site's `@/member` must resolve to the same `@scope/member` the push keyed its
+  // hashes by, or every record of a `@/`-scoped query reads as changed forever — and
+  // silently, since `@std/…` queries are absolute and settle while the others never
+  // do (measured on matinee 2026-08-29: 4 changed right after a push). The scope is
+  // the FOUNDATION's, which the emit reads itself, so both sides resolve alike.
+  // ⚠️ Until 2026-09-23 this said the site's recorded ORG resolves it and must be
+  // passed in — true before 2026-09-22, and read as a reason to pass it.
+  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 || [] }
+}
+
+/**
+ * The emit whose hashes are comparable with the banked ones — ONE definition.
+ *
+ * ⛔ EVERY DEFECT IN THIS AREA HAS BEEN A WRITER AND A READER DISAGREEING ABOUT
+ * WHICH DOCUMENT A HASH DESCRIBES, so the option set that makes them agree must
+ * have a single home. Assembled from three sources, each for a stated reason:
+ *
+ *   · 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 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 collection identity a push stamps, so the document is the
+ *                one a push builds. (A site's `@/x` resolves into its foundation's
+ *                scope, which the emit reads itself — not the site's org, which this
+ *                bullet named until 2026-09-23.)
+ *                ⚠️ 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,
+  { backend = null, priorHashes = {}, sendAll = false, declarations = null, fields = null } = {}
+) {
+  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 queryUuids = readQueryUuids(siteDir, backend)
+  return emitSyncPackages(siteDir, {
+    backend,
+    // Offline, always. A caller that has just read the Models from the backend — a pull —
+    // may hand them in: the declarations a push would resolve, so the hashes still compare.
+    // Without them a site whose foundation is not in the project (a clone's) resolves none
+    // of its Models here, and nothing is banked.
+    resolveModel: declarations
+      ? async (name) => declarations.get(name) ?? null
+      : makeModelResolver({ client: null, offline: true, siteDir, backend }),
+    priorHashes,
+    sendAll,
+    ...applied,
+    // The deployment's own answer (`deploymentFields`), when the caller has just read it, over what
+    // the last push banked.
+    ...(fields || {}),
+    ...(Object.keys(queryUuids).length ? { queryUuids } : {}),
+    ...(Object.keys(assetIds).length ? { assetIds } : {})
+    // ⛔ No `org`: a site's `@/x` refs resolve into its FOUNDATION's scope, which the
+    // emit reads itself — the same read a push makes, so the hashes compare alike.
+  })
+}
+
+/**
+ * Re-bank the send-only-changed hashes over the files as they NOW stand.
+ *
+ * ⛔ FOR A WRITER THAT REWRITES THE WORKING TREE — today, `uniweb pull`.
+ *
+ * A pull projects the backend's document into source files, and that projection is
+ * canonical rather than byte-identical to what was there: it moves section ordering
+ * out of filename prefixes (`1-hero.md` → `hero.md` plus an explicit `sections:`
+ * list) and stamps each section's `id`. Lossless, and a different document.
+ *
+ * ⚠️ `pull` already knew this for the OTHER map — it clears the `local` unit base
+ * because "what we would emit from them is not byte-identical to it, so the old
+ * local base no longer describes anything". That reasoning was never carried to the
+ * hashes, which were left STALE rather than unknown: the next `uniweb status`
+ * reported the site as having unpushed content immediately after a pull, forever.
+ * Measured on matinee 2026-08-29 — `push → pull` reported 1 changed of 8.
+ *
+ * ⭐ Re-banking is the correct answer rather than clearing, because after a pull the
+ * 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.
+ *
+ * @param {object} [opts]
+ * @param {object[]} [opts.recordDocs] - the record documents the pull took; their list items'
+ *        identity is banked against the files just written (`readRecordItemUuids`)
+ * @param {Map<string,object>} [opts.declarations] - the Models the pull read, by name — so a
+ *        site whose foundation is not in the project (a clone's) can be re-banked offline
+ */
+export async function rebankSyncHashes(siteDir, backend = null, { recordDocs, declarations, fields = null } = {}) {
+  // ⛔ With the keys this deployment's Sections take, when the caller has them (`deploymentFields`):
+  // they shape the document the next push sends (`typed_by_data_key`, `og_title`), so a hash banked
+  // without them marks a clone's first push as changed. Until 2026-09-26 a pull banked none.
+  const pkg = await comparisonEmit(siteDir, { backend, sendAll: true, declarations, fields })
+  writeSyncCache(siteDir, backend, onlyWhatThePullTook(siteDir, backend, pkg, recordDocs), pkg.applied || {})
+  // ⭐ And the identity of the records' list items, from the documents the pull just took:
+  // the files it wrote hold the stored items in stored order, so the emit over them pairs
+  // with each document item for item.
+  if (recordDocs?.length) {
+    const byUuid = new Map(recordDocs.filter((d) => d?.$uuid).map((d) => [d.$uuid, d]))
+    const recordUuids = readBackendState(siteDir, backend).records || {}
+    bankRecordItems(
+      siteDir,
+      backend,
+      (pkg.records?.index || []).map((entry) => {
+        const uuid = entry.ownId ? recordUuids[entry.ownId] : null
+        return { uuid, lists: entry.lists, returned: uuid ? byUuid.get(uuid) : null }
+      })
+    )
+  }
+  return Object.keys(pkg.hashes || {}).length
+}
+
+/**
+ * The hashes a pull may bank: the tree's, except for a record the pull did not take.
+ *
+ * ⛔ ONLY WHAT CAME FROM THE BACKEND IS AGREED. A record on disk that the backend did not
+ * hand back — written since the last push, or one a push had refused — is not in sync
+ * because a pull ran. Until 2026-09-26 it was banked with the rest, so every later push
+ * skipped it and `uniweb status` said "in sync": a record written before a `uniweb sync`
+ * (which pulls, then pushes) never reached the backend. One this backend never accepted —
+ * no identity from it — is always sent: a hash it has banked can only be that mistake's.
+ * One it did accept keeps what the last push banked. The folder keeps its hash too while
+ * it places such a record. A pull that took no records (`--no-records`, a 304) leaves
+ * every record's hash as it was.
+ *
+ * @param {object[]|undefined} recordDocs - the record documents the pull took
+ */
+function onlyWhatThePullTook(siteDir, backend, pkg, recordDocs) {
+  const hashes = { ...(pkg.hashes || {}) }
+  const prior = readSyncCache(siteDir, backend)
+  const keep = (key) => {
+    if (Object.hasOwn(prior, key)) hashes[key] = prior[key]
+    else delete hashes[key]
+  }
+  const taken = new Set((recordDocs || []).map((d) => d?.$uuid).filter(Boolean))
+  const recordUuids = readBackendState(siteDir, backend).records || {}
+  let notTaken = 0
+  for (const entry of pkg.records?.index || []) {
+    if (entry.kind === 'folder') continue // the folder itself — held below while it places one
+    const theirs = entry.ownId ? recordUuids[entry.ownId] : null
+    if (theirs && taken.has(theirs)) continue
+    notTaken++
+    const key = `${entry.model} ${entry.id}`
+    if (theirs) keep(key)
+    else delete hashes[key]
+  }
+  if (notTaken) for (const key of Object.keys(hashes)) if (key.startsWith('@uniweb/folder ')) keep(key)
+  return hashes
+}
+
+/**
+ * Re-bank the hashes of the records a push sent naming a record it created — `keys`,
+ * the emit's `namesNew` — as the next push will hash them, and fingerprint their list
+ * items the same way.
+ *
+ * ⭐ Such a record names its new record by `$ref`, and the backend stores the uuid it
+ * mints. The next push names it by that uuid: the same reference, and another hash — so
+ * the hash the push banked describes a document no later emit builds, and the next push
+ * would send every one of these records again. Re-sending is not harmless: a record's
+ * list-section items go without the identity a re-send needs (`identity_required`).
+ *
+ * ⚖️ Only these keys, over the hashes the push just banked: the site-content lane and
+ * the folder are banked as that push sent them, and a caller's own emit options (a
+ * publish that does not declare services) are not the comparison emit's.
+ */
+export async function rebankRecordHashes(siteDir, backend, keys) {
+  if (!keys?.length) return
+  const pkg = await comparisonEmit(siteDir, { backend, sendAll: true })
+  const hashes = { ...readSyncCache(siteDir, backend) }
+  for (const key of keys) if (pkg.hashes?.[key]) hashes[key] = pkg.hashes[key]
+  writeSyncCache(siteDir, backend, hashes, readAppliedInjections(siteDir, backend))
+  // Their list items too: an item that named a new record is fingerprinted anew, each uuid kept
+  // at its place (`reprintRecordItems`) — or the next send finds it by place alone.
+  const wanted = new Set(keys)
+  const recordUuids = readBackendState(siteDir, backend).records || {}
+  const bank = readRecordItemUuids(siteDir, backend)
+  const reprinted = {}
+  for (const entry of pkg.records?.index || []) {
+    if (!wanted.has(`${entry.model} ${entry.id}`)) continue
+    const uuid = entry.ownId ? recordUuids[entry.ownId] : null
+    if (uuid && bank[uuid]) reprinted[uuid] = reprintRecordItems(bank[uuid], entry.lists)
+  }
+  writeRecordItemUuids(siteDir, backend, reprinted)
+}
+
+/**
+ * What a push did with the site's `template:` intent — read from the backend's own
+ * reply, never inferred from what we sent.
+ *
+ * The field is `template`, carrying `designated` or `undesignated`, and it is ABSENT
+ * when the designation did not move (backend, collab framework↔backend #6, 2026-09-23;
+ * kb/framework/reference/template-designation-on-push.md E6).
+ *
+ * ⛔ TWO STATES, NOT THREE — and silence means "unchanged", never "failed". A push that
+ * asks to designate where the backend will not is REFUSED WHOLE, and that refusal
+ * carries its own message (§6), so there is no asked-but-skipped state to print here.
+ *
+ * ⚠️ Backend named the field, not its nesting, so the top level and `report` are both
+ * read; and an unrecognized value is printed verbatim rather than dropped, because a
+ * state we do not know about rendering as SILENCE is the exact failure this line exists
+ * to prevent.
+ *
+ * @param {object|null} payload - the parsed push/create response
+ * @returns {string|null} the state as the backend spelled it
+ */
+export function templateOutcome(payload) {
+  const v = payload?.template ?? payload?.report?.template
+  return typeof v === 'string' && v.trim() ? v.trim() : null
+}
+
+/** The sentence for each state the backend can report. */
+const TEMPLATE_SAID = {
+  designated: 'The backend designated this site as a template.',
+  undesignated: 'The backend undesignated this site — it is no longer a template.'
+}
+
+/**
+ * Submit a site's emitted sync packages over both directional lanes, back-fill the
+ * minted uuids, and persist the send-only-changed cache. The HTTP + file-write-back
+ * half that `emitSyncPackages` (producer-pure) deliberately omits.
+ *
+ * @param {object} params
+ * @param {object} params.client - BackendClient (carries the origin + the lane methods)
+ * @param {string} params.siteDir - the site root (for $uuid write-back + the cache)
+ * @param {object} params.pkg - the `emitSyncPackages` result
+ *        ({ siteContent, collections, siteContentUuid, hashes })
+ * @param {{info,note,error,dim?:Function}} params.report - injected logging
+ * @returns {Promise<{ exitCode: number, boundSiteUuid?: string, finalizedTotal: number, wrote: string[] }>}
+ *   exitCode 1 on any lane failure (already reported, cache NOT persisted); 0 on success.
+ */
+export async function pushSyncPackages({
+  client,
+  siteDir,
+  pkg,
+  report
+}) {
+  const { siteContent, records, siteContentUuid, hashes, applied } = pkg
+  const { info, note, error } = report
+  const dim = report.dim || ((s) => s)
+
+  const wrote = []
+  let finalizedTotal = 0
+  // Records sent as drafts that the backend stored enabled — reported at the end.
+  let draftsNotKept = []
+
+  // POST one lane via the client and parse the JSON response. `doRequest` is a thunk
+  // returning the client's Response promise (so the "Pushing …" line prints before the
+  // request fires). The client carries `collision=force` (last-push-wins) and names the
+  // site's workspace. Returns the parsed payload, or null on any transport/HTTP/parse
+  // failure (already reported).
+  // `boundUuid` is set only for the lanes that address an EXISTING site by uuid
+  // (content UPDATE, folder push) — never for the CREATE, which has no uuid to be
+  // wrong about. It is what lets a 404 be read as "the site this clone is bound to
+  // is gone" rather than "the route is missing".
+  const postLane = async (
+    label,
+    doRequest,
+    explainStale = async () => [],
+    { boundUuid = null, reportTemplate = false } = {}
+  ) => {
+    info(`Pushing ${label} to ${dim(client.origin)} …`)
+    let res
+    try {
+      res = await doRequest()
+    } catch (err) {
+      error(describeRequestError(err, client.origin))
+      if (!(err instanceof WorkspaceMismatchError))
+        note('Is that the backend you meant? Switch with: uniweb login --server <url>')
+      return null
+    }
+    if (!res.ok) {
+      const body = await res.text().catch(() => '')
+      // Two unrelated conflicts share HTTP 409, so branch on the machine-readable
+      // `reason` — never on `detail`, which is prose the backend may reword.
+      let problem = null
+      if ((res.status === 409 || res.status === 400 || res.status === 403 || res.status === 422) && body) {
+        try {
+          problem = JSON.parse(body)
+        } catch {
+          /* not a problem document */
+        }
+      }
+      // A foundation the site may not take (`foundation_not_licensed`, a 403) or that this
+      // backend does not have (`foundation_not_registered`) — said, with what to do next.
+      // Before the credential branch below, which a 403 would otherwise reach.
+      const attach = describeAttachRefusal(problem)
+      if (attach) {
+        error(`${label} push refused — ${attach.headline}`)
+        for (const step of attach.steps) note(step)
+        return null
+      }
+      // The package carried no identity for records the backend already stores, so
+      // applying it would replace every one of them. `ensureItemUuids` is supposed
+      // to make this unreachable, so reaching it means that recovery failed — say so
+      // rather than surfacing a raw 400.
+      // The cache is offering another site's item identities. Recoverable without
+      // the user knowing what a sync cache is: the stale maps are unambiguously
+      // wrong (they describe a different entity), so clear them and say re-run.
+      //
+      // Reachable only for a clone broken BEFORE the pre-flight guard existed —
+      // 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, client.origin, boundUuid)
+        error(
+          `${label} push refused — this copy's sync cache is describing a different site.`
+        )
+        note('Nothing was written.')
+        if (Number.isInteger(problem.stored_entity_id)) {
+          note(
+            `Item ${problem.item_uuid ?? '(unnamed)'} already belongs to entity ${problem.stored_entity_id}; this push is for entity ${problem.document_entity_id}.`
+          )
+        }
+        if (dropped.length) {
+          note(
+            `Cleared the stale cache (${dropped.join(', ')}) — re-run the same command and it will push cleanly.`
+          )
+        } else {
+          note(
+            'The cache held nothing to clear, so this is not the usual cause — please report it.'
+          )
+        }
+        return null
+      }
+      if (problem?.reason === 'identity_required') {
+        // ⛔ THE REFUSAL IS PER-SECTION, NOT PER-PUSH, AND WE USED TO SAY OTHERWISE.
+        //
+        // The backend asks, of each section independently: is this section's ENTIRE
+        // incoming record set uuid-less while the stored entity already has items in
+        // it? So a push can carry correct identity for most of the document and still
+        // be refused over one section it stamps none of — and the old wording ("this
+        // copy has no record of the site's item identity", "the recovery … could not
+        // reach the backend", "`uniweb pull` also restores it") was wrong on all
+        // three counts in exactly that case: the copy has identity, no recovery was
+        // attempted, and a pull changes nothing.
+        //
+        // ⭐ THE BACKEND ALREADY SENDS WHAT LOCATES IT — `section_id`,
+        // `records_without_uuid`, `stored_items` — and this branch discarded every
+        // one of them, so every refusal anyone collected was missing the only fields
+        // that say WHERE. (Named by backend in collab framework↔backend,
+        // 2026-08-28: "the offending section and both counts have been in the body of
+        // every refusal you have collected".)
+        const n = problem.records_without_uuid
+        const stored = problem.stored_items
+        // `section_name` landed backend-side 2026-08-28 (`90e7cd7e`), replacing an
+        // i64 row id we could not resolve. The fallback stays for an older backend,
+        // not because the swap is pending — it is done.
+        const where = problem.section_name ?? problem.section_id
+        error(
+          `${label} push refused — one section carries no item identity` +
+            (where === undefined ? '.' : ` (section ${where}).`)
+        )
+        if (Number.isInteger(n) && Number.isInteger(stored)) {
+          note(
+            `That section sent ${n} record(s), none carrying a \`$uuid\`, while ${stored} item(s) are already stored there.`
+          )
+        }
+        note(
+          'Nothing was written. Applying it would have replaced the identity of every stored item in that section.'
+        )
+        // ⚠️ Deliberately NOT "run `uniweb pull`". A pull re-harvests identity from
+        // the backend's own document, so it fixes a LOST cache — and does nothing at
+        // all when the cache is intact and one section simply has no entry in it,
+        // which is the case this message now names. Suggesting it there sends the
+        // user to re-fetch a map they already have.
+        if (problem.detail) note(String(problem.detail))
+        return null
+      }
+      // ⭐ A RECORD KEEPS ITS TYPE. A record file moved to another type's folder keeps its `$uuid`, and
+      // the backend refuses it as that type (`type_changed`, naming the record and both types), before
+      // writing anything. Storing it as the new type makes it a new record.
+      if (problem?.reason === 'type_changed') {
+        error(`${label} push refused — a stored record would change its type.`)
+        if (problem.detail) note(String(problem.detail))
+        note(
+          'A record keeps its type. To store it as the new type, make it a new record: delete the ' +
+            '`$uuid` line from its file, then push again.'
+        )
+        return null
+      }
+      if (problem?.reason === 'stale_base') {
+        error(
+          `${label} push refused — the backend has newer content than your last pull.`
+        )
+        // Page-level account, when we can get one. The gate is entity-grained, so
+        // without this the user only learns "the document moved" and has no basis
+        // for choosing between pulling and forcing.
+        const detail = await explainStale()
+        for (const line of detail) note(line)
+        // ⭐ Items no file path names — a service, a query — come named by their Section's
+        // key (`stale_keys`, `{ section, key: { name } }`), so say them by name.
+        const keyed = describeStaleKeys(problem.stale_keys)
+        for (const line of keyed) note(line)
+        if (!detail.length && !keyed.length) {
+          const stale = Array.isArray(problem.stale_entities)
+            ? problem.stale_entities
+            : []
+          if (stale.length) {
+            note(
+              `Changed upstream: ${stale.length} entit${stale.length === 1 ? 'y' : 'ies'} (${stale.join(', ')})`
+            )
+          }
+        }
+        note(
+          'Nothing was written — the whole push was refused before any change.'
+        )
+        // Say what will actually work from HERE. Anyone hitting this has local
+        // work — it is why they pushed — and if it is uncommitted then `pull`
+        // refuses too, so bare "run pull" advice walks them into a dead end.
+        if (hasUncommittedContent(siteDir)) {
+          // `--merge` is the recovery that keeps both sides: most of these are two
+          // people editing different parts of one section, which merges silently.
+          // Offer it first, and keep the take-theirs route for anyone who wants it.
+          note(
+            "Commit your changes, then `uniweb pull --merge` to combine them with the backend's."
+          )
+          note(
+            '(Plain `uniweb pull` declines while the work is unsaved — it overwrites rather than merges.)'
+          )
+        } else {
+          note(
+            'Run `uniweb pull --merge` to combine the changes, or `uniweb pull` to take the backend version.'
+          )
+        }
+        note(
+          'To overwrite them anyway, re-run with --force (this discards the upstream edits).'
+        )
+        return null
+      }
+      error(`${label} push rejected: HTTP ${res.status} ${res.statusText}`)
+      if (res.status === 401 || res.status === 403) {
+        note(
+          "Credentials weren't accepted — log in again (`uniweb login --server <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
+        // verb that could have removed it — a site is deleted in the Uniweb app,
+        // and that is what severs the sync — so the raw 404 leaves the user with
+        // no idea that the fix is local and one line.
+        //
+        // ⛔ ORDER THESE TWO CAUSES, and put the RECOVERABLE one first. Until 2026-08-24
+        // 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. 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}.`
+        )
+        note(
+          'Two causes. Check the cheap one first: is this the backend the site lives on?'
+        )
+        note(
+          `  wrong backend  →  uniweb login --server <the right one>   (nothing is lost)`
+        )
+        note(
+          `  deleted there  →  uniweb forget --server ${client.origin}, then push again: it creates a NEW site`
+        )
+        note('Deleting this folder removes only your local copy, either way.')
+      } else if (problem?.reason === 'template_records_not_copyable' && Array.isArray(problem.records)) {
+        // ⭐ A push asking to designate the site a template is refused whole when a record in its
+        // folder cannot be copied into the sites made from it — each named, with a `detail` written
+        // to be shown. Until 2026-09-28 this printed the raw problem document, cut at 800 characters.
+        note(problem.title || 'These records cannot be copied into a template:')
+        for (const r of problem.records) {
+          note(`  ${r?.name ?? '(unnamed)'} — ${r?.detail || r?.reason || 'no reason given'}`)
+        }
+        return null
+      } else if (res.status === 409 && (problem?.title || problem?.detail)) {
+        // ⛔ A 409 names its own cause — a reference the store refuses, a rule of the record's type,
+        // an append-only section — so it is shown as the backend put it, not explained by us. Until
+        // 2026-09-26 every one was explained as "this site's record structure is already established
+        // … push it as a new site", a rule the backend no longer has, and it misled over a refused
+        // reference. (`stale_base` and `item_uuid_conflict` have their own explanations, above.)
+        note([problem.title, problem.detail].filter(Boolean).join(' — '))
+        return null
+      }
+      if (body) note(body.slice(0, 800))
+      return null
+    }
+    let payload
+    try {
+      payload = await res.json()
+    } catch (err) {
+      error(`Could not parse the ${label} response as JSON: ${err.message}`)
+      return null
+    }
+    // The designation outcome rides on the site-content lanes only — the one place
+    // the author's `template:` intent was sent.
+    if (reportTemplate) {
+      const state = templateOutcome(payload)
+      if (state) {
+        note(
+          TEMPLATE_SAID[state] ||
+            `The backend reported the template state as "${state}".`
+        )
+      }
+    }
+    return payload
+  }
+
+  // POST a lane that round-trips entity uuids (content UPDATE + the folder): parse the
+  // finalized list (for record back-fill + the changed summary). Returns the finalized
+  // array, or null on failure (already reported).
+  const pushLane = async (label, doRequest, explainStale, opts) => {
+    const payload = await postLane(label, doRequest, explainStale, opts)
+    if (payload === null) return null
+    const finalized = extractFinalized(payload)
+    if (!finalized) {
+      error(
+        `The ${label} response carried no recognizable finalized list (expected report.finalized[] with index + uuid).`
+      )
+      note(JSON.stringify(payload).slice(0, 800))
+      return null
+    }
+    const summary = changedSummary(finalized)
+    if (summary) note(`${label}: ${summary}`)
+    return finalized
+  }
+
+  // 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 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 —
+  // otherwise the next attempt would re-send lane 1 with a base the backend has
+  // already moved past, and refuse a push the user just made.
+  const newVersions = {}
+  // Per-item tokens from the SAME response — the site-content entity's, keyed by item
+  // `$uuid`: the whole set this copy now holds (`heldTokens`), which replaces the one
+  // it held. Null until that lane lands, which leaves the held set as it was.
+  // ⛔ The records lane's are not kept: that lane is gated by its entity version, and
+  // until 2026-10-07 they were merged into the same map, which was sent for nothing.
+  //
+  // ⛔ Both grains must be re-armed from the push, for one reason: a push writes,
+  // so every token this clone holds for a record it just changed is now stale. Read
+  // on pull only, push 2 classifies that record `pkg != base, host != base` and the
+  // backend refuses it — a conflict naming records nobody else touched, on a second
+  // push with no edit in between. And it is unrecoverable locally, because the
+  // tokens are opaque by contract: a pull would be the only other source, and a
+  // pull rewrites the working tree. That is precisely the `--force` habit the gate
+  // exists to prevent. Returning the entity `version` on push was added to fix this
+  // exact shape one grain up (see delivery-lane.md "Both feed directions are
+  // load-bearing"); the item grain had the same hole until backend `d7e46335`
+  // started echoing `item_versions` here.
+  let heldItemVersions = null
+  const harvest = (finalized) => {
+    for (const f of finalized || []) {
+      // NOT gated on `changed`: the backend pins "zero-write ⇒ version unmoved", so a
+      // no-op resubmit hands back the value we already hold. (The site-content lane
+      // filters first, `harvestSiteContent`.)
+      if (f.uuid && f.version) newVersions[f.uuid] = f.version
+    }
+  }
+  // Both grains land together, at every point the old code banked the entity one.
+  const mergeHarvested = () => {
+    mergeBaseVersions(siteDir, client.origin, newVersions)
+    if (heldItemVersions) writeItemBaseVersions(siteDir, client.origin, heldItemVersions)
+  }
+  // ⛔ The site-content lane banks only the tokens for content this copy holds — the
+  // document we sent against the one the backend stored (`heldTokens`, and the two
+  // losses banking everything caused). What the backend kept for someone else is
+  // collected here, to re-base attribution and to say so.
+  const sentSiteDoc = siteContent ? entityDocFromUwx(siteContent.buffer) : null
+  const notHeld = { kept: [], foreign: [] }
+  const heldUnits = []
+  const harvestSiteContent = (finalized) => {
+    for (const f of finalized || []) {
+      const held = heldTokens({
+        sent: sentSiteDoc,
+        written: f.document,
+        version: f.version,
+        itemVersions: f.itemVersions,
+        held: heldItemVersions ?? readItemBaseVersions(siteDir, client.origin)
+      })
+      harvest([{ ...f, version: held.version }])
+      if (held.itemVersions) heldItemVersions = held.itemVersions
+      heldUnits.push(...held.held)
+      notHeld.kept.push(...held.kept)
+      notHeld.foreign.push(...held.foreign)
+    }
+  }
+  // The backend's post-write copy of the site-content document, kept for the
+  // remote-side unit base (see writeUnitBases).
+  let siteFinalizedDoc = null
+  // ⭐ WHAT THE SITE-CONTENT LANE LANDED IS SETTLED THE MOMENT IT LANDS — its query and item
+  // identity, its unit bases and the files it now holds as synced — on either path to it.
+  // ⛔ Until 2026-09-25 the item identity and the bases were settled at the END, after the
+  // records lane, so a records lane that was refused returned before them: the pages were
+  // stored, their identity was saved nowhere, and every later push sent them without it and
+  // was refused — "one section carries no item identity (section pages)" — while the
+  // queries, banked at once, were kept. And the queries were banked on the update path
+  // only, so a site created with no media never saved theirs.
+  const settleSiteContent = () => {
+    // ⭐ 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
+    // `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, client.origin, recordIds)
+      // ⭐ THE SERVICES THIS COPY NOW HOLDS, `{ name: $uuid }`: those the push stated and
+      // those held before, as the site returned them (`heldServices`). A service added on
+      // the site since this copy's last pull is left out — held, the next push would state
+      // it off, switching off a service nobody here has seen. Replaced, not merged.
+      updateBackendState(siteDir, client.origin, {
+        services: heldServices({
+          written: siteFinalizedDoc.services,
+          sent: Array.isArray(sentSiteDoc?.services) ? sentSiteDoc.services : [],
+          prior: readBackendState(siteDir, client.origin).services
+        })
+      })
+    }
+    // Re-base the page attribution: our emitted document and the backend's post-write
+    // copy of it are the two sides' new agreed state.
+    const patch = {}
+    const ours = sentSiteDoc
+    if (ours) patch.local = computeUnitHashes(ours)
+    // `finalized[].document` is the backend's own representation, read back from
+    // the stored row — the only remote-side base a push can produce.
+    const theirs = siteFinalizedDoc?.pages ? siteFinalizedDoc : null
+    if (theirs) {
+      patch.remote = computeUnitHashes(theirs)
+      // A unit the backend kept for someone else is not agreed state: its remote base
+      // stays where it was, so a refusal names it as changed upstream.
+      const before = readUnitBases(siteDir, client.origin).remote
+      for (const path of notHeld.kept) {
+        if (before[path]) patch.remote[path] = before[path]
+        else delete patch.remote[path]
+      }
+    }
+    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, 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.
+      //
+      // Without `finalized[0].document` (carrying `pages`) this push banks NO item
+      // identity. The push still reports success. The next `push`/`publish` then
+      // emits with no `$uuid` per item, and the backend refuses — correctly, since
+      // silently re-identifying every stored row is far worse. But that refusal
+      // reads as a stale-token or a producer bug, with nothing pointing back at the
+      // push that failed to bank.
+      //
+      // ⚠️ We cannot tell WHY it is absent from here — a response shape that
+      // changed, a lane that shipped nothing, a backend that does not echo the
+      // document. Report the observable fact and let the operator carry it.
+      note(
+        'identity not banked: this push returned no post-write document, so no per-item ' +
+          '$uuid was stored. The next push or publish will be identity-blind and the backend ' +
+          'may refuse it. `uniweb pull` re-arms identity if that happens.'
+      )
+    }
+    // The files of the units the backend now holds as ours are the synced version — the
+    // ancestor the next `pull --merge` merges from.
+    if (heldUnits.length) recordPushedUnits(siteDir, heldUnits)
+  }
+  if (siteContent) {
+    if (siteContentUuid) {
+      const finalized = await pushLane(
+        'site-content',
+        () =>
+          client.updateSiteContent(siteContentUuid, siteContent.buffer),
+        () =>
+          explainStaleSiteContent({
+            client,
+            siteDir,
+            localBuffer: siteContent.buffer,
+            uuid: siteContentUuid
+          }),
+        { boundUuid: siteContentUuid, reportTemplate: true }
+      )
+      if (!finalized) {
+        mergeHarvested()
+        return { exitCode: 1, finalizedTotal, wrote }
+      }
+      harvestSiteContent(finalized)
+      siteFinalizedDoc = finalized[0]?.document || null
+      finalizedTotal += finalized.length
+      settleSiteContent()
+    } else {
+      const payload = await postLane(
+        'site-content',
+        () => client.createSiteContent(siteContent.buffer),
+        undefined,
+        { reportTemplate: true }
+      )
+      if (payload === null) return { exitCode: 1, finalizedTotal, wrote }
+      const minted = extractMintedSiteUuid(payload)
+      if (!minted) {
+        error(
+          'The create response carried no minted site-content uuid — cannot record the site identity or push its folder.'
+        )
+        note(JSON.stringify(payload).slice(0, 800))
+        return { exitCode: 1, finalizedTotal, wrote }
+      }
+      writeSiteEntityUuid(siteDir, client.origin, minted)
+      updateSyncCache(siteDir, client.origin, { siteUuid: minted })
+      boundSiteUuid = minted
+      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 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({ client, siteDir, payload, note })
+      if (createdOrg)
+        wrote.push(`recorded its owner (${createdOrg}) in sync.json`)
+      const createdFinalized = extractFinalized(payload)
+      harvestSiteContent(createdFinalized)
+      siteFinalizedDoc = createdFinalized?.[0]?.document || null
+      finalizedTotal += createdFinalized?.length ?? 1
+      settleSiteContent()
+    }
+  }
+
+  // Lane 2 — collections (the @uniweb/folder + the records it references), keyed by the
+  // site-content uuid. On a brand-new site the backend creates the folder on this first
+  // push. Records round-trip their own $uuid (back-filled into source files); the folder
+  // itself has no uuid (the backend owns it).
+  if (records) {
+    if (!boundSiteUuid) {
+      error(
+        'Cannot push records — the site has no uuid yet. Push the site-content lane first.'
+      )
+      return { exitCode: 1, finalizedTotal, wrote }
+    }
+    const finalized = await pushLane(
+      'records',
+      () => client.pushFolder(boundSiteUuid, records.buffer),
+      undefined,
+      { boundUuid: boundSiteUuid }
+    )
+    if (!finalized) {
+      mergeHarvested()
+      return { exitCode: 1, finalizedTotal, wrote }
+    }
+    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}`)
+    // ⭐ BANK THE RECORDS' LIST ITEMS: each item's `$uuid` in the document the backend returned,
+    // paired by place with the lists as sent — so the next send of a record updates its items
+    // rather than being refused for replacing them (`readRecordItemUuids`).
+    bankRecordItems(
+      siteDir,
+      client.origin,
+      finalized.map((f) => ({
+        uuid: f?.uuid,
+        lists: Number.isInteger(f?.index) ? records.index?.[f.index]?.lists : null,
+        returned: f?.document
+      }))
+    )
+    draftsNotKept = bf.notKeptAsDrafts || []
+    if (bf.updated.length)
+      wrote.push(`wrote ${bf.updated.length} record file(s)`)
+    // ⭐ 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.
+    //
+    // ⛔ Without this a `publish` after a `push` is refused: send-only-changed
+    // skips the unchanged records and re-sends the folder ALONE, its `contents`
+    // items carry no `$uuid`, and a `multi` item without one reads as new — so
+    // the backend refuses rather than replacing every placement. Reproduced on a
+    // live manor 2026-08-27; the identities were on the wire all along.
+    const folderDoc = finalized.find((f) => f?.document?.contents)?.document
+    if (folderDoc) {
+      const placements = collectFolderItemUuids(folderDoc)
+      if (Object.keys(placements).length)
+        writeFolderItemUuids(siteDir, client.origin, placements)
+      // ⭐ A LINK RECORD'S IDENTITY is its folder entry's `$uuid`, banked as a record's is: into
+      // its file the first time, then mapped per backend (`link-records.js`, 2026-09-28).
+      if (records.links?.length) {
+        const lb = backfillLinkUuids({ links: records.links, folderDoc })
+        if (Object.keys(lb.mapped).length) updateBackendMap(siteDir, client.origin, 'records', lb.mapped)
+        for (const w of lb.warnings) note(`! ${w}`)
+        if (lb.updated.length) wrote.push(`wrote ${lb.updated.length} link file(s)`)
+      }
+      // ⭐ …and a FILE RECORD's: a file cannot carry it, so it is banked per backend by the file's
+      // path (`sync.json` `files`; `file-records.js`, 2026-09-28).
+      if (records.files?.length) {
+        const fb = bankedFileUuids({ files: records.files, folderDoc })
+        if (Object.keys(fb).length) updateBackendMap(siteDir, client.origin, 'files', fb)
+      }
+    }
+    finalizedTotal += finalized.length
+  }
+
+  // Persist the full content-hash map so the next push skips unchanged entities,
+  // 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, client.origin, hashes, applied)
+  // A record that named a record this push created is banked as the next push will send
+  // it — by that record's uuid, which the back-fill above just recorded.
+  if (records && pkg.namesNew?.length) {
+    try {
+      await rebankRecordHashes(siteDir, client.origin, pkg.namesNew)
+    } catch (err) {
+      note(`! Could not re-bank ${pkg.namesNew.length} record(s) that name a new record: ${err.message}. The next push sends them again.`)
+    }
+  }
+  mergeHarvested()
+  // (The site-content lane's own state was settled when it landed — `settleSiteContent`.)
+  // What the backend holds that this copy doesn't. None of it was overwritten, and no
+  // later push will overwrite it — but the files are behind until a pull.
+  if (notHeld.kept.length || notHeld.foreign.length) {
+    // Named by the file it is in here, not by its id (`unitFilesOf`).
+    const paths = [
+      ...new Set([...notHeld.kept, ...notHeld.foreign].map((p) => (p === 'site.yml' ? p : unitFilesOf(siteDir, p)[0] || p)))
+    ].sort()
+    note(`Changed on the backend by someone else, not in your files yet: ${paths.join(', ')}`)
+    note('Take them with `uniweb refresh` (or `uniweb pull --merge`). Until then, pushing leaves them as they are.')
+  }
+  // ⛔ A DRAFT THE BACKEND STORED ENABLED FAILS THE PUSH, and only here, after every
+  // piece of sync state above is banked: the push itself happened, and the next one must
+  // see it. What must not happen is a publish that goes live on top of it, which is why
+  // the exit code carries it (publish stops on anything but 0). The files keep their
+  // `draft: true` (see backfillEntityUuids).
+  if (draftsNotKept.length) {
+    const one = draftsNotKept.length === 1
+    const shown = draftsNotKept.map((p) => (isAbsolute(p) ? relative(siteDir, p) : p))
+    error(
+      `This backend did not keep ${one ? 'a record' : `${shown.length} records`} as a draft, ` +
+        `so ${one ? 'it' : 'they'} would be delivered once the site is published:\n  ` +
+        shown.join('\n  ') +
+        '\n  The backend does not support `draft: true` yet. Once it does, push again with --all.'
+    )
+    return { exitCode: 1, boundSiteUuid, finalizedTotal, wrote }
+  }
+  return { exitCode: 0, boundSiteUuid, finalizedTotal, wrote }
+}