@uniweb/build 0.55.1 → 0.57.0

package/src/site/deploy-config.js

@@ -5,14 +5,21 @@
  * by name. Read-only — never writes. See deploy-config-writer.js for
  * the write path.
  *
- * On-disk shape:
+ * On-disk shape (spec: kb/framework/reference/deploy-yml.md):
  *   default: production
  *   targets:
- *     production: { host, ...host-specific config }
+ *     production: { host, backend?, ...host-specific config }
  *     preview:    { host, ...host-specific config }
- *   autoSave: lastDeploy | off | full
- *   lastDeploy:
- *     production: { at, url, foundation, runtime, artifactSha, ... }
+ *   deploys:
+ *     production: { at, host, url?, git?, servicesRequest? }
+ *   saveDeploys: true
+ *
+ * ⚠️ `deploys` was `lastDeploy` and `saveDeploys` was `autoSave: off|lastDeploy|full`
+ * until 2026-09-20. `full` was "reserved; behaves as lastDeploy" — so the tri-state
+ * was already a boolean in practice, and the rename says so. `autoSave` also
+ * SOUNDED like it covered the whole file, which it never did.
+ *
+ * ⚠️ Nothing a backend minted lives here any more. Identity is `sync.json`'s.
  *
  * The CLI and the build pipeline both call resolveTarget() to turn a
  * loaded document + a (possibly null) --target flag into a concrete
@@ -26,9 +33,9 @@ import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
+import { normalizeOrigin } from '../uwx/sync-store.js'
 
 const DEFAULT_TARGET_NAME = 'production'
-const VALID_AUTOSAVE = new Set(['off', 'lastDeploy', 'full'])
 
 /**
  * Load and validate deploy.yml from `siteDir`. Returns null when the
@@ -57,7 +64,7 @@ export async function loadDeployYml(siteDir) {
  *   targetName: string,
  *   host: string,
  *   config: object,
- *   autoSave: 'off'|'lastDeploy'|'full',
+ *   saveDeploys: boolean,
  *   fromFile: boolean,
  * }}
  */
@@ -73,7 +80,7 @@ export function resolveTarget(deployYml, requestedTarget) {
       targetName: DEFAULT_TARGET_NAME,
       host: 'uniweb',
       config: {},
-      autoSave: 'lastDeploy',
+      saveDeploys: true,
       fromFile: false,
     }
   }
@@ -99,11 +106,73 @@ export function resolveTarget(deployYml, requestedTarget) {
     targetName: name,
     host,
     config,
-    autoSave: deployYml.autoSave || 'lastDeploy',
+    saveDeploys: deployYml.saveDeploys !== false,
     fromFile: true,
   }
 }
 
+/**
+ * The target a publish to `origin` records its deploy under.
+ *
+ * ⭐ **The target follows the backend, never the reverse.** A publish goes to ONE backend,
+ * decided before this runs — `--backend`, or the backend the user is logged in to
+ * *[Diego, 2026-09-21: "publish should publish to the backend the user logged in to"]*.
+ * The default target is only a tie-break, winning when it names that backend too.
+ *
+ *   1. no deploy.yml → the scaffold: `production`, naming `origin`
+ *   2. `host: uniweb` targets naming `origin` → the default one if it is among them,
+ *      else the first by name. A target with no `backend:` names `defaultBackend` —
+ *      its documented meaning
+ *   3. none → a NEW target, named after the backend's host (`uniweb.app`,
+ *      `localhost:8080`), `-2`, `-3`… if taken. The caller adds it when it persists.
+ *
+ * ⛔ Until 2026-09-21 publish always resolved the DEFAULT target, whatever backend it
+ * published to: a publish to a second backend recorded over the default target's deploy,
+ * and compared its service request against that target's fingerprint.
+ *
+ * @param {object|null} deployYml - from loadDeployYml
+ * @param {string} origin - the backend being published to
+ * @param {{ defaultBackend?: string }} [opts]
+ * @returns {{ targetName: string, host: 'uniweb', config: object, saveDeploys: boolean,
+ *   fromFile: boolean }} `fromFile: false` means the file has no such target yet
+ */
+export function resolvePublishTarget(deployYml, origin, { defaultBackend } = {}) {
+  const key = normalizeOrigin(origin)
+  if (!deployYml) {
+    return {
+      targetName: DEFAULT_TARGET_NAME,
+      host: 'uniweb',
+      config: { backend: key },
+      saveDeploys: true,
+      fromFile: false,
+    }
+  }
+  const saveDeploys = deployYml.saveDeploys !== false
+  const targets = deployYml.targets || {}
+  const naming = Object.keys(targets)
+    .filter((name) => {
+      const t = targets[name]
+      return t && t.host === 'uniweb' && normalizeOrigin(t.backend || defaultBackend) === key
+    })
+    .sort()
+  if (naming.length) {
+    const targetName = naming.includes(deployYml.default) ? deployYml.default : naming[0]
+    const { host, ...config } = targets[targetName]
+    return { targetName, host, config, saveDeploys, fromFile: true }
+  }
+  let base = 'uniweb'
+  try {
+    base = new URL(key).host || base
+  } catch {
+    /* keep the fallback */
+  }
+  let targetName = base
+  for (let i = 2; Object.prototype.hasOwnProperty.call(targets, targetName); i++) {
+    targetName = `${base}-${i}`
+  }
+  return { targetName, host: 'uniweb', config: { backend: key }, saveDeploys, fromFile: false }
+}
+
 function validate(doc, path) {
   if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) {
     throw new Error(`${path}: top level must be a map.`)
@@ -111,39 +180,19 @@ function validate(doc, path) {
   if (doc.targets !== undefined && (typeof doc.targets !== 'object' || Array.isArray(doc.targets))) {
     throw new Error(`${path}: \`targets\` must be a map.`)
   }
-  // A site has exactly ONE Uniweb identity — `site.yml::$uuid`, a single scalar,
-  // set by the create and never moved. So two targets naming `host: uniweb` cannot
-  // both be coherent: whichever one `default:` selects is the site, and the other
-  // silently describes a site that does not exist. The per-target `backend` key
-  // makes that look expressible, which is exactly why it is worth rejecting rather
-  // than leaving to be discovered.
-  //
-  // *(Diego, 2026-08-12: multiple deploys are not expected in general, and are not
-  // allowed for Uniweb Cloud specifically — the only host that reads `$uuid` at
-  // all. Every other host is stateless from the CLI's side, so any number of those
-  // targets is fine.)*
-  if (doc.targets && typeof doc.targets === 'object' && !Array.isArray(doc.targets)) {
-    const uniwebTargets = Object.entries(doc.targets)
-      .filter(([, t]) => t && typeof t === 'object' && t.host === 'uniweb')
-      .map(([name]) => name)
-    if (uniwebTargets.length > 1) {
-      throw new Error(
-        `${path}: only one target may use \`host: uniweb\` — found ${uniwebTargets.length} (${uniwebTargets.join(', ')}). ` +
-          'A site has a single Uniweb identity (site.yml::$uuid), so a second Uniweb target cannot describe a different site. ' +
-          'Keep one, or point the others at a third-party host.'
-      )
-    }
-  }
-  if (doc.autoSave !== undefined && !VALID_AUTOSAVE.has(doc.autoSave)) {
-    throw new Error(
-      `${path}: \`autoSave\` must be one of: ${[...VALID_AUTOSAVE].join(', ')}.`
-    )
+  // ⭐ SEVERAL `host: uniweb` TARGETS ARE LEGAL (2026-09-20). This rejected a second one
+  // because a site had a single identity, `site.yml::$uuid`, so two Uniweb targets
+  // could not both be coherent. Identity is keyed by backend origin in `sync.json`
+  // now: two targets naming DIFFERENT backends are two sites, and two naming the SAME
+  // backend are one site shipped twice. The reason is gone, so the rejection is too.
+  if (doc.saveDeploys !== undefined && typeof doc.saveDeploys !== 'boolean') {
+    throw new Error(`${path}: \`saveDeploys\` must be true or false.`)
   }
   if (doc.default !== undefined && typeof doc.default !== 'string') {
     throw new Error(`${path}: \`default\` must be a string.`)
   }
-  if (doc.lastDeploy !== undefined && (typeof doc.lastDeploy !== 'object' || Array.isArray(doc.lastDeploy))) {
-    throw new Error(`${path}: \`lastDeploy\` must be a map.`)
+  if (doc.deploys !== undefined && (typeof doc.deploys !== 'object' || Array.isArray(doc.deploys))) {
+    throw new Error(`${path}: \`deploys\` must be a map.`)
   }
   return doc
 }

package/src/site/entity-pool.js

@@ -1,49 +1,130 @@
-// A site's ENTITY POOL — every stored thing on disk, and the model each one has.
+// A site's RECORDS on disk — every file in `records/`, and the model each one has.
 //
-// ⛔ THE PATH DECLARES THE MODEL, AND NOTHING ELSE. That is the whole point of
-// this directory, and it is the de-conflation the records model is built on:
-// `collections/<name>/` used to mean three things at once — these files are
-// entities, their schema is `@/<name>`, and they are grouped as `<name>` for
-// placement. `entities/{schema}/` declares only the first two. Grouping moved to
-// `records.yml`, which is what makes an entity a RECORD.
+// ⭐ PLACING A FILE IN `records/` IS WHAT MAKES IT A RECORD (ruled 2026-09-21
+// [Diego]). The directory is the file side of the site's records folder: the
+// backend's folder holds references to entities, and putting a ref in it is what
+// makes one a record — putting a file in this directory is the same act. Nothing
+// else is needed, and nothing lists it. (`records.yml` only organizes records into
+// sub-folders; see `records-config.js`.) A file whose name starts with `_` or `.`
+// is not read, so it is not a record.
 //
-// ⇒ So nothing here reads a query, a folder, or any config. A pool is a fact
-// about the filesystem.
+// ⛔ A RECORD IS NOT "PUBLISHED" BY BEING HERE. `push` sends the site's records to a
+// backend, and they are served once the SITE is published — publishing the site
+// publishes its folder and what is in it. Nothing about a single record decides that.
+//
+// ⛔ THE PATH DECLARES THE MODEL, AND NOTHING ELSE. `collections/<name>/` used to
+// mean three things at once — these files are entities, their schema is
+// `@/<name>`, and they are grouped as `<name>` for placement. A schema folder here
+// declares only the model; grouping is `records.yml`'s.
+//
+// ⇒ So nothing here reads a query or a folder. A site's records are a fact about
+// the filesystem — plus `site.yml::paths.records`, which says where they live.
 //
 // ⭐ DEPTH NAMES THE SCOPE — the schema-ref grammar, spelled as directories:
 //
-//     entities/person/ada.md         → @/person        (the foundation's own)
-//     entities/std/person/ada.md     → @std/person      (the shared standard set)
-//     entities/acme/project/x.md     → @acme/project    (an org's)
+//     records/person/ada.md         → @/person        (the foundation's own)
+//     records/std/person/ada.md     → @std/person      (the shared standard set)
+//     records/acme/project/x.md     → @acme/project    (an org's)
 //
 // matching `build/src/resolve-data-schema.js`, which is the only grammar there
 // is: a bare directory name can mean `@/<name>` and nothing else.
 //
-// ⛔ BARE, NOT `entities/@std/`. Measured: `@` is a reserved indicator in YAML
+// ⛔ BARE, NOT `records/@std/`. Measured: `@` is a reserved indicator in YAML
 // 1.2, so a bare `@std/person/*.md` scalar throws in js-yaml — and the message is
 // `bad indentation of a sequence entry`, which names neither the cause nor the
-// fix. The `@` form would force quotes on the most common line in `records.yml`
-// and put two spellings in one list.
+// fix. The `@` form would force quotes on every pattern in `records.yml` that
+// names a scoped schema.
 //
 // ⛔ AND NO NESTING BELOW THE SCHEMA DIR, which is what makes the depth rule
 // total: it is the FILE's depth that decides, so one path answers the question
-// with nothing to classify and no ambiguous case to resolve.
+// with nothing to classify and no ambiguous case to resolve. Organization is a
+// `folder:` in `records.yml`, never a directory.
 //
-// ⭐ That costs nothing — it CLOSES a divergence that was live and silent.
-// `uwx/collection-source.js::reportNestedRecords` warns today that records below
-// a collection's top level "build and render locally but are absent from the
-// synced set": the delivery lane recursed and the sync lane was one level deep.
-// `records.yml` replaces on-disk nesting outright, so the two lanes stop
-// disagreeing rather than being taught to agree.
+// ⛔ THE DIRECTORY WAS `entities/` UNTIL 2026-09-21, and `site.yml::paths.entities`
+// the key that moved it. Both are refused by name rather than read (no alias —
+// there is no population to carry): a leftover `entities/` beside `records/` would
+// otherwise hold records nothing reads, silently.
 
 import { readdir } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
-import { join, extname, basename } from 'node:path'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { join, extname, basename, resolve } from 'node:path'
+import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
+
+/** Where a site's records live, relative to its root, unless `site.yml::paths.records` moves them. */
+export const RECORDS_DIR = 'records'
+
+/** The directory's name until 2026-09-21. Read only to refuse it. */
+const RETIRED_DIR = 'entities'
+
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}
 
-/** Where a site's entities live, relative to its root. */
-export const ENTITIES_DIR = 'entities'
+function readSitePaths(siteRoot) {
+  const file = join(siteRoot, 'site.yml')
+  if (!existsSync(file)) return {}
+  try {
+    const doc = yaml.load(readFileSync(file, 'utf8'), YAML_OPTIONS)
+    return doc && typeof doc.paths === 'object' && doc.paths !== null ? doc.paths : {}
+  } catch {
+    // An unreadable site.yml is reported by whoever reads the site; this only
+    // needs the one key, and the default is the right answer without it.
+    return {}
+  }
+}
 
-/** Source extensions an entity file may have. Mirrors the sync-lane reader. */
+/**
+ * Refuse the retired `entities/` directory when it is not the one the site reads.
+ *
+ * ⛔ A RENAMED DIRECTORY FAILS SILENTLY — its files are simply not read, and a site
+ * with no records looks exactly like a site whose records moved. So its presence
+ * stops the build, the push and every other reader, naming the new place.
+ */
+export function refuseRetiredRecordsDir(siteRoot, rel) {
+  const retired = resolve(siteRoot, RETIRED_DIR)
+  if (resolve(siteRoot, rel) === retired) return
+  if (!isDirectory(retired)) return
+  throw new Error(
+    `[uniweb] ${RETIRED_DIR}/ is not read — a site's records live in \`${rel}/\` now. ` +
+      `Rename the directory (\`git mv ${RETIRED_DIR} ${rel}\`) and every file in it is a record, ` +
+      `as before; records.yml no longer lists them.`
+  )
+}
+
+/**
+ * Where a site's records live — `site.yml::paths.records`, else `records/`.
+ *
+ * ⭐ THE ONE RESOLVER, and every lane asks it: the build, the push, the pull and
+ * the CLI. ⛔ Until 2026-09-21 only the build honoured the key — then called
+ * `paths.entities` — while push read the default, so a site that moved its records
+ * built fine and then failed to push, with an error naming a directory it did not
+ * use (measured).
+ *
+ * @param {string} siteRoot
+ * @param {object} [paths] - `site.yml::paths`, when the caller has already read it;
+ *   otherwise `site.yml` is read here.
+ * @returns {{ rel: string, abs: string }} `rel` as written (for messages), `abs`
+ *   resolved against the site root — an absolute `paths.records` is honoured.
+ */
+export function resolveRecordsDir(siteRoot, paths) {
+  const p = paths === undefined ? readSitePaths(siteRoot) : paths || {}
+  if (p.entities !== undefined) {
+    throw new Error(
+      `[uniweb] site.yml: \`paths.entities\` is now \`paths.records\` — the directory a site's ` +
+        `records live in. Rename the key.`
+    )
+  }
+  const rel = typeof p.records === 'string' && p.records.trim() ? p.records.trim().replace(/\/+$/, '') : RECORDS_DIR
+  refuseRetiredRecordsDir(siteRoot, rel)
+  return { rel, abs: resolve(siteRoot, rel) }
+}
+
+/** Source extensions a record file may have. Mirrors the sync-lane reader. */
 export const ENTITY_EXTENSIONS = new Set(['.md', '.yml', '.yaml', '.json', '.bib'])
 
 const isHidden = (name) => name.startsWith('_') || name.startsWith('.')
@@ -51,7 +132,7 @@ const isHidden = (name) => name.startsWith('_') || name.startsWith('.')
 /**
  * The schema ref a pool path names.
  *
- * @param {string[]} dirs - the directory segments below `entities/`
+ * @param {string[]} dirs - the directory segments below `records/`
  * @returns {string|null} the ref, or null when the depth names no schema
  */
 export function schemaForPoolDirs(dirs) {
@@ -61,7 +142,7 @@ export function schemaForPoolDirs(dirs) {
 }
 
 /**
- * Where a schema's entities live — the inverse of `schemaForPoolDirs`.
+ * Where a schema's records live — the inverse of `schemaForPoolDirs`.
  *
  * ⛔ ONE IMPLEMENTATION AND ITS INVERSE, IN ONE PLACE, for the reason this file
  * exists at all: the reader derives a model from a path and the pull side derives
@@ -70,7 +151,7 @@ export function schemaForPoolDirs(dirs) {
  * `deferredFromSchema` — a deriver and its recognizer must not be two copies.
  *
  * @param {string} schema - a ref: `@/name` or `@org/name`
- * @returns {string[]|null} the directory segments below `entities/`, or null for
+ * @returns {string[]|null} the directory segments below `records/`, or null for
  *   a ref this layout cannot express
  */
 export function poolDirsForSchema(schema) {
@@ -85,7 +166,7 @@ export function poolDirsForSchema(schema) {
 /**
  * Both readings of a 2-segment pool path, for an error that has to name them.
  *
- * ⚠️ A reader who mistakes `entities/person/2024/ada.md` for "the `person`
+ * ⚠️ A reader who mistakes `records/person/2024/ada.md` for "the `person`
  * schema, organised by year" needs to be told what the build actually did with
  * it, not merely that something did not resolve. The wrong reading is the
  * plausible one, so the message carries both.
@@ -98,33 +179,46 @@ export function poolPathReadings(dirs) {
 }
 
 /**
- * Read a site's entity pool.
+ * Read a site's records.
  *
- * Returns entities in a stable, path-sorted order — the wire's package digest
+ * Returns them in a stable, path-sorted order — the wire's package digest
  * depends on it — each carrying the model its path declares.
  *
  * ⚠️ NOTHING HERE RESOLVES A SCHEMA. Whether `@std/person` is a schema this site
  * can actually see is a question for whoever holds the foundation's built schema
  * map, and only that caller can raise the error §4 of the model asks for. This
- * reports the pool's SHAPE — a file with no schema above it, a file nested too
- * deep — because those are answerable from the filesystem alone.
+ * reports the directory's SHAPE — a file with no schema above it, a file nested
+ * too deep — because those are answerable from the filesystem alone.
  *
  * @param {string} siteRoot
  * @param {object} [opts]
- * @param {string} [opts.dir] - override the pool directory (site-root-relative)
+ * @param {string} [opts.dir] - the records directory, site-root-relative or
+ *   absolute, when the caller already resolved it; otherwise `resolveRecordsDir`
+ *   reads `site.yml::paths.records`.
  * @returns {Promise<{
  *   entities: Array<{ id, schema, slug, dirs, relPath, absPath, ext }>,
  *   errors: string[],
  *   exists: boolean,
+ *   dir: string,
  * }>}
- *   `id` is the entity's path under `entities/` without its extension — unique
+ *   `id` is the record's path under `records/` without its extension — unique
  *   by construction, stable across pushes, and derivable identically on both
- *   sides without either lane holding the other's ids.
+ *   sides without either lane holding the other's ids. `exists` is whether the
+ *   directory is there at all, which is not the same as holding nothing: a push
+ *   leaves the backend's folder alone for a site with no records directory.
  */
 export async function readEntityPool(siteRoot, opts = {}) {
-  const rel = opts.dir || ENTITIES_DIR
-  const base = join(siteRoot, rel)
-  if (!existsSync(base)) return { entities: [], errors: [], exists: false }
+  let rel
+  if (opts.dir) {
+    rel = String(opts.dir).replace(/\/+$/, '')
+    refuseRetiredRecordsDir(siteRoot, rel)
+  } else {
+    rel = resolveRecordsDir(siteRoot).rel
+  }
+  // ⛔ `resolve`, not `join`: an absolute `paths.records` is supported, and
+  // `join(siteRoot, '/abs')` is a path under the site root that does not exist.
+  const base = resolve(siteRoot, rel)
+  if (!isDirectory(base)) return { entities: [], errors: [], exists: false, dir: rel }
 
   const entities = []
   const errors = []
@@ -188,7 +282,7 @@ export async function readEntityPool(siteRoot, opts = {}) {
   }
 
   await walk(base, [])
-  return { entities, errors, exists: true }
+  return { entities, errors, exists: true, dir: rel }
 }
 
 /**

package/src/site/index.js

@@ -50,5 +50,5 @@ export {
   applyPostProcessing,
   mergeDataIntoContent
 } from './data-fetcher.js'
-export { loadDeployYml, resolveTarget } from './deploy-config.js'
-export { recordLastDeploy, recordTarget } from './deploy-config-writer.js'
+export { loadDeployYml, resolveTarget, resolvePublishTarget } from './deploy-config.js'
+export { recordLastDeploy, recordTarget, forgetDeploys, forgetDeployYml } from './deploy-config-writer.js'

package/src/site/plugin.js

@@ -50,7 +50,7 @@ import { collectSiteContent, mountEntriesOf } from './content-collector.js'
 import { processAssets, rewriteSiteContentPaths } from './asset-processor.js'
 import { processAdvancedAssets } from './advanced-processors.js'
 import { processQueries, writeQueryFiles } from './query-processor.js'
-import { ENTITIES_DIR } from './entity-pool.js'
+import { RECORDS_DIR, resolveRecordsDir } from './entity-pool.js'
 import { executeFetch, mergeDataIntoContent, toFetchList } from './data-fetcher.js'
 import { shouldSplitContent } from './split-content.js'
 import { FONT_LINKS_MARKER } from './head-markers.js'
@@ -133,7 +133,7 @@ export function shouldPrefetchInDev(cfg) {
  *     query list just collected, reload. `queries.yml` declares queries, and so does
  *     `site.yml` (`queries:`), beside the rest of the site's configuration.
  *   - `'records'` — re-materialize the query files, reload: `records.yml` decides
- *     which entities are records, as an entity change decides what one says.
+ *     which folder each record sits in, which a query's `scope:` reads.
  *   - `'content'` — re-collect the site, reload.
  *
  * ⛔ Until 2026-09-14 nothing watched `records.yml` or `queries.yml`, a `site.yml`
@@ -665,7 +665,7 @@ export function siteContentPlugin(options = {}) {
   let resolvedPagesPath = null // Resolved from site.yml pagesDir or default
   let resolvedMountPaths = [] // Absolute dirs mounted under pages/ via site.yml paths:
   let resolvedLayoutPath = null // Resolved from site.yml layoutDir or default
-  let resolvedEntitiesDir = null // site.yml `paths.entities`, site-root-relative
+  let resolvedRecordsDir = null // site.yml `paths.records` as written, via `resolveRecordsDir`
   let headHtml = '' // Contents of site/head.html for injection
   let basePath = '/' // Vite's config.base, always has trailing slash
 
@@ -725,8 +725,11 @@ export function siteContentPlugin(options = {}) {
    */
   async function materializeQueries(queries, config) {
     if (!queries) return
-    const byQuery = await processQueries(resolvedSitePath, queries, resolvedEntitiesDir, basePath, {
+    const byQuery = await processQueries(resolvedSitePath, queries, resolvedRecordsDir, basePath, {
       locale: resolveDefaultLocale(config ?? {}) ?? null,
+      // ⭐ A draft is previewable here, as a hidden page is — `pnpm dev` is where the
+      // author looks at it. A production build leaves it out (`buildStart`).
+      includeDrafts: !isProduction,
     })
     await writeQueryFiles(resolvedSitePath, byQuery, queries)
   }
@@ -911,7 +914,7 @@ export function siteContentPlugin(options = {}) {
           resolvedLayoutPath = paths.layout
             ? resolve(resolvedSitePath, paths.layout)
             : resolve(resolvedSitePath, 'layout')
-          resolvedEntitiesDir = paths.entities || null
+          resolvedRecordsDir = resolveRecordsDir(resolvedSitePath, paths).rel
           resolvedMountPaths = mountEntriesOf(paths).map(([, rel]) => resolve(resolvedSitePath, rel))
 
           if (queriesConfig) {
@@ -934,7 +937,7 @@ export function siteContentPlugin(options = {}) {
         resolvedLayoutPath = paths.layout
           ? resolve(resolvedSitePath, paths.layout)
           : resolve(resolvedSitePath, 'layout')
-        resolvedEntitiesDir = paths.entities || null
+        resolvedRecordsDir = resolveRecordsDir(resolvedSitePath, paths).rel
       }
     },
 
@@ -954,7 +957,7 @@ export function siteContentPlugin(options = {}) {
         // In production, do it here
         if (isProduction && siteContent.config?.queries) {
           console.log('[site-content] Materializing queries...')
-          const byQuery = await processQueries(resolvedSitePath, siteContent.config.queries, resolvedEntitiesDir, basePath)
+          const byQuery = await processQueries(resolvedSitePath, siteContent.config.queries, resolvedRecordsDir, basePath)
           await writeQueryFiles(resolvedSitePath, byQuery, siteContent.config.queries)
         }
 
@@ -1113,11 +1116,11 @@ export function siteContentPlugin(options = {}) {
         // ⭐ WATCH THE POOL, NOT A DIRECTORY PER QUERY. This used to resolve
         // `config.path` for each declaration and watch each one, so a schema
         // folder no query had mentioned yet — a new one, mid-session — was
-        // watched by nothing and its records never rebuilt. `entities/` is one
+        // watched by nothing and its records never rebuilt. `records/` is one
         // recursive root and covers every schema, present and future.
         {
           const contentPaths = new Set([
-            resolve(resolvedSitePath, resolvedEntitiesDir || ENTITIES_DIR)
+            resolve(resolvedSitePath, resolvedRecordsDir || RECORDS_DIR)
           ])
 
           for (const contentPath of contentPaths) {

package/src/site/queries-config.js

@@ -16,9 +16,9 @@
 // rather keep one file. Precedence (per-query, per-key): queries.yml > site.yml.
 //
 // ⛔ THE THREE JOBS `collections/<name>/` USED TO FUSE ARE NOW THREE THINGS.
-// `entities/{schema}/` is the pool, `records.yml` is the folder (what makes an
-// entity a record), and a query asks the folder for a set. This file resolves the
-// LAST of those only.
+// `records/{schema}/` holds the site's records (placing a file there is what makes
+// it one), `records.yml` sorts them into folders, and a query asks for a set. This
+// file resolves the LAST of those only.
 //
 // ⚠️ `collections.yml` and `site.yml::collections` are GONE, with no alias and no
 // deprecation path — the model's §5 ruling, and there is nothing outside this
@@ -85,7 +85,7 @@ export function defaultSchema(name) {
 // address nothing local can derive.
 function normalizeQueryDecl(name, decl) {
   // ⭐ THE STRING SHORTHAND NAMES THE SCHEMA, because that is what a file-based
-  // query actually needs — `entities/{schema}/` supplies the records, so there is
+  // query actually needs — `records/{schema}/` supplies the records, so there is
   // no directory left to name. (It named a PATH while the pool was
   // `collections/<name>/` and the same directory answered both questions.)
   if (typeof decl === 'string') return { name, schema: decl }
@@ -165,7 +165,7 @@ export async function resolveQueriesConfig(siteRoot, opts = {}) {
     if (decl.path && decl.url === undefined) {
       console.warn(
         `[uniweb] query "${decl.name}": \`path: ${decl.path}\` is ignored. A query names a ` +
-          `\`schema:\` and \`entities/{schema}/\` supplies its records — there is no directory ` +
+          `\`schema:\` and \`records/{schema}/\` supplies its records — there is no directory ` +
           `for it to name. Move the files under the schema folder instead.`
       )
     }
@@ -234,6 +234,16 @@ export function refuseQueryDeclaration(decl) {
   }
   refuseQueryRoute(decl, where)
   refuseLimit(decl.limit, where)
+  // ⛔ `sync:` IS RETIRED (2026-09-21). `sync: false` kept a query's records off a
+  // backend while a query owned its records; every record in `records/` is pushed
+  // now, whatever reads it, so an ignored `sync: false` would push exactly what the
+  // author meant to hold back. Refused, naming what does that now.
+  if (decl.sync !== undefined) {
+    throw new Error(
+      `[uniweb] ${where}: \`sync:\` is retired — a query does not own its records. Every file in ` +
+        `\`records/\` is a record and is pushed; a file whose name starts with \`_\` is not a record.`
+    )
+  }
   const external = decl.url !== undefined
   if (!external) {
     for (const key of ['method', 'body', 'transform', 'record']) {