@uniweb/build 0.29.1 → 0.30.1

package/src/uwx/site.js

@@ -10,7 +10,7 @@
 //
 // The document mirrors the @uniweb/site-content Model: `info` (brief) · `pages`
 // (self-nesting; each page carries its `page_sections` as an inline field) ·
-// `layout_sections` · `extensions` · `collections`. `info.foundation`
+// `layout_sections` · `extensions` · `queries`. `info.foundation`
 // carries the verbatim `site.yml::foundation` string (the round-trip source of
 // truth).
 //
@@ -54,13 +54,13 @@ import {
   processMarkdownFile,
 } from '../site/content-collector.js'
 import { normalizeHideIn } from '../site/nav-visibility.js'
-import { resolveDefaultLocale, validateLanguageConfig, collectionDataUrl } from '@uniweb/core'
+import { resolveDefaultLocale, validateLanguageConfig, queryDataUrl } from '@uniweb/core'
 import { emitEntitySyncPackage } from './entity-document.js'
 import { loadLocaleTranslations, localizeScalar, localizeScalarList, localizeContentDoc, localesDir, isLocalizedContent } from './locale-sync.js'
 import { unwrapLocalized } from './backfill.js'
 import { loadFreeformTranslation } from '../i18n/freeform.js'
 import { upsertYamlScalar } from './yaml-upsert.js'
-import { resolveCollectionsConfig } from './collections-config.js'
+import { resolveQueriesConfig } from './queries-config.js'
 
 const SITE_ENTITY_KEY = 'site-content' // one content entity per site project
 
@@ -223,36 +223,43 @@ function buildPageData(config, ctx) {
   let fetch =
     config.fetch ??
     (config.data
-      ? { collection: Array.isArray(config.data) ? config.data[0] : config.data }
+      ? { query: Array.isArray(config.data) ? config.data[0] : config.data }
       : undefined)
-  // Resolve the build-time `collection:` shorthand to the runtime-fetchable
+  // Resolve the authored `query:` shorthand to the runtime-fetchable
   // `path: /data/<name>.json` (the static convention the default-fetcher uses).
   // A shell/backend-hosted site renders client-side with NO prerender, so the
-  // runtime fetches this decl directly — and `collection:` is build-time-only, so
+  // runtime fetches this decl directly — and `query:` is build-time-only, so
   // it would never resolve at render (the static build resolves it the same way
   // in site/data-fetcher.js parseFetchConfig). The gateway serves the collection
   // at `<base>/data/<name>.json`.
-  if (fetch && typeof fetch.collection === 'string') {
-    const { collection, ...rest } = fetch
+  if (fetch && typeof fetch.query === 'string') {
+    const { query, ...rest } = fetch
     // ⭐ BOTH, deliberately, and they are not redundant.
     //
-    //   `collection` — the author's query, unresolved. A consumer that can ask
-    //     a host where collections live (`config.records`) resolves it there,
-    //     which is the only way a live lane is reachable at all: a resolved
-    //     path names one place and closes the question.
+    //   `query` — the author's named query, unresolved. A consumer that can ask
+    //     a host where records live (`config.records`) resolves it there, which
+    //     is the only way a live lane is reachable at all: a resolved path names
+    //     one place and closes the question.
     //
     //   `path` — the compiled artifact, the answer when nobody declares a lane.
     //     Also what a consumer still reading `fetch.path` gets, so teaching the
     //     wire a new field does not break one that has not learned it.
     //
-    // `@uniweb/core`'s resolveFetchConfigs gives `collection` precedence and
-    // drops `path` once it has resolved an address — matching parseFetchConfig,
-    // which has always returned early on `collection`.
+    // `@uniweb/core`'s resolveFetchConfigs gives the query precedence and drops
+    // `path` once it has resolved an address — matching parseFetchConfig, which
+    // has always returned early on the shorthand.
     //
-    // `schema` (the collection name) is BOTH the content.data key and part of the
+    // `schema` (the query name) is BOTH the content.data key and part of the
     // dataStore cache key (deriveCacheKey hashes {path,url,endpoint,schema,…};
-    // `collection` is ignored). Mirrors the static build's parseFetchConfig.
-    fetch = { collection, path: collectionDataUrl(collection), schema: collection, ...rest }
+    // the shorthand is ignored). Mirrors the static build's parseFetchConfig.
+    // ⭐ `query`, END TO END — no crossing. An earlier version emitted `collection`
+    // here on the belief that this field was the backend's to name. MEASURED
+    // otherwise: framework already ships `transform`, `detailPage`, `merge` and
+    // `prerender` inside this same `fetch` object, which no backend could be
+    // validating — so `fetch` is a blob they carry and framework owns its
+    // vocabulary. ⇒ There was nothing to coordinate, and inventing a coordination
+    // is how a name stays wrong.
+    fetch = { query, path: queryDataUrl(query), schema: query, ...rest }
   }
   setIf(data, 'fetch', fetch)
   if (isDynamic) {
@@ -667,11 +674,91 @@ export function isSiteRelativeExtensionUrl(decl) {
  * rename every collection at once and the section goes all-blank and is refused.
  * That is the semantics, not a defect.
  *
+ * ⛔ DO NOT TRIM THE FIELDS BELOW, even the ones the backend never reads.
+ *
+ * The backend destructures exactly two — `name` and `schema` — and projects none of
+ * this Section into a published payload, so the rest read as dead weight. ⛔ THEY ARE
+ * OURS, AND THAT IS REASON ENOUGH: `excerpt`, `deferred`, `detailUrl` and `queryable`
+ * are read across FRAMEWORK's own runtime, build and kit — `useQueryable`
+ * is a public hook a foundation calls to render a filter UI. They drive the file
+ * lane, where they work. "The backend does not read it" was never an argument that
+ * nothing reads it.
+ *
+ * ⚠️ There may be a second reason, and it is NOT ours to assert. Backend states that
+ * their decl type reaches the app lane verbatim and that their reconcile
+ * replaces an item's `data` wholesale with no field-grain merge — from which an
+ * omitted field the EDITOR set would be destroyed on the next push. The mechanism is
+ * their code and theirs to state. **Whether the editor reads or writes this decl at
+ * all is FRONTEND's, and neither framework nor backend has established it.** Treat it
+ * as an open hypothesis, not a fact — see the doc below.
+ *
+ * ⚠️ Separately measured: framework does not emit `label` and has no such collection
+ * field — ours belongs to a `folders:` BRANCH. Backend's fixture asserted we mirror a
+ * `site.yml collections.<name>.label`; no such field has ever existed, and they have
+ * corrected it.
+ *
+ * ⇒ Full record, including what is established vs merely claimed:
+ * `kb/framework/build/collections-decl-open-questions.md`.
+ *
  * @param {object} declarations resolved collection declarations, keyed by name
  * @param {Object<string,string>} [uuids] `name` → backend `$uuid`, from a push
  *        response or a pull. Absent on a first sync, where minting is correct.
  */
-function collectionsNested(declarations, uuids = null) {
+// ⛔ KEYS THAT MUST NOT REACH THE WIRE. Everything else on an authored declaration
+// is emitted, including fields this build does not model — see the note in
+// `queriesNested`. Enumerated here rather than inverted into an allowlist
+// because framework OWNS this vocabulary and can therefore enumerate it
+// truthfully; it does not own the Model's, and cannot.
+//
+// Sources, both framework's own: `site/query-processor.js::parseQueryConfig`
+// (the decl parser) and `site/queries-config.js` (normalization). Pinned by
+// `tests/uwx-decl-unmodelled-fields.test.js`, which fails if either gains a field
+// that is neither emitted nor listed here.
+// Authored keys the explicit block in `queriesNested` already consumes. Kept
+// separate from the framework-local set below because these DO reach the wire —
+// just under a wire spelling. ⚠️ `detailUrl` is the one that matters: it is emitted
+// as `detail_url`, so a pass-through keyed on "is it already in `data`?" does not
+// see it and the field rides TWICE. Measured 2026-08-29, in the first draft of this
+// very change — and the push test missed it because both its controls (`limit`,
+// `schema`) keep their names.
+const DECL_EMITTED_ABOVE = new Set([
+  'source',
+  'schema',
+  'sort',
+  'where',
+  'limit',
+  'excerpt',
+  'deferred',
+  'detailUrl',
+  'queryable'
+])
+
+const DECL_NOT_ON_WIRE = new Set([
+  // Identity — rides as the record's own `name`, not inside `data`.
+  'name',
+  // Folded into `source` above.
+  'path',
+  'url',
+  // Folded into `schema` above (the migration synonym).
+  'model',
+  // Build state: whether the AUTHOR asked for the schema or the subfolder-name
+  // convention supplied it. Decides hard-error vs soft-skip during sync;
+  // `collections-config.js::toConfigQueries` strips it downstream too.
+  'schemaExplicit',
+  // ⭐ FRAMEWORK-LOCAL, and the one that proves the rule. `route:` is a real
+  // authored field — `parseQueryConfig` reads it, and `collectItems` composes
+  // each item's link as `<route>/<slug>` — but the backend's Model has no slot for
+  // it, so emitting it would be sending build-time config to a store that validates
+  // against a declared schema. Measured 2026-08-29: a first version of this change
+  // passed unknown keys through blindly and would have started sending `route` from
+  // every site that declares one.
+  'route',
+  // Legacy predicate, translated to the canonical `where` upstream. No legacy
+  // fields on the wire.
+  'filter'
+])
+
+function queriesNested(declarations, uuids = null) {
   const out = []
   for (const [name, d] of Object.entries(declarations)) {
     const data = {}
@@ -687,6 +774,33 @@ function collectionsNested(declarations, uuids = null) {
     setIf(data, 'deferred', d.deferred)
     setIf(data, 'detail_url', d.detailUrl)
     setIf(data, 'queryable', d.queryable)
+    // ⛔ EMIT WHAT WE DO NOT MODEL. The decl's field set is the BACKEND's Model
+    // (this document mirrors `@uniweb/site-content` — see the lane header), and
+    // their reconcile replaces `data` WHOLESALE with no field-grain merge. So an
+    // allowlist here does not merely fail to send an unmodelled field: it DESTROYS
+    // whatever was stored under it, silently, on every push.
+    //
+    // ⚠️ Measured 2026-08-29: the Model declares ELEVEN decl fields and this emitter
+    // knew ten. The eleventh is `label`, which framework has no authoring concept
+    // for — `label` in framework is a `folders:` BRANCH field (`{segment, label,
+    // entries}`), not a property of a collection.
+    //
+    // ⭐ `label` is the instance, not the defect. Any field the Model gains that we
+    // have not taught this function repeats it, and nothing reports the loss. Hence
+    // a DENY-list: framework can enumerate its own vocabulary truthfully and cannot
+    // enumerate the Model's, so the safe inversion is "withhold what is ours".
+    //
+    // ⚖️ We do NOT warn on an unrecognized key. Framework cannot tell a valid Model
+    // field from a typo — only the server can, and it validates every write against
+    // the declared schema. Its rejection is the honest signal; a guess from here
+    // would cry wolf on every legitimate new field. Same rule and same reasoning as
+    // `site/fetch-shapes.js`: drop only what is DERIVABLE, never what is merely
+    // unrecognized.
+    for (const [key, value] of Object.entries(d)) {
+      if (value === undefined) continue
+      if (DECL_EMITTED_ABOVE.has(key) || DECL_NOT_ON_WIRE.has(key)) continue
+      data[key] = value
+    }
     const rec = withIdentity(name, { name, ...data })
     const uuid = uuids?.[name]
     if (typeof uuid === 'string' && uuid) rec.$uuid = uuid
@@ -695,6 +809,121 @@ function collectionsNested(declarations, uuids = null) {
   return out
 }
 
+// ── `services` + `secrets` — a site's own service records ─────────────────────
+//
+// ⭐ THE FILE KEYS ARE `$services` / `$secrets`, NOT `services` / `secrets`, and the
+// `$` is load-bearing rather than decorative. `site.yml::services` is ALREADY TAKEN,
+// on the other lane: the bundle lane spreads site.yml whole into the payload, so a
+// `services:` block there lands at `config.services` — the HOST tier — which is the
+// documented way to simulate a host locally (`kit/src/utils/submitTarget.js`).
+// Reusing the name would give one key two meanings that differ per lane, which is
+// the shape of bug nobody finds.
+//
+// `$` already means "backend-scoped, round-tripped, not hand-authored" in this file
+// (`$uuid`, `$org`, `$backend`), and that is exactly what these are: a service's
+// config is bound where the service is provisioned, and arrives here by `pull`.
+//
+// ⚖️ WHAT THESE ARE NOT. A site's OWN service declarations — `search:`, `submit:`,
+// `assistant:`, `tracking:` — stay top-level `info.*` keys and are untouched. Those
+// are authored, they resolve at the SITE tier (`config.<name>`, first choice in
+// `@uniweb/core`'s `resolveService`), and moving them here would flip them to the
+// host tier, where a block's mere presence declines every service it does not name.
+// These Sections carry the services a site is PROVISIONED with — `api` above all,
+// which has no file-authored form because it is bought, not declared.
+//
+// ⛔ ABSENT IS NOT EMPTY, and the difference is destructive. The Section is
+// REPLACED by what we send, so `[]` means "drop every stored config row" while a
+// missing key means "I am not telling you about this". A project that has never
+// pulled has no `$services`, and its ordinary push must not read as a request to
+// wipe a service the operator configured in the app. So: emit the Section only when
+// the file declares the key. Clearing is available and explicit — `$services: []`.
+//
+// ⚠️ The push gate is NOT what makes this safe, though it usually catches it: its
+// tokens live in a gitignored per-clone cache, so a fresh clone pushes
+// unconditionally. Correctness has to sit here.
+
+/**
+ * `$services` / `$secrets` → Section records, or undefined when the key is absent.
+ *
+ * ⭐ PASSTHROUGH, NOT AN ALLOWLIST — the same rule and the same reason as
+ * `queriesNested` above. The field set belongs to the backend's Model, a service's
+ * `config` is opaque and per-service, and reconcile replaces `data` wholesale — so
+ * enumerating keys here would not merely fail to send a field we do not know, it
+ * would DESTROY whatever is stored under it on every push. Framework can enumerate
+ * its own vocabulary and cannot enumerate theirs; withhold ours, forward the rest.
+ *
+ * @param {*} declared - the raw `$services` / `$secrets` value from site.yml
+ * @param {(entry: object) => string|null} identify - the record's stable `$id`
+ * @param {string} label - the key name, for the one warning below
+ * @returns {object[]|undefined}
+ */
+function serviceRecords(declared, identify, label) {
+  if (declared === undefined || declared === null) return undefined
+  if (!Array.isArray(declared)) {
+    console.warn(
+      `uwx/site: \`${label}:\` must be a list of entries — ignoring a ${typeof declared}.`
+    )
+    return undefined
+  }
+  const out = []
+  for (const entry of declared) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue
+    const id = identify(entry)
+    // ⚠️ `name` is OUR OWN declared-required field, so a warning here is honest —
+    // unlike an unrecognized key, which only the server can judge. And the loss is
+    // otherwise invisible: on a replaced Section a dropped entry reads as a
+    // deliberate removal of its config row.
+    if (!id) {
+      console.warn(
+        `uwx/site: \`${label}:\` has an entry with no \`name\` — skipping it. On a replaced ` +
+          'section a dropped entry reads as a deliberate removal of its config.'
+      )
+      continue
+    }
+    const data = {}
+    for (const [key, value] of Object.entries(entry)) {
+      if (value === undefined) continue
+      data[key] = value
+    }
+    out.push(withIdentity(id, data))
+  }
+  return out
+}
+
+/** One service per `name` — the same keyspace `config.services` uses at runtime. */
+function servicesNested(siteYml) {
+  return serviceRecords(
+    siteYml.$services,
+    (e) => (typeof e.name === 'string' && e.name ? e.name : null),
+    '$services'
+  )
+}
+
+/**
+ * One secret per `(service, name)` — the pair the backend merges on. A site-level
+ * secret belongs to no service, so `service` is optional and the handle degrades to
+ * the bare name.
+ *
+ * ⛔ `value` IS FORWARDED VERBATIM, INCLUDING A LITERAL. A pulled secret carries the
+ * marker `#ref` meaning "a secret is set", never the value, and pushing the marker
+ * back means "leave it alone" — so the ordinary round trip sends nothing sensitive.
+ * A literal typed into the file is refused by the server, which is where that
+ * judgement belongs; framework does not strip it, because silently dropping a value
+ * an author typed would leave them believing a secret was set.
+ */
+function secretsNested(siteYml) {
+  return serviceRecords(
+    siteYml.$secrets,
+    (e) => {
+      if (typeof e.name !== 'string' || !e.name) return null
+      return typeof e.service === 'string' && e.service
+        ? `${e.service}:${e.name}`
+        : e.name
+    },
+    '$secrets'
+  )
+}
+
 /**
  * Map a file site project to the nested `@uniweb/site-content` `$`-document
  * (see the lane header above). PURE — reads the project, never mints, never writes.
@@ -709,7 +938,7 @@ function collectionsNested(declarations, uuids = null) {
  *        the site's effective default locale (`defaultLanguage || languages[0] ||
  *        'en'` — the shared `resolveDefaultLocale` rule), NOT a bare 'en'.
  * @returns {Promise<object>} the section-keyed `$`-document:
- *        `{ $uuid?, $id, $model, info, pages, layout_sections, extensions, collections }`
+ *        `{ $uuid?, $id, $model, info, pages, layout_sections, extensions, queries }`
  */
 export async function siteProjectToDocument(siteRoot, opts = {}) {
   const siteYml = await readYamlFile(join(siteRoot, 'site.yml'))
@@ -843,13 +1072,38 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // secret store is the only right home either way.
 
   setIf(info, 'tracking', stripCredentials(siteYml.tracking, 'tracking'))
+  // ⛔ `api` IS DELIBERATELY NOT HERE, and this note exists because every comment
+  // above it argues the opposite — three services are on this allowlist precisely so
+  // an authored block cannot work on a static host and vanish on the synced one.
+  // Without this paragraph the next reader adds the missing fourth line and calls it
+  // a bug fix.
+  //
+  // ⭐ `api` is the one service a site does not AUTHOR. It is a real backend that is
+  // provisioned and paid for, so its address is the host's to supply — it arrives as
+  // `config.services.api` and `@uniweb/api` reads it there (`resolveBase`). An
+  // authored `api:` is the SITE tier, which outranks the host permanently.
+  //
+  // ⇒ Carrying it would turn a local-dev override into a production one the moment
+  // someone pushed: the host would store `info.api` and serve it back as `config.api`,
+  // which wins over the address of the backend the site actually has. The vanish on
+  // this lane is the correct behaviour, not the bug the comments above describe —
+  // there, a dropped block leaves a site with NO endpoint; here it leaves the site
+  // with the RIGHT one.
+  //
+  // The provisioned record rides the `$services` section instead (see servicesNested).
   setIf(info, 'paths', siteYml.paths)
   setIf(info, 'data', siteYml.data ?? siteYml.fetch)
-  // `app` — the deployment's `@uniweb/app-spec` reference (a bare uuid string),
-  // bound when the site is hosted as a composite. Authored config that round-trips
-  // verbatim/opaque (like `foundation`), so a pull→edit→push preserves it; it is
-  // deployment-LOCAL (not portable across deployments). (uwx-format.md → info.app.)
-  setIf(info, 'app', siteYml.app)
+  // ⛔ `app` IS RETIRED — do not reintroduce it, in either direction. It carried an
+  // opaque uuid naming a separate entity a host bound to the site; that entity is
+  // gone, a site's services belong to the site itself, and NOTHING replaces the key.
+  //
+  // ⚠️ Removing the emit is the FIRST of two steps and the order is forced: a host
+  // refuses a key it does not declare, so the producer stops sending before the
+  // declaration is dropped. The reverse order fails every push in between.
+  //
+  // ✅ Unobservable, because nothing ever originated the key — no template writes
+  // `site.yml::app`. The line round-tripped a value that was never set.
+  // (uwx-format.md → info.app.)
   // `template: true` designates this site as a clonable SITE-TEMPLATE: on push the
   // backend applies a clonability designation to this site-content entity (it is
   // NOT a registry artifact). Verbatim; absent → a normal (non-template) site.
@@ -881,7 +1135,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
 
   // Collection DECLARATIONS — the merged collections.yml + site.yml::collections
   // config (the records themselves are separate entities; this is just the config).
-  const colConfig = await resolveCollectionsConfig(siteRoot, { siteYml })
+  const colConfig = await resolveQueriesConfig(siteRoot, { siteYml })
 
   // `$uuid?` then `$id` `$model`, then sections in Model-declared order. The entity
   // `$uuid` lives in site.yml (back-filled after first sync); absent on first sync.
@@ -895,7 +1149,21 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   doc.pages = pages
   doc.layout_sections = layoutSections
   doc.extensions = extensionsNested(siteYml)
-  doc.collections = collectionsNested(colConfig.declarations, opts.collectionUuids)
+  // ⭐ THE SECTION IS `queries`. Backend renamed it on `@uniweb/site-content`
+  // (2026-08-29) and explains it as named queries — content that is RESOLVED AT
+  // RUNTIME rather than rendered, which is framework's own model of it
+  // (`records-model.md` §1: a query is second-order site content).
+  //
+  // ⚠️ `queriesNested` keeps its name. §2's rule: rename what an author or a
+  // consumer sees, leave the identifier alone.
+  doc.queries = queriesNested(colConfig.declarations, opts.queryUuids)
+  // 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.
+  const services = servicesNested(siteYml)
+  if (services) doc.services = services
+  const secrets = secretsNested(siteYml)
+  if (secrets) doc.secrets = secrets
   return doc
 }
 

package/src/uwx/sync-package.js

@@ -2,7 +2,7 @@
 // lanes, each its own `.uwx`:
 //
 //   - site-content lane  → one `@uniweb/site-content` entity (the static half).
-//   - collections lane   → one `@uniweb/folder` entity + the collection records it
+//   - records lane      → one `@uniweb/folder` entity + the record entities it
 //                          references (the dynamic half; the `$ref` closure rides
 //                          together so brand-new records resolve in one call).
 //
@@ -14,12 +14,12 @@
 //
 // "Send only changed" spans both lanes via one content-hash map (the sync-cache):
 //   - site-content lane fires iff the site entity changed.
-//   - collections lane fires iff the folder changed OR any record changed — and when
+//   - records lane fires iff the folder changed OR any record changed — and when
 //     it fires it carries the FULL folder (for the `$ref` closure + binding) plus the
-//     changed records. An untouched site with collections pushes nothing on either
+//     changed records. An untouched site with records pushes nothing on either
 //     lane (the idempotent no-op).
 
-import { buildCollectionEntities, entityContentHash } from './collections.js'
+import { buildRecordEntities, entityContentHash } from './records.js'
 import { ASSET_SLOTS } from '@uniweb/semantic-parser'
 import { buildFolderEntity } from './folder.js'
 import { siteProjectToDocument } from './site.js'
@@ -235,11 +235,11 @@ function rewriteEntityAssets(node, map, ids) {
  * @param {object} [opts.exporter] @param {string} [opts.exportedAt]
  * @returns {Promise<{
  *   siteContent: { buffer, entityCount, index, models }|null,
- *   collections: { buffer, entityCount, index, models }|null,
+ *   records: { buffer, entityCount, index, models }|null,
  *   hashes: Object<string,string>, warnings: string[], skipped: number,
  *   schemaless: Array<{name: string, model: string}>, localAssets: string[],
  *   applied: object }>}
- *   `schemaless` lists collections that resolved no data schema (soft-skipped from
+ *   `schemaless` lists queries that resolved no data schema (soft-skipped from
  *   the sync) — the composite deploy delivers these statically via the data ball.
  *   `localAssets` lists the site-root local media refs (`/images/x.png`) the deploy
  *   must upload + rewrite to serve URLs; co-located refs are warned and skipped.
@@ -247,7 +247,7 @@ function rewriteEntityAssets(node, map, ids) {
  *   (`assetRewrite` / `assetIds` / `injectInfo` / `injectExtensions`), ready to be
  *   passed straight back as opts. A caller that banks the `hashes` must bank this
  *   beside them, or an offline re-emit cannot reproduce the document they describe.
- *   Each lane is null when it has nothing to push. The collections `index` keeps a
+ *   Each lane is null when it has nothing to push. The records `index` keeps a
  *   leading `{ kind: 'folder' }` placeholder (submission position 0 → the folder
  *   entity) so record back-fill stays positionally aligned; the folder itself has no
  *   uuid to back-fill.
@@ -261,22 +261,31 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   const exporter = opts.exporter
   const exportedAt = opts.exportedAt
 
-  const col = await buildCollectionEntities(siteRoot, {
+  const col = await buildRecordEntities(siteRoot, {
     ...(opts.foundationDir ? { foundationDir: opts.foundationDir } : {}),
     ...(opts.resolveModel ? { resolveModel: opts.resolveModel } : {}),
     ...(sourceLocale ? { sourceLocale } : {}),
     // The publish org — resolves a foundation-relative `@/x` model ref into
     // `@org/x` before it ships. Absent on an offline probe, which is why
-    // buildCollectionEntities warns rather than throws.
+    // buildRecordEntities warns rather than throws.
     ...(opts.org ? { org: opts.org } : {}),
   })
-  const warnings = [...col.warnings]
+  const warnings = [...col.warnings, ...(col.folder?.warnings ?? [])]
 
   // 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: col.entities,
-    folders: col.colConfig?.folders ?? null,
+    // ⭐ AUTHORED, from `records.yml`. It used to be derived — one branch per
+    // collection — which made the folder a shadow of a directory layout rather
+    // than something the author states.
+    folderNodes: col.folder?.nodes ?? [],
+    // ⛔ Whether `records.yml` EXISTS — not whether it holds anything. Missing is
+    // inert; empty is a folder that REMOVES. Compared against the affirmative
+    // value, never `!== 'missing'`: an absent state would read as declared, and
+    // that is precisely how a site with no records.yml once emitted a folder that
+    // would have emptied the live one.
+    declared: col.recordsState === 'empty' || col.recordsState === 'declared',
     // Placement identity from the folder document a previous push returned.
     // Absent on a first push — every item is genuinely new then. Its ABSENCE on a
     // later push is what made `publish` after `push` fail: send-only-changed skips
@@ -284,13 +293,18 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     // the payload whose item identity has to survive.
     ...(opts.folderItemUuids ? { itemUuids: opts.folderItemUuids } : {}),
   })
+  // ⚠️ A placement that produced no entity is dropped by the builder rather than
+  // sent pointing at nothing — but it must still be SAID. It means an entity was
+  // placed in records.yml and then skipped upstream (a schema that did not
+  // resolve, most often), and the record is simply absent from the site.
+  if (folder?.warnings?.length) warnings.push(...folder.warnings)
 
-  // `collectionUuids` — identity for the `collections` section, keyed by collection
-  // NAME because a declaration has no file of its own (see collectionsNested).
+  // `queryUuids` — identity for the `queries` section, keyed by query
+  // NAME because a declaration has no file of its own (see queriesNested).
   const siteDoc = includeSite
     ? await siteProjectToDocument(siteRoot, {
         sourceLocale,
-        ...(opts.collectionUuids ? { collectionUuids: opts.collectionUuids } : {})
+        ...(opts.queryUuids ? { queryUuids: opts.queryUuids } : {})
       })
     : null
   // Deploy-derived `info` fields (e.g. `data_bundle`, the static-data ball URL) are
@@ -398,14 +412,14 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     return isChanged
   }
 
-  // --- collections lane --------------------------------------------------------
+  // --- records lane ------------------------------------------------------------
   // 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
   const recordChanged = col.entities.map((e, i) => ({ entity: e, index: col.index[i], changed: changed(e) }))
   const changedRecords = recordChanged.filter((r) => r.changed)
 
-  let collections = null
+  let records = null
   if (folder && (folderChanged || changedRecords.length > 0)) {
     // Folder first (always, for the `$ref` closure), then changed records. The
     // leading `{ kind: 'folder' }` keeps submission position 0 aligned for record
@@ -416,7 +430,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     // filtered out here by send-only-changed. Declare them all (the backend rejects a
     // folder that references an undeclared Model).
     const referencedModels = [...collectReferencedModels(folder.document, new Set())]
-    collections = { ...emitLane(entities, exporter, exportedAt, referencedModels), index }
+    records = { ...emitLane(entities, exporter, exportedAt, referencedModels), index }
   }
 
   // --- site-content lane -------------------------------------------------------
@@ -455,7 +469,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   }
 
   return {
-    siteContent, collections, siteContentUuid, hashes, warnings, skipped,
+    siteContent, records, siteContentUuid, hashes, warnings, skipped,
     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

package/src/validate-data.js

@@ -27,7 +27,7 @@ import { readFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { join, resolve, basename } from 'node:path'
 import yaml from 'js-yaml'
-import { collectionNameFromUrl } from '@uniweb/core'
+import { queryNameFromUrl } from '@uniweb/core'
 
 import { validateItem, isStaticallyCheckable, validateBound } from '@uniweb/schemas/conform'
 import { validateAndNormalizeSchema } from './resolve-data-schema.js'
@@ -39,7 +39,7 @@ export { validateItem, isStaticallyCheckable } from '@uniweb/schemas/conform'
 import { buildSchema } from './schema.js'
 import { resolveFoundationSrcPath } from './utils/foundation-source-root.js'
 import { collectSiteContent } from './site/content-collector.js'
-import { processCollections } from './site/collection-processor.js'
+import { processQueries } from './site/query-processor.js'
 
 // --- the join: sections ↔ schemas -------------------------------------------
 
@@ -58,7 +58,7 @@ import { processCollections } from './site/collection-processor.js'
  * this command and the build disagree about what feeds what.
  *
  * Data is acquired without a full build: the foundation schema via schema
- * discovery, the site sections via the content collector, the collections via
+ * discovery, the site sections via the content collector, the byQuery via
  * the collection processor (in-memory, full records — so `deferred:`
  * field-stripping never causes a false "missing required").
  *
@@ -85,15 +85,13 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
   const config = site.config || {}
   const basePath = typeof config.base === 'string' ? config.base : '/'
 
-  // Compile file-based collections in-memory (the same step the data-only
-  // pipeline runs). Full records — `writeCollectionFiles` is the stage that
+  // Compile file-based byQuery in-memory (the same step the data-only
+  // pipeline runs). Full records — `writeQueryFiles` is the stage that
   // strips `deferred:` fields, and we skip it.
-  let collections = {}
-  if (config.collections && typeof config.collections === 'object') {
-    const collectionsBase = config.paths?.collections
-      ? resolve(siteRoot, config.paths.collections)
-      : null
-    collections = await processCollections(siteRoot, config.collections, collectionsBase, basePath)
+  let byQuery = {}
+  if (config.queries && typeof config.queries === 'object') {
+
+    byQuery = await processQueries(siteRoot, config.queries, config.paths?.entities, basePath)
   }
 
   // Pass 1 — discover unique (file, schema-ref) pairs and who uses each.
@@ -144,7 +142,7 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
   let recordCount = 0
 
   for (const entry of work.values()) {
-    const { records, error } = await resolveRecords(entry.path, { collections, siteRoot })
+    const { records, error } = await resolveRecords(entry.path, { byQuery, siteRoot })
     if (error) {
       setupErrors.push({ file: entry.path, message: error, users: entry.users })
       continue
@@ -252,7 +250,7 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
  * works on a link-mode site whose foundation is a registry ref with nothing
  * local), and an unresolved tag must be silent rather than an error. So the
  * package is resolved from this build's own graph, where it is an
- * optionalDependency, exactly as `i18n/collections.js` resolves it.
+ * optionalDependency, exactly as `i18n/records.js` resolves it.
  *
  * @param {Object} site - collected site content (`{ pages }`)
  * @returns {Promise<{ violations: Array, schemas: Set<string>, checked: number }>}
@@ -337,7 +335,7 @@ function nodesOfType(doc, type) {
  * This is the pass that closes an odd hole: a component declares
  * `data: { form: '@std/form' }`, an author writes a ```` ```yaml:form ```` block,
  * and until now **nothing checked one against the other**. The join walked
- * `section.fetch` — collections and fetches — so a schema bound to a key that a
+ * `section.fetch` — byQuery and fetches — so a schema bound to a key that a
  * tagged block fills was never applied to anything. `@std/form` existed for
  * exactly this and had never run outside its own contract test.
  *
@@ -462,17 +460,17 @@ function walkSections(sections, visit) {
 }
 
 /**
- * Resolve a fetch `path` to its records. Declared collections come from the
+ * Resolve a fetch `path` to its records. Declared byQuery come from the
  * in-memory compile (full records, current); a bare file under `public/`
  * (hand-authored data) is read from disk. Either way no prior build is needed.
  */
-async function resolveRecords(path, { collections, siteRoot }) {
+async function resolveRecords(path, { byQuery, siteRoot }) {
   // A compiled-collection URL → a declared collection? Use the compiled
   // records. Anything else falls through to the file read below.
-  const name = collectionNameFromUrl(path)
+  const name = queryNameFromUrl(path)
   let records
-  if (Object.prototype.hasOwnProperty.call(collections, name)) {
-    records = collections[name]
+  if (Object.prototype.hasOwnProperty.call(byQuery, name)) {
+    records = byQuery[name]
   } else {
     // Otherwise read the file from public/ (the data-fetcher's resolution root).
     const filePath = join(siteRoot, 'public', path)