@uniweb/build 0.16.19 → 0.16.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.16.19",
+  "version": "0.16.21",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,16 +59,16 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/schemas": "0.2.7",
+    "@uniweb/schemas": "0.2.9",
+    "@uniweb/projections": "0.2.5",
     "@uniweb/theming": "0.1.15",
-    "@uniweb/content-writer": "0.3.3",
-    "@uniweb/projections": "0.2.5"
+    "@uniweb/content-writer": "0.3.3"
   },
   "optionalDependencies": {
-    "@uniweb/schemas": "0.2.7",
-    "@uniweb/runtime": "0.9.8",
-    "@uniweb/semantic-parser": "1.2.1",
-    "@uniweb/content-reader": "1.2.2"
+    "@uniweb/schemas": "0.2.9",
+    "@uniweb/content-reader": "1.2.2",
+    "@uniweb/runtime": "0.9.9",
+    "@uniweb/semantic-parser": "1.2.1"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",

package/src/index.js

@@ -19,6 +19,7 @@ export {
   validateItem,
   validateDataInputs,
   validateConceptBlocks,
+  validateTaggedDataBlocks,
   isStaticallyCheckable,
 } from './validate-data.js'
 

package/src/resolve-data-schema.js

@@ -57,6 +57,7 @@ export {
   STRUCTURAL_KINDS,
   FORMAT_TYPES,
   SECTION_KINDS,
+  AUTHORING_TYPES,
   SCHEMA_EXTENSIONS,
   parseSchemaRef,
   validateAndNormalizeSchema,

package/src/uwx/data-schema.js

@@ -152,11 +152,16 @@ function lowerSection(def, resolve, optResolve, path = '') {
   if (def.brief === true) out.brief = true
   // Display prose IS a section key — the registry stores it and keys it for
   // translation as `section.<name>.label` / `.description` (confirmed 2026-08-05).
-  // Note the asymmetry with a LEAF, which is the opposite way round: a leaf's
-  // `label`/`description` are accepted by the registry's parser and then DROPPED,
-  // because a field declaration has no slot for prose — field labels live in
-  // translation rows (`section.<name>.field.<key>.label`), which this producer
-  // does not emit today. So section prose arrives; leaf prose does not.
+  // A LEAF is stored differently: its `label`/`description` are accepted by the
+  // registry's parser and then dropped FROM THE FIELD DECLARATION, because a
+  // field declaration has no slot for prose — field labels live in translation
+  // rows keyed `section.<name>.field.<key>.label`. Whether the parser relocates
+  // our inline values into those rows (as it relocates `enum` into a `one_of`
+  // constraint) or discards them is not stated, and it is the difference between
+  // authored field prose reaching the app and not. We keep emitting it either
+  // way: it is accepted, so there is no failure mode, and relocation needs no
+  // producer change. Do not restate this as "leaf prose is lost" — that reading
+  // was asserted here once on the strength of the word "dropped" alone.
   if (def.label) out.label = def.label
   if (def.description) out.description = def.description
   if (def.nestable) out.self_nesting = true
@@ -252,7 +257,7 @@ function lowerField(rawField, resolve, optResolve, path = '') {
         ...lowerSection(
           {
             kind: 'multi',
-            ...sectionProse(field),
+            ...sectionAttrsFromField(field),
             // `translatable: false` is load-bearing, not tidiness: a string field is
             // localized by default, and a localized key could differ per locale —
             // which would destroy the identity the key exists to carry. The key is an
@@ -261,7 +266,13 @@ function lowerField(rawField, resolve, optResolve, path = '') {
               [OPEN_MAP_KEY]: { type: 'string', required: true, translatable: false },
               ...value.fields
             },
-            constraints: [{ kind: 'unique_field', field: OPEN_MAP_KEY, scope: 'section' }]
+            // The uniqueness rule is STRUCTURAL — it is what makes the map's key the
+            // row's identity — so it is prepended rather than assigned: an author's
+            // own constraints on this field add to it and can never replace it.
+            constraints: [
+              { kind: 'unique_field', field: OPEN_MAP_KEY, scope: 'section' },
+              ...(sectionAttrsFromField(field).constraints || [])
+            ]
           },
           resolve,
           optResolve,
@@ -271,7 +282,7 @@ function lowerField(rawField, resolve, optResolve, path = '') {
     }
     return {
       type: 'section',
-      ...lowerSection({ kind: 'single', ...sectionProse(field), fields: field.fields }, resolve, optResolve, path)
+      ...lowerSection({ kind: 'single', ...sectionAttrsFromField(field), fields: field.fields }, resolve, optResolve, path)
     }
   }
   if (type === 'array') {
@@ -279,7 +290,7 @@ function lowerField(rawField, resolve, optResolve, path = '') {
     if (items && items.type === 'object') {
       return {
         type: 'section',
-        ...lowerSection({ kind: 'multi', ...sectionProse(field), fields: items.fields }, resolve, optResolve, path)
+        ...lowerSection({ kind: 'multi', ...sectionAttrsFromField(field), fields: items.fields }, resolve, optResolve, path)
       }
     }
     // A multi-valued LEAF or REFERENCE. `normalizeField` split this field in two
@@ -289,9 +300,22 @@ function lowerField(rawField, resolve, optResolve, path = '') {
     // to `items` — so rejoin the halves and lower them as one leaf carrying
     // `multiple: true`. Reading only `items.type` here is what silently dropped
     // both halves' attributes; the rejoin is the exact inverse of the split.
+    //
+    // An UNTYPED array (`items` omitted — the authoring format allows it) becomes
+    // `json`, not `string`. It used to invent `string`, which is a claim about the
+    // elements that the author never made and that is wrong the moment the list
+    // holds anything else: `@std/form`'s `enum` is documented as "bare strings
+    // AND/OR { value, label }", and it was reaching the registry declared as a
+    // list of strings. `json` is this vocabulary's word for an opaque structured
+    // value, which is exactly what an undeclared element type is. Declaring
+    // `items:` remains the way to say something stronger.
+    //
+    // 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
     return lowerLeaf(
-      { ...collection, ...items, type: items ? items.type : 'string' },
+      { ...collection, ...items, type: items ? items.type : 'json' },
       resolve,
       optResolve,
       { multiple: true }
@@ -379,14 +403,31 @@ function asField(def) {
 }
 
 // A nested section is authored as a FIELD (`{ type: object, description: … }`),
-// but arrives on the wire as a section — so its prose has to travel from the
-// field declaration onto the section body, where the registry has a slot for it.
-// Without this an authored `description:` on a nested object was dropped twice
-// over: once by the normalizer, then again here.
-function sectionProse(field) {
+// but arrives on the wire as a section — so the attributes that belong to a
+// SECTION have to travel from the field declaration onto the section body, where
+// the registry has a slot for them. Without this an authored `description:` on a
+// nested object was dropped twice over (once by the normalizer, then again here),
+// and `constraints:` never arrived at all.
+//
+// `constraints` is the load-bearing one. A list of records is normally authored
+// as a field — `authors: { type: object, many: true }` — so until this existed,
+// section rules were declarable only in the `sections:` form and unreachable in
+// the shape that usually needs them. `min_items` is the motivating rule; note it
+// is a WRITE guarantee ("a delete may not take the section below N"), never a
+// render guarantee — a component still handles an empty list, because the same
+// Model is renderable by a foundation that never saw the constraint.
+function sectionAttrsFromField(field) {
   const out = {}
   if (field.label) out.label = field.label
   if (field.description) out.description = field.description
+  if (Array.isArray(field.constraints) && field.constraints.length) out.constraints = field.constraints
+  // `tree` (→ `self_nesting`) and `append_only` describe how a list of records
+  // behaves, so they belong to the section too. Same silent-drop as `constraints`
+  // had: a list authored as a FIELD could not be a tree or append-only, while the
+  // identical thing in `sections:` form could. `self_nesting` is valid on a nested
+  // section, not only a top-level one (backend, 2026-08-05).
+  if (field.nestable) out.nestable = true
+  if (field.append_only) out.append_only = true
   return out
 }
 

package/src/uwx/registry-package.js

@@ -48,6 +48,9 @@ try {
  * @param {string} [params.scope] - org scope (`@acme` or `acme`) resolving `@/x` -> `@acme/x`.
  * @param {Object} [params.exporter] - `{ tool, version, instance }` for the envelope.
  * @param {string} [params.exportedAt] - ISO timestamp (default: now).
+ * @param {string} [params.runtime] - the `@uniweb/runtime` version this build
+ *   linked against (its compatibility floor), from `dist/runtime-pin.json`.
+ *   Rides in `info.runtime`; omitted when unknown.
  * @param {string} [params.digest] - the foundation's content digest (`sha256:…`),
  *   computed by the CLI over what register ships (shipping-model.md §4.1). Rides
  *   in the foundation-schema entity's `info.digest`; the backend stores it
@@ -55,7 +58,7 @@ try {
  *   can detect "code changed since release" with no local state.
  * @returns {Object} the `.uwx` document (uwx/1; entities, names only, no uuids).
  */
-export function buildRegistryPackage({ schema, foundationDir, scope, exporter, exportedAt, digest } = {}) {
+export function buildRegistryPackage({ schema, foundationDir, scope, exporter, exportedAt, digest, runtime } = {}) {
   const self = schema?._self
   if (!self || !self.name || !self.version) {
     throw new Error('buildRegistryPackage: schema._self with name + version is required')
@@ -70,7 +73,7 @@ export function buildRegistryPackage({ schema, foundationDir, scope, exporter, e
 
   const foundationEntity = {
     model: FOUNDATION_SCHEMA,
-    info: buildInfo(self, org, digest),
+    info: buildInfo(self, org, digest, runtime),
     schema: buildSchemaBlob(schema),
     i18n: { locales: loadI18nLocales(foundationDir) },
     'data-schemas': { refs: buildRefs(dataSchemas, scoped) },
@@ -144,12 +147,18 @@ function wrapEntities(entities, exporter, exportedAt) {
 // Identity card — decomposed so it's readable without opening the blob. The
 // optional `digest` (sha256:…) is the foundation's content fingerprint; the
 // backend stores it opaque and returns it on the foundation-latest read.
-function buildInfo(self, org, digest) {
+function buildInfo(self, org, digest, runtime) {
   // Scope a bare foundation name (`src` -> `@acme/src`); leave an already-scoped name.
   const name = org && !String(self.name).startsWith('@') ? `@${org}/${self.name}` : self.name
   const info = { name, version: self.version, role: self.role || 'foundation' }
   if (self.description !== undefined) info.description = self.description
   if (digest) info.digest = digest
+  // The compatibility FLOOR this build links against (dist/runtime-pin.json).
+  // Omitted when unknown — and a consumer must read the omission as UNKNOWN
+  // rather than unconstrained, since a floor nobody stated cannot be shown to
+  // be satisfied. Same lift as `digest`: stated by the producer, opaque to the
+  // backend, acted on by whoever resolves a whole site.
+  if (runtime) info.runtime = runtime
   return info
 }
 

package/src/validate-data.js

@@ -29,7 +29,7 @@ import { join, resolve, basename } from 'node:path'
 import yaml from 'js-yaml'
 import { collectionNameFromUrl } from '@uniweb/core'
 
-import { validateItem, isStaticallyCheckable } from '@uniweb/schemas/conform'
+import { validateItem, isStaticallyCheckable, validateBound } from '@uniweb/schemas/conform'
 import { validateAndNormalizeSchema } from './resolve-data-schema.js'
 
 // The pure checker, re-exported so `@uniweb/build/validate` stays the one import
@@ -173,6 +173,13 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
   for (const ref of concepts.schemas) schemasSeen.add(ref)
   recordCount += concepts.checked
 
+  // Pass 4 — tagged data blocks, which join by the component's OWN binding.
+  const blocks = validateTaggedDataBlocks(site, foundation, dataSchemas)
+  violations.push(...blocks.violations)
+  deferred.push(...blocks.deferred)
+  for (const ref of blocks.schemas) schemasSeen.add(ref)
+  recordCount += blocks.checked
+
   return {
     violations,
     deferred,
@@ -307,11 +314,15 @@ export async function validateConceptBlocks(site) {
 
 /** Every concept block in a doc, including any nested inside a container. */
 function conceptBlockNodes(doc) {
+  return nodesOfType(doc, 'concept_block')
+}
+
+function nodesOfType(doc, type) {
   const out = []
   const walk = (nodes) => {
     for (const node of nodes || []) {
       if (!node) continue
-      if (node.type === 'concept_block') out.push(node)
+      if (node.type === type) out.push(node)
       else if (Array.isArray(node.content)) walk(node.content)
     }
   }
@@ -319,6 +330,84 @@ function conceptBlockNodes(doc) {
   return out
 }
 
+/**
+ * Check each ```` ```yaml:<tag> ```` / ```` ```json:<tag> ```` data block against
+ * the schema the section's own component BOUND to that key.
+ *
+ * This is the pass that closes an odd hole: a component declares
+ * `data: { form: '@std/form' }`, an author writes a ```` ```yaml:form ```` block,
+ * and until now **nothing checked one against the other**. The join walked
+ * `section.fetch` — collections and fetches — so a schema bound to a key that a
+ * tagged block fills was never applied to anything. `@std/form` existed for
+ * exactly this and had never run outside its own contract test.
+ *
+ * Unlike concept blocks (pass 3), the join here is NOT by convention. A concept
+ * block resolves `md:faq` → `@std/faq` mechanically, which is why that pass must
+ * stay silent when no such schema exists. This one uses the binding the component
+ * actually declared, so there is no naming rule and no registry — a tag nobody
+ * bound is simply not governed, and says nothing.
+ *
+ * The value needs no parsing: a tagged fence lands as a `dataBlock` node with its
+ * parsed value already on `attrs.data`, and a body that FAILED to parse never
+ * becomes one (it falls back to `codeBlock`), so a malformed block cannot reach
+ * here and be misreported as a schema violation.
+ *
+ * Uses `validateBound` rather than `validateItem` because a block's value may be
+ * a record OR a list — ```` ```yaml:nav ```` is a bare array. That dispatch is the
+ * reason root-list conformance had to land first.
+ *
+ * @param {Object} site - collected site content
+ * @param {Object} foundation - the built foundation schema (type → { data })
+ * @param {Object} dataSchemas - normalized schemas keyed by ref
+ * @returns {{ violations: Array, schemas: Set<string>, checked: number, deferred: Array }}
+ */
+export function validateTaggedDataBlocks(site, foundation, dataSchemas) {
+  const violations = []
+  const schemas = new Set()
+  const deferred = []
+  let checked = 0
+
+  for (const page of site?.pages || []) {
+    walkSections(page.sections || [], (section) => {
+      const type = section.type
+      const bindings = type && foundation?.[type]?.data
+      if (!bindings || typeof bindings !== 'object') return
+
+      for (const node of nodesOfType(section.content, 'dataBlock')) {
+        const tag = node.attrs?.tag
+        if (!tag) continue
+
+        const binding = bindings[tag]
+        if (binding === undefined) continue // this key is not governed — say nothing
+
+        // A binding is a named ref, or an inline schema. Only a ref resolves to a
+        // normalized schema here; an inline one is reported rather than guessed at.
+        const ref = typeof binding === 'string' ? binding : binding?.schema
+        if (typeof ref !== 'string') {
+          deferred.push({ route: page.route, section: type, key: tag, reason: 'inline schema on the binding' })
+          continue
+        }
+        const schema = dataSchemas?.[ref]
+        if (!schema) continue // unresolved ref — the build reports that on its own
+
+        schemas.add(ref)
+        checked++
+        for (const finding of validateBound(schema, node.attrs?.data)) {
+          violations.push({
+            file: `${page.route || '/'} › ${type} › ${node.attrs?.language || 'yaml'}:${tag}`,
+            schema: ref,
+            item: `data.${tag}`,
+            users: [{ route: page.route, section: type, key: tag }],
+            ...finding,
+          })
+        }
+      }
+    })
+  }
+
+  return { violations, schemas, checked, deferred }
+}
+
 /** `parseContent`, or null when the parser is not installed. */
 async function loadSemanticParser() {
   try {

package/src/vite-foundation-plugin.js

@@ -45,9 +45,24 @@ let _buildingSSRBundle = false
 
 /**
  * Emit dist/runtime-pin.json declaring the @uniweb/runtime version this
- * foundation was built against. Read by the edge isolate (under the
- * Strategy S split-bundle path) to decide which runtime/{ver}/ssr.js to
- * side-load from R2.
+ * foundation was built against.
+ *
+ * ⛔ **NOTHING ENFORCES IT.** `uniweb register` reads the pin and carries it
+ * with the foundation (as `info.runtime`), so the floor reaches a party that
+ * could act on it — but no lane checks it yet. This header previously said a
+ * server-side isolate read the pin to pick which runtime to side-load, and that
+ * a "semver resolver" applied the policy. Neither existed, and for a while the
+ * pin was written and read by nothing at all. The wrong version had reached
+ * four documentation surfaces before anyone checked it against the consumers,
+ * which is the cost of describing a design as though it had shipped.
+ *
+ * The pin is a **compatibility floor**, not a selector, and it cannot be a
+ * selector: a site loads a primary foundation plus N extensions, each emitting
+ * its own pin, while a site has exactly one runtime — pins are plural, the
+ * choice is singular. The selector is `site.yml::runtime`. The pin's use is
+ * VALIDATION — is a site's runtime at or above max() of every loaded
+ * foundation's floor? — which belongs wherever all of those foundations are
+ * held, not here: this build sees one foundation.
  *
  * Reads the resolved version from the foundation's node_modules/@uniweb/
  * runtime/package.json so the pin reflects what was actually linked at
@@ -56,13 +71,13 @@ let _buildingSSRBundle = false
  *
  * Silently no-ops when @uniweb/runtime isn't resolvable (e.g., the
  * foundation depends on the runtime via a workspace alias that puts it
- * elsewhere). The edge resolver treats the absence of a pin as the
- * legacy single-bundle path, so omitting the pin is harmless during the
- * dual-mode window.
+ * elsewhere). Nothing breaks without it — but note the absence means the
+ * foundation states NO floor, and "unknown" is not "unconstrained": a floor
+ * nobody declared cannot be shown to be satisfied.
  *
- * Optional foundation-author override: a `uniweb.runtimePolicy` field
- * in the foundation's own package.json gets recorded alongside the
- * runtime version so the registry's semver resolver can apply it.
+ * Optional foundation-author override: a `uniweb.runtimePolicy` field in the
+ * foundation's own package.json is recorded alongside the runtime version,
+ * declaring the author's intent for the validation above.
  *
  * @param {string} outDir - dist/ directory to write to.
  * @param {string} projectRoot - foundation project root (where package.json lives).
@@ -555,11 +570,9 @@ export function foundationBuildPlugin(options = {}) {
       // site build's theme.css — this is harmless redundancy there.
       await emitFoundationVarsCss(outDir, schema)
 
-      // Emit runtime-pin.json so the edge isolate (under Strategy S) can
-      // side-load the matching runtime/{ver}/ssr.js. Lands silently before
-      // the dual-mode resolver ships; foundations published in the dual-mode
-      // window already have the pin and start using the split-bundle path
-      // automatically once the edge is updated.
+      // Record which @uniweb/runtime this build linked against. A compatibility
+      // floor for a validation step that does not exist yet, and read by nothing
+      // today — see emitRuntimePin's header before assuming otherwise.
       await emitRuntimePin(outDir, resolvedRoot)
 
       // Emit dist/entry-ssr.js — the single-file SSR twin of the (code-split)