@uniweb/build 0.55.1 → 0.56.0

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

package/src/uwx/site.js

@@ -67,6 +67,7 @@ import { emitEntitySyncPackage } from './entity-document.js'
 import { loadLocaleTranslations, localizeScalar, localizeScalarList, localizeContentDoc, localesDir, isLocalizedContent } from './locale-sync.js'
 import { unwrapLocalized } from './backfill.js'
 import { loadFreeformTranslation } from '../i18n/freeform.js'
+import { updateBackendState, readBackendState } from './sync-store.js'
 import { upsertYamlScalar } from './yaml-upsert.js'
 import { resolveQueriesConfig } from './queries-config.js'
 import { resolveSelfScope } from './self-scope.js'
@@ -974,8 +975,14 @@ function queriesNested(declarations, uuids = null, org = null) {
 
 // ── `services` + `secrets` — a site's own service records ─────────────────────
 //
-// ⭐ THE FILE KEYS ARE `$services` / `$secrets`, NOT `services` / `secrets`, and the
-// `$` is load-bearing rather than decorative. `site.yml::services` is ALREADY TAKEN,
+// ⚠️ THESE WERE `site.yml::$services` / `$secrets` UNTIL 2026-09-20. They now live in
+// `sync.json::backends.<origin>.{services,secrets}`, because what a site is PROVISIONED
+// with is a fact about one backend — a service is bought on the backend that sold it.
+// The `$` prefix existed to keep them off `site.yml::services`, which means something
+// else on the bundle lane (the HOST tier); out of `site.yml` entirely, that collision
+// is gone too.
+//
+// The original note, kept because it explains why the names could not simply be reused: `site.yml::services` is ALREADY TAKEN,
 // on the other lane: the bundle lane spreads site.yml whole into the payload, so a
 // `services:` block there lands at `config.services` — the HOST tier — which is the
 // documented way to simulate a host locally (`kit/src/utils/submitTarget.js`).
@@ -1056,9 +1063,9 @@ function serviceRecords(declared, identify, label) {
 }
 
 /** One service per `name` — the same keyspace `config.services` uses at runtime. */
-function servicesNested(siteYml) {
+function servicesNested(provisioned) {
   return serviceRecords(
-    siteYml.$services,
+    provisioned?.services,
     (e) => (typeof e.name === 'string' && e.name ? e.name : null),
     '$services'
   )
@@ -1076,9 +1083,9 @@ function servicesNested(siteYml) {
  * judgement belongs; framework does not strip it, because silently dropping a value
  * an author typed would leave them believing a secret was set.
  */
-function secretsNested(siteYml) {
+function secretsNested(provisioned) {
   return serviceRecords(
-    siteYml.$secrets,
+    provisioned?.secrets,
     (e) => {
       if (typeof e.name !== 'string' || !e.name) return null
       return typeof e.service === 'string' && e.service
@@ -1212,6 +1219,7 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
  *
  * @param {string} siteRoot - directory containing site.yml
  * @param {object} [opts]
+ * @param {string} [opts.backend] - whose `$uuid` to put on the wire (sync.json)
  * @param {string} [opts.entityUuid] - override the entity `$uuid` (tests); default
  *        is `site.yml::$uuid` (absent on first sync — `$id`-only document).
  * @param {string} [opts.sourceLocale] - localized-field wrap locale. Defaults to
@@ -1497,8 +1505,13 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // `$uuid?` then `$id` `$model`, then sections in Model-declared order. The entity
   // `$uuid` lives in site.yml (back-filled after first sync); absent on first sync.
   const doc = {}
+  // ⭐ From `sync.json`, keyed by the backend this document is being produced FOR.
+  // It was `site.yml::$uuid` — one scalar with no way to say which backend minted it.
+  // A producer with no backend emits no `$uuid`, which is exactly right: the wire
+  // value is that backend's name for this site, and there is no such name yet.
   const entityUuid =
-    opts.entityUuid || (typeof siteYml.$uuid === 'string' ? siteYml.$uuid : undefined)
+    opts.entityUuid ||
+    (opts.backend ? readBackendState(siteRoot, opts.backend).site?.uuid : undefined)
   if (entityUuid) doc.$uuid = entityUuid
   doc.$id = SITE_ENTITY_KEY // one site-content entity per project (stable handle)
   doc.$model = SITE_MODEL_NAME
@@ -1537,9 +1550,13 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // ⚖️ Default is to declare, so every existing caller is unchanged and the
   // withholding is opt-in.
   const declare = opts.declareServices !== false
-  const services = declare ? servicesNested(siteYml) : undefined
+  // ⭐ Provisioned per backend — a service is bought on the backend that sold it,
+  // so which rows exist is a question about ONE backend. They were `site.yml::$services`
+  // / `$secrets`, a single copy that could only ever describe one.
+  const provisioned = opts.backend ? readBackendState(siteRoot, opts.backend) : null
+  const services = declare ? servicesNested(provisioned) : undefined
   if (services) doc.services = services
-  const secrets = declare ? secretsNested(siteYml) : undefined
+  const secrets = declare ? secretsNested(provisioned) : undefined
   if (secrets) doc.secrets = secrets
   return doc
 }
@@ -1589,8 +1606,8 @@ export async function emitSiteSyncPackage(siteRoot, opts = {}) {
  * @param {string} uuid - the entity uuid the backend minted/echoed
  * @returns {boolean} true if site.yml changed
  */
-export function writeSiteEntityUuid(siteRoot, uuid) {
-  return upsertYamlScalar(join(siteRoot, 'site.yml'), '$uuid', uuid)
+export function writeSiteEntityUuid(siteRoot, backend, uuid) {
+  return updateBackendState(siteRoot, backend, { site: { uuid } })
 }
 
 /**
@@ -1639,45 +1656,12 @@ export function writeSiteEntityUuid(siteRoot, uuid) {
  * @param {string} handle - the bare org handle (no leading `@`)
  * @returns {boolean} true if site.yml changed
  */
-export function writeSiteOrg(siteRoot, handle) {
-  return upsertYamlScalar(join(siteRoot, 'site.yml'), '$org', handle)
+export function writeSiteOrg(siteRoot, backend, handle) {
+  return updateBackendState(siteRoot, backend, { site: { org: handle } })
 }
 
-/**
- * Record the backend this project SYNCS WITH (`site.yml::$backend`), beside `$uuid`/`$org`.
- *
- * ⭐ It is not a tag on the site uuid — it is the project's **sync scope**. Four surfaces
- * hold backend-minted identity, and this one fact is what makes all of them meaningful:
- * `site.yml::$uuid`, every collection record's `$uuid` in its own source file,
- * `assets.json`, and `.uniweb/sync-cache.json`. Change the backend and every one of them
- * is foreign at once — which is why a mismatch is a stop, not a fallback
- * (`assertSiteBackendScope` in the CLI).
- *
- * ⛔ **Written ONLY for a non-default backend.** The 98% case stays out of the file, and an
- * absent value reads as the default — correct both for a project written before this key
- * existed and for one synced against the default. Callers decide; this writer does not know
- * the CLI's default. See `recordSiteBackend` (cli/src/backend/site-sync.js), which is where
- * the "is it the default?" test lives.
- *
- * ⚠️ **The name is load-bearing. Five alternatives were considered and rejected (2026-08-24);
- * do not re-propose one.** `origin` is wrong twice over — a site HAS an origin (its own
- * served domain), and this lane is git-modeled, where `origin` names a remote rather than a
- * URL. `remote` implies a multiplicity this design closes. `hosting` and `platform` name the
- * hosting edge, which this package has no client for. `host` collides with
- * `deploy.yml::targets.<n>.host` (the deploy adapter). A `uuid: <id>@<backend>` suffix was
- * rejected too: it would make "this never reaches the backend" a discipline at every read
- * site instead of a property, and `siteProjectToDocument` assigns `$uuid` straight onto the
- * wire document.
- *
- * Safe as a plain YAML scalar: a URL's `:` is followed by `/` or a digit, never a space, so
- * it needs no quoting (verified against js-yaml for apex, `localhost:8080` and host:port+path
- * forms, 2026-08-24). This is the same class of hazard as `$org`'s leading `@`, which is
- * stripped for exactly that reason — but it lands on the safe side.
- *
- * @param {string} siteRoot
- * @param {string} origin - a bare origin, no trailing slash
- * @returns {boolean} true if site.yml changed
- */
-export function writeSiteBackend(siteRoot, origin) {
-  return upsertYamlScalar(join(siteRoot, 'site.yml'), '$backend', origin)
-}
+// ⛔ `writeSiteBackend` and `site.yml::$backend` are GONE (2026-09-20). The scope is
+// no longer a value recorded beside the uuid — it is the KEY the identity is stored
+// under (`sync.json::backends.<origin>`), so there is nothing to record and nothing
+// that can disagree with it. `kb/framework/reference/sync-json.md`.
+

package/src/uwx/sync-package.js

@@ -273,6 +273,8 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   const exportedAt = opts.exportedAt
 
   const col = await buildRecordEntities(siteRoot, {
+    // Which backend's record uuids go on the wire (sync.json) — see records.js.
+    ...(opts.backend ? { backend: opts.backend } : {}),
     ...(opts.foundationDir ? { foundationDir: opts.foundationDir } : {}),
     ...(opts.resolveModel ? { resolveModel: opts.resolveModel } : {}),
     ...(sourceLocale ? { sourceLocale } : {}),
@@ -316,6 +318,8 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   const siteDoc = includeSite
     ? await siteProjectToDocument(siteRoot, {
         sourceLocale,
+        // Whose $uuid belongs on this wire document — see siteProjectToDocument.
+        ...(opts.backend ? { backend: opts.backend } : {}),
         ...(opts.queryUuids ? { queryUuids: opts.queryUuids } : {}),
         // ⛔ THE SAME ORG `buildRecordEntities` WAS GIVEN ABOVE. A query's `schema`
         // must name the Model its records are stored under, and both are qualified