@uniweb/build 0.55.1 → 0.57.0

package/src/uwx/self-scope.js

@@ -26,7 +26,7 @@
 // (the foundation's scope, not the site's publish org) and stays there.
 
 /**
- * An org handle as `--org` or `site.yml::$org` gives it — `@acme`, `acme`, or
+ * An org handle as `--org` or `sync.json` gives it — `@acme`, `acme`, or
  * `@acme/…` — reduced to the bare handle, or `''`.
  *
  * @param {unknown} org
@@ -56,15 +56,15 @@ export function resolveSelfScope(ref, org) {
  * The inverse, for a pull: `@<org>/x` → `@/x` for the site's own org.
  *
  * ⛔ WITHOUT THIS THE ROUND TRIP IS NOT A FIXED POINT, and the failure is silent
- * on both ends. A record authored under `entities/article/` comes back as
- * `@acme/article` and, placed literally, lands under `entities/acme/article/` — a
+ * on both ends. A record authored under `records/article/` comes back as
+ * `@acme/article` and, placed literally, lands under `records/acme/article/` — a
  * different schema folder, which the next build reads as a different schema. A
  * query declared `schema: '@/member'` comes back as `@acme/member`, and one that
  * relied on the query-name default comes back with an explicit schema it never
  * had.
  *
- * ⭐ The site records its own org at create (`site.yml::$org` — "whose this is"),
- * which is exactly the inverse. A model scoped to ANOTHER org is left alone: it
+ * ⭐ The site records its own org at create (`site.org` in `sync.json`, per backend —
+ * "whose this is"), which is exactly the inverse. A model scoped to ANOTHER org is left alone: it
  * genuinely is that org's, and `@/` would be a lie.
  *
  * @param {unknown} ref

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'
@@ -150,7 +151,7 @@ const INFO_TO_SITE_YML = {
   // ⭐ `preview` — the card image, verbatim: the app's timestamp, an author's URL, or
   // the path an author wrote for an image in the project, which `restoreAssetRefs`
   // has already put back by recognizing the serve URL the push recorded in
-  // `assets.json` (asset-map.js). [Diego, 2026-09-10]
+  // `sync.json`'s asset map (asset-map.js). [Diego, 2026-09-10]
   //
   // ⚠️ It was listed here as "DELIBERATELY ABSENT… BACKEND-STAMPED" until
   // 2026-09-10. Leaving an app-written field out of this map is what lets the next
@@ -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) }
@@ -338,8 +349,8 @@ export function siteInfoToConfig({ document, siteRoot, sourceLocale = LOCALIZED_
   // `data_bundle` and `foundation_schema`. It had been a build-derived upload
   // manifest that a pull deliberately never wrote back; framework never populated
   // it. Nothing to project, and nothing here to remove — the note is kept because
-  // `assets.json` (the committed local path → id map) is a DIFFERENT thing and the
-  // two get confused.
+  // the committed local path → id map (each backend's `assets` in `sync.json`;
+  // `assets.json` until 2026-09-20) is a DIFFERENT thing and the two get confused.
 
   return result
 }
@@ -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

@@ -14,13 +14,16 @@
 // carries the verbatim `site.yml::foundation` string (the round-trip source of
 // truth).
 //
-// IDENTITY. The ENTITY `$uuid` lives in `site.yml` (top-level `$uuid`); we read it,
-// send it, and back-fill the minted value there. Nested pages/sections carry a `$id`
-// handle AND a per-item `$uuid`.
+// IDENTITY. The ENTITY `$uuid` is a backend's, recorded per backend in `sync.json`
+// (`backends.<origin>.site.uuid`): we read the one for the backend a document is
+// produced FOR, send it, and record the minted value there. Nested pages/sections
+// carry a `$id` handle AND a per-item `$uuid`. ⚠️ The entity `$uuid` lived in
+// `site.yml` until 2026-09-20 — one value, with no way to say which backend minted it.
 //
 // The per-item uuid is NOT authored — author files never carry sync uuids. It is
-// stamped at emit (`stampUnitUuids`) from an out-of-band cache populated by whatever
-// the backend last reported: a pull, or a push response's `finalized[].document`.
+// stamped at emit (`stampUnitUuids`) from that backend's `items` map in `sync.json`,
+// written from whatever the backend last reported: a pull, or a push response's
+// `finalized[].document`. (The map sat in the gitignored sync cache until 2026-09-20.)
 // This is load-bearing, not bookkeeping: the backend matches records by uuid, and
 // `pages` / `page_sections` / `layout_sections` are all `multi` sections, where a
 // uuid-less record is read as NEW — inserted, with its stored counterpart deleted as
@@ -67,6 +70,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'
@@ -384,7 +388,7 @@ const CATCH_ALL_MARKER = '...path'
 //     `page_sections`). Cross-section parentage is pure structure, never `$parent`.
 //   - `$id` (the stableId — the in-file handle) rides at every item level as the
 //     wire-only closure handle. Per-item `$uuid` is NOT authored here: it is
-//     stamped on by `stampUnitUuids` at emit, from the out-of-band identity cache,
+//     stamped on by `stampUnitUuids` at emit, from the backend's `items` map in `sync.json`,
 //     because the backend matches records by uuid and a uuid-less record in a
 //     `multi` section is read as new (inserted, stored counterpart deleted). See
 //     the IDENTITY note in the file header and `site-diff.js`.
@@ -400,8 +404,8 @@ const SITE_MODEL_NAME = '@uniweb/site-content'
 // `fields` already carries `stable_id` (the Model field); `$id` is the same value.
 // Both are kept: `$id` is the sync handle, `stable_id` is the declared content field
 // the editor/render reads. Per-item `$uuid` is added later by `stampUnitUuids` (it
-// comes from the identity cache, not from the authored files) — see the IDENTITY
-// note in the file header.
+// comes from `sync.json`, not from the authored files) — see the IDENTITY note in
+// the file header.
 function withIdentity(id, fields) {
   return Object.assign({ $id: id }, fields)
 }
@@ -974,8 +978,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 +1066,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 +1086,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
@@ -1207,13 +1217,15 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
 /**
  * Map a file site project to the nested `@uniweb/site-content` `$`-document
  * (see the lane header above). PURE — reads the project, never mints, never writes.
- * The entity `$uuid` comes from `site.yml::$uuid` (back-filled after first sync);
- * nested items carry `$id` only.
+ * The entity `$uuid` is `opts.backend`'s, from `sync.json` (recorded after the first
+ * sync to it); nested items carry `$id` only.
  *
  * @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).
+ *        is `opts.backend`'s site uuid in `sync.json` (absent on a first sync to it,
+ *        or with no backend — a `$id`-only document).
  * @param {string} [opts.sourceLocale] - localized-field wrap locale. Defaults to
  *        the site's effective default locale (`defaultLanguage || languages[0] ||
  *        'en'` — the shared `resolveDefaultLocale` rule), NOT a bare 'en'.
@@ -1300,9 +1312,10 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // deploy-derived `info` field framework sends is `foundation`, via `injectInfo`
   // in `publish`.
   //
-  // ⚠️ The note stays because `assets.json` — the COMMITTED local map from an
-  // author's asset path to the backend's content-addressed id — is a different
-  // thing with a similar name, and it is very much alive.
+  // ⚠️ The note stays because the COMMITTED local map from an author's asset path
+  // to the backend's content-addressed id — each backend's `assets` in `sync.json`,
+  // `assets.json` until 2026-09-20 — is a different thing with a similar name, and
+  // it is very much alive.
   setIf(info, 'favicon', siteYml.favicon)
   // Site-level SEO/social metadata — the same shape as page.yml's `seo:` + the
   // top-level `keywords`, hoisted to the site root so the homepage social card
@@ -1413,7 +1426,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   //     a site-root path to an image in the project, which push uploads like any
   //     content image and sends as its serve URL, and which pull puts back as the
   //     path the author wrote (`restoreAssetRefs` recognizes the URL by the
-  //     fingerprint `assets.json` recorded for it).
+  //     fingerprint recorded for it in `sync.json`'s asset map).
   // The app leaves an author's value alone.
   //
   // ⚠️ Until 2026-09-10 framework emitted no preview, on the premise that the host
@@ -1494,11 +1507,15 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // config (the records themselves are separate entities; this is just the config).
   const colConfig = await resolveQueriesConfig(siteRoot, { siteYml })
 
-  // `$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.
+  // `$uuid?` then `$id` `$model`, then sections in Model-declared order.
   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 +1554,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
 }
@@ -1576,25 +1597,30 @@ export async function emitSiteSyncPackage(siteRoot, opts = {}) {
 // Identity back-fill.
 //
 // The ENTITY `$uuid` (the backend's identity for the whole site-content entity) is
-// back-filled into `site.yml::$uuid` after the first sync. That is the ONLY backend
-// uuid for site-content — its nested pages/sections sync wholesale (collision=force),
-// so there is no per-item uuid round-trip. Per-item identity for the eventual PULL is
-// recovered by in-file `stableId` + content-match (Plan D), not a local id store.
+// recorded after the first sync to a backend, in that backend's section of
+// `sync.json`, beside the org the site was created under. Per-item uuids round-trip
+// too, through the same section's `items` map — see the IDENTITY note in the file
+// header. ⚠️ Until 2026-09-21 this note put the entity `$uuid` in `site.yml`, where it
+// lived until 2026-09-20, and said nested items have no per-item uuid round-trip,
+// which the file header says is not so.
 // ===========================================================================
 
 /**
- * Back-fill the minted site-content entity `$uuid` into `site.yml` (top-level
- * `$uuid`), preserving the file's comments and key order.
+ * Record the minted site-content entity `$uuid` as `backend`'s site, in `sync.json`
+ * (`backends.<origin>.site.uuid`). Until 2026-09-20 it was back-filled into
+ * `site.yml` as a top-level `$uuid`.
  * @param {string} siteRoot
+ * @param {string} backend - the origin of the backend that minted it
  * @param {string} uuid - the entity uuid the backend minted/echoed
- * @returns {boolean} true if site.yml changed
+ * @returns {boolean} true if sync.json 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 } })
 }
 
 /**
- * Record the org the site was CREATED under (`site.yml::$org`), beside `$uuid`.
+ * Record the org the site was CREATED under — `backend`'s `site.org` in `sync.json`,
+ * beside the site's uuid. (It was `site.yml::$org` until 2026-09-20.)
  *
  * The org is consumed at exactly one moment — the `as_org` on the create that
  * mints `$uuid` — and after that the uuid carries the ownership binding. So this
@@ -1602,15 +1628,11 @@ export function writeSiteEntityUuid(siteRoot, uuid) {
  * this site's storage charged to?"*, which `$uuid` alone cannot answer and which
  * otherwise costs a backend round-trip (or is simply unknowable from the repo).
  *
- * Stored as the BARE handle, never `@handle`: `upsertYamlScalar` writes the value
- * verbatim, and `@` is a reserved YAML indicator, so a plain scalar may not start
- * with one — `$org: @acme` is a parse error. The bare form is also the canonical
- * one everywhere else (`deriveScope` returns it, `createOrg` echoes it as
- * `org.handle`, `validateHandle` validates it); the `@` is display sugar the
- * reader re-adds.
- *
- * Safe to add to `site.yml` because the sync lane is an explicit allowlist
- * (`info.*` above is built key by key), so this never rides the wire.
+ * Stored as the BARE handle, never `@handle` — the canonical form everywhere else
+ * (`deriveScope` returns it, `createOrg` echoes it as `org.handle`,
+ * `validateHandle` validates it); the `@` is display sugar the reader re-adds. In
+ * `site.yml` it was also the only form that parsed: `@` is a reserved YAML
+ * indicator, so `$org: @acme` is an error.
  *
  * ⛔ NOT `deploy.yml`, though that file already holds the bound `backend` and the
  * two look like the same class of fact. Four reasons, and the first is the one that
@@ -1618,9 +1640,9 @@ export function writeSiteEntityUuid(siteRoot, uuid) {
  *
  *  1. CARDINALITY. `deploy.yml` is multi-TARGET and `backend` sits *under* a target,
  *     so its shape says "this may vary per target." An org may not: one site has one
- *     owning org, fixed at create and preserved on replace. `$org` is a property of
- *     `$uuid`, which is singular and lives here — filing it under a target would
- *     encode a freedom that does not exist.
+ *     owning org, fixed at create and preserved on replace. The org is a property of
+ *     the site's uuid, and sits beside it in the same backend's section — filing it
+ *     under a target would encode a freedom that does not exist.
  *  2. WHO WRITES. Three paths mint a site (`ensureSiteExists`, the media-less push's
  *     content-lane create, and `clone` seeding an existing one) and **none of them
  *     write `deploy.yml`** — only `deploy` and `publish` call `recordLastDeploy`. The
@@ -1633,51 +1655,19 @@ export function writeSiteEntityUuid(siteRoot, uuid) {
  *     ever being deployed. Ownership does not belong in a record of a deploy that
  *     may not have happened.
  *
- * `backend` answers *where this ships*; `$org` answers *whose this is*.
+ * `backend` answers *where this ships*; `site.org` answers *whose this is*.
  *
  * @param {string} siteRoot
+ * @param {string} backend - the origin of the backend the site was created on
  * @param {string} handle - the bare org handle (no leading `@`)
- * @returns {boolean} true if site.yml changed
+ * @returns {boolean} true if sync.json 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 } : {}),
@@ -288,16 +290,20 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   const folder = buildFolderEntity({
     recordEntities: col.entities,
     ...(sourceLocale ? { sourceLocale } : {}),
-    // ⭐ AUTHORED, from `records.yml`. It used to be derived — one branch per
-    // collection — which made the folder a shadow of a directory layout rather
-    // than something the author states.
-    folderNodes: col.folder?.nodes ?? [],
-    // ⛔ Whether `records.yml` EXISTS — not whether it holds anything. Missing is
-    // inert; empty is a folder that REMOVES. Compared against the affirmative
-    // value, never `!== 'missing'`: an absent state would read as declared, and
-    // that is precisely how a site with no records.yml once emitted a folder that
-    // would have emptied the live one.
-    declared: col.recordsState === 'empty' || col.recordsState === 'declared',
+    // ⭐ Every record in the directory, at the top of the folder or in the
+    // sub-folder `records.yml` places it in — and NOTHING when there is no folder to
+    // state. ⛔ Gated here as well as by `declared`, because the builder sends any
+    // non-empty tree: a `records.yml` whose folders hold only records that resolved
+    // no schema is a tree of empty branches, and sending it would replace the
+    // backend's folder with them (measured on the `dynamic` template, 2026-09-21).
+    folderNodes: col.sendFolder === true ? (col.folder?.nodes ?? []) : [],
+    // ⛔ Whether the file side HAS a folder to state (`records.js::sendsFolder`) —
+    // not whether it holds anything. A site with no records directory sends none
+    // and leaves the backend's alone; an empty directory sends an empty folder,
+    // which REMOVES (the CLI asks first). Compared as `=== true`: an absent value
+    // must read as "nothing to state", which is how a site with no records.yml once
+    // emitted a folder that would have emptied the backend's.
+    declared: col.sendFolder === true,
     // Placement identity from the folder document a previous push returned.
     // Absent on a first push — every item is genuinely new then. Its ABSENCE on a
     // later push is what made `publish` after `push` fail: send-only-changed skips
@@ -306,9 +312,9 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     ...(opts.folderItemUuids ? { itemUuids: opts.folderItemUuids } : {}),
   })
   // ⚠️ A placement that produced no entity is dropped by the builder rather than
-  // sent pointing at nothing — but it must still be SAID. It means an entity was
-  // placed in records.yml and then skipped upstream (a schema that did not
-  // resolve, most often), and the record is simply absent from the site.
+  // sent pointing at nothing — but it must still be SAID. `buildRecordEntities`
+  // places only records it produced, so this is a guard on the pairing rather than
+  // an expected path.
   if (folder?.warnings?.length) warnings.push(...folder.warnings)
 
   // `queryUuids` — identity for the `queries` section, keyed by query
@@ -316,6 +322,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
@@ -400,8 +408,8 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     // ⛔ No identity attrs on `info`: it is a Section whose fields the host declares,
     // and `preview` is a real ASSET_SLOTS slot, so stamping would add
     // `previewAssetId`/`previewAssetExt` — fields the host refuses. Its bare strings
-    // are still swapped for their serve URLs, which `assets.json` recognizes on pull
-    // by fingerprint (asset-map.js → `servedFingerprint`).
+    // are still swapped for their serve URLs, which the asset map in `sync.json`
+    // recognizes on pull by fingerprint (asset-map.js → `servedFingerprint`).
     if (siteDoc) rewriteEntityAssets(siteDoc, assetRewrite, assetIds, siteDoc.info)
     for (const e of col.entities) rewriteEntityAssets(e.document, assetRewrite, assetIds)
   }