uniweb 0.61.0 → 0.63.0

package/src/backend/site-sync.js

@@ -12,15 +12,21 @@
  */
 
 import { writeFileSync, readFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs'
-import { join, dirname } from 'node:path'
+import { join, dirname, relative, isAbsolute } from 'node:path'
 import yaml from 'js-yaml'
 import { hasUncommittedContent } from '../utils/git.js'
 import { humanBytes } from '../utils/bytes.js'
 import { isAuthoredPreview } from '../utils/preview.js'
+import {
+  describeRequestError,
+  WorkspaceMismatchError,
+  workspaceHandle,
+  workspaceHeader
+} from './client.js'
 import {
   backfillEntityUuids,
   writeSiteEntityUuid,
-  writeSiteOrg,
+  updateBackendState,
   emitSyncPackages,
   readZip,
   diffSiteUnits,
@@ -646,46 +652,115 @@ export function writeItemUuids(siteDir, backend, map) {
 }
 
 /**
- * The org this site was created under, as `@handle`, or null.
+ * 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.
  *
- * Read back from `backend`'s `site.org` in `sync.json` (stored bare — see
- * `writeSiteOrg`) and re-dressed with the `@` the CLI and the wire both use. Callers
- * pass it as `--as-org`'s default so an org named once, at create, does not have to
- * be re-typed on every later push.
+ * 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".
  *
- * Deliberately NOT a fallback for the flag: an explicit `--as-org` always wins and
- * rides verbatim, so this can only add a value where the CLI previously sent none.
+ * Deliberately NOT a fallback for the flag: an explicit `--org` always wins.
  *
  * @param {string} siteDir
  * @param {string} backend - the origin whose record to read
  * @returns {string|null}
  */
-export function readSiteOrg(siteDir, backend) {
-  const org = readBackendState(siteDir, backend).site?.org
-  return typeof org === 'string' && org ? `@${org.replace(/^@/, '')}` : 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 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.
+ *
+ * @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
+}
+
+/** 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 org a just-minted site was created under, if one was named.
+ * Record the workspace a just-minted site was created under.
  *
- * Only what we were TOLD is recorded — when no `--as-org` was passed the backend
- * chose the owner and its create response carries no org, so there is nothing to
- * write and guessing one would be worse than the gap. Returns the display form for
- * the caller's "here's what resolved" line, or null when nothing was recorded.
+ * 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} asOrg - the `--as-org` value, `@handle` or bare
+ * @param {string|null|undefined} owner - in the header's form, or null
  * @returns {string|null}
  */
-function recordSiteOrg(siteDir, backend, asOrg) {
-  const handle = String(asOrg || '')
-    .replace(/^@/, '')
-    .replace(/\/.*$/, '')
-    .trim()
-  if (!handle) return null
+function recordSiteWorkspace(siteDir, backend, owner) {
   try {
-    writeSiteOrg(siteDir, backend, handle)
-    return `@${handle}`
+    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.
@@ -693,43 +768,55 @@ function recordSiteOrg(siteDir, backend, asOrg) {
   }
 }
 
+/**
+ * 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 `$uuid` is the only call that reads `as_org`, and the
- * backend never moves ownership afterwards. There is also no CLI verb to transfer
+ * 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 — explicit, then
- * recorded (`package.json::uniweb.scope`), then asked (`deriveScope`) — with one
- * difference: non-interactive, it PICKS the one org you belong to, else your
- * personal org, else the primary, and says which. This refuses instead, because a
- * site's owner is the one-shot decision above. ⚠️ Until 2026-09-21 this said
+ * `register` resolves a foundation's scope in the same order — recorded (the scope
+ * in its name, `@acme/marketing` in main.js), else explicit (`--scope`), else asked
+ * (`deriveScope`) — with one difference: non-interactive, it PICKS the one org you
+ * belong to, else your personal org, else the primary, and says which. This refuses
+ * instead, because a site's owner is the one-shot decision above. ⭐ 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, and only the last step is new:
- *   1. `--as-org @org`      — explicit, rides verbatim
- *   2. `--personal`         — explicit "no org, I mean it" → sends NO `as_org`
+ * 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` sends no `as_org`, and is NOT the same as `--as-org @<handle>`.**
+ * ⛔ **`--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 context is not an org at all. Whether the backend gives
+ * 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 reproduces today's wire byte-for-byte rather than
- * asserting an equivalence this lane cannot check.
- *
- * @returns {Promise<{ asOrg: string|null, refused?: true, reason?: string }>}
- *   `asOrg: null` with no `refused` means "send no as_org" — either a settled site
- *   or a deliberate personal choice.
+ * 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,
@@ -739,21 +826,21 @@ export async function resolveSiteOrgForCreate({
   personal = false,
   offline = false
 }) {
-  if (flag) return { asOrg: flag }
-  if (personal) return { asOrg: null }
+  if (flag) return { workspace: workspaceHandle(flag), source: 'flag' }
+  if (personal) return { workspace: null, source: 'personal' }
 
-  const recorded = readSiteOrg(siteDir, client?.origin)
-  if (recorded) return { asOrg: recorded }
+  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 { asOrg: null }
+  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 { asOrg: null }
+  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
@@ -763,13 +850,13 @@ export async function resolveSiteOrgForCreate({
   const { isNonInteractive } = await import('../utils/interactive.js')
   if (isNonInteractive(args) || args.includes('--yes')) {
     return {
-      asOrg: null,
+      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' +
-        '    --as-org @org     create it under an organization\n' +
+        '    --org @org        create it under an organization\n' +
         '    --personal        create it under your personal account, deliberately'
     }
   }
@@ -787,7 +874,7 @@ export async function resolveSiteOrgForCreate({
       token: await client.token()
     })
   } catch (err) {
-    return { asOrg: null, refused: true, reason: err.message }
+    return { workspace: null, refused: true, reason: err.message }
   }
   const personalHandle = envelope.account_handle || null
   const prompts = (await import('prompts')).default
@@ -817,9 +904,9 @@ export async function resolveSiteOrgForCreate({
       }
     }
   )
-  if (!choice) return { asOrg: null, refused: true, reason: 'No owner chosen.' }
-  if (choice === ':personal') return { asOrg: null }
-  if (choice !== ':new') return { asOrg: `@${choice}` }
+  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(
     {
@@ -836,16 +923,16 @@ export async function resolveSiteOrgForCreate({
     }
   )
   if (!answer.handle)
-    return { asOrg: null, refused: true, reason: 'No org handle given.' }
+    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 { asOrg: `@${org.handle}` }
+    return { workspace: `@${org.handle}`, source: 'picked' }
   } catch (err) {
-    return { asOrg: null, refused: true, reason: err.message }
+    return { workspace: null, refused: true, reason: err.message }
   }
 }
 
@@ -926,7 +1013,6 @@ export async function ensureSiteExists({
   siteDir,
   name,
   foundation,
-  asOrg,
   note
 }) {
   // One read serves both the binding check and the create's defaults, so callers
@@ -942,7 +1028,7 @@ export async function ensureSiteExists({
   }
   const known = readBackendState(siteDir, client.origin).site?.uuid
   if (known) {
-    return { uuid: known, created: false, org: readSiteOrg(siteDir, client.origin) }
+    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
@@ -963,10 +1049,10 @@ export async function ensureSiteExists({
 
   let res
   try {
+    // The owner is the workspace the client names — `nameSiteWorkspace` set it.
     res = await client.createSite({
       name: siteName,
-      foundation: siteFoundation,
-      asOrg
+      foundation: siteFoundation
     })
   } catch (err) {
     return { uuid: null, created: false, reason: err.message }
@@ -999,40 +1085,31 @@ export async function ensureSiteExists({
   // 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,
-    asOrg,
-    note
-  })
+  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**; `asOrg` 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, so it also covers the case we could never record before: no
- * `--as-org` at all, where the backend picked and we had nothing true to write.
+ * 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,
-  asOrg,
-  note
-}) {
+async function recordAndDescribeOwner({ client, siteDir, payload, note }) {
   const echoed = payload && 'org' in payload ? payload.org : undefined
   const owner =
-    echoed === undefined ? asOrg : typeof echoed === 'string' ? echoed : null
-  const org = recordSiteOrg(siteDir, client.origin, 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
@@ -1040,7 +1117,7 @@ async function recordAndDescribeOwner({
   // separately would be recording the name of the drawer inside the drawer.
   note?.(
     org
-      ? `Created the site on ${client.origin} under ${org} — recorded in sync.json.`
+      ? `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.`
   )
 
@@ -1147,21 +1224,14 @@ export async function probeUnpushed(siteDir, { backend = null, sendAll = false }
   //     `sync.json`, which the same push wrote. Reading the live file rather than a
   //     snapshot is what makes a moved map (a teammate's push, a pull) read as
   //     changed instead of matching a copy of itself.
-  //   · RECORDED — the site's own org, from `sync.json` (this backend's `site.org`).
-  //
-  // ⛔ THE ORG IS NOT OPTIONAL HERE, AND OMITTING IT WAS SILENT. It is what resolves
-  // a foundation-relative `@/member` into the `@org/member` the push shipped and
-  // keyed its hashes by. Without it the emit does not fail — `buildRecordEntities`
-  // WARNS and ships the model unresolved, deliberately, so an org-less export still
-  // works — so every record of a `@/`-scoped collection is emitted under a key that
-  // can never match its banked one, and reads as changed forever.
   //
-  // ⚠️ It hides in plain sight because `@std/…` queries are unaffected: their
-  // scope is already absolute, so they match. A site mixing both — the marketing
-  // fixture has `@std/person` AND `@proximify/member` — shows some records settling
-  // and others never settling, which reads like a content problem rather than a
-  // resolution one. Measured on matinee 2026-08-29: `status` reported 4 changed
-  // immediately after a successful push; passing the org took it to 1.
+  // ⛔ 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)
@@ -1180,9 +1250,10 @@ export async function probeUnpushed(siteDir, { backend = null, sendAll = false }
  *   · RE-DERIVED asset identity, from this backend's COMMITTED asset map in
  *                `sync.json`, so a moved map reads as changed rather than matching
  *                a copy of itself.
- *   · RECORDED   the site's org, which resolves a foundation-relative `@/x` into
- *                the `@org/x` the push keyed its hashes by, and the collection
- *                identity a push stamps, so the document is the one a push builds.
+ *   · 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 —
@@ -1201,7 +1272,6 @@ async function comparisonEmit(
   // comparison against the wrong one reports every media ref as changed. Absent is
   // honest rather than a default — no backend, no known ids.
   const assetIds = backend ? readBackendState(siteDir, backend).assets || {} : {}
-  const org = readSiteOrg(siteDir, backend)
   const queryUuids = readQueryUuids(siteDir, backend)
   return emitSyncPackages(siteDir, {
     backend,
@@ -1210,8 +1280,9 @@ async function comparisonEmit(
     sendAll,
     ...applied,
     ...(Object.keys(queryUuids).length ? { queryUuids } : {}),
-    ...(Object.keys(assetIds).length ? { assetIds } : {}),
-    ...(org ? { org } : {})
+    ...(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.
   })
 }
 
@@ -1242,6 +1313,37 @@ export async function rebankSyncHashes(siteDir, backend = null) {
   return Object.keys(pkg.hashes || {}).length
 }
 
+/**
+ * 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
@@ -1252,7 +1354,6 @@ export async function rebankSyncHashes(siteDir, backend = null) {
  * @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 {string|null} [params.asOrg] - act-as org (membership-gated), forwarded to each lane
  * @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.
@@ -1261,7 +1362,6 @@ export async function pushSyncPackages({
   client,
   siteDir,
   pkg,
-  asOrg,
   report
 }) {
   const { siteContent, records, siteContentUuid, hashes, applied } = pkg
@@ -1270,12 +1370,14 @@ export async function pushSyncPackages({
 
   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) + the optional
-  // `--as-org`. Returns the parsed payload, or null on any transport/HTTP/parse failure
-  // (already reported).
+  // 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
@@ -1284,15 +1386,16 @@ export async function pushSyncPackages({
     label,
     doRequest,
     explainStale = async () => [],
-    { boundUuid = null } = {}
+    { boundUuid = null, reportTemplate = false } = {}
   ) => {
     info(`Pushing ${label} to ${dim(client.origin)} …`)
     let res
     try {
       res = await doRequest()
     } catch (err) {
-      error(`Could not reach the backend at ${client.origin}: ${err.message}`)
-      note('Is that the backend you meant? Switch with: uniweb login --backend <url>')
+      error(describeRequestError(err, client.origin))
+      if (!(err instanceof WorkspaceMismatchError))
+        note('Is that the backend you meant? Switch with: uniweb login --backend <url>')
       return null
     }
     if (!res.ok) {
@@ -1481,12 +1584,25 @@ export async function pushSyncPackages({
       if (body) note(body.slice(0, 800))
       return null
     }
+    let payload
     try {
-      return await res.json()
+      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
@@ -1558,9 +1674,7 @@ export async function pushSyncPackages({
       const finalized = await pushLane(
         'site-content',
         () =>
-          client.updateSiteContent(siteContentUuid, siteContent.buffer, {
-            asOrg
-          }),
+          client.updateSiteContent(siteContentUuid, siteContent.buffer),
         () =>
           explainStaleSiteContent({
             client,
@@ -1568,7 +1682,7 @@ export async function pushSyncPackages({
             localBuffer: siteContent.buffer,
             uuid: siteContentUuid
           }),
-        { boundUuid: siteContentUuid }
+        { boundUuid: siteContentUuid, reportTemplate: true }
       )
       if (!finalized) {
         mergeHarvested()
@@ -1589,8 +1703,11 @@ export async function pushSyncPackages({
       }
       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),
+        undefined,
+        { reportTemplate: true }
       )
       if (payload === null) return { exitCode: 1, finalizedTotal, wrote }
       const minted = extractMintedSiteUuid(payload)
@@ -1611,13 +1728,7 @@ export async function pushSyncPackages({
       // 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,
-        asOrg,
-        note
-      })
+      const createdOrg = await recordAndDescribeOwner({ client, siteDir, payload, note })
       if (createdOrg)
         wrote.push(`recorded its owner (${createdOrg}) in sync.json`)
       const createdFinalized = extractFinalized(payload)
@@ -1640,7 +1751,7 @@ export async function pushSyncPackages({
     }
     const finalized = await pushLane(
       'records',
-      () => client.pushFolder(boundSiteUuid, records.buffer, { asOrg }),
+      () => client.pushFolder(boundSiteUuid, records.buffer),
       undefined,
       { boundUuid: boundSiteUuid }
     )
@@ -1658,6 +1769,7 @@ export async function pushSyncPackages({
     }
     for (const w of bf.warnings) note(`! ${w}`)
     for (const d of bf.deferred) note(`↷ ${d.id ?? `#${d.index}`}: ${d.reason}`)
+    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`
@@ -1723,5 +1835,21 @@ export async function pushSyncPackages({
       )
     }
   }
+  // ⛔ 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 }
 }