@uniweb/build 0.59.0 → 0.60.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.59.0",
+  "version": "0.60.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,11 +57,11 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/schemas": "^0.3.4",
+    "@uniweb/content-reader": "^1.2.5",
     "@uniweb/semantic-parser": "^1.4.1",
     "@uniweb/content-writer": "^0.3.4",
     "@uniweb/projections": "^0.7.3",
-    "@uniweb/content-reader": "^1.2.5",
+    "@uniweb/schemas": "^0.5.0",
     "@uniweb/theming": "^0.1.15"
   },
   "optionalDependencies": {
@@ -74,8 +74,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/runtime": "^0.27.4",
-    "@uniweb/core": "^0.29.8"
+    "@uniweb/core": "^0.29.8",
+    "@uniweb/runtime": "^0.27.4"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/resolve-data-schema.js

@@ -287,17 +287,40 @@ async function collectSchemasFromExports(packageDir) {
 // Source 2: a bare `schemas/` directory of schema files, one schema per file
 // (named by basename). Returns `{}` when the directory is absent.
 async function collectSchemasFromDir(dir) {
-  if (!existsSync(dir)) return {}
   const out = {}
-  for (const file of readdirSync(dir).sort()) {
-    const ext = extname(file)
-    if (!SCHEMA_EXTENSIONS.includes(ext)) continue
-    const name = basename(file, ext)
+  for (const { file, name } of schemaFilesIn(dir)) {
     out[`@/${name}`] = validateAndNormalizeSchema(await loadSchemaFile(join(dir, file)), `@/${name}`)
   }
   return out
 }
 
+// The schema files directly in a folder, one schema per file, named by basename.
+// ⭐ A leading `_` leaves a file out — a draft — as it does for a record.
+function schemaFilesIn(dir) {
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .sort()
+    .filter((file) => SCHEMA_EXTENSIONS.includes(extname(file)) && !file.startsWith('_'))
+    .map((file) => ({ file, name: basename(file, extname(file)) }))
+}
+
+/**
+ * The data schemas a foundation DEFINES: one `@/<name>` per file in its `schemas/`
+ * folder, a file named with a leading `_` left out.
+ *
+ * ⭐ THE FOLDER IS THE DECLARATION [Diego, 2026-09-24] — the same rule as for a
+ * record: placing the file there is what makes it one. Until then a foundation's
+ * data schemas were only the ones a section binding reached, so a type only the app
+ * uses — a lesson, a quiz, a learner's progress, which no section renders — was
+ * never in `schema.json` and never registered.
+ *
+ * @param {string} srcDir - the foundation's source root
+ * @returns {string[]}
+ */
+export function ownSchemaRefs(srcDir) {
+  return schemaFilesIn(join(srcDir, 'schemas')).map(({ name }) => `@/${name}`)
+}
+
 // Resolve a package's module entry FILE (absolute) from its package.json —
 // `exports['.']` (string or a conditional import/default/node), else `main`, else
 // `index.js`. Loads a schemas package's own exports without self-resolution.

package/src/schema.js

@@ -17,7 +17,7 @@ import { isFontVar } from '@uniweb/theming'
 import { join, dirname, extname, basename } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { inferTitle } from './utils/infer-title.js'
-import { collectSchemaRefs, buildDataSchemaMap } from './resolve-data-schema.js'
+import { collectSchemaRefs, buildDataSchemaMap, ownSchemaRefs } from './resolve-data-schema.js'
 import {
   composeSupports,
   deriveRecordsSupport,
@@ -960,10 +960,13 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
   // Discover section types
   const components = await discoverComponents(srcDir, sectionPaths)
 
-  // Resolve the data schemas referenced by section bindings (carried in
-  // schema.json for the editor/platform — see named-data-schemas.md).
+  // Resolve the data schemas the foundation DEFINES — every file in its `schemas/`
+  // folder (`ownSchemaRefs`) — and the ones its section bindings reference, carried
+  // in schema.json for the editor/platform (see named-data-schemas.md); `register`
+  // submits the `@/` ones. Bound refs come first, so a foundation whose schemas are
+  // all bound builds the same schema.json it always did.
   const dataSchemas = await buildDataSchemaMap(
-    collectSchemaRefs(components, foundationConfig.data),
+    new Set([...collectSchemaRefs(components, foundationConfig.data), ...ownSchemaRefs(srcDir)]),
     { srcDir },
   )
 

package/src/uwx/backfill.js

@@ -12,6 +12,14 @@
 // canonical). It reads from the SOURCE file (not the backend's finalized document),
 // so field values round-trip untouched and no inverse decode is needed in v1.
 //
+// ⛔ A PUSH NEVER RENDERS THE BACKEND'S DOCUMENT OVER THE AUTHOR'S FILE. It did, for
+// a record's first push, from 2026-05-29 to 2026-09-23 ("variant A"), and that
+// document is not the author's file: it carries the serve URL the push put where the
+// author wrote `/images/x.png`, and only the brief section's declared fields. So a
+// first push rewrote the record's images to a backend route and deleted every key the
+// Model does not declare, and every field of any other section. What a backend holds
+// reaches the file on a pull (`records-project.js`), which restores asset paths first.
+//
 // Single-record YAML/JSON/markdown files are rendered/back-filled in place.
 // Multi-record files — array-form YAML/JSON and BibTeX (many records in one
 // file) — are grouped by file and written once, one `$uuid` per record keyed by
@@ -213,27 +221,19 @@ function briefSectionOf(declaration) {
   return entry ? { name: entry[0], ...entry[1] } : null
 }
 
-// Whether a Model's brief section declares a CONTENT body field (a markup `text`
-// field, or a `format: prosemirror` json field) — the md-body target. A markdown
-// source file can only be safely rendered from the document when its body has a
-// field home — otherwise the body would be lost (variant B then).
-function briefHasContentBody(declaration) {
-  const brief = briefSectionOf(declaration)
-  return Object.values(brief?.fields || {}).some((f) => isContentBodyField(f))
-}
-
 /**
- * Render a finalized entity `document` back to its source-file authoring shape
- * (variant A — the file becomes a projection of backend state). For a flat/brief
- * entity: the entity `$uuid` + the brief section's fields (localized unwrapped,
+ * Render an entity `document` a pull brought back to its source-file authoring shape
+ * — the file becomes a projection of the backend's state, which is what a pull is
+ * (`writeRecordFile`, `records-project.js`). A push never uses it (header ⛔). For a
+ * flat/brief entity: the entity `$uuid` + the brief section's fields (localized unwrapped,
  * date/scalars verbatim), with the brief record's own `$uuid` DROPPED (the backend
- * matches a single-section item by singularity) and `$model`/`$id`/`$meta` omitted.
+ * matches a single-section item by singularity) and `$schema`/`$id`/`$meta` omitted.
  * A disabled entity (`$disabled: true`) writes `draft: true`, and an enabled one writes
  * no `draft:` at all.
  * For markdown, the content body field becomes the body; for YAML/JSON it stays a field.
  *
  * @param {object} params
- * @param {object} params.document     - finalized `{ $uuid, $model, <brief>: {…} }`
+ * @param {object} params.document     - pulled `{ $uuid, $schema, <brief>: {…} }`
  * @param {object} params.declaration  - the Model declaration (`brief` + `sections`)
  * @param {string} params.format       - 'yaml' | 'json' | 'md'
  * @param {string} [params.sourceLocale]
@@ -296,40 +296,26 @@ export function renderEntityDocument({ document, declaration, format, sourceLoca
   return yaml.dump(record) // yaml / yaml
 }
 
-// Write text only when it differs from what's on disk (idempotent).
-function writeIfChanged(filePath, text) {
-  let current = ''
-  try {
-    current = readFileSync(filePath, 'utf8')
-  } catch {
-    // new file / unreadable — treat as a change
-  }
-  if (text === current) return 'unchanged'
-  writeFileSync(filePath, text)
-  return 'updated'
-}
-
 /**
  * Back-fill the sync response into the source files. Correlation is by **`index`**
  * — `finalized[i].index` is the 0-based position of the entity in the submitted
  * sequence, which equals the producer's `index` array order (the backend does not
- * echo `$id`). Single-record files are rendered from the finalized `document`
- * (variant A) when the document + declaration are present and lossless for the
- * format (markdown needs a content body field to carry the body); otherwise the
- * entity `$uuid` is back-filled in place (variant B). Multi-record YAML/JSON files
- * get a per-entry `$uuid` keyed by slug, grouped so each file is written once;
- * BibTeX stays deferred.
+ * echo `$id`). A single-record file gains the entity `$uuid` and nothing else —
+ * never the returned `document` (see the ⛔ in the header). Multi-record YAML/JSON
+ * files get a per-entry `$uuid` keyed by slug, and BibTeX one per cite key, grouped
+ * so each file is written once.
  *
  * @param {object} params
  * @param {object[]} params.index     - the emitter's per-entity index, in submit
- *        order: `{ id, model, slug, sourceFile, format?, multiRecord?, declaration? }`.
+ *        order: `{ id, model, slug, sourceFile, format?, multiRecord?, ownId?, draft? }`.
  * @param {object[]} params.finalized - response entries `{ index, uuid, changed?, document? }`.
- * @param {string} [params.sourceLocale]
+ *        `document` is read for one thing only: whether a record sent as a draft
+ *        came back disabled.
  * @returns {{ updated: string[], unchanged: string[], deferred: object[], warnings: string[], mapped: Object<string,string>, notKeptAsDrafts: string[] }}
  *   `mapped` is own id → the uuid this backend minted, for the caller to record per backend.
  *   `notKeptAsDrafts` names records sent as drafts whose returned document is not disabled.
  */
-export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
+export function backfillEntityUuids({ index, finalized }) {
   const updated = []
   const unchanged = []
   const deferred = []
@@ -364,10 +350,9 @@ export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
     // ⛔ A DRAFT THE BACKEND DID NOT KEEP AS ONE. A backend is obliged to echo
     // `$disabled: true` on the document of an entity it stored disabled. One that predates
     // the key skips it without a word and stores the record enabled, so it is delivered
-    // once the site is published. Rendering that document over the file (variant A) would
-    // then erase `draft: true` from the author's file as well, so the file keeps its own
-    // text and the caller is told. Only a returned document that lacks the flag counts:
-    // with no document there is nothing to judge.
+    // once the site is published. The file keeps its `draft: true` — only the uuid is
+    // written — and the caller is told. Only a returned document that lacks the flag
+    // counts: with no document there is nothing to judge.
     const draftNotKept = entry.draft === true && fin.document && fin.document.$disabled !== true
     if (draftNotKept) notKeptAsDrafts.push(entry.sourceFile || entry.id)
     if (!entry.sourceFile) {
@@ -383,9 +368,9 @@ export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
 
     // ⛔ A record that already carries its OWN id is NOT rewritten. Its id is stable
     // and travels with the file; this backend's uuid belongs in the map, not in the
-    // author's file. And it must not be: variant A below re-renders the WHOLE file from
-    // the backend's document, which carries THIS backend's `$uuid` — so a second
-    // backend would silently overwrite the record's identity with its own.
+    // author's file. And it must not be: the write below puts THIS backend's `$uuid` in
+    // the file, so a second backend would silently overwrite the record's identity
+    // with its own.
     if (entry.ownId) {
       ownIdFiles.add(entry.sourceFile)
       continue
@@ -404,31 +389,8 @@ export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
       continue
     }
 
-    // Variant A: render the finalized document over the file when we have it +
-    // the declaration, and it's lossless for the format (md needs a content body
-    // field for its body). Otherwise variant B: back-fill the uuid in place.
-    const canRenderA =
-      !draftNotKept &&
-      fin.document &&
-      entry.declaration &&
-      (entry.format !== 'md' || briefHasContentBody(entry.declaration))
-    let res
-    if (canRenderA) {
-      try {
-        const text = renderEntityDocument({
-          document: fin.document,
-          declaration: entry.declaration,
-          format: entry.format,
-          sourceLocale,
-        })
-        res = { status: writeIfChanged(entry.sourceFile, text) }
-      } catch (err) {
-        warnings.push(`${entry.sourceFile}: ${err.message}; fell back to uuid back-fill`)
-        res = backfillUuid(entry.sourceFile, uuid)
-      }
-    } else {
-      res = backfillUuid(entry.sourceFile, uuid)
-    }
+    // The uuid, into the author's own file — never the returned document (header ⛔).
+    const res = backfillUuid(entry.sourceFile, uuid)
     if (res.status === 'updated') updated.push(entry.sourceFile)
     else if (res.status === 'unchanged') unchanged.push(entry.sourceFile)
     else if (res.status === 'deferred') deferred.push({ index: i, id: entry.id, file: entry.sourceFile, reason: res.message })

package/src/uwx/data-schema.js

@@ -79,7 +79,7 @@ export function isContentBodyField(field) {
  *   (item_ref) ref to its full `@org/model/<section>` path. Falls back to
  *   `resolveName` (model only) when not supplied.
  * @returns {Object} the declaration (`{ name, label?, description?, source_locale?,
- *          creatable_by?, linkable?, sections }`).
+ *          linkable?, sections }`).
  */
 export function toDataSchemaDeclaration(normalized, { name, resolveName, resolveOptions } = {}) {
   if (!name) throw new Error('toDataSchemaDeclaration: a registry name is required')
@@ -104,10 +104,8 @@ export function toDataSchemaDeclaration(normalized, { name, resolveName, resolve
   if (normalized.label) decl.label = normalized.label
   if (normalized.description) decl.description = normalized.description
   if (normalized.sourceLocale) decl.source_locale = normalized.sourceLocale
-  // `creatable_by` — who may instantiate this Model. Omitted when the author
-  // declares nothing, because the registry's own default (open) is the absent
-  // meaning; sending it explicitly would state a policy the author did not.
-  if (normalized.creatableBy) decl.creatable_by = normalized.creatableBy
+  // ⛔ No `creatable_by`: retired 2026-09-23 — Models are open, and `@uniweb/schemas`
+  // refuses the key. (It was emitted here when authored.)
 
   // `linkable` — DERIVED AND AUTHORED, and the two compose in one direction only.
   //

package/src/uwx/emit-surface.json

@@ -10,7 +10,7 @@
   "systemKeys": [
     "$uuid",
     "$id",
-    "$model"
+    "$schema"
   ],
   "sections": {
     "info": {

package/src/uwx/entity-document.js

@@ -3,7 +3,7 @@
 // Distinct from package.js's emitEntityPackage (the register / site-content lane,
 // whose per-entity body is the legacy `items[]` shape). The sync lane's per-entity
 // body is the section-keyed `$`-document (see docs/reference/entity-content.md):
-// `$uuid?` then `$id` `$model`, then one key per top-level section.
+// `$uuid?` then `$id` `$schema`, then one key per top-level section.
 //
 // Identity rides in the BODY — the backend reads `$id` always, `$uuid` when
 // present, and MINTS `$uuid` on first sync. The manifest is the INDEX, not a copy
@@ -25,6 +25,27 @@ import {
   computePackageSha256,
 } from './manifest.js'
 
+/**
+ * The data schema a `$`-document names — its scoped name (`@scope/name`), or null.
+ *
+ * ⭐ `$schema` is the key, agreed with backend on 2026-09-24 to match the query wire's
+ * `schema` for the same value: what the two lanes exchange is a data schema, and the
+ * scoped name is how we address one in the registry of the backend we talk to. ⛔ Not
+ * an identity ACROSS backends — each has its own registry, so one name on two of them
+ * names two data schemas [Diego, 2026-09-24]. It was `$model` until
+ * then, and ⛔ nothing reads that spelling — no production backend existed to keep a
+ * window for [Diego, 2026-09-24]. The value comes back as it is, so a caller can still
+ * tell an id from a name and say which it met.
+ * Record: `kb/framework/build/uwx-format.md` § *The data schema an entity names*.
+ *
+ * @param {object} doc - an entity `$`-document
+ * @returns {string|null}
+ */
+export function documentSchema(doc) {
+  const value = doc?.$schema
+  return typeof value === 'string' && value ? value : null
+}
+
 // `exporter.instance`: caller-override -> env UNIWEB_INSTANCE_ID -> "unknown".
 // Provenance only; neutralized in the digest, so its value is inert.
 function defaultExporter() {

package/src/uwx/folder.js

@@ -52,18 +52,22 @@ export const FOLDER_MODEL_NAME = '@uniweb/folder'
 export const FOLDER_ENTITY_KEY = '@folder'
 
 // Point one authored leaf at the record entity it names. The folder's `contents`
-// field is polymorphic (it can reference any Model), so the ref uses the
-// entity_ref OPEN form `{ model, entity }` — not a bare uuid (a bare uuid is only
-// valid when the field pins a single model). Known uuid → `entry: { model, entity
+// field is polymorphic (it can reference any data schema), so the ref uses the
+// entity_ref OPEN form `{ schema, entity }` — not a bare uuid (a bare uuid is only
+// valid when the field pins a single schema). Known uuid → `entry: { schema, entity
 // }`; brand-new → `$ref` handle (resolved within this payload to the minted
 // entity).
 //
-// TODO: the sync lane is uuid-keyed, so `model` should be the resolved Model UUID;
-// it currently carries the Model NAME (e.g. `@std/article`). Wire the name→uuid
-// resolution (a registry data-schema read) as a follow-up.
+// ⭐ `schema` carries the data schema's SCOPED NAME (`@std/article`), never a Model id
+// — agreed with backend 2026-09-24: a Model id is the backend's internal identity and
+// does not cross `/dev`, while a scoped name is how we address a data schema in the
+// registry of the backend we talk to. ⛔ Neither is an identity across backends: each
+// has its own registry [Diego, 2026-09-24]. (A TODO here asked
+// for the id until then; the agreement settled it the other way.) The key was `model`
+// until the same date. Record: `kb/framework/build/uwx-format.md` § 8.
 function refLeaf(entity) {
   const leaf = { kind: 'ref', name: entity.slug }
-  if (entity.uuid) leaf.entry = { model: entity.model, entity: entity.uuid }
+  if (entity.uuid) leaf.entry = { schema: entity.model, entity: entity.uuid }
   else leaf.$ref = entity.id // the payload-local handle
   return leaf
 }
@@ -103,7 +107,7 @@ function contentsFromNodes(nodes, byEntityId, missing, sourceLocale) {
   return out
 }
 
-// The uuid of the record a leaf references — once minted, `entry: { model, entity }`
+// The uuid of the record a leaf references — once minted, `entry: { schema, entity }`
 // (a bare uuid is tolerated). A brand-new record's leaf carries `$ref` instead.
 function recordOf(item) {
   if (item?.kind !== 'ref') return null
@@ -255,7 +259,7 @@ export function buildFolderEntity({ recordEntities, folderNodes = [], declared,
 
   const document = {
     $id: FOLDER_ENTITY_KEY,
-    $model: FOLDER_MODEL_NAME,
+    $schema: FOLDER_MODEL_NAME,
     contents,
   }
   // Re-arm placement identity. Without it a second send reads as "every item is

package/src/uwx/index.js

@@ -21,7 +21,7 @@ export {
   PACKAGE_SHA256_ASSUMPTIONS,
 } from './manifest.js'
 export { emitEntityPackage } from './package.js'
-export { emitEntitySyncPackage } from './entity-document.js'
+export { emitEntitySyncPackage, documentSchema } from './entity-document.js'
 export {
   FOUNDATION_SCHEMA_TYPE_UUID,
   SITE_CONTENT_TYPE_UUID,

package/src/uwx/project-writer.js

@@ -212,7 +212,12 @@ function mergeYamlConfig(filePath, changes, { replace = [] } = {}) {
     if (value === null || value === undefined) {
       delete existing[key]
     } else if (typeof value === 'object' && !Array.isArray(value) && !replace.includes(key)) {
-      existing[key] = { ...(existing[key] || {}), ...value }
+      // ⛔ Merged only INTO AN OBJECT. Spread, a string becomes its characters: a
+      // pull wrote `events: '@/event'` back as `events: { '0': '@', '1': '/', …,
+      // schema: '@/event' }` (measured 2026-09-23). Anything else that is not an
+      // object has nothing to keep, so the incoming value replaces it.
+      const prior = existing[key]
+      existing[key] = isPlainObject(prior) ? { ...prior, ...value } : value
     } else {
       existing[key] = value
     }
@@ -220,6 +225,8 @@ function mergeYamlConfig(filePath, changes, { replace = [] } = {}) {
   return writeIfChanged(filePath, yaml.dump(existing, YAML_DUMP_OPTS))
 }
 
+const isPlainObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v)
+
 /**
  * Merge `config` into `site.yml` (shallow). Preserves keys not present in the
  * update (foundation, base, paths, …).
@@ -290,9 +297,45 @@ export function writeMergedYaml(filePath, projected, managedKeys) {
  * @returns {'updated'|'unchanged'}
  */
 export function writeQueriesConfig(siteRoot, queries) {
-  return mergeYamlConfig(queriesYmlPath(siteRoot), queries)
+  const filePath = queriesYmlPath(siteRoot)
+  let authored = {}
+  try {
+    authored = yaml.load(readFileSync(filePath, 'utf8'), YAML_OPTIONS) || {}
+  } catch {
+    // missing / invalid → nothing authored to keep
+  }
+  // ⭐ A query the file already states is left as the author wrote it — in the same
+  // words, or in a shorthand (`team: '@/person'` is `{ schema: '@/person' }`, a bare
+  // `events:` is `{}`), which a pull brings back in its long form. And a pull that
+  // restates every query writes nothing: the file is re-dumped whole otherwise, which
+  // rewrites a bare `events:` as `events: null` and flow style as block style.
+  const changes = {}
+  for (const [name, decl] of Object.entries(queries)) {
+    if (restates(authored?.[name], decl)) continue
+    changes[name] = decl
+  }
+  if (Object.keys(changes).length === 0) return 'unchanged'
+  // ⛔ Each query WHOLE (`replace`), as this function's header always said. Merged into
+  // the local one — what the call did until 2026-09-23 — a key the backend's
+  // declaration no longer has survived every pull: the defect `writeSiteConfig`
+  // records for the declaration keys ("a stale `limit` survived every pull").
+  return mergeYamlConfig(filePath, changes, { replace: Object.keys(changes) })
+}
+
+// Whether a pulled declaration says only what the author's entry already says.
+function restates(authored, decl) {
+  const keys = Object.keys(decl || {})
+  if (typeof authored === 'string') return keys.length === 1 && decl.schema === authored
+  if (authored === null) return keys.length === 0
+  return isPlainObject(authored) && canonicalJson(authored) === canonicalJson(decl)
 }
 
+// JSON with every object's keys sorted — equal for equal values, whatever the order.
+const canonicalJson = (value) =>
+  JSON.stringify(value, (_, v) =>
+    isPlainObject(v) ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, v[k]])) : v
+  )
+
 /**
  * Write the records folder's organization — `folder.yml` in the records directory
  * (`records/`, or wherever `site.yml::paths.records` puts it), as a LIST.
@@ -324,13 +367,13 @@ export function writeThemeFile(siteRoot, theme) {
 }
 
 /**
- * Render a finalized collection-record `document` to its source-file shape
- * (variant A, via renderEntityDocument) and write it idempotently. The record
- * half of the collections lane's write step.
+ * Render a collection-record `document` a pull brought back to its source-file shape
+ * (via renderEntityDocument) and write it idempotently. The record half of the
+ * collections lane's write step.
  *
  * @param {object} opts
  * @param {string} opts.filePath
- * @param {object} opts.document    - finalized `{ $uuid, $model, <brief>: {…} }`
+ * @param {object} opts.document    - pulled `{ $uuid, $schema, <brief>: {…} }`
  * @param {object} opts.declaration - the record's data-schema declaration
  * @param {'yaml'|'json'|'md'} opts.format
  * @param {string} [opts.sourceLocale]

package/src/uwx/records-project.js

@@ -6,12 +6,13 @@
 //
 // Identity & placement:
 //   - a record's slug comes from the FOLDER document — each ref leaf is
-//     `{ entry: { model, entity: <uuid> }, name: <slug> }`, at the top of the folder
+//     `{ entry: { schema, entity: <uuid> }, name: <slug> }`, at the top of the folder
 //     or inside a branch (its `$children`) whose `name` names the sub-folder. The
 //     folder is the authoritative organization on a read (the record document's own
 //     `$id` envelope is not guaranteed to be echoed back), with the record
 //     document's `$id` (its position in the directory) as a fallback when present.
-//   - the record's directory comes from its `$model` — `records/{schema}/` is where
+//   - the record's directory comes from its data schema (`$schema`, read by
+//     `documentSchema`) — `records/{schema}/` is where
 //     a record of that model lives (`site.yml::paths.records` moves it). Not from any
 //     query: a query has no directory, and which query selects a record is not a
 //     fact about it.
@@ -21,7 +22,8 @@
 //     brief has a content body field, else YAML.
 //
 // Field rendering reuses renderEntityDocument (via writeRecordFile) — localized
-// unwrap, date handling, content-body→body are already inverted there.
+// unwrap, date handling, content-body→body are already inverted there. Asset paths
+// are restored before it runs (`restoreAssetRefs`), as the content lane does.
 //
 // Deferred: array-form & BibTeX multi-record files (a pulled record is placed as
 // its own single-record file; merging into an existing array file is a later
@@ -30,6 +32,8 @@
 // record is reported.
 
 import { readBackendState, updateBackendMap } from './sync-store.js'
+import { restoreAssetRefs } from './asset-map.js'
+import { documentSchema } from './entity-document.js'
 import { readFileSync, readdirSync, existsSync, unlinkSync } from 'node:fs'
 import { join, resolve, relative, extname, basename, sep } from 'node:path'
 import yaml from 'js-yaml'
@@ -116,7 +120,7 @@ function briefHasContentBody(declaration) {
 // folder is a self-nesting tree under `contents`, nesting via `$children` (the
 // site-content invariant — folder.js). A leaf sits in a branch whose `name` is
 // the collection; the leaf's `name` is the slug (the handle) and its `entry` is
-// the entity_ref open form `{ model, entity: <uuid> }`. ⛔ `path_segment` is not
+// the entity_ref open form `{ schema, entity: <uuid> }`. ⛔ `path_segment` is not
 // read: the store renamed it on 2026-09-04 and a pull emits the new shape only —
 // a reader that kept the old key would index every record as
 // `{ folderPath: null, slug: undefined }` and rewrite records.yml with
@@ -131,7 +135,7 @@ function indexFolder(folderDoc) {
       if (node?.kind === 'branch') {
         walk(node.$children, node.name ?? folderPath)
       } else if (node?.kind === 'ref' && node.entry) {
-        // `entry` is `{ model, entity: <uuid> }`; tolerate a bare uuid defensively.
+        // `entry` is `{ schema, entity: <uuid> }`; tolerate a bare uuid defensively.
         const uuid = typeof node.entry === 'object' ? node.entry.entity : node.entry
         if (uuid) byUuid.set(uuid, { folderPath, slug: node.name })
       }
@@ -456,11 +460,11 @@ export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceL
  *
  * @param {object} params
  * @param {object} params.folderDoc   - the `@uniweb/folder` document `{ contents }` (no `$uuid`)
- * @param {object[]} params.recordDocs - record `$`-documents `{ $uuid?, $id?, $model, <brief> }`
+ * @param {object[]} params.recordDocs - record `$`-documents `{ $uuid?, $id?, $schema, <brief> }`
  * @param {string} params.siteRoot
  * @param {object} params.opts
  * @param {(modelName: string) => object|null|undefined} params.opts.resolveDeclaration
- *        - resolve a Model's data-schema declaration by name (`$model`).
+ *        - resolve a data schema's declaration by its scoped name (`documentSchema`).
  * @param {string|null} [params.opts.scope] - the scope the push qualified a record's
  *        `@/x` Model with — the site's foundation's — so a `@scope/x` model is placed
  *        back where the author wrote it. The caller resolves it up front, as it does
@@ -495,8 +499,16 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
   const unchanged = []
   const skipped = []
   const warnings = []
+  const backendState = opts.backend ? readBackendState(siteRoot, opts.backend) : {}
+  // ⛔ PUT THE AUTHOR'S ASSET PATHS BACK BEFORE ANYTHING IS RENDERED — the step the
+  // content lane takes (`site-project.js`), for the same reason. A pushed record goes
+  // up with the serve URL the push put where its author wrote `/images/x.png`, and it
+  // comes back that way; rendered as is, a pull rewrites the author's file to a
+  // backend route. Asset ids and fingerprints are per backend, so a projection tied
+  // to none restores nothing. Missing here until 2026-09-23.
+  restoreAssetRefs(recordDocs, backendState.assets || {})
   // This backend's record map, inverted: its uuid → the record's own id.
-  const recordMap = opts.backend ? readBackendState(siteRoot, opts.backend).records || {} : {}
+  const recordMap = backendState.records || {}
   const ownIdByTheirs = new Map(Object.entries(recordMap).map(([own, theirs]) => [theirs, own]))
   // own id → their uuid, for every record this pull wrote. Recorded at the end.
   const learned = {}
@@ -512,18 +524,19 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
       skipped.push({ uuid: document.$uuid, reason: 'no slug (not in the folder, no $id)' })
       continue
     }
-    const declaration = document.$model ? resolveDeclaration(document.$model) : null
+    const schema = documentSchema(document)
+    const declaration = schema ? resolveDeclaration(schema) : null
     if (!declaration) {
-      skipped.push({ uuid: document.$uuid, slug: where.slug, reason: `unresolved model ${document.$model || '(none)'}` })
+      skipped.push({ uuid: document.$uuid, slug: where.slug, reason: `unresolved model ${schema || '(none)'}` })
       continue
     }
 
-    const poolDir = recordDirFor(recordsRoot, document.$model, selfScope)
+    const poolDir = recordDirFor(recordsRoot, schema, selfScope)
     if (!poolDir) {
       skipped.push({
         uuid: document.$uuid,
         slug: where.slug,
-        reason: `model ${document.$model} names no pool folder (expected @/name or @org/name)`,
+        reason: `model ${schema} names no pool folder (expected @/name or @org/name)`,
       })
       continue
     }
@@ -550,7 +563,7 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
 
     // The free-form home for this record's content body (locale-independent); a
     // target-locale full-doc body is written under locales/freeform/{locale}/here.
-    const freeformRelPath = buildFreeformRecordPath(document.$model, where.slug)
+    const freeformRelPath = buildFreeformRecordPath(schema, where.slug)
 
     // ⛔ The file gets the record's OWN id, never this backend's — a pull from a second
     // backend must not overwrite the identity the record already has.
@@ -559,7 +572,11 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
     try {
       status = writeRecordFile({ filePath, document: toWrite, declaration, format, sourceLocale, collector, freeformRelPath })
     } catch (err) {
-      warnings.push(`${where.slug}: ${err.message}`)
+      // ⛔ A record that could not be written was not placed, so it is a SKIP, not a
+      // warning: a caller that counts what it placed (the CLI's pull) must see it.
+      // Until 2026-09-24 it was a warning, and a pull over records with no Sections —
+      // what a partly applied push left — reported every one of them as taken.
+      skipped.push({ uuid: document.$uuid, slug: where.slug, reason: err.message })
       continue
     }
     if (status === 'unchanged') unchanged.push(filePath)

package/src/uwx/records.js

@@ -2,7 +2,7 @@
 // referenced BY NAME, on the entity-content SYNC lane.
 //
 // Each record becomes a section-keyed `$`-document (docs/reference/entity-content.md):
-// `$id` (the producer-local handle), `$model` (the Model by name), and
+// `$id` (the producer-local handle), `$schema` (its data schema, by scoped name), and
 // each SINGLE section keyed by its name — the brief plus any sibling singles, not
 // the brief alone. The backend MINTS `$uuid` on first sync and
 // returns it in the finalized response; the verb back-fills it into the source
@@ -75,7 +75,7 @@ const SKIP_KEYS = new Set([
   'slug',
   '$id',
   '$uuid',
-  '$model',
+  '$schema',
   '$owner',
   '$unit',
   '$meta',
@@ -85,7 +85,7 @@ const SKIP_KEYS = new Set([
   'draft',
 ])
 
-// Recursively drop IDENTITY `$`-sigil keys (`$uuid`/`$id`/`$model`/… — never
+// Recursively drop IDENTITY `$`-sigil keys (`$uuid`/`$id`/`$schema`/… — never
 // field data; the sigil-exclusivity invariant guarantees this) at every level,
 // so a back-filled `$uuid` doesn't change the hash. Two are exceptions, because
 // they are content rather than identity:
@@ -103,7 +103,7 @@ function stripSigils(value) {
     // encoding rather than the reference made the folder's hash unreproducible.
     //
     // `refLeaf` (uwx/folder.js) emits `$ref: <the record's $id>` — the pool position
-    // `<dirs>/<slug>` — while the record is brand-new, and `entry: { model, entity:
+    // `<dirs>/<slug>` — while the record is brand-new, and `entry: { schema, entity:
     // <uuid> }` once it has been minted.
     // Both denote the same record. A push hashes the folder BEFORE submitting, then
     // back-fills the minted `$uuid` into every record's source file — so the very
@@ -205,8 +205,10 @@ function encodeFieldValue(value, field, sourceLocale, translations) {
  * @param {string} [params.sourceLocale]   - locale for localized-field wrap
  * @param {object} [params.translations]   - `{ locale: { hash: tgt } }` for wrapping
  *        localized scalar fields per-locale (from loadLocaleTranslations)
- * @returns {{ entities: object[], warnings: string[] }} each entity is
- *   `{ id, uuid, model, file, document }` — `document` is the section-keyed body.
+ * @returns {{ entities: object[], warnings: string[], refusals: string[] }} each
+ *   entity is `{ id, uuid, model, file, document }` — `document` is the section-keyed
+ *   body. `refusals` names the records that cannot be sent as written, one line
+ *   each; a caller that sends must not send while any is present.
  */
 export function recordsToEntities({
   label,
@@ -259,6 +261,14 @@ export function recordsToEntities({
       if (!fieldByKey.has(key)) fieldByKey.set(key, field)
     }
   }
+  // Every section by name, single or list — to recognize a record written BY SECTION
+  // (`details: { title: … }`), the shape docs/reference/entity-content.md gives a
+  // sections-form record. This mapper reads a record's fields from the top of its
+  // file, so such a record is refused below rather than sent without them.
+  const sectionNames = new Set(sectionEntries.map(([name]) => name))
+  const listSections = new Set(
+    sectionEntries.filter(([, s]) => s && s.multiple === true).map(([name]) => name)
+  )
 
   // The markdown body of a `.md` record is the value of the Model's CONTENT body
   // field — a markup `text` field (raw source string) or a `format: prosemirror`
@@ -276,6 +286,8 @@ export function recordsToEntities({
 
   const entities = []
   const warnings = []
+  // Records that cannot be sent as written — see the ⛔ at the end of the loop.
+  const refusals = []
   if (contentMatches.length > 1) {
     warnings.push(
       `${label}: ${declaration.name} has more than one content ` +
@@ -299,7 +311,7 @@ export function recordsToEntities({
     // only the fallback for a record that did not arrive that way.
     //
     // The qualification is a CONSTRAINT, not a style: the sync response is keyed per
-    // (`$model`, `$id`), so a bare slug would collide whenever two schema folders
+    // (`$schema`, `$id`), so a bare slug would collide whenever two schema folders
     // resolving to one Model reuse one (see the duplicate check). ⇒ Do not describe this
     // value as "the slug" — the folder leaf's `name` is the bare segment, and
     // conflating the two has already misdirected a naming decision.
@@ -326,31 +338,74 @@ export function recordsToEntities({
       }
       if (Object.keys(data).length) sectionData[secName] = data
     }
-    // Warn for author keys not on ANY record section. A real unknown key means the
-    // frontmatter doesn't match the collection's data schema — that SHOULD warn
-    // (only identity/transport keys in SKIP_KEYS are silent).
+    // Author keys on no record section (only identity/transport keys in SKIP_KEYS are
+    // exempt). A key naming a SECTION is not unknown: the record is written by
+    // section, refused below.
+    const bySection = []
+    const undeclared = []
     for (const key of Object.keys(record)) {
       if (SKIP_KEYS.has(key) || fieldByKey.has(key)) continue
-      warnings.push(
-        `${label}/${slug}: field "${key}" is not on ` +
-          `${declaration.name} — not synced`
+      if (sectionNames.has(key)) bySection.push(key)
+      else undeclared.push(key)
+    }
+
+    // ⛔ A RECORD THE BACKEND WOULD REFUSE — OR WOULD STORE EMPTY — IS REFUSED HERE,
+    // before anything is sent. Two cases are visible from here, and the second is only
+    // checked when the first does not already explain it:
+    //   - a record written by section, whose sections' contents this mapper cannot
+    //     send (it reads fields from the top of the file). Sent, it arrives with an
+    //     empty brief: refused when the brief has a `required` field, and otherwise
+    //     STORED EMPTY, in silence — so this stays whatever the backend does with a
+    //     refusal;
+    //   - a `required` field the send would lack — the brief is always sent, another
+    //     single section only when the record fills it. The backend refuses it too,
+    //     but names the field, not the file.
+    // Measured 2026-09-23: a record written by section went up with an empty brief and
+    // the lane was refused — and the refused lane left the folder's entries and
+    // entities with no data behind, so every later push of the site's records was
+    // refused. The backend's push has been one transaction since 2026-09-24; a refusal
+    // now writes nothing.
+    // ⛔ And what a push cannot carry is refused too, because it is lost twice over: the
+    // backend never receives it, and the next pull writes the file without it — an
+    // undeclared key (`tags:` beside a schema with no `tags`), or a markdown body where
+    // the schema has no field to hold it. Both were warnings until 2026-09-24
+    // ("not synced"), and a pull then deleted the value from the author's file.
+    if (undeclared.length) {
+      const one = undeclared.length === 1
+      refusals.push(
+        `${label}/${slug}: ${quoted(undeclared)} ${one ? 'is not a field' : 'are not fields'} of ` +
+          `${declaration.name} — a push cannot carry ${one ? 'it' : 'them'}, and the next pull would ` +
+          `drop ${one ? 'it' : 'them'} from the file. Declare ${one ? 'it' : 'them'} in the schema, ` +
+          `or remove ${one ? 'it' : 'them'}.`
       )
     }
     if (hasBody && !bodyTarget) {
-      warnings.push(
-        `${label}/${slug}: markdown body present but ` +
-          `${declaration.name} has no content body field — body not synced`
+      refusals.push(
+        `${label}/${slug}: the file has a markdown body, and ${declaration.name} has no field for ` +
+          'it (a `markdown` or `richtext` field) — a push cannot carry it. Add one to the schema, ' +
+          'or move the text into a field.'
       )
     }
+    if (bySection.length) {
+      refusals.push(sectionShapeRefusal(`${label}/${slug}`, bySection, listSections, declaration.name))
+    } else {
+      const missing = missingRequired(recordSections, sectionData, briefName)
+      if (missing.length) {
+        refusals.push(
+          `${label}/${slug}: ${declaration.name} requires ${listOf(missing)}, and this record ` +
+            `has no value for ${missing.length === 1 ? 'it' : 'them'}.`
+        )
+      }
+    }
 
-    // The `$`-document, in canonical key order: `$uuid?`, `$id`, `$model`, `$disabled?`,
+    // The `$`-document, in canonical key order: `$uuid?`, `$id`, `$schema`, `$disabled?`,
     // then each populated section in declared order (the brief always present as the
     // card). `$owner`/`$unit`/`$meta` are omitted — the backend binds owner + unit on
     // its side.
     const document = {}
     if (uuid) document.$uuid = uuid
     document.$id = id
-    document.$model = declaration.name
+    document.$schema = declaration.name
     // ⭐ A DRAFT IS SENT AS A DISABLED ENTITY: it stays in the folder and is never
     // publicly delivered. Only `true` travels. An absent key means enabled [Diego,
     // 2026-09-21], so a record whose `draft: true` is removed is sent without the key
@@ -373,7 +428,51 @@ export function recordsToEntities({
       document,
     })
   }
-  return { entities, warnings }
+  return { entities, warnings, refusals }
+}
+
+// "a", "a and b", "a, b and c" — items are already formatted.
+function listOf(items) {
+  if (items.length <= 1) return items.join('')
+  return `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`
+}
+
+const quoted = (keys) => listOf(keys.map((k) => `"${k}"`))
+
+// Why a record written by section cannot be sent, and what to do about each kind of
+// section it names: a single section's fields can move to the top of the file; a
+// list section has no file form a push can send.
+function sectionShapeRefusal(where, keys, listSections, modelName) {
+  const singles = keys.filter((k) => !listSections.has(k))
+  const lists = keys.filter((k) => listSections.has(k))
+  const one = keys.length === 1
+  let message =
+    `${where}: ${quoted(keys)} ${one ? 'is a section' : 'are sections'} of ${modelName}, and a ` +
+    `push reads a record's fields from the top of its file — what ${one ? 'it holds' : 'they hold'} ` +
+    'would not be sent.'
+  if (singles.length) message += ` Move the fields of ${quoted(singles)} up a level.`
+  if (lists.length) {
+    message +=
+      ` ${quoted(lists)} ${lists.length === 1 ? 'holds' : 'hold'} a list, which a push cannot ` +
+      'send from a file yet.'
+  }
+  return message
+}
+
+// The `required` fields a record's send would lack. The brief is always sent; another
+// single section only when the record fills it, so an empty one is not checked. A
+// field counts as present when the send carries a value for it (`null` is none).
+function missingRequired(recordSections, sectionData, briefName) {
+  const missing = []
+  for (const [secName, sec] of recordSections) {
+    const data = sectionData[secName]
+    if (secName !== briefName && !data) continue
+    for (const [key, field] of Object.entries(sec.fields || {})) {
+      if (field?.required !== true || data?.[key] != null) continue
+      missing.push(secName === briefName ? `"${key}"` : `"${key}" (section "${secName}")`)
+    }
+  }
+  return missing
 }
 
 // Post-pass: override a collection record's localized CONTENT body with a per-locale
@@ -544,7 +643,7 @@ function resolveDeclaration(schema, modelName) {
  * (e.g. site-content) into one sync package. First sync sends no `$uuid` (the
  * backend mints); re-sync round-trips the back-filled `$uuid`. Throws on an
  * unresolvable EXPLICIT Model, an invalid `records/folder.yml`, or a duplicate
- * ($model, $id) within the submission.
+ * ($schema, $id) within the submission.
  *
  * @param {string} siteRoot - directory containing site.yml
  * @param {object} [opts]
@@ -558,8 +657,9 @@ function resolveDeclaration(schema, modelName) {
  *        Defaults to the site's foundation's (`siteSelfScope`); a caller that has it
  *        already passes it, so one emit reads it once.
  * @returns {Promise<{ entities: object[], index: object[], warnings: string[],
- *   schemaless: Array<{name: string, model: string}>, colConfig: object,
- *   folder: object, recordsDirExists: boolean }>}
+ *   refusals: string[], schemaless: Array<{name: string, model: string}>,
+ *   colConfig: object, folder: object, recordsDirExists: boolean }>}
+ *   `refusals` — records that cannot be sent as written (`recordsToEntities`).
  *   `schemaless` lists the QUERIES whose schema resolved to nothing (the
  *   convention-default soft-skip) — their records are not pushed as entities, and
  *   the composite deploy delivers those queries statically instead.
@@ -597,6 +697,7 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
     throw new Error(`uwx/records: ${recordsCfg.file} is invalid —\n  ${folder.errors.join('\n  ')}`)
   }
   const warnings = [...pool.errors, ...folder.warnings]
+  const refusals = []
 
   const colConfig = opts.queriesConfig || (await resolveQueriesConfig(siteRoot))
   const queries = siteQueries(colConfig.declarations)
@@ -606,6 +707,7 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
       entities: [],
       index: [],
       warnings,
+      refusals,
       schemaless: [],
       colConfig,
       folder: { ...folder, nodes: [] },
@@ -657,7 +759,7 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
   // ⭐ Resolving BEFORE `declarationFor` is what keeps this to one line of behaviour:
   // `resolveDeclaration` already matches a fully-qualified name against the
   // foundation's `@/`-keyed `dataSchemas`, so a resolved name looks up correctly and
-  // `declaration.name` — the value that becomes `$model` — is the resolved one.
+  // `declaration.name` — the value that becomes `$schema` — is the resolved one.
   //
   // ⛔ The rule lives in `./self-scope.js`, shared with the `queries` Section
   // (`site.js::queriesNested`): a query's `schema` must name exactly the Model
@@ -740,7 +842,7 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
   const producedBy = new Map()
   // Schemas (as written) whose Model resolved to nothing — soft-skipped.
   const unresolved = new Set()
-  // The sync response is keyed per ($model, $id), so the pair must be unique
+  // The sync response is keyed per ($schema, $id), so the pair must be unique
   // within one submission.
   const seen = new Set()
 
@@ -821,14 +923,14 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
       const dupKey = `${e.model} ${e.id}`
       if (seen.has(dupKey)) {
         throw new Error(
-          `uwx/records: duplicate ($model, $id) in one sync — "${e.id}" of ` +
+          `uwx/records: duplicate ($schema, $id) in one sync — "${e.id}" of ` +
             `${e.model} comes from more than one record. Each record in a schema ` +
             'folder needs its own slug; make the slugs unique.'
         )
       }
       seen.add(dupKey)
       // The verb back-fills the minted `$uuid` into this source file, matched
-      // back from the finalized response by ($model, $id).
+      // back from the finalized response by ($schema, $id).
       const src = sourceBySlug.get(e.slug)
       index.push({
         id: e.id,
@@ -843,16 +945,13 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
         ownId: ownIds.get(e.slug) ?? null,
         format: src ? src.format : null,
         multiRecord: src ? src.multiRecord : false,
-        // The Model declaration, so the back-fill can render the finalized
-        // document → authoring shape (variant A): unwrap localized fields, route
-        // the content body field to the md body, drop the brief record `$uuid`.
-        declaration,
         // Sent disabled, so the back-fill can check that the backend kept it that way.
         draft: e.document.$disabled === true,
       })
     }
     entities.push(...mappedOut.entities)
     warnings.push(...mappedOut.warnings)
+    refusals.push(...mappedOut.refusals)
   }
 
   // Queries whose schema resolved to nothing — not pushed as entities. The composite
@@ -903,6 +1002,7 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
     entities,
     index,
     warnings,
+    refusals,
     schemaless,
     colConfig,
     folder: { ...folder, nodes },
@@ -968,11 +1068,11 @@ export function filterChanged(entities, index, { priorHashes = {}, sendAll = fal
  * @param {object} [opts] - buildRecordEntities opts, plus `priorHashes`,
  *        `sendAll`, `exporter`, `exportedAt`.
  * @returns {Promise<{ buffer: Buffer|null, models: string[], entityCount: number,
- *        warnings: string[], index: object[], hashes: Object<string,string>,
- *        skipped: number }>}
+ *        warnings: string[], refusals: string[], index: object[],
+ *        hashes: Object<string,string>, skipped: number }>}
  */
 export async function emitRecordSyncPackage(siteRoot, opts = {}) {
-  const { entities, index, warnings, recordsDirExists } = await buildRecordEntities(siteRoot, opts)
+  const { entities, index, warnings, refusals, recordsDirExists } = await buildRecordEntities(siteRoot, opts)
   if (entities.length === 0) {
     throw new Error(
       'uwx/records: no records to export — ' +
@@ -989,7 +1089,7 @@ export async function emitRecordSyncPackage(siteRoot, opts = {}) {
 
   const sentModels = [...new Set(sendEntities.map((e) => e.model))]
   if (sendEntities.length === 0) {
-    return { buffer: null, models: sentModels, entityCount: 0, warnings, index: [], hashes, skipped }
+    return { buffer: null, models: sentModels, entityCount: 0, warnings, refusals, index: [], hashes, skipped }
   }
 
   const buffer = emitEntitySyncPackage({
@@ -1000,5 +1100,5 @@ export async function emitRecordSyncPackage(siteRoot, opts = {}) {
     exportedAt: opts.exportedAt,
   })
 
-  return { buffer, models: sentModels, entityCount: sendEntities.length, warnings, index: sendIndex, hashes, skipped }
+  return { buffer, models: sentModels, entityCount: sendEntities.length, warnings, refusals, index: sendIndex, hashes, skipped }
 }

package/src/uwx/self-scope.js

@@ -9,7 +9,7 @@
 //
 // ⭐ ONE RULE FOR EVERY PATH THAT SHIPS A REF FROM ONE PUBLISH, and its inverse:
 //
-//   - a record's `$model`             `records.js::buildRecordEntities`
+//   - a record's `$schema`            `records.js::buildRecordEntities`
 //   - a query's `schema`              `site.js::queriesNested` (the `queries` Section)
 //   - the author's spelling, on pull  `records-project.js` (placement and declarations)
 //

package/src/uwx/site.js

@@ -850,7 +850,7 @@ export function isSiteRelativeExtensionUrl(decl) {
  * @param {Object<string,string>} [uuids] `name` → backend `$uuid`, from a push
  *        response or a pull. Absent on a first sync, where minting is correct.
  * @param {string} [org] the publish org. A foundation-relative `schema` (`@/x`)
- *        is qualified with it (`./self-scope.js`), exactly as the records' `$model`
+ *        is qualified with it (`./self-scope.js`), exactly as the records' `$schema`
  *        is — see the note at the `schema` line below.
  */
 // ⛔ KEYS THAT MUST NOT REACH THE WIRE. Everything else on an authored declaration
@@ -930,7 +930,7 @@ function queriesNested(declarations, uuids = null, scope = null) {
     // the runtime fetches it from (never the records service).
     const source = d.path ? { path: d.path } : d.url !== undefined ? externalSource(d) : d.source
     setIf(data, 'source', source)
-    // ⛔ QUALIFIED, WITH THE SAME RULE AND THE SAME SCOPE AS THE RECORDS' `$model`
+    // ⛔ QUALIFIED, WITH THE SAME RULE AND THE SAME SCOPE AS THE RECORDS' `$schema`
     // (`records.js::buildRecordEntities`) — the site's foundation's. A consumer
     // answers a query by matching this name against the Models its records were
     // stored under, so a verbatim `@/member` beside records stored as `@acme/member`
@@ -1242,7 +1242,7 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
  *        `siteSelfScope`; pass the scope the records are emitted with. With none
  *        known, `@/x` ships as written.
  * @returns {Promise<object>} the section-keyed `$`-document:
- *        `{ $uuid?, $id, $model, info, settings?, pages, layout_sections, extensions,
+ *        `{ $uuid?, $id, $schema, info, settings?, pages, layout_sections, extensions,
  *        queries, services?, secrets? }`
  */
 export async function siteProjectToDocument(siteRoot, opts = {}) {
@@ -1518,7 +1518,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // config (the records themselves are separate entities; this is just the config).
   const colConfig = await resolveQueriesConfig(siteRoot, { siteYml })
 
-  // `$uuid?` then `$id` `$model`, then sections in Model-declared order.
+  // `$uuid?` then `$id` `$schema`, then sections in Model-declared order.
   const doc = {}
   // ⭐ From `sync.json`, keyed by the backend this document is being produced FOR.
   // It was `site.yml::$uuid` — one scalar with no way to say which backend minted it.
@@ -1529,7 +1529,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
     (opts.backend ? readBackendState(siteRoot, opts.backend).site?.uuid : undefined)
   if (entityUuid) doc.$uuid = entityUuid
   doc.$id = SITE_ENTITY_KEY // one site-content entity per project (stable handle)
-  doc.$model = SITE_MODEL_NAME
+  doc.$schema = SITE_MODEL_NAME
   doc.info = info
   // Emitted only when the file declares something — see `settingsNested`.
   const settings = settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translations })
@@ -1594,7 +1594,7 @@ export async function emitSiteSyncPackage(siteRoot, opts = {}) {
     entities: [
       {
         id: document.$id,
-        model: document.$model,
+        model: document.$schema,
         file: 'entities/site-content.json',
         document,
       },

package/src/uwx/sync-package.js

@@ -71,7 +71,7 @@ function emitLane(entities, exporter, exportedAt, extraModels = []) {
   return { buffer, entityCount: entities.length, models }
 }
 
-// Collect the Models referenced by the folder's `ref` leaves (`entry.model`), walking
+// Collect the Models referenced by the folder's `ref` leaves (`entry.schema`), walking
 // the contents/$children tree. The folder is built from the FULL record set, so it
 // references every record's Model — including records the send-only-changed filter
 // drops from THIS package (a re-push where the folder changed but the records didn't).
@@ -79,7 +79,7 @@ function emitLane(entities, exporter, exportedAt, extraModels = []) {
 // ride even when their record entities don't.
 function collectReferencedModels(node, acc) {
   if (!node || typeof node !== 'object') return acc
-  if (node.entry && typeof node.entry.model === 'string') acc.add(node.entry.model)
+  if (node.entry && typeof node.entry.schema === 'string') acc.add(node.entry.schema)
   for (const key of ['$children', 'contents']) {
     if (Array.isArray(node[key])) for (const child of node[key]) collectReferencedModels(child, acc)
   }
@@ -251,9 +251,13 @@ function rewriteEntityAssets(node, map, ids, noStamp = null) {
  * @returns {Promise<{
  *   siteContent: { buffer, entityCount, index, models }|null,
  *   records: { buffer, entityCount, index, models }|null,
- *   hashes: Object<string,string>, warnings: string[], skipped: number,
- *   schemaless: Array<{name: string, model: string}>, localAssets: string[],
- *   applied: object }>}
+ *   hashes: Object<string,string>, warnings: string[], refusals: string[],
+ *   skipped: number, schemaless: Array<{name: string, model: string}>,
+ *   localAssets: string[], applied: object }>}
+ *   `refusals` names the records that cannot be sent as written, one line each
+ *   (`records.js::recordsToEntities`). A caller that submits must not submit while
+ *   any is present: the backend would refuse the records lane — or, for a record
+ *   written by section whose brief requires nothing, store it empty.
  *   `schemaless` lists queries that resolved no data schema (soft-skipped from
  *   the sync) — the composite deploy delivers these statically via the data ball.
  *   `localAssets` lists the site-root local media refs (`/images/x.png`) the deploy
@@ -277,7 +281,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   const exportedAt = opts.exportedAt
   refuseOrgOption(opts, 'emitSyncPackages')
   // ⭐ ONE SCOPE FOR THE WHOLE EMIT — the site's foundation's, the one `register`
-  // stored its Models under — so a record's `$model` and a query's `schema` are
+  // stored its Models under — so a record's `$schema` and a query's `schema` are
   // qualified alike. Read once here and handed to both. ⛔ It was the org that owns
   // the SITE until 2026-09-22 (`self-scope.js`).
   const scope =
@@ -446,7 +450,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   const localAssets = [...localAssetSet]
 
   const siteEntity = siteDoc
-    ? { id: siteDoc.$id, model: siteDoc.$model, file: 'entities/site-content.json', document: siteDoc }
+    ? { id: siteDoc.$id, model: siteDoc.$schema, file: 'entities/site-content.json', document: siteDoc }
     : null
 
   // One hash map over every entity (both lanes) — the sync-cache the caller persists.
@@ -519,6 +523,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
 
   return {
     siteContent, records, siteContentUuid, hashes, warnings, skipped,
+    refusals: col.refusals || [],
     schemaless: col.schemaless, localAssets, applied,
     // { stamped, unknown } when identity was applied; null when the caller passed
     // no map. `unknown > 0` with `stamped === 0` on a site that has been pushed

package/src/validate-data.js

@@ -31,15 +31,17 @@ import { YAML_OPTIONS } from './utils/yaml-schema.js'
 import { queryNameFromUrl, declaredKeys, fillDeclaredKeys, fetchLevels, pageRouteQuery } from '@uniweb/core'
 import { parentRouteOf } from '@uniweb/core/route-match'
 
-import { validateItem, isStaticallyCheckable, validateBound } from '@uniweb/schemas/conform'
-import { validateAndNormalizeSchema } from './resolve-data-schema.js'
+import { validateItem, isStaticallyCheckable, validateBound, flatRecordFields } from '@uniweb/schemas/conform'
+import { validateAndNormalizeSchema, buildDataSchemaMap } from './resolve-data-schema.js'
 
 // The pure checker, re-exported so `@uniweb/build/validate` stays the one import
 // path callers know (`uniweb validate`, the CLI, and the contract tests all
 // reach it here) even though the implementation moved next to the vocabulary.
 export { validateItem, isStaticallyCheckable } from '@uniweb/schemas/conform'
 import { buildSchema } from './schema.js'
-import { resolveRecordsDir } from './site/entity-pool.js'
+import { resolveRecordsDir, readEntityPool, groupPoolBySchema } from './site/entity-pool.js'
+import { readEntityFile } from './uwx/entity-source.js'
+import { isContentBodyField } from './uwx/data-schema.js'
 import { toFetchList } from './site/data-fetcher.js'
 import { resolveFoundationSrcPath } from './utils/foundation-source-root.js'
 import { collectSiteContent } from './site/content-collector.js'
@@ -195,8 +197,11 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
         const schema = dataSchemas[ref]
         if (!schema) continue // build guarantees refs resolve; defensive skip
 
+        // ⭐ A sections-form schema is checked like any other now (`isStaticallyCheckable`,
+        // 2026-09-24) — a record can be flat or written by section. What is left out is a
+        // schema whose ROOT IS A LIST: it describes a whole value, not one record.
         if (!isStaticallyCheckable(schema)) {
-          deferred.push({ route: page.route, section: type, key, reason: 'rich sections-form schema', ref })
+          deferred.push({ route: page.route, section: type, key, reason: 'its root is a list, not a record', ref })
           continue
         }
 
@@ -215,6 +220,8 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
   const violations = []
   const schemasSeen = new Set()
   let recordCount = 0
+  // (schema, slug) of every record this pass checked, so pass 5 checks the rest.
+  const checkedRecords = new Set()
 
   for (const entry of work.values()) {
     const { records, error } = await resolveRecords(entry.path, { byQuery, siteRoot })
@@ -227,6 +234,7 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
     const items = Array.isArray(records) ? records : [records]
     items.forEach((item, idx) => {
       recordCount++
+      if (item && typeof item.slug === 'string') checkedRecords.add(recordKey(entry.ref, item.slug))
       for (const finding of validateItem(entry.schema, item)) {
         violations.push({
           file: entry.path,
@@ -253,6 +261,16 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
   for (const ref of blocks.schemas) schemasSeen.add(ref)
   recordCount += blocks.checked
 
+  // Pass 5 — every record file no section's binding reached, against the data schema
+  // its folder names. ⭐ The set a push sends: every file in the records directory is
+  // a record and every record is pushed, whether or not a section reads it — and
+  // until 2026-09-24 one that no section read was never checked here.
+  const files = await validateRecordFiles(siteRoot, { srcDir, dataSchemas, paths: config.paths, checked: checkedRecords })
+  violations.push(...files.violations)
+  setupErrors.push(...files.setupErrors)
+  for (const ref of files.schemas) schemasSeen.add(ref)
+  recordCount += files.checked
+
   return {
     violations,
     deferred,
@@ -266,6 +284,69 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
   }
 }
 
+const recordKey = (ref, slug) => `${ref}\u0000${slug}`
+
+/**
+ * Check the records in the records directory that pass 2 did not, each against the
+ * data schema its folder names (`records/member/` → `@/member`).
+ *
+ * A record is read the way a push reads it (`uwx/entity-source.js`), and a markdown
+ * record's body is the value of its schema's content body field unless its
+ * frontmatter sets one — which is what a push sends it as (`uwx/records.js`).
+ *
+ * A folder whose schema resolves to nothing is left out in silence: its records are
+ * schema-less, delivered as files, and the push says so itself.
+ *
+ * @returns {Promise<{ violations: object[], setupErrors: object[], schemas: Set<string>, checked: number }>}
+ */
+async function validateRecordFiles(siteRoot, { srcDir, dataSchemas, paths, checked }) {
+  const out = { violations: [], setupErrors: [], schemas: new Set(), checked: 0 }
+  const pool = await readEntityPool(siteRoot, { dir: resolveRecordsDir(siteRoot, paths).rel })
+  for (const [ref, entities] of groupPoolBySchema(pool.entities)) {
+    const schema = await schemaForRecords(ref, { srcDir, dataSchemas })
+    if (!schema || !isStaticallyCheckable(schema)) continue
+    for (const pooled of entities) {
+      let records
+      try {
+        records = await readEntityFile(pooled.absPath)
+      } catch (err) {
+        out.setupErrors.push({ file: pooled.relPath, message: err.message, users: [] })
+        continue
+      }
+      for (const r of records) {
+        if (!r.slug || checked.has(recordKey(ref, r.slug))) continue
+        out.checked++
+        out.schemas.add(ref)
+        for (const finding of validateItem(schema, withBody(schema, r))) {
+          out.violations.push({ file: pooled.relPath, schema: ref, item: r.slug, users: [], ...finding })
+        }
+      }
+    }
+  }
+  return out
+}
+
+// The schema a records folder names — the one a section binds if any does, else
+// resolved the way every other ref is. Null when nothing resolves.
+async function schemaForRecords(ref, { srcDir, dataSchemas }) {
+  if (dataSchemas[ref]) return dataSchemas[ref]
+  try {
+    return (await buildDataSchemaMap([ref], { srcDir }))[ref] || null
+  } catch {
+    return null
+  }
+}
+
+// A record as a push sends it: a markdown body fills the schema's content body field
+// when the frontmatter does not set it.
+function withBody(schema, r) {
+  const record = { ...(r.data || {}) }
+  if (typeof r.body !== 'string' || r.body.trim() === '') return record
+  const key = Object.entries(flatRecordFields(schema) || {}).find(([, f]) => isContentBodyField(f))?.[0]
+  if (key && record[key] === undefined) record[key] = r.body
+  return record
+}
+
 /**
  * Check each ```md:<tag> concept block against `@std/<tag>`, when that schema
  * exists.