@uniweb/build 0.56.0 → 0.57.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,15 +57,15 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
+    "@uniweb/content-reader": "^1.2.5",
     "@uniweb/schemas": "^0.3.3",
-    "@uniweb/projections": "^0.7.3",
     "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/content-reader": "^1.2.5",
     "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/theming": "^0.1.15"
+    "@uniweb/theming": "^0.1.15",
+    "@uniweb/projections": "^0.7.3"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.27.2"
+    "@uniweb/runtime": "^0.27.3"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,8 +74,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/runtime": "^0.27.2",
-    "@uniweb/core": "^0.29.6"
+    "@uniweb/core": "^0.29.7",
+    "@uniweb/runtime": "^0.27.3"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/content/index.js

@@ -21,6 +21,9 @@ export {
   writeQueryFiles,
   getQueryLastModified,
 } from '../site/query-processor.js'
+// Where a site's records live — `paths.records`, else `records/` — so a caller
+// holding its own config (a document's, not a `site.yml`) asks the one resolver.
+export { resolveRecordsDir } from '../site/entity-pool.js'
 export {
   parseFetchConfig,
   executeFetch,

package/src/i18n/data-strings.js

@@ -31,7 +31,7 @@ export const HEURISTIC_SKIP_FIELDS = new Set([
   'pmid', 'bibtex', 'pdf', 'code', 'data', 'slides', 'video',
   'repository', 'caseStudy', 'website', 'avatar', 'image',
   'thumbnail', 'currency', 'order', 'hidden', 'current',
-  'featured', 'published', 'allDay', 'remote', 'hybrid',
+  'featured', 'published', 'draft', 'allDay', 'remote', 'hybrid',
   'noindex', 'corresponding', 'required', 'virtual',
   'lastModified', 'date', 'updated', 'posted', 'submitted',
   'accepted', 'startDate', 'endDate', 'deadline',

package/src/i18n/freeform.js

@@ -10,7 +10,7 @@
  *   locales/freeform/{locale}/
  *     pages/{pageRoute}/{stableId}.md      - By route
  *     page-ids/{pageId}/{stableId}.md      - By page ID (stable)
- *     entities/{schema dirs}/{slug}.md     - Records
+ *     records/{schema dirs}/{slug}.md      - Records
  *
  * Resolution order for sections:
  *   1. page-ids/{pageId}/{stableId}.md (if page has id:)
@@ -22,7 +22,7 @@ import { readFile, readdir, stat } from 'fs/promises'
 import { existsSync } from 'node:fs'
 import { join, relative, dirname, sep } from 'node:path'
 import yaml from 'js-yaml'
-import { poolDirsForSchema, ENTITIES_DIR } from '../site/entity-pool.js'
+import { poolDirsForSchema, schemaForPoolDirs, RECORDS_DIR } from '../site/entity-pool.js'
 import { parseFrontmatter } from '../utils/frontmatter.js'
 import { computeSourceHash } from './freeform-manifest.js'
 
@@ -101,13 +101,13 @@ export async function loadFreeformTranslation(section, page, locale, localesDir)
 }
 
 /**
- * Load a free-form translation for one ENTITY.
+ * Load a free-form translation for one RECORD.
  *
- * Path: entities/{schema dirs}/{slug}.md — mirroring the pool exactly.
+ * Path: records/{schema dirs}/{slug}.md — mirroring the records directory exactly.
  *
- * ⛔ KEYED BY THE ENTITY, NOT BY A QUERY. It used to be
+ * ⛔ KEYED BY THE RECORD, NOT BY A QUERY. It used to be
  * `collections/{queryName}/{slug}.md`, which was fine only while a
- * collection was also a directory of files. With `entities/{schema}/` as the pool,
+ * collection was also a directory of files. With `records/{schema}/` holding records,
  * TWO queries can cover one schema — so a query-keyed path would make an author
  * write the same translation once per query, and finding neither from the other.
  * ⚠️ And a query is renameable where a record's model is not: keying on the query
@@ -185,7 +185,7 @@ async function discoverMarkdownFiles(dir, baseDir) {
  * register a translation that has no manifest entry yet.
  *
  * ⭐ Each path is relative to the locale's free-form directory — `pages/about/story.md`,
- * `page-ids/<id>/intro.md`, `entities/article/hello.md` — the form the manifest keys a
+ * `page-ids/<id>/intro.md`, `records/article/hello.md` — the form the manifest keys a
  * translation by and `freeformPathsFor` derives. ⛔ Until 2026-09-14 each was relative
  * to its own subdirectory (`about/story.md`), so none matched a manifest key: the build
  * registered no new file, and a status counted every stale or orphaned file as up to date.
@@ -217,10 +217,10 @@ export async function discoverFreeformTranslations(locale, localesDir) {
     result.pageIds = (await discoverMarkdownFiles(pageIdsDir, freeformDir)).sort()
   }
 
-  // Discover entity translations
-  const entitiesDir = join(freeformDir, ENTITIES_DIR)
-  if (existsSync(entitiesDir)) {
-    result.records = (await discoverMarkdownFiles(entitiesDir, freeformDir)).sort()
+  // Discover record translations
+  const recordsDir = join(freeformDir, RECORDS_DIR)
+  if (existsSync(recordsDir)) {
+    result.records = (await discoverMarkdownFiles(recordsDir, freeformDir)).sort()
   }
 
   return result
@@ -246,7 +246,7 @@ export async function getFreeformFileMeta(filePath) {
  * Parse a free-form translation file path to extract metadata
  *
  * @param {string} relativePath - Path relative to locale's freeform dir
- * @returns {Object} { type, pageRoute?, pageId?, queryName?, stableId, slug? }
+ * @returns {Object} { type, pageRoute?, pageId?, schema?, stableId, slug? }
  */
 export function parseFreeformPath(relativePath) {
   const parts = relativePath.split('/')
@@ -266,11 +266,12 @@ export function parseFreeformPath(relativePath) {
     return { type: 'pageId', pageId, stableId }
   }
 
-  if (parts[0] === ENTITIES_DIR) {
-    // collections/articles/getting-started.md → { type: 'collection', queryName: 'articles', slug: 'getting-started' }
+  if (parts[0] === RECORDS_DIR) {
+    // records/std/person/ada.md → { type: 'record', schema: '@std/person', slug: 'ada' }
+    // ⛔ This returned `queryName: parts[1]` until 2026-09-21 — the first schema
+    // segment (`std` above), and never a query's name. Nothing read it.
     const slug = parts[parts.length - 1].replace('.md', '')
-    const queryName = parts[1]
-    return { type: 'record', queryName, slug }
+    return { type: 'record', schema: schemaForPoolDirs(parts.slice(1, -1)), slug }
   }
 
   return { type: 'unknown', relativePath }
@@ -343,7 +344,7 @@ function freeformSections(siteContent) {
  *   - `canJudge(path)` — whether this content can say a translation at `path` is
  *     orphaned. ⛔ Only a page section's (`pages/…`, `page-ids/…`), and not one for a page
  *     whose sections the content does not carry — a prerendered site with split content
- *     rewrites `site-content.json` without them. A record's (`entities/…`) is read from
+ *     rewrites `site-content.json` without them. A record's (`records/…`) is read from
  *     records this content does not hold. A check that cannot see the source must never
  *     call its translation orphaned: `prune --freeform` deletes what it is told is.
  *
@@ -413,10 +414,10 @@ export function buildFreeformPath(section, page, preferPageId = true) {
  *
  * @param {string} schema - the entity's model ref (`@/name` or `@org/name`)
  * @param {string} slug - the entity's slug
- * @returns {string|null} e.g. `entities/article/getting-started.md`, or null for a
+ * @returns {string|null} e.g. `records/article/getting-started.md`, or null for a
  *   ref this layout cannot express
  */
 export function buildFreeformRecordPath(schema, slug) {
   const dirs = poolDirsForSchema(schema)
-  return dirs ? `${ENTITIES_DIR}/${dirs.join('/')}/${slug}.md` : null
+  return dirs ? `${RECORDS_DIR}/${dirs.join('/')}/${slug}.md` : null
 }

package/src/i18n/index.js

@@ -21,7 +21,7 @@ import {
   buildLocalizedRecords,
   getRecordLocales,
   translateRecordData,
-  RECORDS_DIR
+  RECORD_LOCALES_DIR
 } from './records.js'
 import { resolveDefaultLocale } from '@uniweb/core'
 import { generateSearchIndex } from '@uniweb/projections'
@@ -75,7 +75,7 @@ export {
   buildLocalizedRecords,
   getRecordLocales,
   translateRecordData,
-  RECORDS_DIR,
+  RECORD_LOCALES_DIR,
 
   // Locale resolution
   getAvailableLocales,
@@ -234,7 +234,7 @@ export async function extractRecordManifest(siteRoot, options = {}) {
   const manifest = await extractRecordContent(siteRoot)
 
   // Ensure collections locales directory exists
-  const recordLocalesDir = join(siteRoot, localesDir, RECORDS_DIR)
+  const recordLocalesDir = join(siteRoot, localesDir, RECORD_LOCALES_DIR)
   if (!existsSync(recordLocalesDir)) {
     await mkdir(recordLocalesDir, { recursive: true })
   }
@@ -517,7 +517,7 @@ async function warnAboutFreeformIssues(locale, freeformDir, siteContent) {
     }
 
     // Check for orphaned translations — only those this content can judge: never a
-    // record's (`entities/…`), which is read from records the site content does not hold.
+    // record's (`records/…`), which is read from records the site content does not hold.
     const orphaned = await getOrphanedTranslations(freeformDir, validPaths)
     for (const item of orphaned) {
       if (!canJudge(item.path)) continue

package/src/i18n/records.js

@@ -23,7 +23,7 @@ import { loadFreeformRecord } from './freeform.js'
 // is not, wherever the value came from. Moved rather than copied: two tuned
 // denylists would drift, and drift here is silent.
 import { resolveQueriesConfig } from '../site/queries-config.js'
-import { poolDirsForSchema, schemaForPoolDirs, ENTITIES_DIR } from '../site/entity-pool.js'
+import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir } from '../site/entity-pool.js'
 import {
   NON_TRANSLATABLE_TYPES,
   HEURISTIC_SKIP_FIELDS,
@@ -37,7 +37,11 @@ import {
 // contexts were keyed by the QUERY, so two queries over one schema produced two
 // entries for one record, each invisible from the other, and a renamed query
 // orphaned every translation under it.
-export const RECORDS_DIR = 'records'
+//
+// ⚠️ `RECORD_LOCALES_DIR`, and not `RECORDS_DIR`, since 2026-09-21: that name is the
+// site's own `records/` directory now (`site/entity-pool.js`), and this one is
+// `locales/records/` — two directories, one word, so the constant says which.
+export const RECORD_LOCALES_DIR = 'records'
 
 // ---------------------------------------------------------------------------
 // Schema resolution
@@ -72,7 +76,7 @@ async function resolveSchema(queryName, siteRoot) {
   // an author to write into it was the one remaining place the framework
   // contradicted its own rule that `collections/` is the only way to provide
   // structured data. The schema describes the source, so it lives with it.
-  const companionPath = join(siteRoot, ENTITIES_DIR, `${queryName}.schema.js`)
+  const companionPath = join(resolveRecordsDir(siteRoot).abs, `${queryName}.schema.js`)
   if (existsSync(companionPath)) {
     try {
       const mod = await import(pathToFileURL(companionPath).href)
@@ -657,7 +661,7 @@ export async function buildLocalizedRecords(siteRoot, options = {}) {
   const {
     locales = [],
     outputDir = join(siteRoot, 'dist'),
-    recordLocalesDir = join(siteRoot, 'locales', RECORDS_DIR),
+    recordLocalesDir = join(siteRoot, 'locales', RECORD_LOCALES_DIR),
     localesDir = join(siteRoot, 'locales'),
     freeformEnabled = true
   } = options
@@ -987,7 +991,7 @@ export async function translateRecordData(items, queryName, siteRoot, options =
  * @returns {Promise<string[]>} Array of locale codes
  */
 export async function getRecordLocales(localesPath) {
-  const recordLocalesDir = join(localesPath, RECORDS_DIR)
+  const recordLocalesDir = join(localesPath, RECORD_LOCALES_DIR)
   if (!existsSync(recordLocalesDir)) return []
 
   try {

package/src/site/build-site-data.js

@@ -24,6 +24,7 @@ import { join, resolve, dirname } from 'node:path'
 import { resolveDefaultLocale, DATA_DIR } from '@uniweb/core'
 import { collectSiteContent } from './content-collector.js'
 import { processQueries, writeQueryFiles } from './query-processor.js'
+import { resolveRecordsDir } from './entity-pool.js'
 import { processAssets, rewriteSiteContentPaths } from './asset-processor.js'
 import { processAdvancedAssets } from './advanced-processors.js'
 import {
@@ -61,7 +62,7 @@ import {
  *     re-derive, so we always ship enough for the ones that do.
  *   - `data/<collection>.json` (+ per-record files for `deferred:`
  *     collections) — same shape `processQueries` produces today.
- *   - `records/<path under entities/>` — the records' co-located assets, where
+ *   - `records/<path under the records directory>` — the records' co-located assets, where
  *     the compiled records point.
  *   - `assets/<media>` — processed images / video posters / PDF
  *     thumbnails. Filtered by the deploy CLI to MEDIA only at upload time.
@@ -143,7 +144,7 @@ export async function buildSiteData({
     const byQuery = await processQueries(
       resolvedSiteRoot,
       siteContent.config.queries,
-      siteContent.config?.paths?.entities,
+      resolveRecordsDir(resolvedSiteRoot, siteContent.config?.paths).rel,
       basePath,
       { locale: resolveDefaultLocale(siteContent.config) ?? null }
     )
@@ -155,7 +156,7 @@ export async function buildSiteData({
       await cp(publicDataDir, distDataDir, { recursive: true })
     }
 
-    // ⭐ AND THE RECORDS' CO-LOCATED ASSETS — `public/records/<path under entities/>`,
+    // ⭐ AND THE RECORDS' CO-LOCATED ASSETS — `public/records/<path under records/>`,
     // where the compiled records point (`/records/…`), mirrored the way vite mirrors
     // all of `public/` on the bundle lane. ⛔ Until 2026-09-14 only `public/data` was
     // copied, so a record's image URL named a file this lane's `dist/` did not have.

package/src/site/config.js

@@ -484,7 +484,7 @@ export async function defineSiteConfig(options = {}) {
           const allowed = ['..']
           const parentDir = resolve(siteRoot, '..')
           const paths = siteConfig.paths || {}
-          for (const key of ['pages', 'layout', 'entities']) {
+          for (const key of ['pages', 'layout', 'records']) {
             if (paths[key]) {
               const resolved = resolve(siteRoot, paths[key])
               if (!resolved.startsWith(parentDir)) {

package/src/site/content-collector.js

@@ -2727,9 +2727,10 @@ export async function collectSiteContent(sitePath, options = {}) {
   // The `query:` shorthand ships as `config.fetch`, desugared below; carried raw
   // it would sit beside `config.queries`, the declarations, and read as one.
   const { publishLanguages: _publishLanguages, query: _query, ...runtimeSiteConfig } = siteConfig
-  // ⛔ `$`-prefixed keys are the project's BACKEND-SCOPED state — `$uuid`, `$org`,
-  // `$backend`, `$services`, `$secrets` — and this payload is a PUBLISHED artifact
-  // that a visitor can fetch. They have no runtime reader (nothing in core, runtime
+  // ⛔ `$`-prefixed keys were the project's BACKEND-SCOPED state — `$uuid`, `$org`,
+  // `$backend`, `$services`, `$secrets` — until they moved to `sync.json`
+  // (2026-09-20), and a `site.yml` written before then can still carry them. This
+  // payload is a PUBLISHED artifact that a visitor can fetch. They have no runtime reader (nothing in core, runtime
   // or kit reads a `config.$*` key), so this removes noise for four of them and a
   // real disclosure for the fifth: `$secrets` carries no values, but its entries
   // name every secret the site has, and an inventory of credential names is not

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 }
 }
 
 /**