@uniweb/build 1.22.0 → 1.23.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -42,6 +42,7 @@ import { YAML_OPTIONS } from '../utils/yaml-schema.js'
42
42
  import { parseFrontmatter } from './entity-source.js'
43
43
  import { writeRecordFile, writeQueriesConfig, writeRecordsConfig } from './project-writer.js'
44
44
  import { foundationDataSchemas, foundationSchemaJson, QUERIES_YML_RELPATH } from './queries-config.js'
45
+ import { foundationSections } from '../site/queries-config.js'
45
46
  import { dataKeyTypes } from './data-key-types.js'
46
47
  import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir, readEntityPoolSync, resolveRecordMounts } from '../site/entity-pool.js'
47
48
  import { folderYmlPath, resolveFolder } from '../site/records-config.js'
@@ -232,9 +233,43 @@ function recordDirsReadingAs(recordsRoot, model, scope, { own = null, keyTypes =
232
233
  return dirs
233
234
  }
234
235
 
235
- // What the site's foundation declares, when its declarations are in this project: its own
236
- // data-schema names (`ownSchemaNames`) and the types of its data keys (`dataKeyTypes`). Both
237
- // null otherwise — a clone's foundation is not in the project.
236
+ /**
237
+ * What the site's foundation declares, read as the build reads it (`foundationSections`): from its
238
+ * SOURCE when it is local, else from the registered version a clone keeps. Its own data-schema names
239
+ * (`ownSchemaNames`) and the types of its data keys (`dataKeyTypes`); both null when neither is there,
240
+ * or before a clone's `site.yml` exists. A pull reads it once and hands it to `recordsToProject`
241
+ * (`opts.foundation`) and `siteContentDocumentToProject` (`foundation`).
242
+ *
243
+ * ⛔ Until 2026-11-11 the pull read only a built `dist/meta/schema.json`, so in a copy whose local
244
+ * foundation had not been built — every fresh clone — it knew no data key's type: a record kept in
245
+ * a folder named for a typed key (`records/articles/` for `articles: '@/blog-post'`) was written
246
+ * again in its type's folder (`records/blog-post/`), two files for one record, and `queries.yml`
247
+ * gained a `schema:` the author had not written.
248
+ *
249
+ * @param {string} siteRoot
250
+ * @returns {Promise<{ own: Set<string>|null, keyTypes: Map<string, string>|null }>}
251
+ */
252
+ export async function readSiteFoundationDeclarations(siteRoot) {
253
+ let siteYml = null
254
+ try {
255
+ siteYml = yaml.load(readFileSync(join(siteRoot, 'site.yml'), 'utf8'), YAML_OPTIONS) || null
256
+ } catch {
257
+ return { own: null, keyTypes: null }
258
+ }
259
+ let schema = null
260
+ try {
261
+ schema = siteYml ? await foundationSections(siteRoot, siteYml) : null
262
+ } catch {
263
+ schema = null // a foundation that does not read is reported by the build that builds it
264
+ }
265
+ // ⛔ Own names only from a schema that carries its data schemas — see `siteFoundationDeclarations`.
266
+ return schema ? { own: ownSchemaNames(schema.dataSchemas), keyTypes: dataKeyTypes(schema) } : { own: null, keyTypes: null }
267
+ }
268
+
269
+ // What the site's foundation declares, from its BUILT or registered `schema.json` — what a projection
270
+ // reads when its caller hands it nothing (`readSiteFoundationDeclarations`): its own data-schema names
271
+ // (`ownSchemaNames`) and the types of its data keys (`dataKeyTypes`). Both null otherwise — a clone's
272
+ // foundation is not in the project.
238
273
  function siteFoundationDeclarations(siteRoot) {
239
274
  let siteYml = null
240
275
  try {
@@ -460,7 +495,7 @@ function typedQueryFolders(siteRoot, recordsRoot, scope, own, keyTypes) {
460
495
  return out
461
496
  }
462
497
 
463
- export function declarationsToQueriesYml({ document, siteRoot, scope, ...rest }) {
498
+ export function declarationsToQueriesYml({ document, siteRoot, scope, foundation = null, ...rest }) {
464
499
  refuseOrgOption(rest, 'declarationsToQueriesYml')
465
500
  const decls = Array.isArray(document?.queries) ? document.queries : []
466
501
  const report = {}
@@ -474,13 +509,13 @@ export function declarationsToQueriesYml({ document, siteRoot, scope, ...rest })
474
509
  } catch {
475
510
  siteYml = null
476
511
  }
477
- const dataSchemas = siteYml ? foundationDataSchemas(siteRoot, siteYml) : null
478
512
  const selfScope =
479
513
  scope !== undefined ? scope : (parseCatalogRef(document?.info?.foundation)?.scope ?? null)
480
514
  // Which of the scope's schemas are the foundation's own — the rest keep their scope
481
- // (`unresolveSelfScope`) — and the types of its data keys.
482
- const own = ownSchemaNames(dataSchemas)
483
- const keyTypes = siteYml ? dataKeyTypes(foundationSchemaJson(siteRoot, siteYml)) : null
515
+ // (`unresolveSelfScope`) — and the types of its data keys: as the caller read them, from the
516
+ // foundation's source where it is local (`readSiteFoundationDeclarations`), else its built schema.
517
+ const own = foundation?.own ?? ownSchemaNames(siteYml ? foundationDataSchemas(siteRoot, siteYml) : null)
518
+ const keyTypes = foundation?.keyTypes ?? (siteYml ? dataKeyTypes(foundationSchemaJson(siteRoot, siteYml)) : null)
484
519
  const authored = authoredQuerySchemas(siteRoot, siteYml)
485
520
  // The key types a catalog-ref foundation has come from the registered version the project keeps.
486
521
  const markedOnly = Boolean(parseCatalogRef(siteYml?.foundation))
@@ -700,6 +735,8 @@ function holdsPattern(abs) {
700
735
  * back where the author wrote it. The caller resolves it up front, as it does
701
736
  * Models (`siteSelfScope`); absent, a model is placed under its own scope.
702
737
  * @param {string} [params.opts.backend] - whose record map to read and extend
738
+ * @param {{ own: Set<string>|null, keyTypes: Map<string, string>|null }} [params.opts.foundation] - what the
739
+ * site's foundation declares, as `readSiteFoundationDeclarations` reads it; absent, its built schema
703
740
  * @param {string} [params.opts.sourceLocale]
704
741
  * @returns {{ updated: string[], placed: string[], unchanged: string[], skipped: object[], warnings: string[], locales: object }}
705
742
  */
@@ -715,7 +752,10 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
715
752
  // Which of that scope's Models are the foundation's own — the rest keep their scope, so
716
753
  // a standard `@std/person` under a foundation in `@std` is placed in `records/std/person/`
717
754
  // (`unresolveSelfScope`).
718
- const { own, keyTypes } = siteFoundationDeclarations(siteRoot)
755
+ // …as the caller read them, from the foundation's source where it is local
756
+ // (`readSiteFoundationDeclarations`); else from its built or registered schema.
757
+ const declared = opts.foundation?.keyTypes || opts.foundation?.own ? opts.foundation : siteFoundationDeclarations(siteRoot)
758
+ const { own, keyTypes } = declared
719
759
  if (typeof resolveDeclaration !== 'function') {
720
760
  throw new Error('uwx/records-project: opts.resolveDeclaration(modelName) is required')
721
761
  }
@@ -60,6 +60,7 @@ import { toDataSchemaDeclaration, isProseMirrorField, isMarkupTextField } from '
60
60
  import { recordFileLayout, contentBodyTarget } from './record-layout.js'
61
61
  import { emitEntitySyncPackage } from './entity-document.js'
62
62
  import { qualifyRef } from '@uniweb/schemas/refs'
63
+ import { standardTypeFor } from '../site/standard-type-for.js'
63
64
  import { siteSelfScope, refuseOrgOption } from './self-scope.js'
64
65
  import { sha256Hex, toJsonBuffer } from './manifest.js'
65
66
  import { isUuid } from './uuid.js'
@@ -740,7 +741,7 @@ function siteQueries(declarations) {
740
741
  // those files, and on every push once every file in the directory is placed.
741
742
  //
742
743
  // ⚠️ A file that produced nothing is dropped WITHOUT a warning here: its schema did
743
- // not resolve (reported as schemaless), or its records were skipped (reported while
744
+ // not resolve (refused, `noDataSchema`), or its records were skipped (reported while
744
745
  // reading them). Saying it a second time, as a folder problem, names the wrong cause.
745
746
  function placeProducedRecords(nodes, producedBy) {
746
747
  const out = []
@@ -869,12 +870,9 @@ function resolveDeclaration(schema, modelName) {
869
870
  * Defaults to the site's foundation's (`siteSelfScope`); a caller that has it
870
871
  * already passes it, so one emit reads it once.
871
872
  * @returns {Promise<{ entities: object[], index: object[], warnings: string[],
872
- * refusals: string[], schemaless: Array<{name: string, model: string}>,
873
- * colConfig: object, folder: object, recordsDirExists: boolean }>}
874
- * `refusals` — records that cannot be sent as written (`recordsToEntities`).
875
- * `schemaless` lists the QUERIES whose schema resolved to nothing (the
876
- * convention-default soft-skip) — their records are not pushed as entities, and
877
- * the composite deploy delivers those queries statically instead.
873
+ * refusals: string[], colConfig: object, folder: object, recordsDirExists: boolean }>}
874
+ * `refusals` — records that cannot be sent as written (`recordsToEntities`), and the
875
+ * folders and queries whose data schema resolves to nothing (`noDataSchema`).
878
876
  * `recordsDirExists` is false for a site with no records directory at all.
879
877
  * `sendFolder` is whether a push sends the folder — see `sendsFolder`.
880
878
  */
@@ -922,7 +920,6 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
922
920
  index: [],
923
921
  warnings,
924
922
  refusals,
925
- schemaless: [],
926
923
  colConfig,
927
924
  folder: { ...folder, nodes: [] },
928
925
  recordsDirExists: pool.exists,
@@ -941,8 +938,8 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
941
938
  const resolveModel = typeof opts.resolveModel === 'function' ? opts.resolveModel : null
942
939
  // The local foundation is REQUIRED only when a query asked for a schema
943
940
  // EXPLICITLY (and there's no remote resolver). A schema that only a folder name
944
- // or a query name supplied soft-skips when nothing resolves, so a delivery-only
945
- // site with no foundation must not be forced to have one.
941
+ // or a query name supplied and that nothing resolves is refused per folder and per
942
+ // query below (`noDataSchema`), which says which records it is about.
946
943
  const explicitBy = new Map() // schema (as written) → the first query that asked for it
947
944
  for (const { name, decl } of queries) {
948
945
  if (decl.schemaExplicit && !explicitBy.has(decl.schema)) explicitBy.set(decl.schema, name)
@@ -1005,6 +1002,27 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1005
1002
  return modelName
1006
1003
  }
1007
1004
 
1005
+ // ⭐ EVERY RECORD HAS A DATA SCHEMA [Diego, 2026-11-11]. A schema only a folder's name or a
1006
+ // query's name supplied, which resolves to nothing, is refused, one line per folder and per
1007
+ // query that reads no folder: the push sends nothing, and says what to write. ⛔ Until
1008
+ // 2026-11-11 it was a soft skip: the records were not sent, a publish uploaded their compiled
1009
+ // files instead, in the site's own language only, and the app could not edit them.
1010
+ const noDataSchema = (where, modelName) => {
1011
+ const std = standardTypeFor(String(modelName).split('/').pop())
1012
+ return (
1013
+ `${where}: no data schema resolves for ${modelName}` +
1014
+ (resolveModel?.offline === true
1015
+ ? ' here (this run does not ask the backend)'
1016
+ : resolveModel
1017
+ ? ', in the foundation or on the backend'
1018
+ : '') +
1019
+ ', and every record needs one. ' +
1020
+ (std ? `A standard type fits its name: @std/${std}, kept in ${pool.dir}/std/${std}/. ` : '') +
1021
+ 'Use a standard type where one fits (`records/std/<name>/`; `uniweb guide data` lists them), name a ' +
1022
+ 'registered one on the query (`schema:` in queries.yml), or define your own in the foundation (`schemas/<name>.yml`).'
1023
+ )
1024
+ }
1025
+
1008
1026
  // ⚠️ AN EXPLICIT SCHEMA THAT RESOLVES TO NOTHING IS THE AUTHOR'S ERROR — and a
1009
1027
  // depth-2 folder has two readings worth naming. `records/person/2024/ada.md`
1010
1028
  // resolves as `@person/2024` — the rule is total, so it is not ambiguous — but an
@@ -1103,7 +1121,7 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1103
1121
  const index = []
1104
1122
  // pool id (the FILE) → the records it produced, so the folder places records.
1105
1123
  const producedBy = new Map()
1106
- // Schemas (as written) whose Model resolved to nothing — soft-skipped.
1124
+ // Schemas (as written) whose Model resolved to nothing — refused (`noDataSchema`).
1107
1125
  const unresolved = new Set()
1108
1126
  // The sync response is keyed per ($schema, $id), so the pair must be unique
1109
1127
  // within one submission.
@@ -1188,9 +1206,10 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1188
1206
  const declaration = (await declarationFor(modelName)) || (await typedFor(schema))
1189
1207
  if (!declaration) {
1190
1208
  // An explicit schema the author asked for is a hard error; one only the
1191
- // folder's name supplied is a soft skip, reported below.
1209
+ // folder's name supplied is refused for the folder, with the rest of the push.
1192
1210
  if (explicitBy.has(schema)) throw unresolvedExplicit(modelName, explicitBy.get(schema))
1193
1211
  unresolved.add(schema)
1212
+ refusals.push(noDataSchema(`${pool.dir}/${label}/`, modelName))
1194
1213
  continue
1195
1214
  }
1196
1215
 
@@ -1342,18 +1361,10 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1342
1361
  refusals.push(...mappedOut.refusals)
1343
1362
  }
1344
1363
 
1345
- // Queries whose schema resolved to nothing — not pushed as entities. Their compiled
1346
- // data is delivered as static files instead (`site/schemaless-data.js`), so the caller
1347
- // can route it there; and their declarations are sent naming no Model
1348
- // (`site.js::queriesNested`).
1349
- //
1350
- // ⛔ Deliberately NOT a `warnings` string. This is a product decision the author
1351
- // is making — entities or static files — and it needs to be reported at a
1352
- // prominence a prose warning cannot carry. Callers get the structured entry and
1353
- // say it themselves (`cli/src/commands/{publish,push}.js`). It used to push
1354
- // `"… — not synced"`, printed dim among everything else, and an author read that
1355
- // as "my data did not upload" when it is delivered, as static files.
1356
- const schemaless = []
1364
+ // A query reads records of one data schema, so its schema must resolve too. A query over a
1365
+ // folder whose schema resolved to nothing is refused with the folder, above; one that reads no
1366
+ // folder is refused here (`noDataSchema`). ⛔ Until 2026-11-11 such a query was "schema-less":
1367
+ // its declaration went up naming no Model and a publish uploaded its compiled files.
1357
1368
  for (const { name, decl } of queries) {
1358
1369
  const schema = decl.schema || decl.model
1359
1370
  const hasRecords = poolBySchema.has(schema)
@@ -1363,7 +1374,7 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1363
1374
  : Boolean((await declarationFor(modelFor(schema, `query "${name}"`))) || (await typedFor(schema))))
1364
1375
  if (!resolved) {
1365
1376
  if (decl.schemaExplicit) throw unresolvedExplicit(qualifyRef(schema, scope), name)
1366
- schemaless.push({ name, model: qualifyRef(schema, scope) })
1377
+ if (!hasRecords) refusals.push(noDataSchema(`query "${name}"`, qualifyRef(schema, scope)))
1367
1378
  continue
1368
1379
  }
1369
1380
  if (!hasRecords) {
@@ -1375,16 +1386,6 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1375
1386
  )
1376
1387
  }
1377
1388
  }
1378
- // Records whose schema resolved to nothing and that no query reads: they are not
1379
- // pushed, and no static file carries them either — say so, once per folder.
1380
- for (const schema of unresolved) {
1381
- if (queries.some(({ decl }) => (decl.schema || decl.model) === schema)) continue
1382
- const n = poolBySchema.get(schema).length
1383
- warnings.push(
1384
- `${pool.dir}/${poolBySchema.get(schema)[0].dirs.join('/')}/: no data schema resolves for ${schema}, ` +
1385
- `and no query reads ${n === 1 ? 'this record' : `these ${n} records`} — not pushed.`
1386
- )
1387
- }
1388
1389
 
1389
1390
  const nodes = placeProducedRecords(folder.nodes, producedBy)
1390
1391
 
@@ -1393,7 +1394,6 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1393
1394
  index,
1394
1395
  warnings,
1395
1396
  refusals,
1396
- schemaless,
1397
1397
  colConfig,
1398
1398
  folder: { ...folder, nodes },
1399
1399
  recordsDirExists: pool.exists,
@@ -1419,10 +1419,12 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1419
1419
  // the records directory is there and holds nothing at all (the deliberate empty,
1420
1420
  // which removes what the backend has — the CLI asks first).
1421
1421
  //
1422
- // ⛔ NOT when every record's schema resolved to nothing, nor when the directory
1423
- // holds only files that are not records (warned). Neither is an author emptying
1424
- // the folder, and sending one would remove the backend's records — including any
1425
- // authored there — for a state nobody chose. Inert instead, like no directory.
1422
+ // ⛔ NOT when the directory holds only files that are not records (warned), nor when
1423
+ // every record's schema resolved to nothing — which a push refuses (`noDataSchema`),
1424
+ // and which a comparison that does not stop on refusals (`status`) must not read as
1425
+ // an emptied folder. Neither is an author emptying the folder, and sending one would
1426
+ // remove the backend's records — including any authored there — for a state nobody
1427
+ // chose. Inert instead, like no directory.
1426
1428
  function sendsFolder(pool, entities, links = []) {
1427
1429
  if (!pool.exists) return false
1428
1430
  if (entities.length > 0 || links.length > 0) return true
@@ -31,6 +31,7 @@ import { join } from 'node:path'
31
31
  import { normalizeFoundationSchema } from '@uniweb/schemas/foundation'
32
32
  import { parseOptionsRef } from '@uniweb/schemas/format'
33
33
  import { qualifyRef } from '@uniweb/schemas/refs'
34
+ import { mappingInFull } from '../foundation/mappings.js'
34
35
  import { toDataSchemaDeclaration, optionsSectionPath } from './data-schema.js'
35
36
  import { checkFoundationName, checkRegistrationScope, splitFoundationName } from '../foundation-name.js'
36
37
 
@@ -85,6 +86,16 @@ export function buildRegistryPackage({ schema, foundationDir, scope, exporter, e
85
86
  )
86
87
 
87
88
  const mappingEntities = buildMappingEntities(schema._mappings || {}, scoped)
89
+ // Its own, and the library mappings its main.js carries (`_mappings` keys in full), which their
90
+ // library registers: a foundation names those, and registers none.
91
+ const mappingRefs = [
92
+ ...new Set([
93
+ ...mappingEntities.map((e) => e.name),
94
+ ...Object.keys(schema._mappings || {}).filter((ref) => !ref.startsWith('@/')),
95
+ ]),
96
+ ]
97
+ .sort((a, b) => a.localeCompare(b))
98
+ .map((name) => ({ name }))
88
99
 
89
100
  const foundationEntity = {
90
101
  model: FOUNDATION_SCHEMA,
@@ -92,9 +103,7 @@ export function buildRegistryPackage({ schema, foundationDir, scope, exporter, e
92
103
  schema: buildSchemaBlob(schema, org),
93
104
  i18n: { locales: loadI18nLocales(foundationDir) },
94
105
  'data-schemas': { refs: buildRefs(dataSchemas, scoped) },
95
- ...(mappingEntities.length && {
96
- mappings: { refs: mappingEntities.map((e) => ({ name: e.name })).sort((a, b) => a.name.localeCompare(b.name)) },
97
- }),
106
+ ...(mappingRefs.length && { mappings: { refs: mappingRefs } }),
98
107
  }
99
108
 
100
109
  // Data schemas, then mappings, then the foundation: a backend installs them in the order they
@@ -103,31 +112,36 @@ export function buildRegistryPackage({ schema, foundationDir, scope, exporter, e
103
112
  }
104
113
 
105
114
  /**
106
- * Assemble a foundation-LESS registry-publish `.uwx` — only `@uniweb/data-schema`
107
- * entities, no foundation-schema. `uniweb register` submits this for a
108
- * schemas-only package (the standard schemas under `@std`, or an org's own
109
- * `@org/schemas`). A data-schema may be published on its own (`uwx-format.md` §2
110
- * "A data-schema may also be published on its own", §5) — the wire shape is a
111
- * names-only `.uwx` whose entities are all data-schemas.
115
+ * Assemble a foundation-LESS registry-publish `.uwx` — `@uniweb/data-schema` entities,
116
+ * then a library's `@uniweb/mapping-schema` ones, and no foundation-schema. `uniweb
117
+ * register` submits this for a schemas-only package (the standard schemas under `@std`,
118
+ * an org's own `@org/schemas`, a library). A data-schema may be published on its own
119
+ * (`uwx-format.md` §2 "A data-schema may also be published on its own", §5), and a
120
+ * library may hold mappings alone — the wire shape is a names-only `.uwx` with no
121
+ * foundation.
112
122
  *
113
123
  * @param {Object} params
114
124
  * @param {Object} params.schemas - map `{ '@/<name>': normalizedSchema }` of the
115
125
  * schemas the package defines (from `collectStandaloneSchemas`).
126
+ * @param {Object} [params.mappings] - map `{ '@/<name>': declaration }` of the
127
+ * mappings it defines (`buildMappingMap` over its `mappings/`).
116
128
  * @param {string} [params.scope] - org scope (`@std`/`std`) resolving `@/x` -> `@std/x`.
117
129
  * @param {Object} [params.exporter] - `{ tool, version, instance }` envelope.
118
130
  * @param {string} [params.exportedAt] - ISO timestamp (default: now).
119
- * @returns {Object} the `.uwx` document (uwx/1; only data-schema entities, no uuids).
131
+ * @returns {Object} the `.uwx` document (uwx/1; no foundation, no uuids).
120
132
  */
121
- export function buildSchemaOnlyPackage({ schemas, scope, exporter, exportedAt } = {}) {
133
+ export function buildSchemaOnlyPackage({ schemas, mappings, scope, exporter, exportedAt } = {}) {
122
134
  // ⛔ The producer's own guard, as `buildInfo`'s name check is for a foundation:
123
135
  // `uniweb register` refuses a reserved scope before it gets here.
124
136
  const reserved = checkRegistrationScope(scope)
125
137
  if (reserved) throw new Error(`buildSchemaOnlyPackage: ${reserved}`)
126
- const { entities } = buildDataSchemaEntities(schemas || {}, scope)
127
- if (entities.length === 0) {
128
- throw new Error('buildSchemaOnlyPackage: no data schemas to register (expected a map of "@/<name>" -> schema).')
138
+ const { entities, scoped } = buildDataSchemaEntities(schemas || {}, scope)
139
+ // A library's mappings (its `mappings/`) after its types, as in a foundation's package.
140
+ const mappingEntities = buildMappingEntities(mappings || {}, scoped)
141
+ if (entities.length === 0 && mappingEntities.length === 0) {
142
+ throw new Error('buildSchemaOnlyPackage: no data schemas or mappings to register (expected a map of "@/<name>" -> declaration).')
129
143
  }
130
- return wrapEntities(entities, exporter, exportedAt)
144
+ return wrapEntities([...entities, ...mappingEntities], exporter, exportedAt)
131
145
  }
132
146
 
133
147
  // The scope a foundation registers under: the one in its name, else `scope`.
@@ -180,8 +194,8 @@ function buildDataSchemaEntities(dataSchemas, scope) {
180
194
  * One `@uniweb/mapping-schema` entity per mapping the foundation defines (`schema._mappings`,
181
195
  * `foundation/mappings.js`): its identity flat, as a data schema's is, and the rest of the file under
182
196
  * `rules` — the envelope's `model:` names the exchange type, so the mapping's own `model:` cannot sit
183
- * beside it. `rules.model` and `rules.keys_from` are named in full; nothing else in `rules` is
184
- * touched, since a backend judges it. A mapping another one names in `keys_from` comes first.
197
+ * beside it. `rules.model`, `rules.keys_from` and a reverse `follow` line's `model` are named in
198
+ * full; nothing else in `rules` is touched, since a backend judges it. A mapping another one names in `keys_from` comes first.
185
199
  *
186
200
  * @param {Object<string, object>} mappings - `{ '@/<name>': declaration }`
187
201
  * @param {(ref: string) => string} scoped - `@/x` → the registration scope's name
@@ -192,9 +206,7 @@ function buildMappingEntities(mappings, scoped) {
192
206
  .filter(([ref]) => ref.startsWith('@/'))
193
207
  .sort(([a], [b]) => a.localeCompare(b))
194
208
  .map(([ref, decl]) => {
195
- const { label, description, ...rules } = decl
196
- if (typeof rules.model === 'string') rules.model = scoped(rules.model)
197
- if (typeof rules.keys_from === 'string') rules.keys_from = scoped(rules.keys_from)
209
+ const { label, description, ...rules } = mappingInFull(decl, scoped)
198
210
  return {
199
211
  model: MAPPING_SCHEMA,
200
212
  name: scoped(ref),
@@ -7,8 +7,8 @@
7
7
  * site needs it is what its published pages fetch — never whether it has records to sync.
8
8
  * A query counts when a page, a section or the site fetches it, and its records have a
9
9
  * data schema (the declaration names one) and come from the site's own folder (no `url:`).
10
- * A schema-less query's records are delivered as static files, which `records` does not
11
- * touch; an external query is fetched from its own address.
10
+ * Every such query names one, since every record has a data schema [Diego, 2026-11-11];
11
+ * an external query is fetched from its own address.
12
12
  *
13
13
  * @module
14
14
  */
@@ -245,7 +245,7 @@ function readAuthoredYaml(filePath) {
245
245
  * per-file write status ('updated' | 'unchanged'); `blueprint` when the document has a
246
246
  * `services` Section (`./blueprint.js`, `writePulledBlueprint`)
247
247
  */
248
- export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLocale = documentSourceLocale(document), collector, keepAuthoredFoundation = false, sameFile = null, scope }) {
248
+ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLocale = documentSourceLocale(document), collector, keepAuthoredFoundation = false, sameFile = null, scope, foundation = null }) {
249
249
  const info = document?.info || {}
250
250
  const settingsSection = document?.settings || {}
251
251
 
@@ -394,7 +394,7 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
394
394
  siteRoot,
395
395
  rows: document.services,
396
396
  scope: blueprintScope,
397
- own: siteYmlNow ? ownSchemaNames(foundationDataSchemas(siteRoot, siteYmlNow)) : null
397
+ own: foundation?.own ?? (siteYmlNow ? ownSchemaNames(foundationDataSchemas(siteRoot, siteYmlNow)) : null)
398
398
  })
399
399
  }
400
400
 
@@ -1993,7 +1993,7 @@ function seenPageRoutes(items) {
1993
1993
  * page at both its routes
1994
1994
  * @returns {{ config: object, collections: object, locales: object, pages: string[], sections: string[], layout: string[], deleted: string[], renamed: object[] }}
1995
1995
  */
1996
- export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = documentSourceLocale(document), prune = false, keepAuthoredFoundation = false, scope, dataModel = null, sectionType = DEFAULT_SECTION_TYPE, writableMounts = [], priorItems = null }) {
1996
+ export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = documentSourceLocale(document), prune = false, keepAuthoredFoundation = false, scope, dataModel = null, sectionType = DEFAULT_SECTION_TYPE, writableMounts = [], priorItems = null, foundation = null }) {
1997
1997
  // Before anything is written: a pull that would leave content out of the files stops here.
1998
1998
  refuseContentFilesCannotHold(document, sourceLocale)
1999
1999
 
@@ -2026,8 +2026,10 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
2026
2026
  // section's writer to make relative to its own file (`located-media.js`).
2027
2027
  const mediaKeys = siteFileKeys(assetMap)
2028
2028
 
2029
- report.config = siteInfoToConfig({ document, siteRoot, backend, sourceLocale, collector, keepAuthoredFoundation, sameFile: sameStoredFile(assetMap, { siteRoot }), scope })
2030
- report.queries = declarationsToQueriesYml({ document, siteRoot, scope })
2029
+ // What the site's foundation declares, as the caller read it from the foundation's source where it
2030
+ // is local (`readSiteFoundationDeclarations`): absent, each projection reads the built schema.
2031
+ report.config = siteInfoToConfig({ document, siteRoot, backend, sourceLocale, collector, keepAuthoredFoundation, sameFile: sameStoredFile(assetMap, { siteRoot }), scope, foundation })
2032
+ report.queries = declarationsToQueriesYml({ document, siteRoot, scope, foundation })
2031
2033
 
2032
2034
  // The uuid identity index (gitignored `.uniweb/`): read the prior map to anchor
2033
2035
  // rename detection, build a fresh one as we project, then persist it. Items not
package/src/uwx/site.js CHANGED
@@ -1162,7 +1162,7 @@ function externalSource(d) {
1162
1162
  return source
1163
1163
  }
1164
1164
 
1165
- function queriesNested(declarations, uuids = null, scope = null, keyTyped = null, queryFields = null, schemaless = null) {
1165
+ function queriesNested(declarations, uuids = null, scope = null, keyTyped = null, queryFields = null) {
1166
1166
  const out = []
1167
1167
  for (const [name, d] of Object.entries(declarations)) {
1168
1168
  refuseUnder(d.where, `queries.${name}`)
@@ -1183,14 +1183,11 @@ function queriesNested(declarations, uuids = null, scope = null, keyTyped = null
1183
1183
  // names that type — the data schema its records are sent as (`data-key-types.js`).
1184
1184
  const typed = (!d.schemaExplicit && keyTyped?.get(d.schema)) || null
1185
1185
  const schema = typed || d.schema
1186
- // ⛔ NO MODEL FOR A QUERY WHOSE RECORDS RESOLVED NONE (`schemaless`, decided by the records
1187
- // lane — `records.js`). Its name-defaulted `schema` names a Model nothing declares, its records
1188
- // are not pushed, and its compiled data travels as static files — so the declaration goes up
1189
- // with no `schema`. ⛔ Until 2026-09-28 it named that Model anyway (`videos` → `@std/videos`),
1190
- // and a store that checks a query's `schema` against the site's declared types refused the
1191
- // whole content push for it. An explicit `schema:` that does not resolve never reaches here:
1192
- // the records lane refuses it.
1193
- if (!schemaless?.has(name)) setIf(data, 'schema', qualifyRef(schema, scope))
1186
+ // ⭐ EVERY RECORD QUERY NAMES ITS MODEL. One whose schema resolves to nothing never reaches a
1187
+ // backend: the records lane refuses it (`records.js::noDataSchema`), since every record has a
1188
+ // data schema [Diego, 2026-11-11]. ⛔ Until then such a query was "schema-less" and went up
1189
+ // naming no `schema` here, while a publish uploaded its compiled files.
1190
+ setIf(data, 'schema', qualifyRef(schema, scope))
1194
1191
  // ⭐ …AND SAYS SO, so a pull can tell the author's form (`team:`, no schema) from an explicit
1195
1192
  // one — sent only where the deployment's `queries` Section declares the key (`GET /dev/config`
1196
1193
  // → `siteContent.queryFields`), since one that does not refuses a push carrying it.
@@ -1537,8 +1534,6 @@ function touchIconValue(named, settingsFields) {
1537
1534
  * resolves into (`@/x` → `@scope/x`): the site's foundation's. Defaults to
1538
1535
  * `siteSelfScope`; pass the scope the records are emitted with. With none
1539
1536
  * known, `@/x` ships as written.
1540
- * @param {string[]} [opts.schemaless] - the queries whose records resolved no data schema
1541
- * (the records lane's `schemaless`): their declarations name no `schema`.
1542
1537
  * @param {object} [opts.media] - a push's sink for the sections' co-located media
1543
1538
  * (`located-media.js::locatedMediaSink`): each file to upload, and — where its upload
1544
1539
  * map names the file — the reference replaced by the file's key. Absent, nothing is located.
@@ -1826,8 +1821,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
1826
1821
  opts.queryUuids,
1827
1822
  scope,
1828
1823
  opts.keyTyped,
1829
- opts.queryFields,
1830
- Array.isArray(opts.schemaless) ? new Set(opts.schemaless) : null
1824
+ opts.queryFields
1831
1825
  )
1832
1826
  // Emitted only when there is something to state — see the header above
1833
1827
  // `serviceRecords`. ⭐ What this copy holds is per backend — a service is bought on
@@ -295,8 +295,7 @@ function rewriteEntityAssets(node, map, ids, bare = null) {
295
295
  * siteContent: { buffer, entityCount, index, models }|null,
296
296
  * records: { buffer, entityCount, index, models, links }|null,
297
297
  * hashes: Object<string,string>, warnings: string[], refusals: string[],
298
- * skipped: number, schemaless: Array<{name: string, model: string}>,
299
- * localAssets: string[], applied: object, namesNew: string[],
298
+ * skipped: number, localAssets: string[], applied: object, namesNew: string[],
300
299
  * recordItemIdentity: { stamped: number, unknown: number, unbanked: string[] } }>}
301
300
  * Each record entry of `records.index` carries `lists`: the record's list items as
302
301
  * sent (`record-items.js::recordItemLists`), for the caller to bank against the
@@ -305,11 +304,11 @@ function rewriteEntityAssets(node, map, ids, bare = null) {
305
304
  * creates — by `$ref`, where the next push will send a uuid — as keys of `hashes`. A
306
305
  * caller that banks `hashes` re-banks these once the push is applied.
307
306
  * `refusals` names the records that cannot be sent as written, one line each
308
- * (`records.js::recordsToEntities`). A caller that submits must not submit while
309
- * any is present: the backend would refuse the records lane — or, for a record
310
- * written by section whose brief requires nothing, store it empty.
311
- * `schemaless` lists queries that resolved no data schema (soft-skipped from
312
- * the sync) — the composite deploy delivers these statically via the data ball.
307
+ * (`records.js::recordsToEntities`), and each folder or query whose data schema
308
+ * resolves to nothing, since every record needs one (`records.js::noDataSchema`). A
309
+ * caller that submits must not submit while any is present: the backend would refuse
310
+ * the records lane — or, for a record written by section whose brief requires nothing,
311
+ * store it empty.
313
312
  * `localAssets` lists the site-root local media refs (`/images/x.png`) the deploy
314
313
  * must upload + rewrite to serve URLs. A section's co-located files ride `localFiles`,
315
314
  * under their keys from the site root (`located-media.js`); any other co-located ref is
@@ -420,8 +419,6 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
420
419
  // …and the same data schema, where a name stands for the type of its data key
421
420
  // (`@/team` → `@/member`, `data-key-types.js`): decided once, by the records.
422
421
  keyTyped: col.keyTyped,
423
- // …and which queries resolved NO data schema — their declarations go up naming none.
424
- schemaless: col.schemaless.map((q) => q.name),
425
422
  // …and whether this deployment takes the key that says so (`siteContent.queryFields`) —
426
423
  // and the page and `settings` keys that carry Open Graph texts per language.
427
424
  ...(Array.isArray(opts.queryFields) ? { queryFields: opts.queryFields } : {}),
@@ -722,7 +719,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
722
719
  // Records that name a record this push creates — see `namesNew` above.
723
720
  namesNew,
724
721
  refusals,
725
- schemaless: col.schemaless, localAssets, applied,
722
+ localAssets, applied,
726
723
  // The files a push uploads for its file records, each `{ ref, path, contentType }` — the file, and
727
724
  // a PDF's preview — and for its sections' co-located media, each `{ ref, path }`. Uploaded through
728
725
  // the media lane; `ref` is the key the second emit rewrites.
@@ -32,6 +32,7 @@ import { queryNameFromUrl, declaredKeys, fillDeclaredKeys, fetchLevels, pageRout
32
32
  import { parentRouteOf } from '@uniweb/core/route-match'
33
33
 
34
34
  import { validateItem, validateRecordFile, validateBound, validateKeyValue, contentBodyField, rootListSection, referencesOf } from '@uniweb/schemas/conform'
35
+ import { normalizeData } from '@uniweb/schemas/foundation'
35
36
  import { isUuid } from './uwx/uuid.js'
36
37
  import { validateAndNormalizeSchema, buildDataSchemaMap } from './resolve-data-schema.js'
37
38
 
@@ -50,6 +51,45 @@ import { processQueries } from './site/query-processor.js'
50
51
 
51
52
  // --- the join: sections ↔ schemas -------------------------------------------
52
53
 
54
+ /**
55
+ * The keys a section type declares with an inline shape — a field map or a form — whose every
56
+ * field gives a `default:` with something in it: the words a section draws itself, which it shows
57
+ * when the section holds no block of its own (`uniweb guide foundation` § A section's own words).
58
+ * Read by the one normalizer every form of a declaration goes through (`normalizeData`).
59
+ *
60
+ * ⛔ A blank default is not a word: `default: ''`, `null` or an empty list leaves the section nothing
61
+ * to show, which an editor pre-fills as empty — an older way to declare a key a fetch fills, every
62
+ * field blank. ⛔ Until 2026-11-11 (the day this check learned of own words) any `default:` counted.
63
+ *
64
+ * @param {object|undefined} data - a section type's `data:`
65
+ * @returns {Set<string>}
66
+ */
67
+ function keysWithOwnWords(data) {
68
+ const out = new Set()
69
+ let normalized = {}
70
+ try {
71
+ normalized = normalizeData(data, { strict: false }) || {}
72
+ } catch {
73
+ return out // a declaration the foundation's build stops on is reported there
74
+ }
75
+ for (const [key, decl] of Object.entries(normalized)) {
76
+ const fields = decl?.kind === 'fields' ? Object.values(decl.fields || {}) : decl?.kind === 'form' ? decl.fields : null
77
+ if (Array.isArray(fields) && fields.length > 0 && fields.every((f) => f && typeof f === 'object' && shows(f.default))) {
78
+ out.add(key)
79
+ }
80
+ }
81
+ return out
82
+ }
83
+
84
+ /** Whether a field's `default:` gives the section something to show. */
85
+ function shows(value) {
86
+ if (value === undefined || value === null) return false
87
+ if (typeof value === 'string') return value.trim() !== ''
88
+ if (Array.isArray(value)) return value.length > 0
89
+ if (typeof value === 'object') return Object.keys(value).length > 0
90
+ return true
91
+ }
92
+
53
93
  /**
54
94
  * Walk a site's sections, pair each governed data input with its schema, and
55
95
  * validate. The section is the join point: it has a *type* (→ `meta.js` → a
@@ -185,7 +225,16 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
185
225
  const concepts = new Set(
186
226
  (foundation[type]?.content || []).filter((e) => e?.kind === 'concept').map((e) => e.key)
187
227
  )
188
- const declaredNames = declared.map(([key]) => key).filter((key) => !concepts.has(key))
228
+ // ⛔ NOR IS A SECTION'S OWN WORDS. A key declared with an inline shape whose every field gives
229
+ // a `default:` holds the words a section draws itself, which an author overrides with a
230
+ // ```yaml:labels block (`uniweb guide foundation` § A section's own words): with no block the
231
+ // component shows the type's own, so it renders without data, and a page's query that feeds
232
+ // another section has not failed to reach it. ⛔ Until 2026-11-11 it was counted, and every
233
+ // publish of a site whose blog page queries its articles reported the page's Hero.
234
+ const ownWords = keysWithOwnWords(bindings)
235
+ const declaredNames = declared
236
+ .map(([key]) => key)
237
+ .filter((key) => !concepts.has(key) && !ownWords.has(key))
189
238
  if (declaredNames.length > 0 && inputs.length > 0 && fills.size === 0 && !declaredNames.some((k) => held.includes(k))) {
190
239
  const delivered = inputs.map((i) => i.as).filter(Boolean)
191
240
  setupErrors.push({
@@ -355,8 +404,9 @@ function listViolation(finding, label, base) {
355
404
  * ⭐ A folder named for a data key the foundation types, when no data schema has its name,
356
405
  * holds records of that type and is checked against it — `records/team/` against `@/member`
357
406
  * for `data: { team: '@/member' }` — the way a push sends them [Diego, 2026-09-25]
358
- * (`uwx/data-key-types.js`). A folder whose schema resolves to nothing even so is left out in
359
- * silence: its records are schema-less, delivered as files, and the push says so itself.
407
+ * (`uwx/data-key-types.js`). A folder whose schema this check cannot read (a foundation that is
408
+ * not local) is left out in silence; one it can read and finds nothing for has already stopped
409
+ * `processQueries`, since every record has a data schema [Diego, 2026-11-11].
360
410
  *
361
411
  * @returns {Promise<{ violations: object[], setupErrors: object[], schemas: Set<string>, checked: number }>}
362
412
  */