@uniweb/build 0.63.4 → 0.64.1

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,29 @@ 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.
+  // ⛔ An EMPTY body is one too: until 2026-09-26 it never compared as unchanged, so a section holding
+  // only frontmatter — a parametric page's `type:` and `fetch:` — was re-serialized, and lost its
+  // comments, on a pull that changed nothing. So is no document at all (a params-only update).
+  const authoredBody = (existingBody || '').replace(/^\n+/, '').replace(/\s+$/, '')
+  const keepsBody = !content || sameMarkdownDocument(authoredBody, content)
+  if (existing && keepsBody && canonicalJson(nextFrontmatter) === canonicalJson(frontmatter)) return 'unchanged'
+  const body = keepsBody ? authoredBody : proseMirrorToMarkdown(content)
   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 +220,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 +230,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 +282,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 +302,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 +342,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 +382,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 +429,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/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.
@@ -205,8 +255,12 @@ function siteFoundationDeclarations(siteRoot) {
     return { own: null, keyTypes: null }
   }
   const schema = siteYml ? foundationSchemaJson(siteRoot, siteYml) : null
+  // ⛔ Own names only from a schema that carries its data schemas. The registered version a clone
+  // keeps carries none (they travel as Models), and read as an empty set it said "owns nothing", so a
+  // clone placed a foundation's own `@std/exhibit` in `records/std/exhibit/`; unknown (null), the
+  // standard-schema rule decides (`unresolveSelfScope`), as it did before the kept version existed.
   return schema
-    ? { own: ownSchemaNames(schema.dataSchemas || {}), keyTypes: dataKeyTypes(schema) }
+    ? { own: ownSchemaNames(schema.dataSchemas), keyTypes: dataKeyTypes(schema) }
     : { own: null, keyTypes: null }
 }
 
@@ -268,22 +322,39 @@ const DECL_WIRE_CONSUMED = new Set([
   'deferred',
   'detail_url',
   'detail',
-  'queryable'
+  'queryable',
+  // Says the query names no schema of its own — how the file is written, never a key in it.
+  'typed_by_data_key',
 ])
 
+// 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, markedOnly = false) {
   // ⛔ 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
@@ -320,8 +391,15 @@ function declToFileShape(wire, dataSchemas = null, scope = null, own = null, key
   // ⛔ UNLESS THE AUTHOR WROTE IT: a `schema:` the local file already states for this query is
   // written back as it is. Until 2026-09-25 a pull into a working copy dropped international's
   // `articles: { schema: '@std/article' }`, because a section types `articles` as `@std/article`.
-  const keyDefault = name && !own?.has(name) ? keyTypes?.get(name) : null
+  // ⭐ A CLONE GOES BY THE MARK. Where the key's type comes only from the registered foundation a
+  // project keeps (`markedOnly`: its foundation is a catalog ref), a query is written terse only when
+  // the push marked it `typed_by_data_key` — the author wrote no schema — or when the author's own
+  // file declares it with none. Unmarked, the schema was the author's, and it is written.
   const written = name ? authored?.get(name) : undefined
+  const typedHere = !markedOnly || wire.typed_by_data_key === true || written === null
+  const keyType = name && !own?.has(name) && typedHere ? keyTypes?.get(name) : null
+  // In the author's form: the registered version names the type qualified (`@acme/member`).
+  const keyDefault = keyType ? unresolveSelfScope(keyType, scope, own) : null
   if (d.schema && (d.schema === written || (d.schema !== defaultSchema(name) && d.schema !== keyDefault))) {
     decl.schema = d.schema
   }
@@ -346,7 +424,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)
@@ -398,18 +476,42 @@ function authoredQuerySchemas(siteRoot, siteYml) {
   } catch {
     file = null
   }
+  // name → the schema the author's file states for it, or null for a query it declares with none.
+  // ⛔ The string shorthand (`team: '@/member'`) is a schema too: until 2026-09-26 it read as none,
+  // so a pull could write the author's `team: '@/member'` back as `team: {}`.
   const out = new Map()
   for (const decls of [siteYml?.queries, file]) {
     if (!decls || typeof decls !== 'object') continue
     for (const [name, decl] of Object.entries(decls)) {
-      if (typeof decl?.schema === 'string') out.set(name, decl.schema)
-      else if (out.has(name)) out.delete(name)
+      const schema = typeof decl === 'string' ? decl : typeof decl?.schema === 'string' ? decl.schema : null
+      out.set(name, schema)
     }
   }
   return out
 }
 
-export function declarationsToQueriesYml({ document, siteRoot, scope, ...rest }) {
+// ⭐ WHERE A NEW RECORD OF A KEY'S TYPE GOES: the folder of a query the site declares with no schema
+// of its own, whose name is a data key typed as that Model — `records/team/` for `team:` typed
+// `@acme/member` — which is where a push reads it from (`uwx/data-key-types.js`). model → folder.
+function typedQueryFolders(siteRoot, recordsRoot, scope, own, keyTypes) {
+  const out = new Map()
+  if (!keyTypes?.size) return out
+  let siteYml = null
+  try {
+    siteYml = yaml.load(readFileSync(join(siteRoot, 'site.yml'), 'utf8'), YAML_OPTIONS) || null
+  } catch {
+    siteYml = null
+  }
+  for (const [name, schema] of authoredQuerySchemas(siteRoot, siteYml)) {
+    if (schema !== null || own?.has(name)) continue
+    const type = keyTypes.get(name)
+    const model = type ? resolveSelfScope(type, scope) : null
+    if (model && !out.has(model)) out.set(model, join(recordsRoot, name))
+  }
+  return out
+}
+
+export function declarationsToQueriesYml({ document, siteRoot, scope, models = null, ...rest }) {
   refuseOrgOption(rest, 'declarationsToQueriesYml')
   const decls = Array.isArray(document?.queries) ? document.queries : []
   const report = {}
@@ -435,10 +537,12 @@ export function declarationsToQueriesYml({ document, siteRoot, scope, ...rest })
   const own = ownSchemaNames(dataSchemas)
   const keyTypes = siteYml ? dataKeyTypes(foundationSchemaJson(siteRoot, siteYml)) : null
   const authored = authoredQuerySchemas(siteRoot, siteYml)
+  // The key types a catalog-ref foundation has come from the registered version the project keeps.
+  const markedOnly = Boolean(parseCatalogRef(siteYml?.foundation))
 
   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, markedOnly)
     if (!name) continue
     queries[name] = decl
   }
@@ -524,7 +628,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 +694,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 +721,20 @@ 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 keyFolders = typedQueryFolders(siteRoot, recordsRoot, selfScope, own, keyTypes)
+  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)
@@ -663,8 +775,9 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
       isNew = false
     } else {
       // A new record goes where the project already keeps records of its Model — its derived
-      // folder, else another that reads as the Model (`records/team/` for `@std/member`).
-      const home = existsSync(poolDir) ? poolDir : readingAs(schema)[0] || poolDir
+      // folder, else another that reads as the Model (`records/team/` for `@std/member`), else the
+      // folder of a query typed by its data key as the Model (`typedQueryFolders`) — a clone's.
+      const home = existsSync(poolDir) ? poolDir : readingAs(schema)[0] || keyFolders.get(schema) || poolDir
       format = defaultFormat(home, declaration)
       filePath = join(home, where.slug + EXT_FOR_FORMAT[format])
       isNew = true
@@ -677,9 +790,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 +832,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}/.