uniweb 0.69.0 → 0.69.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.69.0",
+  "version": "0.69.2",
   "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/runtime": "^0.27.4",
+    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/core": "^0.29.8",
     "@uniweb/kit": "^0.19.4",
+    "@uniweb/runtime": "^0.27.4",
     "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/schemas": "^0.7.0",
-    "@uniweb/content-writer": "^0.3.4"
+    "@uniweb/schemas": "^0.7.0"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.63.0",
+    "@uniweb/build": "^0.63.2",
     "@uniweb/content-reader": "^1.2.5",
     "@uniweb/semantic-parser": "^1.4.1"
   },

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
@@ -1219,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
@@ -1229,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,
@@ -1260,16 +1351,38 @@ 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.
+ * 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
@@ -1287,6 +1400,18 @@ export async function rebankRecordHashes(siteDir, backend, keys) {
   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)
 }
 
 /**
@@ -1766,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)`)

package/src/commands/publish.js

@@ -86,6 +86,8 @@ import {
   readItemBaseVersions,
   ensureItemUuids,
   readFolderItemUuids,
+  readRecordItemUuids,
+  recoverRecordItemUuids,
   ensureSiteExists,
   refuseUnsendableRecords,
   clearRemoteSyncStateIfUnbound,
@@ -946,28 +948,41 @@ export async function publish(args = []) {
   // 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 = {
+    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, {
-      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 } : {})
-    })
+    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 }

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,6 +82,8 @@ import {
   readItemUuids,
   readFolderItemUuids,
   readQueryUuids,
+  readRecordItemUuids,
+  recoverRecordItemUuids,
   ensureItemUuids,
   refuseUnsendableRecords,
   ensureSiteExists,
@@ -496,40 +498,55 @@ export async function push(args = [], deps = {}) {
     output || dryRun
       ? readItemUuids(siteDir, client.origin)
       : await ensureItemUuids({ client, siteDir, note })
+  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, {
-      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 } : {})
-    })
+    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 }

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-25T11:51:15.075Z",
+  "generatedAt": "2026-09-25T13:50:26.904Z",
   "packages": {
     "@uniweb/api": {
       "version": "0.6.2",
@@ -10,7 +10,7 @@
       ]
     },
     "@uniweb/build": {
-      "version": "0.63.0",
+      "version": "0.63.2",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -116,7 +116,7 @@
       "deps": []
     },
     "@uniweb/templates": {
-      "version": "0.17.0",
+      "version": "0.17.2",
       "path": "framework/templates",
       "deps": []
     },