@uniweb/build 0.62.0 → 0.63.1

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

@@ -25,16 +25,21 @@
 //
 // ⭐ A REFERENCE (`entity_ref`) NAMES ITS RECORD BY HANDLE in a file — `speaker: ada`,
 // the target's file name or its `slug:` — and is sent as the uuid THIS backend minted for
-// that record (`refResolver`). A target this backend has not minted yet (new in this
-// push) cannot be named on the wire, so its referrer WAITS: sent without that reference
-// and completed by the next pass, or held back when it cannot exist without it — see
-// `sync-package.js`, and the CLI's `pushInPasses`, which repeats the push.
+// that record (`refResolver`). A target this backend has not minted yet is new, so this
+// push creates it, and the reference names it by its `$id` in the package —
+// `speaker: { $ref: "speaker/ada" }` — which the backend resolves to the uuid it mints.
+// One push creates both. ⛔ Until 2026-09-25 such a referrer WAITED, sent without the
+// 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 replaces that section's records rather than updating them in place.
+// ⭐ 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'
@@ -85,7 +90,7 @@ const RECORD_KEYS = new Set([
 
 // Recursively drop IDENTITY `$`-sigil keys (`$uuid`/`$id`/`$schema`/… — never
 // field data; the sigil-exclusivity invariant guarantees this) at every level,
-// so a back-filled `$uuid` doesn't change the hash. Two are exceptions, because
+// so a back-filled `$uuid` doesn't change the hash. Three are exceptions, because
 // they are content rather than identity:
 //   - `$children` is STRUCTURAL content (a self-nesting record's subtree, e.g.
 //     site-content's nested pages/sections), so it is KEPT and recursed into —
@@ -94,15 +99,21 @@ const RECORD_KEYS = new Set([
 //   - `$disabled` is a record's delivery STATE (`draft: true` on the file side). It
 //     is KEPT so that drafting or un-drafting a record with nothing else changed is
 //     still sent; stripped, "send only changed" would never send the toggle.
+//   - `$ref` is a REFERENCE to a record the same push creates (`speaker: { $ref:
+//     "speaker/ada" }`), and which record it names is content. Once the backend has
+//     minted that record the next push names it by uuid instead — so the CLI re-banks a
+//     record that sent a `$ref` after its push (`namesNew`, `sync-package.js`). The
+//     folder's ref leaf is not this case: see below.
 function stripSigils(value) {
   if (Array.isArray(value)) return value.map(stripSigils)
   if (value && typeof value === 'object') {
     // ⛔ A `@uniweb/folder` REF LEAF ENCODES ONE REFERENCE TWO WAYS, and hashing the
     // encoding rather than the reference made the folder's hash unreproducible.
     //
-    // `refLeaf` (uwx/folder.js) emits `$ref: <the record's $id>` — the pool position
-    // `<dirs>/<slug>` — while the record is brand-new, and `entry: { schema, entity:
-    // <uuid> }` once it has been minted.
+    // `refLeaf` (uwx/folder.js) emits `entry: { $ref: <the record's $id> }` — the pool
+    // position `<dirs>/<slug>` — while the record is brand-new, and `entry: { schema,
+    // entity: <uuid> }` once it has been minted. (`$ref` was a key of the leaf itself
+    // until 2026-09-25, when the backend made it a reference's value.)
     // Both denote the same record. A push hashes the folder BEFORE submitting, then
     // back-fills the minted `$uuid` into every record's source file — so the very
     // next emit builds the OTHER encoding, and the hash the push just banked can
@@ -116,19 +127,20 @@ function stripSigils(value) {
     // `name` (the record's handle) at its position inside the branch that holds it.
     // Two siblings may share a name — records of different schemas can — and position
     // still tells them apart; a leaf that comes to reference another record arrives
-    // with that record changed, which re-sends the folder anyway. `$ref` adds a
-    // payload-local handle and `entry` adds identity, and both are exactly what
-    // `$uuid` is stripped for.
+    // with that record changed, which re-sends the folder anyway. `entry` carries a
+    // payload-local handle or an identity, and both are exactly what `$uuid` is
+    // stripped for.
     //
     // ⚖️ The previous rule kept `$ref` "so a reference change is visible". It still
     // is: point a leaf at a different record and its `name` moves with it.
     const isFolderRefLeaf = value.kind === 'ref'
     const out = {}
     for (const [k, v] of Object.entries(value)) {
-      if (isFolderRefLeaf && (k === '$ref' || k === 'entry')) continue
-      // `$children` (a self-nesting subtree) and `$disabled` (a delivery state) are
-      // CONTENT, not identity sigils — kept, so a change to either stays visible.
-      if (k === '$children' || k === '$disabled') {
+      if (isFolderRefLeaf && k === 'entry') continue
+      // `$children` (a self-nesting subtree), `$disabled` (a delivery state) and `$ref`
+      // (a reference to a record of the same push) are CONTENT, not identity sigils —
+      // kept, so a change to any of them stays visible.
+      if (k === '$children' || k === '$disabled' || k === '$ref') {
         out[k] = stripSigils(v)
         continue
       }
@@ -218,11 +230,10 @@ function encodeFieldValue(value, field, sourceLocale, translations) {
  * @param {{ resolve: (model: string, value: *) => object }} [params.refs] - what a
  *        reference sends (`refResolver`). Without it a reference is sent as written.
  * @returns {{ entities: object[], warnings: string[], refusals: string[] }} each
- *   entity is `{ id, uuid, model, file, document, pending }` — `document` is the
- *   section-keyed body, and `pending` the references it WAITS on, left out of it:
- *   `{ path, model, name, required }`, one per reference whose record this backend has
- *   not minted yet. `refusals` names the records that cannot be sent as written, one
- *   line each; a caller that sends must not send while any is present.
+ *   entity is `{ id, uuid, slug, model, file, document, namesNew }` — `document` is the
+ *   section-keyed body, and `namesNew` how many of its references name a record this
+ *   push creates, by `$ref`. `refusals` names the records that cannot be sent as
+ *   written, one line each; a caller that sends must not send while any is present.
  */
 export function recordsToEntities({
   label,
@@ -324,10 +335,7 @@ export function recordsToEntities({
       )
     }
     if (!enc.misplaced.length && !enc.shape.length) {
-      // A required reference that waits for its record is owed, not missing: the push
-      // that completes the record sends it (see `pending` below).
-      const waiting = new Set(enc.pending.map((p) => `"${p.path}"`))
-      const missing = missingRequired(layout, sections).filter((m) => !waiting.has(m))
+      const missing = missingRequired(layout, sections)
       if (missing.length) {
         refusals.push(
           `${where}: ${declaration.name} requires ${listOf(missing)}, and this record ` +
@@ -364,7 +372,7 @@ export function recordsToEntities({
       // unique within its schema folder, and an authored `$id` need not be.
       file: `entities/${label}/${slug}.json`,
       document,
-      pending: enc.pending,
+      namesNew: enc.namesNew,
     })
   }
   return { entities, warnings, refusals }
@@ -374,7 +382,7 @@ export function recordsToEntities({
 // 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: [], pending: [], unresolved: [] }
+  return { sourceLocale, translations, refs, undeclared: [], misplaced: [], shape: [], unresolved: [], namesNew: 0 }
 }
 
 // A flat record: its keys, minus the record's own, are the one section's fields.
@@ -478,10 +486,10 @@ function encodeRecord(fields, value, enc, prefix, reserved) {
 const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
 
 // A reference, as a push sends it: the uuid this backend minted for the record the file
-// names (`refResolver`). A list of them is each of those. One whose record this backend
-// has not minted yet is left out and noted as WAITING (`enc.pending`) — the push that
-// completes it sends it. Without a resolver, and for a reference open to several Models
-// (which our schemas do not author), the value is sent as written.
+// names (`refResolver`) — or, for a record it has not minted, which this push creates,
+// `{ $ref: <that record's $id> }`, the backend's name for a record of the same package.
+// A list of them is each of those. Without a resolver, and for a reference open to
+// several Models (which our schemas do not author), the value is sent as written.
 function encodeReference(value, field, enc, path) {
   if (!enc.refs || typeof field.model !== 'string') return value
   if (field.multiple === true) {
@@ -490,27 +498,23 @@ function encodeReference(value, field, enc, path) {
       return undefined
     }
     const sent = []
-    const waiting = []
     value.forEach((one, i) => {
-      const uuid = resolveReference(one, field, enc, `${path}[${i}]`, waiting)
-      if (uuid !== undefined) sent.push(uuid)
+      const ref = resolveReference(one, field, enc, `${path}[${i}]`)
+      if (ref !== undefined) sent.push(ref)
     })
-    // A required list with nothing to send yet waits whole; otherwise what is known goes now.
-    const required = field.required === true && sent.length === 0
-    for (const w of waiting) enc.pending.push({ ...w, required })
     return sent
   }
-  const waiting = []
-  const uuid = resolveReference(value, field, enc, path, waiting)
-  for (const w of waiting) enc.pending.push({ ...w, required: field.required === true })
-  return uuid
+  return resolveReference(value, field, enc, path)
 }
 
-function resolveReference(value, field, enc, path, waiting) {
+function resolveReference(value, field, enc, path) {
   const answer = enc.refs.resolve(field.model, value)
   if (answer.uuid) return answer.uuid
-  if (answer.pending) waiting.push({ path, model: field.model, name: value })
-  else enc.unresolved.push({ path, model: field.model, value, ...answer })
+  if (answer.ref) {
+    enc.namesNew++
+    return { $ref: answer.ref }
+  }
+  enc.unresolved.push({ path, model: field.model, value, ...answer })
   return undefined
 }
 
@@ -527,31 +531,34 @@ function describeUnresolved({ path, model, value, invalid, ambiguous }) {
 // own id (mapped like a handle's), or the backend's id of a record the project does not
 // hold, which is what a pull writes for one.
 //
-// ⛔ A record this backend has not minted yet — never pushed there — answers `pending`: a
-// uuid it did not mint is never sent (see `buildRecordEntities`), so its referrer waits.
+// ⭐ A record this backend has not minted yet — never pushed there — answers with its
+// `$id` (`ref`): it is new, so this push creates it, and the backend takes
+// `{ $ref: <$id> }` for a record of the same package. A uuid it did not mint is never
+// sent (see `buildRecordEntities`).
 const AMBIGUOUS = Symbol('ambiguous')
 function refResolver(readSchemas, recordMap) {
-  const byModel = new Map() // Model → handle → the record's own id (null before its first push)
-  const ownIds = new Set()
+  const byModel = new Map() // Model → handle → the record: its own id (null before its first push) and `$id`
+  const byOwnId = new Map() // the record's own id → the record
   for (const { declaration, flat } of readSchemas) {
     let names = byModel.get(declaration.name)
     if (!names) byModel.set(declaration.name, (names = new Map()))
     for (const rec of flat) {
       const own = typeof rec.$uuid === 'string' && rec.$uuid ? rec.$uuid : null
-      names.set(rec.slug, names.has(rec.slug) ? AMBIGUOUS : own)
-      if (own) ownIds.add(own)
+      const record = { own, id: rec.$id }
+      names.set(rec.slug, names.has(rec.slug) ? AMBIGUOUS : record)
+      if (own) byOwnId.set(own, record)
     }
   }
-  const minted = (own) => (own && recordMap[own] ? { uuid: recordMap[own] } : { pending: true })
+  const sent = ({ own, id }) => (own && recordMap[own] ? { uuid: recordMap[own] } : { ref: id })
   return {
     resolve(model, value) {
       if (typeof value !== 'string' || value === '') return { invalid: true }
       const names = byModel.get(model)
       if (names?.has(value)) {
-        const own = names.get(value)
-        return own === AMBIGUOUS ? { ambiguous: true } : minted(own)
+        const record = names.get(value)
+        return record === AMBIGUOUS ? { ambiguous: true } : sent(record)
       }
-      if (isUuid(value)) return ownIds.has(value) ? minted(value) : { uuid: value }
+      if (isUuid(value)) return byOwnId.has(value) ? sent(byOwnId.get(value)) : { uuid: value }
       return { missing: true }
     },
   }
@@ -873,6 +880,8 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
       folder: { ...folder, nodes: [] },
       recordsDirExists: pool.exists,
       sendFolder: sendsFolder(pool, []),
+      declarations: new Map(),
+      keyTyped: new Map(),
     }
   }
 
@@ -970,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
 
@@ -1008,12 +1035,19 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
 
   // ⭐ EVERY MODEL'S RECORDS ARE READ BEFORE ANY IS MAPPED: a reference names a record
   // of another Model by its handle (`speaker: ada`), and the push sends that record's
-  // uuid in its place (`refResolver`).
+  // 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.
@@ -1049,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 })
@@ -1139,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) })
@@ -1177,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/registry-package.js

@@ -157,7 +157,56 @@ function buildDataSchemaEntities(dataSchemas, scope) {
       // way; item_ref `options` get the full `@org/x/<section>` path (§10.1).
       ...toDataSchemaDeclaration(normalized, { name: scoped(ref), resolveName: scoped, resolveOptions }),
     }))
-  return { entities, scoped, org }
+  return { entities: referencedFirst(entities), scoped, org }
+}
+
+/**
+ * The data schemas in an order a backend can install one at a time: a schema another one in
+ * the package references comes BEFORE it — alphabetical otherwise, so the order is stable.
+ *
+ * ⭐ WHY. A backend installs a package's data schemas in the order they arrive, and refuses a
+ * reference to a Model it holds neither yet nor from before: measured 2026-09-25, a foundation
+ * whose `exhibit` references its own `specimen` was refused whole — *"entity_ref target
+ * `@x/specimen` matches no model declared in this fixture or registered on the host"* — because
+ * `exhibit` sorts first. Alphabetical order was right only by luck (`speaker` before `talk`).
+ *
+ * ⚠️ A CYCLE CANNOT BE ORDERED — `author` names `book` and `book` names `author` — and keeps
+ * the order the walk gives it. Whether one package may reference itself in any order is the
+ * backend's to accept; this only stops refusing what an order can fix. A schema naming ITSELF
+ * is not a dependency.
+ *
+ * @param {Array<{ name: string, sections?: object }>} entities - lowered declarations
+ * @returns {Array} the same entities, referenced ones first
+ */
+function referencedFirst(entities) {
+  const byName = new Map(entities.map((e) => [e.name, e]))
+  const targets = (entity) => {
+    const out = new Set()
+    const walk = (fields) => {
+      for (const field of Object.values(fields || {})) {
+        if (!field || typeof field !== 'object') continue
+        if (field.type === 'entity_ref') for (const m of [field.model].flat()) out.add(m)
+        // `options: '@org/x/<section>'` names a section of Model `@org/x`.
+        if (field.type === 'item_ref' && typeof field.options === 'string') {
+          out.add(field.options.split('/').slice(0, 2).join('/'))
+        }
+        if (field.type === 'section') walk(field.fields)
+      }
+    }
+    for (const section of Object.values(entity.sections || {})) walk(section.fields)
+    return [...out].filter((name) => name !== entity.name && byName.has(name)).sort()
+  }
+  const ordered = []
+  const state = new Map() // name → 'visiting' | 'done'
+  const visit = (entity) => {
+    if (state.get(entity.name)) return // done, or on the walk now — a cycle
+    state.set(entity.name, 'visiting')
+    for (const name of targets(entity)) visit(byName.get(name))
+    state.set(entity.name, 'done')
+    ordered.push(entity)
+  }
+  for (const entity of entities) visit(entity)
+  return ordered
 }
 
 // The shared `.uwx` envelope (uwx/1 + exporter + timestamp) around an entity list.