@uniweb/build 0.64.0 → 0.64.2

package/src/uwx/backfill.js

@@ -32,7 +32,7 @@ import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { proseMirrorToMarkdown } from '@uniweb/content-writer'
 import { parseFrontmatter } from './entity-source.js'
-import { isProseMirrorField } from './data-schema.js'
+import { isProseMirrorField, isOpenMapSection, openMapFromRows } from './data-schema.js'
 import { recordFileLayout, contentBodyTarget } from './record-layout.js'
 import { unwrapLocalizedContent } from './locale-sync.js'
 import { parseBibtex, exportBibtex } from '@citestyle/bibtex'
@@ -307,7 +307,7 @@ function decodeRecord(fields, value, dec, sectionName) {
     const raw = value[key]
     if (raw === undefined) continue
     if (field?.type === 'section') {
-      out[key] = field.multiple === true ? decodeList(field, raw, dec) : decodeRecord(field.fields, raw, dec, null)
+      out[key] = field.multiple === true ? decodeSectionList(field, raw, dec) : decodeRecord(field.fields, raw, dec, null)
       continue
     }
     const isBody = Boolean(dec.bodyAt) && sectionName === dec.bodyAt.section && key === dec.bodyAt.key
@@ -318,6 +318,14 @@ function decodeRecord(fields, value, dec, sectionName) {
   return out
 }
 
+// A `many` field's records — an OPEN MAP's written back as the author's map, keyed by each row's
+// `name` (`isOpenMapSection`), which is what the push reads a map from. Rows that cannot be a map
+// stay a list, which the push reads too.
+function decodeSectionList(def, value, dec) {
+  const list = decodeList(def, value, dec)
+  return (isOpenMapSection(def) && openMapFromRows(list)) || list
+}
+
 // The records of a `many` section; a self-nesting one's `$children` nest back under
 // `children:`, the reserved key the push reads them from.
 function decodeList(def, value, dec) {
@@ -332,8 +340,11 @@ function decodeList(def, value, dec) {
 }
 
 // A leaf's authored value. A localized SCALAR's target locales are captured into the
-// collector (the content body's are captured by `unwrapLocalizedContent`, with its
-// free-form path); a list of localized values is unwrapped element by element.
+// collector — a markdown body's too, keyed by its whole text as the records extractor keys it
+// (a ProseMirror body's are captured by `unwrapLocalizedContent`, with its free-form path); a
+// list of localized values is unwrapped element by element. ⛔ Until 2026-09-26 a body was
+// taken to be ProseMirror, so a markdown one's translations were captured nowhere and a
+// clone rendered it in the source language.
 function decodeLeaf(raw, field, dec, isBody) {
   if (field?.type === 'entity_ref') return decodeReference(raw, field, dec)
   if (isProseMirrorField(field)) {
@@ -344,10 +355,10 @@ function decodeLeaf(raw, field, dec, isBody) {
   }
   if (!field?.localized) return raw
   if (Array.isArray(raw)) {
-    if (!isBody) for (const item of raw) dec.collector?.add(item, dec.context)
+    for (const item of raw) dec.collector?.add(item, dec.context)
     return unwrapLocalizedList(raw, dec.sourceLocale)
   }
-  if (!isBody) dec.collector?.add(raw, dec.context)
+  dec.collector?.add(raw, dec.context)
   return unwrapLocalized(raw, dec.sourceLocale)
 }
 

package/src/uwx/data-schema.js

@@ -37,6 +37,40 @@ const CONTENT_TEXT_FORMATS = new Set(['markdown', 'html'])
 // declares its own `name` is an error instead, which names the problem precisely.
 const OPEN_MAP_KEY = 'name'
 
+/**
+ * ⭐ AN OPEN MAP'S LOWERED SECTION. `values:` lowers to rows (`lowerField`): a `multiple` section
+ * whose required string `name` — the map's key — is made each row's identity by a `unique_field`
+ * rule. A record FILE holds it as the author wrote it, a map from key to value; the WIRE holds the
+ * rows. This is the one test, read off the declaration alone, because a pull into a clone has
+ * nothing else: the push turns a file's map into rows by it, and the pull the rows back into a map.
+ */
+export function isOpenMapSection(def) {
+  if (def?.multiple !== true || def.self_nesting === true) return false
+  const key = def.fields?.[OPEN_MAP_KEY]
+  if (key?.type !== 'string' || key.required !== true || key.localized === true) return false
+  return (def.constraints || []).some((c) => c?.kind === 'unique_field' && c.field === OPEN_MAP_KEY && c.scope === 'section')
+}
+
+/** A file's open map as the rows it lowers to, in the map's key order: each key is its row's `name`. */
+export function openMapEntries(map) {
+  return Object.entries(map).map(([key, value]) => ({ key, value, row: { ...value, [OPEN_MAP_KEY]: key } }))
+}
+
+/**
+ * Rows back as the map a file holds, or null when they cannot be one — a row with no key, or a key
+ * two rows share — so a caller keeps them a list, which a push reads too, and nothing is lost.
+ */
+export function openMapFromRows(rows) {
+  const map = {}
+  for (const row of rows || []) {
+    const key = row?.[OPEN_MAP_KEY]
+    if (typeof key !== 'string' || key === '' || Object.hasOwn(map, key)) return null
+    const { [OPEN_MAP_KEY]: _key, ...value } = row
+    map[key] = value
+  }
+  return map
+}
+
 /**
  * A `text` field marked as rich content (`format: markdown` or `html`): the
  * file-based body target. Round-trips as the raw source string — what the retired

package/src/uwx/emit-surface.json

@@ -74,6 +74,12 @@
         "layout": [
           "site.yml::layout"
         ],
+        "og_description": [
+          "site.yml::seo"
+        ],
+        "og_title": [
+          "site.yml::seo"
+        ],
         "paths": [
           "site.yml::paths"
         ],

package/src/uwx/index.js

@@ -179,3 +179,12 @@ export {
 // is the foundation-less variant (only data-schema entities) for a schemas-only package.
 export { buildRegistryPackage, buildSchemaOnlyPackage } from './registry-package.js'
 export { toDataSchemaDeclaration } from './data-schema.js'
+
+// A registered foundation a project names by catalog ref — a clone's — kept under `.uniweb/` as the
+// backend answered for it, so the build, the push and the pull can read its section types.
+export {
+  registeredFoundationPath,
+  readRegisteredFoundation,
+  writeRegisteredFoundation,
+} from '../site/registered-foundation.js'
+export { parseCatalogRef } from '../site/foundation-ref.js'

package/src/uwx/open-graph.js

@@ -0,0 +1,69 @@
+// ⭐ A PAGE'S OR A SITE'S OPEN GRAPH TITLE AND DESCRIPTION, PER LANGUAGE — `og_title` and
+// `og_description` on the wire, `seo.ogTitle` / `seo.ogDescription` in a file.
+//
+// A file keeps them inside `seo`, whose other keys are crawler and sitemap directives a deployment
+// stores as one object. Where the deployment's page — or `settings` — Section declares the two keys
+// (`GET /dev/config` → `siteContent.pageFields` / `settingsFields`), a push sends them per language
+// through those keys and the rest of `seo` as it is; elsewhere they ride inside `seo` as authored,
+// in the source language only. A pull puts them back inside `seo`.
+import { localizeScalar } from './locale-sync.js'
+import { unwrapLocalized } from './backfill.js'
+
+// wire key → the key inside a file's `seo`
+const OPEN_GRAPH_KEYS = [
+  ['og_title', 'ogTitle'],
+  ['og_description', 'ogDescription'],
+]
+
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+
+/** Whether a Section's declared keys take the two. */
+export function takesOpenGraph(fields) {
+  return Array.isArray(fields) && OPEN_GRAPH_KEYS.every(([wire]) => fields.includes(wire))
+}
+
+/**
+ * A file's `seo` as a push sends it: `{ og_title?, og_description?, seo? }`. The two are taken out
+ * of `seo` and localized only where the Section takes them; `seo` is left out when nothing else is
+ * in it. A value that is not a string stays where it is.
+ */
+export function splitOpenGraph(seo, fields, sourceLocale, translations, context = null) {
+  if (!takesOpenGraph(fields) || !isRecord(seo)) return { seo }
+  const rest = { ...seo }
+  const out = {}
+  for (const [wire, key] of OPEN_GRAPH_KEYS) {
+    if (typeof seo[key] !== 'string') continue
+    out[wire] = localizeScalar(seo[key], sourceLocale, translations, context)
+    delete rest[key]
+  }
+  out.seo = Object.keys(rest).length ? rest : undefined
+  return out
+}
+
+/** One of the two, as a push sends it — or undefined where the Section does not take them. */
+export function openGraphValue(seo, wire, fields, sourceLocale, translations, context = null) {
+  return splitOpenGraph(seo, fields, sourceLocale, translations, context)[wire]
+}
+
+/** `seo` as a push sends it beside the two — without them where the Section takes them. */
+export function seoBesideOpenGraph(seo, fields) {
+  return splitOpenGraph(seo, fields, null, null).seo
+}
+
+/**
+ * A document's `og_title` / `og_description` folded back into a file's `seo` — the source
+ * language's value — with the other languages handed to `collector` in `context`. Returns `seo`
+ * unchanged when the holder carries neither, and undefined for an empty result.
+ */
+export function foldOpenGraph(holder, seo, sourceLocale, collector = null, context = null) {
+  if (!OPEN_GRAPH_KEYS.some(([wire]) => holder?.[wire] !== undefined)) return seo
+  const out = isRecord(seo) ? { ...seo } : {}
+  for (const [wire, key] of OPEN_GRAPH_KEYS) {
+    const value = holder?.[wire]
+    if (value === undefined) continue
+    collector?.add(value, context)
+    const source = unwrapLocalized(value, sourceLocale)
+    if (typeof source === 'string' && source !== '') out[key] = source
+  }
+  return Object.keys(out).length ? out : undefined
+}

package/src/uwx/project-writer.js

@@ -201,10 +201,13 @@ export function writeSectionFile({ filePath, content, params, reserved = DEFAULT
   // is not re-serialized: the writer's markdown differs from an author's in blank lines and line breaks,
   // and a pull that changed nothing reformatted every section it touched (measured 2026-09-26 on the
   // `marketing` template). A file with nothing to change is not written at all.
+  // ⛔ An EMPTY body is one too: until 2026-09-26 it never compared as unchanged, so a section holding
+  // only frontmatter — a parametric page's `type:` and `fetch:` — was re-serialized, and lost its
+  // comments, on a pull that changed nothing. So is no document at all (a params-only update).
   const authoredBody = (existingBody || '').replace(/^\n+/, '').replace(/\s+$/, '')
-  const keepsBody = Boolean(content && authoredBody) && sameMarkdownDocument(authoredBody, content)
-  if (keepsBody && canonicalJson(nextFrontmatter) === canonicalJson(frontmatter)) return 'unchanged'
-  const body = content && !keepsBody ? proseMirrorToMarkdown(content) : authoredBody
+  const keepsBody = !content || sameMarkdownDocument(authoredBody, content)
+  if (existing && keepsBody && canonicalJson(nextFrontmatter) === canonicalJson(frontmatter)) return 'unchanged'
+  const body = keepsBody ? authoredBody : proseMirrorToMarkdown(content)
   return writeIfChanged(filePath, assembleSection(nextFrontmatter, body))
 }
 

package/src/uwx/records-project.js

@@ -255,8 +255,12 @@ function siteFoundationDeclarations(siteRoot) {
     return { own: null, keyTypes: null }
   }
   const schema = siteYml ? foundationSchemaJson(siteRoot, siteYml) : null
+  // ⛔ Own names only from a schema that carries its data schemas. The registered version a clone
+  // keeps carries none (they travel as Models), and read as an empty set it said "owns nothing", so a
+  // clone placed a foundation's own `@std/exhibit` in `records/std/exhibit/`; unknown (null), the
+  // standard-schema rule decides (`unresolveSelfScope`), as it did before the kept version existed.
   return schema
-    ? { own: ownSchemaNames(schema.dataSchemas || {}), keyTypes: dataKeyTypes(schema) }
+    ? { own: ownSchemaNames(schema.dataSchemas), keyTypes: dataKeyTypes(schema) }
     : { own: null, keyTypes: null }
 }
 
@@ -318,7 +322,9 @@ const DECL_WIRE_CONSUMED = new Set([
   'deferred',
   'detail_url',
   'detail',
-  'queryable'
+  'queryable',
+  // Says the query names no schema of its own — how the file is written, never a key in it.
+  'typed_by_data_key',
 ])
 
 // A standard schema (`@std/<name>`), normalized as the build resolves one — known with no foundation
@@ -348,7 +354,7 @@ function isDerivedDeferred(d, dataSchemas, pulledModel = null) {
   return d.deferred.every((f) => a.has(f))
 }
 
-function declToFileShape(wire, dataSchemas = null, scope = null, own = null, keyTypes = null, authored = null, models = null) {
+function declToFileShape(wire, dataSchemas = null, scope = null, own = null, keyTypes = null, authored = null, models = null, markedOnly = false) {
   // ⛔ UNDO THE PRODUCER'S QUALIFICATION FIRST, before anything compares against
   // `schema`. The push qualifies a foundation-relative `@/x` to `@scope/x`
   // (`site.js::queriesNested`), and both checks below are keyed by the author's
@@ -385,8 +391,15 @@ function declToFileShape(wire, dataSchemas = null, scope = null, own = null, key
   // ⛔ UNLESS THE AUTHOR WROTE IT: a `schema:` the local file already states for this query is
   // written back as it is. Until 2026-09-25 a pull into a working copy dropped international's
   // `articles: { schema: '@std/article' }`, because a section types `articles` as `@std/article`.
-  const keyDefault = name && !own?.has(name) ? keyTypes?.get(name) : null
+  // ⭐ A CLONE GOES BY THE MARK. Where the key's type comes only from the registered foundation a
+  // project keeps (`markedOnly`: its foundation is a catalog ref), a query is written terse only when
+  // the push marked it `typed_by_data_key` — the author wrote no schema — or when the author's own
+  // file declares it with none. Unmarked, the schema was the author's, and it is written.
   const written = name ? authored?.get(name) : undefined
+  const typedHere = !markedOnly || wire.typed_by_data_key === true || written === null
+  const keyType = name && !own?.has(name) && typedHere ? keyTypes?.get(name) : null
+  // In the author's form: the registered version names the type qualified (`@acme/member`).
+  const keyDefault = keyType ? unresolveSelfScope(keyType, scope, own) : null
   if (d.schema && (d.schema === written || (d.schema !== defaultSchema(name) && d.schema !== keyDefault))) {
     decl.schema = d.schema
   }
@@ -463,17 +476,41 @@ function authoredQuerySchemas(siteRoot, siteYml) {
   } catch {
     file = null
   }
+  // name → the schema the author's file states for it, or null for a query it declares with none.
+  // ⛔ The string shorthand (`team: '@/member'`) is a schema too: until 2026-09-26 it read as none,
+  // so a pull could write the author's `team: '@/member'` back as `team: {}`.
   const out = new Map()
   for (const decls of [siteYml?.queries, file]) {
     if (!decls || typeof decls !== 'object') continue
     for (const [name, decl] of Object.entries(decls)) {
-      if (typeof decl?.schema === 'string') out.set(name, decl.schema)
-      else if (out.has(name)) out.delete(name)
+      const schema = typeof decl === 'string' ? decl : typeof decl?.schema === 'string' ? decl.schema : null
+      out.set(name, schema)
     }
   }
   return out
 }
 
+// ⭐ WHERE A NEW RECORD OF A KEY'S TYPE GOES: the folder of a query the site declares with no schema
+// of its own, whose name is a data key typed as that Model — `records/team/` for `team:` typed
+// `@acme/member` — which is where a push reads it from (`uwx/data-key-types.js`). model → folder.
+function typedQueryFolders(siteRoot, recordsRoot, scope, own, keyTypes) {
+  const out = new Map()
+  if (!keyTypes?.size) return out
+  let siteYml = null
+  try {
+    siteYml = yaml.load(readFileSync(join(siteRoot, 'site.yml'), 'utf8'), YAML_OPTIONS) || null
+  } catch {
+    siteYml = null
+  }
+  for (const [name, schema] of authoredQuerySchemas(siteRoot, siteYml)) {
+    if (schema !== null || own?.has(name)) continue
+    const type = keyTypes.get(name)
+    const model = type ? resolveSelfScope(type, scope) : null
+    if (model && !out.has(model)) out.set(model, join(recordsRoot, name))
+  }
+  return out
+}
+
 export function declarationsToQueriesYml({ document, siteRoot, scope, models = null, ...rest }) {
   refuseOrgOption(rest, 'declarationsToQueriesYml')
   const decls = Array.isArray(document?.queries) ? document.queries : []
@@ -500,10 +537,12 @@ export function declarationsToQueriesYml({ document, siteRoot, scope, models = n
   const own = ownSchemaNames(dataSchemas)
   const keyTypes = siteYml ? dataKeyTypes(foundationSchemaJson(siteRoot, siteYml)) : null
   const authored = authoredQuerySchemas(siteRoot, siteYml)
+  // The key types a catalog-ref foundation has come from the registered version the project keeps.
+  const markedOnly = Boolean(parseCatalogRef(siteYml?.foundation))
 
   const queries = {}
   for (const d of decls) {
-    const { name, decl } = declToFileShape(d, dataSchemas, selfScope, own, keyTypes, authored, models)
+    const { name, decl } = declToFileShape(d, dataSchemas, selfScope, own, keyTypes, authored, models, markedOnly)
     if (!name) continue
     queries[name] = decl
   }
@@ -682,6 +721,7 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
   // The file holding a record already, by its own id: the derived folder first, then any
   // other that reads as the same Model (`recordDirsReadingAs`).
   const readingAs = (model) => recordDirsReadingAs(recordsRoot, model, selfScope, { own, keyTypes })
+  const keyFolders = typedQueryFolders(siteRoot, recordsRoot, selfScope, own, keyTypes)
   const findRecordFile = (poolDir, model, ownId) => {
     const dirs = [poolDir, ...readingAs(model).filter((dir) => dir !== poolDir)]
     // Single-record files first, as before; then an entry of a list file.
@@ -735,8 +775,9 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
       isNew = false
     } else {
       // A new record goes where the project already keeps records of its Model — its derived
-      // folder, else another that reads as the Model (`records/team/` for `@std/member`).
-      const home = existsSync(poolDir) ? poolDir : readingAs(schema)[0] || poolDir
+      // folder, else another that reads as the Model (`records/team/` for `@std/member`), else the
+      // folder of a query typed by its data key as the Model (`typedQueryFolders`) — a clone's.
+      const home = existsSync(poolDir) ? poolDir : readingAs(schema)[0] || keyFolders.get(schema) || poolDir
       format = defaultFormat(home, declaration)
       filePath = join(home, where.slug + EXT_FOR_FORMAT[format])
       isNew = true

package/src/uwx/records.js

@@ -44,6 +44,7 @@ import { readFileSync, existsSync } from 'node:fs'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { detectFoundationType } from '../site/foundation-ref.js'
+import { foundationSchemaJson } from '../site/queries-config.js'
 import { join, resolve } from 'node:path'
 
 import { resolveQueriesConfig } from './queries-config.js'
@@ -55,7 +56,7 @@ import {
   poolPathReadings,
   poolDirsForSchema,
 } from '../site/entity-pool.js'
-import { toDataSchemaDeclaration, isProseMirrorField, isMarkupTextField } from './data-schema.js'
+import { toDataSchemaDeclaration, isProseMirrorField, isMarkupTextField, isOpenMapSection, openMapEntries } from './data-schema.js'
 import { recordFileLayout, contentBodyTarget } from './record-layout.js'
 import { emitEntitySyncPackage } from './entity-document.js'
 import { resolveSelfScope, siteSelfScope, refuseOrgOption } from './self-scope.js'
@@ -268,6 +269,25 @@ export function recordsToEntities({
         `"${bodyTarget.section}.${bodyTarget.key}"`
     )
   }
+  // ⛔ A SITE'S FOLDER PLACES ONLY A RECORD SOMETHING CAN REFERENCE. A folder entry is a
+  // reference, and a Model with no brief is not linkable (`toDataSchemaDeclaration`), so a
+  // backend refuses to place its records — measured 2026-09-25 as a `409 … linkable: false`,
+  // and by design (backend, 2026-09-26). Refused here, once for the schema, before anything
+  // is sent — and saying why, which the backend's refusal names only by its design doc.
+  if (declaration.linkable === false) {
+    const slugs = (records || []).map((r) => r?.slug).filter(Boolean)
+    if (slugs.length) {
+      const named = slugs.slice(0, 3).join(', ') + (slugs.length > 3 ? ` and ${slugs.length - 3} more` : '')
+      refusals.push(
+        `${label}: ${declaration.name} has no brief, so a site's folder cannot place its records ` +
+          `(${named}) — a folder entry is a reference, and only a record of a schema with a brief ` +
+          'can be one. Give the schema a brief (`brief: true` on one of its sections), or keep this ' +
+          'data out of records/.'
+      )
+    }
+    return { entities, warnings, refusals }
+  }
+
   for (const record of records || []) {
     const slug = record.slug
     if (!slug) {
@@ -429,6 +449,20 @@ function readBySection(layout, record, enc) {
 // are its child sections), a list of records for a `many` one.
 function encodeSection(def, value, enc, path) {
   if (def.multiple === true) {
+    // ⭐ AN OPEN MAP is the author's map in a file and rows on the wire (`isOpenMapSection`): each
+    // key becomes its row's `name`. ⛔ Until 2026-09-26 the map was refused as "a list of records",
+    // so no record holding one could be pushed. Rows written as a list are read as they are.
+    if (isOpenMapSection(def) && isPlainObject(value)) {
+      const rows = []
+      for (const { key, value: entry, row } of openMapEntries(value)) {
+        if (!isPlainObject(entry)) {
+          enc.shape.push(`"${path}.${key}" is one entry of a map — write it as a map of its fields.`)
+          continue
+        }
+        rows.push(encodeItem(def, row, enc, `${path}.${key}`))
+      }
+      return rows
+    }
     if (!Array.isArray(value)) {
       enc.shape.push(`"${path}" holds a list of records — write it as a list ("- …" under "${path}:").`)
       return undefined
@@ -757,6 +791,17 @@ function resolveFoundationDir(siteRoot, opts) {
   }
 }
 
+// The site's foundation's schema as a project keeps it for a catalog ref (`foundationSchemaJson`,
+// `site/registered-foundation.js`) — its section types, which is all this is read for.
+function registeredFoundationSchema(siteRoot) {
+  try {
+    const siteYml = yaml.load(readFileSync(join(siteRoot, 'site.yml'), 'utf8'), YAML_OPTIONS) || {}
+    return foundationSchemaJson(siteRoot, siteYml)
+  } catch {
+    return null
+  }
+}
+
 // Load the local foundation's built schema.json (the source of locally-defined
 // Model declarations), or null when there's no local foundation. `required` (set
 // when no remote resolver is available) turns "missing" into a helpful error
@@ -988,7 +1033,8 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
   // holds records of that type. `keyTyped` records each such name for the `queries` Section,
   // which must name the same data schema (`sync-package.js` hands it on). ⛔ Never for a schema
   // a query asked for explicitly: that one is the author's, and fails loudly.
-  const keyTypes = dataKeyTypes(localSchema)
+  // A clone has no local foundation: its section types come from the registered version it keeps.
+  const keyTypes = dataKeyTypes(localSchema || registeredFoundationSchema(siteRoot))
   const keyTyped = new Map()
   const typedFor = async (schema) => {
     const key = keyOfDefaultRef(schema)

package/src/uwx/site-project.js

@@ -32,6 +32,7 @@
 // we unwrap to the source locale for the file surface (other locales stay in
 // the i18n pipeline). Absent `info` keys are left untouched on disk.
 
+import { foldOpenGraph } from './open-graph.js'
 import { join, relative, extname, basename, dirname } from 'node:path'
 import { restoreAssetRefs } from './asset-map.js'
 import { readBackendState, updateBackendState } from './sync-store.js'
@@ -43,7 +44,7 @@ import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { writeSiteConfig, writeThemeFile, writeIfChanged, writeSectionFile, writeMergedYaml } from './project-writer.js'
 import { declarationsToQueriesYml } from './records-project.js'
 import { FILLED_SECTION_TYPE, buildRouteOf } from './site.js'
-import { translationContext } from '../i18n/extract.js'
+import { translationContext, SITE_META_CONTEXT } from '../i18n/extract.js'
 import { authorableDeclaration, DECLARATION_KEYS } from '../site/fetch-shapes.js'
 import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations, unwrapLocalizedContent, localesDir } from './locale-sync.js'
 import { resolveLocaleList } from '../i18n/locales.js'
@@ -282,6 +283,11 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
   for (const [settingsKey, ymlKey] of Object.entries(SETTINGS_TO_SITE_YML)) {
     if (settingsSection[settingsKey] !== undefined) siteChanges[ymlKey] = settingsSection[settingsKey]
   }
+  // ⭐ The site's Open Graph title and description, sent per language as `og_title` /
+  // `og_description` where the deployment takes them: back inside `seo`, the source language's,
+  // the others to the collector in the site's context (`uwx/open-graph.js`).
+  const siteSeo = foldOpenGraph(settingsSection, siteChanges.seo, sourceLocale, collector, SITE_META_CONTEXT)
+  if (siteSeo !== undefined) siteChanges.seo = siteSeo
 
   // `settings.keywords` is a LOCALIZED list (it renders into `<meta name="keywords">`)
   // → unwrap to the source locale; the target locales go to the collector.
@@ -696,7 +702,10 @@ function pageRecordToYml(record, sectionsArray, sourceLocale, existing = null, {
   if (record.redirect !== undefined) y.redirect = record.redirect
   if (record.rewrite !== undefined) y.rewrite = record.rewrite
   if (record.layout !== undefined) y.layout = record.layout
-  if (record.seo !== undefined) y.seo = record.seo
+  // Its Open Graph title and description, per language on the wire, back inside `seo`
+  // (`uwx/open-graph.js`); their other languages are collected with the page's metadata.
+  const seo = foldOpenGraph(record, record.seo, sourceLocale)
+  if (seo !== undefined) y.seo = seo
   // Invert the build's resolution rather than copy it — see fetch-shapes.js. Under
   // the key the file already uses (`existing`), else `query:` for names alone.
   if (record.fetch !== undefined) {
@@ -816,6 +825,8 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
     ctx.collector?.add(record.title, meta)
     ctx.collector?.add(record.label, meta)
     ctx.collector?.add(record.description, meta)
+    ctx.collector?.add(record.og_title, meta)
+    ctx.collector?.add(record.og_description, meta)
     // keywords is a localized ARRAY — capture each element's target locales.
     if (Array.isArray(record.keywords)) record.keywords.forEach((kw) => ctx.collector?.add(kw, meta))
     else ctx.collector?.add(record.keywords, meta)

package/src/uwx/site.js

@@ -76,7 +76,8 @@ import { loadLocaleTranslations, localizeScalar, localizeScalarList, localizeCon
 import { unwrapLocalized } from './backfill.js'
 import { loadFreeformTranslation } from '../i18n/freeform.js'
 import { resolveLocaleList } from '../i18n/locales.js'
-import { translationContext } from '../i18n/extract.js'
+import { translationContext, SITE_META_CONTEXT } from '../i18n/extract.js'
+import { splitOpenGraph, openGraphValue, seoBesideOpenGraph } from './open-graph.js'
 import { updateBackendState, readBackendState } from './sync-store.js'
 import { upsertYamlScalar } from './yaml-upsert.js'
 import { resolveQueriesConfig } from './queries-config.js'
@@ -293,7 +294,9 @@ function localizePageMeta(page, route, sourceLocale, translations) {
     value && typeof value === 'object' && typeof value[sourceLocale] === 'string'
       ? localizeScalar(value[sourceLocale], sourceLocale, translations, context)
       : value
-  for (const key of ['title', 'label', 'description']) if (page[key] !== undefined) page[key] = again(page[key])
+  for (const key of ['title', 'label', 'description', 'og_title', 'og_description']) {
+    if (page[key] !== undefined) page[key] = again(page[key])
+  }
   if (Array.isArray(page.keywords)) page.keywords = page.keywords.map(again)
 }
 
@@ -318,7 +321,7 @@ function mapSectionData(section) {
 }
 
 function buildPageData(config, ctx) {
-  const { slug, mode, isDynamic, paramName, isRoot, siteIndex, sourceLocale, translations, where } =
+  const { slug, mode, isDynamic, paramName, isRoot, siteIndex, sourceLocale, translations, where, pageFields } =
     ctx
   // The page `slug` is the localized route source — a `{lang: slug}` map (the
   // site-content Model declares it localized; greenlit 2026-06-13). The source
@@ -355,7 +358,13 @@ function buildPageData(config, ctx) {
   setIf(data, 'redirect', config.redirect)
   setIf(data, 'rewrite', config.rewrite)
   setIf(data, 'layout', config.layout)
-  setIf(data, 'seo', config.seo)
+  // ⭐ Its Open Graph title and description per language, where the deployment's page takes them
+  // (`uwx/open-graph.js`) — out of `seo`, which travels as one object. ⛔ Until 2026-09-26 they rode
+  // inside `seo` only, in the source language, though the build translates them.
+  const og = splitOpenGraph(config.seo, pageFields, sourceLocale, translations)
+  setIf(data, 'og_title', og.og_title)
+  setIf(data, 'og_description', og.og_description)
+  setIf(data, 'seo', og.seo)
   // ⭐ A `query:` or `fetch:` LIST means "fetch each" — one declaration per entry. Before
   // 2026-09-02 this kept `[0]` and dropped the rest silently, so the wire
   // carried one dataset for a page that asked for several.
@@ -729,7 +738,7 @@ const REPUBLISH_CLAUSE =
 // Recursively build the `pages` tree: each record carries its fields, its inline
 // `page_sections` (page mode only), and its child pages under `$children`.
 async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, parentConfig, isRoot) {
-  const { siteRoot, siteIndex, sourceLocale, translations } = ctx
+  const { siteRoot, siteIndex, sourceLocale, translations, pageFields } = ctx
   const folders = await orderedSubfolders(dirPath, inheritedMode, parentConfig)
   const out = []
   // A folder inside a `[...path]` folder can never be reached, and `[dir]` /
@@ -763,6 +772,7 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
       siteIndex,
       sourceLocale,
       translations,
+      pageFields,
     })
     // `$id` is the stableId when authored (rename-stable), else the slug (the
     // natural handle — spec default). The path is NEVER the identity.
@@ -980,7 +990,9 @@ const DECL_EMITTED_ABOVE = new Set([
   'limit',
   'excerpt',
   'deferred',
-  'queryable'
+  'queryable',
+  // Derived by the rule above, never taken from a file.
+  'typed_by_data_key',
 ])
 
 const DECL_NOT_ON_WIRE = new Set([
@@ -1022,7 +1034,7 @@ function externalSource(d) {
   return source
 }
 
-function queriesNested(declarations, uuids = null, scope = null, keyTyped = null) {
+function queriesNested(declarations, uuids = null, scope = null, keyTyped = null, queryFields = null) {
   const out = []
   for (const [name, d] of Object.entries(declarations)) {
     refuseUnder(d.where, `queries.${name}`)
@@ -1041,8 +1053,13 @@ function queriesNested(declarations, uuids = null, scope = null, keyTyped = null
     // empty. The pull puts the author's `@/` back (`records-project.js::declarationsToQueriesYml`).
     // A query whose name-defaulted schema stands for the type of the data key of its name
     // names that type — the data schema its records are sent as (`data-key-types.js`).
-    const schema = (!d.schemaExplicit && keyTyped?.get(d.schema)) || d.schema
+    const typed = (!d.schemaExplicit && keyTyped?.get(d.schema)) || null
+    const schema = typed || d.schema
     setIf(data, 'schema', resolveSelfScope(schema, scope))
+    // ⭐ …AND SAYS SO, so a pull can tell the author's form (`team:`, no schema) from an explicit
+    // one — sent only where the deployment's `queries` Section declares the key (`GET /dev/config`
+    // → `siteContent.queryFields`), since one that does not refuses a push carrying it.
+    if (typed && Array.isArray(queryFields) && queryFields.includes('typed_by_data_key')) data.typed_by_data_key = true
     setIf(data, 'sort', d.sort)
     // Legacy `filter:` is not synced — it is translated to `where` upstream
     // (the canonical predicate). No legacy fields on the wire.
@@ -1238,7 +1255,7 @@ function secretsNested(provisioned) {
 // ROUND-TRIP LAW). `site-project.js::SETTINGS_TO_SITE_YML` plus its explicit
 // branches is the other half, and `producer-list-drift.test.js` fails if a key
 // emitted here has neither.
-function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translations, languages = null } = {}) {
+function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translations, languages = null, settingsFields = null } = {}) {
   const settings = {}
 
   // Site-wide values an author declares once and references from page content as
@@ -1287,7 +1304,12 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
   // (`core/src/seo.js`). Two of those are literally sitemap.xml columns. It only
   // ever passed the card test because `image` was inside it; the card's picture is
   // `info.preview` now.
-  setIf(settings, 'seo', siteYml.seo)
+  // The site's Open Graph title and description per language, where the deployment's `settings`
+  // takes them (`uwx/open-graph.js`), in the site's context (`SITE_META_CONTEXT`).
+  // (Each read inline from `siteYml.seo`, so the emit surface names its source.)
+  setIf(settings, 'og_title', openGraphValue(siteYml.seo, 'og_title', settingsFields, sourceLocale, translations, SITE_META_CONTEXT))
+  setIf(settings, 'og_description', openGraphValue(siteYml.seo, 'og_description', settingsFields, sourceLocale, translations, SITE_META_CONTEXT))
+  setIf(settings, 'seo', seoBesideOpenGraph(siteYml.seo, settingsFields))
   // ⭐ `keywords` IS seo by function — it renders into `<meta name="keywords">`
   // (`runtime/src/ssr-renderer.js`). It is top-level in site.yml for authoring
   // convenience, not because it is a different kind of thing. Localized, so it
@@ -1569,7 +1591,8 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // (uwx-format.md → info.url.)
 
   // `siteIndex` — the homepage — joins below, once the pages directory's own config is read.
-  const ctx = { siteRoot, sourceLocale, translations }
+  // …and the keys this deployment's page takes (`siteContent.pageFields`), for its Open Graph texts.
+  const ctx = { siteRoot, sourceLocale, translations, pageFields: opts.pageFields }
   // ⛔ ONE `paths:` CONVENTION, TWO READERS, AND THIS ONE IS A STRICT SUBSET.
   // The build honours sub-mounts — `paths: { pages/<segment>: <dir> }`, through
   // `resolveMounts`/`mountEntriesOf` in `site/content-collector.js` — and this
@@ -1650,7 +1673,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // Emitted only when the file declares something — see `settingsNested`.
   // The languages the site's translation files make, for a site that declares none (`settingsNested`).
   const languages = targetLocales.length > 0 ? [sourceLocale, ...targetLocales] : null
-  const settings = settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translations, languages })
+  const settings = settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translations, languages, settingsFields: opts.settingsFields })
   if (settings) doc.settings = settings
   doc.pages = pages
   doc.layout_sections = layoutSections
@@ -1663,7 +1686,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // ⚠️ `queriesNested` keeps its name. §2's rule: rename what an author or a
   // consumer sees, leave the identifier alone.
   const scope = opts.scope !== undefined ? opts.scope : await siteSelfScope(siteRoot)
-  doc.queries = queriesNested(colConfig.declarations, opts.queryUuids, scope, opts.keyTyped)
+  doc.queries = queriesNested(colConfig.declarations, opts.queryUuids, scope, opts.keyTyped, opts.queryFields)
   // Emitted ONLY when the file declares the key — see the header above
   // `serviceRecords`: on a replaced Section, absent and empty are different
   // requests and one of them is destructive.