@uniweb/build 0.63.0 → 0.63.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.63.0",
+  "version": "0.63.1",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {

package/src/site/queries-config.js

@@ -361,7 +361,7 @@ async function deriveDeferredFromSchemas(siteRoot, siteYml, declarations) {
   )
   if (pending.length === 0) return
 
-  const dataSchemas = loadFoundationDataSchemas(siteRoot, siteYml)
+  const dataSchemas = foundationDataSchemas(siteRoot, siteYml)
   if (!dataSchemas) return
 
   for (const decl of pending) {
@@ -447,11 +447,15 @@ function localFoundationSrcDir(siteRoot, siteYml) {
 
 /** The data schemas a site's foundation declares, or null when unresolvable. */
 export function foundationDataSchemas(siteRoot, siteYml) {
-  return loadFoundationDataSchemas(siteRoot, siteYml)
+  return foundationSchemaJson(siteRoot, siteYml)?.dataSchemas || null
 }
 
-/** The foundation's built data-schema map, or null when there is nothing to read. */
-function loadFoundationDataSchemas(siteRoot, siteYml) {
+/**
+ * A site's foundation's built `schema.json` whole — its section types (each with its `data:`)
+ * beside `_self` and `dataSchemas` — or null when the foundation is not in the project or not
+ * built.
+ */
+export function foundationSchemaJson(siteRoot, siteYml) {
   if (!siteYml?.foundation) return null
   let info
   try {
@@ -463,7 +467,7 @@ function loadFoundationDataSchemas(siteRoot, siteYml) {
   const schemaPath = join(info.path, 'dist', 'meta', 'schema.json')
   if (!existsSync(schemaPath)) return null
   try {
-    return JSON.parse(readFileSync(schemaPath, 'utf8'))?.dataSchemas || null
+    return JSON.parse(readFileSync(schemaPath, 'utf8')) || null
   } catch {
     return null
   }

package/src/uwx/data-key-types.js

@@ -0,0 +1,53 @@
+// ⭐ A NAME THAT IS A DATA KEY, NOT A DATA SCHEMA — its records are of the key's type.
+//
+// [Diego, 2026-09-25] — *"if team is just a data key for the `@std/member` type and that type
+// has a schema, it should not be understood as missing a schema and becoming static data."*
+//
+// A query that declares no `schema:` takes its own name (`team` → `@/team`), and so does its
+// records folder (`records/team/`). When no data schema has that name, but the foundation's
+// section types declare the data key of that name with a type — `data: { team: '@/member' }` in a
+// `meta.js` — the records ARE of that type: a push sends them as its entities, and the query names
+// it on the wire. ⛔ Until 2026-09-25 they were read as having no data schema at all and went out
+// as static files, although the one section that reads them declared what they are.
+//
+// ⚠️ THIS DECIDES ONLY WHICH DATA SCHEMA THE RECORDS BELONG TO. Where they live on disk, how the
+// site builds them and how their translations are keyed stay keyed by the name (`team`), as the
+// author wrote it — the records are where the author put them, and the query still reads them.
+//
+// ⛔ A key two section types declare with different types names no type: nothing says which.
+
+import { declaredKeys } from '@uniweb/core/data-keys'
+
+/**
+ * The type each data key of a foundation's section types names, where every declaration of the
+ * key agrees on one — from its built `schema.json`, whose section types sit at the top level
+ * beside `_self` and `dataSchemas`, each with its `data:`.
+ *
+ * @param {object|null} foundationSchema - a foundation's built `dist/meta/schema.json`
+ * @returns {Map<string, string>} data key → its schema ref (`team` → `@/member`)
+ */
+export function dataKeyTypes(foundationSchema) {
+  const types = new Map()
+  const conflicted = new Set()
+  for (const [name, entry] of Object.entries(foundationSchema || {})) {
+    if (name === '_self' || name === 'dataSchemas' || !entry || typeof entry !== 'object') continue
+    for (const [key, ref] of declaredKeys(entry.data)) {
+      if (!ref) continue
+      if (types.has(key) && types.get(key) !== ref) conflicted.add(key)
+      else types.set(key, ref)
+    }
+  }
+  for (const key of conflicted) types.delete(key)
+  return types
+}
+
+/**
+ * The data key a name-defaulted ref stands for — `@/team` → `team` — or null for any other ref.
+ *
+ * @param {unknown} ref
+ * @returns {string|null}
+ */
+export function keyOfDefaultRef(ref) {
+  const m = typeof ref === 'string' ? /^@\/([^/]+)$/.exec(ref) : null
+  return m ? m[1] : null
+}

package/src/uwx/index.js

@@ -57,6 +57,15 @@ export { buildFolderEntity,
   collectFolderItemUuids,
   stampFolderItemUuids
 } from './folder.js'
+// The identity of a record's list items — banked per record from what a push sent and
+// what came back, stamped on the next send.
+export {
+  recordItemLists,
+  harvestRecordItems,
+  storedRecordItems,
+  stampRecordItems,
+  reprintRecordItems
+} from './record-items.js'
 export {
   recordsToProject,
   declarationsToQueriesYml,

package/src/uwx/queries-config.js

@@ -7,5 +7,6 @@ export {
   defaultSchema,
   deferredFromSchema,
   foundationDataSchemas,
+  foundationSchemaJson,
   QUERIES_YML_RELPATH,
 } from '../site/queries-config.js'

package/src/uwx/record-items.js

@@ -0,0 +1,312 @@
+// The identity of a record's LIST ITEMS — what a push must remember so that the next send of a
+// record updates its stored items instead of replacing them.
+//
+// ⛔ AN ITEM OF A LIST WITHOUT A `$uuid` IS A NEW ROW. A record's `many` sections are `multi`
+// sections on the backend, so a record re-sent with its list items uuid-less would insert them all
+// and delete every stored one. The backend refuses that, whole (`identity_required`, naming the
+// section) — measured 2026-09-25 on an edit of a talk whose `sessions` it held. A single section
+// needs nothing: its one item is matched by section. So every LIST of a record carries its items'
+// `$uuid`s once the backend holds them: a `many` section, a list nested in a section or in an
+// item, and a self-nesting list's `$children`, at every depth.
+//
+// ⭐ BANKED PER RECORD, FROM WHAT WAS SENT AND WHAT CAME BACK. An item has no file and no name, so
+// nothing on disk can carry its identity — the fourth kind in the producer's ledger, beside
+// site-content units, records and folder placements. The backend's response mirrors the package
+// item for item ("the producer walks both trees in lockstep"), so a push pairs each item it sent
+// with the `$uuid` returned at the same place, and banks both: that uuid, and a fingerprint of the
+// item as it was sent (`harvestRecordItems`). A pull pairs the same way — the files it writes hold
+// the stored items in stored order.
+//
+// ⭐ MATCHED BY CONTENT, THEN BY PLACE (`stampRecordItems`). The next send gives an item the uuid of
+// the banked item with the same fingerprint — its own fields unchanged, wherever it moved — and
+// otherwise the one banked at its own position: an item edited where it stands. An item's own lists
+// are then matched the same way under the item it took. Anything else goes without one, as
+// a new row, and a banked item nothing claims is left out of the send, which deletes it. ⛔ No uuid
+// is stamped twice: two items claiming one row is the failure identity exists to prevent.
+//
+// THE BANK IS FLAT, one line per item — it is committed, in `sync.json`: each item under its
+// place in the record, its value its `$uuid` and, when known, its fingerprint —
+// `"sessions[0]": "<uuid> <fingerprint>"`. A list's place is its path within its container, the
+// same on both sides: `sessions` for a `many` section, `details.notes` for a list inside a single
+// section, `printings` inside an item, `$children` for the items nested under an item of a
+// self-nesting list — so `parts[0].$children[1]` is the second part nested under the first.
+
+import { entityContentHash } from './records.js'
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+
+// An item's OWN content: its fields, with the lists nested in it left out — they are matched
+// on their own, under it. ⛔ Not the item whole: a parent that moved while one of its children
+// changed then matches nothing, and it comes back new with its whole subtree (measured
+// 2026-09-25 on a tree reordered while a nested part was renamed).
+function ownContent(def, value) {
+  if (!isPlainObject(value)) return value
+  const out = {}
+  for (const [key, v] of Object.entries(value)) {
+    if (key === '$children' && def?.self_nesting === true) continue
+    const field = def?.fields?.[key]
+    if (field?.type === 'section') {
+      if (field.multiple === true) continue
+      out[key] = ownContent(field, v)
+    } else {
+      out[key] = v
+    }
+  }
+  return out
+}
+
+// An item's own content in 16 hex characters — `$uuid`s aside, like every content hash of ours.
+const fingerprint = (def, item) => entityContentHash(ownContent(def, item)).slice(0, 16)
+
+// Each list of a container — a single section's value, or one item of a list — by its path.
+function eachList(def, value, prefix, visit) {
+  if (!isPlainObject(value)) return
+  for (const [key, field] of Object.entries(def?.fields || {})) {
+    if (field?.type !== 'section') continue
+    if (field.multiple === true) {
+      if (Array.isArray(value[key])) visit(`${prefix}${key}`, field, value[key])
+    } else {
+      eachList(field, value[key], `${prefix}${key}.`, visit)
+    }
+  }
+  if (def?.self_nesting === true && Array.isArray(value.$children)) {
+    visit(`${prefix}$children`, def, value.$children)
+  }
+}
+
+// Each list of a record document: its `many` sections, and the lists inside its single ones.
+function eachRecordList(declaration, document, visit) {
+  for (const [name, def] of Object.entries(declaration?.sections || {})) {
+    if (!def || typeof def !== 'object') continue
+    const value = document?.[name]
+    if (def.multiple === true) {
+      if (Array.isArray(value)) visit(name, def, value)
+    } else {
+      eachList(def, value, `${name}.`, visit)
+    }
+  }
+}
+
+function itemsOf(def, items) {
+  return items.map((item) => {
+    const node = { h: fingerprint(def, item) }
+    const nested = {}
+    eachList(def, item, '', (path, d, list) => {
+      nested[path] = itemsOf(d, list)
+    })
+    if (Object.keys(nested).length) node.c = nested
+    return node
+  })
+}
+
+/**
+ * The lists of one record document, as sent: each list's items by path, each item its
+ * fingerprint (`h`) and its own lists (`c`). What `harvestRecordItems` pairs with the
+ * document the backend returns. Not stored — a bank is (`harvestRecordItems`).
+ *
+ * @param {object} document - the record's `$`-document
+ * @param {object} declaration - its data schema's declaration (`{ name, sections }`)
+ * @returns {Object<string, Array<{ h: string, c?: object }>>} empty when the record has no list
+ */
+export function recordItemLists(document, declaration) {
+  const lists = {}
+  eachRecordList(declaration, document, (path, def, items) => {
+    lists[path] = itemsOf(def, items)
+  })
+  return lists
+}
+
+/** Whether a record's lists hold any item at all. */
+export function hasListItems(lists) {
+  return Object.values(lists || {}).some((items) => items.length > 0)
+}
+
+const valueAt = (value, path) =>
+  path.split('.').reduce((v, key) => (isPlainObject(v) ? v[key] : undefined), value)
+
+const uuidOf = (item) => (isPlainObject(item) && typeof item.$uuid === 'string' && item.$uuid ? item.$uuid : null)
+
+function pairItems(ours, theirs, at, bank) {
+  // Paired by position: the backend returns each list as it was sent. A list that came back
+  // with another length is still paired, but without fingerprints, so the next send matches
+  // its items by place alone.
+  const exact = ours.length === theirs.length
+  theirs.forEach((item, k) => {
+    const uuid = uuidOf(item)
+    if (!uuid) return
+    const place = `${at}[${k}]`
+    bank[place] = exact ? `${uuid} ${ours[k].h}` : uuid
+    for (const [path, sub] of Object.entries(ours[k]?.c || {})) {
+      const list = valueAt(item, path)
+      if (Array.isArray(list)) pairItems(sub, list, `${place}.${path}`, bank)
+    }
+  })
+}
+
+/**
+ * The bank entry for one record: each list item's `$uuid` in the document the backend
+ * returned (a push's finalized document, or a pull's), with its fingerprint as sent, paired
+ * by place with the lists as sent (`recordItemLists`).
+ *
+ * @param {object} lists - `recordItemLists` of the document as sent
+ * @param {object} returned - the backend's document for the same record
+ * @returns {Object<string, string>} place → `"<uuid> <fingerprint>"` (or `"<uuid>"`)
+ */
+export function harvestRecordItems(lists, returned) {
+  const bank = {}
+  for (const [path, ours] of Object.entries(lists || {})) {
+    const theirs = valueAt(returned, path)
+    if (Array.isArray(theirs)) pairItems(ours, theirs, path, bank)
+  }
+  return bank
+}
+
+// A list in the backend's document: an array of items that each carry a `$uuid`.
+const isStoredList = (v) => Array.isArray(v) && v.length > 0 && v.every((item) => uuidOf(item))
+
+function storedLists(container, prefix, bank) {
+  for (const [key, value] of Object.entries(container || {})) {
+    if (key.startsWith('$') && key !== '$children') continue
+    if (isStoredList(value)) {
+      value.forEach((item, k) => {
+        const place = `${prefix}${key}[${k}]`
+        bank[place] = item.$uuid
+        storedLists(item, `${place}.`, bank)
+      })
+    } else if (uuidOf(value)) {
+      // A section: its lists sit under its name.
+      storedLists(value, `${prefix}${key}.`, bank)
+    }
+  }
+}
+
+/**
+ * The bank entry for one record read from the backend's document ALONE — for a record whose
+ * items were never banked, like one pushed by a CLI from before this. No fingerprints: what
+ * was sent is unknown, so the next send matches each item by place.
+ *
+ * Read by shape: a list is an array whose every item carries a `$uuid`, and a section is an
+ * object carrying one — a reference is a string or an `{ schema, entity }`, and a localized
+ * value a `{ lang: … }` map, neither of which does.
+ *
+ * @param {object} returned - the backend's document for one record
+ * @returns {Object<string, string>} place → `"<uuid>"`
+ */
+export function storedRecordItems(returned) {
+  const bank = {}
+  storedLists(returned, '', bank)
+  return bank
+}
+
+// The bank's items grouped by list: list path → { index → { u, h, place } }.
+function bankedLists(bank) {
+  const lists = new Map()
+  for (const [place, value] of Object.entries(bank || {})) {
+    const m = /^(.*)\[(\d+)\]$/.exec(place)
+    if (!m || typeof value !== 'string') continue
+    const [u, h] = value.split(' ')
+    if (!u) continue
+    if (!lists.has(m[1])) lists.set(m[1], [])
+    lists.get(m[1])[Number(m[2])] = { u, h: h || null, place }
+  }
+  return lists
+}
+
+// Which banked item each item takes: the same fingerprint first, then the same place.
+function matchItems(prints, banked) {
+  const assigned = new Array(prints.length).fill(null)
+  const taken = new Set()
+  const byPrint = new Map()
+  banked.forEach((b, j) => {
+    if (!b?.h) return
+    if (!byPrint.has(b.h)) byPrint.set(b.h, [])
+    byPrint.get(b.h).push(j)
+  })
+  prints.forEach((h, i) => {
+    const queue = byPrint.get(h)
+    while (queue?.length) {
+      const j = queue.shift()
+      if (taken.has(j)) continue
+      assigned[i] = banked[j]
+      taken.add(j)
+      break
+    }
+  })
+  prints.forEach((_, i) => {
+    if (assigned[i] || taken.has(i) || !banked[i]) return
+    assigned[i] = banked[i]
+    taken.add(i)
+  })
+  return assigned
+}
+
+function stampList(def, items, at, lists, counts, claimed) {
+  const banked = (at !== null && lists.get(at)) || []
+  const assigned = matchItems(items.map((item) => fingerprint(def, item)), banked)
+  items.forEach((item, i) => {
+    const b = assigned[i]
+    if (b && !claimed.has(b.u)) {
+      item.$uuid = b.u
+      claimed.add(b.u)
+      counts.stamped++
+    } else {
+      counts.unknown++
+    }
+    // An item's own lists are banked under the place of the item it matched — a new item's
+    // nested items are new too.
+    const under = b && item.$uuid === b.u ? b.place : null
+    eachList(def, item, '', (path, d, list) =>
+      stampList(d, list, under === null ? null : `${under}.${path}`, lists, counts, claimed)
+    )
+  })
+}
+
+/**
+ * Stamp a record document about to be sent with its list items' banked `$uuid`s.
+ *
+ * @param {object} document - the record's `$`-document; stamped in place
+ * @param {object} declaration - its data schema's declaration
+ * @param {Object<string,string>} bank - this record's entry (`harvestRecordItems` /
+ *        `storedRecordItems`)
+ * @returns {{ stamped: number, unknown: number }} items given a uuid, and items sent as new
+ */
+export function stampRecordItems(document, declaration, bank) {
+  const counts = { stamped: 0, unknown: 0 }
+  const claimed = new Set()
+  const lists = bankedLists(bank)
+  eachRecordList(declaration, document, (path, def, items) => {
+    stampList(def, items, path, lists, counts, claimed)
+  })
+  return counts
+}
+
+function flatPrints(lists, at, out) {
+  for (const [path, items] of Object.entries(lists || {})) {
+    items.forEach((node, k) => {
+      const place = `${at}${path}[${k}]`
+      out[place] = node.h
+      flatPrints(node.c, `${place}.`, out)
+    })
+  }
+  return out
+}
+
+/**
+ * A bank entry with its fingerprints taken again from the record as the NEXT send will
+ * build it, each uuid kept at its place. For a record that named a new record by `$ref`:
+ * once that record is minted the next send names it by uuid, so an item holding such a
+ * reference is fingerprinted anew — the same item, another encoding.
+ *
+ * @param {Object<string,string>} bank - this record's entry
+ * @param {object} lists - `recordItemLists` of the record as the next send builds it
+ * @returns {Object<string,string>}
+ */
+export function reprintRecordItems(bank, lists) {
+  const prints = flatPrints(lists, '', {})
+  const out = {}
+  for (const [place, value] of Object.entries(bank || {})) {
+    const [u] = String(value).split(' ')
+    out[place] = prints[place] ? `${u} ${prints[place]}` : value
+  }
+  return out
+}

package/src/uwx/records-project.js

@@ -41,11 +41,12 @@ 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 { defaultSchema, deferredFromSchema, foundationDataSchemas } from './queries-config.js'
-import { poolDirsForSchema, resolveRecordsDir } from '../site/entity-pool.js'
+import { defaultSchema, deferredFromSchema, foundationDataSchemas, foundationSchemaJson } from './queries-config.js'
+import { dataKeyTypes } from './data-key-types.js'
+import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir } from '../site/entity-pool.js'
 import { folderYmlPath } from '../site/records-config.js'
 import { contentBodyTarget } from './record-layout.js'
-import { unresolveSelfScope, refuseOrgOption } from './self-scope.js'
+import { unresolveSelfScope, resolveSelfScope, ownSchemaNames, refuseOrgOption } from './self-scope.js'
 import { parseCatalogRef } from '../site/foundation-ref.js'
 import { unwrapLocalized } from './backfill.js'
 import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations } from './locale-sync.js'
@@ -153,11 +154,62 @@ function indexFolder(folderDoc) {
 // `schemaForPoolDirs`, and deliberately not a second rule: if the two disagreed,
 // a pulled record would land somewhere the next build reads as a different
 // schema — silently, because both paths are well-formed.
-function recordDirFor(recordsRoot, model, scope) {
-  const dirs = poolDirsForSchema(unresolveSelfScope(model, scope))
+function recordDirFor(recordsRoot, model, scope, own) {
+  const dirs = poolDirsForSchema(unresolveSelfScope(model, scope, own))
   return dirs ? join(recordsRoot, ...dirs) : null
 }
 
+// ⭐ A PULLED RECORD GOES BACK INTO THE FILE THAT HOLDS IT — wherever under the records
+// directory that is, so long as its folder reads as the same Model. Two folders can:
+// under a foundation in `@std`, `records/person/` (`@/person`, qualified into `@std`) and
+// `records/std/person/` both read as `@std/person`. ⛔ Looked for in the one folder the
+// pull derived, as until 2026-09-25, a record the author kept in the other was written
+// again beside it — two files, one record — and the next push was refused.
+//
+// ⭐ And a folder named for a data key the foundation types, when no data schema has that name,
+// reads as that type — `records/team/` as `@std/member` for `data: { team: '@/member' }`
+// (`data-key-types.js`), the same rule a push reads it by.
+function recordDirsReadingAs(recordsRoot, model, scope, { own = null, keyTypes = null } = {}) {
+  const dirs = []
+  if (!existsSync(recordsRoot)) return dirs
+  const visible = (dir) =>
+    readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith('_') && !e.name.startsWith('.'))
+      .map((e) => e.name)
+  for (const first of visible(recordsRoot)) {
+    const at = [first]
+    const keyType = !own?.has(first) ? keyTypes?.get(first) : null
+    if (
+      resolveSelfScope(schemaForPoolDirs(at), scope) === model ||
+      (keyType && resolveSelfScope(keyType, scope) === model)
+    ) {
+      dirs.push(join(recordsRoot, first))
+    }
+    for (const second of visible(join(recordsRoot, first))) {
+      if (resolveSelfScope(schemaForPoolDirs([first, second]), scope) === model) {
+        dirs.push(join(recordsRoot, first, second))
+      }
+    }
+  }
+  return dirs
+}
+
+// What the site's foundation declares, when its declarations are in this project: its own
+// data-schema names (`ownSchemaNames`) and the types of its data keys (`dataKeyTypes`). Both
+// null otherwise — a clone's foundation is not in the project.
+function siteFoundationDeclarations(siteRoot) {
+  let siteYml = null
+  try {
+    siteYml = yaml.load(readFileSync(join(siteRoot, 'site.yml'), 'utf8'), YAML_OPTIONS) || null
+  } catch {
+    return { own: null, keyTypes: null }
+  }
+  const schema = siteYml ? foundationSchemaJson(siteRoot, siteYml) : null
+  return schema
+    ? { own: ownSchemaNames(schema.dataSchemas || {}), keyTypes: dataKeyTypes(schema) }
+    : { own: null, keyTypes: null }
+}
+
 // ⚠️ Undoing the producer's self-scope resolution (`unresolveSelfScope`) lives in
 // `./self-scope.js`, beside the forward rule it inverts. It did not show before
 // records were placed by their model: every record went to
@@ -231,7 +283,7 @@ function isDerivedDeferred(d, dataSchemas) {
   return d.deferred.every((f) => a.has(f))
 }
 
-function declToFileShape(wire, dataSchemas = null, scope = null) {
+function declToFileShape(wire, dataSchemas = null, scope = null, own = null, keyTypes = 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
@@ -239,7 +291,7 @@ function declToFileShape(wire, dataSchemas = null, scope = null) {
   // explicit schema the author never had — and the derived-`deferred` lookup would
   // miss, persisting a derivation into their file (the 2026-08-29 defect).
   const d = scope && typeof wire.schema === 'string'
-    ? { ...wire, schema: unresolveSelfScope(wire.schema, scope) }
+    ? { ...wire, schema: unresolveSelfScope(wire.schema, scope, own) }
     : wire
   const name = d.name || d.$id
   const decl = {}
@@ -262,7 +314,11 @@ function declToFileShape(wire, dataSchemas = null, scope = null) {
     decl.source = source
   }
 
-  if (d.schema && d.schema !== defaultSchema(name)) decl.schema = d.schema
+  // The default is the query's name — or, when no data schema has that name, the type the
+  // foundation declares for the data key of that name (`data-key-types.js`), which is what a
+  // push sent in its place. Either one stays unwritten, so the terse file stays terse.
+  const keyDefault = name && !own?.has(name) ? keyTypes?.get(name) : null
+  if (d.schema && d.schema !== defaultSchema(name) && d.schema !== keyDefault) decl.schema = d.schema
   setIf(decl, 'sort', d.sort)
   setIf(decl, 'where', d.where)
   setIf(decl, 'limit', d.limit)
@@ -348,10 +404,14 @@ export function declarationsToQueriesYml({ document, siteRoot, scope, ...rest })
   const dataSchemas = siteYml ? foundationDataSchemas(siteRoot, siteYml) : null
   const selfScope =
     scope !== undefined ? scope : (parseCatalogRef(document?.info?.foundation)?.scope ?? null)
+  // Which of the scope's schemas are the foundation's own — the rest keep their scope
+  // (`unresolveSelfScope`) — and the types of its data keys.
+  const own = ownSchemaNames(dataSchemas)
+  const keyTypes = siteYml ? dataKeyTypes(foundationSchemaJson(siteRoot, siteYml)) : null
 
   const queries = {}
   for (const d of decls) {
-    const { name, decl } = declToFileShape(d, dataSchemas, selfScope)
+    const { name, decl } = declToFileShape(d, dataSchemas, selfScope, own, keyTypes)
     if (!name) continue
     queries[name] = decl
   }
@@ -477,6 +537,10 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
   // `@scope/x` model is placed back where the author wrote it. ⛔ It was the site
   // owner's org, read from `sync.json`, until 2026-09-22 (`self-scope.js`).
   const selfScope = opts.scope ?? null
+  // Which of that scope's Models are the foundation's own — the rest keep their scope, so
+  // a standard `@std/person` under a foundation in `@std` is placed in `records/std/person/`
+  // (`unresolveSelfScope`).
+  const { own, keyTypes } = siteFoundationDeclarations(siteRoot)
   if (typeof resolveDeclaration !== 'function') {
     throw new Error('uwx/records-project: opts.resolveDeclaration(modelName) is required')
   }
@@ -514,7 +578,7 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
   restoreAssetRefs(recordDocs, backendState.assets || {})
   // This backend's record map, inverted: its uuid → the record's own id.
   const recordMap = backendState.records || {}
-  const ownIdByTheirs = new Map(Object.entries(recordMap).map(([own, theirs]) => [theirs, own]))
+  const ownIdByTheirs = new Map(Object.entries(recordMap).map(([ownId, theirs]) => [theirs, ownId]))
   // own id → their uuid, for every record this pull wrote. Recorded at the end.
   const learned = {}
   // uuid → the path under `records/` the record landed at. Only this loop knows
@@ -522,6 +586,16 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
   // re-derived (a second rule could pick a different extension and the folder
   // would name a file that is not there).
   const poolPathByUuid = new Map()
+  // 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
 
   for (const document of recordDocs) {
     const where = locate(document, folderIndex)
@@ -536,7 +610,7 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
       continue
     }
 
-    const poolDir = recordDirFor(recordsRoot, schema, selfScope)
+    const poolDir = recordDirFor(recordsRoot, schema, selfScope, own)
     if (!poolDir) {
       skipped.push({
         uuid: document.$uuid,
@@ -550,8 +624,8 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
     // the first backend a record reaches minted the id it keeps — so the backend's
     // uuid is the own id, exactly as before identity was keyed by backend.
     const theirs = document.$uuid || null
-    const own = theirs ? ownIdByTheirs.get(theirs) || theirs : null
-    const existing = own ? findRecordFileByUuid(poolDir, own) : null
+    const ownId = theirs ? ownIdByTheirs.get(theirs) || theirs : null
+    const existing = ownId ? findRecordFile(poolDir, schema, ownId) : null
 
     let filePath
     let format
@@ -561,8 +635,11 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
       format = existing.format
       isNew = false
     } else {
-      format = defaultFormat(poolDir, declaration)
-      filePath = join(poolDir, where.slug + EXT_FOR_FORMAT[format])
+      // 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
+      format = defaultFormat(home, declaration)
+      filePath = join(home, where.slug + EXT_FOR_FORMAT[format])
       isNew = true
     }
 
@@ -572,7 +649,7 @@ 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 = own && own !== theirs ? { ...document, $uuid: own } : document
+    const toWrite = ownId && ownId !== theirs ? { ...document, $uuid: ownId } : document
     let status
     try {
       status = writeRecordFile({ filePath, document: toWrite, declaration, format, sourceLocale, collector, freeformRelPath, refName })
@@ -591,7 +668,7 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
     // terms, so that is what `folderToFolderYml` will look them up by.
     if (theirs) {
       poolPathByUuid.set(theirs, relative(recordsRoot, filePath).split(sep).join('/'))
-      if (own) learned[own] = theirs
+      if (ownId) learned[ownId] = theirs
     }
   }
 

package/src/uwx/records.js

@@ -32,13 +32,14 @@
 // reference or held back, and the CLI pushed again to complete it.
 // ⚠️ item_ref and file fields are still sent as the file writes them.
 //
-// ⚠️ A record of a `many` section is sent without a `$uuid`, so a push that changes a
-// record whose section the backend already holds is REFUSED, whole (`identity_required`):
-// applied, it would re-identify every stored item. Measured 2026-09-25 — this said such a
-// push "replaces that section's records" until then. Its first push, which creates the
-// items, is not affected.
+// ⭐ A record of a `many` section — an ITEM of a record's list — carries the `$uuid` the backend
+// gave it once the backend holds it, from a bank the CLI keeps per record (`record-items.js`,
+// stamped in `sync-package.js`). Sent without it, a record whose list the backend holds is
+// REFUSED, whole (`identity_required`): applied, it would re-identify every stored item —
+// measured 2026-09-25 on an edit of a talk, before the bank existed.
 
 import { readBackendState } from './sync-store.js'
+import { dataKeyTypes, keyOfDefaultRef } from './data-key-types.js'
 import { readFileSync, existsSync } from 'node:fs'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
@@ -879,6 +880,8 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
       folder: { ...folder, nodes: [] },
       recordsDirExists: pool.exists,
       sendFolder: sendsFolder(pool, []),
+      declarations: new Map(),
+      keyTyped: new Map(),
     }
   }
 
@@ -976,6 +979,24 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
     )
   }
 
+  // ⭐ A NAME THAT IS A DATA KEY, NOT A DATA SCHEMA [Diego, 2026-09-25] (`data-key-types.js`):
+  // a records folder or a query whose name-defaulted schema (`@/team`) resolves to nothing,
+  // while the foundation's section types type the data key of that name (`team: '@/member'`),
+  // holds records of that type. `keyTyped` records each such name for the `queries` Section,
+  // which must name the same data schema (`sync-package.js` hands it on). ⛔ Never for a schema
+  // a query asked for explicitly: that one is the author's, and fails loudly.
+  const keyTypes = dataKeyTypes(localSchema)
+  const keyTyped = new Map()
+  const typedFor = async (schema) => {
+    const key = keyOfDefaultRef(schema)
+    const type = key ? keyTypes.get(key) : null
+    if (!type || explicitBy.has(schema)) return null
+    const declaration = await declarationFor(modelFor(type, `data key "${key}"`))
+    if (!declaration) return null
+    keyTyped.set(schema, type)
+    return declaration
+  }
+
   const sourceLocale =
     opts.sourceLocale || LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale
 
@@ -1016,10 +1037,17 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
   // of another Model by its handle (`speaker: ada`), and the push sends that record's
   // uuid in its place — or its `$id`, while it is new (`refResolver`).
   const readSchemas = []
+  // ⛔ ONE RECORD IN TWO FILES — the same own id, its `$uuid`, twice — is refused, naming
+  // both. It is not two records, and sent, both would claim one entity. A pull could write
+  // one until 2026-09-25: under a foundation in `@std`, a standard `@std/person` record was
+  // written again into `records/person/`, beside the author's `records/std/person/`
+  // (`self-scope.js::unresolveSelfScope`), and a push then reported only a name two
+  // records share.
+  const fileByOwnId = new Map()
   for (const [schema, poolEntities] of poolBySchema) {
     const label = poolEntities[0].dirs.join('/')
     const modelName = modelFor(schema, `${pool.dir}/${label}/`)
-    const declaration = await declarationFor(modelName)
+    const declaration = (await declarationFor(modelName)) || (await typedFor(schema))
     if (!declaration) {
       // An explicit schema the author asked for is a hard error; one only the
       // folder's name supplied is a soft skip, reported below.
@@ -1055,6 +1083,16 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
         // ⚠️ A multi-record file (array YAML, BibTeX) contributes several records
         // from one path, so the slug — not the file stem — completes the id.
         rec.$id = rec.$id || [...pooled.dirs, r.slug].join('/')
+        const ownId = typeof rec.$uuid === 'string' && rec.$uuid ? rec.$uuid : null
+        const firstFile = ownId ? fileByOwnId.get(ownId) : undefined
+        if (firstFile && firstFile !== pooled.relPath) {
+          refusals.push(
+            `${pooled.relPath}: holds the same record as ${firstFile} — both carry ` +
+              `\`$uuid: ${ownId}\` — so a push would send one record twice. Keep one of them.`
+          )
+        } else if (ownId) {
+          fileByOwnId.set(ownId, pooled.relPath)
+        }
         flat.push(rec)
         sourceBySlug.set(r.slug, r)
         produced.push({ id: rec.$id, slug: r.slug })
@@ -1145,7 +1183,7 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
     const hasRecords = poolBySchema.has(schema)
     const resolved = hasRecords
       ? !unresolved.has(schema)
-      : Boolean(await declarationFor(modelFor(schema, `query "${name}"`)))
+      : Boolean((await declarationFor(modelFor(schema, `query "${name}"`))) || (await typedFor(schema)))
     if (!resolved) {
       if (decl.schemaExplicit) throw unresolvedExplicit(resolveSelfScope(schema, scope), name)
       schemaless.push({ name, model: resolveSelfScope(schema, scope) })
@@ -1183,6 +1221,12 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
     folder: { ...folder, nodes },
     recordsDirExists: pool.exists,
     sendFolder: sendsFolder(pool, entities),
+    // Each entity's declaration, by its Model — what walks a record's lists
+    // (`record-items.js`).
+    declarations: new Map(readSchemas.map(({ declaration }) => [declaration.name, declaration])),
+    // A name-defaulted schema that stands for the type of the data key of its name
+    // (`@/team` → `@/member`) — see `typedFor` above.
+    keyTyped,
   }
 }
 

package/src/uwx/self-scope.js

@@ -33,6 +33,7 @@
 import { readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import yaml from 'js-yaml'
+import { isStandardSchema } from '@uniweb/schemas'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { detectFoundationType, parseCatalogRef } from '../site/foundation-ref.js'
 import { readFoundationName } from '../schema.js'
@@ -66,7 +67,8 @@ export function resolveSelfScope(ref, scope) {
 }
 
 /**
- * The inverse, for a pull: `@<scope>/x` → `@/x` for the site's foundation's scope.
+ * The inverse, for a pull: `@<scope>/x` → `@/x` — when `x` is one of the foundation's
+ * OWN data schemas.
  *
  * ⛔ WITHOUT THIS THE ROUND TRIP IS NOT A FIXED POINT, and the failure is silent
  * on both ends. A record authored under `records/article/` comes back as
@@ -76,17 +78,51 @@ export function resolveSelfScope(ref, scope) {
  * relied on the query-name default comes back with an explicit schema it never
  * had.
  *
+ * ⛔ AND NOT EVERY `@<scope>/x` WAS AN `@/x`: the forward rule is not one-to-one. A
+ * foundation in `@std` — every template's — whose site also uses the STANDARD
+ * `@std/person` ships both its own `@/specimen` and that `@std/person` as `@std/…`.
+ * Inverted whole, as it was until 2026-09-25, the standard schema came back as the
+ * foundation's own: a clone put `@std/person` records in `records/person/` and
+ * rewrote the query to `@/person`, and a pull into a working copy wrote them BESIDE
+ * the author's `records/std/person/`, after which every reference to a person named
+ * two records and the next push was refused. So `x` is written back as `@/x` only
+ * when it is the foundation's own: one of `own`, the names its declarations define
+ * (`ownSchemaNames`) — or, when those cannot be read here (its foundation is not in
+ * this project, as after a clone), any name that is not a standard schema of `@std`.
+ *
  * A model scoped to ANY OTHER scope is left alone: it genuinely is that org's, and
  * `@/` would be a lie.
  *
  * @param {unknown} ref
  * @param {unknown} scope - the scope the pulled records were qualified with
+ * @param {Set<string>|null} [own] - the names of the data schemas the foundation
+ *        defines, when known
  * @returns {unknown}
  */
-export function unresolveSelfScope(ref, scope) {
+export function unresolveSelfScope(ref, scope, own = null) {
   const handle = bareOrg(scope)
-  if (typeof ref !== 'string' || !handle) return ref
-  return ref.startsWith(`@${handle}/`) ? `@/${ref.slice(handle.length + 2)}` : ref
+  if (typeof ref !== 'string' || !handle || !ref.startsWith(`@${handle}/`)) return ref
+  const name = ref.slice(handle.length + 2)
+  const isOwn = own ? own.has(name) : !(handle === 'std' && isStandardSchema(name))
+  return isOwn ? `@/${name}` : ref
+}
+
+/**
+ * The names of the data schemas a foundation DEFINES — the `@/x` keys of its built
+ * declarations (`dist/meta/schema.json` → `dataSchemas`), which is what `register`
+ * registers. A schema it only references keeps its scope there (`@std/person`) and is
+ * not one of them. Null when there are no declarations to read.
+ *
+ * @param {object|null} dataSchemas - a foundation's `dataSchemas` map
+ * @returns {Set<string>|null}
+ */
+export function ownSchemaNames(dataSchemas) {
+  if (!dataSchemas || typeof dataSchemas !== 'object') return null
+  return new Set(
+    Object.keys(dataSchemas)
+      .filter((ref) => ref.startsWith('@/'))
+      .map((ref) => ref.slice(2))
+  )
 }
 
 /**
@@ -95,7 +131,8 @@ export function unresolveSelfScope(ref, scope) {
  *
  * - `foundation` given (a pull passes the pinned ref the pushed site carries) — a
  *   catalog ref's scope, or a local foundation's, resolved from that value.
- * - else `foundationDir` — that local foundation's.
+ * - else `foundationDir` — that local foundation's; when its name has none, the scope of
+ *   the release `site.yml::foundation` pins for it, if that names the same foundation.
  * - else `site.yml::foundation`, the same way.
  *
  * A local foundation's scope is the one in its name, read by the one rule
@@ -112,7 +149,10 @@ export function unresolveSelfScope(ref, scope) {
  * @returns {Promise<string|null>}
  */
 export async function siteSelfScope(siteRoot, { foundation, foundationDir } = {}) {
-  if (foundation === undefined && foundationDir) return localFoundationScope(resolve(foundationDir))
+  if (foundation === undefined && foundationDir) {
+    const dir = resolve(foundationDir)
+    return (await localFoundationScope(dir)) ?? (await pinnedReleaseScope(siteRoot, dir))
+  }
   const declared = foundation !== undefined ? foundation : readDeclaredFoundation(siteRoot)
   const value = declared && typeof declared === 'object' ? declared.name : declared
   if (typeof value !== 'string' || !value) return null
@@ -136,6 +176,26 @@ async function localFoundationScope(dir) {
   }
 }
 
+// ⭐ A LOCAL FOUNDATION WHOSE NAME CARRIES NO SCOPE, handed in as the source of the release
+// the site pins (`site.yml::foundation: '@std/lab@0.1.0'`, the same name): that release's
+// scope. The site's pin IS the foundation's name with its scope, and the local folder is its
+// source. It arises when a registration was written to a file (`register --scope @std -o`),
+// which writes nothing into the source — so a push given the source (`--foundation <dir>`)
+// found a bare name and shipped every `@/x` unresolved (measured 2026-09-25: records of `@/team`
+// shipped as static files). ⛔ Only for the same name: a pin of another foundation says
+// nothing about this one's scope.
+async function pinnedReleaseScope(siteRoot, dir) {
+  const declared = readDeclaredFoundation(siteRoot)
+  const ref = parseCatalogRef(declared && typeof declared === 'object' ? declared.name : declared)
+  if (!ref?.scope) return null
+  try {
+    const { name } = await readFoundationName(dir)
+    return splitFoundationName(name).bare === ref.name ? ref.scope : null
+  } catch {
+    return null
+  }
+}
+
 function readDeclaredFoundation(siteRoot) {
   try {
     const siteYml = yaml.load(readFileSync(join(siteRoot, 'site.yml'), 'utf8'), YAML_OPTIONS) || {}

package/src/uwx/site.js

@@ -919,7 +919,7 @@ function externalSource(d) {
   return source
 }
 
-function queriesNested(declarations, uuids = null, scope = null) {
+function queriesNested(declarations, uuids = null, scope = null, keyTyped = null) {
   const out = []
   for (const [name, d] of Object.entries(declarations)) {
     refuseUnder(d.where, `queries.${name}`)
@@ -936,7 +936,10 @@ function queriesNested(declarations, uuids = null, scope = null) {
     // stored under, so a verbatim `@/member` beside records stored as `@acme/member`
     // names nothing: the query resolves no Model and the page that binds it renders
     // empty. The pull puts the author's `@/` back (`records-project.js::declarationsToQueriesYml`).
-    setIf(data, 'schema', resolveSelfScope(d.schema, scope))
+    // A query whose name-defaulted schema stands for the type of the data key of its name
+    // names that type — the data schema its records are sent as (`data-key-types.js`).
+    const schema = (!d.schemaExplicit && keyTyped?.get(d.schema)) || d.schema
+    setIf(data, 'schema', resolveSelfScope(schema, scope))
     setIf(data, 'sort', d.sort)
     // Legacy `filter:` is not synced — it is translated to `where` upstream
     // (the canonical predicate). No legacy fields on the wire.
@@ -1545,7 +1548,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // ⚠️ `queriesNested` keeps its name. §2's rule: rename what an author or a
   // consumer sees, leave the identifier alone.
   const scope = opts.scope !== undefined ? opts.scope : await siteSelfScope(siteRoot)
-  doc.queries = queriesNested(colConfig.declarations, opts.queryUuids, scope)
+  doc.queries = queriesNested(colConfig.declarations, opts.queryUuids, scope, opts.keyTyped)
   // Emitted ONLY when the file declares the key — see the header above
   // `serviceRecords`: on a replaced Section, absent and empty are different
   // requests and one of them is destructive.

package/src/uwx/sync-package.js

@@ -20,6 +20,7 @@
 //     lane (the idempotent no-op).
 
 import { buildRecordEntities, entityContentHash } from './records.js'
+import { recordItemLists, hasListItems, stampRecordItems } from './record-items.js'
 import { ASSET_SLOTS } from '@uniweb/semantic-parser'
 import { buildFolderEntity } from './folder.js'
 import { siteProjectToDocument } from './site.js'
@@ -217,6 +218,10 @@ function rewriteEntityAssets(node, map, ids, noStamp = null) {
  *        stamped onto the site-content document so the backend matches our items
  *        instead of re-minting them (which deletes and recreates every page and
  *        section row). Sourced from a pull or a push response, cached by the caller.
+ * @param {Object<string,Object<string,string>>} [opts.recordItemUuids] - record `$uuid` → the
+ *        identity of its list items, as a previous push or pull banked it
+ *        (`record-items.js`); stamped onto each record the backend holds, so a re-sent
+ *        record updates its items instead of replacing them.
  * @param {Object<string,string>} [opts.itemBaseVersions] - record `$uuid` → opaque
  *        per-ITEM `version`. Narrowed at emit to the records the package carries and
  *        sent as `entries[].item_base_versions`, so the backend can refuse only the
@@ -253,7 +258,11 @@ function rewriteEntityAssets(node, map, ids, noStamp = null) {
  *   records: { buffer, entityCount, index, models }|null,
  *   hashes: Object<string,string>, warnings: string[], refusals: string[],
  *   skipped: number, schemaless: Array<{name: string, model: string}>,
- *   localAssets: string[], applied: object, namesNew: string[] }>}
+ *   localAssets: string[], applied: object, namesNew: string[],
+ *   recordItemIdentity: { stamped: number, unknown: number, unbanked: string[] } }>}
+ *   Each record entry of `records.index` carries `lists`: the record's list items as
+ *   sent (`record-items.js::recordItemLists`), for the caller to bank against the
+ *   document the backend returns.
  *   `namesNew` lists the records this package sends whose references name a record it
  *   creates — by `$ref`, where the next push will send a uuid — as keys of `hashes`. A
  *   caller that banks `hashes` re-banks these once the push is applied.
@@ -347,6 +356,9 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
         // must name the Model its records are stored under, and both are qualified
         // from one `@/x` by one rule (`./self-scope.js`) — so they take one scope.
         scope,
+        // …and the same data schema, where a name stands for the type of its data key
+        // (`@/team` → `@/member`, `data-key-types.js`): decided once, by the records.
+        keyTyped: col.keyTyped,
         // Withhold the `$services`/`$secrets` Sections when the caller has
         // determined the file is not asking for anything new by them. Passed
         // through rather than decided here: the last-agreed state is project
@@ -452,6 +464,32 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   for (const e of col.entities) collectFrom(e.document)
   const localAssets = [...localAssetSet]
 
+  // ⭐ THE IDENTITY OF A RECORD'S LIST ITEMS (`record-items.js`), taken on each document as it
+  // will be sent — after every rewrite above. `opts.recordItemUuids` is the caller's bank: per
+  // record (its uuid on this backend), each list's items as a previous push or pull left them.
+  // A record this backend has not minted has only new items, and one it holds with no bank entry
+  // is named in `unbanked`, so the caller can recover its items' identity before sending it.
+  // Stamping does not move a content hash: `$uuid` is stripped from every one.
+  const recordItemBank =
+    opts.recordItemUuids && typeof opts.recordItemUuids === 'object' ? opts.recordItemUuids : null
+  const recordItemIdentity = { stamped: 0, unknown: 0, unbanked: [] }
+  const unbankedIds = new Set()
+  for (const e of col.entities) {
+    const declaration = col.declarations?.get(e.model)
+    if (!declaration) continue
+    e.lists = recordItemLists(e.document, declaration)
+    const uuid = e.document.$uuid
+    if (!uuid || !hasListItems(e.lists)) continue
+    const banked = recordItemBank?.[uuid]
+    if (!banked) {
+      unbankedIds.add(e.id)
+      continue
+    }
+    const n = stampRecordItems(e.document, declaration, banked)
+    recordItemIdentity.stamped += n.stamped
+    recordItemIdentity.unknown += n.unknown
+  }
+
   const siteEntity = siteDoc
     ? { id: siteDoc.$id, model: siteDoc.$schema, file: 'entities/site-content.json', document: siteDoc }
     : null
@@ -492,7 +530,12 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     // leading `{ kind: 'folder' }` keeps submission position 0 aligned for record
     // back-fill (backfillEntityUuids skips it — the folder has no uuid to write).
     const entities = [folder, ...changedRecords.map((r) => r.entity)].map(stamp)
-    const index = [{ kind: 'folder' }, ...changedRecords.map((r) => r.index)]
+    // Each record's lists as sent ride on its index entry: the caller pairs them with the
+    // document the backend returns, to bank the items' identity (`record-items.js`).
+    const index = [{ kind: 'folder' }, ...changedRecords.map((r) => ({ ...r.index, lists: r.entity.lists || {} }))]
+    for (const r of changedRecords) {
+      if (unbankedIds.has(r.entity.id)) recordItemIdentity.unbanked.push(r.entity.document.$uuid)
+    }
     // The folder references every record's Model via `entry.model` — including records
     // filtered out here by send-only-changed. Declare them all (the backend rejects a
     // folder that references an undeclared Model).
@@ -545,5 +588,9 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     // no map. `unknown > 0` with `stamped === 0` on a site that has been pushed
     // before is the index-loss signature the backend refuses — the caller reports it.
     itemIdentity,
+    // The records' list items: how many took a banked uuid and how many go as new, and the
+    // records this package SENDS that the backend holds with list items and no bank entry
+    // (their uuids) — sent as they are, the backend refuses each one (`identity_required`).
+    recordItemIdentity,
   }
 }

package/src/uwx/sync-store.js

@@ -43,8 +43,12 @@ export const SYNC_STORE_FILE = 'sync.json'
 /** Current on-disk shape. Bumped only for a breaking layout change. */
 const VERSION = 1
 
-/** Map sections — merged entry by entry. Anything else in a patch replaces. */
-const MAP_SECTIONS = new Set(['records', 'items', 'queries', 'folders', 'assets'])
+/**
+ * Map sections — merged entry by entry. Anything else in a patch replaces.
+ * `recordItems` is keyed by a record's uuid here, each entry that record's list items
+ * (`record-items.js`) — replaced whole, one record at a time.
+ */
+const MAP_SECTIONS = new Set(['records', 'items', 'queries', 'folders', 'assets', 'recordItems'])
 
 const storePath = (siteDir) => join(siteDir, SYNC_STORE_FILE)
 
@@ -207,7 +211,7 @@ export function updateBackendState(siteDir, origin, patch) {
  *
  * @param {string} siteDir
  * @param {string} origin
- * @param {string} section - one of `records` `items` `queries` `folders` `assets`
+ * @param {string} section - one of `records` `items` `queries` `folders` `assets` `recordItems`
  * @param {Record<string, *>} entries
  * @param {(next: *, prior: *) => *} [merge]
  * @returns {{ added: string[], changed: string[], written: boolean }}