@uniweb/build 0.63.3 → 0.64.0

package/src/uwx/project-writer.js

@@ -16,7 +16,9 @@ import { randomBytes } from 'node:crypto'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { proseMirrorToMarkdown, serializeFrontmatter } from '@uniweb/content-writer'
+import { markdownToProseMirror } from '@uniweb/content-reader'
 import { parseFrontmatter } from './entity-source.js'
+import { canonicalJson, sameMarkdownDocument } from './same-content.js'
 import { renderEntityDocument } from './backfill.js'
 import { queriesYmlPath } from './queries-config.js'
 import { folderYmlPath } from '../site/records-config.js'
@@ -43,7 +45,7 @@ export const DEFAULT_RESERVED_FRONTMATTER = new Set([
 ])
 
 // js-yaml dump options shared by every config write, so output is byte-stable.
-const YAML_DUMP_OPTS = { lineWidth: -1, quotingType: "'", forceQuotes: false, noRefs: true }
+export const YAML_DUMP_OPTS = { lineWidth: -1, quotingType: "'", forceQuotes: false, noRefs: true }
 
 /**
  * Write `text` to `filePath` only when it differs from what's on disk, using a
@@ -164,9 +166,11 @@ function assembleSection(frontmatter, body) {
  * @param {object} [opts.content] - ProseMirror document for the body
  * @param {object} [opts.params] - incoming frontmatter params to merge
  * @param {Set<string>} [opts.reserved] - keys preserved when already present
+ * @param {object} [opts.implied] - `{ key: value }` a file means by leaving `key` out; an incoming
+ *        value equal to it is not written into an existing file that leaves the key out
  * @returns {'updated'|'unchanged'}
  */
-export function writeSectionFile({ filePath, content, params, reserved = DEFAULT_RESERVED_FRONTMATTER }) {
+export function writeSectionFile({ filePath, content, params, reserved = DEFAULT_RESERVED_FRONTMATTER, implied = null }) {
   let existing = ''
   try {
     existing = readFileSync(filePath, 'utf8')
@@ -185,15 +189,26 @@ export function writeSectionFile({ filePath, content, params, reserved = DEFAULT
       // how a newly-projected section gets its `type`/`nest`/etc.
       if (reserved.has(key) && key in frontmatter) continue
       if (reserved.has(key) && DECLARATION_KEYS.includes(key) && declaresLocally) continue
+      // A value the file implies by leaving the key out (`implied`) is not written into a file that
+      // exists — a new file has nothing to imply it with.
+      if (implied && existing && !(key in frontmatter) && implied[key] === value) continue
       if (value === null || value === undefined) delete nextFrontmatter[key]
       else nextFrontmatter[key] = value
     }
   }
 
-  const body = content ? proseMirrorToMarkdown(content) : (existingBody || '').replace(/^\n+/, '').replace(/\s+$/, '')
+  // ⭐ AN UNCHANGED BODY KEEPS THE AUTHOR'S OWN TEXT. A body that parses to the document the pull brought
+  // is not re-serialized: the writer's markdown differs from an author's in blank lines and line breaks,
+  // and a pull that changed nothing reformatted every section it touched (measured 2026-09-26 on the
+  // `marketing` template). A file with nothing to change is not written at all.
+  const authoredBody = (existingBody || '').replace(/^\n+/, '').replace(/\s+$/, '')
+  const keepsBody = Boolean(content && authoredBody) && sameMarkdownDocument(authoredBody, content)
+  if (keepsBody && canonicalJson(nextFrontmatter) === canonicalJson(frontmatter)) return 'unchanged'
+  const body = content && !keepsBody ? proseMirrorToMarkdown(content) : authoredBody
   return writeIfChanged(filePath, assembleSection(nextFrontmatter, body))
 }
 
+
 // Shallow-merge `changes` into a YAML config file and write idempotently. A key
 // whose value is null/undefined is deleted; an object value is shallow-merged one
 // level deep (so partial `theme` / `build` updates don't drop sibling keys) unless
@@ -202,12 +217,8 @@ export function writeSectionFile({ filePath, content, params, reserved = DEFAULT
 // config, but comment-preserving merges for hand-authored config files are a
 // quality bar to revisit.
 function mergeYamlConfig(filePath, changes, { replace = [] } = {}) {
-  let existing = {}
-  try {
-    existing = yaml.load(readFileSync(filePath, 'utf8'), YAML_OPTIONS) || {}
-  } catch {
-    // missing / invalid → start fresh
-  }
+  const prior = loadYamlFile(filePath)
+  const existing = isPlainObject(prior.value) ? { ...prior.value } : {}
   for (const [key, value] of Object.entries(changes)) {
     if (value === null || value === undefined) {
       delete existing[key]
@@ -216,13 +227,32 @@ function mergeYamlConfig(filePath, changes, { replace = [] } = {}) {
       // 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
+      const current = existing[key]
+      existing[key] = isPlainObject(current) ? { ...current, ...value } : value
     } else {
       existing[key] = value
     }
   }
-  return writeIfChanged(filePath, yaml.dump(existing, YAML_DUMP_OPTS))
+  return writeYamlIfChanged(filePath, existing, prior)
+}
+
+// A YAML file, parsed — and whether there was one: a missing or unreadable file is never "unchanged".
+function loadYamlFile(filePath) {
+  try {
+    return { value: yaml.load(readFileSync(filePath, 'utf8'), YAML_OPTIONS) ?? {}, read: true }
+  } catch {
+    return { value: {}, read: false }
+  }
+}
+
+// ⭐ A FILE WHOSE MEANING WOULD NOT CHANGE IS LEFT AS ITS AUTHOR WROTE IT. Every writer here re-dumps the
+// whole file — its comments dropped, its strings re-quoted, its lists reflowed — so a pull that restated
+// a file rewrote it all the same. ⛔ Until 2026-09-26 a pull into the copy that pushed it re-dumped
+// `site.yml`, `theme.yml` and every `page.yml` (measured on the `international` template: every comment
+// in its `site.yml` gone, and nothing had changed).
+function writeYamlIfChanged(filePath, value, prior) {
+  if (prior.read && canonicalJson(value) === canonicalJson(prior.value)) return 'unchanged'
+  return writeIfChanged(filePath, yaml.dump(value, YAML_DUMP_OPTS))
 }
 
 const isPlainObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v)
@@ -249,7 +279,7 @@ export function writeSiteConfig(siteRoot, config) {
  * @returns {'updated'|'unchanged'}
  */
 export function writeYamlFile(filePath, obj) {
-  return writeIfChanged(filePath, yaml.dump(obj || {}, YAML_DUMP_OPTS))
+  return writeYamlIfChanged(filePath, obj || {}, loadYamlFile(filePath))
 }
 
 /**
@@ -269,17 +299,17 @@ export function writeYamlFile(filePath, obj) {
  * @returns {'updated'|'unchanged'}
  */
 export function writeMergedYaml(filePath, projected, managedKeys) {
-  let existing = {}
-  try {
-    existing = yaml.load(readFileSync(filePath, 'utf8'), YAML_OPTIONS) || {}
-  } catch {
-    // missing / invalid → start fresh
+  const prior = loadYamlFile(filePath)
+  const existing = isPlainObject(prior.value) ? prior.value : {}
+  const managed = new Set(managedKeys)
+  // Each key where the file has it — a value the pull changes stays in its place — then the new ones.
+  const out = {}
+  for (const [key, value] of Object.entries(existing)) {
+    if (key in projected) out[key] = projected[key]
+    else if (!managed.has(key)) out[key] = value
   }
-  if (!existing || typeof existing !== 'object' || Array.isArray(existing)) existing = {}
-  const out = { ...existing }
-  for (const key of managedKeys) delete out[key]
-  Object.assign(out, projected)
-  return writeIfChanged(filePath, yaml.dump(out, YAML_DUMP_OPTS))
+  for (const [key, value] of Object.entries(projected)) if (!(key in out)) out[key] = value
+  return writeYamlIfChanged(filePath, out, prior)
 }
 
 /**
@@ -309,12 +339,31 @@ export function writeQueriesConfig(siteRoot, queries) {
   // `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.
+  //
+  // ⭐ WHEREVER THE AUTHOR DECLARED IT — `queries.yml`, or `site.yml`'s `queries:` block, which the
+  // build reads too, under it. ⛔ Until 2026-09-26 only `queries.yml` was consulted, so a site whose
+  // queries live in `site.yml` (the `international` template) got a `queries.yml` repeating every one
+  // of them on each pull, in the long form. A query that changed is written back where it lives.
+  let site = {}
+  try {
+    site = yaml.load(readFileSync(join(siteRoot, 'site.yml'), 'utf8'), YAML_OPTIONS) || {}
+  } catch {
+    // missing / invalid → nothing declared there
+  }
+  const inSite = isPlainObject(site.queries) ? site.queries : {}
   const changes = {}
+  const siteChanges = {}
   for (const [name, decl] of Object.entries(queries)) {
+    const inFile = isPlainObject(authored) && name in authored
+    if (!inFile && name in inSite) {
+      if (!restates(inSite[name], decl)) siteChanges[name] = decl
+      continue
+    }
     if (restates(authored?.[name], decl)) continue
     changes[name] = decl
   }
-  if (Object.keys(changes).length === 0) return 'unchanged'
+  if (Object.keys(siteChanges).length) writeSiteConfig(siteRoot, { queries: siteChanges })
+  if (Object.keys(changes).length === 0) return Object.keys(siteChanges).length ? 'updated' : '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`
@@ -330,11 +379,6 @@ function restates(authored, decl) {
   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
@@ -382,9 +426,40 @@ export function writeThemeFile(siteRoot, theme) {
  *        body (so a target-locale full-doc body is captured for locales/freeform/)
  * @param {(model: string, uuid: string) => string|null} [opts.refName] - the name a
  *        referenced record goes by, so a reference is written as that name
+ * @param {{ key: string }} [opts.context] - the record's identity, `<pool>/<handle>`, which
+ *        its translations are kept under — an entry that differs from record to record
+ *        comes back as `{ default, overrides }`
  * @returns {'updated'|'unchanged'}
  */
-export function writeRecordFile({ filePath, document, declaration, format, sourceLocale = 'en', collector, freeformRelPath, refName }) {
-  const text = renderEntityDocument({ document, declaration, format, sourceLocale, collector, freeformRelPath, refName })
+export function writeRecordFile({ filePath, document, declaration, format, sourceLocale = 'en', collector, freeformRelPath, refName, context = null }) {
+  const text = renderEntityDocument({ document, declaration, format, sourceLocale, collector, freeformRelPath, refName, context })
+  // ⭐ A record the pull did not change keeps the author's file — its key order, its blank lines, its
+  // quoting. ⛔ Until 2026-09-26 each one was re-rendered (measured on the `international` template).
+  let current = null
+  try {
+    current = readFileSync(filePath, 'utf8')
+  } catch {
+    // new file
+  }
+  if (current !== null && sameRecordText(current, text, format, filePath)) return 'unchanged'
   return writeIfChanged(filePath, text)
 }
+
+// Do two renderings of a record file say the same thing — the same data, and a body that parses to
+// the same document?
+function sameRecordText(a, b, format, filePath) {
+  try {
+    if (format === 'md') {
+      const x = parseFrontmatter(a, filePath)
+      const y = parseFrontmatter(b, filePath)
+      if (canonicalJson(x.frontmatter) !== canonicalJson(y.frontmatter)) return false
+      const bx = (x.body || '').trim()
+      const by = (y.body || '').trim()
+      return bx === by || sameMarkdownDocument(bx, markdownToProseMirror(by))
+    }
+    const parse = format === 'json' ? JSON.parse : (t) => yaml.load(t, YAML_OPTIONS)
+    return canonicalJson(parse(a)) === canonicalJson(parse(b))
+  } catch {
+    return false
+  }
+}

package/src/uwx/record-identity.js

@@ -0,0 +1,46 @@
+// ⭐ WHICH STORED RECORD EACH OF A COPY'S RECORDS IS — recovered from what the backend holds.
+//
+// A push sends a record with the uuid THIS backend minted for it: `sync.json`'s `records` map,
+// the record's own id (its file's `$uuid`) → theirs. A copy bound to the site whose map lost an
+// entry sends that record with none, and the backend mints a second entity for it — silently,
+// since a new record is never refused. The folder that places it is refused instead, because its
+// placements then carry no identity while the stored ones do (`identity_required`, measured
+// 2026-09-25 on a blog site whose binding held neither map).
+//
+// ⭐ MATCHED THE WAY A PULL PLACES THEM: a record whose own id IS a stored uuid is that record —
+// the first backend a record reaches mints the id its file keeps. Otherwise it is the stored
+// record the folder places under the same Model and slug. ⛔ A Model and slug two stored records
+// share names neither, and a stored record already mapped to another is not taken again: a wrong
+// match would overwrite a record the author did not edit, where no match only re-creates one.
+
+import { indexFolder } from './records-project.js'
+
+/**
+ * The stored uuid of each record the map does not name, where the backend's folder says which.
+ *
+ * @param {object} params
+ * @param {Array<{ ownId?: string|null, model?: string, slug?: string }>} params.index - the
+ *        records a push is about to send (`emitSyncPackages().records.index`)
+ * @param {Object<string,string>} [params.recordMap] - this backend's map: own id → its uuid
+ * @param {object} params.folderDoc - the backend's `@uniweb/folder` document for the site
+ * @returns {Object<string,string>} own id → the stored uuid, for the records recovered
+ */
+export function matchStoredRecords({ index, recordMap = {}, folderDoc }) {
+  const placed = indexFolder(folderDoc)
+  const byName = new Map()
+  for (const [theirs, { slug, schema }] of placed) {
+    if (!slug || !schema) continue
+    const key = `${schema} ${slug}`
+    byName.set(key, byName.has(key) ? null : theirs)
+  }
+  const taken = new Set(Object.values(recordMap))
+  const learned = {}
+  for (const e of index || []) {
+    if (!e?.ownId || recordMap[e.ownId] || learned[e.ownId]) continue
+    const theirs = placed.has(e.ownId) ? e.ownId : byName.get(`${e.model} ${e.slug}`)
+    if (!theirs || taken.has(theirs)) continue
+    taken.add(theirs)
+    learned[e.ownId] = theirs
+  }
+  return learned
+}

package/src/uwx/records-project.js

@@ -35,12 +35,13 @@
 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 { readFileSync, readdirSync, existsSync, unlinkSync, writeFileSync } from 'node:fs'
+import { join, resolve, relative, dirname, extname, basename, sep } from 'node:path'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { parseFrontmatter } from './entity-source.js'
-import { writeRecordFile, writeQueriesConfig, writeRecordsConfig } from './project-writer.js'
+import { writeRecordFile, writeQueriesConfig, writeRecordsConfig, YAML_DUMP_OPTS } from './project-writer.js'
+import { canonicalJson } from './same-content.js'
 import { defaultSchema, deferredFromSchema, foundationDataSchemas, foundationSchemaJson, QUERIES_YML_RELPATH } from './queries-config.js'
 import { dataKeyTypes } from './data-key-types.js'
 import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir } from '../site/entity-pool.js'
@@ -48,7 +49,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 } from './backfill.js'
+import { unwrapLocalized, renderEntityDocument } from './backfill.js'
+import { parseBibtex } from '@citestyle/bibtex'
+import { getSchema as getStandardSchema, isStandardSchema } from '@uniweb/schemas'
+import { validateAndNormalizeSchema } from '../resolve-data-schema.js'
 import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations } from './locale-sync.js'
 import { buildFreeformRecordPath } from '../i18n/freeform.js'
 
@@ -97,6 +101,52 @@ export function findRecordFileByUuid(poolDir, uuid) {
   return null
 }
 
+// ⭐ A RECORD KEPT IN A LIST FILE — a JSON or YAML array, or a BibTeX file: several records in one —
+// is found by its entry's `$uuid`, which the push's back-fill writes into each entry. ⛔ Until
+// 2026-09-25 a pull looked in single-record files alone, wrote each such record again as a file of
+// its own beside the list, and the next push held it twice — measured on the `international`
+// template's `records/team/team.json`.
+export function findListEntryByUuid(poolDir, uuid) {
+  if (!uuid || !existsSync(poolDir)) return null
+  for (const name of readdirSync(poolDir)) {
+    if (name.startsWith('_')) continue
+    const ext = extname(name).toLowerCase()
+    const format = ext === '.bib' ? 'bib' : formatForExt(ext)
+    if (format !== 'json' && format !== 'yaml' && format !== 'bib') continue
+    const path = join(poolDir, name)
+    let entries
+    try {
+      const text = readFileSync(path, 'utf8')
+      entries = format === 'json' ? JSON.parse(text) : format === 'yaml' ? yaml.load(text, YAML_OPTIONS) : parseBibtex(text)
+    } catch {
+      continue
+    }
+    if (!Array.isArray(entries)) continue
+    const index = entries.findIndex((e) => e && typeof e === 'object' && e.$uuid === uuid)
+    if (index >= 0) return { path, format, index, list: true }
+  }
+  return null
+}
+
+// A pulled record written back into its entry of a JSON or YAML list, every other entry untouched.
+// The entry keeps its `slug`, which names it where a single-record file's name would.
+function writeRecordIntoList({ list, document, declaration, sourceLocale, collector, freeformRelPath, refName, context = null }) {
+  const text = readFileSync(list.path, 'utf8')
+  const entries = list.format === 'json' ? JSON.parse(text) : yaml.load(text, YAML_OPTIONS)
+  const rendered = renderEntityDocument({ document, declaration, format: list.format, sourceLocale, collector, freeformRelPath, refName, context })
+  const { $uuid, ...fields } = list.format === 'json' ? JSON.parse(rendered) : yaml.load(rendered, YAML_OPTIONS)
+  const slug = entries[list.index]?.slug
+  const entry = { ...($uuid ? { $uuid } : {}), ...(slug !== undefined ? { slug } : {}), ...fields }
+  // ⭐ An entry the pull did not change leaves the file as the author wrote it — its key order, its
+  // spacing, and a YAML file's comments. ⛔ Until 2026-09-26 the file was compared as text and re-dumped.
+  if (canonicalJson(entries[list.index]) === canonicalJson(entry)) return 'unchanged'
+  const next = entries.map((e, i) => (i === list.index ? entry : e))
+  const out = list.format === 'json' ? JSON.stringify(next, null, 2) + '\n' : yaml.dump(next, YAML_DUMP_OPTS)
+  if (out === text) return 'unchanged'
+  writeFileSync(list.path, out)
+  return 'updated'
+}
+
 // The format to give a NEW record file in a collection: match the collection's
 // existing single-record files, else markdown when the schema has a content body field
 // (so the body has a home), else YAML.
@@ -125,7 +175,7 @@ function defaultFormat(poolDir, declaration) {
 // are walked; the collection is the NEAREST enclosing branch segment (correct for
 // the default one-branch-per-collection org; a deeply nested virtual org may
 // differ — see the module header).
-function indexFolder(folderDoc) {
+export function indexFolder(folderDoc) {
   const byUuid = new Map()
   const walk = (nodes, folderPath) => {
     for (const node of nodes || []) {
@@ -271,19 +321,34 @@ const DECL_WIRE_CONSUMED = new Set([
   'queryable'
 ])
 
+// A standard schema (`@std/<name>`), normalized as the build resolves one — known with no foundation
+// on disk. ⛔ Until 2026-09-26 a clone, which has none, could not tell a derived `deferred:` from an
+// authored one and wrote it into the author's queries (`international`'s `articles`, over `@std/article`).
+function standardDataSchema(ref) {
+  const m = typeof ref === 'string' ? /^@std\/([^/]+)$/.exec(ref) : null
+  if (!m || !isStandardSchema(m[1])) return null
+  try {
+    return validateAndNormalizeSchema(getStandardSchema(m[1]), ref)
+  } catch {
+    return null
+  }
+}
+
 // Is this wire `deferred` exactly what the schema's brief would have derived? Compared
 // as an ORDER-INSENSITIVE set: the deriver walks the schema's sections, and a round trip
 // through YAML and the store is not obliged to preserve that order. Comparing as a list
 // would classify a reordered-but-identical value as authored, and persist it.
-function isDerivedDeferred(d, dataSchemas) {
-  if (!dataSchemas || !Array.isArray(d.deferred)) return false
-  const derived = deferredFromSchema(dataSchemas[d.schema])
+function isDerivedDeferred(d, dataSchemas, pulledModel = null) {
+  if (!Array.isArray(d.deferred)) return false
+  // A clone has no foundation to read a schema from: it judges by the Model the pull read from the
+  // backend (`pulledModel`), and a standard schema is known in any case (`standardDataSchema`).
+  const derived = deferredFromSchema(dataSchemas?.[d.schema] ?? pulledModel ?? standardDataSchema(d.schema))
   if (!derived || derived.length !== d.deferred.length) return false
   const a = new Set(derived)
   return d.deferred.every((f) => a.has(f))
 }
 
-function declToFileShape(wire, dataSchemas = null, scope = null, own = null, keyTypes = null, authored = null) {
+function declToFileShape(wire, dataSchemas = null, scope = null, own = null, keyTypes = null, authored = null, models = null) {
   // ⛔ UNDO THE PRODUCER'S QUALIFICATION FIRST, before anything compares against
   // `schema`. The push qualifies a foundation-relative `@/x` to `@scope/x`
   // (`site.js::queriesNested`), and both checks below are keyed by the author's
@@ -346,7 +411,7 @@ function declToFileShape(wire, dataSchemas = null, scope = null, own = null, key
   //
   // ⚖️ Only an EQUAL value is dropped. An author who deliberately writes a narrower or
   // wider `deferred:` than the brief implies has expressed intent, and that survives.
-  if (d.deferred !== undefined && !isDerivedDeferred(d, dataSchemas)) {
+  if (d.deferred !== undefined && !isDerivedDeferred(d, dataSchemas, models?.[wire.schema] ?? null)) {
     decl.deferred = d.deferred
   }
   // ⛔ A stored `detail_url` is not written back: `detailUrl:` is retired (2026-09-13)
@@ -409,7 +474,7 @@ function authoredQuerySchemas(siteRoot, siteYml) {
   return out
 }
 
-export function declarationsToQueriesYml({ document, siteRoot, scope, ...rest }) {
+export function declarationsToQueriesYml({ document, siteRoot, scope, models = null, ...rest }) {
   refuseOrgOption(rest, 'declarationsToQueriesYml')
   const decls = Array.isArray(document?.queries) ? document.queries : []
   const report = {}
@@ -438,7 +503,7 @@ export function declarationsToQueriesYml({ document, siteRoot, scope, ...rest })
 
   const queries = {}
   for (const d of decls) {
-    const { name, decl } = declToFileShape(d, dataSchemas, selfScope, own, keyTypes, authored)
+    const { name, decl } = declToFileShape(d, dataSchemas, selfScope, own, keyTypes, authored, models)
     if (!name) continue
     queries[name] = decl
   }
@@ -524,7 +589,8 @@ export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceL
         unplaceable = true
         continue
       }
-      out.push(rel)
+      // A list file holds several records and is one path — listed once.
+      if (!out.includes(rel)) out.push(rel)
     }
     return out
   }
@@ -589,7 +655,7 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
   // Captures target-locale translations of localized record fields: SCALARs →
   // locales/records/{locale}.json (structural maps too), and a prosemirror
   // BODY's free-form per-locale override → locales/freeform/{locale}/records/.
-  const collector = createTranslationCollector(sourceLocale)
+  const collector = createTranslationCollector(sourceLocale, { siteRoot })
   const updated = []
   const placed = []
   const unchanged = []
@@ -616,13 +682,19 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
   // The file holding a record already, by its own id: the derived folder first, then any
   // other that reads as the same Model (`recordDirsReadingAs`).
   const readingAs = (model) => recordDirsReadingAs(recordsRoot, model, selfScope, { own, keyTypes })
-  const findRecordFile = (poolDir, model, ownId) =>
-    findRecordFileByUuid(poolDir, ownId) ||
-    readingAs(model)
-      .filter((dir) => dir !== poolDir)
-      .map((dir) => findRecordFileByUuid(dir, ownId))
-      .find(Boolean) ||
-    null
+  const findRecordFile = (poolDir, model, ownId) => {
+    const dirs = [poolDir, ...readingAs(model).filter((dir) => dir !== poolDir)]
+    // Single-record files first, as before; then an entry of a list file.
+    for (const find of [findRecordFileByUuid, findListEntryByUuid]) {
+      for (const dir of dirs) {
+        const hit = find(dir, ownId)
+        if (hit) return hit
+      }
+    }
+    return null
+  }
+  // BibTeX files holding a pulled record — never rewritten by a pull, and said once each.
+  const keptBib = new Set()
 
   for (const document of recordDocs) {
     const where = locate(document, folderIndex)
@@ -677,9 +749,21 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
     // ⛔ 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.
     const toWrite = ownId && ownId !== theirs ? { ...document, $uuid: ownId } : document
+    // The record's identity as the build keys its translations — the folder its file is in,
+    // under `records/`, and its handle — so a translation that differs from one record to
+    // another comes back as the author's `{ default, overrides }`.
+    const context = { key: [relative(recordsRoot, dirname(existing?.path ?? filePath)).split(sep).join('/'), where.slug].filter(Boolean).join('/') }
     let status
     try {
-      status = writeRecordFile({ filePath, document: toWrite, declaration, format, sourceLocale, collector, freeformRelPath, refName })
+      if (existing?.list && existing.format === 'bib') {
+        // Kept as the author has it: a pull does not re-render BibTeX (said once per file, below).
+        keptBib.add(existing.path)
+        status = 'unchanged'
+      } else if (existing?.list) {
+        status = writeRecordIntoList({ list: existing, document: toWrite, declaration, sourceLocale, collector, freeformRelPath, refName, context })
+      } else {
+        status = writeRecordFile({ filePath, document: toWrite, declaration, format, sourceLocale, collector, freeformRelPath, refName, context })
+      }
     } catch (err) {
       // ⛔ 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.
@@ -707,6 +791,9 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
   // site's folder, keyed by the site-content uuid.
   const records = folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceLocale })
   warnings.push(...records.warnings)
+  for (const path of keptBib) {
+    warnings.push(`${relative(siteRoot, path)}: a pull does not rewrite a BibTeX file — its records are kept as they are.`)
+  }
 
   // Flush localized record-field translations to locales/records/{locale}.json,
   // and any prosemirror free-form body overrides to locales/freeform/{locale}/.

package/src/uwx/records.js

@@ -62,7 +62,7 @@ import { resolveSelfScope, siteSelfScope, refuseOrgOption } from './self-scope.j
 import { sha256Hex, toJsonBuffer } from './manifest.js'
 import { isUuid } from './uuid.js'
 import { markdownToProseMirror } from '@uniweb/content-reader'
-import { LOCALIZED_FIELD_ASSUMPTION, localize } from './localize.js'
+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'
@@ -164,7 +164,10 @@ export function entityContentHash(document) {
   return sha256Hex(toJsonBuffer(stripSigils(document)))
 }
 
-function encodeFieldValue(value, field, sourceLocale, translations) {
+// ⭐ `context` is the record the value is in — `{ key: '<pool>/<handle>' }`, the identity its
+// translations are kept under (`i18n/records.js`) — so an entry that reads differently in some
+// records (`{ default, overrides }`) is sent as each one renders it.
+function encodeFieldValue(value, field, sourceLocale, translations, context = null) {
   if (value == null) return value
   if (isProseMirrorField(field)) {
     // markdown source → ProseMirror doc. When localized, wrap per-locale exactly
@@ -172,7 +175,7 @@ function encodeFieldValue(value, field, sourceLocale, translations) {
     // path, flushed to locales/records/{locale}.json by the caller.
     const doc = typeof value === 'string' ? markdownToProseMirror(value) : value
     if (!field.localized) return doc
-    const localized = localizeContentDoc(doc, sourceLocale, Object.keys(translations || {}), translations)
+    const localized = localizeContentDoc(doc, sourceLocale, Object.keys(translations || {}), translations, context)
     // localizeContentDoc returns a BARE doc when there are no target locales. A
     // localized field MUST ride as a `{ lang: value }` map on the wire — the
     // schema-driven projector drops a localized field whose value isn't a map — so
@@ -184,15 +187,14 @@ function encodeFieldValue(value, field, sourceLocale, translations) {
     // element — the shape page `keywords` already take. ⛔ It went up as a bare list
     // until 2026-09-24: `localizeScalar` passes any object through, arrays included.
     if (Array.isArray(value) && !isMarkupTextField(field)) {
-      return localizeScalarList(value, sourceLocale, translations)
+      return localizeScalarList(value, sourceLocale, translations, context)
     }
-    // A markup `text` BODY (format markdown|html) rides as a RAW string, wrapped
-    // per-locale wholesale (its per-string translations live in the i18n manifest /
-    // free-form, not the scalar map). Other localized scalars wrap per-string from
-    // locales/records/{locale}.json.
-    return isMarkupTextField(field)
-      ? localize(value, sourceLocale)
-      : localizeScalar(value, sourceLocale, translations)
+    // A markup `text` field (format markdown|html) rides as its RAW source, and its
+    // translation is the one the build renders: the whole value, keyed by the value
+    // (`i18n/records.js` extracts and translates it as one unit) — so it is wrapped
+    // per string like any localized scalar. ⛔ Until 2026-09-26 it went up as its
+    // source alone (`{ en }`), though the static build rendered its translation.
+    return localizeScalar(value, sourceLocale, translations, context)
   }
   // A Date handed in by a caller. The backend validates `date` as `YYYY-MM-DD` and
   // `datetime` as RFC3339 — emitting full ISO for a `date` field is rejected before
@@ -291,14 +293,15 @@ export function recordsToEntities({
     const uuid = record.$uuid || null
     const hasBody = typeof record.$body === 'string' && record.$body.trim() !== ''
 
-    const enc = encoder(sourceLocale, translations, refs)
+    const context = { key: `${label}/${slug}` } // as the build keys the record's translations
+    const enc = encoder(sourceLocale, translations, refs, context)
     const sections = layout.flat ? readFlat(layout, record, enc) : readBySection(layout, record, enc)
     // The markdown body fills the content body field, in whatever section declares it,
     // unless the file already sets that field.
     if (hasBody && bodyTarget) {
       const data = (sections[bodyTarget.section] ??= {})
       if (data[bodyTarget.key] == null) {
-        data[bodyTarget.key] = encodeFieldValue(record.$body, bodyTarget.field, sourceLocale, translations)
+        data[bodyTarget.key] = encodeFieldValue(record.$body, bodyTarget.field, sourceLocale, translations, context)
       }
     }
     // The brief is the card, and is always sent — an empty one included, so a required
@@ -381,8 +384,8 @@ export function recordsToEntities({
 // What one record's read collects beside the values: the keys with no place in the
 // schema, the keys written flat in a schema written by section, and values of the
 // wrong shape for their section.
-function encoder(sourceLocale, translations, refs = null) {
-  return { sourceLocale, translations, refs, undeclared: [], misplaced: [], shape: [], unresolved: [], namesNew: 0 }
+function encoder(sourceLocale, translations, refs = null, context = null) {
+  return { sourceLocale, translations, refs, context, undeclared: [], misplaced: [], shape: [], unresolved: [], namesNew: 0 }
 }
 
 // A flat record: its keys, minus the record's own, are the one section's fields.
@@ -473,7 +476,7 @@ function encodeRecord(fields, value, enc, prefix, reserved) {
         ? encodeSection(field, v, enc, `${prefix}${key}`)
         : field?.type === 'entity_ref'
           ? encodeReference(v, field, enc, `${prefix}${key}`)
-          : encodeFieldValue(v, field, enc.sourceLocale, enc.translations)
+          : encodeFieldValue(v, field, enc.sourceLocale, enc.translations, enc.context)
     if (encoded !== undefined) out[key] = encoded
   }
   for (const key of Object.keys(value)) {

package/src/uwx/same-content.js

@@ -0,0 +1,43 @@
+// Do two renderings of an author's content say the same thing? A pull that changes nothing must leave
+// the author's file as they wrote it, and the writer's formatting is not theirs — so a pull compares
+// meaning, not text, before it writes.
+//
+// A leaf, so the writers that compare this way — `project-writer.js` (sections, YAML config, record
+// files), `locale-sync.js` (free-form translations) and `records-project.js` (list files) — share one
+// rule without importing each other.
+
+import { markdownToProseMirror } from '@uniweb/content-reader'
+
+const isPlainObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v)
+
+/** JSON with every object's keys sorted — equal for equal values, whatever the order. */
+export const canonicalJson = (value) =>
+  JSON.stringify(value, (_, v) =>
+    isPlainObject(v) ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, v[k]])) : v
+  )
+
+/**
+ * Does this markdown parse to `doc`, the way a push parses it?
+ *
+ * @param {string} markdown - an author's markdown body
+ * @param {object} doc - a ProseMirror document
+ * @returns {boolean}
+ */
+export function sameMarkdownDocument(markdown, doc) {
+  try {
+    return canonicalJson(withoutDefaults(markdownToProseMirror(markdown))) === canonicalJson(withoutDefaults(doc))
+  } catch {
+    return false
+  }
+}
+
+// A document without the attributes that only restate a default: an inset's `embedKind: 'visual'`,
+// which the parser writes and the pull's re-inlining leaves out (`reinlineInsets`) — so a body holding
+// an inset never compared as unchanged (measured 2026-09-26 on the `marketing` template's hero).
+function withoutDefaults(doc) {
+  return JSON.parse(JSON.stringify(doc), (_, v) => {
+    if (v?.type !== 'inset_ref' || v.attrs?.embedKind !== 'visual') return v
+    const { embedKind: _visual, ...attrs } = v.attrs
+    return { ...v, attrs }
+  })
+}