uniweb 0.33.0 → 0.33.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.33.0",
+  "version": "0.33.1",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,13 +41,13 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/runtime": "^0.13.1",
-    "@uniweb/semantic-parser": "^1.3.1",
     "@uniweb/core": "^0.13.1",
-    "@uniweb/kit": "^0.14.0"
+    "@uniweb/kit": "^0.14.0",
+    "@uniweb/semantic-parser": "^1.3.1",
+    "@uniweb/runtime": "^0.13.1"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.29.0",
+    "@uniweb/build": "^0.29.1",
     "@uniweb/content-reader": "^1.2.4",
     "@uniweb/semantic-parser": "^1.3.1"
   },

package/src/backend/site-sync.js

@@ -27,6 +27,7 @@ import {
   computeUnitHashes,
   collectUnitUuids,
   collectFolderItemUuids,
+  collectCollectionUuids,
   readAssetMap
 } from '@uniweb/build/uwx'
 
@@ -241,6 +242,7 @@ export function clearRemoteSyncState(siteDir, siteUuid = null) {
   const prior = readSyncCacheFile(siteDir)
   const dropped = [
     'itemUuids',
+    'collectionUuids',
     'hashes',
     'baseVersions',
     'unitBases',
@@ -248,6 +250,9 @@ export function clearRemoteSyncState(siteDir, siteUuid = null) {
   ].filter((k) => prior[k] && Object.keys(prior[k]).length)
   updateSyncCache(siteDir, {
     itemUuids: {},
+    // Remote-derived exactly like itemUuids — it holds the OLD site's collection
+    // ids, and surviving the drop it would offer them for the new site's sections.
+    collectionUuids: {},
     hashes: {},
     baseVersions: {},
     unitBases: {},
@@ -468,6 +473,32 @@ export function readItemUuids(siteDir) {
 export function readFolderItemUuids(siteDir) {
   return readMap(siteDir, 'folderItemUuids')
 }
+
+/**
+ * Collection-declaration identity: `{ <collection name>: <backend $uuid> }`.
+ *
+ * ⛔ THE THIRD MAP, AND EACH ONE EXISTS FOR THE SAME REASON. `itemUuids` is keyed by
+ * the file an item projects to. Two kinds of item have no file of their own — a
+ * folder's placements, and a collection DECLARATION (they all live in one
+ * `collections/collections.yml`) — so a path-keyed map has no shape either could
+ * occupy, and a push re-sends that whole section uuid-less.
+ *
+ * The backend refuses an all-blank section over stored items rather than applying it,
+ * because applying it would insert every record fresh and delete every stored row —
+ * content survives, identity does not. So `push` worked once and every push after was
+ * refused. Measured 2026-08-29; collab framework-backend-812b.
+ *
+ * ⭐ Keyed by NAME, which the backend enforces unique within the section and uses as
+ * its own join key. ⛔ Not `$id`: it holds the same string but is a payload-local
+ * handle the backend skips on parse and never stores.
+ */
+export function readCollectionUuids(siteDir) {
+  return readMap(siteDir, 'collectionUuids')
+}
+export function writeCollectionUuids(siteDir, map) {
+  if (!map || !Object.keys(map).length) return
+  updateSyncCache(siteDir, { collectionUuids: map })
+}
 export function writeFolderItemUuids(siteDir, map) {
   if (!map || !Object.keys(map).length) return
   updateSyncCache(siteDir, { folderItemUuids: map })
@@ -948,20 +979,72 @@ export async function probeUnpushed(siteDir, { sendAll = false } = {}) {
   // and others never settling, which reads like a content problem rather than a
   // resolution one. Measured on matinee 2026-08-29: `status` reported 4 changed
   // immediately after a successful push; passing the org took it to 1.
+  const pkg = await comparisonEmit(siteDir, { priorHashes, sendAll })
+  const changed =
+    (pkg.siteContent?.entityCount || 0) + (pkg.collections?.entityCount || 0)
+  return { changed, unchanged: pkg.skipped || 0, warnings: pkg.warnings || [] }
+}
+
+/**
+ * The emit whose hashes are comparable with the banked ones — ONE definition.
+ *
+ * ⛔ EVERY DEFECT IN THIS AREA HAS BEEN A WRITER AND A READER DISAGREEING ABOUT
+ * WHICH DOCUMENT A HASH DESCRIBES, so the option set that makes them agree must
+ * have a single home. Assembled from three sources, each for a stated reason:
+ *
+ *   · BANKED     the injections the push applied before hashing — serve URLs and
+ *                the pinned foundation ref, which only a round trip produces.
+ *   · RE-DERIVED asset identity, from the COMMITTED `assets.json`, so a moved map
+ *                reads as changed rather than matching a copy of itself.
+ *   · RECORDED   the site's org, which resolves a foundation-relative `@/x` into
+ *                the `@org/x` the push keyed its hashes by, and the collection
+ *                identity a push stamps — so `status` hashes the same document a
+ *                push would send rather than one missing a section's `$uuid`s.
+ *
+ * Offline by design — measured at zero HTTP requests, a property the cross-client
+ * flows rely on.
+ */
+async function comparisonEmit(siteDir, { priorHashes = {}, sendAll = false } = {}) {
   const applied = readAppliedInjections(siteDir)
   const assetIds = readAssetMap(siteDir)
   const org = readSiteOrg(siteDir)
-  const pkg = await emitSyncPackages(siteDir, {
+  const collectionUuids = readCollectionUuids(siteDir)
+  return emitSyncPackages(siteDir, {
     resolveModel: makeModelResolver({ client: null, offline: true }),
     priorHashes,
     sendAll,
     ...applied,
+    ...(Object.keys(collectionUuids).length ? { collectionUuids } : {}),
     ...(Object.keys(assetIds).length ? { assetIds } : {}),
     ...(org ? { org } : {})
   })
-  const changed =
-    (pkg.siteContent?.entityCount || 0) + (pkg.collections?.entityCount || 0)
-  return { changed, unchanged: pkg.skipped || 0, warnings: pkg.warnings || [] }
+}
+
+/**
+ * Re-bank the send-only-changed hashes over the files as they NOW stand.
+ *
+ * ⛔ FOR A WRITER THAT REWRITES THE WORKING TREE — today, `uniweb pull`.
+ *
+ * A pull projects the backend's document into source files, and that projection is
+ * canonical rather than byte-identical to what was there: it moves section ordering
+ * out of filename prefixes (`1-hero.md` → `hero.md` plus an explicit `sections:`
+ * list) and stamps each section's `id`. Lossless, and a different document.
+ *
+ * ⚠️ `pull` already knew this for the OTHER map — it clears the `local` unit base
+ * because "what we would emit from them is not byte-identical to it, so the old
+ * local base no longer describes anything". That reasoning was never carried to the
+ * hashes, which were left STALE rather than unknown: the next `uniweb status`
+ * reported the site as having unpushed content immediately after a pull, forever.
+ * Measured on matinee 2026-08-29 — `push → pull` reported 1 changed of 8.
+ *
+ * ⭐ 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.
+ */
+export async function rebankSyncHashes(siteDir) {
+  const pkg = await comparisonEmit(siteDir, { sendAll: true })
+  writeSyncCache(siteDir, pkg.hashes || {}, pkg.applied || {})
+  return Object.keys(pkg.hashes || {}).length
 }
 
 /**
@@ -1063,18 +1146,47 @@ export async function pushSyncPackages({
         return null
       }
       if (problem?.reason === 'identity_required') {
+        // ⛔ THE REFUSAL IS PER-SECTION, NOT PER-PUSH, AND WE USED TO SAY OTHERWISE.
+        //
+        // The backend asks, of each section independently: is this section's ENTIRE
+        // incoming record set uuid-less while the stored entity already has items in
+        // it? So a push can carry correct identity for most of the document and still
+        // be refused over one section it stamps none of — and the old wording ("this
+        // copy has no record of the site's item identity", "the recovery … could not
+        // reach the backend", "`uniweb pull` also restores it") was wrong on all
+        // three counts in exactly that case: the copy has identity, no recovery was
+        // attempted, and a pull changes nothing.
+        //
+        // ⭐ THE BACKEND ALREADY SENDS WHAT LOCATES IT — `section_id`,
+        // `records_without_uuid`, `stored_items` — and this branch discarded every
+        // one of them, so every refusal anyone collected was missing the only fields
+        // that say WHERE. (Named by backend in collab `framework-backend-812b`,
+        // 2026-08-28: "the offending section and both counts have been in the body of
+        // every refusal you have collected".)
+        const n = problem.records_without_uuid
+        const stored = problem.stored_items
+        // `section_name` landed backend-side 2026-08-28 (`90e7cd7e`), replacing an
+        // i64 row id we could not resolve. The fallback stays for an older backend,
+        // not because the swap is pending — it is done.
+        const where = problem.section_name ?? problem.section_id
         error(
-          `${label} push refused — this copy has no record of the site's item identity.`
-        )
-        note(
-          'Nothing was written. Pushing without it would have replaced the identity of every stored item.'
-        )
-        note(
-          'The recovery normally runs automatically, so it likely could not reach the backend.'
+          `${label} push refused — one section carries no item identity` +
+            (where === undefined ? '.' : ` (section ${where}).`)
         )
+        if (Number.isInteger(n) && Number.isInteger(stored)) {
+          note(
+            `That section sent ${n} record(s), none carrying a \`$uuid\`, while ${stored} item(s) are already stored there.`
+          )
+        }
         note(
-          'Check your connection and re-run; `uniweb pull` also restores it.'
+          'Nothing was written. Applying it would have replaced the identity of every stored item in that section.'
         )
+        // ⚠️ Deliberately NOT "run `uniweb pull`". A pull re-harvests identity from
+        // the backend's own document, so it fixes a LOST cache — and does nothing at
+        // all when the cache is intact and one section simply has no entry in it,
+        // which is the case this message now names. Suggesting it there sends the
+        // user to re-fetch a map they already have.
+        if (problem.detail) note(String(problem.detail))
         return null
       }
       if (problem?.reason === 'stale_base') {
@@ -1264,6 +1376,16 @@ export async function pushSyncPackages({
       }
       harvest(finalized)
       siteFinalizedDoc = finalized[0]?.document || null
+      // ⭐ BANK COLLECTION-DECLARATION IDENTITY, the sibling of the folder's
+      // placements below. These items have no file to back-fill into — they all
+      // come from one `collections/collections.yml` — so the only place their
+      // `$uuid` can live is the cache, keyed by the name the backend enforces
+      // unique. Without it every push after the first re-sends the whole
+      // `collections` section uuid-less and is refused.
+      if (siteFinalizedDoc) {
+        const collectionIds = collectCollectionUuids(siteFinalizedDoc)
+        if (Object.keys(collectionIds).length) writeCollectionUuids(siteDir, collectionIds)
+      }
       finalizedTotal += finalized.length
     } else {
       const payload = await postLane('site-content', () =>

package/src/commands/pull.js

@@ -75,7 +75,8 @@ import {
   resolveCollectionsConfig,
   readZip,
   computeUnitHashes,
-  collectUnitUuids
+  collectUnitUuids,
+  collectCollectionUuids
 } from '@uniweb/build/uwx'
 import {
   readWritten,
@@ -84,6 +85,8 @@ import {
 } from '../utils/pull-written.js'
 import {
   makeModelResolver,
+  rebankSyncHashes,
+  writeCollectionUuids,
   mergeBaseVersions,
   mergeItemBaseVersions,
   writeUnitBases,
@@ -686,6 +689,10 @@ export async function pull(args = [], deps = {}) {
       // Per-item identity for the next push. Without it the backend reads our
       // records as new and re-mints every page and section row.
       writeItemUuids(siteDir, collectUnitUuids(siteDoc))
+      // The collections section's identity has no file to live in either — same
+      // reason, same remedy, keyed by name. A pull is the other route by which a
+      // copy can recover it (see readCollectionUuids).
+      writeCollectionUuids(siteDir, collectCollectionUuids(siteDoc))
       // Bring the media down BEFORE projecting: a newly-landed asset gains a map
       // entry, and the projection reads that map to put authored paths back. Run
       // after, and this pull's new assets would project as URLs and only restore
@@ -840,6 +847,33 @@ export async function pull(args = [], deps = {}) {
     removed
   )
 
+  // ⛔ RE-BANK THE SEND-ONLY-CHANGED HASHES OVER WHAT WE JUST WROTE.
+  //
+  // The projection above is canonical, not byte-identical to what was on disk: it
+  // moves section ordering out of filename prefixes (`1-hero.md` → `hero.md` plus an
+  // explicit `sections:` list) and stamps each section's `id`. Lossless, and a
+  // different document — which is exactly why the `local` unit base is cleared above.
+  //
+  // ⚠️ That same reasoning was never carried to the hashes, so they were left STALE
+  // rather than unknown, and `uniweb status` reported unpushed content immediately
+  // after a pull, permanently. Measured on matinee 2026-08-29: push → pull reported
+  // 1 changed of 8, with nothing edited in between.
+  //
+  // Re-banking rather than clearing, because after a pull the on-disk state IS the
+  // agreed state — it came from the backend, so a push with no edits should send
+  // nothing. Clearing would make it send everything.
+  //
+  // 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) {
+    try {
+      await rebankSyncHashes(siteDir)
+    } catch (err) {
+      note(`! could not re-bank the sync cache: ${err.message}`)
+      note('  The next push will re-send content that is already current.')
+    }
+  }
+
   success(
     `Pulled — ${pages} page(s), ${sections} section(s), ${records} record(s)` +
       (deleted ? `, ${deleted} deleted` : '')

package/src/commands/push.js

@@ -85,6 +85,7 @@ import {
   readItemBaseVersions,
   readItemUuids,
   readFolderItemUuids,
+  readCollectionUuids,
   ensureItemUuids,
   ensureSiteExists,
   clearRemoteSyncStateIfUnbound,
@@ -474,6 +475,9 @@ export async function push(args = [], deps = {}) {
     pkg = await emitSyncPackages(siteDir, {
       // Placement identity for the folder — see writeFolderItemUuids.
       folderItemUuids: readFolderItemUuids(siteDir),
+      // Identity for the `collections` section — see readCollectionUuids. Keyed by
+      // name, because a declaration has no file for a path-keyed map to hold.
+      collectionUuids: readCollectionUuids(siteDir),
       // Resolves a foundation-relative `@/x` model ref into `@org/x`.
       ...(asOrg ? { org: asOrg } : {}),
       ...(foundationDir ? { foundationDir } : {}),

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-28T16:19:53.330Z",
+  "generatedAt": "2026-08-28T23:49:23.885Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.29.0",
+      "version": "0.29.1",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -112,7 +112,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.8.15",
+      "version": "0.8.16",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",