@uniweb/build 0.55.0 → 0.56.0

package/src/uwx/asset-map.js

@@ -1,156 +1,34 @@
 /**
- * `assets.json` — the site's committed map from a local asset path to the
- * backend's content-addressed id.
- *
- * ## Why it is COMMITTED, and why that is the whole point
- *
- * The same map used to be built on every push and thrown away
- * (`assetsByLocalUrl`, in memory, consumed by the content rewrite and dropped).
- * Rebuilt per push it is a private detail; committed it is a **log every machine
- * collaborating on this site can read**:
- *
- *   - a teammate who clones knows which bytes the project expects to exist and
- *     can fetch the ones they lack, instead of discovering a missing image at
- *     render;
- *   - `pull` can put an asset back at **the path its author wrote**, rather than
- *     inventing one — without this, a push turns `/images/hero.png` into an
- *     opaque id and nothing remembers it was ever called that;
- *   - a re-push of unchanged media is visibly a no-op rather than a silent one.
- *
- * ⇒ It is project state, not cache. `.uniweb/` is gitignored in both scaffolded
- * templates, which is why this does not live there.
- *
- * ## ⛔ Diff stability is a hard requirement, not tidiness
- *
- * A committed file that reorders itself produces a spurious diff on every push
- * and trains people to stop reading it — at which point a real change to what a
- * site ships passes unnoticed. Keys are therefore **sorted**, the shape is flat,
- * and the writer is a no-op when nothing changed (it does not rewrite an
- * identical file, so `git status` stays clean on a push that moved no assets).
- *
- * ## What it deliberately does NOT hold
- *
- * ⛔ **No serve URL.** A URL is a host's route layout, and storing one here would
- * re-create — in a committed file, on every machine — exactly the coupling that
- * deleting `buildAssetUrl` removed from this CLI. The id plus the host's
- * `config.assets.url` pattern is the whole address, and only the host owns the
- * second half.
- *
- * ⚖️ **What it holds instead is a FINGERPRINT of the served URL** (`served`), and the
- * difference is the point: a hash can recognize an address and cannot compose one.
- * It exists for references that are a BARE STRING — `info.preview`, `info.favicon`,
- * `seo.image`, a section param — where there is no object to stamp `assetId` beside,
- * so the stored value is the serve URL alone. `pull` hashes such a string and, when
- * it matches, puts back the path the author wrote. Should the host ever serve an
- * asset at a new address, the fingerprint simply stops matching and the pull leaves
- * the URL — the honest projection — until the next push records the new one.
- *
- * ⛔ **No mime or size.** The store validates those and they are its to change;
- * a second copy here is a second thing to disagree.
+ * Asset reference helpers — two pure functions, no file.
+ *
+ * ⚠️ **The MAP moved to `sync.json` on 2026-09-20** (`sync-store.js`,
+ * `backends.<origin>.assets`). It lived here as `assets.json`, a single flat
+ * `local path → id` file that assumed ONE backend — which is exactly what it
+ * could not represent once a project syncs with several: an id is minted by a
+ * backend and means nothing to any other one. `readAssetMap` / `updateAssetMap` /
+ * `refForAssetId` / `ASSET_MAP_FILE` went with it.
+ *
+ * What stays here is what never touched the filesystem:
+ *
+ * - **`servedFingerprint`** — hashes a serve URL. It exists for references that are
+ *   a BARE STRING (`info.preview`, `seo.image`, a section param), where there is no
+ *   object to stamp an id beside, so the stored value is the address alone. ⛔ A
+ *   fingerprint rather than the URL because a hash can RECOGNIZE an address and
+ *   cannot COMPOSE one — route layout is the host's and never ours to rebuild.
+ * - **`restoreAssetRefs`** — puts an author's own paths back into a document pulled
+ *   from a backend. Without it a push/pull cycle rewrites every image in a
+ *   developer's source to a backend route: a mangling of files they own, by a round
+ *   trip that changed nothing.
+ *
+ * ⭐ **`restoreAssetRefs` no-ops on an empty map**, which is what makes the store's
+ * `backend` parameter honest: a projection not tied to a backend has no known
+ * assets, so it restores nothing rather than guessing.
+ *
+ * @module
  */
 
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { createHash } from 'node:crypto'
 import { ASSET_SLOTS } from '@uniweb/semantic-parser'
-import { join } from 'node:path'
-
-export const ASSET_MAP_FILE = 'assets.json'
-
-/** Current on-disk shape. Bumped only for a breaking layout change. */
-const VERSION = 1
-
-const mapPath = (siteDir) => join(siteDir, ASSET_MAP_FILE)
-
-/**
- * Read the site's asset map. A missing, unreadable or malformed file reads as
- * empty rather than throwing: the map is an accelerator and a record, and a
- * corrupt one must never be the reason a push fails. The next write repairs it.
- *
- * @param {string} siteDir
- * @returns {Record<string, { id: string, ext: string }>} local ref → identity
- */
-export function readAssetMap(siteDir) {
-  const p = mapPath(siteDir)
-  if (!existsSync(p)) return {}
-  try {
-    const parsed = JSON.parse(readFileSync(p, 'utf8'))
-    const assets = parsed?.assets
-    if (!assets || typeof assets !== 'object') return {}
-    const out = {}
-    for (const [ref, v] of Object.entries(assets)) {
-      if (v && typeof v.id === 'string' && v.id) {
-        out[ref] = { id: v.id, ext: typeof v.ext === 'string' ? v.ext : '' }
-        if (typeof v.served === 'string' && v.served) out[ref].served = v.served
-      }
-    }
-    return out
-  } catch {
-    return {}
-  }
-}
-
-/**
- * Merge `entries` into the site's map and write it if anything changed.
- *
- * MERGE, not replace: a push carries only the refs that page's content touched,
- * so replacing would drop every asset this run happened not to mention — which
- * is most of them on a partial push. An entry whose id changed is overwritten
- * (the bytes at that path changed); an identical entry is left alone.
- *
- * @param {string} siteDir
- * @param {Record<string, { id: string, ext: string }>} entries
- * @returns {{ added: string[], changed: string[], written: boolean }}
- */
-export function updateAssetMap(siteDir, entries) {
-  const prior = readAssetMap(siteDir)
-  const added = []
-  const changed = []
-
-  for (const [ref, v] of Object.entries(entries || {})) {
-    if (!v?.id) continue
-    const was = prior[ref]
-    // A new `served` fingerprint is a change too: the host serves these bytes at
-    // another address now, and the old fingerprint would stop recognizing it. An
-    // entry that carries none — a download learns identity, not an upload's URL —
-    // keeps the one already recorded for the same bytes.
-    const served = v.served || (was && was.id === v.id ? was.served : undefined)
-    if (!was) added.push(ref)
-    else if (was.id !== v.id || (served || '') !== (was.served || '')) changed.push(ref)
-    else continue
-    prior[ref] = { id: v.id, ext: v.ext || '', ...(served ? { served } : {}) }
-  }
-
-  if (!added.length && !changed.length) return { added, changed, written: false }
-
-  // Sorted keys + a trailing newline: a committed file that reorders itself
-  // produces a diff on every push and teaches people to skip reading it.
-  const assets = {}
-  for (const ref of Object.keys(prior).sort()) assets[ref] = prior[ref]
-  writeFileSync(
-    mapPath(siteDir),
-    JSON.stringify({ version: VERSION, assets }, null, 2) + '\n'
-  )
-  return { added, changed, written: true }
-}
-
-/**
- * The local ref a given asset id is known at, or null.
- *
- * This is the direction `pull` needs and the reason the map is worth
- * committing: stored content carries an id, and only this can say the author
- * called it `/images/hero.png`. Without it a pull must invent a path.
- *
- * @param {Record<string, { id: string, ext: string }>} map
- * @param {string} id
- * @returns {string|null}
- */
-export function refForAssetId(map, id) {
-  if (!id) return null
-  for (const [ref, v] of Object.entries(map || {})) {
-    if (v.id === id) return ref
-  }
-  return null
-}
 
 /**
  * The fingerprint `assets.json` keeps of the URL a host serves an asset at.

package/src/uwx/backfill.js

@@ -318,13 +318,21 @@ function writeIfChanged(filePath, text) {
  *        order: `{ id, model, slug, sourceFile, format?, multiRecord?, declaration? }`.
  * @param {object[]} params.finalized - response entries `{ index, uuid, changed?, document? }`.
  * @param {string} [params.sourceLocale]
- * @returns {{ updated: string[], unchanged: string[], deferred: object[], warnings: string[] }}
+ * @returns {{ updated: string[], unchanged: string[], deferred: object[], warnings: string[], mapped: Object<string,string> }}
+ *   `mapped` is own id → the uuid this backend minted, for the caller to record per backend.
  */
 export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
   const updated = []
   const unchanged = []
   const deferred = []
   const warnings = []
+  // ⭐ own id → the uuid THIS backend minted. The caller files it under the backend in
+  // `sync.json::backends.<origin>.records`; this function knows no backend.
+  const mapped = {}
+  // Files holding only records that already carry their own id. Counted ONCE per file
+  // at the end: an array-form file holds several records, and "examined, nothing
+  // written" is a statement about the file, not about each record in it.
+  const ownIdFiles = new Set()
   // Multi-record files are written ONCE per file, applying every (slug → uuid).
   const arrayFiles = new Map() // array-form YAML/JSON: sourceFile -> Map(slug -> uuid)
   const bibFiles = new Map() // BibTeX: sourceFile -> Map(cite key -> uuid)
@@ -347,6 +355,22 @@ export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
       deferred.push({ index: i, id: entry.id, reason: 'no source file on disk' })
       continue
     }
+
+    // ⭐ Every record the backend returned is mapped: own id → the uuid it minted.
+    // A record new to EVERY backend has no own id yet, so the minted uuid becomes it
+    // (written below) and the mapping is identity — which is exactly the behaviour
+    // before identity was keyed by backend, so a single-backend project is unchanged.
+    mapped[entry.ownId || uuid] = uuid
+
+    // ⛔ A record that already carries its OWN id is NOT rewritten. Its id is stable
+    // and travels with the file; this backend's uuid belongs in the map, not in the
+    // author's file. And it must not be: variant A below re-renders the WHOLE file from
+    // the backend's document, which carries THIS backend's `$uuid` — so a second
+    // backend would silently overwrite the record's identity with its own.
+    if (entry.ownId) {
+      ownIdFiles.add(entry.sourceFile)
+      continue
+    }
     if (entry.multiRecord) {
       // Many records in one file → group by file, written once. BibTeX and
       // array-form YAML/JSON both re-render canonically (sync owns the output);
@@ -405,5 +429,8 @@ export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
     else warnings.push(`${file}: ${res.message}`)
   }
 
-  return { updated, unchanged, deferred, warnings }
+  for (const file of ownIdFiles) {
+    if (!updated.includes(file) && !unchanged.includes(file)) unchanged.push(file)
+  }
+  return { updated, unchanged, deferred, warnings, mapped }
 }

package/src/uwx/index.js

@@ -44,7 +44,6 @@ export {
   emitSiteSyncPackage,
   writeSiteEntityUuid,
   writeSiteOrg,
-  writeSiteBackend,
   extensionDeclaration,
   isExtensionUrl,
   isSiteRelativeExtensionUrl,
@@ -77,14 +76,27 @@ export {
   localeFilePath,
 } from './locale-sync.js'
 export { emitSyncPackages } from './sync-package.js'
-export {
-  readAssetMap,
-  updateAssetMap,
+// ⚠️ The asset MAP is `sync.json::backends.<origin>.assets` (sync-store.js, below).
+// `readAssetMap` / `updateAssetMap` / `refForAssetId` / `ASSET_MAP_FILE` were removed
+// on 2026-09-20: a single flat file cannot hold ids minted by more than one backend.
+export { restoreAssetRefs, servedFingerprint } from './asset-map.js'
+// `sync.json` — what each backend minted, keyed by origin. Absorbs `assets.json`
+// above, `site.yml`'s identity keys and three maps out of the sync cache.
+// Spec: kb/framework/reference/sync-json.md
+export {
+  SYNC_STORE_FILE,
+  readSyncStore,
+  readBackendState,
+  listSyncedBackends,
+  updateBackendState,
+  updateBackendMap,
+  carryServed,
+  clearBackend,
+  clearBackendSections,
+  forgetSyncStore,
   refForAssetId,
-  restoreAssetRefs,
-  ASSET_MAP_FILE,
-  servedFingerprint,
-} from './asset-map.js'
+  normalizeOrigin as normalizeBackendOrigin,
+} from './sync-store.js'
 export {
   diffSiteUnits,
   describeSiteDiff,

package/src/uwx/records-project.js

@@ -32,6 +32,7 @@
 // nothing is written into `collections.yml` here. Nothing is silently dropped: an
 // unplaceable or unresolvable record is reported.
 
+import { readBackendState, updateBackendMap } from './sync-store.js'
 import { readFileSync, readdirSync, existsSync } from 'node:fs'
 import { join, resolve, relative, extname, basename, sep } from 'node:path'
 import yaml from 'js-yaml'
@@ -175,13 +176,13 @@ function locate(document, folderIndex) {
 }
 
 /** `site.yml::$org`, bare (`acme`), or null. Stored bare — see `writeSiteOrg`. */
-function readSiteOrg(siteRoot) {
-  try {
-    const y = yaml.load(readFileSync(join(siteRoot, 'site.yml'), 'utf8'), YAML_OPTIONS) || {}
-    return typeof y.$org === 'string' && y.$org ? y.$org : null
-  } catch {
-    return null
-  }
+// ⛔ `site.yml::$org` IS GONE (2026-09-20) — the org lives in
+// `sync.json::backends.<origin>.site.org`. This read `site.yml` and, once step 4
+// moved the key, silently returned null: every `@org/x` model a pull met would have
+// been placed back as if the site had no org. No test spanned it.
+function readSiteOrg(siteRoot, backend) {
+  const org = backend ? readBackendState(siteRoot, backend).site?.org : null
+  return typeof org === 'string' && org ? org : null
 }
 
 // Skip undefined when copying optional fields into a projected declaration.
@@ -335,7 +336,7 @@ function declToFileShape(wire, dataSchemas = null, selfOrg = null) {
  *        the same default `recordsToProject` places records by.
  * @returns {{ collections?: 'updated'|'unchanged' }}
  */
-export function declarationsToQueriesYml({ document, siteRoot, org }) {
+export function declarationsToQueriesYml({ document, siteRoot, org, backend = null }) {
   const decls = Array.isArray(document?.queries) ? document.queries : []
   const report = {}
   if (decls.length === 0) return report
@@ -353,7 +354,7 @@ export function declarationsToQueriesYml({ document, siteRoot, org }) {
     siteYml = null
   }
   const dataSchemas = siteYml ? foundationDataSchemas(siteRoot, siteYml) : null
-  const selfOrg = org ?? readSiteOrg(siteRoot)
+  const selfOrg = org ?? readSiteOrg(siteRoot, backend)
 
   const queries = {}
   for (const d of decls) {
@@ -453,7 +454,7 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
   // The site's own org, so a `@org/x` model the producer resolved from `@/x` is
   // placed back where the author wrote it. Read from `site.yml::$org` unless the
   // caller already has it.
-  const selfOrg = opts.org ?? readSiteOrg(siteRoot)
+  const selfOrg = opts.org ?? readSiteOrg(siteRoot, opts.backend)
   if (typeof resolveDeclaration !== 'function') {
     throw new Error('uwx/records-project: opts.resolveDeclaration(modelName) is required')
   }
@@ -468,6 +469,11 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
   const unchanged = []
   const skipped = []
   const warnings = []
+  // This backend's record map, inverted: its uuid → the record's own id.
+  const recordMap = opts.backend ? readBackendState(siteRoot, opts.backend).records || {} : {}
+  const ownIdByTheirs = new Map(Object.entries(recordMap).map(([own, theirs]) => [theirs, own]))
+  // own id → their uuid, for every record this pull wrote. Recorded at the end.
+  const learned = {}
   // uuid → the path under `entities/` the record landed at. Only this loop knows
   // the extension each one got, so `records.yml` is written from it rather than
   // re-derived (a second rule could pick a different extension and the folder
@@ -495,7 +501,13 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
       })
       continue
     }
-    const existing = document.$uuid ? findRecordFileByUuid(poolDir, document.$uuid) : null
+    // ⭐ The incoming `$uuid` is the BACKEND's. The file holds the record's OWN id, so
+    // reverse this backend's map to find it. With no mapping the two are the same —
+    // the first backend a record reaches minted the id it keeps — so the backend's
+    // uuid is the own id, exactly as before identity was keyed by backend.
+    const theirs = document.$uuid || null
+    const own = theirs ? ownIdByTheirs.get(theirs) || theirs : null
+    const existing = own ? findRecordFileByUuid(poolDir, own) : null
 
     let filePath
     let format
@@ -514,9 +526,12 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
     // target-locale full-doc body is written under locales/freeform/{locale}/here.
     const freeformRelPath = buildFreeformRecordPath(document.$model, where.slug)
 
+    // ⛔ The file gets the record's OWN id, never this backend's — a pull from a second
+    // backend must not overwrite the identity the record already has.
+    const toWrite = own && own !== theirs ? { ...document, $uuid: own } : document
     let status
     try {
-      status = writeRecordFile({ filePath, document, declaration, format, sourceLocale, collector, freeformRelPath })
+      status = writeRecordFile({ filePath, document: toWrite, declaration, format, sourceLocale, collector, freeformRelPath })
     } catch (err) {
       warnings.push(`${where.slug}: ${err.message}`)
       continue
@@ -524,8 +539,11 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
     if (status === 'unchanged') unchanged.push(filePath)
     else if (isNew) placed.push(filePath)
     else updated.push(filePath)
-    if (document.$uuid) {
-      poolPathByUuid.set(document.$uuid, relative(join(siteRoot, ENTITIES_DIR), filePath).split(sep).join('/'))
+    // Keyed by THEIR uuid: the folder document references records in the backend's
+    // terms, so that is what `folderToRecordsYml` will look them up by.
+    if (theirs) {
+      poolPathByUuid.set(theirs, relative(join(siteRoot, ENTITIES_DIR), filePath).split(sep).join('/'))
+      if (own) learned[own] = theirs
     }
   }
 
@@ -543,5 +561,9 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
   const locales = writeLocaleTranslations(siteRoot, collector.byLocale, 'records')
   const freeform = writeFreeformTranslations(siteRoot, collector.freeformPending)
 
+  if (opts.backend && Object.keys(learned).length) {
+    updateBackendMap(siteRoot, opts.backend, 'records', learned)
+  }
+
   return { updated, placed, unchanged, skipped, warnings, locales, freeform, records: records.status }
 }

package/src/uwx/records.js

@@ -39,6 +39,7 @@
 // injected `opts.resolveModel`. A scope note that under-claims is worse than none:
 // it sends a reader to build what is already there.
 
+import { readBackendState } from './sync-store.js'
 import { readFileSync, existsSync } from 'node:fs'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
@@ -740,9 +741,30 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
       }
     }
 
+    // ⭐ THE FILE'S `$uuid` IS OURS; THE WIRE'S IS THE BACKEND'S (2026-09-20).
+    //
+    // A record's `$uuid` is its stable identity and travels with the file, so moving
+    // or renaming it changes nothing. What goes on the WIRE to backend B is the uuid B
+    // minted for it — looked up in `sync.json::backends.<B>.records` — or none, so B
+    // mints one. ⛔ Never send a backend a uuid it did not mint: whether it would
+    // accept one is the backend's to say, and this is correct either way.
+    //
+    // For the FIRST backend a record reaches, B's minted uuid is written into the
+    // file and the map is identity — exactly what happened before this change, so a
+    // single-backend project behaves as it always did.
+    const recordMap = opts.backend ? readBackendState(siteRoot, opts.backend).records || {} : {}
+    const ownIds = new Map()
+    const onWire = flat.map((rec) => {
+      const own = typeof rec.$uuid === 'string' && rec.$uuid ? rec.$uuid : null
+      ownIds.set(rec.slug, own)
+      const minted = own ? recordMap[own] : undefined
+      const { $uuid: _own, ...rest } = rec
+      return minted ? { ...rest, $uuid: minted } : rest
+    })
+
     const mappedOut = recordsToEntities({
       queryName: name,
-      records: flat,
+      records: onWire,
       declaration,
       sourceLocale,
       translations,
@@ -780,6 +802,9 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
         // per-entry `$uuid` write keyed by slug (see backfill.js). `format` lets
         // the writer route (array-form vs BibTeX, the latter still deferred).
         sourceFile: src ? src.sourceFile : null,
+        // The record's OWN id (the file's `$uuid`), or null for one never synced.
+        // The back-fill maps it to what the backend returns; see above.
+        ownId: ownIds.get(e.slug) ?? null,
         format: src ? src.format : null,
         multiRecord: src ? src.multiRecord : false,
         // The Model declaration, so the back-fill can render the finalized

package/src/uwx/site-project.js

@@ -33,7 +33,8 @@
 // the i18n pipeline). Absent `info` keys are left untouched on disk.
 
 import { join, relative, extname, basename, dirname } from 'node:path'
-import { readAssetMap, restoreAssetRefs } from './asset-map.js'
+import { restoreAssetRefs } from './asset-map.js'
+import { readBackendState, updateBackendState } from './sync-store.js'
 import { readFileSync, existsSync, unlinkSync, renameSync, rmSync, readdirSync, statSync, mkdirSync } from 'node:fs'
 import { isMarkdownFile, isIgnoredFolder } from '../utils/content-files.js'
 import { createHash } from 'node:crypto'
@@ -225,7 +226,7 @@ function readAuthoredYaml(filePath) {
  * @returns {{ siteConfig: string, theme?: string, headHtml?: string }} per-file
  *          write status ('updated' | 'unchanged')
  */
-export function siteInfoToConfig({ document, siteRoot, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, keepAuthoredFoundation = false }) {
+export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, keepAuthoredFoundation = false }) {
   const info = document?.info || {}
   const settingsSection = document?.settings || {}
 
@@ -295,7 +296,7 @@ export function siteInfoToConfig({ document, siteRoot, sourceLocale = LOCALIZED_
     : []
   if (extensions.length > 0) siteChanges.extensions = extensions
 
-  // services[] → site.yml::$services · secrets[] → site.yml::$secrets.
+  // services[] / secrets[] → sync.json::backends.<origin>.{services,secrets}.
   //
   // ⭐ The `$` prefix, and not the bare name, for the reason spelled out in
   // `uwx/site.js`: `site.yml::services` already means "pretend a host offers these"
@@ -315,10 +316,20 @@ export function siteInfoToConfig({ document, siteRoot, sourceLocale = LOCALIZED_
   // state — "this site has no service rows" — and it is the state a `pull` must be
   // able to deliver after the last one was removed. Skipping would leave a stale
   // `$services` on disk that the next push would resurrect.
-  for (const [section, ymlKey] of [['services', '$services'], ['secrets', '$secrets']]) {
-    const records = document?.[section]
-    if (!Array.isArray(records)) continue
-    siteChanges[ymlKey] = records.map(({ $id: _id, ...fields }) => fields)
+  // ⭐ To `sync.json`, under the backend that provisioned them — not `site.yml`.
+  // A service is bought on one backend, so its rows describe that backend alone.
+  // ⛔ Needs a backend: with none there is nowhere coherent to file them, and
+  // writing them to a shared place is exactly the single-copy bug this removed.
+  if (backend) {
+    const provisioned = {}
+    for (const section of ['services', 'secrets']) {
+      const records = document?.[section]
+      if (!Array.isArray(records)) continue
+      provisioned[section] = records.map(({ $id: _id, ...fields }) => fields)
+    }
+    if (Object.keys(provisioned).length) {
+      updateBackendState(siteRoot, backend, provisioned)
+    }
   }
 
   const result = { siteConfig: writeSiteConfig(siteRoot, siteChanges) }
@@ -859,7 +870,7 @@ function projectLayout(layoutSections, layoutBaseDir, report, prune, ctx) {
  *        empty set.
  * @returns {{ config: object, collections: object, locales: object, pages: string[], sections: string[], layout: string[], deleted: string[], renamed: object[] }}
  */
-export function siteContentDocumentToProject({ document, siteRoot, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, prune = false, keepAuthoredFoundation = false }) {
+export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, prune = false, keepAuthoredFoundation = false }) {
   const report = { config: null, collections: null, locales: null, assets: null, pages: [], sections: [], layout: [], deleted: [], renamed: [] }
 
   // Collects target-locale translations of localized scalars as they're projected;
@@ -871,10 +882,18 @@ export function siteContentDocumentToProject({ document, siteRoot, sourceLocale
   // the author wrote. Without this a push/pull cycle rewrites every image in a
   // developer's source to a backend route — a mangling of files they own, by a
   // round trip that changed nothing.
-  report.assets = restoreAssetRefs(document, readAssetMap(siteRoot))
-
-  report.config = siteInfoToConfig({ document, siteRoot, sourceLocale, collector, keepAuthoredFoundation })
-  report.queries = declarationsToQueriesYml({ document, siteRoot })
+  // ⛔ `backend` is required to restore anything, and its absence is HONEST rather
+  // than a default: asset ids are minted per backend (`sync.json`), so a projection
+  // not tied to one has no known assets and restores nothing. Every caller that
+  // pulls has an origin; the ones that do not are projecting a document in the
+  // abstract.
+  report.assets = restoreAssetRefs(
+    document,
+    backend ? readBackendState(siteRoot, backend).assets || {} : {}
+  )
+
+  report.config = siteInfoToConfig({ document, siteRoot, backend, sourceLocale, collector, keepAuthoredFoundation })
+  report.queries = declarationsToQueriesYml({ document, siteRoot, backend })
 
   // The uuid identity index (gitignored `.uniweb/`): read the prior map to anchor
   // rename detection, build a fresh one as we project, then persist it. Items not