@uniweb/build 0.59.1 → 0.61.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.59.1",
+  "version": "0.61.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -58,11 +58,11 @@
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
     "@uniweb/content-reader": "^1.2.5",
-    "@uniweb/schemas": "^0.4.0",
-    "@uniweb/theming": "^0.1.15",
     "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/projections": "^0.7.3"
+    "@uniweb/schemas": "^0.6.0",
+    "@uniweb/theming": "^0.1.15",
+    "@uniweb/projections": "^0.7.3",
+    "@uniweb/content-writer": "^0.3.4"
   },
   "optionalDependencies": {
     "@uniweb/runtime": "^0.27.4"

package/src/index.js

@@ -26,7 +26,6 @@ export {
 export {
   validateItem,
   validateDataInputs,
-  validateConceptBlocks,
   validateTaggedDataBlocks,
   isStaticallyCheckable,
 } from './validate-data.js'

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/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)