uniweb 0.65.0 → 0.67.0

package/src/commands/pull.js

@@ -28,9 +28,9 @@
  * three-way merge local work with what the backend sends, instead of choosing
  * between them. Most "conflicts" are two people editing different paragraphs of one
  * section, which merges silently; only genuine overlaps get conflict markers. The
- * common ancestor is the COMMITTED version of each file — the backend keeps no
- * per-version history and does not need to — so `--merge` requires a repo, and the
- * merge itself is `git merge-file`.
+ * common ancestor is the version the last pull wrote, found in the repo's history —
+ * the backend keeps no per-version history and does not need to — so `--merge`
+ * requires a repo, and the merge itself is `git merge-file`.
  *
  * `uniweb login && uniweb pull`. Run from a site, or a workspace with one site.
  *
@@ -76,7 +76,8 @@ import {
   readZip,
   computeUnitHashes,
   collectUnitUuids,
-  collectQueryUuids
+  collectQueryUuids,
+  documentSchema
 } from '@uniweb/build/uwx'
 import {
   readWritten,
@@ -97,6 +98,7 @@ import {
   uncommittedUnder,
   siteContentRoots,
   showAtHead,
+  findCommitted,
   mergeFile
 } from '../utils/git.js'
 import { isNonInteractive } from '../utils/interactive.js'
@@ -203,10 +205,15 @@ function readYamlUuid(filePath) {
 function pullCachePath(siteDir) {
   return join(siteDir, '.uniweb', 'pull-cache.json')
 }
+// ⛔ VERSION 2 DISOWNS EVERY ETAG A VERSION-1 PULL WROTE. Before 2026-09-23 a
+// `--merge` that kept a local file whole — every one, in the default layout (see
+// `showAt`) — still cached the ETag of content it never took. Every later pull then
+// answered 304 and the file never caught up. Ignoring those once costs one full pull.
+const PULL_CACHE_VERSION = 2
 function readPullCache(siteDir) {
   try {
     const obj = JSON.parse(readFileSync(pullCachePath(siteDir), 'utf8'))
-    return obj && typeof obj === 'object' ? obj : {}
+    return obj && typeof obj === 'object' && obj.version >= PULL_CACHE_VERSION ? obj : {}
   } catch {
     return {}
   }
@@ -216,7 +223,7 @@ function writePullCache(siteDir, { content, folder }) {
   mkdirSync(dirname(p), { recursive: true })
   writeFileSync(
     p,
-    JSON.stringify({ version: 1, content, folder }, null, 2) + '\n'
+    JSON.stringify({ version: PULL_CACHE_VERSION, content, folder }, null, 2) + '\n'
   )
 }
 
@@ -224,7 +231,10 @@ function writePullCache(siteDir, { content, folder }) {
 // document, or a `{ document }` / `{ entity }` envelope. (Adjust at live e2e.)
 export function extractDocument(payload) {
   if (!payload || typeof payload !== 'object') return null
-  if (payload.$model || payload.$id || payload.info) return payload
+  // ⛔ `$uuid` counts: every stored entity has one. Without it, a document naming no
+  // `$schema` stopped being a document at all — it vanished from the pull, which then
+  // reported "0 record(s)" and succeeded (2026-09-24, when `$model` left this test).
+  if (payload.$schema || payload.$uuid || payload.$id || payload.info) return payload
   return payload.document || payload.entity || null
 }
 
@@ -244,8 +254,59 @@ export function splitRecordsPull(payload) {
   if (!list) return { folderDoc: null, recordDocs: [] }
   const docs = list.map(extractDocument).filter(Boolean)
   return {
-    folderDoc: docs.find((d) => d.$model === FOLDER_MODEL) || null,
-    recordDocs: docs.filter((d) => d.$model !== FOLDER_MODEL)
+    folderDoc: docs.find((d) => documentSchema(d) === FOLDER_MODEL) || null,
+    recordDocs: docs.filter((d) => documentSchema(d) !== FOLDER_MODEL)
+  }
+}
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * Say why a pull did not place every record it was sent: a headline for an error
+ * and the lines under it.
+ *
+ * ⛔ A data schema named by id, or not named at all, is said first, and instead of the
+ * per-record reasons. The folder is found by its data schema's scoped name
+ * (`splitRecordsPull`) and a record is placed in `records/<schema>/` by its data
+ * schema's scoped name, so a response naming them by id — or naming none — places
+ * nothing, and every record is then skipped as "not in the folder", which hides the
+ * cause. Measured 2026-09-23: a backend answered the folder lane with ids for the
+ * folder and every record, under the key `$schema` replaced (`$model`).
+ *
+ * @param {{ docs: object[], taken: number, skipped: object[] }} lane - every document
+ *        the lane carried, how many records were written or already current, and the
+ *        projection's skips
+ * @returns {{ headline: string, lines: string[] }}
+ */
+export function describeUnplacedRecords({ docs, taken, skipped }) {
+  const none = taken === 0
+  const lead = none ? 'No record' : 'Not every record'
+  const placedBy =
+    "A record is placed in records/<schema>/ by its data schema's scoped name, so these cannot be placed."
+  const byId = [
+    ...new Set((docs || []).map((d) => documentSchema(d)).filter((m) => m && UUID_RE.test(m)))
+  ]
+  if (byId.length) {
+    return {
+      headline: `${lead} could be placed — the backend named their data schemas by id, not by scoped name.`,
+      lines: [
+        `Named by id: ${byId.slice(0, 3).join(', ')}${byId.length > 3 ? ', …' : ''}`,
+        placedBy,
+        'Your record files are unchanged.'
+      ]
+    }
+  }
+  const unnamed = (docs || []).filter((d) => !documentSchema(d)).length
+  if (unnamed) {
+    return {
+      headline: `${lead} could be placed — ${unnamed} of the backend's documents name no data schema (\`$schema\`).`,
+      lines: [placedBy, 'Your record files are unchanged.']
+    }
+  }
+  const n = skipped.length
+  return {
+    headline: `${n} record${n === 1 ? '' : 's'} could not be placed — ${n === 1 ? 'its file is' : 'their files are'} unchanged.`,
+    lines: skipped.map((s) => `↷ ${s.slug ?? s.uuid ?? '(record)'}: ${s.reason}`)
   }
 }
 
@@ -438,39 +499,66 @@ async function checkWorkingTree(siteDir, args) {
  * merging afterwards — so the projector stays a plain writer and needs no hook, and
  * nothing is lost in between because "mine" is already in memory.
  *
- * Requires a repo, and that is not a mandate creeping in: the ancestor IS the
+ * Requires a repo, and that is not a mandate creeping in: the ancestor is a
  * committed version, and the merge is git's. There is nothing to merge against
  * without one.
  *
- * @returns {Map<string, {content: Buffer, inHead: boolean}>|null} captured work, or
- *   null when merging isn't possible here (the caller reports and stops).
+ * ⭐ THE ANCESTOR IS THE VERSION THE LAST PULL WROTE — found in history by the hash
+ * the pull recorded (`findCommitted`), HEAD's only for a file no pull ever wrote.
+ * HEAD stops being that version the moment someone commits an edit on top of it,
+ * and a merge against it read their edit as the starting point: the backend's
+ * version won whole, reverting the committed edit (measured 2026-09-23 — commit,
+ * push refused, `uniweb refresh`, the edit gone from the working tree). The same
+ * reason brings in work that is COMMITTED but was never pushed: clean to git, so a
+ * dirty scan cannot see it, yet the projection would overwrite it.
+ *
+ * @returns {Map<string, {content: Buffer, base: Buffer|null}>|null} captured work,
+ *   or null when merging isn't possible here (the caller reports and stops).
  */
 function captureLocalWork(siteDir) {
   const dirty = uncommittedUnder(siteDir, siteContentRoots(siteDir))
   if (dirty === null) return null
   const written = readWritten(siteDir)
+  const ancestorOf = (rel) => {
+    const recorded = written.files[rel]
+    return (recorded && findCommitted(siteDir, rel, recorded)) || showAtHead(siteDir, rel)
+  }
   const out = new Map()
   for (const rel of dirty) {
     if (isPullOutput(siteDir, rel, written)) continue // pull's own output, not work
     try {
-      out.set(rel, {
-        content: readFileSync(join(siteDir, rel)),
-        inHead: showAtHead(siteDir, rel) !== null
-      })
+      out.set(rel, { content: readFileSync(join(siteDir, rel)), base: ancestorOf(rel) })
     } catch {
       // Locally deleted. Pull will restore the backend's copy, which is the
       // sensible reading of "I removed this and then asked for their version".
     }
   }
+  // Committed work: a file a pull wrote, edited and committed since. Its ancestor is
+  // only ever the version the pull wrote — HEAD is the edit itself — and when that is
+  // not in history there is none, which the merge treats as such.
+  for (const [rel, recorded] of Object.entries(written.files)) {
+    if (out.has(rel) || dirty.includes(rel)) continue
+    let content
+    try {
+      content = readFileSync(join(siteDir, rel))
+    } catch {
+      continue
+    }
+    if (createHash('sha256').update(content).digest('hex') === recorded) continue // untouched
+    out.set(rel, { content, base: findCommitted(siteDir, rel, recorded) })
+  }
   return out
 }
 
-// Merge captured work back over what the projection just wrote. Returns a report.
+// Merge captured work back over what the projection just wrote. Returns a report;
+// `unavailable` lists files whose merge could not run at all — they did NOT take the
+// backend's version, so the caller must not record this pull as taken.
 function mergeLocalWork(siteDir, captured) {
   const clean = []
   const conflicted = []
   const kept = []
-  for (const [rel, { content: mine, inHead }] of captured) {
+  const unavailable = []
+  for (const [rel, { content: mine, base }] of captured) {
     const abs = join(siteDir, rel)
     let theirs = null
     try {
@@ -490,27 +578,23 @@ function mergeLocalWork(siteDir, captured) {
     }
     if (theirs.equals(mine)) continue // both sides agree already
 
-    const base = inHead ? showAtHead(siteDir, rel) : null
-    if (!base) {
-      // No committed ancestor — a file added locally and never committed. There is
-      // no third input, so a three-way merge is not defined. Keep ours rather than
-      // guess, and say so.
-      writeFileSync(abs, mine)
-      kept.push(`${rel} (no committed ancestor, kept yours)`)
-      continue
-    }
-
+    // ⛔ NO ANCESTOR IS A TWO-WAY MERGE, NOT "KEEP OURS". Both sides hold the file and
+    // no common version is on record — added on both sides, or a pull's version that
+    // was never committed. Keeping ours hid the backend's version entirely, and the
+    // pull then recorded it as taken. An empty ancestor is git's add/add: both
+    // versions, under conflict markers, for a person to settle.
     const dir = mkdtempSync(join(tmpdir(), 'uniweb-merge-'))
     try {
       const basePath = join(dir, 'base')
       const theirsPath = join(dir, 'theirs')
-      writeFileSync(basePath, base)
+      writeFileSync(basePath, base || '')
       writeFileSync(theirsPath, theirs)
       writeFileSync(abs, mine) // merge-file rewrites this in place
       const r = mergeFile(siteDir, abs, basePath, theirsPath)
       if (!r.merged) {
         writeFileSync(abs, mine) // merge couldn't run — never leave a half-state
         kept.push(`${rel} (merge unavailable, kept yours)`)
+        unavailable.push(rel)
       } else if (r.conflicted) {
         conflicted.push(rel)
       } else {
@@ -520,7 +604,7 @@ function mergeLocalWork(siteDir, captured) {
       rmSync(dir, { recursive: true, force: true })
     }
   }
-  return { clean, conflicted, kept }
+  return { clean, conflicted, kept, unavailable }
 }
 
 // Minimal yes/no prompt; defaults to no, because the default must not destroy.
@@ -704,12 +788,16 @@ export async function pull(args = [], deps = {}) {
       const etag = res.headers?.get?.('etag') ?? null
       const buf = Buffer.from(await res.arrayBuffer())
       const docs = readPullDocuments(buf)
-      // Bank the per-entity staleness tokens this lane carried, so the next push
-      // is gated against the state we just took. A 304 skips this — correctly:
-      // unchanged upstream means the token we already hold is still current.
-      mergeBaseVersions(siteDir, client.origin, readPullVersions(buf))
-      mergeItemBaseVersions(siteDir, client.origin, readPullItemVersions(buf))
-      return { docs, etag }
+      // The staleness tokens this lane carried, so the next push is gated against
+      // the state we took. Banked by the caller once local work is merged back — a
+      // file the merge did not take must not have its token recorded as taken. A 304
+      // carries none, correctly: the tokens we hold are still current.
+      return {
+        docs,
+        etag,
+        versions: readPullVersions(buf),
+        itemVersions: readPullItemVersions(buf)
+      }
     } catch (err) {
       error(`Could not read the ${label} response: ${err.message}`)
       return null
@@ -724,6 +812,9 @@ export async function pull(args = [], deps = {}) {
   let sections = 0
   let records = 0
   let deleted = 0
+  // Set when the folder lane carried records this pull did not place — see the ⛔
+  // where it is set.
+  let recordsNotPlaced = null
 
   // Conditional-pull cache: the last ETag seen per lane (opaque token — cached and
   // echoed verbatim, never recomputed). Lives in the gitignored `.uniweb/`.
@@ -747,16 +838,21 @@ export async function pull(args = [], deps = {}) {
     return pullScope
   }
 
+  // ⛔ `--force` IS UNCONDITIONAL. It means "take the backend's version over mine", and
+  // an ETag answers a different question — whether the BACKEND moved, never whether
+  // the files still hold what it sent. Echoed here, a `git checkout` followed by
+  // `pull --force` got a 304 and left the checked-out files in place (2026-09-23).
+  const conditional = !force
   // Lane 1 — content → config + pages/** + layout/**. The .uwx carries a single
   // entity (the site-content document). A 304 (unchanged) leaves local files as-is.
   const content = await getDocs('content', () =>
-    client.pullSiteContent(siteContentUuid, { etag: etagContent })
+    client.pullSiteContent(siteContentUuid, { etag: conditional ? etagContent : undefined })
   )
   if (content?.refused) return { exitCode: 1 }
   if (content && !content.notModified) {
     const siteDoc =
       content.docs &&
-      (content.docs.find((d) => d?.info || d?.$model) ||
+      (content.docs.find((d) => d?.info || documentSchema(d)) ||
         content.docs[0] ||
         null)
     if (siteDoc) {
@@ -865,17 +961,19 @@ export async function pull(args = [], deps = {}) {
   // (the backend resolves the site's `@uniweb/folder` from it; the framework never
   // 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
   if (!noRecords) {
     const folder = await getDocs('records', () =>
-      client.pullFolder(siteContentUuid, { etag: etagFolder })
+      client.pullFolder(siteContentUuid, { etag: conditional ? etagFolder : undefined })
     )
+    folderLane = folder
     if (folder?.refused) return { exitCode: 1 }
     if (folder && !folder.notModified && folder.docs?.length) {
       const { folderDoc, recordDocs } = splitRecordsPull(folder.docs)
       const resolveModel = makeModelResolver({ client })
       const declByModel = new Map()
       for (const model of [
-        ...new Set(recordDocs.map((d) => d.$model).filter(Boolean))
+        ...new Set(recordDocs.map((d) => documentSchema(d)).filter(Boolean))
       ]) {
         try {
           declByModel.set(model, await resolveModel(model))
@@ -883,8 +981,8 @@ export async function pull(args = [], deps = {}) {
           note(`! could not resolve model ${model}: ${err.message}`)
         }
       }
-      // ⛔ NO QUERY CONFIG. A record's home is decided by what it IS — its
-      // `$model` names the pool folder — not by any query that happens to select
+      // ⛔ NO QUERY CONFIG. A record's home is decided by what it IS — its data
+      // schema (`documentSchema`) names the pool folder — not by any query that happens to select
       // it. Handed the foundation's scope (`scopeFor`), `recordsToProject` places a
       // `@/x` model the producer resolved to `@acme/x` back where the author wrote it.
       const report = recordsToProject({
@@ -911,34 +1009,36 @@ export async function pull(args = [], deps = {}) {
         removed.push(resolve(siteDir, report.recordsFile))
       }
       records += report.placed.length + report.updated.length
-      for (const s of report.skipped)
-        note(`↷ ${s.slug ?? s.uuid ?? '(record)'}: ${s.reason}`)
+      // ⛔ A PULL THAT DID NOT PLACE A RECORD HAS NOT TAKEN THE BACKEND'S RECORDS.
+      // Until 2026-09-23 each skip was a dim note, the pull said "✓ Pulled … 0
+      // record(s)" and exited 0, and it banked the lane's ETag and tokens. So the next
+      // pull would hear 304 and never retry, and a `refresh && push` would go on to
+      // push — and a push sends the folder whole (`utils/records-guard.js`), so the
+      // skipped records would leave it. It is an error now, the lane is not recorded
+      // as taken (below), and the exit is non-zero (the end).
+      if (report.skipped.length) {
+        recordsNotPlaced = describeUnplacedRecords({
+          docs: folder.docs,
+          taken: report.placed.length + report.updated.length + report.unchanged.length,
+          skipped: report.skipped
+        })
+        error(recordsNotPlaced.headline)
+        for (const line of recordsNotPlaced.lines) note(`  ${line}`)
+      }
       for (const w of report.warnings) note(`! ${w}`)
     }
     if (folder?.etag) etagFolder = folder.etag
   }
 
-  // Persist the ETags so the next pull is conditional (304 when unchanged).
-  writePullCache(siteDir, { content: etagContent, folder: etagFolder })
+  // ⛔ WHAT THIS PULL WROTE, AND THE HASHES A PUSH DIFFS AGAINST, DESCRIBE THE
+  // BACKEND'S CONTENT — so both are taken over the projection, BEFORE local work is
+  // merged back. Taken after it, as they were until 2026-09-23, they recorded the
+  // merged-in local edits as pull output and as already pushed: the next push said
+  // "Nothing to push", `status` said in sync, and the edit never left this machine —
+  // while a later plain pull would have overwritten it as its own output.
+  //
   // Config files are rewritten every pull whether or not they changed; include the
   // ones the projector owns so a pull-then-pull doesn't trip on them either.
-  // Merge captured local work back over what the projection just wrote. Runs after
-  // BOTH lanes, so a file either lane produced is merged the same way.
-  if (captured && captured.size) {
-    mergeReport = mergeLocalWork(siteDir, captured)
-    const r = mergeReport
-    if (r.clean.length) {
-      info(`Merged your changes into ${r.clean.length} file(s):`)
-      for (const f of r.clean) note(`  ${f}`)
-    }
-    for (const f of r.kept) note(`\u21b7 ${f}`)
-    if (r.conflicted.length) {
-      error(`${r.conflicted.length} file(s) have conflicts to resolve:`)
-      for (const f of r.conflicted) note(`  ${f}`)
-      note('Conflict markers are in place. Resolve them, then commit and push.')
-    }
-  }
-
   recordWritten(
     siteDir,
     [
@@ -978,14 +1078,66 @@ export async function pull(args = [], deps = {}) {
     }
   }
 
-  success(
+  // Merge captured local work back over what the projection just wrote. Runs after
+  // BOTH lanes, so a file either lane produced is merged the same way.
+  if (captured && captured.size) {
+    mergeReport = mergeLocalWork(siteDir, captured)
+    const r = mergeReport
+    if (r.clean.length) {
+      info(`Merged your changes into ${r.clean.length} file(s):`)
+      for (const f of r.clean) note(`  ${f}`)
+    }
+    for (const f of r.kept) note(`\u21b7 ${f}`)
+    if (r.conflicted.length) {
+      error(`${r.conflicted.length} file(s) have conflicts to resolve:`)
+      for (const f of r.conflicted) note(`  ${f}`)
+      note('Conflict markers are in place. Resolve them, then commit and push.')
+    }
+  }
+
+  // ⛔ THE TOKENS AND ETAGS SAY "THIS COPY HOLDS THE BACKEND'S VERSION" — so they are
+  // banked only once every file has taken it, merged or in conflict. A token banked
+  // for a file that kept ours makes the next push of it read as "only you changed it"
+  // and overwrite the backend's version; an ETag banked for it makes every later pull
+  // answer 304, so the file never catches up. Measured 2026-09-23, both: a refused
+  // push, `uniweb refresh`, and a push that quietly put back a heading another writer
+  // had replaced. When a merge could not run, nothing of this pull is recorded as
+  // taken, and the next pull fetches it again.
+  const unavailable = mergeReport?.unavailable || []
+  if (unavailable.length) {
+    note("! Not recorded as taken — a merge could not run, so those files keep yours.")
+    note('  Pushing them is refused until a pull merges them; fix git, then `uniweb pull --merge` again.')
+  } else {
+    for (const lane of [content, folderLane]) {
+      if (!lane || lane.notModified || lane.refused) continue
+      // Records this pull did not place were not taken, so neither is their lane.
+      if (lane === folderLane && recordsNotPlaced) continue
+      mergeBaseVersions(siteDir, client.origin, lane.versions)
+      mergeItemBaseVersions(siteDir, client.origin, lane.itemVersions)
+    }
+    // Persist the ETags so the next pull is conditional (304 when unchanged). The
+    // folder's is DROPPED when records were not placed, so the next pull fetches
+    // them again rather than hearing 304 about a state it never took.
+    writePullCache(siteDir, {
+      content: etagContent,
+      folder: recordsNotPlaced ? null : etagFolder
+    })
+  }
+  if (recordsNotPlaced) {
+    note('Records not recorded as taken — the next pull fetches them again.')
+  }
+
+  const summary =
     `Pulled — ${pages} page(s), ${sections} section(s), ${records} record(s)` +
-      (deleted ? `, ${deleted} deleted` : '')
-  )
+    (deleted ? `, ${deleted} deleted` : '')
+  if (recordsNotPlaced) info(summary)
+  else success(summary)
   // Unresolved conflicts are a non-zero exit, the way a conflicted `git merge` is.
   // The pull itself worked; there is work left for a human. This is what makes a
   // chained `uniweb pull --merge && uniweb push` safe by construction — without it,
   // the obvious one-liner pushes conflict markers into live content.
+  // Records it could not place are the same: the pull ran, and what it was sent is not
+  // all in the files — a chained push must not go on as if it were.
   const conflicts = mergeReport?.conflicted?.length ?? 0
-  return { exitCode: conflicts ? 1 : 0, merge: mergeReport }
+  return { exitCode: conflicts || recordsNotPlaced ? 1 : 0, merge: mergeReport }
 }

package/src/commands/push.js

@@ -5,7 +5,7 @@
  *   - folder lane → one `@uniweb/folder` + the collection-record entities it
  *     references (the dynamic half; the `$ref` closure rides together).
  *
- * Each entity is an entity-content document (`$id` + `$model` + sections). The site's
+ * Each entity is an entity-content document (`$id` + `$schema` + sections). The site's
  * identity on a backend is its site-content uuid, in that backend's section of
  * `sync.json`. A first push to a backend has none — it CREATEs the site (uuid-less),
  * the backend mints + adopts it and returns the new uuid, which `push` records in
@@ -64,7 +64,7 @@ import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
 import { updateBackendMap, carryServed, SYNC_STORE_FILE } from '@uniweb/build/uwx'
 import { BackendClient } from '../backend/client.js'
 import { resolveSiteDir } from './deploy.js'
-import { warnIfContentDoesNotConform } from '../utils/conformance.js'
+import { refuseIfContentDoesNotConform } from '../utils/conformance.js'
 import { reportSchemalessQueries } from '../utils/schemaless-report.js'
 import { checkFlags } from '../utils/flag-guard.js'
 import {
@@ -83,6 +83,7 @@ import {
   readFolderItemUuids,
   readQueryUuids,
   ensureItemUuids,
+  refuseUnsendableRecords,
   ensureSiteExists,
   clearRemoteSyncStateIfUnbound,
   dropSiteBoundValues,
@@ -148,9 +149,10 @@ export async function push(args = [], deps = {}) {
 
   const siteDir = await resolveSiteDir(args, 'push')
 
-  // Advisory only — warns and pushes. A malformed data block otherwise rides
-  // the sync wire unchecked; see utils/conformance.js.
-  await warnIfContentDoesNotConform(siteDir, { args })
+  // ⭐ A GATE, before anything is sent: the backend checks these records against the
+  // schemas this push registers, so one that does not conform would be refused on
+  // arrival or lose a value on the way. See utils/conformance.js.
+  if (await refuseIfContentDoesNotConform(siteDir, { args })) return { exitCode: 1 }
   // ⭐ THE BACKEND YOU ARE LOGGED IN TO is where this goes *[Diego, 2026-09-21]*, for every
   // backend verb (resolveBackendOrigin). Only UNIWEB_REGISTER_URL — the automation
   // override — outranks it, and nothing talks to a backend the user is not logged in to:
@@ -394,6 +396,7 @@ export async function push(args = [], deps = {}) {
   let assetIds = null
   if (!output && !dryRun) {
     let mediaRefs = []
+    let refusals = []
     try {
       const probe = await emitSyncPackages(siteDir, {
       backend: client.origin,
@@ -403,10 +406,14 @@ export async function push(args = [], deps = {}) {
         resolveModel: makeModelResolver({ client, offline: false })
       })
       mediaRefs = probe.localAssets || []
+      refusals = probe.refusals || []
     } catch (err) {
       error(`Could not scan the site for local media: ${err.message}`)
       return { exitCode: 2 }
     }
+    // A record the backend would refuse stops the push HERE — before the site is
+    // created or a byte uploaded, not merely before the send (`refuseUnsendableRecords`).
+    if (refuseUnsendableRecords(refusals, { error, note })) return { exitCode: 1 }
     if (mediaRefs.length) {
       // The site has to exist before its bytes do — an upload with no owning
       // entity is charged and cannot be freed, because freeing means deleting the
@@ -530,6 +537,9 @@ export async function push(args = [], deps = {}) {
   const { siteContent, records, siteContentUuid, warnings, skipped } = pkg
   log('')
   for (const w of warnings) note(`! ${w}`)
+  // The same stop for the paths the probe above does not run on — `-o` and
+  // `--dry-run` say what a push would do, and a push would stop here.
+  if (refuseUnsendableRecords(pkg.refusals, { error, note })) return { exitCode: 1 }
   // Warn level, not dim: this is the author choosing entities vs static files.
   reportSchemalessQueries(pkg.schemaless, { warn, dim: note })
 

package/src/commands/status.js

@@ -38,6 +38,7 @@ import {
   foundationScopedName
 } from '../backend/foundation-bring-along.js'
 import { computeFoundationDigest } from '../utils/code-upload.js'
+import { compareSemverPrecedence } from '../utils/semver-precedence.js'
 import { checkFlags } from '../utils/flag-guard.js'
 
 const c = {
@@ -120,6 +121,7 @@ export async function status(args = []) {
   let site = null
   let fdnLatest = null
   let foundationFresh = null // true/false when both digests are known; else null
+  let localFoundationVersion = null
   let remoteError = null // a refusal about the workspace — the one remote failure worth saying
   if (remote) {
     try {
@@ -138,6 +140,7 @@ export async function status(args = []) {
       // site.yml ref. The digest compare is read-only — it never builds, so it
       // only fires when the local foundation is already built (dist present).
       const local = resolveLocalFoundation(siteDir, siteYml)
+      localFoundationVersion = local?.version ?? null
       const lookupName =
         (local && (await foundationScopedName(local.dir))) || fndScope
       if (lookupName) fdnLatest = await client.readFoundationLatest(lookupName)
@@ -240,10 +243,21 @@ export async function status(args = []) {
         `A newer foundation version (${fdnLatest.latest_version}) is registered than the site pins (${fndVersion}).`
       )
     }
+    // What the next push or publish does with it (`backend/foundation-bring-along.js`):
+    // release changed code — under the next version when its own is taken — unless the
+    // registry holds a NEWER version, which stops them. ⛔ This pointed at `uniweb
+    // register` until 2026-09-24 — which cannot release a change under a version
+    // already registered, since a registered version is immutable.
     if (foundationFresh === false) {
-      say.info(
-        'Local foundation differs from the registered version — `uniweb register` (or `uniweb publish`) to release the change.'
-      )
+      if (compareSemverPrecedence(localFoundationVersion, fdnLatest.latest_version) === -1) {
+        say.info(
+          `The registry holds foundation ${fdnLatest.latest_version}, newer than your ${localFoundationVersion} — a push or publish stops until you pull that change, or pass \`--bump\` to release yours above it.`
+        )
+      } else {
+        say.info(
+          'Local foundation differs from the registered version — the next `uniweb push` or `uniweb publish` releases it.'
+        )
+      }
     } else if (foundationFresh === true) {
       say.ok('Local foundation matches the registered version.')
     }

package/src/commands/validate.js

@@ -4,14 +4,18 @@
  *
  * For each section that consumes file-based data, this resolves the schema the
  * foundation bound to that input (via `meta.js` `data:`) and checks the data
- * items against it. It answers "does my data match what I promised?" — distinct
- * from `doctor`, which checks your project against framework conventions.
+ * items against it — and every record file in the records directory against the
+ * schema its folder names, whether or not a section reads it. It answers "does my
+ * data match what I promised?" — distinct from `doctor`, which checks your project
+ * against framework conventions.
  *
- * It warns by default; `--strict` turns findings into a non-zero exit for CI.
- * The live render path stays tolerant — this gate runs before a site is live,
- * by choice. Dynamic (remote) inputs and entity references can't be resolved
- * without a running backend, so they're reported as deferred, never silently
- * skipped.
+ * ⭐ A violation fails it (exit 1); `--lax` reports without failing. It warned by
+ * default until 2026-09-24, with `--strict` to fail — a gate that passes is one
+ * nobody reads, and `push` / `publish` now refuse the same findings. The live render
+ * path stays tolerant. Remote (`url:`) inputs are not in the project, so they're
+ * reported as deferred, never silently skipped. The value of an entity reference is
+ * not checked against the entity it names. ⛔ This said references were "reported as
+ * deferred" until 2026-09-24; no check ever reported them.
  */
 
 import { existsSync, readFileSync } from 'node:fs'
@@ -168,7 +172,7 @@ function printSiteHuman(result) {
   }
 
   if (deferred.length > 0) {
-    log(`  ${colors.dim}↪ deferred (not statically checkable):${colors.reset}`)
+    log(`  ${colors.dim}↪ deferred (not checked):${colors.reset}`)
     for (const d of deferred) {
       const extra = d.url
         ? ` ${colors.dim}(${d.url})${colors.reset}`
@@ -201,7 +205,9 @@ function dedupeUsers(users) {
 
 export async function validate(args = []) {
   const asJson = args.includes('--json')
-  const strict = args.includes('--strict')
+  // A violation fails the run unless `--lax` says to only report it. (`--strict`, the
+  // flag that turned failing on until 2026-09-24, is simply the default now.)
+  const strict = !args.includes('--lax')
   const siteFilter = flagValue(args, '--site')
   const positional = args.find(
     (a, i) => !a.startsWith('--') && args[i - 1] !== '--site'
@@ -353,7 +359,7 @@ export async function validate(args = []) {
           ? `${colors.red}error${colors.reset}`
           : `${colors.yellow}warning${colors.reset}`
         log(
-          `${totalViolations} violation(s) — reported as ${mode}${strict ? '' : ` ${colors.dim}(pass --strict to fail CI)${colors.reset}`}`
+          `${totalViolations} violation(s) — reported as ${mode}${strict ? '' : ` ${colors.dim}(--lax: without it, this fails)${colors.reset}`}`
         )
       }
       if (hadError)
@@ -362,9 +368,8 @@ export async function validate(args = []) {
     }
   }
 
-  // Exit semantics: 2 = couldn't run; 1 = violations under --strict; 0 = clean
-  // or warn-only (the live path stays tolerant, so findings don't fail by
-  // default). Setup/read failures are surfaced but don't fail the build.
+  // Exit semantics: 2 = couldn't run; 1 = violations (unless --lax); 0 = clean, or
+  // violations reported under --lax. Setup/read failures are surfaced but don't fail.
   if (hadError) return { exitCode: 2 }
   if (totalViolations > 0 && strict) return { exitCode: 1 }
   return { exitCode: 0 }