uniweb 0.13.17 → 0.14.0

package/src/backend/site-sync.js

@@ -23,7 +23,7 @@ import {
   diffSiteUnits,
   describeSiteDiff,
   computeUnitHashes,
-  collectUnitUuids,
+  collectUnitUuids
 } from '@uniweb/build/uwx'
 
 // First entity `$`-document out of a `.uwx` we produced or the backend served.
@@ -66,7 +66,9 @@ async function explainStaleSiteContent({ client, siteDir, localBuffer, uuid }) {
     const remoteDoc = entityDocFromUwx(Buffer.from(await res.arrayBuffer()))
     const localDoc = entityDocFromUwx(localBuffer)
     if (!remoteDoc || !localDoc) return []
-    return describeSiteDiff(diffSiteUnits(localDoc, remoteDoc, readUnitBases(siteDir)))
+    return describeSiteDiff(
+      diffSiteUnits(localDoc, remoteDoc, readUnitBases(siteDir))
+    )
   } catch {
     return []
   }
@@ -98,7 +100,7 @@ export function extractFinalized(payload) {
       // resubmit returns the value we already hold, and anything else is theirs
       // to report, not ours to derive.
       version: typeof d?.version === 'string' ? d.version : null,
-      document: d?.document ?? null,
+      document: d?.document ?? null
     }))
     .filter((e) => Number.isInteger(e.index) && e.uuid)
 }
@@ -109,7 +111,13 @@ export function extractFinalized(payload) {
 // 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) {
-  if (typeof payload?.siteContentUuid === 'string') return payload.siteContentUuid
+  // `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)
@@ -181,6 +189,106 @@ const readMap = (siteDir, 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).
+ *
+ * `.uniweb/sync-cache.json` holds four maps keyed by *unit path* — item uuids,
+ * content hashes, entity base versions, unit bases — and a unit path (`site.yml`,
+ * `pages/about/about.md`) is the same string for every site. So the cache does not
+ * self-invalidate when `site.yml::$uuid` goes away: it keeps describing the site
+ * this folder used to be.
+ *
+ * Which is a state we ACTIVELY TELL PEOPLE TO ENTER. The 404 guidance on a
+ * uuid-bound lane says to clear `$uuid` to re-publish as a new site — the documented
+ * recovery after a site is deleted in the app. Following it left the stale maps in
+ * place, and the next publish failed two ways:
+ *
+ *   - **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.
+ *
+ * Call this BEFORE `ensureSiteExists`, which mints a uuid and would otherwise make
+ * the clone look bound before the check runs.
+ */
+/**
+ * Drop the four 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, siteUuid = null) {
+  const prior = readSyncCacheFile(siteDir)
+  const dropped = ['itemUuids', 'hashes', 'baseVersions', 'unitBases'].filter(
+    (k) => prior[k] && Object.keys(prior[k]).length
+  )
+  updateSyncCache(siteDir, {
+    itemUuids: {},
+    hashes: {},
+    baseVersions: {},
+    unitBases: {},
+    siteUuid: siteUuid || null
+  })
+  return dropped
+}
+
+export function clearRemoteSyncStateIfUnbound(siteDir) {
+  let current = null
+  try {
+    const y = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))
+    if (typeof y?.$uuid === 'string') current = y.$uuid
+  } catch {
+    /* unreadable site.yml — treat as unbound and clear, which is the safe side */
+  }
+
+  const prior = readSyncCacheFile(siteDir)
+  const REMOTE_MAPS = ['itemUuids', 'hashes', 'baseVersions', 'unitBases']
+  const populated = REMOTE_MAPS.filter(
+    (k) => prior[k] && Object.keys(prior[k]).length
+  )
+  if (!populated.length) {
+    // Nothing to invalidate, but still stamp identity so a LATER divergence is
+    // detectable. A cache that never records its site can only be checked by the
+    // unbound rule, which misses the bound-but-wrong case below.
+    if (current && prior.siteUuid !== current) {
+      updateSyncCache(siteDir, { siteUuid: current })
+    }
+    return []
+  }
+
+  // Two ways the cache can describe a site this clone is not working with:
+  //
+  //   1. UNBOUND — no `$uuid` at all, so there is no backend site for any of it to
+  //      be about. This is the state the documented "clear `$uuid` to re-publish as
+  //      a new site" recovery puts you in.
+  //   2. BOUND TO A DIFFERENT SITE — `$uuid` names one site and the cache was
+  //      written for another. Reachable in one step: the create mints a uuid and
+  //      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, { siteUuid: current })
+    }
+    return []
+  }
+
+  clearRemoteSyncState(siteDir, current)
+  return stale
+}
+
 export function readSyncCache(siteDir) {
   return readMap(siteDir, 'hashes')
 }
@@ -223,11 +331,15 @@ export function readItemBaseVersions(siteDir) {
 }
 export function mergeItemBaseVersions(siteDir, versions) {
   if (!versions || !Object.keys(versions).length) return
-  updateSyncCache(siteDir, { itemBaseVersions: { ...readItemBaseVersions(siteDir), ...versions } })
+  updateSyncCache(siteDir, {
+    itemBaseVersions: { ...readItemBaseVersions(siteDir), ...versions }
+  })
 }
 export function mergeBaseVersions(siteDir, versions) {
   if (!versions || !Object.keys(versions).length) return
-  updateSyncCache(siteDir, { baseVersions: { ...readBaseVersions(siteDir), ...versions } })
+  updateSyncCache(siteDir, {
+    baseVersions: { ...readBaseVersions(siteDir), ...versions }
+  })
 }
 
 /**
@@ -278,6 +390,104 @@ export function writeItemUuids(siteDir, map) {
   updateSyncCache(siteDir, { itemUuids: map })
 }
 
+/**
+ * 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 `site.yml::$uuid` is already set, so only the first publish of a
+ * site pays for it. The uuid is written back immediately, keeping the window in
+ * 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,
+  asOrg,
+  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 */
+  }
+  if (typeof siteYml.$uuid === 'string') {
+    return { uuid: siteYml.$uuid, created: false }
+  }
+
+  // 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 {
+    res = await client.createSite({
+      name: siteName,
+      foundation: siteFoundation,
+      asOrg
+    })
+  } 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)'
+          : `HTTP ${res?.status} ${res?.statusText || ''}${body ? ` — ${body.slice(0, 200)}` : ''}`
+    }
+  }
+  const minted = extractMintedSiteUuid(await res.json().catch(() => null))
+  if (!minted) {
+    return {
+      uuid: null,
+      created: false,
+      reason: 'the create returned no site uuid'
+    }
+  }
+  writeSiteEntityUuid(siteDir, minted)
+  // Stamp the cache with the site it now describes, so a push that fails after
+  // this point cannot leave a cache pointing at a different site with no way to
+  // detect it.
+  updateSyncCache(siteDir, { siteUuid: minted })
+  note?.(`Created the site on the backend (recorded $uuid in site.yml).`)
+  return { uuid: minted, created: true }
+}
+
 /**
  * Guarantee we have per-item identity before an identity-bearing push.
  *
@@ -297,7 +507,9 @@ export async function ensureItemUuids({ client, siteDir, note }) {
   try {
     const y = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))
     siteContentUuid = typeof y?.$uuid === 'string' ? y.$uuid : null
-  } catch { /* unreadable site.yml — nothing to recover against */ }
+  } catch {
+    /* unreadable site.yml — nothing to recover against */
+  }
   if (!siteContentUuid) return cached
   try {
     const res = await client.pullSiteContent(siteContentUuid)
@@ -307,7 +519,9 @@ export async function ensureItemUuids({ client, siteDir, note }) {
     const harvested = collectUnitUuids(doc)
     if (Object.keys(harvested).length) {
       writeItemUuids(siteDir, harvested)
-      note?.(`Recovered identity for ${Object.keys(harvested).length} item(s) from the backend.`)
+      note?.(
+        `Recovered identity for ${Object.keys(harvested).length} item(s) from the backend.`
+      )
     }
     return harvested
   } catch {
@@ -323,7 +537,9 @@ export function readUnitBases(siteDir) {
 }
 export function writeUnitBases(siteDir, patch) {
   if (!patch) return
-  updateSyncCache(siteDir, { unitBases: { ...readUnitBases(siteDir), ...patch } })
+  updateSyncCache(siteDir, {
+    unitBases: { ...readUnitBases(siteDir), ...patch }
+  })
 }
 
 /**
@@ -343,9 +559,10 @@ export async function probeUnpushed(siteDir, { sendAll = false } = {}) {
   const pkg = await emitSyncPackages(siteDir, {
     resolveModel: makeModelResolver({ client: null, offline: true }),
     priorHashes,
-    sendAll,
+    sendAll
   })
-  const changed = (pkg.siteContent?.entityCount || 0) + (pkg.collections?.entityCount || 0)
+  const changed =
+    (pkg.siteContent?.entityCount || 0) + (pkg.collections?.entityCount || 0)
   return { changed, unchanged: pkg.skipped || 0, warnings: pkg.warnings || [] }
 }
 
@@ -364,7 +581,13 @@ export async function probeUnpushed(siteDir, { sendAll = false } = {}) {
  * @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, asOrg, report }) {
+export async function pushSyncPackages({
+  client,
+  siteDir,
+  pkg,
+  asOrg,
+  report
+}) {
   const { siteContent, collections, siteContentUuid, hashes } = pkg
   const { info, note, error } = report
   const dim = report.dim || ((s) => s)
@@ -377,7 +600,16 @@ export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report })
   // request fires). The client carries `collision=force` (last-push-wins) + the optional
   // `--as-org`. Returns the parsed payload, or null on any transport/HTTP/parse failure
   // (already reported).
-  const postLane = async (label, doRequest, explainStale = async () => []) => {
+  // `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 } = {}
+  ) => {
     info(`Pushing ${label} to ${dim(client.origin)} …`)
     let res
     try {
@@ -393,33 +625,82 @@ export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report })
       // `reason` — never on `detail`, which is prose the backend may reword.
       let problem = null
       if ((res.status === 409 || res.status === 400) && body) {
-        try { problem = JSON.parse(body) } catch { /* not a problem document */ }
+        try {
+          problem = JSON.parse(body)
+        } catch {
+          /* not a problem document */
+        }
       }
       // 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, 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') {
-        error(`${label} push refused — this copy has no record of the site's item identity.`)
-        note('Nothing was written. Pushing without it would have replaced the identity of every stored item.')
-        note('The recovery normally runs automatically, so it likely could not reach the backend.')
-        note('Check your connection and re-run; `uniweb pull` also restores it.')
+        error(
+          `${label} push refused — this copy has no record of the site's item identity.`
+        )
+        note(
+          'Nothing was written. Pushing without it would have replaced the identity of every stored item.'
+        )
+        note(
+          'The recovery normally runs automatically, so it likely could not reach the backend.'
+        )
+        note(
+          'Check your connection and re-run; `uniweb pull` also restores it.'
+        )
         return null
       }
       if (problem?.reason === 'stale_base') {
-        error(`${label} push refused — the backend has newer content than your last pull.`)
+        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)
         if (!detail.length) {
-          const stale = Array.isArray(problem.stale_entities) ? problem.stale_entities : []
+          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(
+              `Changed upstream: ${stale.length} entit${stale.length === 1 ? 'y' : 'ies'} (${stale.join(', ')})`
+            )
           }
         }
-        note('Nothing was written — the whole push was refused before any change.')
+        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.
@@ -427,17 +708,38 @@ export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report })
           // `--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.)')
+          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(
+            '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).')
+        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 — supply a bearer with --token <bearer> (or UNIWEB_TOKEN).")
+        note(
+          "Credentials weren't accepted — supply a bearer with --token <bearer> (or 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.
+        note(
+          `The backend has no site with uuid ${boundUuid} — the usual cause is that it was deleted in the Uniweb app.`
+        )
+        note(
+          'Deleting this folder removes only your local copy; clearing `$uuid` from site.yml re-publishes it as a new site.'
+        )
       } else if (res.status === 409) {
         // The site's @uniweb/folder is genesis-owned: its structure is fixed on first
         // deploy and not reconciled in place (the v1 rule — see gotcha #20's mode switch).
@@ -462,12 +764,14 @@ export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report })
   // 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) => {
-    const payload = await postLane(label, doRequest, explainStale)
+  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).`)
+      error(
+        `The ${label} response carried no recognizable finalized list (expected report.finalized[] with index + uuid).`
+      )
       note(JSON.stringify(payload).slice(0, 800))
       return null
     }
@@ -487,7 +791,8 @@ export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report })
   // already moved past, and refuse a push the user just made.
   const newVersions = {}
   const harvest = (finalized) => {
-    for (const f of finalized || []) if (f.uuid && f.version) newVersions[f.uuid] = f.version
+    for (const f of finalized || [])
+      if (f.uuid && f.version) newVersions[f.uuid] = f.version
   }
   // The backend's post-write copy of the site-content document, kept for the
   // remote-side unit base (see writeUnitBases).
@@ -496,8 +801,18 @@ export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report })
     if (siteContentUuid) {
       const finalized = await pushLane(
         'site-content',
-        () => client.updateSiteContent(siteContentUuid, siteContent.buffer, { asOrg }),
-        () => explainStaleSiteContent({ client, siteDir, localBuffer: siteContent.buffer, uuid: siteContentUuid })
+        () =>
+          client.updateSiteContent(siteContentUuid, siteContent.buffer, {
+            asOrg
+          }),
+        () =>
+          explainStaleSiteContent({
+            client,
+            siteDir,
+            localBuffer: siteContent.buffer,
+            uuid: siteContentUuid
+          }),
+        { boundUuid: siteContentUuid }
       )
       if (!finalized) {
         mergeBaseVersions(siteDir, newVersions)
@@ -507,18 +822,20 @@ export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report })
       siteFinalizedDoc = finalized[0]?.document || null
       finalizedTotal += finalized.length
     } else {
-      const payload = await postLane(
-        'site-content',
-        () => client.createSiteContent(siteContent.buffer, { asOrg })
+      const payload = await postLane('site-content', () =>
+        client.createSiteContent(siteContent.buffer, { asOrg })
       )
       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.')
+        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, minted)
+      updateSyncCache(siteDir, { siteUuid: minted })
       boundSiteUuid = minted
       wrote.push('recorded site $uuid in site.yml')
       const createdFinalized = extractFinalized(payload)
@@ -534,12 +851,16 @@ export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report })
   // itself has no uuid (the backend owns it).
   if (collections) {
     if (!boundSiteUuid) {
-      error('Cannot push collections — the site has no uuid yet. Push the site-content lane first.')
+      error(
+        'Cannot push collections — the site has no uuid yet. Push the site-content lane first.'
+      )
       return { exitCode: 1, finalizedTotal, wrote }
     }
     const finalized = await pushLane(
       'collections',
-      () => client.pushFolder(boundSiteUuid, collections.buffer, { asOrg })
+      () => client.pushFolder(boundSiteUuid, collections.buffer, { asOrg }),
+      undefined,
+      { boundUuid: boundSiteUuid }
     )
     if (!finalized) {
       mergeBaseVersions(siteDir, newVersions)
@@ -549,7 +870,8 @@ export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report })
     const bf = backfillEntityUuids({ index: collections.index, finalized })
     for (const w of bf.warnings) note(`! ${w}`)
     for (const d of bf.deferred) note(`↷ ${d.id ?? `#${d.index}`}: ${d.reason}`)
-    if (bf.updated.length) wrote.push(`wrote ${bf.updated.length} record file(s)`)
+    if (bf.updated.length)
+      wrote.push(`wrote ${bf.updated.length} record file(s)`)
     finalizedTotal += finalized.length
   }