@uniweb/build 0.16.18 → 0.16.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.16.18",
+  "version": "0.16.20",
   "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/content-writer": "0.3.3",
+    "@uniweb/schemas": "0.2.8",
+    "@uniweb/theming": "0.1.15",
     "@uniweb/projections": "0.2.5",
-    "@uniweb/schemas": "0.2.6",
-    "@uniweb/theming": "0.1.15"
+    "@uniweb/content-writer": "0.3.3"
   },
   "optionalDependencies": {
-    "@uniweb/content-reader": "1.2.2",
-    "@uniweb/runtime": "0.9.7",
-    "@uniweb/schemas": "0.2.6",
-    "@uniweb/semantic-parser": "1.2.1"
+    "@uniweb/runtime": "0.9.9",
+    "@uniweb/schemas": "0.2.8",
+    "@uniweb/semantic-parser": "1.2.1",
+    "@uniweb/content-reader": "1.2.2"
   },
   "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/site/emit-extensions.js

@@ -0,0 +1,129 @@
+/**
+ * Emit a workspace extension's built code into the site's own output.
+ *
+ * ── The gap this closes ──
+ *
+ * A site declares an extension by URL. The site-relative form —
+ * `extensions: ['/effects/entry.js']` — means "served from this site's own
+ * origin", and it is what the `extensions` template ships. But nothing ever put
+ * the file there.
+ *
+ * The result was a build that succeeds and a site that is wrong: prerender
+ * loads the extension from the workspace (via `resolveExtensionPath`) and
+ * renders its sections into the static HTML, then the browser fetches
+ * `/effects/entry.js`, gets a 404, `loadExtensions()` drops it, and hydration
+ * REPLACES the correct markup with `Component not found`. A visitor watches a
+ * working section break. Measured on the `extensions` template, 2026-08-05.
+ *
+ * ── Why here ──
+ *
+ * The build is the only party that knows both the declared URL and where the
+ * extension's `dist/` actually is, and the site's output is the only place the
+ * two can meet. This is the emission half of "site-hosted linked" — the shape
+ * the model doc lists as producible only by hand.
+ *
+ * ── What is emitted, and what is not ──
+ *
+ * The BROWSER delivery set. A foundation's `dist/` also carries things only
+ * other consumers want, and a static host should not serve them:
+ *
+ *   entry.js, assets/**       → emitted; the browser loads these
+ *   entry-ssr.js              → skipped; the single-file SSR twin, for an
+ *                               isolate that loads one module. Nothing on a
+ *                               static host reads it.
+ *   meta/**                   → skipped; the editor schema. Authoring-time, and
+ *                               not something to publish to visitors.
+ *   runtime-pin.json          → skipped; build provenance, read by no browser.
+ *   *.map                     → skipped; dev-only.
+ *
+ * Same browser/internal split the runtime's distribution channel draws, for the
+ * same reason: what a visitor fetches and what a renderer needs are different
+ * sets, and only one of them belongs on a public origin.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+
+/** True for the `/effects/entry.js` form — the only one this site can serve. */
+export function isSiteRelative(decl) {
+  const url = typeof decl === 'string' ? decl : decl?.url
+  return typeof url === 'string' && url.startsWith('/') && !url.startsWith('//')
+}
+
+/** Every file under `dir`, relative to it. */
+function walk(dir, base = dir) {
+  if (!existsSync(dir)) return []
+  return readdirSync(dir).flatMap((entry) => {
+    const full = join(dir, entry)
+    return statSync(full).isDirectory() ? walk(full, base) : [relative(base, full)]
+  })
+}
+
+/** Is this file part of what a browser fetches? */
+function isBrowserAsset(rel) {
+  if (rel.endsWith('.map')) return false
+  if (rel === 'runtime-pin.json') return false
+  if (rel.startsWith('meta/') || rel.startsWith(`meta\\`)) return false
+  if (/(^|[/\\])entry-ssr\.js$/.test(rel)) return false
+  return true
+}
+
+/**
+ * Locate the built `dist/` behind a site-relative extension URL.
+ *
+ * The same candidates `resolveExtensionPath` walks for prerender, kept in step
+ * deliberately: if prerender can load an extension from the workspace but the
+ * build cannot find it to emit, that is exactly the split that produced the
+ * bug — one lane resolving it and the other not.
+ *
+ * @returns {{ distDir: string, urlBase: string }|null}
+ */
+export function resolveExtensionDist(url, siteDir) {
+  const parts = url.replace(/^\//, '').split('/')
+  if (parts.length < 2) return null
+  const pkgName = parts[0]
+  const projectRoot = resolve(siteDir, '..')
+
+  for (const candidate of [
+    join(projectRoot, pkgName, 'dist'),
+    join(projectRoot, 'extensions', pkgName, 'dist')
+  ]) {
+    if (existsSync(candidate)) return { distDir: candidate, urlBase: pkgName }
+  }
+  return null
+}
+
+/**
+ * Files to emit for a site's declared extensions.
+ *
+ * Returns `{ fileName, source }` pairs for Rollup's `emitFile`, plus the
+ * declarations that could not be resolved — the caller warns about those rather
+ * than failing, because an absolute-URL extension is legitimately not ours to
+ * emit and a missing workspace build is a warning the developer can act on.
+ *
+ * @param {Array} extensions - `site.yml::extensions`, as declared.
+ * @param {string} siteDir - the site package directory.
+ */
+export function collectExtensionAssets(extensions, siteDir) {
+  const emit = []
+  const unresolved = []
+  if (!Array.isArray(extensions)) return { emit, unresolved }
+
+  for (const decl of extensions) {
+    if (!isSiteRelative(decl)) continue // absolute URL or a ref — someone else serves it
+    const url = typeof decl === 'string' ? decl : decl.url
+    const found = resolveExtensionDist(url, siteDir)
+    if (!found) {
+      unresolved.push(url)
+      continue
+    }
+    for (const rel of walk(found.distDir)) {
+      if (!isBrowserAsset(rel)) continue
+      emit.push({
+        fileName: `${found.urlBase}/${rel.split('\\').join('/')}`,
+        source: readFileSync(join(found.distDir, rel))
+      })
+    }
+  }
+  return { emit, unresolved }
+}

package/src/site/plugin.js

@@ -52,6 +52,7 @@ import { processCollections, writeCollectionFiles } from './collection-processor
 import { executeFetch, mergeDataIntoContent } from './data-fetcher.js'
 import { shouldSplitContent } from './split-content.js'
 import { FONT_LINKS_MARKER } from './head-markers.js'
+import { collectExtensionAssets } from './emit-extensions.js'
 
 // BCP 47 locale code pattern: en, zh-CN, zh-Hant, pt-BR, fr-CA, sr-Latn, etc.
 const LOCALE_RE = '[a-z]{2,3}(?:-[A-Za-z]{2,4})?'
@@ -1464,6 +1465,25 @@ export function siteContentPlugin(options = {}) {
       // markdown (retrieval). Free and on by default; a site opts out under
       // `agents:` in site.yml.
       emitProjections.call(this, finalContent)
+
+      // A site-relative extension (`/effects/entry.js`) is served from the
+      // site's OWN origin, so the site's build is what has to put it there.
+      // Without this the build succeeds, prerender renders the extension's
+      // sections from the workspace, and the browser then 404s and replaces
+      // them with `Component not found` on hydration.
+      const { emit, unresolved } = collectExtensionAssets(
+        finalContent.config?.extensions,
+        resolve(sitePath)
+      )
+      for (const asset of emit) {
+        this.emitFile({ type: 'asset', fileName: asset.fileName, source: asset.source })
+      }
+      for (const url of unresolved) {
+        this.warn(
+          `Extension '${url}' is site-relative but no built extension was found for it. ` +
+            `The site will 404 on it at runtime — build the extension, or reference it by URL.`
+        )
+      }
     },
 
     closeBundle() {

package/src/uwx/data-schema.js

@@ -150,6 +150,20 @@ function lowerSection(def, resolve, optResolve, path = '') {
   const out = {}
   if ((def.kind || 'single') === 'multi') out.multiple = true
   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).
+  // 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
   if (def.append_only) out.append_only = true
 
@@ -243,6 +257,7 @@ function lowerField(rawField, resolve, optResolve, path = '') {
         ...lowerSection(
           {
             kind: 'multi',
+            ...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
@@ -251,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,
@@ -261,7 +282,7 @@ function lowerField(rawField, resolve, optResolve, path = '') {
     }
     return {
       type: 'section',
-      ...lowerSection({ kind: 'single', fields: field.fields }, resolve, optResolve, path)
+      ...lowerSection({ kind: 'single', ...sectionAttrsFromField(field), fields: field.fields }, resolve, optResolve, path)
     }
   }
   if (type === 'array') {
@@ -269,7 +290,7 @@ function lowerField(rawField, resolve, optResolve, path = '') {
     if (items && items.type === 'object') {
       return {
         type: 'section',
-        ...lowerSection({ kind: 'multi', 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
@@ -279,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 }
@@ -368,6 +402,35 @@ function asField(def) {
   return typeof def === 'string' ? { type: def } : (def && typeof def === 'object' ? def : {})
 }
 
+// A nested section is authored as a FIELD (`{ type: object, description: … }`),
+// 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
+}
+
 function shortName(name) {
   return String(name).split('/').pop()
 }

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)