@uniweb/build 0.72.0 → 0.73.1

package/src/site/records-config.js

@@ -47,6 +47,11 @@ import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { compareByNumericPrefix } from '../utils/numeric-prefix.js'
 import { RECORDS_DIR, FOLDER_YML, resolveRecordsDir } from './entity-pool.js'
+import { readLabel } from './entry-label.js'
+
+// What a label may be, for every message that refuses one.
+const LABEL_FORMS =
+  "A label is the entry's display text: one text, or one per language (`label: { en: …, fr: … }`)."
 
 export { FOLDER_YML }
 
@@ -276,13 +281,15 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
       }
       if (tags.length) said.tags = tags
     }
+    // ⭐ One text — the site's default language — or one text per language, `{ en: …, fr: … }`
+    // (`entry-label.js`, 2026-09-28).
     if (entry.label !== undefined && entry.label !== null) {
-      if (typeof entry.label !== 'string' && typeof entry.label !== 'number') {
-        errors.push(`${file}: ${where} has a \`label:\` that is not text. A label is the entry's display text.`)
+      const read = readLabel(entry.label)
+      if (read.error) {
+        errors.push(`${file}: ${where} has a \`label:\` that ${read.error}. ${LABEL_FORMS}`)
         return null
       }
-      const label = String(entry.label).trim()
-      if (label) said.label = label
+      if (read.label !== null) said.label = read.label
     }
     return said
   }
@@ -371,7 +378,14 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
       }
       folderAt.set(at, where)
       const branch = { kind: 'branch', name: segment }
-      if (entry.label !== undefined && entry.label !== null) branch.label = String(entry.label)
+      if (entry.label !== undefined && entry.label !== null) {
+        const read = readLabel(entry.label)
+        if (read.error) {
+          errors.push(`${file}: folder "${segment}" (${where}) has a \`label:\` that ${read.error}. ${LABEL_FORMS}`)
+          return []
+        }
+        if (read.label !== null) branch.label = read.label
+      }
       // A folder takes `tags:` as a record's entry does — kept, sent and pulled back, though
       // no question answers a folder.
       if (entry.tags !== undefined && entry.tags !== null) {

package/src/uwx/entity-source.js

@@ -73,7 +73,8 @@ export async function readEntityFile(filepath) {
 async function readOneFile(filepath) {
   const ext = extname(filepath).toLowerCase()
   const format = formatFor(ext)
-  const slugFromName = basename(filepath, ext)
+  // Cut as written, as the pool names it (`site/entity-pool.js`) — `ext` is lowercased.
+  const slugFromName = basename(filepath, extname(filepath))
   const raw = await readFile(filepath, 'utf-8')
 
   if (format === 'md') {

package/src/uwx/file-records.js

@@ -0,0 +1,178 @@
+// ⭐ A FILE RECORD IS A FOLDER ENTRY OF KIND `file`, NEVER AN ENTITY — `@uniweb/file` (2026-09-28).
+//
+// On the file side the file itself is the record (`site/file-records.js`): any file in
+// `records/uniweb/file/`, named by its stem, its label and tags on its `folder.yml` entry. On the wire
+// a backend holds it as an item of the site's `@uniweb/folder`:
+//
+//     { kind: 'file', name, file: { url, name, mime, size, preview?, assetId, assetExt, … }, label?, tags?, $uuid? }
+//
+// — its value an ASSET: the file goes up through the asset lane the site's media use (owned by the
+// site), and the push writes the serve URL and the asset's identity where the upload key stood,
+// exactly as it does for media (`sync-package.js::rewriteEntityAssets`).
+//
+// ⭐ ITS IDENTITY is the entry's `$uuid`. A file cannot carry it, so the CLI banks it per backend in
+// `sync.json`, keyed by the file's path in the records directory (`files`): a renamed file is a new
+// record, as a renamed record file's name is a new name.
+
+import { existsSync, mkdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { labelOnWire } from '../site/entry-label.js'
+import { FILE_RECORD_DIRS } from '../site/entity-pool.js'
+import { fileRecordValue, makeFilePreview, mimeFor } from '../site/file-records.js'
+
+export { FILE_MODEL } from '../site/file-records.js'
+
+/** The key a push writes where a file record's URL goes, until its upload maps it to the serve URL. */
+export const fileUploadKey = (poolPath) => `records/${poolPath}`
+/** …and where its preview's goes. */
+export const previewUploadKey = (poolPath) => `records/${poolPath}.preview.webp`
+
+/**
+ * Each file record's value as a push first writes it — upload keys where the URLs go — and the files
+ * the push uploads for them: the file, and a PDF's preview made into `.uniweb/file-previews/`.
+ *
+ * @param {object} params
+ * @param {Array<{ poolPath: string, name: string, absPath: string }>} params.files
+ * @param {string} params.siteRoot
+ * @returns {Promise<{ values: Map<string, object>, uploads: Array<{ ref: string, path: string, contentType: string }> }>}
+ *   `values` by pool path
+ */
+export async function fileRecordUploads({ files = [], siteRoot }) {
+  const values = new Map()
+  const uploads = []
+  for (const f of files) {
+    const previewPath = join(siteRoot, '.uniweb', 'file-previews', `${f.poolPath}.preview.webp`)
+    mkdirSync(dirname(previewPath), { recursive: true })
+    const hasPreview = (await makeFilePreview(f.absPath, previewPath)) && existsSync(previewPath)
+    values.set(
+      f.poolPath,
+      fileRecordValue({
+        absPath: f.absPath,
+        name: f.name,
+        url: fileUploadKey(f.poolPath),
+        ...(hasPreview ? { preview: previewUploadKey(f.poolPath) } : {}),
+      })
+    )
+    uploads.push({ ref: fileUploadKey(f.poolPath), path: f.absPath, contentType: mimeFor(f.name) })
+    if (hasPreview) uploads.push({ ref: previewUploadKey(f.poolPath), path: previewPath, contentType: 'image/webp' })
+  }
+  return { values, uploads }
+}
+
+/**
+ * A file entry as the wire carries it.
+ *
+ * @param {{ slug: string, uuid?: string|null, value: object }} file
+ * @param {{ label?: *, tags?: string[] }} node - its placement
+ * @param {string} sourceLocale
+ */
+export function fileLeaf(file, node, sourceLocale) {
+  const leaf = { kind: 'file', name: file.slug, file: { ...file.value } }
+  if (file.uuid) leaf.$uuid = file.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 file entry in a folder document.
+ *
+ * @param {object} folderDoc - `{ contents }`, nesting through `$children`
+ * @returns {object[]}
+ */
+export function fileItems(folderDoc) {
+  const out = []
+  const walk = (nodes) => {
+    for (const node of nodes || []) {
+      if (!node || typeof node !== 'object') continue
+      if (node.kind === 'branch') walk(node.$children)
+      else if (node.kind === 'file') out.push(node)
+    }
+  }
+  walk(folderDoc?.contents)
+  return out
+}
+
+/**
+ * After a push: the uuid the backend holds each file entry under, by the file's path — what the CLI
+ * banks in `sync.json` (`files`). Matched by name: a file record's name is its file's stem, and no
+ * two share one.
+ *
+ * @param {object} params
+ * @param {Array<{ slug: string, poolPath: string }>} params.files
+ * @param {object} params.folderDoc - the folder document the backend returned
+ * @returns {Object<string,string>} pool path → the backend's uuid
+ */
+export function bankedFileUuids({ files = [], folderDoc }) {
+  const bySlug = new Map(files.map((f) => [f.slug, f]))
+  const out = {}
+  for (const item of fileItems(folderDoc)) {
+    const file = bySlug.get(item.name)
+    if (file && typeof item.$uuid === 'string' && item.$uuid) out[file.poolPath] = item.$uuid
+  }
+  return out
+}
+
+/**
+ * A pull: where each file entry of the folder lands in `records/uniweb/file/`, and which files have
+ * to be fetched — a file the project already holds under that entry's identity is kept, one whose
+ * asset has changed is fetched again, and one it does not hold is fetched to `<its name>`.
+ *
+ * ⛔ A FILE OF THAT NAME HOLDING ANOTHER RECORD IS NOT WRITTEN OVER — reported, and left out.
+ *
+ * @param {object} params
+ * @param {object} params.folderDoc
+ * @param {string} params.recordsRoot - the records directory, absolute
+ * @param {Object<string,string>} [params.fileMap] - pool path → the backend's uuid (`sync.json` `files`)
+ * @param {Object<string,{ id: string }>} [params.assetMap] - upload key → the asset it last uploaded as
+ * @returns {{ pathByUuid: Map<string,string>, downloads: Array<{ url: string, path: string, poolPath: string, ref: string, assetId?: string, assetExt?: string }>, learned: Object<string,string>, warnings: string[] }}
+ *   a download's `ref` is the key its asset is recorded under (`sync.json` `assets`), as a push records it
+ */
+export function filesToPull({ folderDoc, recordsRoot, fileMap = {}, assetMap = {} }) {
+  const pathByTheirs = new Map(Object.entries(fileMap).map(([poolPath, theirs]) => [theirs, poolPath]))
+  const pathByUuid = new Map()
+  const downloads = []
+  const learned = {}
+  const warnings = []
+  for (const item of fileItems(folderDoc)) {
+    const theirs = typeof item.$uuid === 'string' && item.$uuid ? item.$uuid : null
+    const url = typeof item.file?.url === 'string' ? item.file.url : null
+    const fileName = fileNameFor(item)
+    if (!theirs || !url || !fileName) {
+      warnings.push(`the folder holds a file ("${item.name ?? '?'}") with no identity, url or name — not written.`)
+      continue
+    }
+    let poolPath = pathByTheirs.get(theirs) || null
+    const held = poolPath && existsSync(join(recordsRoot, ...poolPath.split('/')))
+    if (!held) {
+      poolPath = [...FILE_RECORD_DIRS, fileName].join('/')
+      const at = join(recordsRoot, ...poolPath.split('/'))
+      if (existsSync(at) && fileMap[poolPath] !== theirs) {
+        warnings.push(`${poolPath} holds another file than the folder's "${item.name}" — it was not written over.`)
+        continue
+      }
+    }
+    const path = join(recordsRoot, ...poolPath.split('/'))
+    const current = assetMap[fileUploadKey(poolPath)]?.id
+    if (!held || (item.file.assetId && current !== item.file.assetId)) {
+      downloads.push({
+        url,
+        path,
+        poolPath,
+        ref: fileUploadKey(poolPath),
+        ...(item.file.assetId ? { assetId: item.file.assetId, assetExt: item.file.assetExt || '' } : {}),
+      })
+    }
+    pathByUuid.set(theirs, poolPath)
+    learned[poolPath] = theirs
+  }
+  return { pathByUuid, downloads, learned, warnings }
+}
+
+/** The name a pulled file is written under: its value's `name`, else the entry's name and the asset's extension. */
+function fileNameFor(item) {
+  const named = typeof item.file?.name === 'string' ? item.file.name.trim() : ''
+  if (named && !named.includes('/') && !named.includes('\\') && !named.startsWith('.')) return named
+  const ext = typeof item.file?.assetExt === 'string' && item.file.assetExt ? `.${item.file.assetExt}` : ''
+  return typeof item.name === 'string' && item.name ? `${item.name}${ext}` : null
+}

package/src/uwx/folder.js

@@ -50,6 +50,10 @@
 // is keyed by the site's uuid on that backend, from `sync.json`). The framework
 // never holds a folder uuid.
 
+import { labelOnWire } from '../site/entry-label.js'
+import { linkLeaf } from './link-records.js'
+import { fileLeaf } from './file-records.js'
+
 export const FOLDER_MODEL_NAME = '@uniweb/folder'
 export const FOLDER_ENTITY_KEY = '@folder'
 
@@ -91,20 +95,34 @@ function refLeaf(entity) {
  * @param {Map<string, object>} byEntityId - record entities, keyed by pool id
  * @param {string[]} missing - collects ids that resolved to no entity
  */
-function contentsFromNodes(nodes, byEntityId, missing, sourceLocale) {
+function contentsFromNodes(nodes, byEntityId, missing, sourceLocale, byLinkId = new Map(), byFileId = new Map()) {
   const out = []
   for (const node of nodes || []) {
     if (node.kind === 'branch') {
       const branch = { kind: 'branch', name: node.name }
       // The display text is a LOCALIZED field on the wire — a `{ locale: value }`
-      // map, like every localized scalar this producer sends — keyed by the
-      // site's source locale.
-      if (node.label !== undefined) branch.label = { [sourceLocale]: String(node.label) }
+      // map, like every localized scalar this producer sends: every language the
+      // file gives, or the one text it gives as the site's source locale's
+      // (`entry-label.js`).
+      if (node.label !== undefined) branch.label = labelOnWire(node.label, sourceLocale)
       if (Array.isArray(node.tags) && node.tags.length) branch.tags = [...node.tags]
-      branch.$children = contentsFromNodes(node.$children, byEntityId, missing, sourceLocale)
+      branch.$children = contentsFromNodes(node.$children, byEntityId, missing, sourceLocale, byLinkId, byFileId)
       out.push(branch)
       continue
     }
+    // ⭐ A LINK RECORD IS AN ENTRY OF ITS OWN KIND, holding its data — never a ref to an entity
+    // (`./link-records.js`).
+    const link = byLinkId.get(node.$entityId)
+    if (link) {
+      out.push(linkLeaf(link, node, sourceLocale))
+      continue
+    }
+    // …and so is a file record, its value an asset (`./file-records.js`).
+    const file = byFileId.get(node.$entityId)
+    if (file) {
+      out.push(fileLeaf(file, node, sourceLocale))
+      continue
+    }
     const entity = byEntityId.get(node.$entityId)
     if (!entity) {
       missing.push(node.$entityId)
@@ -114,7 +132,7 @@ function contentsFromNodes(nodes, byEntityId, missing, sourceLocale) {
     // ⭐ What the folder says about the record (`records/folder.yml`, ruled 2026-09-27
     // [Diego]): its display text, localized as a branch's is, and its tags, in the order
     // written. A records service answers them beside the record as `$label` and `$tags`.
-    if (node.label !== undefined) leaf.label = { [sourceLocale]: String(node.label) }
+    if (node.label !== undefined) leaf.label = labelOnWire(node.label, sourceLocale)
     if (Array.isArray(node.tags) && node.tags.length) leaf.tags = [...node.tags]
     out.push(leaf)
   }
@@ -205,7 +223,13 @@ export function stampFolderItemUuids(doc, pathToUuid = {}) {
   let stamped = 0
   let unknown = 0
   const claimed = new Set()
+  // ⭐ An item that already carries its identity keeps it — a link entry's `$uuid` is its
+  // record's (`./link-records.js`) — and no other item may be stamped with it.
+  walkFolderItems(doc?.contents, (_at, item) => {
+    if (typeof item.$uuid === 'string' && item.$uuid) claimed.add(item.$uuid)
+  })
   walkFolderItems(doc?.contents, ({ path, unique, record }, item) => {
+    if (typeof item.$uuid === 'string' && item.$uuid) return
     let uuid = record ? pathToUuid[`@${record}`] : undefined
     if (!uuid && unique) uuid = pathToUuid[path]
     if (uuid && !claimed.has(uuid)) {
@@ -228,6 +252,10 @@ export function stampFolderItemUuids(doc, pathToUuid = {}) {
  * @param {object} params
  * @param {object[]} params.recordEntities - the record entities (full set, BEFORE
  *        send-only-changed filtering), each `{ id, uuid, slug, model }`
+ * @param {object[]} [params.links] - the link records, each `{ id, slug, url, uuid }` — sent as
+ *        entries of kind `link`, never as entities (`./link-records.js`)
+ * @param {object[]} [params.files] - the file records, each `{ id, slug, uuid, value }` — sent as
+ *        entries of kind `file`, their `value` an asset (`./file-records.js`)
  * @param {Array} params.folderNodes - the placed records: `folder.yml`'s sub-folders,
  *        then every record at the top
  * @param {boolean} [params.declared] - whether the records DIRECTORY exists. See below.
@@ -238,7 +266,7 @@ export function stampFolderItemUuids(doc, pathToUuid = {}) {
  *        keyed under on the wire
  * @returns {{ id, uuid, model, file, document, warnings }|null}
  */
-export function buildFolderEntity({ recordEntities, folderNodes = [], declared, itemUuids = null, sourceLocale = 'en' }) {
+export function buildFolderEntity({ recordEntities, links = [], files = [], folderNodes = [], declared, itemUuids = null, sourceLocale = 'en' }) {
   // ⛔ `missing` AND `empty` ARE DIFFERENT, AND THE ASYMMETRY IS DELIBERATE.
   //
   //   no records directory  → null. INERT: nothing is sent, and the backend's
@@ -256,9 +284,11 @@ export function buildFolderEntity({ recordEntities, folderNodes = [], declared,
 
   const byEntityId = new Map()
   for (const e of recordEntities || []) byEntityId.set(e.id, e)
+  const byLinkId = new Map((links || []).map((l) => [l.id, l]))
+  const byFileId = new Map((files || []).map((f) => [f.id, f]))
 
   const missing = []
-  const contents = contentsFromNodes(folderNodes, byEntityId, missing, sourceLocale)
+  const contents = contentsFromNodes(folderNodes, byEntityId, missing, sourceLocale, byLinkId, byFileId)
   // ⚠️ `id` IS THE RECORD'S PATH IN THE RECORDS DIRECTORY, NOT A FOLDER PATH — say
   // so, because the two read identically and a reader who takes it for a placement
   // concludes the emitter is dropping a branch it never had. *(Measured 2026-08-31:

package/src/uwx/index.js

@@ -188,3 +188,11 @@ export {
   writeRegisteredFoundation,
 } from '../site/registered-foundation.js'
 export { parseCatalogRef } from '../site/foundation-ref.js'
+
+// Link records — `@uniweb/link`: a file in `records/uniweb/link/` on the file side, a folder entry of
+// kind `link` on the wire, never an entity.
+export { LINK_MODEL, linkItems, backfillLinkUuids, writeLinkRecords, linkRecordRefusal } from './link-records.js'
+
+// File records — `@uniweb/file`: the file itself in `records/uniweb/file/` on the file side, a folder
+// entry of kind `file` on the wire, its value an asset.
+export { FILE_MODEL, fileItems, bankedFileUuids, filesToPull } from './file-records.js'

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)
+}