@uniweb/build 0.29.1 → 0.30.0

package/src/site/records-config.js

@@ -0,0 +1,299 @@
+// `records.yml` — the site's FOLDER: what is in it, and where.
+//
+// ⭐ LISTING AN ENTITY HERE IS WHAT MAKES IT A RECORD. An entity in `entities/`
+// exists; a record is a leaf entry in the site's folder. The backend's own gauge:
+// "An entity in no folder is not a record either: it exists, but cannot be
+// publicly fetched; placing a ref to it in a published folder is what makes one."
+// ⇒ An unreferenced entity is a draft, for free, with no flag to set.
+//
+// ⛔ IT IS A DATABASE, NOT A PAGE SYSTEM. Records are data. They usually have no
+// structure at all — a flat pool, and THE COMMON CASE IS THREE LINES:
+//
+//     - person/*.md
+//     - publication/*.md
+//     - project/*.md
+//
+// ⛔ AND STRUCTURE IS QUERY SCOPE, NOT NAVIGATION. A `folder:` is an addressable
+// dimension a query slices on — `where: { path: { under: 'archive' } }` — never a
+// menu, a listing or a URL tree. The question is not "does this site want
+// sub-pages?" but "will a query ever ask for a SLICE rather than the whole pool?"
+// Most will not, which is why flat is the norm rather than a simplification.
+//
+// ⭐ THE SHAPE IS A LIST, and an entity gets no ceremony: a bare string IS an
+// entity path, one file or a pattern matching many. Only the exceptions announce
+// themselves — `url:`, `asset:`, `folder:`. (An earlier design keyed a map by
+// entry name; it charged every entry a key, a kind and often a label to buy
+// navigation ergonomics most sites never use. Measured on a realistic file: 7 of
+// 11 entries are just a path.)
+//
+// ⛔ NO QUERIES IN HERE. A computed subset is a named query, in `queries.yml`.
+// Curation enumerates; queries compute. Two constructs, two jobs.
+//
+// ⭐ AND IT IS THE SYNC CONTROL. What syncs is exactly what this file references —
+// no flag, no inference. `missing` and `empty` differ deliberately:
+//
+//     missing  → inert. Do not sync; leave the server's folder untouched.
+//     empty    → destructive. Sync an empty folder, removing what is there.
+//
+// The safe state is the ABSENCE of a file and the destructive act requires
+// affirmatively creating one, so a live folder cannot be wiped by deleting
+// something. ⛔ Do not "simplify" these into one behaviour — it would delete a
+// capability. The placeholder hazard (someone creates an empty file meaning to
+// fill it in) is guarded at the CLI with a count and a confirmation; the format
+// stays honest and the CLI does the asking.
+//
+// Model: `kb/framework/plans/records-model.md`.
+
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import yaml from 'js-yaml'
+import { compareByNumericPrefix } from '../utils/numeric-prefix.js'
+
+export const RECORDS_YML_RELPATH = 'records.yml'
+
+/** Path to the records.yml file (whether or not it exists yet). */
+export function recordsYmlPath(siteRoot) {
+  return join(siteRoot, RECORDS_YML_RELPATH)
+}
+
+/** What `records.yml` says about syncing, before any entry is resolved. */
+export const FOLDER_MISSING = 'missing'
+export const FOLDER_EMPTY = 'empty'
+export const FOLDER_DECLARED = 'declared'
+
+/**
+ * Match one entity path against a `records.yml` pattern.
+ *
+ * ⛔ `*` DOES NOT CROSS A `/`, which is what a reader expects of a file pattern
+ * and is NOT what `@uniweb/core`'s `globMatch` does. That one backs the `like`
+ * PREDICATE, where a value is one opaque string and a cross-segment `*` is
+ * correct. Same syntax, different question — so this is a deliberate second
+ * implementation, not a copy that drifted. Do not "converge" them.
+ */
+export function matchEntityPattern(pattern, relPath) {
+  const re =
+    '^' +
+    pattern
+      .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+      .replace(/\*/g, '[^/]*')
+      .replace(/\?/g, '[^/]')
+    + '$'
+  return new RegExp(re).test(relPath)
+}
+
+/** Does this string name one exact file rather than a set? */
+const isPattern = (s) => /[*?]/.test(s)
+
+/**
+ * The slug a record is addressed by — its filename stem, whole.
+ *
+ * ⛔ NOTHING IS STRIPPED. A leading number is a DATE (`2026-03-…`) at least as
+ * often as it is an order (`01-`), and nothing in the filename distinguishes
+ * them, so consuming one into the name mangles the other. A number is read to
+ * SORT by and never to rename. *(An earlier draft of the model stripped a leading
+ * `01-`; implementing it against the model's own example pool is what surfaced
+ * the collision, and the idea was withdrawn.)*
+ */
+export function slugForEntity(entity) {
+  return entity.slug
+}
+
+/**
+ * Read `records.yml`.
+ *
+ * ⛔ THE THREE STATES ARE NOT TWO. `missing` and `empty` mean different things
+ * and the difference is load-bearing (see the header), so this reports which it
+ * saw rather than collapsing them into "no entries".
+ *
+ * @returns {Promise<{ state: string, entries: Array, error: string|null }>}
+ */
+export async function readRecordsConfig(siteRoot) {
+  const file = join(siteRoot, RECORDS_YML_RELPATH)
+  if (!existsSync(file)) return { state: FOLDER_MISSING, entries: [], error: null }
+
+  let doc
+  try {
+    doc = yaml.load(await readFile(file, 'utf8'))
+  } catch (err) {
+    return { state: FOLDER_MISSING, entries: [], error: `${RECORDS_YML_RELPATH}: ${err.message}` }
+  }
+
+  if (doc === null || doc === undefined || (Array.isArray(doc) && doc.length === 0)) {
+    return { state: FOLDER_EMPTY, entries: [], error: null }
+  }
+  if (!Array.isArray(doc)) {
+    return {
+      state: FOLDER_MISSING,
+      entries: [],
+      error:
+        `${RECORDS_YML_RELPATH} must be a LIST of what is in the folder, not a mapping. ` +
+        `The common case is three lines:\n  - person/*.md\n  - publication/*.md`,
+    }
+  }
+  return { state: FOLDER_DECLARED, entries: doc, error: null }
+}
+
+/**
+ * Resolve the folder's entries against the entity pool.
+ *
+ * Every rule here is a guard, and each one exists because its failure was
+ * SILENT. `entries: [artcles]` used to produce a real, reachable, empty path
+ * with no warning at all.
+ *
+ * ⛔ ONE PLACEMENT PER ENTITY. Two entries matching one file is a hard error, not
+ * a second placement. The wire could carry many-to-many — `folder.js` nests, and
+ * placements are keyed by their `path_segment` chain — but `core/src/where.js`'s
+ * `matchUnder` is STRING-ONLY, so a record with two paths would match nothing
+ * under `where: { path: { under: … } }`, silently. Widening `under` is a
+ * predicate the backend also evaluates natively, so it is a cross-lane change to
+ * agree first, not to infer. Until then the file lane is the floor: one folder.
+ *
+ * @param {Array} entries - the parsed `records.yml` list
+ * @param {Array} pool - entities from `readEntityPool`
+ * @returns {{ nodes: Array, placements: Map, errors: string[], warnings: string[] }}
+ *   `nodes` is the folder tree (branches + entity placements, in file order);
+ *   `placements` maps an entity id to its `{ entity, path, slug }`.
+ */
+export function resolveFolder(entries, pool) {
+  const errors = []
+  const warnings = []
+  const placements = new Map()
+  // Which entry claimed a file, so the second one can name the first.
+  const claimedBy = new Map()
+
+  const byRelPath = new Map()
+  for (const e of pool || []) {
+    // ⚠️ KEYED BY THE FILE AS IT EXISTS, prefix and all — an author writing
+    // `post/01-lab-opens.md` is naming a file they can see, not the slug it
+    // produces. `poolPath` is that path, relative to `entities/`.
+    byRelPath.set(e.poolPath, e)
+  }
+
+  const place = (entity, pathSegs, where) => {
+    const key = entity.id
+    const prior = claimedBy.get(key)
+    if (prior) {
+      errors.push(
+        `${RECORDS_YML_RELPATH}: "${entity.relPath}" is placed twice — by ${prior} and by ${where}. ` +
+          `An entity occupies one folder; a computed subset is a named query, not a second placement.`
+      )
+      return null
+    }
+    claimedBy.set(key, where)
+    const slug = slugForEntity(entity)
+    const path = pathSegs.join('/')
+    placements.set(key, { entity, path, slug })
+    return { kind: 'ref', path_segment: slug, $entityId: key }
+  }
+
+  const resolveEntry = (entry, pathSegs, index, trail) => {
+    const where = `entry ${trail}[${index}]`
+
+    if (typeof entry === 'string') {
+      const pattern = entry.trim()
+      if (!pattern) {
+        errors.push(`${RECORDS_YML_RELPATH}: ${where} is an empty string.`)
+        return []
+      }
+      if (!isPattern(pattern)) {
+        const hit = byRelPath.get(pattern)
+        if (!hit) {
+          errors.push(
+            `${RECORDS_YML_RELPATH}: ${where} names "${pattern}", which is not in entities/. ` +
+              `A bare string is a path under entities/, extension included.`
+          )
+          return []
+        }
+        const leaf = place(hit, pathSegs, where)
+        return leaf ? [leaf] : []
+      }
+      // ⛔ A PATTERN MATCHING NOTHING IS AN ERROR. `entities/artcle/*.md` is the
+      // old empty-branch defect respelled, and it produced a real, reachable,
+      // empty path with no warning.
+      const matches = [...byRelPath.entries()]
+        .filter(([rel]) => matchEntityPattern(pattern, rel))
+        .map(([, e]) => e)
+      if (matches.length === 0) {
+        errors.push(
+          `${RECORDS_YML_RELPATH}: ${where} pattern "${pattern}" matches no entity. ` +
+            `Check the schema folder name and the extension.`
+        )
+        return []
+      }
+      // Matches sort alphanumerically by filename, numeric-aware — so `1-`, `2-`,
+      // `10-` order as written rather than as strings, and `2025-…` precedes
+      // `2026-…`. Ordering only: the number never leaves the name.
+      matches.sort((a, b) => compareByNumericPrefix(a.slug, b.slug))
+      return matches.map((e) => place(e, pathSegs, where)).filter(Boolean)
+    }
+
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      errors.push(`${RECORDS_YML_RELPATH}: ${where} is neither a path nor a typed entry.`)
+      return []
+    }
+
+    if (entry.folder !== undefined) {
+      // ⚠️ COERCED, because YAML types a bare `2024` as a NUMBER — and a folder
+      // named for a year is the single most likely one anybody writes. Both the
+      // segment and the label reach the wire as strings; passing a number through
+      // would surface as a type error on the far side, far from the file that
+      // caused it. `0` is a legal folder name, so this tests for absence rather
+      // than falsiness.
+      const raw = entry.folder
+      const segment = raw === null || raw === undefined ? '' : String(raw).trim()
+      if (!segment) {
+        errors.push(`${RECORDS_YML_RELPATH}: ${where} declares a folder with no name.`)
+        return []
+      }
+      const branch = { kind: 'branch', path_segment: segment }
+      if (entry.label !== undefined && entry.label !== null) branch.name = String(entry.label)
+      const kids = Array.isArray(entry.records) ? entry.records : []
+      if (kids.length === 0) {
+        warnings.push(
+          `${RECORDS_YML_RELPATH}: folder "${segment}" (${where}) holds no records. ` +
+            `A folder exists to be QUERIED — if no query needs the slice, do not make it.`
+        )
+      }
+      branch.$children = kids.flatMap((child, i) =>
+        resolveEntry(child, [...pathSegs, segment], i, `${trail}[${index}].records`)
+      )
+      return [branch]
+    }
+
+    // ⛔ REJECT LOUDLY RATHER THAN IGNORE. The union's shape is settled and these
+    // are part of it, but framework emits only `ref` and `branch` today. Silently
+    // dropping an entry an author wrote is the failure mode this whole file
+    // exists to prevent.
+    if (entry.url !== undefined || entry.asset !== undefined) {
+      const kind = entry.url !== undefined ? 'url' : 'asset'
+      errors.push(
+        `${RECORDS_YML_RELPATH}: ${where} declares \`${kind}:\`, which the folder producer ` +
+          `does not emit yet. A folder holds urls and assets by design, but nothing would ` +
+          `be sent for this entry — so it is refused rather than dropped.`
+      )
+      return []
+    }
+
+    errors.push(
+      `${RECORDS_YML_RELPATH}: ${where} has no recognized kind. ` +
+        `A bare string is an entity path; anything else says \`folder:\`, \`url:\` or \`asset:\`.`
+    )
+    return []
+  }
+
+  const nodes = (entries || []).flatMap((entry, i) => resolveEntry(entry, [], i, ''))
+
+  // ⚠️ REPORT WHAT NOTHING REFERENCES. It is a legitimate draft state, so it is
+  // not an error — but silence is how every defect in this area survived.
+  for (const e of pool || []) {
+    if (!placements.has(e.id)) {
+      warnings.push(
+        `${e.relPath} is in entities/ but referenced by nothing in ${RECORDS_YML_RELPATH} — ` +
+          `it exists, but it is not a record and no query can reach it.`
+      )
+    }
+  }
+
+  return { nodes, placements, errors, warnings }
+}

package/src/site/schemaless-data.js

@@ -61,7 +61,7 @@ async function readJsonTree(dir) {
 
 // The collection a `dist/data` relpath belongs to: the first path segment, minus a
 // trailing `.json`. `articles.json` → `articles`; `articles/hello.json` → `articles`.
-function collectionOf(relPath) {
+function queryOf(relPath) {
   const first = relPath.split('/')[0]
   return first.endsWith('.json') ? first.slice(0, -5) : first
 }
@@ -79,7 +79,7 @@ export async function collectSchemalessData(distDir, schemalessNames = []) {
   const allData = await readJsonTree(join(distDir, DATA_DIR))
   const data = {}
   for (const [relPath, value] of Object.entries(allData)) {
-    if (schemaless.has(collectionOf(relPath))) data[relPath] = value
+    if (schemaless.has(queryOf(relPath))) data[relPath] = value
   }
   // Agent projections deliberately do NOT ride the ball.
   //

package/src/utils/numeric-prefix.js

@@ -0,0 +1,63 @@
+// The `01-` filename convention — ONE rule, for pages and for records.
+//
+// ⛔ IT WAS PRIVATE TO THE PAGES LANE, and `records.yml` needs exactly the same
+// rule: a leading `01-` orders a file and is stripped from the name it produces.
+// Two copies would drift, and the drift would be invisible — a section ordering
+// one way and a record another, both plausible, with nothing comparing them.
+//
+// ⚠️ Lifted here rather than imported from `site/content-collector.js` because
+// that module reads a site's whole page tree and imports the query resolver; a
+// records reader importing it would close a cycle. A naming convention is a leaf.
+
+/**
+ * Split a leading numeric prefix off a filename stem.
+ *
+ * Dots are sub-levels, so `1`, `1.5`, `2` order as you would read them.
+ *
+ * ⛔ THE RECORDS LANE USES THIS FOR ORDERING ONLY — it does NOT strip the prefix
+ * from a record's slug. A record's slug is its filename stem, whole. An earlier
+ * draft of the model stripped it, and implementing that surfaced why it cannot
+ * work here: a leading number is a DATE at least as often as it is an order, and
+ * the two are indistinguishable by shape. Measured on the model's own example
+ * pool, `2026-03-nature-folding.md` became `03-nature-folding`.
+ *
+ * ⚖️ Sorting is unaffected and stays useful: `2025-11-…` before `2026-03-…` is
+ * exactly what a date prefix should do, and `1-`, `2-`, `10-` order as written
+ * rather than as strings. Reading a number to ORDER by it is safe; consuming it
+ * into a name is not.
+ *
+ * @param {string} filename - a stem, without its extension
+ * @returns {{ prefix: string|null, name: string }}
+ */
+export function parseNumericPrefix(filename) {
+  const match = filename.match(/^(\d+(?:\.\d+)*)-?(.*)$/)
+  if (match) {
+    return { prefix: match[1], name: match[2] || match[1] }
+  }
+  return { prefix: null, name: filename }
+}
+
+/**
+ * Compare two stems by their numeric prefix, falling back to locale order.
+ *
+ * ⚠️ Prefixed names sort BEFORE unprefixed ones. A file the author numbered is
+ * one they placed deliberately; an unnumbered one has no stated position, so it
+ * follows rather than interleaving at an arbitrary point.
+ */
+export function compareByNumericPrefix(a, b) {
+  const { prefix: pa } = parseNumericPrefix(a)
+  const { prefix: pb } = parseNumericPrefix(b)
+
+  if (!pa && !pb) return a.localeCompare(b)
+  if (!pa) return 1
+  if (!pb) return -1
+
+  const partsA = pa.split('.').map(Number)
+  const partsB = pb.split('.').map(Number)
+  for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
+    const na = partsA[i] ?? 0
+    const nb = partsB[i] ?? 0
+    if (na !== nb) return na - nb
+  }
+  return 0
+}

package/src/uwx/backfill.js

@@ -22,7 +22,7 @@ import { readFileSync, writeFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import yaml from 'js-yaml'
 import { proseMirrorToMarkdown } from '@uniweb/content-writer'
-import { parseFrontmatter } from './collection-source.js'
+import { parseFrontmatter } from './entity-source.js'
 import { isProseMirrorField, isContentBodyField } from './data-schema.js'
 import { unwrapLocalizedContent } from './locale-sync.js'
 import { parseBibtex, exportBibtex } from '@citestyle/bibtex'
@@ -35,9 +35,9 @@ const SOURCE_EXTENSIONS = ['.yml', '.yaml', '.json', '.md', '.bib']
  * probing the supported extensions. Returns the absolute path or null (e.g. an
  * array-form file holding many records, whose name is not `<slug>.<ext>`).
  */
-export function findRecordFile(collectionDir, slug) {
+export function findRecordFile(poolDir, slug) {
   for (const ext of SOURCE_EXTENSIONS) {
-    const p = join(collectionDir, slug + ext)
+    const p = join(poolDir, slug + ext)
     if (existsSync(p)) return p
   }
   return null
@@ -235,11 +235,11 @@ function briefHasContentBody(declaration) {
  * @param {string} params.format       - 'yaml' | 'json' | 'md'
  * @param {string} [params.sourceLocale]
  * @param {object} [params.collector]  - translation collector; target locales of
- *        localized SCALAR fields are captured into it (→ locales/collections/{locale}.json),
+ *        localized SCALAR fields are captured into it (→ locales/records/{locale}.json),
  *        and a localized prosemirror BODY's target locales are captured as either a
  *        structural map or, when `freeformRelPath` is given, a free-form body override.
  * @param {string} [params.freeformRelPath] - the free-form path for this record's
- *        content body (buildFreeformCollectionPath); lets a target-locale full-doc
+ *        content body (buildFreeformRecordPath); lets a target-locale full-doc
  *        body be written under locales/freeform/{locale}/ instead of being dropped.
  * @returns {string} the source-file text
  */

package/src/uwx/data-schema.js

@@ -313,9 +313,9 @@ function lowerField(rawField, resolve, optResolve, path = '') {
     // Note the local checker is unaffected and still stricter: `validateItem`
     // works on the IR, where the field is `type: array`, so it verifies the value
     // IS a list. Only what the registry is told changes.
-    const { items: _items, ...collection } = field
+    const { items: _items, ...rest } = field
     return lowerLeaf(
-      { ...collection, ...items, type: items ? items.type : 'json' },
+      { ...rest, ...items, type: items ? items.type : 'json' },
       resolve,
       optResolve,
       { multiple: true }

package/src/uwx/entity-source.js

@@ -0,0 +1,122 @@
+// Read a file-based collection's ORIGINAL source records for sync — the author's
+// files, untouched. This is deliberately NOT `processQueries`
+// (`build/src/site/query-processor.js`): that is the DELIVERY pipeline that
+// builds `public/data/<name>.json` — it converts markdown bodies to ProseMirror,
+// derives excerpt/image, rewrites asset paths, and copies files into
+// `public/collections/`. Sync carries the source, so it must read the source:
+// raw frontmatter + raw markdown body, raw YAML/JSON mappings, raw BibTeX entries.
+// No conversion, no derivation, no filter/sort/limit, no asset side effects.
+//
+// ⭐ THE FLAT-VS-RECURSIVE DIVERGENCE THIS FILE USED TO WARN ABOUT IS CLOSED.
+// It reported records below a collection's top level as building and rendering
+// locally while being absent from the synced set — the delivery lane recursed,
+// this one was one level deep. `entities/{schema}/` has no nesting to disagree
+// about (`site/entity-pool.js` refuses it), and placement moved to `records.yml`,
+// so both lanes now read the same flat pool. The warning went with the ambiguity.
+//
+// A collection `.md` is NOT a page-section `.md`: its frontmatter is structured
+// DATA whose schema is the collection type's data schema (the `model:` Model), and
+// its body is the value of the Model's content body field (a markup `text` field,
+// or a `format: prosemirror` json field) — not foundation/runtime config. See
+// docs/reference/entity-content.md §"Markdown (frontmatter + body)".
+
+import { readFile } from 'node:fs/promises'
+import { basename, extname } from 'node:path'
+import yaml from 'js-yaml'
+import { parseBibtex } from '@citestyle/bibtex'
+
+const SOURCE_EXTENSIONS = new Set(['.md', '.yml', '.yaml', '.json', '.bib'])
+
+/**
+ * Split YAML frontmatter from a markdown body. Mirrors the collection
+ * processor's split (`---\n` delimited) so a record read here re-renders to the
+ * same shape the back-fill writer produces. A file with no frontmatter yields an
+ * empty mapping and the whole text as body.
+ *
+ * @param {string} raw
+ * @returns {{ frontmatter: object, body: string }}
+ */
+export function parseFrontmatter(raw) {
+  if (!raw.trimStart().startsWith('---')) {
+    return { frontmatter: {}, body: raw }
+  }
+  const parts = raw.split('---\n')
+  if (parts.length < 3) {
+    return { frontmatter: {}, body: raw }
+  }
+  try {
+    const frontmatter = yaml.load(parts[1]) || {}
+    const body = parts.slice(2).join('---\n')
+    return { frontmatter, body }
+  } catch {
+    return { frontmatter: {}, body: raw }
+  }
+}
+
+// Format key from a file extension. Single source of the format vocabulary the
+// reader emits and the writer dispatches on.
+function formatFor(ext) {
+  if (ext === '.md') return 'md'
+  if (ext === '.json') return 'json'
+  if (ext === '.yml' || ext === '.yaml') return 'yaml'
+  if (ext === '.bib') return 'bib'
+  return null
+}
+
+/**
+ * Read ONE entity file into its raw source record(s).
+ *
+ * ⭐ THE FILE IS THE UNIT NOW. `entities/{schema}/` supplies the model, so
+ * nothing above this needs a directory scan to know what a file is — the pool
+ * reader (`site/entity-pool.js`) already walked the tree and paired each file
+ * with its schema. A single-record file yields one record; array-form YAML/JSON
+ * and BibTeX yield several, each carrying its own slug.
+ *
+ * @param {string} filepath - absolute path to one entity source file
+ * @returns {Promise<Array<{ slug, format, data, body, sourceFile, multiRecord }>>}
+ */
+export async function readEntityFile(filepath) {
+  return readOneFile(filepath)
+}
+
+async function readOneFile(filepath) {
+  const ext = extname(filepath).toLowerCase()
+  const format = formatFor(ext)
+  const slugFromName = basename(filepath, ext)
+  const raw = await readFile(filepath, 'utf-8')
+
+  if (format === 'md') {
+    const { frontmatter, body } = parseFrontmatter(raw)
+    const slug = frontmatter.slug || slugFromName
+    return [{ slug, format, data: frontmatter, body, sourceFile: filepath, multiRecord: false }]
+  }
+
+  if (format === 'bib') {
+    // BibTeX always yields an array — the cite key is the slug/$id. Multi-record
+    // file → write-back deferred (no natural in-file `$uuid` slot in v1).
+    const entries = parseBibtex(raw)
+    return entries
+      .filter((e) => e && e.id)
+      .map((e) => ({ slug: e.id, format, data: e, body: undefined, sourceFile: filepath, multiRecord: true }))
+  }
+
+  // yaml / json
+  const data = format === 'json' ? JSON.parse(raw) : yaml.load(raw)
+  if (Array.isArray(data)) {
+    // Many records in one file — each carries its own slug. Write-back deferred.
+    return data
+      .filter((item) => item && typeof item === 'object')
+      .map((item) => ({
+        slug: item.slug,
+        format,
+        data: item,
+        body: undefined,
+        sourceFile: filepath,
+        multiRecord: true,
+      }))
+  }
+  const mapping = data && typeof data === 'object' ? data : {}
+  const slug = mapping.slug || slugFromName
+  return [{ slug, format, data: mapping, body: undefined, sourceFile: filepath, multiRecord: false }]
+}
+