@uniweb/build 1.1.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -56,15 +56,15 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/projections": "~1.1.0",
-    "@uniweb/content-writer": "~1.0.1",
-    "@uniweb/semantic-parser": "~1.5.1",
-    "@uniweb/schemas": "~1.0.1",
-    "@uniweb/content-reader": "~1.2.8",
-    "@uniweb/theming": "~1.1.0"
+    "@uniweb/projections": "~1.1.1",
+    "@uniweb/content-writer": "~1.1.0",
+    "@uniweb/theming": "~1.2.0",
+    "@uniweb/semantic-parser": "~1.6.0",
+    "@uniweb/schemas": "~1.2.0",
+    "@uniweb/content-reader": "~1.3.0"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "~1.1.0"
+    "@uniweb/runtime": "~1.1.1"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -73,8 +73,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "~1.1.0",
-    "@uniweb/runtime": "~1.1.0"
+    "@uniweb/runtime": "~1.1.1",
+    "@uniweb/core": "~1.2.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/i18n/freeform.js

@@ -26,6 +26,7 @@ import { poolDirsForSchema, schemaForPoolDirs, RECORDS_DIR } from '../site/entit
 import { parseFrontmatter } from '../utils/frontmatter.js'
 import { computeSourceHash } from './freeform-manifest.js'
 import { layoutAreaRoute } from '../site/layout-folder.js'
+import { warnOutsideVocabulary } from '../site/vocabulary-warnings.js'
 
 // Try to import content-reader for markdown → ProseMirror conversion
 let markdownToProseMirror
@@ -46,6 +47,11 @@ try {
 }
 
 
+/** Report what a translation's markdown could not honour, naming the file. */
+function warnFor(filePath) {
+  return (message) => console.warn(`[i18n] ${relative(process.cwd(), filePath)}: ${message}`)
+}
+
 /**
  * Normalize route for filesystem path
  * Removes leading slash, replaces remaining slashes with path separators
@@ -83,8 +89,10 @@ export async function loadFreeformTranslation(section, page, locale, localesDir)
       const content = await readFile(filePath, 'utf-8')
       const { frontmatter, body } = parseFrontmatter(content, filePath)
 
-      // Convert markdown body to ProseMirror
-      const proseMirrorContent = markdownToProseMirror(body)
+      // Convert markdown body to ProseMirror — HTML in it shows as written,
+      // except `<br>`, and the translator is told which file.
+      const proseMirrorContent = markdownToProseMirror(body, { onWarning: warnFor(filePath) })
+      warnOutsideVocabulary(proseMirrorContent, warnFor(filePath))
 
       return {
         content: proseMirrorContent,
@@ -138,7 +146,8 @@ export async function loadFreeformRecord(item, schema, locale, localesDir) {
     const { frontmatter, body } = parseFrontmatter(content, filePath)
 
     // Convert markdown body to ProseMirror (if body exists)
-    const proseMirrorContent = body.trim() ? markdownToProseMirror(body) : null
+    const proseMirrorContent = body.trim() ? markdownToProseMirror(body, { onWarning: warnFor(filePath) }) : null
+    if (proseMirrorContent) warnOutsideVocabulary(proseMirrorContent, warnFor(filePath))
 
     return {
       frontmatter: Object.keys(frontmatter).length > 0 ? frontmatter : null,

package/src/resolve-data-schema.js

@@ -40,6 +40,7 @@ import { existsSync, readdirSync, statSync } from 'node:fs'
 import { join, resolve, isAbsolute, extname, basename } from 'node:path'
 import { dataRefOf } from '@uniweb/core/data-keys'
 import { SYSTEM_RECORD_SCHEMAS } from '@uniweb/schemas/system'
+import { assertOptionsTargets } from './uwx/data-schema.js'
 import { pathToFileURL } from 'node:url'
 import { createRequire } from 'node:module'
 import yaml from 'js-yaml'
@@ -101,7 +102,7 @@ const packageForScope = (scope) => SCOPE_PACKAGE[scope] ?? `@${scope}/schemas`
  */
 function normalizeNamedSchema(schema, ref) {
   const normalized = validateAndNormalizeSchema(schema, ref)
-  const paths = fieldsWithDefaults(normalized)
+  const paths = fieldsWhere(normalized, (spec) => spec.default !== undefined)
   if (paths.length > 0) {
     throw new Error(
       `Data schema '${ref}': a named data schema declares no default — remove \`default:\` from ` +
@@ -109,11 +110,37 @@ function normalizeNamedSchema(schema, ref) {
         `renders as; an editor pre-fills from a component's own inline field map or form in \`data:\`.`
     )
   }
+  // ⛔ The same reason, two more keys (2026-10-15): nothing keeps them for a named schema. A
+  // registry has no slot for a field's `help` or for a leaf's `constraints` — it refuses the
+  // first, and a section key cannot sit on a leaf — and no reader of the build reads either.
+  // Until then both were dropped when the schema was registered, without a word.
+  const helped = fieldsWhere(normalized, (spec) => spec.help !== undefined)
+  if (helped.length > 0) {
+    throw new Error(
+      `Data schema '${ref}': a named data schema declares no \`help\` — write it as the field's ` +
+        `\`description\`, which a registry keeps: ${helped.map((p) => `'${p}'`).join(', ')}.`
+    )
+  }
+  const ruled = fieldsWhere(normalized, (spec) => spec.constraints !== undefined && !isSectionShaped(spec))
+  if (ruled.length > 0) {
+    throw new Error(
+      `Data schema '${ref}': ${ruled.map((p) => `'${p}'`).join(', ')} declare${ruled.length === 1 ? 's' : ''} ` +
+        `\`constraints\` on a value — they are a section's rules, naming its fields: declare them in the ` +
+        `\`constraints:\` of the section that holds the field (beside \`fields:\` in a \`fields:\` schema).`
+    )
+  }
   return normalized
 }
 
-/** The dotted paths of every field in a normalized schema that declares a `default`. */
-function fieldsWithDefaults(schema) {
+// A field that lowers into a section — a nested object, an open map, a list of records — and so
+// may carry a section's `constraints`.
+function isSectionShaped(spec) {
+  if (spec.type === 'object') return true
+  return spec.type === 'array' && spec.items?.type === 'object'
+}
+
+/** The dotted paths of every field in a normalized schema that `test` holds for. */
+function fieldsWhere(schema, test) {
   const found = []
   const walkFields = (fields, prefix) => {
     if (!fields || typeof fields !== 'object') return
@@ -121,7 +148,7 @@ function fieldsWithDefaults(schema) {
   }
   const walkSpec = (spec, path) => {
     if (!spec || typeof spec !== 'object') return
-    if (spec.default !== undefined) found.push(path)
+    if (test(spec)) found.push(path)
     walkFields(spec.fields, `${path}.`)
     if (spec.items) walkSpec(spec.items, `${path}[]`)
     if (spec.values) walkSpec(spec.values, `${path}{}`)
@@ -292,6 +319,9 @@ export async function buildDataSchemaMap(refs, { srcDir }) {
       if (!map[target]) queue.push(target)
     }
   }
+  // A picklist names a section of the Model holding its choices — refused here, at the author's
+  // screen, when it names none (`optionsSectionPath`), rather than when the schema is registered.
+  assertOptionsTargets(map)
   return map
 }
 

package/src/site/content-collector.js

@@ -42,6 +42,7 @@ import { authoredRedirectTarget } from '@uniweb/core/resolve-route'
 import { parseFrontmatter } from '../utils/frontmatter.js'
 import { parseGrid } from '@uniweb/schemas/grid'
 import { runtimeServicesConfig, refuseRetiredServiceKeys, refuseUnreadableServices } from '../uwx/services-request.js'
+import { warnOutsideVocabulary } from './vocabulary-warnings.js'
 
 // Try to import content-reader, fall back to simplified parser
 let markdownToProseMirror
@@ -1068,7 +1069,12 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
   // come through here (a free-form translation, a record body) kept raw references
   // nothing resolved, and the same section's content differed between a build and a
   // document stored as written.
-  const proseMirrorContent = markdownToProseMirror(markdown)
+  //
+  // HTML in the markdown is not content: it shows as written, except `<br>`
+  // (content-reader, since 2026-10-14). Say so with the file in hand.
+  const warnHere = (message) => console.warn(`[content-collector] ${relative(siteRoot, filePath)}: ${message}`)
+  const proseMirrorContent = markdownToProseMirror(markdown, { onWarning: warnHere })
+  warnOutsideVocabulary(proseMirrorContent, warnHere)
 
   // `query: team` → `fetch: { query: team }`; a list, one config per name, each under
   // its own `as` — the one helper every level uses. Unrelated to a section type's

package/src/site/query-processor.js

@@ -72,6 +72,7 @@ import { toDeliveredRecord, toStoredRecord, storedPath, briefFieldMap, contentBo
 import { collectNestedRefs } from '@uniweb/schemas/format'
 import { labelIn } from './entry-label.js'
 import { fileRecordValue, makeFilePreview } from './file-records.js'
+import { warnOutsideVocabulary } from './vocabulary-warnings.js'
 
 // Try to import content-reader for markdown parsing
 let markdownToProseMirror
@@ -563,8 +564,11 @@ async function processContentItem(dir, filename, config, siteRoot, basePath, rec
   // record was published.
   await processDataItemAssets(frontmatter, filepath, siteRoot, recordsRoot, basePath)
 
-  // Parse markdown body to ProseMirror
-  const content = markdownToProseMirror(body)
+  // Parse markdown body to ProseMirror — HTML in it shows as written, except
+  // `<br>`, and the author is told which file.
+  const warnHere = (message) => console.warn(`[records] ${relative(siteRoot, filepath)}: ${message}`)
+  const content = markdownToProseMirror(body, { onWarning: warnHere })
+  warnOutsideVocabulary(content, warnHere)
 
   // Process assets (resolve paths, copy co-located files)
   // This modifies content in place, updating paths to site-root-relative

package/src/site/vocabulary-warnings.js

@@ -0,0 +1,33 @@
+/**
+ * Say, with the file in hand, what in a document a page leaves out.
+ *
+ * A document holds the rich-text vocabulary (`@uniweb/content-reader/vocabulary`):
+ * its types and attributes, and the values that reach a page's markup. What is
+ * outside it — a link to `javascript:`, an inert `{.name}`, MathML outside the
+ * allowlist — the renderer leaves out of the page, and a backend that cleans the
+ * content it stores removes, so the next pull would write the file without it.
+ * The author hears it here first, once per thing, naming the file.
+ */
+import { outsideVocabulary } from '@uniweb/content-reader/vocabulary'
+
+const SAYS = {
+  url: (f) => `a link to \`${f.found}\` is never followed`,
+  target: (f) => `\`target=${f.found}\` is not a link target`,
+  'style-name': (f) => `\`{${f.found}}\` is not a style name`,
+  color: (f) => `\`${f.found}\` is not a colour`,
+  mathml: (f) => `a formula's MathML holds what a page cannot show (${f.found})`,
+  'ref-id': (f) => `\`${f.found}\` is not an inset reference`,
+}
+
+/**
+ * Warn, for each thing in `doc` outside the vocabulary, with the file it came from.
+ *
+ * @param {Object} doc - a ProseMirror document
+ * @param {(message: string) => void} warn - prints one message, prefixed with the file
+ */
+export function warnOutsideVocabulary(doc, warn) {
+  for (const finding of outsideVocabulary(doc)) {
+    const says = SAYS[finding.rule]?.(finding) ?? `\`${finding.found}\` is not part of a document (${finding.rule})`
+    warn(`${says} — a page leaves it out, and a backend that cleans what it stores removes it`)
+  }
+}

package/src/uwx/data-schema.js

@@ -21,13 +21,16 @@
  * Pure — IR in, declaration out; no I/O, no uuids.
  */
 
+import { parseOptionsRef, FIELD_RULES } from '@uniweb/schemas/format'
+
 // Text kinds carry per-locale values when localized.
 const TEXT_KINDS = new Set(['string', 'text'])
 
 // Rich-content `format` markers on a `text` field — the file-based body shape that
 // replaced the retired `richtext` kind (2026-06-02 / uwx-format.md). A `text` field
 // carrying one round-trips as the RAW source string (no ProseMirror conversion).
-const CONTENT_TEXT_FORMATS = new Set(['markdown', 'html'])
+// ⛔ `html` was one until 2026-10-14; `@uniweb/schemas` refuses it by name since.
+const CONTENT_TEXT_FORMATS = new Set(['markdown'])
 
 // The field an open map's key lowers into. `name` matches the idiom already in use
 // for this shape (the backend's site-content `collections` section), so an open map
@@ -109,11 +112,12 @@ export function isContentBodyField(field) {
  * @param {string} opts.name - the schema's registry name (`@org/x` or `@/x`).
  * @param {(ref: string) => string} [opts.resolveName] - maps a `ref` target name.
  *   Defaults to resolving `@/x` into the schema's own org, passing others through.
- * @param {(ref: string) => string} [opts.resolveOptions] - maps an `options`
- *   (item_ref) ref to its full `@org/model/<section>` path. Falls back to
- *   `resolveName` (model only) when not supplied.
+ * @param {(options: string, fieldPath: string) => string} [opts.resolveOptions] - maps an
+ *   `options` (item_ref) value to the `@org/model/<section-path>` the registry takes — a
+ *   register supplies it (`registry-package.js`), naming the section a short `'@/x'` means.
+ *   Falls back to `resolveName`, which resolves the scope and keeps the rest as written.
  * @returns {Object} the declaration (`{ name, label?, plural?, icon?, description?,
- *          source_locale?, linkable?, sections }`).
+ *          source_locale?, linkable?, grantable?, sections }`).
  */
 export function toDataSchemaDeclaration(normalized, { name, resolveName, resolveOptions } = {}) {
   if (!name) throw new Error('toDataSchemaDeclaration: a registry name is required')
@@ -121,11 +125,33 @@ export function toDataSchemaDeclaration(normalized, { name, resolveName, resolve
     throw new Error('toDataSchemaDeclaration: a normalized schema is required')
   }
   const resolve = resolveName || defaultResolver(name)
-  const optResolve = resolveOptions || resolve
+  const resolveChoices = resolveOptions || resolve
+  // A picklist that names no list is refused naming the schema and the field — and so is one
+  // that picks from a section of its own schema (`OWN_SECTION`).
+  const optResolve = (options, fieldPath) => {
+    let resolved
+    try {
+      resolved = resolveChoices(options, fieldPath)
+    } catch (err) {
+      throw new Error(`Data schema '${name}': field '${fieldPath}' ${err.message}`)
+    }
+    if (typeof resolved === 'string' && resolved.startsWith(`${name}/`)) {
+      throw new Error(`Data schema '${name}': field '${fieldPath}' ${OWN_SECTION}`)
+    }
+    return resolved
+  }
 
-  const { sections, brief } = normalized.sections
-    ? lowerSectionsForm(normalized.sections, resolve, optResolve)
-    : lowerFieldsForm(normalized.fields || {}, resolve, optResolve)
+  let lowered
+  try {
+    lowered = normalized.sections
+      ? lowerSectionsForm(normalized.sections, resolve, optResolve)
+      : lowerFieldsForm(normalized.fields || {}, resolve, optResolve, normalized.constraints)
+  } catch (err) {
+    // A field the lowering refuses is named with its schema.
+    if (err.fieldPath !== undefined) throw new Error(`Data schema '${name}': ${err.message}`)
+    throw err
+  }
+  const { sections, brief } = lowered
 
   // The model-level sort axis is inline: `sort_date: true` on the brief's named
   // date field (replaces the old schema-level `sort_date_field` back-reference).
@@ -158,6 +184,10 @@ export function toDataSchemaDeclaration(normalized, { name, resolveName, resolve
   // reference, which read as a promise that one is accepted. A backend refuses it.
   if (normalized.linkable === false) decl.linkable = false
 
+  // `grantable` — AUTHORED ONLY, like `linkable`: a model's entries may be shared one at a
+  // time unless it says `grantable: false` (omitted ⇒ true) [Diego, 2026-10-14].
+  if (normalized.grantable === false) decl.grantable = false
+
   decl.sections = sections
   return decl
 }
@@ -176,9 +206,10 @@ export function toDataSchemaDeclaration(normalized, { name, resolveName, resolve
 // only the recommended name for its card.
 export const SHORTHAND_SECTION = 'brief'
 
-function lowerFieldsForm(fields, resolve, optResolve) {
+// A `fields:` schema's top-level `constraints:` are its one section's rules (2026-10-15).
+function lowerFieldsForm(fields, resolve, optResolve, constraints) {
   return {
-    sections: { [SHORTHAND_SECTION]: lowerSection({ kind: 'single', brief: true, fields }, resolve, optResolve) },
+    sections: { [SHORTHAND_SECTION]: lowerSection({ kind: 'single', brief: true, fields, constraints }, resolve, optResolve) },
     brief: SHORTHAND_SECTION,
   }
 }
@@ -381,17 +412,17 @@ function lowerField(rawField, resolve, optResolve, path = '') {
       { ...rest, ...items, type: items ? items.type : 'json' },
       resolve,
       optResolve,
-      { multiple: true }
+      { multiple: true, path }
     )
   }
 
-  return lowerLeaf(field, resolve, optResolve)
+  return lowerLeaf(field, resolve, optResolve, { path })
 }
 
 // Lower a LEAF-SHAPED field — a scalar, a reference (`entity_ref`), or a curated
 // picklist (`item_ref`) — with or without `multiple`. The single place field
 // attributes are emitted, so every leaf-shaped kind carries the same set.
-function lowerLeaf(field, resolve, optResolve, { multiple = false } = {}) {
+function lowerLeaf(field, resolve, optResolve, { multiple = false, path = '' } = {}) {
   const leafType = field.type
 
   // `richtext` is NOT a kind — it is the author alias for a ProseMirror document
@@ -411,11 +442,30 @@ function lowerLeaf(field, resolve, optResolve, { multiple = false } = {}) {
   }
   const leafFormat = field.format
 
+  // A section's rules on a value have nowhere to go: the wire's `constraints` is a section key.
+  // A named schema refuses them before this (`resolve-data-schema.js`); refused here too, rather
+  // than dropped, which they were until 2026-10-15.
+  if (field.constraints !== undefined) {
+    throw Object.assign(
+      new Error(
+        `field '${path}' declares \`constraints\` on a value — they are a section's rules: declare them ` +
+          `in the \`constraints:\` of the section that holds it.`
+      ),
+      { fieldPath: path }
+    )
+  }
+
   const out = { type: leafType }
   if (multiple) out.multiple = true
   if (field.label) out.label = field.label
   if (field.description) out.description = field.description
   if (field.required) out.required = true
+  // A field's rules, as written — `max_length`, `min`, `max`, `mime_types`, `max_size`
+  // (`FIELD_RULES`): a registry keeps each as the field's own key and checks it on every
+  // write. ⛔ Until 2026-10-15 the normalizer dropped them before this saw them.
+  for (const key of Object.keys(FIELD_RULES)) {
+    if (field[key] !== undefined) out[key] = field[key]
+  }
 
   // A reference to a whole entity, hydrating to the target's brief. It is a
   // FIELD, so it carries field attributes — the same ones `item_ref` below has
@@ -424,13 +474,17 @@ function lowerLeaf(field, resolve, optResolve, { multiple = false } = {}) {
   if (leafType === 'ref') {
     out.type = 'entity_ref'
     if (field.ref) out.model = resolve(field.ref)
+    // The level on the entry it points to that opens this entry, for `read` — by link
+    // [Diego, 2026-10-14]. `@uniweb/schemas` admits it only here, as read, edit or admin.
+    if (field.readable_with) out.readable_with = field.readable_with
     return out
   }
 
-  // A curated picklist is an item_ref (machine-ish — never localized).
+  // A curated picklist is an item_ref (machine-ish — never localized), naming the section whose
+  // items are its choices (`optionsSectionPath`).
   if (field.options !== undefined) {
     out.type = 'item_ref'
-    out.options = optResolve(field.options)
+    out.options = optResolve(field.options, path)
     return out
   }
 
@@ -461,6 +515,142 @@ function lowerLeaf(field, resolve, optResolve, { multiple = false } = {}) {
   return out
 }
 
+// --- picklists ----------------------------------------------------------------
+
+// ⛔ A picklist cannot take its choices from a section of its own schema: a registry refuses it on
+// every register, whatever order the package lists its schemas in (measured 2026-10-15). Refused
+// here, at the author's screen, until a registry takes it.
+const OWN_SECTION =
+  'takes its choices from a section of its own schema, which a registry does not take — keep the list in a Model of its own.'
+
+/**
+ * ⭐ THE SECTION A PICKLIST'S CHOICES ARE IN — its path in the options Model, as the registry
+ * names it (2026-10-15). A field that picks from a list names the section holding the list:
+ * `options: '@/lists/countries'`, a nested one by its path (`'@/lists/countries/subdivisions'`).
+ * A Model whose top holds ONE list may be named alone — `'@/country'`, the `fields:` shorthand's
+ * one section, is the common case — and that list is the one meant.
+ *
+ * A register sends `@scope/name/<this path>` (`registry-package.js`): a registry takes an
+ * `item_ref`'s `options` as `@org/model/section-path` and refuses one that names no section
+ * (2026-10-15).
+ *
+ * ⛔ A Model with several lists at its top is refused when named alone: which one the author meant
+ * is not ours to guess. Until 2026-10-15 the first single-or-multi section was taken, and a path
+ * could not be written at all, so a Model's second list could never be a field's choices.
+ *
+ * @param {string} options - the field's `options:` as authored (`@/lists/countries`)
+ * @param {Object} target - the options Model, normalized
+ * @returns {string} the section's path in the Model (`countries`, `brief` for the shorthand)
+ * @throws when the path names no section, or a section that holds only sections, or is left out
+ *   of a Model whose top holds more than one list — naming the lists it has
+ */
+export function optionsSectionPath(options, target) {
+  const { model, path } = parseOptionsRef(options)
+  const sections = sectionPathsOf(target)
+  const lists = sections.filter((s) => s.holdsItems).map((s) => s.path)
+  const named = (paths) => paths.map((p) => `'${model}/${p}'`).join(', ')
+  if (path == null) {
+    const top = lists.filter((p) => !p.includes('/'))
+    if (top.length === 1) return top[0]
+    throw new Error(
+      top.length === 0
+        ? `takes its choices from '${options}', which holds no list at its top — name the section that holds them: ${named(lists) || '(it has none)'}.`
+        : `takes its choices from '${options}', which holds ${top.length} lists at its top — name the one: ${named(top)}.`
+    )
+  }
+  const found = sections.find((s) => s.path === path)
+  if (!found) {
+    throw new Error(`takes its choices from '${options}', but '${model}' has no section '${path}' — its lists: ${named(lists) || '(none)'}.`)
+  }
+  if (!found.holdsItems) {
+    const under = lists.filter((p) => p.startsWith(`${path}/`))
+    throw new Error(
+      `takes its choices from '${options}', a section that holds only sections, so it has no items to choose — ` +
+        `name a list under it: ${named(under) || '(it has none)'}.`
+    )
+  }
+  return path
+}
+
+/**
+ * Check every picklist in a closed map of normalized schemas against the Model it names, throwing
+ * for the first whose `options:` names no list (`optionsSectionPath`). A Model the map does not
+ * hold is skipped: resolving the graph fails on it first.
+ *
+ * @param {Object<string, Object>} dataSchemas - `{ [ref]: normalized }`, closed under references
+ */
+export function assertOptionsTargets(dataSchemas) {
+  for (const [ref, schema] of Object.entries(dataSchemas || {})) {
+    forEachOptionsField(schema, (fieldPath, options) => {
+      const { model } = parseOptionsRef(options)
+      if (model === ref) throw new Error(`Data schema '${ref}': field '${fieldPath}' ${OWN_SECTION}`)
+      const target = dataSchemas[model]
+      if (!target) return
+      try {
+        optionsSectionPath(options, target)
+      } catch (err) {
+        throw new Error(`Data schema '${ref}': field '${fieldPath}' ${err.message}`)
+      }
+    })
+  }
+}
+
+// Every field of a normalized schema that declares `options:`, with its dotted path — in any
+// section, nested object, list of records or open map.
+function forEachOptionsField(schema, fn) {
+  const visitField = (raw, path) => {
+    const field = asField(raw)
+    if (typeof field.options === 'string') fn(path, field.options)
+    if (field.items) visitField(field.items, path)
+    if (field.values) visitField(field.values, path)
+    for (const [key, child] of Object.entries(field.fields || {})) visitField(child, `${path}.${key}`)
+  }
+  const visitSection = (section, prefix) => {
+    for (const [key, field] of Object.entries(section?.fields || {})) visitField(field, `${prefix}${key}`)
+    for (const [name, child] of Object.entries(section?.sections || {})) visitSection(child, `${prefix}${name}.`)
+  }
+  if (schema?.fields) visitSection(schema, '')
+  for (const [name, section] of Object.entries(schema?.sections || {})) visitSection(section, `${name}.`)
+}
+
+// The sections of a normalized Model by the path the registry names each one by, and whether each
+// holds items — the lowering's own shapes (`lowerField`): a child in `sections:`, a nested object
+// (one record), a list of records, an open map (rows). A section holding only sections — a binder —
+// holds none.
+function sectionPathsOf(normalized) {
+  const out = []
+  const visit = (path, node) => {
+    out.push({ path, holdsItems: holdsItems(node) })
+    for (const [name, child] of Object.entries(node.sections || {})) visit(`${path}/${name}`, child)
+    for (const [name, field] of Object.entries(node.fields || {})) {
+      const nested = sectionOfField(field)
+      if (nested) visit(`${path}/${name}`, nested)
+    }
+  }
+  if (normalized?.fields) visit(SHORTHAND_SECTION, { kind: 'single', fields: normalized.fields })
+  for (const [name, section] of Object.entries(normalized?.sections || {})) visit(name, section)
+  return out
+}
+
+// The section a section-shaped FIELD lowers into (`lowerField`), or null for a leaf.
+function sectionOfField(raw) {
+  const field = asField(raw)
+  if (field.type === 'object') {
+    if (field.values !== undefined) return { kind: 'multi', fields: { [OPEN_MAP_KEY]: { type: 'string' }, ...asField(field.values).fields } }
+    return { kind: 'single', fields: field.fields }
+  }
+  if (field.type === 'array' && field.items && asField(field.items).type === 'object') {
+    return { kind: 'multi', fields: asField(field.items).fields }
+  }
+  return null
+}
+
+function holdsItems(section) {
+  if ((section.kind || 'single') === 'multi') return true
+  if (section.kind === 'binder') return false
+  return Object.values(section.fields || {}).some((field) => !sectionOfField(field))
+}
+
 // --- helpers -----------------------------------------------------------------
 
 function asField(def) {

package/src/uwx/registry-package.js

@@ -27,7 +27,8 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { normalizeFoundationSchema } from '@uniweb/schemas/foundation'
-import { toDataSchemaDeclaration, SHORTHAND_SECTION } from './data-schema.js'
+import { parseOptionsRef } from '@uniweb/schemas/format'
+import { toDataSchemaDeclaration, optionsSectionPath } from './data-schema.js'
 import { checkFoundationName, splitFoundationName } from '../foundation-name.js'
 
 const FOUNDATION_SCHEMA = '@uniweb/foundation-schema'
@@ -155,7 +156,8 @@ function buildDataSchemaEntities(dataSchemas, scope) {
     .map(([ref, normalized]) => ({
       model: DATA_SCHEMA,
       // `name` resolved to the concrete scope; entity_ref `models` resolve the same
-      // way; item_ref `options` get the full `@org/x/<section>` path (§10.1).
+      // way; item_ref `options` name the section whose items are the choices
+      // (`@org/x/<section-path>`, `makeOptionsResolver`).
       ...toDataSchemaDeclaration(normalized, { name: scoped(ref), resolveName: scoped, resolveOptions }),
     }))
   return { entities: referencedFirst(entities), scoped, org }
@@ -279,27 +281,23 @@ function buildRefs(dataSchemas, scoped) {
   return Object.keys(dataSchemas).sort().map((ref) => ({ name: scoped(ref) }))
 }
 
-// Resolve an item_ref `options: '@/x'` to the full `@/x/<section>` path the
-// backend needs (it splits on the last `/`; a bare model mis-resolves — §10.1).
-// The section is the options model's single item-bearing (single/multi) section.
+// An item_ref's `options` as a registry takes it: `@scope/name/<section-path>`. A registry
+// refuses a path that names no section, and picks none for us (2026-10-15). The section is
+// the one the author named, or — for `'@/x'` alone — the options Model's one list
+// (`optionsSectionPath`, which refuses a Model with several).
+// ⛔ Until 2026-10-15 this took the Model's FIRST single-or-multi section, and this comment said
+// the registry "splits on the last `/`" — it does not, and a two-segment path is refused.
 function makeOptionsResolver(dataSchemas, scoped) {
-  return (ref) => {
-    const model = dataSchemas[ref]
-    if (!model) return scoped(ref)
-    const section = itemBearingSectionName(model, ref)
-    return section ? `${scoped(ref)}/${section}` : scoped(ref)
-  }
-}
-
-function itemBearingSectionName(normalized, ref) {
-  // fields-form → the shorthand's one section, always named `brief`
-  if (normalized.fields) return SHORTHAND_SECTION
-  // sections-form → the first item-bearing (single/multi) section
-  for (const [name, sec] of Object.entries(normalized.sections || {})) {
-    const kind = sec.kind || 'single'
-    if (kind === 'single' || kind === 'multi') return name
+  return (options) => {
+    const { model, path } = parseOptionsRef(options)
+    const target = dataSchemas[model]
+    if (target) return `${scoped(model)}/${optionsSectionPath(options, target)}`
+    if (path) return `${scoped(model)}/${path}`
+    throw new Error(
+      `takes its choices from '${options}', a Model this package does not define — name the section ` +
+        `that holds them: '${options}/<section>'.`
+    )
   }
-  return null
 }
 
 // Per-locale sidecar map from `<foundationDir>/i18n/<locale>.json`. `{}` when none.

package/src/uwx/site-project.js

@@ -47,7 +47,8 @@ import { declarationsToQueriesYml } from './records-project.js'
 import { FILLED_SECTION_TYPE, buildRouteOf } from './site.js'
 import { translationContext, SITE_META_CONTEXT } from '../i18n/extract.js'
 import { authorableDeclaration, DECLARATION_KEYS } from '../site/fetch-shapes.js'
-import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations, unwrapLocalizedContent } from './locale-sync.js'
+import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations, unwrapLocalizedContent, isProseMirrorDoc } from './locale-sync.js'
+import { unwritableNodes } from '@uniweb/content-writer'
 import { buildFreeformPath, freeformPathsFor } from '../i18n/freeform.js'
 import { unwrapLocalized, unwrapLocalizedList } from './backfill.js'
 import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
@@ -1201,6 +1202,59 @@ function projectLayout(layoutSections, layoutBaseDir, report, prune, ctx) {
   if (prune && written.length > 0) pruneOrphanLayout(layoutBaseDir, new Set(written), report)
 }
 
+/**
+ * ⛔ A PULL THAT WOULD DROP CONTENT WRITES NOTHING.
+ *
+ * A node a markdown file cannot hold is left out of the file it is written to,
+ * and the push after the pull then deletes it from the site — with nobody told
+ * but a log line. So every section document the projection would write is asked
+ * first (`unwritableNodes`, `@uniweb/content-writer`), every locale's included,
+ * and the pull stops, naming each section and what it holds.
+ * ⛔ Until 2026-10-14 the writer logged one line per type and the pull went on:
+ * measured with a button an editor saved as a node, which a pull and a push then
+ * deleted.
+ *
+ * @param {object} document - the `@uniweb/site-content` document
+ * @param {string} sourceLocale
+ */
+function refuseContentFilesCannotHold(document, sourceLocale) {
+  const found = []
+  const name = (record, where) => {
+    const own = record?.slug !== undefined ? pageDirName(record, sourceLocale) : record?.stable_id || record?.$uuid
+    return own ? (where ? `${where}/${own}` : String(own)) : where
+  }
+  const visit = (value, where) => {
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item, where)
+      return
+    }
+    if (!value || typeof value !== 'object') return
+    const here = name(value, where)
+    for (const [key, field] of Object.entries(value)) {
+      if (key === 'content') {
+        const docs = isProseMirrorDoc(field)
+          ? [field]
+          : isPlainRecord(field)
+            ? Object.values(field).filter(isProseMirrorDoc)
+            : []
+        const types = [...new Set(docs.flatMap((doc) => unwritableNodes(doc)))]
+        if (types.length) found.push(`${here || 'a section'}: ${types.join(', ')}`)
+        if (docs.length) continue
+      }
+      visit(field, here)
+    }
+  }
+  visit(document?.pages, '')
+  visit(document?.layout_sections, 'layout')
+  if (found.length === 0) return
+  throw new Error(
+    'This pull would leave content out of your files — a file cannot hold it, so your next push would ' +
+      'delete it from the site. Nothing was written.\n' +
+      found.map((entry) => `  ${entry}`).join('\n') +
+      '\nChange or remove it where it was made, then pull again.'
+  )
+}
+
 /**
  * Project a whole `@uniweb/site-content` document to a site's files: `info` →
  * config (siteInfoToConfig), `collections[]` declarations →
@@ -1226,6 +1280,9 @@ function projectLayout(layoutSections, layoutBaseDir, report, prune, ctx) {
  * @returns {{ config: object, collections: object, locales: object, pages: string[], sections: string[], layout: string[], deleted: string[], renamed: object[] }}
  */
 export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, prune = false, keepAuthoredFoundation = false, scope, dataModel = null }) {
+  // Before anything is written: a pull that would leave content out of the files stops here.
+  refuseContentFilesCannotHold(document, sourceLocale)
+
   const report = { config: null, collections: null, locales: null, assets: null, pages: [], sections: [], layout: [], deleted: [], renamed: [] }
 
   // Collects target-locale translations of localized scalars as they're projected;