@uniweb/build 0.72.0 → 0.73.1

package/src/uwx/records-project.js

@@ -48,7 +48,10 @@ import { folderYmlPath } from '../site/records-config.js'
 import { contentBodyTarget } from './record-layout.js'
 import { unresolveSelfScope, resolveSelfScope, ownSchemaNames, refuseOrgOption } from './self-scope.js'
 import { parseCatalogRef } from '../site/foundation-ref.js'
-import { unwrapLocalized, renderEntityDocument } from './backfill.js'
+import { renderEntityDocument } from './backfill.js'
+import { labelForFile } from '../site/entry-label.js'
+import { LINK_MODEL, writeLinkRecords } from './link-records.js'
+import { FILE_MODEL, filesToPull } from './file-records.js'
 import { parseBibtex } from '@citestyle/bibtex'
 import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations } from './locale-sync.js'
 import { buildFreeformRecordPath } from '../i18n/freeform.js'
@@ -161,6 +164,13 @@ export function indexFolder(folderDoc) {
         const uuid = typeof node.entry === 'object' ? node.entry.entity : node.entry
         const schema = typeof node.entry === 'object' ? node.entry.schema : undefined
         if (uuid) byUuid.set(uuid, { folderPath, slug: node.name, schema })
+      } else if (node?.kind === 'link' && typeof node.$uuid === 'string' && node.$uuid) {
+        // ⭐ A link entry is a record of `@uniweb/link`, its identity the item's own
+        // (`./link-records.js`).
+        byUuid.set(node.$uuid, { folderPath, slug: node.name, schema: LINK_MODEL })
+      } else if (node?.kind === 'file' && typeof node.$uuid === 'string' && node.$uuid) {
+        // …and a file entry one of `@uniweb/file` (`./file-records.js`).
+        byUuid.set(node.$uuid, { folderPath, slug: node.name, schema: FILE_MODEL })
       }
     }
   }
@@ -522,25 +532,30 @@ export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceL
       if (!node || typeof node !== 'object') continue
       if (node.kind === 'branch') {
         const entry = { folder: node.name }
-        // Only a BRANCH takes a label. A record carries its own title; the folder
-        // does not caption its rows. On the wire the label is a localized map;
-        // folder.yml carries the source-locale string (a bare string passes).
-        if (node.label !== undefined) entry.label = unwrapLocalized(node.label, sourceLocale)
+        // A folder's label, as a record entry's below: on the wire a map of languages;
+        // in folder.yml the source language's text alone, or every language the label
+        // holds when it holds another (`entry-label.js`, 2026-09-28). ⛔ This kept the
+        // source language's text only until then, and said only a branch takes a label —
+        // a record's entry has taken one since 2026-09-27.
+        const folderLabel = labelForFile(node.label, sourceLocale)
+        if (folderLabel !== null) entry.label = folderLabel
         if (Array.isArray(node.tags) && node.tags.length) entry.tags = node.tags.map(String)
         entry.records = walk(node.$children, true)
         out.push(entry)
         continue
       }
-      const uuid = node.entry?.entity ?? node.entry
+      // A link or file entry is its own record — its identity is the item's (`./link-records.js`,
+      // `./file-records.js`).
+      const uuid = node.kind === 'link' || node.kind === 'file' ? node.$uuid : node.entry?.entity ?? node.entry
       const rel = typeof uuid === 'string' ? poolPathByUuid.get(uuid) : null
       // ⭐ What the folder says about the record — its entry's `tags` and `label` — comes
       // back as the entry `{ path, tags?, label? }` (ruled 2026-09-27 [Diego]).
       const said = {}
       if (Array.isArray(node.tags) && node.tags.length) said.tags = node.tags.map(String)
-      if (node.label !== undefined && node.label !== null) {
-        const label = unwrapLocalized(node.label, sourceLocale)
-        if (typeof label === 'string' && label) said.label = label
-      }
+      // Every language the label holds (`entry-label.js`, 2026-09-28) — ⛔ the source
+      // language's alone until then, so a translated label lost the rest on a round trip.
+      const label = labelForFile(node.label, sourceLocale)
+      if (label !== null) said.label = label
       const says = Object.keys(said).length > 0
       // A record at the top of the folder needs no line unless the folder says something
       // about it — but one that did not land is still said: the next push sends the folder
@@ -768,6 +783,27 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
   //
   // The folder ENTITY still carries no `$uuid` we persist: the backend owns the
   // site's folder, keyed by the site-content uuid.
+  // ⭐ THE FOLDER'S LINK ENTRIES, written as their record files (`./link-records.js`) — before the
+  // folder, which places them by the files they land in. ⛔ Until 2026-09-28 a pull could not write
+  // one, and warned that a push from here would remove it.
+  const linked = writeLinkRecords({ folderDoc, recordsRoot, ownIdByTheirs })
+  for (const [theirs, rel] of linked.pathByUuid) poolPathByUuid.set(theirs, rel)
+  Object.assign(learned, linked.learned)
+  placed.push(...linked.placed)
+  updated.push(...linked.updated)
+  unchanged.push(...linked.unchanged)
+  warnings.push(...linked.warnings)
+  // ⭐ AND ITS FILE ENTRIES (`./file-records.js`): where each file lands in `records/uniweb/file/`,
+  // placed like any record — the bytes are the CLI's to fetch (`fileDownloads`), as it fetches media.
+  const pulledFiles = filesToPull({
+    folderDoc,
+    recordsRoot,
+    fileMap: backendState.files || {},
+    assetMap: backendState.assets || {},
+  })
+  for (const [theirs, rel] of pulledFiles.pathByUuid) poolPathByUuid.set(theirs, rel)
+  warnings.push(...pulledFiles.warnings)
+
   const records = folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceLocale })
   warnings.push(...records.warnings)
   for (const path of keptBib) {
@@ -782,6 +818,13 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
   if (opts.backend && Object.keys(learned).length) {
     updateBackendMap(siteRoot, opts.backend, 'records', learned)
   }
+  if (opts.backend && Object.keys(pulledFiles.learned).length) {
+    updateBackendMap(siteRoot, opts.backend, 'files', pulledFiles.learned)
+  }
 
-  return { updated, placed, unchanged, skipped, warnings, locales, freeform, records: records.status, recordsFile: records.file }
+  return {
+    updated, placed, unchanged, skipped, warnings, locales, freeform, records: records.status, recordsFile: records.file,
+    // The file records' bytes to fetch — `{ url, path, poolPath }` each (`./file-records.js`).
+    fileDownloads: pulledFiles.downloads,
+  }
 }

package/src/uwx/records.js

@@ -67,6 +67,8 @@ import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
 import { localizeScalar, localizeScalarList, localizeContentDoc, loadLocaleTranslations, discoverLocales, discoverFreeformLocales, localesDir, isLocalizedContent } from './locale-sync.js'
 import { loadFreeformRecord } from '../i18n/freeform.js'
 import { isDraftRecord } from '../site/record-draft.js'
+import { LINK_MODEL, linkRecordRefusal } from './link-records.js'
+import { FILE_MODEL } from './file-records.js'
 
 const DATE_KINDS = new Set(['date', 'datetime'])
 // The record's OWN keys — identity and transport, never a field of any section, never
@@ -907,9 +909,11 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
       colConfig,
       folder: { ...folder, nodes: [] },
       recordsDirExists: pool.exists,
-      sendFolder: sendsFolder(pool, []),
+      sendFolder: sendsFolder(pool, [], []),
       declarations: new Map(),
       keyTyped: new Map(),
+      links: [],
+      files: [],
     }
   }
 
@@ -1073,7 +1077,64 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
   // (`self-scope.js::unresolveSelfScope`), and a push then reported only a name two
   // records share.
   const fileByOwnId = new Map()
+
+  // ⭐ A LINK RECORD IS A FOLDER ENTRY, NEVER AN ENTITY (`@uniweb/link`, 2026-09-28 —
+  // `./link-records.js`). Its file holds its `url` and its own `$uuid`; the push sends it as an
+  // item of the folder, `{ kind: 'link', name, url }`, under the uuid this backend holds it by
+  // (`recordMap`), or none on its first push. Placed like any record, so `folder.yml` gives its
+  // label and tags.
+  const links = []
+  const linkNames = new Map() // slug → the file that gave it, so two files cannot claim one name
+  for (const pooled of poolBySchema.get(LINK_MODEL) || []) {
+    const produced = []
+    for (const r of await readEntityFile(pooled.absPath)) {
+      const where = r.multiRecord ? `${pooled.relPath} (${r.slug})` : pooled.relPath
+      const refusal = linkRecordRefusal(r, where)
+      if (refusal) {
+        refusals.push(refusal)
+        continue
+      }
+      const first = linkNames.get(r.slug)
+      if (first) {
+        refusals.push(`${pooled.relPath}: a link named "${r.slug}" is also ${first} — a link is named by its file, so each needs its own name.`)
+        continue
+      }
+      linkNames.set(r.slug, pooled.relPath)
+      const id = [...pooled.dirs, r.slug].join('/')
+      const ownId = typeof r.data?.$uuid === 'string' && r.data.$uuid ? r.data.$uuid : null
+      links.push({
+        id,
+        slug: r.slug,
+        url: r.data.url.trim(),
+        ownId,
+        uuid: ownId ? recordMap[ownId] ?? null : null,
+        sourceFile: r.multiRecord ? null : r.sourceFile ?? pooled.absPath,
+      })
+      produced.push({ id, slug: r.slug })
+    }
+    producedBy.set(pooled.id, produced)
+  }
+
+  // ⭐ A FILE RECORD IS A FOLDER ENTRY OF KIND `file`, NEVER AN ENTITY (`@uniweb/file`, 2026-09-28 —
+  // `./file-records.js`). The file itself is the record; nothing in it is read. Its identity is the
+  // uuid this backend holds its entry by, banked per backend by the file's path (`sync.json` `files`).
+  const files = []
+  const fileMap = opts.backend ? readBackendState(siteRoot, opts.backend).files || {} : {}
+  for (const pooled of poolBySchema.get(FILE_MODEL) || []) {
+    const id = [...pooled.dirs, pooled.slug].join('/')
+    files.push({
+      id,
+      slug: pooled.slug,
+      name: pooled.file,
+      absPath: pooled.absPath,
+      poolPath: pooled.poolPath,
+      uuid: fileMap[pooled.poolPath] ?? null,
+    })
+    producedBy.set(pooled.id, [{ id, slug: pooled.slug }])
+  }
+
   for (const [schema, poolEntities] of poolBySchema) {
+    if (schema === LINK_MODEL || schema === FILE_MODEL) continue
     const label = poolEntities[0].dirs.join('/')
     const modelName = modelFor(schema, `${pool.dir}/${label}/`)
     const declaration = (await declarationFor(modelName)) || (await typedFor(schema))
@@ -1196,9 +1257,10 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
     refusals.push(...mappedOut.refusals)
   }
 
-  // Queries whose schema resolved to nothing — not pushed as entities. The composite
-  // deploy delivers these statically (the "data ball") instead, so the caller can
-  // route them there.
+  // Queries whose schema resolved to nothing — not pushed as entities. Their compiled
+  // data is delivered as static files instead (`site/schemaless-data.js`), so the caller
+  // can route it there; and their declarations are sent naming no Model
+  // (`site.js::queriesNested`).
   //
   // ⛔ Deliberately NOT a `warnings` string. This is a product decision the author
   // is making — entities or static files — and it needs to be reported at a
@@ -1210,9 +1272,10 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
   for (const { name, decl } of queries) {
     const schema = decl.schema || decl.model
     const hasRecords = poolBySchema.has(schema)
-    const resolved = hasRecords
+    // A query over link records names a system Model, which resolves whatever the foundation holds.
+    const resolved = schema === LINK_MODEL || schema === FILE_MODEL || (hasRecords
       ? !unresolved.has(schema)
-      : Boolean((await declarationFor(modelFor(schema, `query "${name}"`))) || (await typedFor(schema)))
+      : Boolean((await declarationFor(modelFor(schema, `query "${name}"`))) || (await typedFor(schema))))
     if (!resolved) {
       if (decl.schemaExplicit) throw unresolvedExplicit(resolveSelfScope(schema, scope), name)
       schemaless.push({ name, model: resolveSelfScope(schema, scope) })
@@ -1249,13 +1312,17 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
     colConfig,
     folder: { ...folder, nodes },
     recordsDirExists: pool.exists,
-    sendFolder: sendsFolder(pool, entities),
+    sendFolder: sendsFolder(pool, entities, [...links, ...files]),
     // Each entity's declaration, by its Model — what walks a record's lists
     // (`record-items.js`).
     declarations: new Map(readSchemas.map(({ declaration }) => [declaration.name, declaration])),
     // A name-defaulted schema that stands for the type of the data key of its name
     // (`@/team` → `@/member`) — see `typedFor` above.
     keyTyped,
+    // The link records, sent as folder entries rather than entities (`./link-records.js`).
+    links,
+    // The file records, likewise (`./file-records.js`).
+    files,
   }
 }
 
@@ -1269,9 +1336,9 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
 // holds only files that are not records (warned). Neither is an author emptying
 // the folder, and sending one would remove the backend's records — including any
 // authored there — for a state nobody chose. Inert instead, like no directory.
-function sendsFolder(pool, entities) {
+function sendsFolder(pool, entities, links = []) {
   if (!pool.exists) return false
-  if (entities.length > 0) return true
+  if (entities.length > 0 || links.length > 0) return true
   return pool.entities.length === 0 && pool.errors.length === 0
 }
 

package/src/uwx/site-project.js

@@ -387,7 +387,7 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
  * Project one section `$`-record (from `page_sections` / `layout_sections`) to a
  * section `.md` file — the inverse of site.js `mapSectionData`. Frontmatter is
  * `type` + `hidden` + the flat `params` (`background` and `theme` among them) +
- * the data declaration (`params.fetch`, else the `fetch` field) + `id` (`stable_id`);
+ * the data declaration (`params.fetch`) + `id` (`stable_id`);
  * the body is the section's content serialized to markdown. Idempotent.
  *
  * Note: `$children` (a section's child sections) are NOT written here — the page
@@ -406,10 +406,11 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
 export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, freeformRelPath, freeformCandidates = null, writeId = true, context = null }) {
   // ⛔ A stored `preset` or `input` is not written back: neither has an effect, and the build
   // would only warn about it (2026-09-27).
-  // ⛔ No `background` / `theme_override` / `insets`: the site-content Model dropped all three
-  // (2026-09-28), with a stored background and theme copied into `params`. Until then a field
-  // filled in where `params` lacked the key, and a stored `insets[]` was re-inlined into the body.
-  const { type, stable_id, hidden, params, content, fetch } = record || {}
+  // ⛔ No `background` / `theme_override` / `insets` / `fetch`: the site-content Model dropped all
+  // four from a section (2026-09-28), with a stored background, theme and data declaration copied
+  // into `params`. Until then a field filled in where `params` lacked the key, and a stored
+  // `insets[]` was re-inlined into the body. (A PAGE's `fetch` is its own field — `pageRecordToYml`.)
+  const { type, stable_id, hidden, params, content } = record || {}
 
   // A localized `content` field unwraps to the source-locale doc for the body; its
   // target-locale structural maps are captured into the locales/ collector, and any
@@ -429,11 +430,9 @@ export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED
   // Invert the build's resolution rather than copy it — see fetch-shapes.js. A new
   // file gets `query:` for a declaration of names alone; a section that declares
   // its data locally keeps it (`writeSectionFile`, the declaration keys).
-  // ⭐ From `params.fetch` when present — where a section carries its data since 2026-09-28 —
-  // else the stored field.
-  const ownFetch = paramFetch !== undefined ? paramFetch : fetch
-  if (ownFetch !== undefined) {
-    const { key, value } = authorableDeclaration(ownFetch)
+  // ⭐ From `params.fetch` — where a section carries its data since 2026-09-28.
+  if (paramFetch !== undefined) {
+    const { key, value } = authorableDeclaration(paramFetch)
     frontmatter[key] = value
   }
   // `id:` only where the file's name does not already give it (`writeId`, `pageSectionsToFiles`).

package/src/uwx/site.js

@@ -1037,7 +1037,7 @@ function externalSource(d) {
   return source
 }
 
-function queriesNested(declarations, uuids = null, scope = null, keyTyped = null, queryFields = null) {
+function queriesNested(declarations, uuids = null, scope = null, keyTyped = null, queryFields = null, schemaless = null) {
   const out = []
   for (const [name, d] of Object.entries(declarations)) {
     refuseUnder(d.where, `queries.${name}`)
@@ -1058,7 +1058,14 @@ function queriesNested(declarations, uuids = null, scope = null, keyTyped = null
     // names that type — the data schema its records are sent as (`data-key-types.js`).
     const typed = (!d.schemaExplicit && keyTyped?.get(d.schema)) || null
     const schema = typed || d.schema
-    setIf(data, 'schema', resolveSelfScope(schema, scope))
+    // ⛔ NO MODEL FOR A QUERY WHOSE RECORDS RESOLVED NONE (`schemaless`, decided by the records
+    // lane — `records.js`). Its name-defaulted `schema` names a Model nothing declares, its records
+    // are not pushed, and its compiled data travels as static files — so the declaration goes up
+    // with no `schema`. ⛔ Until 2026-09-28 it named that Model anyway (`videos` → `@std/videos`),
+    // and a store that checks a query's `schema` against the site's declared types refused the
+    // whole content push for it. An explicit `schema:` that does not resolve never reaches here:
+    // the records lane refuses it.
+    if (!schemaless?.has(name)) setIf(data, 'schema', resolveSelfScope(schema, scope))
     // ⭐ …AND SAYS SO, so a pull can tell the author's form (`team:`, no schema) from an explicit
     // one — sent only where the deployment's `queries` Section declares the key (`GET /dev/config`
     // → `siteContent.queryFields`), since one that does not refuses a push carrying it.
@@ -1377,6 +1384,8 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
  *        resolves into (`@/x` → `@scope/x`): the site's foundation's. Defaults to
  *        `siteSelfScope`; pass the scope the records are emitted with. With none
  *        known, `@/x` ships as written.
+ * @param {string[]} [opts.schemaless] - the queries whose records resolved no data schema
+ *        (the records lane's `schemaless`): their declarations name no `schema`.
  * @returns {Promise<object>} the section-keyed `$`-document:
  *        `{ $uuid?, $id, $schema, info, settings?, pages, layout_sections, extensions,
  *        queries, services?, secrets? }`
@@ -1688,7 +1697,14 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // ⚠️ `queriesNested` keeps its name. §2's rule: rename what an author or a
   // consumer sees, leave the identifier alone.
   const scope = opts.scope !== undefined ? opts.scope : await siteSelfScope(siteRoot)
-  doc.queries = queriesNested(colConfig.declarations, opts.queryUuids, scope, opts.keyTyped, opts.queryFields)
+  doc.queries = queriesNested(
+    colConfig.declarations,
+    opts.queryUuids,
+    scope,
+    opts.keyTyped,
+    opts.queryFields,
+    Array.isArray(opts.schemaless) ? new Set(opts.schemaless) : null
+  )
   // Emitted ONLY when the file declares the key — see the header above
   // `serviceRecords`: on a replaced Section, absent and empty are different
   // requests and one of them is destructive.

package/src/uwx/sync-package.js

@@ -22,6 +22,7 @@
 import { buildRecordEntities, entityContentHash } from './records.js'
 import { recordItemLists, hasListItems, stampRecordItems } from './record-items.js'
 import { ASSET_SLOTS } from '@uniweb/semantic-parser'
+import { fileRecordUploads } from './file-records.js'
 import { buildFolderEntity } from './folder.js'
 import { siteProjectToDocument } from './site.js'
 import { siteSelfScope, refuseOrgOption } from './self-scope.js'
@@ -255,7 +256,7 @@ function rewriteEntityAssets(node, map, ids, noStamp = null) {
  * @param {object} [opts.exporter] @param {string} [opts.exportedAt]
  * @returns {Promise<{
  *   siteContent: { buffer, entityCount, index, models }|null,
- *   records: { buffer, entityCount, index, models }|null,
+ *   records: { buffer, entityCount, index, models, links }|null,
  *   hashes: Object<string,string>, warnings: string[], refusals: string[],
  *   skipped: number, schemaless: Array<{name: string, model: string}>,
  *   localAssets: string[], applied: object, namesNew: string[],
@@ -314,8 +315,16 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
 
   // The folder rides over the FULL record set (before filtering) so its references
   // are complete — new records by `$ref`, already-minted ones by `entry: <uuid>`.
+  // ⭐ File records ride the folder as entries too, their value an asset: the push writes an upload
+  // key where each URL goes, uploads the files (`localFiles`), and its second emit swaps the keys for
+  // serve URLs and stamps the assets' identity beside them, as it does media (`./file-records.js`).
+  const { values: fileValues, uploads: localFiles } = await fileRecordUploads({ files: col.files || [], siteRoot })
+  const files = (col.files || []).map((f) => ({ ...f, value: fileValues.get(f.poolPath) }))
   const folder = buildFolderEntity({
     recordEntities: col.entities,
+    // Link records ride the folder as entries of their own kind (`./link-records.js`).
+    links: col.links || [],
+    files,
     ...(sourceLocale ? { sourceLocale } : {}),
     // ⭐ Every record in the directory, at the top of the folder or in the
     // sub-folder `folder.yml` places it in — and NOTHING when there is no folder to
@@ -359,6 +368,8 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
         // …and the same data schema, where a name stands for the type of its data key
         // (`@/team` → `@/member`, `data-key-types.js`): decided once, by the records.
         keyTyped: col.keyTyped,
+        // …and which queries resolved NO data schema — their declarations go up naming none.
+        schemaless: col.schemaless.map((q) => q.name),
         // …and whether this deployment takes the key that says so (`siteContent.queryFields`) —
         // and the page and `settings` keys that carry Open Graph texts per language.
         ...(Array.isArray(opts.queryFields) ? { queryFields: opts.queryFields } : {}),
@@ -447,6 +458,8 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     // recognizes on pull by fingerprint (asset-map.js → `servedFingerprint`).
     if (siteDoc) rewriteEntityAssets(siteDoc, assetRewrite, assetIds, siteDoc.info)
     for (const e of col.entities) rewriteEntityAssets(e.document, assetRewrite, assetIds)
+    // The folder too: a file entry's value names its asset by an upload key until here.
+    if (folder) rewriteEntityAssets(folder.document, assetRewrite, assetIds)
   }
   // Collect the site-root local refs the deploy must upload (`/images/x.png`).
   // Co-located refs (`./x`, `../x`) need the source `.md` location to resolve — the
@@ -560,7 +573,9 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     // filtered out here by send-only-changed. Declare them all (the backend rejects a
     // folder that references an undeclared Model).
     const referencedModels = [...collectReferencedModels(folder.document, new Set())]
-    records = { ...emitLane(entities, exporter, exportedAt, referencedModels), index }
+    // `links` rides beside the index: the caller banks each link's uuid from the folder the
+    // backend returns (`link-records.js::backfillLinkUuids`).
+    records = { ...emitLane(entities, exporter, exportedAt, referencedModels), index, links: col.links || [], files: col.files || [] }
   }
 
   // --- site-content lane -------------------------------------------------------
@@ -607,6 +622,9 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     namesNew,
     refusals,
     schemaless: col.schemaless, localAssets, applied,
+    // The files a push uploads for its file records, each `{ ref, path, contentType }` — the file, and
+    // a PDF's preview. Uploaded through the media lane; `ref` is the key the second emit rewrites.
+    localFiles,
     // { 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
     // before is the index-loss signature the backend refuses — the caller reports it.

package/src/uwx/sync-store.js

@@ -48,7 +48,7 @@ const VERSION = 1
  * `recordItems` is keyed by a record's uuid here, each entry that record's list items
  * (`record-items.js`) — replaced whole, one record at a time.
  */
-const MAP_SECTIONS = new Set(['records', 'items', 'queries', 'folders', 'assets', 'recordItems'])
+const MAP_SECTIONS = new Set(['records', 'items', 'queries', 'folders', 'assets', 'recordItems', 'files'])
 
 const storePath = (siteDir) => join(siteDir, SYNC_STORE_FILE)
 

package/src/validate-data.js

@@ -365,6 +365,14 @@ async function validateRecordFiles(siteRoot, { srcDir, dataSchemas, keyTypes = n
     names.set(ref, known)
     if (ref !== folderRef) names.set(folderRef, known)
     for (const pooled of entities) {
+      // ⭐ A FILE RECORD'S FILE IS ITS VALUE, never its data (`site/file-records.js`): nothing in it
+      // is read, so there is nothing to check — only its name, which a reference may give.
+      // ⛔ Until 2026-09-28 its bytes were parsed as YAML here, and every push of a site holding a
+      // PDF warned "directives end mark is expected".
+      if (pooled.fileRecord) {
+        known.add(String(pooled.slug))
+        continue
+      }
       let records
       try {
         records = await readEntityFile(pooled.absPath)