@uniweb/build 0.62.0 → 0.63.1

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'
@@ -33,18 +34,6 @@ const SITE_ENTITY_KEY = 'site-content'
 
 const cacheKey = (entity) => `${entity.model} ${entity.id}`
 
-// The folder's placements without the records a push leaves out — `{ kind: 'ref' }` leaves
-// naming them by `$entityId`, inside any branch.
-function withoutRecords(nodes, ids) {
-  if (!ids.size) return nodes
-  const out = []
-  for (const node of nodes || []) {
-    if (node?.kind === 'branch') out.push({ ...node, $children: withoutRecords(node.$children, ids) })
-    else if (!ids.has(node?.$entityId)) out.push(node)
-  }
-  return out
-}
-
 // Attach the push gate's optimistic-concurrency token to an entity, keyed by the
 // BACKEND uuid in its document body (`$uuid`). A never-synced entity has no
 // `$uuid` and therefore no base — correctly unconditional, since there is no
@@ -229,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
@@ -265,11 +258,14 @@ 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,
- *   waiting: Array<{id: string, model: string, slug: string, held: boolean, pending: object[]}> }>}
- *   `waiting` lists the records whose references name a record this backend has not
- *   minted yet — sent without them, or held back. A caller that sends pushes again
- *   once this push has been applied (`records.js::encodeReference`).
+ *   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.
  *   `refusals` names the records that cannot be sent as written, one line each
  *   (`records.js::recordsToEntities`). A caller that submits must not submit while
  *   any is present: the backend would refuse the records lane — or, for a record
@@ -316,43 +312,10 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   })
   const warnings = [...col.warnings, ...(col.folder?.warnings ?? [])]
 
-  // ⭐ RECORDS WAITING FOR A REFERENCE (`records.js::encodeReference`). A record whose
-  // reference names a record this backend has not minted yet cannot name it on the wire,
-  // so this push sends what it can and the next pass completes it (the CLI's
-  // `pushInPasses`):
-  //   · new, and nothing it waits for is required → sent now without those references,
-  //     so after one pass every record exists, whatever refers to what;
-  //   · new, and a required reference waits → HELD and placed nowhere: it cannot be
-  //     created without it;
-  //   · already on this backend → HELD, left as it is there: sent without a reference it
-  //     has, it would lose that reference until the next pass.
-  // A held record is not sent and keeps the hash last banked for it, so the next pass
-  // sees it as changed.
-  const held = new Set()
-  const unplaced = new Set()
-  for (const e of col.entities) {
-    if (!e.pending?.length) continue
-    if (e.uuid) held.add(e.id)
-    else if (e.pending.some((p) => p.required)) {
-      held.add(e.id)
-      unplaced.add(e.id)
-    }
-  }
-  const waiting = col.entities
-    .filter((e) => e.pending?.length)
-    .map((e) => ({ id: e.id, model: e.model, slug: e.slug, held: held.has(e.id), pending: e.pending }))
-  const placedEntities = []
-  const placedIndex = []
-  col.entities.forEach((e, i) => {
-    if (unplaced.has(e.id)) return
-    placedEntities.push(e)
-    placedIndex.push(col.index[i])
-  })
-
   // The folder rides over the FULL record set (before filtering) so its references
   // are complete — new records by `$ref`, already-minted ones by `entry: <uuid>`.
   const folder = buildFolderEntity({
-    recordEntities: placedEntities,
+    recordEntities: col.entities,
     ...(sourceLocale ? { sourceLocale } : {}),
     // ⭐ Every record in the directory, at the top of the folder or in the
     // sub-folder `folder.yml` places it in — and NOTHING when there is no folder to
@@ -360,7 +323,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     // non-empty tree: a `folder.yml` whose folders hold only records that resolved
     // no schema is a tree of empty branches, and sending it would replace the
     // backend's folder with them (measured on the `dynamic` template, 2026-09-21).
-    folderNodes: col.sendFolder === true ? withoutRecords(col.folder?.nodes ?? [], unplaced) : [],
+    folderNodes: col.sendFolder === true ? (col.folder?.nodes ?? []) : [],
     // ⛔ Whether the file side HAS a folder to state (`records.js::sendsFolder`) —
     // not whether it holds anything. A site with no records directory sends none
     // and leaves the backend's alone; an empty directory sends an empty folder,
@@ -393,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
@@ -498,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
@@ -518,26 +510,32 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   // changed() has side effects (hashes/skipped), so evaluate every entity exactly
   // once, in a stable order: folder, then each record.
   const folderChanged = folder ? changed(folder) : false
-  // A held record keeps its last banked hash — it was not sent (see `held` above).
-  const keepBanked = (entity) => {
-    const key = cacheKey(entity)
-    if (priorHashes[key] !== undefined) hashes[key] = priorHashes[key]
-    return false
-  }
-  const recordChanged = placedEntities.map((e, i) => ({
+  const recordChanged = col.entities.map((e, i) => ({
     entity: e,
-    index: placedIndex[i],
-    changed: held.has(e.id) ? keepBanked(e) : changed(e),
+    index: col.index[i],
+    changed: changed(e),
   }))
   const changedRecords = recordChanged.filter((r) => r.changed)
 
   let records = null
+  // ⭐ A RECORD THAT NAMES A RECORD THIS PUSH CREATES names it by `$ref`
+  // (`records.js::encodeReference`), and the backend stores the uuid it mints for it. The
+  // next push sends that uuid: the same reference, another encoding — and another hash.
+  // So the caller re-banks these records once the push is applied, or the next push
+  // sends every one of them again.
+  let namesNew = []
   if (folder && (folderChanged || changedRecords.length > 0)) {
+    namesNew = changedRecords.filter((r) => r.entity.namesNew > 0).map((r) => cacheKey(r.entity))
     // Folder first (always, for the `$ref` closure), then changed records. The
     // 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).
@@ -582,14 +580,17 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
 
   return {
     siteContent, records, siteContentUuid, hashes, warnings, skipped,
-    // Records waiting for a reference's record — see `held` above. Non-empty ⇒ the caller
-    // pushes again once this push has been applied.
-    waiting,
+    // Records that name a record this push creates — see `namesNew` above.
+    namesNew,
     refusals: col.refusals || [],
     schemaless: col.schemaless, localAssets, applied,
     // { stamped, unknown } when identity was applied; null when the caller passed
     // 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 }}