@uniweb/build 0.29.0 → 0.30.0

package/src/uwx/{collections.js → records.js}

@@ -44,15 +44,22 @@ import yaml from 'js-yaml'
 import { detectFoundationType } from '../site/foundation-ref.js'
 import { join, resolve } from 'node:path'
 
-import { resolveCollectionsConfig } from './collections-config.js'
-import { readCollectionRecords } from './collection-source.js'
+import { resolveQueriesConfig } from './queries-config.js'
+import { readEntityFile } from './entity-source.js'
+import { readRecordsConfig, resolveFolder, RECORDS_YML_RELPATH } from '../site/records-config.js'
+import {
+  readEntityPool,
+  groupPoolBySchema,
+  poolPathReadings,
+  poolDirsForSchema,
+} from '../site/entity-pool.js'
 import { toDataSchemaDeclaration, isProseMirrorField, isMarkupTextField, isContentBodyField } from './data-schema.js'
 import { emitEntitySyncPackage } from './entity-document.js'
 import { sha256Hex, toJsonBuffer } from './manifest.js'
 import { markdownToProseMirror } from '@uniweb/content-reader'
 import { LOCALIZED_FIELD_ASSUMPTION, localize } from './localize.js'
 import { localizeScalar, localizeContentDoc, loadLocaleTranslations, discoverLocales, discoverFreeformLocales, localesDir, isLocalizedContent } from './locale-sync.js'
-import { loadFreeformCollectionItem } from '../i18n/freeform.js'
+import { loadFreeformRecord } from '../i18n/freeform.js'
 
 const DATE_KINDS = new Set(['date', 'datetime'])
 // Identity/transport keys on a source record — never Model fields, never warned.
@@ -139,7 +146,7 @@ function encodeFieldValue(value, field, sourceLocale, translations) {
   if (isProseMirrorField(field)) {
     // markdown source → ProseMirror doc. When localized, wrap per-locale exactly
     // like a page section's content (source doc + target structural maps) — same
-    // path, flushed to locales/collections/{locale}.json by the caller.
+    // path, flushed to locales/records/{locale}.json by the caller.
     const doc = typeof value === 'string' ? markdownToProseMirror(value) : value
     if (!field.localized) return doc
     const localized = localizeContentDoc(doc, sourceLocale, Object.keys(translations || {}), translations)
@@ -153,7 +160,7 @@ function encodeFieldValue(value, field, sourceLocale, translations) {
     // A markup `text` BODY (format markdown|html) rides as a RAW string, wrapped
     // per-locale wholesale (its per-string translations live in the i18n manifest /
     // free-form, not the scalar map). Other localized scalars wrap per-string from
-    // locales/collections/{locale}.json.
+    // locales/records/{locale}.json.
     return isMarkupTextField(field)
       ? localize(value, sourceLocale)
       : localizeScalar(value, sourceLocale, translations)
@@ -174,7 +181,7 @@ function encodeFieldValue(value, field, sourceLocale, translations) {
  * already carries `$uuid` (back-filled from a prior sync) round-trips it.
  *
  * @param {object} params
- * @param {string} params.collectionName  - the site.yml collection name
+ * @param {string} params.queryName  - the site.yml collection name
  * @param {object[]} params.records        - [{ slug, ...fields }]
  * @param {object} params.declaration      - the `@uniweb/data-schema` declaration
  *        (from toDataSchemaDeclaration): `{ name, brief, sections }`
@@ -184,15 +191,15 @@ function encodeFieldValue(value, field, sourceLocale, translations) {
  * @returns {{ entities: object[], warnings: string[] }} each entity is
  *   `{ id, uuid, model, file, document }` — `document` is the section-keyed body.
  */
-export function collectionRecordsToEntities({
-  collectionName,
+export function recordsToEntities({
+  queryName,
   records,
   declaration,
   sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale,
   translations,
 }) {
   if (!declaration || !declaration.name) {
-    throw new Error('uwx/collections: a declaration with a name is required')
+    throw new Error('uwx/records: a declaration with a name is required')
   }
   // A record (one source file) maps to the Model's SINGLE sections in declared
   // order — the brief (the card) plus any sibling single sections, e.g. a body
@@ -205,7 +212,7 @@ export function collectionRecordsToEntities({
   const briefEntry = sectionEntries.find(([, s]) => s && s.brief === true)
   const briefName = briefEntry?.[0]
   if (!briefName) {
-    throw new Error(`uwx/collections: Model ${declaration.name} has no brief section`)
+    throw new Error(`uwx/records: Model ${declaration.name} has no brief section`)
   }
   // The single sections one record can populate (the brief + sibling singles).
   //
@@ -254,7 +261,7 @@ export function collectionRecordsToEntities({
   const warnings = []
   if (contentMatches.length > 1) {
     warnings.push(
-      `${collectionName}: ${declaration.name} has more than one content ` +
+      `${queryName}: ${declaration.name} has more than one content ` +
         `(markdown / html / prosemirror) field — the markdown body maps to ` +
         `"${bodyTarget.secName}.${bodyTarget.key}"`
     )
@@ -262,13 +269,13 @@ export function collectionRecordsToEntities({
   for (const record of records || []) {
     const slug = record.slug
     if (!slug) {
-      warnings.push(`${collectionName}: a record without a slug was skipped`)
+      warnings.push(`${queryName}: a record without a slug was skipped`)
       continue
     }
     // `$id` is the payload-local handle = the record's path under collections/
     // (`<collection>/<slug>`), globally unique within one sync so the @uniweb/folder
     // entity can point a leaf at it via `$ref`. An explicit frontmatter `$id` wins.
-    const id = record.$id || `${collectionName}/${slug}`
+    const id = record.$id || `${queryName}/${slug}`
     const uuid = record.$uuid || null
     const hasBody = typeof record.$body === 'string' && record.$body.trim() !== ''
 
@@ -297,13 +304,13 @@ export function collectionRecordsToEntities({
     for (const key of Object.keys(record)) {
       if (SKIP_KEYS.has(key) || fieldByKey.has(key)) continue
       warnings.push(
-        `${collectionName}/${slug}: field "${key}" is not on ` +
+        `${queryName}/${slug}: field "${key}" is not on ` +
           `${declaration.name} — not synced`
       )
     }
     if (hasBody && !bodyTarget) {
       warnings.push(
-        `${collectionName}/${slug}: markdown body present but ` +
+        `${queryName}/${slug}: markdown body present but ` +
           `${declaration.name} has no content body field — body not synced`
       )
     }
@@ -324,9 +331,8 @@ export function collectionRecordsToEntities({
       id,
       uuid,
       slug,
-      collection: collectionName, // the @uniweb/folder groups leaves by this
       model: declaration.name, // reference the Model BY NAME — importer resolves it
-      file: `entities/${collectionName}/${slug}.json`,
+      file: `entities/${queryName}/${slug}.json`,
       document,
     })
   }
@@ -334,14 +340,14 @@ export function collectionRecordsToEntities({
 }
 
 // Post-pass: override a collection record's localized CONTENT body with a per-locale
-// FREE-FORM body when `locales/freeform/{locale}/collections/<col>/<slug>.md` exists
+// FREE-FORM body when `locales/freeform/{locale}/entities/<schema>/<slug>.md` exists
 // — the override wins over the structural map, exactly like site-content sections
 // (site.js localizeContentTree). Only a `format: prosemirror` localized field can
 // take it (it is a PM doc on the wire; a markup `text` body stays a raw string).
 // Mutates the entity documents in place. Async — the free-form read hits the disk.
-async function applyFreeformCollectionOverrides({
+async function applyFreeformRecordOverrides({
   entities,
-  collectionName,
+  queryName,
   declaration,
   sourceLocale,
   targetLocales,
@@ -362,8 +368,8 @@ async function applyFreeformCollectionOverrides({
     // still a bare doc because no structural translation was present).
     const sourceDoc = isLocalizedContent(localized) ? localized[sourceLocale] : localized
     for (const locale of targetLocales) {
-      // loadFreeformCollectionItem returns { content, frontmatter, … } — doc is `.content`.
-      const body = (await loadFreeformCollectionItem({ slug: entity.slug }, collectionName, locale, localesBase))?.content
+      // loadFreeformRecord returns { content, frontmatter, … } — doc is `.content`.
+      const body = (await loadFreeformRecord({ slug: entity.slug }, entity.model, locale, localesBase))?.content
       if (!body) continue
       if (!isLocalizedContent(localized)) localized = { [sourceLocale]: sourceDoc }
       localized[locale] = body // free-form full body overrides the structural map
@@ -377,9 +383,9 @@ async function applyFreeformCollectionOverrides({
 // The collections in site.yml that opt into export (an object decl with `model:`).
 // The declared collections that opt into sync: a resolvable data schema present
 // (explicit or convention-defaulted) and not opted out (`sync: false`). Takes the
-// merged declarations from resolveCollectionsConfig (collections.yml over
+// merged declarations from resolveQueriesConfig (collections.yml over
 // site.yml::collections), so collections.yml is honored without re-reading.
-function syncableCollections(declarations) {
+function syncableQueries(declarations) {
   const out = []
   for (const decl of Object.values(declarations)) {
     if ((decl.schema || decl.model) && decl.sync !== false) out.push({ name: decl.name, decl })
@@ -426,7 +432,7 @@ function loadLocalFoundationSchema(siteRoot, opts, { required }) {
   if (!foundationDir) {
     if (required) {
       throw new Error(
-        'uwx/collections: could not locate a local foundation. Pass foundationDir, ' +
+        'uwx/records: could not locate a local foundation. Pass foundationDir, ' +
           'use a `file:` foundation dependency, or run via `uniweb sync` so non-local ' +
           'Models resolve from the registry.'
       )
@@ -437,7 +443,7 @@ function loadLocalFoundationSchema(siteRoot, opts, { required }) {
   if (!existsSync(schemaPath)) {
     if (required) {
       throw new Error(
-        `uwx/collections: ${schemaPath} not found — build the foundation first ` +
+        `uwx/records: ${schemaPath} not found — build the foundation first ` +
           '(`uniweb build`).'
       )
     }
@@ -467,15 +473,28 @@ function resolveDeclaration(schema, modelName) {
   return null
 }
 
-// Load a collection's ORIGINAL source records for export — the author's files,
+// Load a query's ORIGINAL source records for export — the author's files,
 // untouched (raw frontmatter + raw markdown body, raw YAML/JSON, raw BibTeX). This
-// is deliberately NOT `processCollections` (the delivery pipeline that builds
+// is deliberately NOT `processQueries` (the delivery pipeline that builds
 // public/data, converts bodies to ProseMirror, and copies assets). Sync carries
-// the source. Only file-based (`path:`) collections export; remote (`url:`) data
-// is not a local file collection.
-async function loadSourceRecords(siteRoot, decl) {
-  if (!decl.path) return null // not file-based — caller warns + skips
-  return readCollectionRecords(resolve(siteRoot, decl.path))
+// the source.
+//
+// ⭐ THE QUERY NAMES A SCHEMA AND THE POOL FOLLOWS. It does not name a directory,
+// and there is no disk path for it to name: `entities/{schema}/` declares the
+// model, so the entities of a schema ARE its records. That is the de-conflation —
+// `collections/<name>/` used to answer "which files", "which schema" and "grouped
+// how" with one directory, and only the first two were ever the same question.
+//
+// Remote (`url:`) queries have no local files; the caller warns and skips.
+function loadSourceRecordsFromPool(poolBySchema, decl, placements) {
+  if (!decl.schema) return null
+  const entities = poolBySchema.get(decl.schema)
+  if (!entities) return null
+  // ⛔ ONLY WHAT `records.yml` REFERENCES. An entity of the right schema that no
+  // entry places is not a record, so syncing it would create something nobody can
+  // reach — and would make the payload disagree with the folder describing it.
+  const placed = entities.filter((e) => placements.has(e.id))
+  return placed.length ? placed : null
 }
 
 /**
@@ -500,15 +519,36 @@ async function loadSourceRecords(siteRoot, decl) {
  *   default soft-skip) — not synced as entities; the composite deploy delivers
  *   them statically via the data ball.
  */
-export async function buildCollectionEntities(siteRoot, opts = {}) {
+export async function buildRecordEntities(siteRoot, opts = {}) {
   // Merged collections config (collections.yml over site.yml::collections). Reused
   // from the caller when provided (sync-package shares it with the folder builder).
-  const colConfig = opts.collectionsConfig || (await resolveCollectionsConfig(siteRoot))
+  // ⭐ `records.yml` IS THE FOLDER, AND IT DECIDES WHAT SYNCS. Listing an entity
+  // is what makes it a record; an entity nothing references exists but cannot be
+  // publicly fetched — so it is a draft, for free, with no flag to set. This is
+  // why `collections.yml::sync` is deleted rather than ported: "do not sync" is
+  // now "reference nothing", which is the actual round trip.
+  //
+  // ⛔ AND `missing` IS NOT `empty`. Missing means do not sync at all and leave
+  // the server's folder untouched; empty means sync an empty folder, REMOVING
+  // what is there. The safe state is the absence of a file, so a live folder
+  // cannot be wiped by deleting one — the destructive act requires affirmatively
+  // creating one, and the CLI asks before it happens.
+  //
+  // ⚠️ READ FIRST, ABOVE EVERY EARLY RETURN. `recordsState` has to ride out of
+  // this function on every path, because its ABSENCE reads as "not missing" to a
+  // caller — measured: a site with no queries returned no state, the folder
+  // builder took that for `declared`, and a site with no `records.yml` at all
+  // emitted an empty folder that would have removed everything.
+  const recordsCfg = await readRecordsConfig(siteRoot)
+  if (recordsCfg.error) throw new Error(`uwx/records: ${recordsCfg.error}`)
+  const recordsState = recordsCfg.state
+
+  const colConfig = opts.queriesConfig || (await resolveQueriesConfig(siteRoot))
   if (!colConfig.folderSync) {
-    return { entities: [], index: [], warnings: [], schemaless: [], mappedCount: 0, colConfig }
+    return { entities: [], index: [], warnings: [], schemaless: [], mappedCount: 0, colConfig, recordsState, folder: null }
   }
-  const mapped = syncableCollections(colConfig.declarations)
-  if (mapped.length === 0) return { entities: [], index: [], warnings: [], schemaless: [], mappedCount: 0, colConfig }
+  const mapped = syncableQueries(colConfig.declarations)
+  if (mapped.length === 0) return { entities: [], index: [], warnings: [], schemaless: [], mappedCount: 0, colConfig, recordsState, folder: null }
 
   // A Model declaration comes from a LOCAL foundation (offline) or, for a
   // non-local Model, from the injected async `resolveModel(name)` — the verb wires
@@ -538,19 +578,31 @@ export async function buildCollectionEntities(siteRoot, opts = {}) {
     opts.sourceLocale || LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale
 
   // Target locales for wrapping localized record fields per-locale: those with a
-  // structural-translation file (locales/collections/{locale}.json) UNIONED with
+  // structural-translation file (locales/records/{locale}.json) UNIONED with
   // those that only have a free-form override dir (locales/freeform/{locale}/) — a
   // record localized solely by a free-form body would otherwise go undiscovered.
   const targetLocales = [
-    ...new Set([...discoverLocales(siteRoot, 'collections'), ...discoverFreeformLocales(siteRoot)]),
+    ...new Set([...discoverLocales(siteRoot, 'records'), ...discoverFreeformLocales(siteRoot)]),
   ].filter((l) => l !== sourceLocale)
   const translations =
-    targetLocales.length > 0 ? loadLocaleTranslations(siteRoot, targetLocales, 'collections') : null
+    targetLocales.length > 0 ? loadLocaleTranslations(siteRoot, targetLocales, 'records') : null
 
   const entities = []
   const index = []
   const warnings = []
 
+  // ⭐ THE POOL, READ ONCE. A query names a `schema:` and the entities of that
+  // schema are its records — so the pool is walked once here rather than a
+  // directory per declaration, and two queries over one schema read one set of
+  // files instead of two.
+  const pool = await readEntityPool(siteRoot)
+  const poolBySchema = groupPoolBySchema(pool.entities)
+
+  const folder = resolveFolder(recordsCfg.entries, pool.entities)
+  if (folder.errors.length) {
+    throw new Error(`uwx/records: ${RECORDS_YML_RELPATH} is invalid —\n  ${folder.errors.join('\n  ')}`)
+  }
+
   // ⛔ `@/x` IS A FOUNDATION-RELATIVE ALIAS AND MUST BE RESOLVED BEFORE IT SHIPS.
   //
   // `register` resolves it (`uwx/registry-package.js` builds `scoped` from the
@@ -590,7 +642,7 @@ export async function buildCollectionEntities(siteRoot, opts = {}) {
     // the backend's refusal names a missing Model and cannot name this cause.
     if (modelName === declaredModel && typeof declaredModel === 'string' && declaredModel.startsWith('@/')) {
       warnings.push(
-        `collection "${name}": \`${declaredModel}\` is foundation-relative and no org is known, ` +
+        `query "${name}": \`${declaredModel}\` is foundation-relative and no org is known, ` +
           `so it ships unresolved. The backend resolves Models by name and will refuse it. ` +
           `Pass \`--org @handle\`, or push once so the site records its org.`
       )
@@ -613,19 +665,36 @@ export async function buildCollectionEntities(siteRoot, opts = {}) {
         schemaless.push({ name, model: modelName })
         continue
       }
+      // ⚠️ NAME BOTH READINGS OF A DEPTH-2 POOL PATH. `entities/person/2024/ada.md`
+      // resolves as `@person/2024` — the rule is total, so it is not ambiguous —
+      // but an author who meant "records organised by year inside the `person`
+      // schema" needs to be told what the build actually read, not only that
+      // something failed to resolve. The wrong reading is the plausible one.
+      const dirs = poolDirsForSchema(modelName)
+      const { alternative } = dirs ? poolPathReadings(dirs) : { alternative: null }
       throw new Error(
-        `uwx/collections: Model "${modelName}" (collection "${name}") could not be ` +
+        `uwx/records: Model "${modelName}" (query "${name}") could not be ` +
           'resolved — not defined by a local foundation' +
           (resolveModel
             ? ', and the backend has no such Model (register it first).'
             : '. Run via `uniweb sync` (which fetches non-local Models from the ' +
-              'registry), or provide a local foundation that defines it.')
+              'registry), or provide a local foundation that defines it.') +
+          (alternative
+            ? ` If you meant \`entities/${dirs[0]}/\` (${alternative}) organised by ` +
+              `\`${dirs[1]}\`, note that a folder inside a schema folder is read as an ` +
+              `org scope. Organise records in records.yml, not on disk.`
+            : '')
       )
     }
-    const sourceRecords = await loadSourceRecords(siteRoot, decl)
-    if (sourceRecords == null) {
+    const poolEntities = loadSourceRecordsFromPool(poolBySchema, decl, folder.placements)
+    if (poolEntities == null) {
+      // No entities of this schema on disk. A remote (`url:`) query has none by
+      // definition; a file-based one with an empty pool is an author state worth
+      // naming, because "nothing synced" and "nothing there" look identical.
       warnings.push(
-        `${name}: not a file-based (\`path:\`) collection — skipped`
+        decl.url
+          ? `${name}: a remote (\`url:\`) query has no local entities — skipped`
+          : `${name}: no entities of ${decl.schema} in the pool — nothing to sync`
       )
       continue
     }
@@ -636,19 +705,30 @@ export async function buildCollectionEntities(siteRoot, opts = {}) {
     // deferred (no single-record file to rewrite in place).
     const flat = []
     const sourceBySlug = new Map()
-    for (const r of sourceRecords) {
-      if (!r.slug) {
-        warnings.push(`${name}: a record without a slug was skipped`)
-        continue
+    for (const pooled of poolEntities) {
+      for (const r of await readEntityFile(pooled.absPath)) {
+        if (!r.slug) {
+          warnings.push(`${name}: a record without a slug was skipped`)
+          continue
+        }
+        const rec = { ...r.data, slug: r.slug }
+        if (r.body !== undefined) rec.$body = r.body
+        // ⭐ THE RECORD'S IDENTITY IS ITS POOL POSITION, not `<query>/<slug>`. It
+        // has to be: the folder places entities and must reference the very ones
+        // the payload carries, and two queries over one schema would otherwise
+        // mint two identities for one file. `<dirs>/<slug>` is unique by
+        // construction and derivable on both sides.
+        //
+        // ⚠️ 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('/')
+        flat.push(rec)
+        sourceBySlug.set(r.slug, r)
       }
-      const rec = { ...r.data, slug: r.slug }
-      if (r.body !== undefined) rec.$body = r.body
-      flat.push(rec)
-      sourceBySlug.set(r.slug, r)
     }
 
-    const mappedOut = collectionRecordsToEntities({
-      collectionName: name,
+    const mappedOut = recordsToEntities({
+      queryName: name,
       records: flat,
       declaration,
       sourceLocale,
@@ -657,9 +737,9 @@ export async function buildCollectionEntities(siteRoot, opts = {}) {
     // Free-form per-locale body overrides (a full localized doc beats the structural
     // map) — only meaningful for a multi-locale site with a prosemirror content field.
     if (targetLocales.length > 0) {
-      await applyFreeformCollectionOverrides({
+      await applyFreeformRecordOverrides({
         entities: mappedOut.entities,
-        collectionName: name,
+        queryName: name,
         declaration,
         sourceLocale,
         targetLocales,
@@ -670,8 +750,8 @@ export async function buildCollectionEntities(siteRoot, opts = {}) {
       const dupKey = `${e.model} ${e.id}`
       if (seen.has(dupKey)) {
         throw new Error(
-          `uwx/collections: duplicate ($model, $id) in one sync — "${e.id}" of ` +
-            `${e.model} appears in more than one collection. Each ($model, $id) ` +
+          `uwx/records: duplicate ($model, $id) in one sync — "${e.id}" of ` +
+            `${e.model} appears in more than one query. Each ($model, $id) ` +
             'must be unique within a sync; make the slugs unique.'
         )
       }
@@ -699,7 +779,7 @@ export async function buildCollectionEntities(siteRoot, opts = {}) {
     warnings.push(...mappedOut.warnings)
   }
 
-  return { entities, index, warnings, schemaless, mappedCount: mapped.length, colConfig }
+  return { entities, index, warnings, schemaless, mappedCount: mapped.length, colConfig, folder, recordsState }
 }
 
 /**
@@ -734,28 +814,31 @@ export function filterChanged(entities, index, { priorHashes = {}, sendAll = fal
 
 /**
  * Build a collection-only sync package. Thin composition over
- * `buildCollectionEntities` + `filterChanged` + `emitEntitySyncPackage`, kept for
+ * `buildRecordEntities` + `filterChanged` + `emitEntitySyncPackage`, kept for
  * the collection-only callers/tests. The combined site+collections path is
  * `emitSyncPackage` (sync-package.js).
  *
  * @param {string} siteRoot
- * @param {object} [opts] - buildCollectionEntities opts, plus `priorHashes`,
+ * @param {object} [opts] - buildRecordEntities opts, plus `priorHashes`,
  *        `sendAll`, `exporter`, `exportedAt`.
  * @returns {Promise<{ buffer: Buffer|null, models: string[], entityCount: number,
  *        warnings: string[], index: object[], hashes: Object<string,string>,
  *        skipped: number }>}
  */
-export async function emitCollectionSyncPackage(siteRoot, opts = {}) {
-  const { entities, index, warnings, mappedCount } = await buildCollectionEntities(siteRoot, opts)
+export async function emitRecordSyncPackage(siteRoot, opts = {}) {
+  const { entities, index, warnings, mappedCount } = await buildRecordEntities(siteRoot, opts)
   if (mappedCount === 0) {
     throw new Error(
-      'uwx/collections: no collection declares `model:` — nothing to export. ' +
-        'Add `model: "@org/name"` to a collection in site.yml.'
+      'uwx/records: no query declares a schema — nothing to export. ' +
+        'Add a query to queries.yml naming the schema its records use, e.g.\n' +
+        "  articles:\n    schema: '@/article'"
     )
   }
   if (entities.length === 0) {
     throw new Error(
-      'uwx/collections: no records to export (mapped collections were empty or skipped)'
+      'uwx/records: no records to export. Either records.yml references ' +
+        'nothing, or every query matched an empty pool — an entity is only a ' +
+        'record once records.yml lists it.'
     )
   }
 

package/src/uwx/site-diff.js

@@ -46,7 +46,7 @@
 // Either base may be missing; the affected side degrades to "unknown" and is
 // reported as unattributed rather than guessed at.
 
-import { entityContentHash } from './collections.js'
+import { entityContentHash } from './records.js'
 import { recordStableId, safeStableIdFilename, pageDirName } from './site-project.js'
 import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
 
@@ -292,3 +292,26 @@ export function describeSiteDiff(diff, { limit = 8 } = {}) {
   }
   return lines
 }
+
+
+/**
+ * Query-declaration identity from a document the BACKEND produced (a pull, or a
+ * push response's `finalized[].document`): `{ <query name>: <$uuid> }`.
+ *
+ * ⛔ The sibling of collectFolderItemUuids, and it exists for the same reason: these
+ * items have no file of their own, so nothing in a path-keyed map can hold their
+ * identity, and a push that omits it re-sends the whole section uuid-less. The
+ * backend refuses that rather than deleting every stored row — see queriesNested.
+ *
+ * Keyed by `name`, which the backend enforces unique within the section. `$id` is
+ * deliberately not consulted: it is a payload-local handle the backend never stores.
+ */
+export function collectQueryUuids(doc) {
+  const out = {}
+  for (const item of doc?.queries || []) {
+    const name = item?.name
+    const uuid = item?.$uuid
+    if (typeof name === 'string' && typeof uuid === 'string' && name && uuid) out[name] = uuid
+  }
+  return out
+}

package/src/uwx/site-project.js

@@ -38,7 +38,8 @@ import { readFileSync, existsSync, unlinkSync, renameSync, rmSync, readdirSync,
 import { createHash } from 'node:crypto'
 import yaml from 'js-yaml'
 import { writeSiteConfig, writeThemeFile, writeIfChanged, writeSectionFile, writeMergedYaml } from './project-writer.js'
-import { declarationsToCollectionsYml } from './collections-project.js'
+import { declarationsToQueriesYml } from './records-project.js'
+import { authorableFetch } from '../site/fetch-shapes.js'
 import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations, unwrapLocalizedContent } from './locale-sync.js'
 import { buildFreeformPath } from '../i18n/freeform.js'
 import { unwrapLocalized, unwrapLocalizedList } from './backfill.js'
@@ -303,7 +304,8 @@ export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED
   if (theme_override !== undefined) frontmatter.theme = theme_override
   if (preset !== undefined) frontmatter.preset = preset
   if (input !== undefined) frontmatter.input = input
-  if (fetch !== undefined) frontmatter.fetch = fetch
+  // Invert the build's resolution rather than copy it — see fetch-shapes.js.
+  if (fetch !== undefined) frontmatter.fetch = authorableFetch(fetch)
   if (stable_id !== undefined) frontmatter.id = stable_id
 
   const body = insets ? reinlineInsets(sourceContent, insets) : sourceContent
@@ -424,7 +426,8 @@ function pageRecordToYml(record, sectionsArray, sourceLocale) {
   if (record.rewrite !== undefined) y.rewrite = record.rewrite
   if (record.layout !== undefined) y.layout = record.layout
   if (record.seo !== undefined) y.seo = record.seo
-  if (record.fetch !== undefined) y.fetch = record.fetch
+  // Invert the build's resolution rather than copy it — see fetch-shapes.js.
+  if (record.fetch !== undefined) y.fetch = authorableFetch(record.fetch)
   // `sections:` exists to preserve ORDER and NESTING, which the projected filenames
   // can't carry (they're `<stableId>.md`, with no numeric prefix). It must not also
   // decide MEMBERSHIP — and a bare list does: the collector reads a list without
@@ -625,12 +628,12 @@ function projectLayout(layoutSections, layoutBaseDir, report, prune, ctx) {
 /**
  * Project a whole `@uniweb/site-content` document to a site's files: `info` →
  * config (siteInfoToConfig), `collections[]` declarations →
- * `collections.yml::collections` (declarationsToCollectionsYml), `pages[]` →
+ * `collections.yml::collections` (declarationsToQueriesYml), `pages[]` →
  * `pages/**`, `layout_sections` → `layout/**`. Idempotent. Matches by
  * stableId-name (clean overwrite); orphan deletion + content-similarity matching
  * is the reconcile layer.
  *
- * The collection RECORDS are the separate collections lane (collectionsToProject);
+ * The collection RECORDS are the separate collections lane (recordsToProject);
  * this writes only their config declarations.
  *
  * @param {object} params
@@ -658,7 +661,7 @@ export function siteContentDocumentToProject({ document, siteRoot, sourceLocale
   report.assets = restoreAssetRefs(document, readAssetMap(siteRoot))
 
   report.config = siteInfoToConfig({ document, siteRoot, sourceLocale, collector, keepAuthoredFoundation })
-  report.collections = declarationsToCollectionsYml({ document, siteRoot })
+  report.queries = declarationsToQueriesYml({ document, siteRoot })
 
   // The uuid identity index (gitignored `.uniweb/`): read the prior map to anchor
   // rename detection, build a fresh one as we project, then persist it. Items not