@uniweb/build 0.62.0 → 0.63.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.62.0",
+  "version": "0.63.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -60,9 +60,9 @@
     "@uniweb/content-reader": "^1.2.5",
     "@uniweb/content-writer": "^0.3.4",
     "@uniweb/schemas": "^0.7.0",
+    "@uniweb/projections": "^0.7.3",
     "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/theming": "^0.1.15",
-    "@uniweb/projections": "^0.7.3"
+    "@uniweb/theming": "^0.1.15"
   },
   "optionalDependencies": {
     "@uniweb/runtime": "^0.27.4"
@@ -74,8 +74,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/runtime": "^0.27.4",
-    "@uniweb/core": "^0.29.8"
+    "@uniweb/core": "^0.29.8",
+    "@uniweb/runtime": "^0.27.4"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/uwx/folder.js

@@ -7,9 +7,10 @@
 //   - `contents` is the self-nesting tree (an array), nesting via `$children` — the
 //     same mechanism site-content pages/sections use. Each node holds REFERENCES,
 //     never content:
-//       - a LEAF references one record entity: `{ kind: 'ref', name, ... }` with
-//         `entry: <uuid>` once the record was minted (back-filled into its file),
-//         or `$ref: "<id>"` while brand-new (resolved within this payload).
+//       - a LEAF references one record entity: `{ kind: 'ref', name, entry }` —
+//         `entry: { schema, entity: <uuid> }` once the record was minted (back-filled
+//         into its file), or `entry: { $ref: "<$id>" }` while brand-new (resolved
+//         within this payload).
 //       - a BRANCH is a sub-folder: `{ kind: 'branch', name, label?, $children }`.
 //
 // ⭐ A LEAF'S `name` IS ITS RECORD'S HANDLE — the slug, the records service's `$name` —
@@ -55,8 +56,13 @@ export const FOLDER_ENTITY_KEY = '@folder'
 // field is polymorphic (it can reference any data schema), so the ref uses the
 // entity_ref OPEN form `{ schema, entity }` — not a bare uuid (a bare uuid is only
 // valid when the field pins a single schema). Known uuid → `entry: { schema, entity
-// }`; brand-new → `$ref` handle (resolved within this payload to the minted
-// entity).
+// }`; brand-new → `entry: { $ref: <$id> }`, the record's payload-local handle, which
+// the backend resolves to the uuid it mints for that record in the same package.
+//
+// ⛔ `$ref` IS THE REFERENCE'S VALUE, NOT A KEY OF THE LEAF (2026-09-25). A backend
+// resolves `{ $ref }` wherever a reference value goes, and refuses the key form it
+// replaced, `{ kind: 'ref', name, $ref }`. There is no window: a CLI that writes the key
+// form cannot push a site with a record new to that backend.
 //
 // ⭐ `schema` carries the data schema's SCOPED NAME (`@std/article`), never a Model id
 // — agreed with backend 2026-09-24: a Model id is the backend's internal identity and
@@ -68,7 +74,7 @@ export const FOLDER_ENTITY_KEY = '@folder'
 function refLeaf(entity) {
   const leaf = { kind: 'ref', name: entity.slug }
   if (entity.uuid) leaf.entry = { schema: entity.model, entity: entity.uuid }
-  else leaf.$ref = entity.id // the payload-local handle
+  else leaf.entry = { $ref: entity.id } // the payload-local handle
   return leaf
 }
 
@@ -76,7 +82,7 @@ function refLeaf(entity) {
  * Turn the placed records into folder `contents`.
  *
  * ⛔ A LEAF WHOSE ENTITY IS MISSING IS DROPPED AND REPORTED, never emitted empty.
- * A `ref` with neither `entry` nor `$ref` is a placement pointing at nothing —
+ * A `ref` with no `entry` is a placement pointing at nothing —
  * the backend cannot resolve it, and the failure would surface there rather than
  * here, as somebody else's error.
  *
@@ -108,7 +114,8 @@ function contentsFromNodes(nodes, byEntityId, missing, sourceLocale) {
 }
 
 // The uuid of the record a leaf references — once minted, `entry: { schema, entity }`
-// (a bare uuid is tolerated). A brand-new record's leaf carries `$ref` instead.
+// (a bare uuid is tolerated). A brand-new record's leaf carries `entry: { $ref }`, and
+// has none.
 function recordOf(item) {
   if (item?.kind !== 'ref') return null
   const e = item.entry

package/src/uwx/records.js

@@ -25,14 +25,18 @@
 //
 // ⭐ A REFERENCE (`entity_ref`) NAMES ITS RECORD BY HANDLE in a file — `speaker: ada`,
 // the target's file name or its `slug:` — and is sent as the uuid THIS backend minted for
-// that record (`refResolver`). A target this backend has not minted yet (new in this
-// push) cannot be named on the wire, so its referrer WAITS: sent without that reference
-// and completed by the next pass, or held back when it cannot exist without it — see
-// `sync-package.js`, and the CLI's `pushInPasses`, which repeats the push.
+// that record (`refResolver`). A target this backend has not minted yet is new, so this
+// push creates it, and the reference names it by its `$id` in the package —
+// `speaker: { $ref: "speaker/ada" }` — which the backend resolves to the uuid it mints.
+// One push creates both. ⛔ Until 2026-09-25 such a referrer WAITED, sent without the
+// reference or held back, and the CLI pushed again to complete it.
 // ⚠️ item_ref and file fields are still sent as the file writes them.
 //
 // ⚠️ A record of a `many` section is sent without a `$uuid`, so a push that changes a
-// record replaces that section's records rather than updating them in place.
+// record whose section the backend already holds is REFUSED, whole (`identity_required`):
+// applied, it would re-identify every stored item. Measured 2026-09-25 — this said such a
+// push "replaces that section's records" until then. Its first push, which creates the
+// items, is not affected.
 
 import { readBackendState } from './sync-store.js'
 import { readFileSync, existsSync } from 'node:fs'
@@ -85,7 +89,7 @@ const RECORD_KEYS = new Set([
 
 // Recursively drop IDENTITY `$`-sigil keys (`$uuid`/`$id`/`$schema`/… — never
 // field data; the sigil-exclusivity invariant guarantees this) at every level,
-// so a back-filled `$uuid` doesn't change the hash. Two are exceptions, because
+// so a back-filled `$uuid` doesn't change the hash. Three are exceptions, because
 // they are content rather than identity:
 //   - `$children` is STRUCTURAL content (a self-nesting record's subtree, e.g.
 //     site-content's nested pages/sections), so it is KEPT and recursed into —
@@ -94,15 +98,21 @@ const RECORD_KEYS = new Set([
 //   - `$disabled` is a record's delivery STATE (`draft: true` on the file side). It
 //     is KEPT so that drafting or un-drafting a record with nothing else changed is
 //     still sent; stripped, "send only changed" would never send the toggle.
+//   - `$ref` is a REFERENCE to a record the same push creates (`speaker: { $ref:
+//     "speaker/ada" }`), and which record it names is content. Once the backend has
+//     minted that record the next push names it by uuid instead — so the CLI re-banks a
+//     record that sent a `$ref` after its push (`namesNew`, `sync-package.js`). The
+//     folder's ref leaf is not this case: see below.
 function stripSigils(value) {
   if (Array.isArray(value)) return value.map(stripSigils)
   if (value && typeof value === 'object') {
     // ⛔ A `@uniweb/folder` REF LEAF ENCODES ONE REFERENCE TWO WAYS, and hashing the
     // encoding rather than the reference made the folder's hash unreproducible.
     //
-    // `refLeaf` (uwx/folder.js) emits `$ref: <the record's $id>` — the pool position
-    // `<dirs>/<slug>` — while the record is brand-new, and `entry: { schema, entity:
-    // <uuid> }` once it has been minted.
+    // `refLeaf` (uwx/folder.js) emits `entry: { $ref: <the record's $id> }` — the pool
+    // position `<dirs>/<slug>` — while the record is brand-new, and `entry: { schema,
+    // entity: <uuid> }` once it has been minted. (`$ref` was a key of the leaf itself
+    // until 2026-09-25, when the backend made it a reference's value.)
     // Both denote the same record. A push hashes the folder BEFORE submitting, then
     // back-fills the minted `$uuid` into every record's source file — so the very
     // next emit builds the OTHER encoding, and the hash the push just banked can
@@ -116,19 +126,20 @@ function stripSigils(value) {
     // `name` (the record's handle) at its position inside the branch that holds it.
     // Two siblings may share a name — records of different schemas can — and position
     // still tells them apart; a leaf that comes to reference another record arrives
-    // with that record changed, which re-sends the folder anyway. `$ref` adds a
-    // payload-local handle and `entry` adds identity, and both are exactly what
-    // `$uuid` is stripped for.
+    // with that record changed, which re-sends the folder anyway. `entry` carries a
+    // payload-local handle or an identity, and both are exactly what `$uuid` is
+    // stripped for.
     //
     // ⚖️ The previous rule kept `$ref` "so a reference change is visible". It still
     // is: point a leaf at a different record and its `name` moves with it.
     const isFolderRefLeaf = value.kind === 'ref'
     const out = {}
     for (const [k, v] of Object.entries(value)) {
-      if (isFolderRefLeaf && (k === '$ref' || k === 'entry')) continue
-      // `$children` (a self-nesting subtree) and `$disabled` (a delivery state) are
-      // CONTENT, not identity sigils — kept, so a change to either stays visible.
-      if (k === '$children' || k === '$disabled') {
+      if (isFolderRefLeaf && k === 'entry') continue
+      // `$children` (a self-nesting subtree), `$disabled` (a delivery state) and `$ref`
+      // (a reference to a record of the same push) are CONTENT, not identity sigils —
+      // kept, so a change to any of them stays visible.
+      if (k === '$children' || k === '$disabled' || k === '$ref') {
         out[k] = stripSigils(v)
         continue
       }
@@ -218,11 +229,10 @@ function encodeFieldValue(value, field, sourceLocale, translations) {
  * @param {{ resolve: (model: string, value: *) => object }} [params.refs] - what a
  *        reference sends (`refResolver`). Without it a reference is sent as written.
  * @returns {{ entities: object[], warnings: string[], refusals: string[] }} each
- *   entity is `{ id, uuid, model, file, document, pending }` — `document` is the
- *   section-keyed body, and `pending` the references it WAITS on, left out of it:
- *   `{ path, model, name, required }`, one per reference whose record this backend has
- *   not minted yet. `refusals` names the records that cannot be sent as written, one
- *   line each; a caller that sends must not send while any is present.
+ *   entity is `{ id, uuid, slug, model, file, document, namesNew }` — `document` is the
+ *   section-keyed body, and `namesNew` how many of its references name a record this
+ *   push creates, by `$ref`. `refusals` names the records that cannot be sent as
+ *   written, one line each; a caller that sends must not send while any is present.
  */
 export function recordsToEntities({
   label,
@@ -324,10 +334,7 @@ export function recordsToEntities({
       )
     }
     if (!enc.misplaced.length && !enc.shape.length) {
-      // A required reference that waits for its record is owed, not missing: the push
-      // that completes the record sends it (see `pending` below).
-      const waiting = new Set(enc.pending.map((p) => `"${p.path}"`))
-      const missing = missingRequired(layout, sections).filter((m) => !waiting.has(m))
+      const missing = missingRequired(layout, sections)
       if (missing.length) {
         refusals.push(
           `${where}: ${declaration.name} requires ${listOf(missing)}, and this record ` +
@@ -364,7 +371,7 @@ export function recordsToEntities({
       // unique within its schema folder, and an authored `$id` need not be.
       file: `entities/${label}/${slug}.json`,
       document,
-      pending: enc.pending,
+      namesNew: enc.namesNew,
     })
   }
   return { entities, warnings, refusals }
@@ -374,7 +381,7 @@ export function recordsToEntities({
 // schema, the keys written flat in a schema written by section, and values of the
 // wrong shape for their section.
 function encoder(sourceLocale, translations, refs = null) {
-  return { sourceLocale, translations, refs, undeclared: [], misplaced: [], shape: [], pending: [], unresolved: [] }
+  return { sourceLocale, translations, refs, undeclared: [], misplaced: [], shape: [], unresolved: [], namesNew: 0 }
 }
 
 // A flat record: its keys, minus the record's own, are the one section's fields.
@@ -478,10 +485,10 @@ function encodeRecord(fields, value, enc, prefix, reserved) {
 const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
 
 // A reference, as a push sends it: the uuid this backend minted for the record the file
-// names (`refResolver`). A list of them is each of those. One whose record this backend
-// has not minted yet is left out and noted as WAITING (`enc.pending`) — the push that
-// completes it sends it. Without a resolver, and for a reference open to several Models
-// (which our schemas do not author), the value is sent as written.
+// names (`refResolver`) — or, for a record it has not minted, which this push creates,
+// `{ $ref: <that record's $id> }`, the backend's name for a record of the same package.
+// A list of them is each of those. Without a resolver, and for a reference open to
+// several Models (which our schemas do not author), the value is sent as written.
 function encodeReference(value, field, enc, path) {
   if (!enc.refs || typeof field.model !== 'string') return value
   if (field.multiple === true) {
@@ -490,27 +497,23 @@ function encodeReference(value, field, enc, path) {
       return undefined
     }
     const sent = []
-    const waiting = []
     value.forEach((one, i) => {
-      const uuid = resolveReference(one, field, enc, `${path}[${i}]`, waiting)
-      if (uuid !== undefined) sent.push(uuid)
+      const ref = resolveReference(one, field, enc, `${path}[${i}]`)
+      if (ref !== undefined) sent.push(ref)
     })
-    // A required list with nothing to send yet waits whole; otherwise what is known goes now.
-    const required = field.required === true && sent.length === 0
-    for (const w of waiting) enc.pending.push({ ...w, required })
     return sent
   }
-  const waiting = []
-  const uuid = resolveReference(value, field, enc, path, waiting)
-  for (const w of waiting) enc.pending.push({ ...w, required: field.required === true })
-  return uuid
+  return resolveReference(value, field, enc, path)
 }
 
-function resolveReference(value, field, enc, path, waiting) {
+function resolveReference(value, field, enc, path) {
   const answer = enc.refs.resolve(field.model, value)
   if (answer.uuid) return answer.uuid
-  if (answer.pending) waiting.push({ path, model: field.model, name: value })
-  else enc.unresolved.push({ path, model: field.model, value, ...answer })
+  if (answer.ref) {
+    enc.namesNew++
+    return { $ref: answer.ref }
+  }
+  enc.unresolved.push({ path, model: field.model, value, ...answer })
   return undefined
 }
 
@@ -527,31 +530,34 @@ function describeUnresolved({ path, model, value, invalid, ambiguous }) {
 // own id (mapped like a handle's), or the backend's id of a record the project does not
 // hold, which is what a pull writes for one.
 //
-// ⛔ A record this backend has not minted yet — never pushed there — answers `pending`: a
-// uuid it did not mint is never sent (see `buildRecordEntities`), so its referrer waits.
+// ⭐ A record this backend has not minted yet — never pushed there — answers with its
+// `$id` (`ref`): it is new, so this push creates it, and the backend takes
+// `{ $ref: <$id> }` for a record of the same package. A uuid it did not mint is never
+// sent (see `buildRecordEntities`).
 const AMBIGUOUS = Symbol('ambiguous')
 function refResolver(readSchemas, recordMap) {
-  const byModel = new Map() // Model → handle → the record's own id (null before its first push)
-  const ownIds = new Set()
+  const byModel = new Map() // Model → handle → the record: its own id (null before its first push) and `$id`
+  const byOwnId = new Map() // the record's own id → the record
   for (const { declaration, flat } of readSchemas) {
     let names = byModel.get(declaration.name)
     if (!names) byModel.set(declaration.name, (names = new Map()))
     for (const rec of flat) {
       const own = typeof rec.$uuid === 'string' && rec.$uuid ? rec.$uuid : null
-      names.set(rec.slug, names.has(rec.slug) ? AMBIGUOUS : own)
-      if (own) ownIds.add(own)
+      const record = { own, id: rec.$id }
+      names.set(rec.slug, names.has(rec.slug) ? AMBIGUOUS : record)
+      if (own) byOwnId.set(own, record)
     }
   }
-  const minted = (own) => (own && recordMap[own] ? { uuid: recordMap[own] } : { pending: true })
+  const sent = ({ own, id }) => (own && recordMap[own] ? { uuid: recordMap[own] } : { ref: id })
   return {
     resolve(model, value) {
       if (typeof value !== 'string' || value === '') return { invalid: true }
       const names = byModel.get(model)
       if (names?.has(value)) {
-        const own = names.get(value)
-        return own === AMBIGUOUS ? { ambiguous: true } : minted(own)
+        const record = names.get(value)
+        return record === AMBIGUOUS ? { ambiguous: true } : sent(record)
       }
-      if (isUuid(value)) return ownIds.has(value) ? minted(value) : { uuid: value }
+      if (isUuid(value)) return byOwnId.has(value) ? sent(byOwnId.get(value)) : { uuid: value }
       return { missing: true }
     },
   }
@@ -1008,7 +1014,7 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
 
   // ⭐ EVERY MODEL'S RECORDS ARE READ BEFORE ANY IS MAPPED: a reference names a record
   // of another Model by its handle (`speaker: ada`), and the push sends that record's
-  // uuid in its place (`refResolver`).
+  // uuid in its place — or its `$id`, while it is new (`refResolver`).
   const readSchemas = []
   for (const [schema, poolEntities] of poolBySchema) {
     const label = poolEntities[0].dirs.join('/')

package/src/uwx/registry-package.js

@@ -157,7 +157,56 @@ function buildDataSchemaEntities(dataSchemas, scope) {
       // way; item_ref `options` get the full `@org/x/<section>` path (§10.1).
       ...toDataSchemaDeclaration(normalized, { name: scoped(ref), resolveName: scoped, resolveOptions }),
     }))
-  return { entities, scoped, org }
+  return { entities: referencedFirst(entities), scoped, org }
+}
+
+/**
+ * The data schemas in an order a backend can install one at a time: a schema another one in
+ * the package references comes BEFORE it — alphabetical otherwise, so the order is stable.
+ *
+ * ⭐ WHY. A backend installs a package's data schemas in the order they arrive, and refuses a
+ * reference to a Model it holds neither yet nor from before: measured 2026-09-25, a foundation
+ * whose `exhibit` references its own `specimen` was refused whole — *"entity_ref target
+ * `@x/specimen` matches no model declared in this fixture or registered on the host"* — because
+ * `exhibit` sorts first. Alphabetical order was right only by luck (`speaker` before `talk`).
+ *
+ * ⚠️ A CYCLE CANNOT BE ORDERED — `author` names `book` and `book` names `author` — and keeps
+ * the order the walk gives it. Whether one package may reference itself in any order is the
+ * backend's to accept; this only stops refusing what an order can fix. A schema naming ITSELF
+ * is not a dependency.
+ *
+ * @param {Array<{ name: string, sections?: object }>} entities - lowered declarations
+ * @returns {Array} the same entities, referenced ones first
+ */
+function referencedFirst(entities) {
+  const byName = new Map(entities.map((e) => [e.name, e]))
+  const targets = (entity) => {
+    const out = new Set()
+    const walk = (fields) => {
+      for (const field of Object.values(fields || {})) {
+        if (!field || typeof field !== 'object') continue
+        if (field.type === 'entity_ref') for (const m of [field.model].flat()) out.add(m)
+        // `options: '@org/x/<section>'` names a section of Model `@org/x`.
+        if (field.type === 'item_ref' && typeof field.options === 'string') {
+          out.add(field.options.split('/').slice(0, 2).join('/'))
+        }
+        if (field.type === 'section') walk(field.fields)
+      }
+    }
+    for (const section of Object.values(entity.sections || {})) walk(section.fields)
+    return [...out].filter((name) => name !== entity.name && byName.has(name)).sort()
+  }
+  const ordered = []
+  const state = new Map() // name → 'visiting' | 'done'
+  const visit = (entity) => {
+    if (state.get(entity.name)) return // done, or on the walk now — a cycle
+    state.set(entity.name, 'visiting')
+    for (const name of targets(entity)) visit(byName.get(name))
+    state.set(entity.name, 'done')
+    ordered.push(entity)
+  }
+  for (const entity of entities) visit(entity)
+  return ordered
 }
 
 // The shared `.uwx` envelope (uwx/1 + exporter + timestamp) around an entity list.

package/src/uwx/sync-package.js

@@ -33,18 +33,6 @@ const SITE_ENTITY_KEY = 'site-content'
 
 const cacheKey = (entity) => `${entity.model} ${entity.id}`
 
-// The folder's placements without the records a push leaves out — `{ kind: 'ref' }` leaves
-// naming them by `$entityId`, inside any branch.
-function withoutRecords(nodes, ids) {
-  if (!ids.size) return nodes
-  const out = []
-  for (const node of nodes || []) {
-    if (node?.kind === 'branch') out.push({ ...node, $children: withoutRecords(node.$children, ids) })
-    else if (!ids.has(node?.$entityId)) out.push(node)
-  }
-  return out
-}
-
 // Attach the push gate's optimistic-concurrency token to an entity, keyed by the
 // BACKEND uuid in its document body (`$uuid`). A never-synced entity has no
 // `$uuid` and therefore no base — correctly unconditional, since there is no
@@ -265,11 +253,10 @@ function rewriteEntityAssets(node, map, ids, noStamp = null) {
  *   records: { buffer, entityCount, index, models }|null,
  *   hashes: Object<string,string>, warnings: string[], refusals: string[],
  *   skipped: number, schemaless: Array<{name: string, model: string}>,
- *   localAssets: string[], applied: object,
- *   waiting: Array<{id: string, model: string, slug: string, held: boolean, pending: object[]}> }>}
- *   `waiting` lists the records whose references name a record this backend has not
- *   minted yet — sent without them, or held back. A caller that sends pushes again
- *   once this push has been applied (`records.js::encodeReference`).
+ *   localAssets: string[], applied: object, namesNew: string[] }>}
+ *   `namesNew` lists the records this package sends whose references name a record it
+ *   creates — by `$ref`, where the next push will send a uuid — as keys of `hashes`. A
+ *   caller that banks `hashes` re-banks these once the push is applied.
  *   `refusals` names the records that cannot be sent as written, one line each
  *   (`records.js::recordsToEntities`). A caller that submits must not submit while
  *   any is present: the backend would refuse the records lane — or, for a record
@@ -316,43 +303,10 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   })
   const warnings = [...col.warnings, ...(col.folder?.warnings ?? [])]
 
-  // ⭐ RECORDS WAITING FOR A REFERENCE (`records.js::encodeReference`). A record whose
-  // reference names a record this backend has not minted yet cannot name it on the wire,
-  // so this push sends what it can and the next pass completes it (the CLI's
-  // `pushInPasses`):
-  //   · new, and nothing it waits for is required → sent now without those references,
-  //     so after one pass every record exists, whatever refers to what;
-  //   · new, and a required reference waits → HELD and placed nowhere: it cannot be
-  //     created without it;
-  //   · already on this backend → HELD, left as it is there: sent without a reference it
-  //     has, it would lose that reference until the next pass.
-  // A held record is not sent and keeps the hash last banked for it, so the next pass
-  // sees it as changed.
-  const held = new Set()
-  const unplaced = new Set()
-  for (const e of col.entities) {
-    if (!e.pending?.length) continue
-    if (e.uuid) held.add(e.id)
-    else if (e.pending.some((p) => p.required)) {
-      held.add(e.id)
-      unplaced.add(e.id)
-    }
-  }
-  const waiting = col.entities
-    .filter((e) => e.pending?.length)
-    .map((e) => ({ id: e.id, model: e.model, slug: e.slug, held: held.has(e.id), pending: e.pending }))
-  const placedEntities = []
-  const placedIndex = []
-  col.entities.forEach((e, i) => {
-    if (unplaced.has(e.id)) return
-    placedEntities.push(e)
-    placedIndex.push(col.index[i])
-  })
-
   // The folder rides over the FULL record set (before filtering) so its references
   // are complete — new records by `$ref`, already-minted ones by `entry: <uuid>`.
   const folder = buildFolderEntity({
-    recordEntities: placedEntities,
+    recordEntities: col.entities,
     ...(sourceLocale ? { sourceLocale } : {}),
     // ⭐ Every record in the directory, at the top of the folder or in the
     // sub-folder `folder.yml` places it in — and NOTHING when there is no folder to
@@ -360,7 +314,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     // non-empty tree: a `folder.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 ? withoutRecords(col.folder?.nodes ?? [], unplaced) : [],
+    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,
@@ -518,21 +472,22 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   // changed() has side effects (hashes/skipped), so evaluate every entity exactly
   // once, in a stable order: folder, then each record.
   const folderChanged = folder ? changed(folder) : false
-  // A held record keeps its last banked hash — it was not sent (see `held` above).
-  const keepBanked = (entity) => {
-    const key = cacheKey(entity)
-    if (priorHashes[key] !== undefined) hashes[key] = priorHashes[key]
-    return false
-  }
-  const recordChanged = placedEntities.map((e, i) => ({
+  const recordChanged = col.entities.map((e, i) => ({
     entity: e,
-    index: placedIndex[i],
-    changed: held.has(e.id) ? keepBanked(e) : changed(e),
+    index: col.index[i],
+    changed: changed(e),
   }))
   const changedRecords = recordChanged.filter((r) => r.changed)
 
   let records = null
+  // ⭐ A RECORD THAT NAMES A RECORD THIS PUSH CREATES names it by `$ref`
+  // (`records.js::encodeReference`), and the backend stores the uuid it mints for it. The
+  // next push sends that uuid: the same reference, another encoding — and another hash.
+  // So the caller re-banks these records once the push is applied, or the next push
+  // sends every one of them again.
+  let namesNew = []
   if (folder && (folderChanged || changedRecords.length > 0)) {
+    namesNew = changedRecords.filter((r) => r.entity.namesNew > 0).map((r) => cacheKey(r.entity))
     // Folder first (always, for the `$ref` closure), then changed records. The
     // leading `{ kind: 'folder' }` keeps submission position 0 aligned for record
     // back-fill (backfillEntityUuids skips it — the folder has no uuid to write).
@@ -582,9 +537,8 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
 
   return {
     siteContent, records, siteContentUuid, hashes, warnings, skipped,
-    // Records waiting for a reference's record — see `held` above. Non-empty ⇒ the caller
-    // pushes again once this push has been applied.
-    waiting,
+    // Records that name a record this push creates — see `namesNew` above.
+    namesNew,
     refusals: col.refusals || [],
     schemaless: col.schemaless, localAssets, applied,
     // { stamped, unknown } when identity was applied; null when the caller passed