uniweb 0.68.0 → 0.69.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.68.0",
+  "version": "0.69.1",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,15 +41,15 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/core": "^0.29.8",
     "@uniweb/runtime": "^0.27.4",
-    "@uniweb/kit": "^0.19.4",
     "@uniweb/schemas": "^0.7.0",
-    "@uniweb/semantic-parser": "^1.4.1"
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/kit": "^0.19.4"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.62.0",
+    "@uniweb/build": "^0.63.1",
     "@uniweb/content-reader": "^1.2.5",
     "@uniweb/semantic-parser": "^1.4.1"
   },

package/partials/agents.md

@@ -896,7 +896,7 @@ The body — the value of the schema's content field, `article_body.content`.
 
 **A component receives it differently from how the file writes it**, the same way on a static site and a hosted one: the brief's fields at the top (`article.title`), every other section under its name (`article.article_body.content`, `article.article_body.author`), and `$name`, the handle. Lists carry the brief alone unless the query says otherwise (`deferred:`, below). Full rules: `reference/entity-content.md`.
 
-**A reference names the record it points at.** A `{ ref: '@/speaker' }` field is written as that record's name — `speaker: ada` for `records/speaker/ada.yml` (its file's name, or its `slug:`) — and a `many` one as a list of names. A component receives `{ entity, brief }`: the record reduced to its brief, so `talk.speaker.brief.name`. `uniweb validate` and a push report a name that matches no record; a push sends each reference to the record it names (a second pass when that record is new too), and a pull writes the name back.
+**A reference names the record it points at.** A `{ ref: '@/speaker' }` field is written as that record's name — `speaker: ada` for `records/speaker/ada.yml` (its file's name, or its `slug:`) — and a `many` one as a list of names. A component receives `{ entity, brief }`: the record reduced to its brief, so `talk.speaker.brief.name`. `uniweb validate` and a push report a name that matches no record; a push sends each reference to the record it names (in the same push when that record is new too), and a pull writes the name back.
 
 **`records/folder.yml` — optional, and only for folders.** It is the one file in `records/` that is not a record, it moves with the directory (`paths.records`), and like a pages folder's `folder.yml` it describes the folder it sits in. Every record sits at the top of the site's records folder unless `folder.yml` places it in a sub-folder. Add one only when a query needs to ask for a *slice* of the records rather than all of them — most sites never do:
 

package/src/backend/site-sync.js

@@ -42,7 +42,10 @@ import {
   updateBackendMap,
   clearBackendSections,
   normalizeBackendOrigin,
-  removeYamlScalar
+  removeYamlScalar,
+  harvestRecordItems,
+  storedRecordItems,
+  reprintRecordItems
 } from '@uniweb/build/uwx'
 
 // First entity `$`-document out of a `.uwx` we produced or the backend served.
@@ -62,6 +65,21 @@ function entityDocFromUwx(buf) {
   return null
 }
 
+// Every entity `$`-document of a `.uwx` — the folder lane holds the folder and its records.
+function entityDocsFromUwx(buf) {
+  const docs = []
+  if (!buf || buf.length < 2 || buf[0] !== 0x50 || buf[1] !== 0x4b) return docs
+  for (const [name, data] of readZip(buf)) {
+    if (name === 'manifest.json' || !name.endsWith('.json')) continue
+    try {
+      docs.push(JSON.parse(data.toString('utf8')))
+    } catch {
+      // not a document
+    }
+  }
+  return docs
+}
+
 /**
  * Turn an entity-grained staleness refusal into a file-level account.
  *
@@ -793,6 +811,73 @@ export function writeItemUuids(siteDir, backend, map) {
   updateBackendMap(siteDir, backend, 'items', map)
 }
 
+/**
+ * The identity of each record's list items:
+ * `{ <record $uuid>: { <place>: "<item $uuid> <fingerprint>" } }`.
+ *
+ * ⛔ THE FOURTH MAP, FOR THE SAME REASON AS THE OTHER THREE. An item of a record's `many`
+ * section — or of a list nested in one, or of a tree's `$children` — is a `multi` row with no
+ * file and no name, so neither a path-keyed map nor the record's own file can hold it. Sent
+ * without it, the record is refused whole (`identity_required`), since applying it would
+ * replace every stored item: measured 2026-09-25 on an edit of a talk's title. Banked per
+ * record from a push's finalized documents (paired by place with what was sent) and from a
+ * pull; matched on the next send by content, then by place (`@uniweb/build`'s
+ * `record-items.js`). Each record's entry is replaced whole.
+ */
+export function readRecordItemUuids(siteDir, backend) {
+  return readBackendState(siteDir, backend).recordItems || {}
+}
+export function writeRecordItemUuids(siteDir, backend, map) {
+  if (!map || !Object.keys(map).length) return
+  updateBackendMap(siteDir, backend, 'recordItems', map)
+}
+
+// The records' list items, banked from the documents the backend returned for them —
+// `returned` by `$uuid` — paired by place with the lists as sent, which ride on each record's
+// index entry (`lists`). A record keeps an entry only while it has list items, or had one.
+function bankRecordItems(siteDir, backend, pairs) {
+  const prior = readRecordItemUuids(siteDir, backend)
+  const bank = {}
+  for (const { uuid, lists, returned } of pairs) {
+    if (!uuid || !lists || !returned) continue
+    const items = harvestRecordItems(lists, returned)
+    if (Object.keys(items).length || prior[uuid]) bank[uuid] = items
+  }
+  writeRecordItemUuids(siteDir, backend, bank)
+  return Object.keys(bank).length
+}
+
+/**
+ * Recover the list-item identity of records the backend holds and this copy never banked —
+ * `uuids`, the emit's `recordItemIdentity.unbanked` — from the backend's own documents: one read
+ * of the folder lane, and nothing written but `sync.json`. The send that follows matches their
+ * items by place alone (`storedRecordItems`): what was sent before is unknown here.
+ *
+ * Best-effort, like `ensureItemUuids`: a failure leaves them unbanked, and the backend refuses
+ * the send rather than replace their items.
+ *
+ * @returns {Promise<number>} how many records were recovered
+ */
+export async function recoverRecordItemUuids({ client, siteDir, uuids, note }) {
+  const siteUuid = readBackendState(siteDir, client.origin).site?.uuid || null
+  if (!siteUuid || !uuids?.length) return 0
+  try {
+    const res = await client.pullFolder(siteUuid)
+    if (!res?.ok) return 0
+    const wanted = new Set(uuids)
+    const bank = {}
+    for (const doc of entityDocsFromUwx(Buffer.from(await res.arrayBuffer()))) {
+      if (wanted.has(doc?.$uuid)) bank[doc.$uuid] = storedRecordItems(doc)
+    }
+    writeRecordItemUuids(siteDir, client.origin, bank)
+    const n = Object.keys(bank).length
+    if (n) note?.(`Recovered the identity of the list items of ${n} record(s) from the backend.`)
+    return n
+  } catch {
+    return 0
+  }
+}
+
 /**
  * The workspace this site was created in on `backend` — its owner, as the create
  * answered it — in the header's form: `@handle`, a unit's bare uuid when that unit has
@@ -1186,12 +1271,9 @@ export async function probeUnpushed(siteDir, { backend = null, sendAll = false }
   // ⚠️ Until 2026-09-23 this said the site's recorded ORG resolves it and must be
   // passed in — true before 2026-09-22, and read as a reason to pass it.
   const pkg = await comparisonEmit(siteDir, { backend, priorHashes, sendAll })
-  // A record held back for a reference (`pushInPasses`) is not in either lane, and is
-  // still unpushed.
   const changed =
     (pkg.siteContent?.entityCount || 0) +
-    (pkg.records?.entityCount || 0) +
-    (pkg.waiting || []).filter((w) => w.held).length
+    (pkg.records?.entityCount || 0)
   return { changed, unchanged: pkg.skipped || 0, warnings: pkg.warnings || [] }
 }
 
@@ -1222,7 +1304,7 @@ export async function probeUnpushed(siteDir, { backend = null, sendAll = false }
  */
 async function comparisonEmit(
   siteDir,
-  { backend = null, priorHashes = {}, sendAll = false } = {}
+  { backend = null, priorHashes = {}, sendAll = false, declarations = null } = {}
 ) {
   const applied = readAppliedInjections(siteDir, backend)
   // ⛔ Per backend: an asset id is minted by one and means nothing to another, so a
@@ -1232,7 +1314,13 @@ async function comparisonEmit(
   const queryUuids = readQueryUuids(siteDir, backend)
   return emitSyncPackages(siteDir, {
     backend,
-    resolveModel: makeModelResolver({ client: null, offline: true }),
+    // Offline, always. A caller that has just read the Models from the backend — a pull —
+    // may hand them in: the declarations a push would resolve, so the hashes still compare.
+    // Without them a site whose foundation is not in the project (a clone's) resolves none
+    // of its Models here, and nothing is banked.
+    resolveModel: declarations
+      ? async (name) => declarations.get(name) ?? null
+      : makeModelResolver({ client: null, offline: true }),
     priorHashes,
     sendAll,
     ...applied,
@@ -1263,13 +1351,69 @@ async function comparisonEmit(
  * ⭐ Re-banking is the correct answer rather than clearing, because after a pull the
  * on-disk state IS the agreed state: it came from the backend. A push with no edits
  * in between should send nothing, and clearing would make it send everything.
+ *
+ * @param {object} [opts]
+ * @param {object[]} [opts.recordDocs] - the record documents the pull took; their list items'
+ *        identity is banked against the files just written (`readRecordItemUuids`)
+ * @param {Map<string,object>} [opts.declarations] - the Models the pull read, by name — so a
+ *        site whose foundation is not in the project (a clone's) can be re-banked offline
  */
-export async function rebankSyncHashes(siteDir, backend = null) {
-  const pkg = await comparisonEmit(siteDir, { backend, sendAll: true })
+export async function rebankSyncHashes(siteDir, backend = null, { recordDocs, declarations } = {}) {
+  const pkg = await comparisonEmit(siteDir, { backend, sendAll: true, declarations })
   writeSyncCache(siteDir, backend, pkg.hashes || {}, pkg.applied || {})
+  // ⭐ And the identity of the records' list items, from the documents the pull just took:
+  // the files it wrote hold the stored items in stored order, so the emit over them pairs
+  // with each document item for item.
+  if (recordDocs?.length) {
+    const byUuid = new Map(recordDocs.filter((d) => d?.$uuid).map((d) => [d.$uuid, d]))
+    const recordUuids = readBackendState(siteDir, backend).records || {}
+    bankRecordItems(
+      siteDir,
+      backend,
+      (pkg.records?.index || []).map((entry) => {
+        const uuid = entry.ownId ? recordUuids[entry.ownId] : null
+        return { uuid, lists: entry.lists, returned: uuid ? byUuid.get(uuid) : null }
+      })
+    )
+  }
   return Object.keys(pkg.hashes || {}).length
 }
 
+/**
+ * Re-bank the hashes of the records a push sent naming a record it created — `keys`,
+ * the emit's `namesNew` — as the next push will hash them, and fingerprint their list
+ * items the same way.
+ *
+ * ⭐ Such a record names its new record by `$ref`, and the backend stores the uuid it
+ * mints. The next push names it by that uuid: the same reference, and another hash — so
+ * the hash the push banked describes a document no later emit builds, and the next push
+ * would send every one of these records again. Re-sending is not harmless: a record's
+ * list-section items go without the identity a re-send needs (`identity_required`).
+ *
+ * ⚖️ Only these keys, over the hashes the push just banked: the site-content lane and
+ * the folder are banked as that push sent them, and a caller's own emit options (a
+ * publish that does not declare services) are not the comparison emit's.
+ */
+export async function rebankRecordHashes(siteDir, backend, keys) {
+  if (!keys?.length) return
+  const pkg = await comparisonEmit(siteDir, { backend, sendAll: true })
+  const hashes = { ...readSyncCache(siteDir, backend) }
+  for (const key of keys) if (pkg.hashes?.[key]) hashes[key] = pkg.hashes[key]
+  writeSyncCache(siteDir, backend, hashes, readAppliedInjections(siteDir, backend))
+  // Their list items too: an item that named a new record is fingerprinted anew, each uuid kept
+  // at its place (`reprintRecordItems`) — or the next send finds it by place alone.
+  const wanted = new Set(keys)
+  const recordUuids = readBackendState(siteDir, backend).records || {}
+  const bank = readRecordItemUuids(siteDir, backend)
+  const reprinted = {}
+  for (const entry of pkg.records?.index || []) {
+    if (!wanted.has(`${entry.model} ${entry.id}`)) continue
+    const uuid = entry.ownId ? recordUuids[entry.ownId] : null
+    if (uuid && bank[uuid]) reprinted[uuid] = reprintRecordItems(bank[uuid], entry.lists)
+  }
+  writeRecordItemUuids(siteDir, backend, reprinted)
+}
+
 /**
  * What a push did with the site's `template:` intent — read from the backend's own
  * reply, never inferred from what we sent.
@@ -1747,6 +1891,18 @@ export async function pushSyncPackages({
     }
     for (const w of bf.warnings) note(`! ${w}`)
     for (const d of bf.deferred) note(`↷ ${d.id ?? `#${d.index}`}: ${d.reason}`)
+    // ⭐ BANK THE RECORDS' LIST ITEMS: each item's `$uuid` in the document the backend returned,
+    // paired by place with the lists as sent — so the next send of a record updates its items
+    // rather than being refused for replacing them (`readRecordItemUuids`).
+    bankRecordItems(
+      siteDir,
+      client.origin,
+      finalized.map((f) => ({
+        uuid: f?.uuid,
+        lists: Number.isInteger(f?.index) ? records.index?.[f.index]?.lists : null,
+        returned: f?.document
+      }))
+    )
     draftsNotKept = bf.notKeptAsDrafts || []
     if (bf.updated.length)
       wrote.push(`wrote ${bf.updated.length} record file(s)`)
@@ -1774,6 +1930,15 @@ export async function pushSyncPackages({
   // Entities absent from finalized[] (skipped, or not editable) keep their cached
   // value — absence is not invalidation.
   writeSyncCache(siteDir, client.origin, hashes, applied)
+  // A record that named a record this push created is banked as the next push will send
+  // it — by that record's uuid, which the back-fill above just recorded.
+  if (records && pkg.namesNew?.length) {
+    try {
+      await rebankRecordHashes(siteDir, client.origin, pkg.namesNew)
+    } catch (err) {
+      note(`! Could not re-bank ${pkg.namesNew.length} record(s) that name a new record: ${err.message}. The next push sends them again.`)
+    }
+  }
   mergeHarvested()
   // Re-base the page attribution: our emitted document and the backend's post-write
   // copy of it are the two sides' new agreed state. Only when the site-content lane
@@ -1850,78 +2015,3 @@ export async function pushSyncPackages({
   }
   return { exitCode: 0, boundSiteUuid, finalizedTotal, wrote }
 }
-
-/**
- * Push, then push again while records WAIT for a reference's record — the verbs' way to
- * send a package (`push`, `publish`).
- *
- * ⭐ A reference is sent as the uuid the backend minted for the record it names, so a
- * record that points at one created by the same push cannot be completed in that push
- * (`@uniweb/build`'s `emitSyncPackages` → `waiting`). The first pass creates what it can —
- * records whose waiting references are not required go without them — and each further
- * pass, emitted afresh from the state the last one banked, sends what has become
- * nameable. A chain of required references takes one pass per link; two records that
- * each require the other can never be completed, and the push stops, naming them.
- *
- * @param {object} params
- * @param {object} params.pkg - the first pass's package (`emitSyncPackages`)
- * @param {() => Promise<object>} params.reemit - the next pass's package, emitted afresh
- * @param {Function} [params.push] - sends one package; `pushSyncPackages` (a test's seam)
- * @returns {Promise<{ exitCode: number, boundSiteUuid?: string, finalizedTotal: number, wrote: string[], passes: number }>}
- */
-export async function pushInPasses({ client, siteDir, pkg, report, reemit, maxPasses = 12, push = pushSyncPackages }) {
-  const { note, error } = report
-  let current = pkg
-  let passes = 1
-  let result = await push({ client, siteDir, pkg: current, report })
-  let finalizedTotal = result.finalizedTotal || 0
-  const wrote = [...(result.wrote || [])]
-  while (result.exitCode === 0 && current.waiting?.length) {
-    const n = current.waiting.length
-    note(
-      `${n} record${n === 1 ? '' : 's'} name${n === 1 ? 's' : ''} a record this push created — ` +
-        `pushing again to complete ${n === 1 ? 'its references' : 'their references'}.`
-    )
-    let next
-    try {
-      next = await reemit()
-    } catch (err) {
-      error(`Could not build the next pass: ${err.message}`)
-      return { ...result, exitCode: 1, finalizedTotal, wrote, passes }
-    }
-    if (refuseUnsendableRecords(next.refusals, report)) {
-      return { ...result, exitCode: 1, finalizedTotal, wrote, passes }
-    }
-    // Nothing became nameable: every record still waiting waits on one that waits too.
-    if (waitingKey(next.waiting) === waitingKey(current.waiting) || passes >= maxPasses) {
-      error(
-        'These records could not be completed — each requires a reference to a record that ' +
-          'is itself waiting to be created:'
-      )
-      for (const w of next.waiting || []) {
-        const refs = w.pending.map((p) => `${p.path} → "${p.name}"`).join(', ')
-        note(`  ${w.id} (${w.model}): ${refs}`)
-      }
-      note(
-        'Push one of them without that reference first — or make it optional in the schema — ' +
-          'then add it back and push again.'
-      )
-      return { ...result, exitCode: 1, finalizedTotal, wrote, passes }
-    }
-    current = next
-    passes++
-    result = await push({ client, siteDir, pkg: current, report })
-    finalizedTotal += result.finalizedTotal || 0
-    for (const w of result.wrote || []) if (!wrote.includes(w)) wrote.push(w)
-  }
-  return { ...result, finalizedTotal, wrote, passes }
-}
-
-// Which records wait, and on what — two passes that leave it the same made no progress.
-function waitingKey(waiting) {
-  return JSON.stringify(
-    (waiting || [])
-      .map((w) => [w.model, w.id, w.pending.map((p) => `${p.path}:${p.name}`).sort()])
-      .sort()
-  )
-}

package/src/commands/publish.js

@@ -86,12 +86,13 @@ import {
   readItemBaseVersions,
   ensureItemUuids,
   readFolderItemUuids,
+  readRecordItemUuids,
+  recoverRecordItemUuids,
   ensureSiteExists,
   refuseUnsendableRecords,
   clearRemoteSyncStateIfUnbound,
   dropSiteBoundValues,
-  readItemUuids,
-  pushInPasses
+  pushSyncPackages
 } from '../backend/site-sync.js'
 import { resolveWorkspace, describeWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
 import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
@@ -943,36 +944,45 @@ export async function publish(args = []) {
     say.dim('Services unchanged.')
   }
 
-  // The emit's options, read afresh for each pass (`pushInPasses`): a pass banks
-  // hashes, identity and base versions that the next one must build on.
-  //
   // publish rides the same gated push as `uniweb push`: if an app author has
   // edited since this clone last synced, the push is refused rather than
   // overwriting them, and nothing goes live. `--force` drops the precondition.
   const forced = args.includes('--force')
-  const emitOptions = ({ priorHashes, itemUuids }) => ({
-      backend: client.origin,
-      ...(declaration.declare ? {} : { declareServices: false }),
-      // Placement identity for the folder — see writeFolderItemUuids.
-      folderItemUuids: readFolderItemUuids(siteDir, client.origin),
-      ...(foundationDir ? { foundationDir } : {}),
-      resolveModel,
-      priorHashes,
-      itemUuids,
-      ...(forced
-        ? {}
-        : {
-            baseVersions: readBaseVersions(siteDir, client.origin),
-            itemBaseVersions: readItemBaseVersions(siteDir, client.origin)
-          }),
-      ...(Object.keys(injectInfo).length ? { injectInfo } : {}),
-      ...(Object.keys(ext.pins).length ? { injectExtensions: ext.pins } : {}),
-      ...(assetRewrite ? { assetRewrite } : {}),
-      ...(assetIds ? { assetIds } : {})
-  })
+  const emitOptions = {
+    backend: client.origin,
+    ...(declaration.declare ? {} : { declareServices: false }),
+    // Placement identity for the folder — see writeFolderItemUuids.
+    folderItemUuids: readFolderItemUuids(siteDir, client.origin),
+    // Identity for the records' list items — see readRecordItemUuids.
+    recordItemUuids: readRecordItemUuids(siteDir, client.origin),
+    ...(foundationDir ? { foundationDir } : {}),
+    resolveModel,
+    priorHashes,
+    itemUuids,
+    ...(forced
+      ? {}
+      : {
+          baseVersions: readBaseVersions(siteDir, client.origin),
+          itemBaseVersions: readItemBaseVersions(siteDir, client.origin)
+        }),
+    ...(Object.keys(injectInfo).length ? { injectInfo } : {}),
+    ...(Object.keys(ext.pins).length ? { injectExtensions: ext.pins } : {}),
+    ...(assetRewrite ? { assetRewrite } : {}),
+    ...(assetIds ? { assetIds } : {})
+  }
   let pkg
   try {
-    pkg = await emitSyncPackages(siteDir, emitOptions({ priorHashes, itemUuids }))
+    pkg = await emitSyncPackages(siteDir, emitOptions)
+    // Records the backend holds whose list items this copy never banked — see `uniweb push`.
+    const unbanked = pkg.recordItemIdentity?.unbanked
+    if (unbanked?.length) {
+      if (await recoverRecordItemUuids({ client, siteDir, uuids: unbanked, note: (m) => say.dim(m) })) {
+        pkg = await emitSyncPackages(siteDir, {
+          ...emitOptions,
+          recordItemUuids: readRecordItemUuids(siteDir, client.origin)
+        })
+      }
+    }
   } catch (err) {
     say.err(`Could not build the sync package: ${err.message}`)
     return { exitCode: 1 }
@@ -987,19 +997,11 @@ export async function publish(args = []) {
     error: (m) => say.err(m),
     dim: (s) => `${c.dim}${s}${c.reset}`
   }
-  const pushResult = await pushInPasses({
+  const pushResult = await pushSyncPackages({
     client,
     siteDir,
     pkg,
-    report,
-    reemit: () =>
-      emitSyncPackages(
-        siteDir,
-        emitOptions({
-          priorHashes: readSyncCache(siteDir, client.origin),
-          itemUuids: readItemUuids(siteDir, client.origin)
-        })
-      )
+    report
   })
   if (pushResult.exitCode !== 0) return { exitCode: pushResult.exitCode }
   const siteUuid = pushResult.boundSiteUuid

package/src/commands/pull.js

@@ -77,6 +77,7 @@ import {
   computeUnitHashes,
   collectUnitUuids,
   collectQueryUuids,
+  collectFolderItemUuids,
   documentSchema
 } from '@uniweb/build/uwx'
 import {
@@ -91,7 +92,8 @@ import {
   mergeBaseVersions,
   mergeItemBaseVersions,
   writeUnitBases,
-  writeItemUuids
+  writeItemUuids,
+  writeFolderItemUuids
 } from '../backend/site-sync.js'
 import { resolveWorkspace } from '../backend/workspace.js'
 import {
@@ -849,6 +851,9 @@ export async function pull(args = [], deps = {}) {
     client.pullSiteContent(siteContentUuid, { etag: conditional ? etagContent : undefined })
   )
   if (content?.refused) return { exitCode: 1 }
+  // The Models the pulled site's queries name, as the push qualified them — the re-bank
+  // below resolves with them too (see there).
+  let pulledQueryModels = []
   if (content && !content.notModified) {
     const siteDoc =
       content.docs &&
@@ -856,6 +861,9 @@ export async function pull(args = [], deps = {}) {
         content.docs[0] ||
         null)
     if (siteDoc) {
+      pulledQueryModels = (Array.isArray(siteDoc.queries) ? siteDoc.queries : [])
+        .map((q) => q?.schema)
+        .filter((s) => typeof s === 'string' && /^@[^/]+\//.test(s))
       // Re-base the page attribution. The pulled document IS the backend's own
       // representation, so it becomes the remote base directly. We deliberately
       // CLEAR the local base rather than reuse it: our source files were just
@@ -962,6 +970,12 @@ export async function pull(args = [], deps = {}) {
   // holds a folder uuid). Models are resolved by name (async) up front, so
   // recordsToProject keeps its synchronous contract. A 304 leaves files as-is.
   let folderLane = null
+  // The record documents this pull took — the re-bank below pairs their list items with the
+  // files just written.
+  let pulledRecordDocs = []
+  // The Models this pull read from the backend, by name — the re-bank below resolves with
+  // them, since a clone's foundation is not in the project to resolve them offline.
+  let pulledDeclarations = null
   if (!noRecords) {
     const folder = await getDocs('records', () =>
       client.pullFolder(siteContentUuid, { etag: conditional ? etagFolder : undefined })
@@ -970,8 +984,10 @@ export async function pull(args = [], deps = {}) {
     if (folder?.refused) return { exitCode: 1 }
     if (folder && !folder.notModified && folder.docs?.length) {
       const { folderDoc, recordDocs } = splitRecordsPull(folder.docs)
+      pulledRecordDocs = recordDocs
       const resolveModel = makeModelResolver({ client })
       const declByModel = new Map()
+      pulledDeclarations = declByModel
       for (const model of [
         ...new Set(recordDocs.map((d) => documentSchema(d)).filter(Boolean))
       ]) {
@@ -998,6 +1014,12 @@ export async function pull(args = [], deps = {}) {
           scope: await scopeFor(null)
         }
       })
+      // ⭐ THE FOLDER'S PLACEMENT IDENTITY, from the folder this pull took — as a push banks
+      // it from the folder it sent. ⛔ Only a push banked it until 2026-09-25, so a copy that
+      // had never pushed (every clone) sent its first folder with its placements uuid-less,
+      // and the backend refused that push (`identity_required`, section `contents`) —
+      // measured on a template clone's first edit.
+      if (folderDoc) writeFolderItemUuids(siteDir, client.origin, collectFolderItemUuids(folderDoc))
       // The folder's organization, `folder.yml` in the records directory — named as
       // the author would write it (`records/folder.yml`, or under `paths.records`).
       if (report.records === 'updated') {
@@ -1069,9 +1091,30 @@ export async function pull(args = [], deps = {}) {
   //
   // Best-effort: a failure here costs an unnecessary re-send on the next push, never
   // wrong content, and must not fail a pull whose files are already written.
-  if (!dryRun) {
+  // Nothing projected — both lanes unchanged (304) — leaves the banked state describing the
+  // files as they are, so there is nothing to re-bank. Re-banking anyway only failed, noisily,
+  // where the Models cannot be resolved offline (a clone's).
+  const projected = Boolean(content && !content.notModified) || Boolean(folderLane && !folderLane.notModified)
+  if (!dryRun && projected) {
     try {
-      await rebankSyncHashes(siteDir, client.origin)
+      // ⭐ With the Models this pull read, and those its queries name — a query may name a
+      // schema no record uses yet. The re-bank is offline, and a site whose foundation is not
+      // in the project (a clone's) resolves none of them otherwise: every template clone
+      // said "could not re-bank" until 2026-09-25, and banked nothing.
+      const declarations = pulledDeclarations || new Map()
+      const readModel = makeModelResolver({ client })
+      for (const model of pulledQueryModels) {
+        if (declarations.has(model)) continue
+        try {
+          declarations.set(model, await readModel(model))
+        } catch {
+          // Unreadable here: the re-bank says so if it needs it.
+        }
+      }
+      await rebankSyncHashes(siteDir, client.origin, {
+        recordDocs: pulledRecordDocs,
+        ...(declarations.size ? { declarations } : {})
+      })
     } catch (err) {
       note(`! could not re-bank the sync cache: ${err.message}`)
       note('  The next push will re-send content that is already current.')

package/src/commands/push.js

@@ -82,12 +82,14 @@ import {
   readItemUuids,
   readFolderItemUuids,
   readQueryUuids,
+  readRecordItemUuids,
+  recoverRecordItemUuids,
   ensureItemUuids,
   refuseUnsendableRecords,
   ensureSiteExists,
   clearRemoteSyncStateIfUnbound,
   dropSiteBoundValues,
-  pushInPasses
+  pushSyncPackages
 } from '../backend/site-sync.js'
 import { resolveWorkspace, describeWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
 
@@ -496,43 +498,55 @@ export async function push(args = [], deps = {}) {
     output || dryRun
       ? readItemUuids(siteDir, client.origin)
       : await ensureItemUuids({ client, siteDir, note })
-  // The emit's options, read afresh for each pass (`pushInPasses`): a pass banks
-  // hashes, identity and base versions that the next one must build on.
-  const emitOptions = ({ priorHashes, sendAll, itemUuids }) => ({
-      backend: client.origin,
-      // Placement identity for the folder — see writeFolderItemUuids.
-      folderItemUuids: readFolderItemUuids(siteDir, client.origin),
-      // Identity for the `queries` section — see readQueryUuids. Keyed by
-      // name, because a declaration has no file for a path-keyed map to hold.
-      queryUuids: readQueryUuids(siteDir, client.origin),
-      ...(foundationDir ? { foundationDir } : {}),
-      resolveModel: makeModelResolver({
-        client,
-        offline: Boolean(output) || dryRun
-      }),
-      priorHashes,
-      sendAll,
-      itemUuids,
-      // The PINNED foundation ref from the bring-along above, stamped over the
-      // authored `site.yml` string. Delivery is version-pinned end to end, so an
-      // unpinned local name on the wire names code no host can serve. Absent when
-      // the site already references a registry ref or URL — then site.yml's own
-      // value rides verbatim.
-      ...(fnd.ref ? { injectInfo: { foundation: fnd.ref } } : {}),
-      // Both grains are dropped together by --force: one flag, one meaning,
-      // no partial-force mode.
-      ...(force
-        ? {}
-        : {
-            baseVersions: readBaseVersions(siteDir, client.origin),
-            itemBaseVersions: readItemBaseVersions(siteDir, client.origin)
-          }),
-      ...(assetRewrite ? { assetRewrite } : {}),
-      ...(assetIds ? { assetIds } : {})
-  })
+  const emitOptions = {
+    backend: client.origin,
+    // Placement identity for the folder — see writeFolderItemUuids.
+    folderItemUuids: readFolderItemUuids(siteDir, client.origin),
+    // Identity for the `queries` section — see readQueryUuids. Keyed by
+    // name, because a declaration has no file for a path-keyed map to hold.
+    queryUuids: readQueryUuids(siteDir, client.origin),
+    // Identity for the records' list items — see readRecordItemUuids.
+    recordItemUuids: readRecordItemUuids(siteDir, client.origin),
+    ...(foundationDir ? { foundationDir } : {}),
+    resolveModel: makeModelResolver({
+      client,
+      offline: Boolean(output) || dryRun
+    }),
+    priorHashes,
+    sendAll,
+    itemUuids,
+    // The PINNED foundation ref from the bring-along above, stamped over the
+    // authored `site.yml` string. Delivery is version-pinned end to end, so an
+    // unpinned local name on the wire names code no host can serve. Absent when
+    // the site already references a registry ref or URL — then site.yml's own
+    // value rides verbatim.
+    ...(fnd.ref ? { injectInfo: { foundation: fnd.ref } } : {}),
+    // Both grains are dropped together by --force: one flag, one meaning,
+    // no partial-force mode.
+    ...(force
+      ? {}
+      : {
+          baseVersions: readBaseVersions(siteDir, client.origin),
+          itemBaseVersions: readItemBaseVersions(siteDir, client.origin)
+        }),
+    ...(assetRewrite ? { assetRewrite } : {}),
+    ...(assetIds ? { assetIds } : {})
+  }
   let pkg
   try {
-    pkg = await emitSyncPackages(siteDir, emitOptions({ priorHashes, sendAll, itemUuids }))
+    pkg = await emitSyncPackages(siteDir, emitOptions)
+    // A record the backend holds whose list items this copy never banked — pushed before the
+    // bank existed, say — is refused if sent without them. Recover them from the backend, and
+    // build the package again with them.
+    const unbanked = pkg.recordItemIdentity?.unbanked
+    if (unbanked?.length && !output && !dryRun) {
+      if (await recoverRecordItemUuids({ client, siteDir, uuids: unbanked, note })) {
+        pkg = await emitSyncPackages(siteDir, {
+          ...emitOptions,
+          recordItemUuids: readRecordItemUuids(siteDir, client.origin)
+        })
+      }
+    }
   } catch (err) {
     error(`Could not build the sync package: ${err.message}`)
     return { exitCode: 2 }
@@ -598,9 +612,8 @@ export async function push(args = [], deps = {}) {
   }
 
   // Submit both lanes, back-fill the minted uuids, and persist the send-only-changed
-  // cache — again for any record whose reference names a record this push created.
-  // Shared with `uniweb publish` via ../backend/site-sync.js.
-  const result = await pushInPasses({
+  // cache. Shared with `uniweb publish` via ../backend/site-sync.js.
+  const result = await pushSyncPackages({
     client,
     siteDir,
     pkg,
@@ -609,16 +622,7 @@ export async function push(args = [], deps = {}) {
       note,
       error,
       dim: (s) => `${colors.dim}${s}${colors.reset}`
-    },
-    reemit: () =>
-      emitSyncPackages(
-        siteDir,
-        emitOptions({
-          priorHashes: readSyncCache(siteDir, client.origin),
-          sendAll: false,
-          itemUuids: readItemUuids(siteDir, client.origin)
-        })
-      )
+    }
   })
   if (result.exitCode !== 0) return { exitCode: result.exitCode }
   success(

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-24T21:52:18.260Z",
+  "generatedAt": "2026-09-25T13:32:50.848Z",
   "packages": {
     "@uniweb/api": {
       "version": "0.6.2",
@@ -10,7 +10,7 @@
       ]
     },
     "@uniweb/build": {
-      "version": "0.62.0",
+      "version": "0.63.1",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -116,7 +116,7 @@
       "deps": []
     },
     "@uniweb/templates": {
-      "version": "0.17.0",
+      "version": "0.17.1",
       "path": "framework/templates",
       "deps": []
     },
@@ -126,7 +126,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.10.5",
+      "version": "0.10.6",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",