uniweb 0.64.1 → 0.66.0

package/src/backend/site-sync.js

@@ -15,10 +15,12 @@ import { writeFileSync, readFileSync, mkdirSync, existsSync, unlinkSync } from '
 import { join, dirname, relative, isAbsolute } 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
@@ -32,6 +34,7 @@ import {
   diffSiteUnits,
   describeSiteDiff,
   computeUnitHashes,
+  collectSiteUnits,
   collectUnitUuids,
   collectFolderItemUuids,
   collectQueryUuids,
@@ -90,6 +93,141 @@ async function explainStaleSiteContent({ client, siteDir, localBuffer, uuid }) {
   }
 }
 
+// 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.
+ *
+ * With either document missing there is nothing to compare, and the tokens are banked
+ * as the backend sent them — the contract is that `finalized[].document` is always
+ * there.
+ *
+ * @returns {{ version: string|null, itemVersions: Object<string,string>|null,
+ *   held: string[], kept: string[], foreign: string[] }} `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 }) {
+  if (!sent || !written) return { version, itemVersions, held: [], kept: [], foreign: [] }
+  const ours = collectSiteUnits(sent)
+  const theirs = collectSiteUnits(written)
+  const uuidAt = collectUnitUuids(written)
+  const units = new Set(Object.values(uuidAt))
+  const held = []
+  const kept = []
+  const foreign = []
+  const items = {}
+  for (const [path, uuid] of Object.entries(uuidAt)) {
+    if (!ours.has(path)) {
+      foreign.push(path)
+      continue
+    }
+    if (!writtenAsSent(ours.get(path), theirs.get(path))) {
+      kept.push(path)
+      continue
+    }
+    held.push(path)
+    if (itemVersions?.[uuid]) items[uuid] = itemVersions[uuid]
+  }
+  // A token for an item that is not a unit (a `queries` declaration) is never sent
+  // back — the emit narrows preconditions to units (`withBaseVersion`) — so it is
+  // banked as before: it can neither arm nor disarm anything.
+  for (const [uuid, token] of Object.entries(itemVersions || {})) {
+    if (!units.has(uuid)) items[uuid] = token
+  }
+  return {
+    version: foreign.length ? null : version,
+    itemVersions: itemVersions ? items : null,
+    held: held.sort(),
+    kept: kept.sort(),
+    foreign: foreign.sort()
+  }
+}
+
+// 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.
+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 */
+  }
+  for (const root of ['pages', 'layout']) {
+    if (unitPath.startsWith(`${root}/`)) return [`${paths[root] || root}${unitPath.slice(root.length)}`]
+  }
+  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`
@@ -111,10 +249,10 @@ export function extractFinalized(payload) {
       uuid: d?.uuid ?? d?.document?.$uuid ?? null,
       changed: d?.changed,
       // Post-write optimistic-concurrency token, read back from the stored row.
-      // Cache it UNCONDITIONALLY — do not branch on `changed` and do not infer:
-      // the backend pins "zero-write ⇒ version unmoved" with a test, so a no-op
-      // resubmit returns the value we already hold, and anything else is theirs
-      // to report, not ours to derive.
+      // 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
@@ -547,8 +685,12 @@ export function readItemBaseVersions(siteDir, backend) {
 }
 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), ...versions }
+    itemBaseVersions: { ...readItemBaseVersions(siteDir, backend), ...versions }
   })
 }
 export function mergeBaseVersions(siteDir, backend, versions) {
@@ -652,21 +794,19 @@ export function writeItemUuids(siteDir, backend, map) {
 }
 
 /**
- * The workspace this project's requests name on `backend`, as the header names it —
- * `@handle`, or a unit's bare uuid when that unit has no handle — or null for none.
- *
- * Read back 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, for a workspace
- * that has no handle. At most one is set (`writeSiteWorkspace`). ⛔ They are 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.
+ * 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).
  *
- * Recorded at create — the site's owner — or adopted later from a backend's `409
- * wrong_workspace`, which may name a PARENT workspace that contains the site rather
- * than the site's own unit. ⇒ It is "the workspace these requests name", never
- * printed as "the site's org".
+ * ⭐ 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.)
  *
- * Deliberately NOT a fallback for the flag: an explicit `--org` always wins.
+ * 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
@@ -681,10 +821,10 @@ export function readSiteWorkspace(siteDir, backend) {
 }
 
 /**
- * Record the workspace this project's requests name 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.
+ * 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
@@ -702,50 +842,6 @@ function writeSiteWorkspace(siteDir, backend, workspace) {
   return w
 }
 
-/** A workspace as a sentence names it: `@acme`, `the unit <uuid>`, or `your personal workspace`. */
-export function describeWorkspace(workspace) {
-  if (!workspace) return 'your personal workspace'
-  return workspace.startsWith('@') ? workspace : `the unit ${workspace}`
-}
-
-/**
- * Point `client` at the workspace this project's requests name — `x-uniweb-workspace`.
- *
- * ⭐ THE WORKSPACE IS PER PROJECT, per backend — the one `sync.json` recorded — never
- * per login: a login is one session for the whole machine (`utils/session-file.js`).
- * An explicit choice (`--org`, `--personal`, the create picker) is sent as named, and
- * a `409 wrong_workspace` then STOPS the command. Otherwise the client adopts the
- * workspace the backend names, and this records it — as-is, since it may be a parent
- * workspace, or a unit with no handle — and says so. (`client.js::request`; agreed
- * with backend 2026-09-23.)
- *
- * @param {import('./client.js').BackendClient} client
- * @param {object} p
- * @param {string} p.siteDir
- * @param {string|null} p.workspace - in the header's form (`readSiteWorkspace`, or
- *   `workspaceHandle(--org)`), or null to name none
- * @param {boolean} [p.explicit=false]
- * @param {(m: string) => void} [p.note]
- * @returns {import('./client.js').BackendClient}
- */
-export function nameSiteWorkspace(client, { siteDir, workspace, explicit = false, note }) {
-  return client.setWorkspace(workspace, {
-    explicit,
-    onAdopted: (adopted) => {
-      try {
-        writeSiteWorkspace(siteDir, client.origin, adopted)
-      } catch {
-        // Recording is a convenience for the next command; this one still retries.
-      }
-      note?.(
-        adopted
-          ? `Requests for this site now name ${describeWorkspace(adopted)}, the workspace the backend works on it from (recorded in sync.json).`
-          : 'Requests for this site now name no workspace — the backend works on it from your personal one (recorded in sync.json).'
-      )
-    }
-  })
-}
-
 /**
  * Record the workspace a just-minted site was created under.
  *
@@ -768,173 +864,6 @@ function recordSiteWorkspace(siteDir, backend, owner) {
   }
 }
 
-/**
- * The `source`s of `resolveSiteOrgForCreate` that are the user's OWN choice — named on
- * the command line or picked — and so explicit: a `409 wrong_workspace` for one stops
- * the command rather than adopting the backend's answer (`nameSiteWorkspace`).
- */
-export const EXPLICIT_OWNER = new Set(['flag', 'personal', 'picked'])
-
-/**
- * Resolve WHICH ORG will own a site that is about to be created.
- *
- * The create that mints the site's uuid takes its owner from the workspace the request
- * names (`x-uniweb-workspace`), and the backend never moves ownership afterwards. There is also no CLI verb to transfer
- * or delete a site. So this is a **one-shot, unrepealable** decision — and until
- * this function existed the CLI made it silently, by sending nothing and letting
- * the backend fall back to the session's personal context. A developer who belongs
- * to several orgs could put a company site, and the storage it bills, somewhere
- * they never named.
- *
- * `register` resolves a foundation's scope in the same order — recorded (the scope
- * in its name, `@acme/marketing` in main.js), else explicit (`--scope`), else derived
- * (`deriveScope`) — with one difference: non-interactive, it takes your personal
- * scope and says so. This refuses instead, because a site's owner is the one-shot
- * decision above, and a scope is only a namespace (2026-09-23). ⭐ And the two are
- * separate decisions: a foundation may be registered under any org its author
- * belongs to, whoever owns the site (2026-09-22) — a site's `@/x` refs take the
- * FOUNDATION's scope, never this one. ⚠️ Until 2026-09-21 this said
- * `register` "has refused to guess a scope", which is wrong for a non-interactive
- * run by anyone with an org.
- *
- * Order:
- *   1. `--org @org`         — explicit; the create names it as its workspace
- *   2. `--personal`         — explicit "no org, I mean it" → names NO workspace
- *   3. the recorded org     — `sync.json`, written at this site's own create
- *   4. the site already exists on this backend (a recorded uuid) → null; ownership
- *      is settled, ask nothing
- *   5. otherwise ASK (TTY) or REFUSE (non-interactive)
- *
- * ⛔ **`--personal` names no workspace, and is NOT the same as `--org @<handle>`.**
- * The personal *org* `@jane` is an org like any other, lazily created on first use;
- * the session's personal workspace is not an org at all. Whether the backend gives
- * them the same owning unit is **its** business and unverified here, so the
- * deliberate-personal spelling names nothing rather than asserting an equivalence
- * this lane cannot check.
- *
- * @returns {Promise<{ workspace: string|null, source?: string, refused?: true, reason?: string }>}
- *   `workspace: null` with no `refused` means "name no workspace" — either a settled site
- *   or a deliberate personal choice. `source` says which answer it is: `flag`,
- *   `personal` and `picked` are the user's own choice (explicit — a mismatch then
- *   stops the command); `recorded`, `existing` and `offline` are not.
- */
-export async function resolveSiteOrgForCreate({
-  client,
-  siteDir,
-  args = [],
-  flag,
-  personal = false,
-  offline = false
-}) {
-  if (flag) return { workspace: workspaceHandle(flag), source: 'flag' }
-  if (personal) return { workspace: null, source: 'personal' }
-
-  const recorded = readSiteWorkspace(siteDir, client?.origin)
-  if (recorded) return { workspace: recorded, source: 'recorded' }
-
-  // Already created ⇒ nothing to decide: ownership was settled at its create and
-  // re-asking would be theatre. ⭐ "Created" is a question about THIS backend now —
-  // the same project may be brand new on one and long-established on another.
-  if (readBackendState(siteDir, client?.origin).site?.uuid) return { workspace: null, source: 'existing' }
-
-  // An offline preview (`--dry-run` / `-o`) must never authenticate, and it is
-  // creating nothing, so there is no decision to force. Say what is unresolved
-  // instead of prompting for an answer the run will not use.
-  if (offline) return { workspace: null, source: 'offline' }
-
-  // `--yes` promises "never block on a prompt", so it has to answer this one too —
-  // and the only honest non-blocking answer to an unanswerable ownership question
-  // is a refusal. Treating it as consent-to-anything would reinstate the silent
-  // default this whole path exists to remove, behind a flag that reads like
-  // approval.
-  const { isNonInteractive } = await import('../utils/interactive.js')
-  if (isNonInteractive(args) || args.includes('--yes')) {
-    return {
-      workspace: null,
-      refused: true,
-      reason:
-        'This site does not exist on the backend yet, and no org was named.\n' +
-        '  The create decides who OWNS it — and which workspace its storage is billed to —\n' +
-        '  one time, with no CLI way to change it afterwards. Name it explicitly:\n' +
-        '    --org @org        create it under an organization\n' +
-        '    --personal        create it under your personal account, deliberately'
-    }
-  }
-
-  // Interactive: offer the real choice. Deliberately NOT `deriveScope` — that one picks
-  // a NAMESPACE for a foundation, where `@<your handle>` is your personal scope. Here
-  // the answer is an OWNER: your personal workspace (named by naming none) or an org.
-  const { fetchOrgs, createOrg, validateHandle, bareHandle } =
-    await import('../utils/registry-orgs.js')
-  let envelope
-  try {
-    envelope = await fetchOrgs({
-      apiBase: client.origin,
-      token: await client.token()
-    })
-  } catch (err) {
-    return { workspace: null, refused: true, reason: err.message }
-  }
-  const personalHandle = envelope.account_handle || null
-  const prompts = (await import('prompts')).default
-  const choices = [
-    ...envelope.orgs.map((o) => ({
-      title: `@${o.handle}${o.handle === personalHandle ? ' — your personal org' : o.is_primary ? ' (primary)' : ''}`,
-      value: o.handle
-    })),
-    {
-      title: `Personal — no organization${personalHandle ? ` (${personalHandle})` : ''}`,
-      value: ':personal'
-    },
-    { title: 'A new organization…', value: ':new' }
-  ]
-  const { choice } = await prompts(
-    {
-      type: 'select',
-      name: 'choice',
-      message: 'Create this site under which owner?',
-      choices,
-      initial: 0
-    },
-    {
-      onCancel: () => {
-        console.log('\nCancelled.')
-        process.exit(0)
-      }
-    }
-  )
-  if (!choice) return { workspace: null, refused: true, reason: 'No owner chosen.' }
-  if (choice === ':personal') return { workspace: null, source: 'picked' }
-  if (choice !== ':new') return { workspace: `@${choice}`, source: 'picked' }
-
-  const answer = await prompts(
-    {
-      type: 'text',
-      name: 'handle',
-      message: 'Org handle (e.g. acme):',
-      validate: (v) => validateHandle(v) || true
-    },
-    {
-      onCancel: () => {
-        console.log('\nCancelled.')
-        process.exit(0)
-      }
-    }
-  )
-  if (!answer.handle)
-    return { workspace: null, refused: true, reason: 'No org handle given.' }
-  try {
-    const org = await createOrg({
-      apiBase: client.origin,
-      token: await client.token(),
-      handle: bareHandle(answer.handle)
-    })
-    return { workspace: `@${org.handle}`, source: 'picked' }
-  } catch (err) {
-    return { workspace: null, refused: true, reason: err.message }
-  }
-}
-
 /**
  * Turn a typed site-create refusal into a sentence, or null to fall through to the
  * generic HTTP line.
@@ -1048,7 +977,7 @@ export async function ensureSiteExists({
 
   let res
   try {
-    // The owner is the workspace the client names — `nameSiteWorkspace` set it.
+    // The owner is the workspace the client names — the command's (`workspace.js`).
     res = await client.createSite({
       name: siteName,
       foundation: siteFoundation
@@ -1147,6 +1076,31 @@ async function recordAndDescribeOwner({ client, siteDir, payload, note }) {
   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.
  *
@@ -1652,11 +1606,11 @@ export async function pushSyncPackages({
   const harvest = (finalized) => {
     for (const f of finalized || []) {
       if (f.uuid && f.version) newVersions[f.uuid] = f.version
-      // Unconditionally, and NOT gated on `changed` — same rule as the entity
-      // token: the backend pins "zero-write ⇒ version unmoved", so a no-op
-      // resubmit hands back the value we already hold. An older backend omits the
-      // field entirely, which leaves the cached tokens alone and degrades to the
-      // entity grain, exactly as before.
+      // NOT gated on `changed` — same rule as the entity token: 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`.)
+      // An older backend omits the field entirely, which leaves the cached tokens
+      // alone and degrades to the entity grain, exactly as before.
       if (f.itemVersions) Object.assign(newItemVersions, f.itemVersions)
     }
   }
@@ -1665,6 +1619,27 @@ export async function pushSyncPackages({
     mergeBaseVersions(siteDir, client.origin, newVersions)
     mergeItemBaseVersions(siteDir, client.origin, newItemVersions)
   }
+  // ⛔ 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
+      })
+      harvest([{ ...f, version: held.version, itemVersions: 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
@@ -1687,7 +1662,7 @@ export async function pushSyncPackages({
         mergeHarvested()
         return { exitCode: 1, finalizedTotal, wrote }
       }
-      harvest(finalized)
+      harvestSiteContent(finalized)
       siteFinalizedDoc = finalized[0]?.document || null
       // ⭐ BANK COLLECTION-DECLARATION IDENTITY, the sibling of the folder's
       // placements below. These items have no file to back-fill into — they all
@@ -1731,7 +1706,7 @@ export async function pushSyncPackages({
       if (createdOrg)
         wrote.push(`recorded its owner (${createdOrg}) in sync.json`)
       const createdFinalized = extractFinalized(payload)
-      harvest(createdFinalized)
+      harvestSiteContent(createdFinalized)
       siteFinalizedDoc = createdFinalized?.[0]?.document || null
       finalizedTotal += createdFinalized?.length ?? 1
     }
@@ -1801,12 +1776,21 @@ export async function pushSyncPackages({
   // actually shipped — a push that skipped it left that state where it was.
   if (siteContent) {
     const patch = {}
-    const ours = entityDocFromUwx(siteContent.buffer)
+    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)
+    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.
@@ -1834,6 +1818,16 @@ export async function pushSyncPackages({
       )
     }
   }
+  // 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)
+  // 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) {
+    const paths = [...new Set([...notHeld.kept, ...notHeld.foreign])].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