@uniweb/build 0.73.0 → 0.73.2

package/src/uwx/link-records.js

@@ -0,0 +1,233 @@
+// ⭐ A LINK RECORD IS A FOLDER ENTRY, NEVER AN ENTITY — `@uniweb/link` (2026-09-28).
+//
+// On the file side a link is a record like any other: a file in `records/uniweb/link/`, holding its
+// `url` (and, once it has reached a backend, its `$uuid`), placed in the folder by
+// `records/folder.yml`, which also gives its `label` and `tags` — they are its ENTRY's, not the
+// Model's. A static build compiles it like any record (`@uniweb/schemas/system`).
+//
+// On the wire a link is not an entity at all: a backend holds it as an item of the site's
+// `@uniweb/folder` of kind `link`, its data on the item — `{ kind: 'link', name, url, label?, tags? }`
+// — and the item's `$uuid` is the record's identity. A push that sent an entity of `@uniweb/link`
+// would be refused. So the push lowers each link record into such an entry (`folder.js`), the CLI
+// banks the uuid the backend gives it the way a record's is banked — in the file the first time,
+// mapped per backend after that — and a pull writes each link entry back as its file.
+//
+// `@uniweb/file` is not built: how a file reference is stored is still open.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { extname, join } from 'node:path'
+import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
+import { labelOnWire } from '../site/entry-label.js'
+import { poolDirsForSchema } from '../site/entity-pool.js'
+import { backfillUuid } from './backfill.js'
+
+export const LINK_MODEL = '@uniweb/link'
+
+/** Where link records live, below the records directory: `uniweb/link`. */
+export const LINK_DIRS = poolDirsForSchema(LINK_MODEL)
+
+/**
+ * Why a link record cannot be sent as written, or null when it can.
+ *
+ * @param {{ data?: object, body?: string }} record - a record as its file reader returns it
+ * @param {string} where - the file, for the message
+ * @returns {string|null}
+ */
+export function linkRecordRefusal(record, where) {
+  const data = record?.data && typeof record.data === 'object' ? record.data : {}
+  if (typeof record?.body === 'string' && record.body.trim()) {
+    return `${where}: a link record has no body — it holds its \`url\` alone.`
+  }
+  if (data.draft !== undefined) {
+    return (
+      `${where}: a link cannot be kept off a published site yet, so a draft link is not sent. ` +
+      `Remove \`draft:\` to send it, or the file to leave it out.`
+    )
+  }
+  const placement = ['label', 'tags'].filter((k) => data[k] !== undefined)
+  if (placement.length) {
+    const keys = placement.map((k) => `\`${k}:\``).join(' and ')
+    return (
+      `${where}: a link's ${keys} ${placement.length === 1 ? 'is' : 'are'} its folder entry's, not the ` +
+      `record's — give ${placement.length === 1 ? 'it' : 'them'} in records/folder.yml, on the entry ` +
+      `\`- path: ${LINK_DIRS.join('/')}/<file>\`.`
+    )
+  }
+  const extra = Object.keys(data).filter((k) => k !== 'url' && k !== '$uuid')
+  if (extra.length) {
+    return `${where}: a link record holds its \`url\` and nothing else — not ${extra.map((k) => `\`${k}:\``).join(', ')}.`
+  }
+  if (typeof data.url !== 'string' || !data.url.trim()) return `${where}: a link record needs a \`url\`.`
+  // ⭐ ABSOLUTE — a scheme and `://` — as a backend holds a link's url (`format: url`, 2026-09-28): a
+  // relative path or a `mailto:` is refused there, so it is refused here, before anything is sent.
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(data.url.trim())) {
+    return `${where}: a link's \`url\` is absolute — a scheme and \`://\`, like \`https://…\` — not "${data.url.trim()}".`
+  }
+  return null
+}
+
+/**
+ * A link entry as the wire carries it: `{ kind: 'link', name, url }`, with the uuid this backend
+ * holds it under, and the label and tags its placement gives.
+ *
+ * @param {{ slug: string, url: string, uuid?: string|null }} link
+ * @param {{ label?: *, tags?: string[] }} node - its placement (`records-config.js::resolveFolder`)
+ * @param {string} sourceLocale
+ */
+export function linkLeaf(link, node, sourceLocale) {
+  const leaf = { kind: 'link', name: link.slug, url: link.url }
+  if (link.uuid) leaf.$uuid = link.uuid
+  if (node?.label !== undefined) leaf.label = labelOnWire(node.label, sourceLocale)
+  if (Array.isArray(node?.tags) && node.tags.length) leaf.tags = [...node.tags]
+  return leaf
+}
+
+/**
+ * Every link entry in a folder document, with the branch it sits in.
+ *
+ * @param {object} folderDoc - `{ contents }`, nesting through `$children`
+ * @returns {Array<{ item: object, branch: string }>}
+ */
+export function linkItems(folderDoc) {
+  const out = []
+  const walk = (nodes, branch) => {
+    for (const node of nodes || []) {
+      if (!node || typeof node !== 'object') continue
+      if (node.kind === 'branch') walk(node.$children, branch ? `${branch}/${node.name}` : node.name)
+      else if (node.kind === 'link') out.push({ item: node, branch })
+    }
+  }
+  walk(folderDoc?.contents, '')
+  return out
+}
+
+/**
+ * After a push: the uuid the backend holds each link entry under, banked as a record's is.
+ *
+ * A link that has an own id maps it to this backend's uuid. A link with none — the first backend it
+ * reaches — takes that uuid as its own: it is written into the file, and the map is identity.
+ * Matched by name: a link's name is its file's, so no two links share one.
+ *
+ * @param {object} params
+ * @param {Array<{ slug: string, ownId: string|null, sourceFile: string|null }>} params.links
+ * @param {object} params.folderDoc - the folder document the backend returned
+ * @returns {{ mapped: Object<string,string>, updated: string[], warnings: string[] }}
+ */
+export function backfillLinkUuids({ links = [], folderDoc }) {
+  const bySlug = new Map(links.map((l) => [l.slug, l]))
+  const mapped = {}
+  const updated = []
+  const warnings = []
+  for (const { item } of linkItems(folderDoc)) {
+    const link = bySlug.get(item.name)
+    if (!link || typeof item.$uuid !== 'string' || !item.$uuid) continue
+    if (link.ownId) {
+      mapped[link.ownId] = item.$uuid
+      continue
+    }
+    if (!link.sourceFile) continue
+    const res = backfillUuid(link.sourceFile, item.$uuid)
+    if (res.status === 'error' || res.status === 'deferred') {
+      warnings.push(`${link.sourceFile}: ${res.message}`)
+      continue
+    }
+    if (res.status === 'updated') updated.push(link.sourceFile)
+    mapped[item.$uuid] = item.$uuid
+  }
+  return { mapped, updated, warnings }
+}
+
+/** A link file's `$uuid` and `url`, or null when it does not read as one. */
+function readLinkFile(path) {
+  try {
+    const text = readFileSync(path, 'utf8')
+    const data = extname(path).toLowerCase() === '.json' ? JSON.parse(text) : yaml.load(text, YAML_OPTIONS)
+    return data && typeof data === 'object' && !Array.isArray(data) ? data : null
+  } catch {
+    return null
+  }
+}
+
+const LINK_EXTENSIONS = ['.yml', '.yaml', '.json']
+
+/**
+ * A pull: each link entry of the folder written as its record file in `records/uniweb/link/` —
+ * `$uuid` (the link's own id) and `url` — the inverse of what a push sends.
+ *
+ * ⛔ A FILE OF THAT NAME HOLDING ANOTHER LINK IS NOT WRITTEN OVER: the entry is reported and left
+ * out, rather than one link taking another's file.
+ *
+ * @param {object} params
+ * @param {object} params.folderDoc
+ * @param {string} params.recordsRoot - the records directory, absolute
+ * @param {Map<string,string>} params.ownIdByTheirs - this backend's uuid → the record's own id
+ * @returns {{ pathByUuid: Map<string,string>, learned: Object<string,string>, placed: string[], updated: string[], unchanged: string[], warnings: string[] }}
+ *   `pathByUuid` — the backend's uuid → the file, relative to the records directory
+ */
+export function writeLinkRecords({ folderDoc, recordsRoot, ownIdByTheirs = new Map() }) {
+  const dir = join(recordsRoot, ...LINK_DIRS)
+  const pathByUuid = new Map()
+  const learned = {}
+  const placed = []
+  const updated = []
+  const unchanged = []
+  const warnings = []
+
+  // The link files already here, by own id.
+  const held = new Map()
+  const files = existsSync(dir)
+    ? readdirSync(dir).sort().filter((name) => !name.startsWith('_') && LINK_EXTENSIONS.includes(extname(name).toLowerCase()))
+    : []
+  for (const name of files) {
+    const data = readLinkFile(join(dir, name))
+    if (typeof data?.$uuid === 'string' && data.$uuid) held.set(data.$uuid, name)
+  }
+
+  for (const { item } of linkItems(folderDoc)) {
+    const theirs = typeof item.$uuid === 'string' && item.$uuid ? item.$uuid : null
+    if (!theirs || typeof item.name !== 'string' || !item.name || typeof item.url !== 'string') {
+      warnings.push(`the folder holds a link ("${item.name ?? '?'}") with no identity or no url — not written.`)
+      continue
+    }
+    const ownId = ownIdByTheirs.get(theirs) || theirs
+    let name = held.get(ownId)
+    let status
+    if (name) {
+      const path = join(dir, name)
+      const data = readLinkFile(path) || {}
+      if (data.url === item.url) {
+        status = 'unchanged'
+      } else {
+        writeLinkFile(path, { ...data, $uuid: ownId, url: item.url })
+        status = 'updated'
+      }
+    } else {
+      name = `${item.name}.yml`
+      const path = join(dir, name)
+      const there = existsSync(path) ? readLinkFile(path) : null
+      if (there) {
+        warnings.push(
+          `${[...LINK_DIRS, name].join('/')} holds another link than the folder's "${item.name}" — ` +
+            `it was not written over, and the folder's link was not written.`
+        )
+        continue
+      }
+      mkdirSync(dir, { recursive: true })
+      writeLinkFile(path, { $uuid: ownId, url: item.url })
+      status = 'placed'
+    }
+    const path = join(dir, name)
+    ;(status === 'placed' ? placed : status === 'updated' ? updated : unchanged).push(path)
+    pathByUuid.set(theirs, [...LINK_DIRS, name].join('/'))
+    learned[ownId] = theirs
+  }
+  return { pathByUuid, learned, placed, updated, unchanged, warnings }
+}
+
+function writeLinkFile(path, data) {
+  const { $uuid, url, ...rest } = data
+  const ordered = { ...($uuid ? { $uuid } : {}), url, ...rest }
+  const text = extname(path).toLowerCase() === '.json' ? JSON.stringify(ordered, null, 2) + '\n' : yaml.dump(ordered)
+  writeFileSync(path, text)
+}

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