@uniweb/build 1.23.9 → 1.24.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@uniweb/build",
3
- "version": "1.23.9",
3
+ "version": "1.24.1",
4
4
  "description": "Build tooling for the Uniweb Component Web Platform",
5
5
  "type": "module",
6
6
  "exports": {
@@ -57,12 +57,12 @@
57
57
  "js-yaml": "^4.3.2",
58
58
  "sharp": "^0.35.5",
59
59
  "yaml": "^2.5.0",
60
- "@uniweb/content-reader": "~1.5.11",
61
- "@uniweb/projections": "~1.2.17",
62
- "@uniweb/semantic-parser": "~1.13.5",
63
60
  "@uniweb/schemas": "~1.7.4",
64
61
  "@uniweb/theming": "~1.3.2",
65
- "@uniweb/content-writer": "~1.3.2"
62
+ "@uniweb/content-writer": "~1.3.2",
63
+ "@uniweb/content-reader": "~1.5.11",
64
+ "@uniweb/semantic-parser": "~1.13.5",
65
+ "@uniweb/projections": "~1.2.17"
66
66
  },
67
67
  "optionalDependencies": {
68
68
  "@uniweb/runtime": "~1.6.5"
@@ -0,0 +1,55 @@
1
+ /**
2
+ * The system Models whose records only a backend holds — `@uniweb/catalog`, a site backend's store.
3
+ *
4
+ * A site READS one and holds none. It names one in a query (`queries.yml`: `schema: '@uniweb/catalog'`)
5
+ * and in a data key (`meta.js`: `data: { store: { schema: '@uniweb/catalog', whole: true } }`), and the
6
+ * published site's records service answers it: the catalogs its owner made public, each with its
7
+ * offerings and prices, which a visitor who isn't signed in may see. Its records are written in the
8
+ * app, on the site's backend, so no file of a site is one: a build or a push that finds one stops.
9
+ *
10
+ * ⭐ NOTHING HERE DEFINES ONE. The backend's definition is the only one, and the app edits it with its
11
+ * own screen, so a copy kept here could only drift from it. That is the difference from the system
12
+ * Models a site's records may name (`@uniweb/schemas/system`: `@uniweb/link`, `@uniweb/file`), whose
13
+ * definitions a site with no backend builds and validates its own records with.
14
+ *
15
+ * ⛔ Until 2026-11-16 every build refused the name as reserved, and a push named it a Model the backend
16
+ * has none of (the backend's data-schema read answers 404 for its system Models, `@uniweb/link`
17
+ * included, measured on a local backend that day), so a site could not declare its store at all.
18
+ */
19
+
20
+ /** The backend-held system Models, by their full name. */
21
+ export const BACKEND_MODELS = Object.freeze(['@uniweb/catalog'])
22
+
23
+ /** Is this ref one of them? */
24
+ export function isBackendModel(ref) {
25
+ return typeof ref === 'string' && BACKEND_MODELS.includes(ref)
26
+ }
27
+
28
+ /**
29
+ * The refusal for files kept as records of one — `records/uniweb/catalog/`.
30
+ *
31
+ * @param {string} where - the directory, as the author wrote it (`records/uniweb/catalog/`)
32
+ * @param {string} ref - the Model (`@uniweb/catalog`)
33
+ */
34
+ export function backendRecordsRefusal(where, ref) {
35
+ return (
36
+ `${where}: ${ref} is a site backend's own, so a site holds none of its records. Its owner writes ` +
37
+ `them in the app, on the site's backend; the site reads them with a query (\`schema: '${ref}'\` in ` +
38
+ `queries.yml). Remove these files.`
39
+ )
40
+ }
41
+
42
+ /**
43
+ * What a build says about a query of one, which no build has records for: the published site's
44
+ * records service answers it, and a local run sees it with `uniweb dev --published`.
45
+ *
46
+ * @param {string} name - the query's name
47
+ * @param {string} ref - the Model
48
+ */
49
+ export function backendQueryNote(name, ref) {
50
+ return (
51
+ `Query "${name}" reads ${ref}, which only a site backend holds, so a build has none of its records. ` +
52
+ 'On the published site, its records service answers it, with what the site\'s owner made public; ' +
53
+ '`uniweb dev --published` shows that here.'
54
+ )
55
+ }
@@ -45,6 +45,7 @@ import { existsSync, readdirSync, statSync } from 'node:fs'
45
45
  import { join, resolve, isAbsolute, extname, basename } from 'node:path'
46
46
  import { dataRefOf } from '@uniweb/core/data-keys'
47
47
  import { SYSTEM_RECORD_SCHEMAS } from '@uniweb/schemas/system'
48
+ import { BACKEND_MODELS, isBackendModel } from './backend-models.js'
48
49
  import { assertOptionsTargets, assertI18nPaths } from './uwx/data-schema.js'
49
50
  import { pathToFileURL } from 'node:url'
50
51
  import { createRequire } from 'node:module'
@@ -228,15 +229,25 @@ export async function resolveSchemaRef(ref, { srcDir, aliases }) {
228
229
 
229
230
  // ⭐ THE SYSTEM MODELS A SITE'S RECORDS MAY NAME — `@uniweb/link` — resolve from the build's own
230
231
  // copy (`@uniweb/schemas/system`), whatever the foundation holds: a site with no backend builds,
231
- // validates and renders a link record with it. Every other `@uniweb/` name is platform plumbing,
232
- // never a data-schema source. (The whole scope was refused until 2026-09-28.)
232
+ // validates and renders a link record with it. A backend-held one — `@uniweb/catalog` — has no
233
+ // copy here (`./backend-models.js`): `buildDataSchemaMap` passes over it, so asking for its
234
+ // definition is a mistake that says so. Every other `@uniweb/` name is platform plumbing, never a
235
+ // data-schema source. (The whole scope was refused until 2026-09-28.)
233
236
  if (scope === RESERVED_SYSTEM_SCOPE) {
234
237
  const system = SYSTEM_RECORD_SCHEMAS[name]
235
238
  if (system) return normalizeNamedSchema(system, ref)
239
+ if (isBackendModel(ref)) {
240
+ throw new Error(
241
+ `'${ref}' is a site backend's own Model: only the backend defines it, and a site's records are never ` +
242
+ `of it. A site reads it with a query or a data key.`
243
+ )
244
+ }
236
245
  const allowed = Object.keys(SYSTEM_RECORD_SCHEMAS).map((n) => `'@${scope}/${n}'`).join(', ')
246
+ const read = BACKEND_MODELS.map((m) => `'${m}'`).join(', ')
237
247
  throw new Error(
238
248
  `'@${scope}' is the reserved platform system namespace: the only data schemas a site's records ` +
239
- `may name in it are ${allowed}. Use '@std/${name}' for the shared standard schemas.`
249
+ `may name in it are ${allowed}, and a query or a data key may also read ${read}, which a site ` +
250
+ `backend holds. Use '@std/${name}' for the shared standard schemas.`
240
251
  )
241
252
  }
242
253
 
@@ -346,7 +357,9 @@ export async function buildDataSchemaMap(refs, { srcDir }) {
346
357
  const queue = Array.from(refs)
347
358
  while (queue.length > 0) {
348
359
  const ref = queue.shift()
349
- if (map[ref]) continue
360
+ // A backend-held system Model (`@uniweb/catalog`) is a ref with no definition here: a data key or
361
+ // a query reads it, and the backend's definition is the only one (`./backend-models.js`).
362
+ if (map[ref] || isBackendModel(ref)) continue
350
363
  map[ref] = await resolveSchemaRef(ref, { srcDir, aliases })
351
364
  for (const target of collectNestedRefs(map[ref])) {
352
365
  if (!map[target]) queue.push(target)
@@ -32,6 +32,7 @@ import { join } from 'node:path'
32
32
  import { existsSync, readFileSync } from 'node:fs'
33
33
  import { recordLayout } from '@uniweb/schemas/conform'
34
34
  import { isSystemRecordRef } from '@uniweb/schemas/system'
35
+ import { isBackendModel } from '../backend-models.js'
35
36
  import { detectFoundationType, parseCatalogRef } from './foundation-ref.js'
36
37
  import { readRegisteredFoundation } from './registered-foundation.js'
37
38
  import { buildDataSchemaMap, SCHEMA_NOT_FOUND } from '../resolve-data-schema.js'
@@ -387,7 +388,9 @@ export async function dataKeyTyping(siteRoot, declarations, opts = {}) {
387
388
  const { schemas } = await resolveRecordSchemas(siteRoot, [...named, ...keyTypes.values()], { siteYml })
388
389
  for (const [key, type] of keyTypes) {
389
390
  const ref = defaultSchema(key)
390
- if (schemas[ref] || explicit.has(ref) || !schemas[type]) continue
391
+ // A type only a site backend holds (`@uniweb/catalog`) has no definition here, and is a type all
392
+ // the same (`../backend-models.js`).
393
+ if (schemas[ref] || explicit.has(ref) || !(schemas[type] || isBackendModel(type))) continue
391
394
  typing.set(ref, type)
392
395
  }
393
396
  return typing
@@ -69,6 +69,7 @@ import { refuseNotOneRecord } from './record-file.js'
69
69
  import { resolveRecordSchemas, resolveQueriesConfig, dataKeyTyping } from './queries-config.js'
70
70
  import { keyOfDefaultRef } from '../uwx/data-key-types.js'
71
71
  import { standardTypeFor } from './standard-type-for.js'
72
+ import { isBackendModel, backendRecordsRefusal, backendQueryNote } from '../backend-models.js'
72
73
  import { parseFrontmatter } from '../utils/frontmatter.js'
73
74
  import { toDeliveredRecord, toStoredRecord, storedPath, briefFieldMap, contentBodyField, misplacedFields, undeclaredFields, withoutUndeclared, mapReferences, recordLayout } from '@uniweb/schemas/conform'
74
75
  import { ownsType, undeclaredAdvice, listOf } from './undeclared-fields.js'
@@ -1267,6 +1268,8 @@ export async function processQueries(siteDir, queriesConfigIn, recordsDir, baseP
1267
1268
  poolBySchema.delete(ref)
1268
1269
  poolBySchema.set(type, [...(poolBySchema.get(type) || []), ...held])
1269
1270
  }
1271
+ // Once typed, so a folder named for a key typed `@uniweb/catalog` is refused with the catalog's own.
1272
+ refuseBackendRecords(poolBySchema, pool.dir)
1270
1273
 
1271
1274
  // ⭐ THE DATA SCHEMA EACH QUERY'S RECORDS ARE DELIVERED IN (`deliverRecord`) — resolved
1272
1275
  // from the foundation's source once for every query and every folder of records.
@@ -1305,7 +1308,11 @@ export async function processQueries(siteDir, queriesConfigIn, recordsDir, baseP
1305
1308
  parsed.dataSchema = (parsed.schema && dataSchemas[parsed.schema]) || null
1306
1309
  parsed.references = references
1307
1310
  parsed.unsendable = unsendable
1308
- if (parsed.poolEntities.length === 0) {
1311
+ if (parsed.poolEntities.length === 0 && isBackendModel(parsed.schema)) {
1312
+ // ⭐ Records only a site backend holds (`@uniweb/catalog`): none here, ever, so `[]` is the
1313
+ // answer, and the published site's records service answers it with what the owner made public.
1314
+ console.log(`[query-processor] ${backendQueryNote(name, parsed.schema)}`)
1315
+ } else if (parsed.poolEntities.length === 0) {
1309
1316
  const dirs = folderRef ? poolDirsForSchema(folderRef) : null
1310
1317
  console.warn(
1311
1318
  `[query-processor] Query "${name}" matches no records — ` +
@@ -1350,6 +1357,22 @@ async function querySchemas(siteDir, queriesConfig, typing = new Map(), poolBySc
1350
1357
  return { schemas, missing }
1351
1358
  }
1352
1359
 
1360
+ /**
1361
+ * Stop the build for files kept as records of a Model only a site backend holds — `records/uniweb/catalog/`
1362
+ * (`../backend-models.js`): its records are written in the app, on the site's backend, so a site reads
1363
+ * them with a query and holds none. A push refuses the same files.
1364
+ *
1365
+ * @param {Map<string, Array>} poolBySchema - the records, by the ref their folder names
1366
+ * @param {string} dir - the records directory, as the site names it
1367
+ */
1368
+ export function refuseBackendRecords(poolBySchema, dir) {
1369
+ const lines = []
1370
+ for (const [ref, held] of poolBySchema) {
1371
+ if (isBackendModel(ref) && held?.length) lines.push(backendRecordsRefusal(`${dir}/${held[0].dirs.join('/')}/`, ref))
1372
+ }
1373
+ if (lines.length) throw new Error(`[uniweb] ${lines.join('\n')}`)
1374
+ }
1375
+
1353
1376
  /**
1354
1377
  * Stop the build for records whose data schema resolves to nothing, naming each folder and
1355
1378
  * query and what to write: every record has a data schema [Diego, 2026-11-11]. `missing` holds
@@ -157,9 +157,10 @@ const looksLikeAddress = (v) => v.startsWith('/') || /^https?:\/\//i.test(v)
157
157
 
158
158
  /**
159
159
  * Whether two references name the same stored file: the same string, or two references the map gives
160
- * one asset id. A backend keeps a file by its bytes, so two files with the same bytes are one asset, with
161
- * one id and one served address. A stored reference to it says nothing of which path it came from, and
162
- * `restoreAssetRefs` gives it the first path the map lists.
160
+ * one asset id — a path it keeps, or the address the host serves one at. A backend keeps a file by its
161
+ * bytes, so two files with the same bytes are one asset, with one id and one served address. A stored
162
+ * reference to it says nothing of which path it came from, and `restoreAssetRefs` gives it the first
163
+ * path the map lists.
163
164
  *
164
165
  * A relative reference is read from the file it is written in (`fromFile`), as the push keyed it
165
166
  * (`located-media.js::siteFileKey`).
@@ -174,10 +175,23 @@ const looksLikeAddress = (v) => v.startsWith('/') || /^https?:\/\//i.test(v)
174
175
  * @returns {(a: string, b: string, fromFile?: string|null) => boolean}
175
176
  */
176
177
  export function sameStoredFile(map, { siteRoot = null, tree = () => [] } = {}) {
178
+ const byServed = new Map()
179
+ for (const v of Object.values(map || {})) {
180
+ if (v?.served && v?.id && !byServed.has(v.served)) byServed.set(v.served, v.id)
181
+ }
177
182
  const idOf = (ref, fromFile) => {
178
183
  if (typeof ref !== 'string' || !ref) return null
179
184
  const own = map?.[ref]?.id
180
185
  if (own) return own
186
+ // ⭐ An address the host serves a stored file at names that file, by the fingerprint a push
187
+ // recorded for it (`servedFingerprint`), as `restoreAssetRefs` reads it. ⛔ Until 2026-11-16
188
+ // only a path did, so a `site.yml` naming its favicon by the host's address came back as the
189
+ // path of a file of the same bytes the site had just begun to use (`/favicon.svg`), and
190
+ // `uniweb status` called that a change on the backend (measured on a site, 2026-11-16).
191
+ if (looksLikeAddress(ref)) {
192
+ const served = byServed.get(servedFingerprint(ref))
193
+ if (served) return served
194
+ }
181
195
  if (!siteRoot || !fromFile || ref.startsWith('/') || /^[a-z][a-z0-9+.-]*:/i.test(ref)) return null
182
196
  const key = siteFileKey(siteRoot, resolve(dirname(fromFile), ref), tree())
183
197
  return (key && map?.[key]?.id) || null
package/src/uwx/folder.js CHANGED
@@ -159,8 +159,19 @@ function recordOf(item) {
159
159
 
160
160
  /**
161
161
  * Walk a folder document's `contents` tree, visiting every item with the keys that
162
- * address it: its slash-joined `name` chain, whether that chain is UNIQUE among its
163
- * siblings, and — for a leaf — the uuid of the record it references.
162
+ * address it: its slash-joined `name` chain, whether that chain names it alone
163
+ * (`unique`), and — for a leaf — the uuid of the record it references.
164
+ *
165
+ * ⭐ A SUB-FOLDER'S CHAIN NAMES IT WHATEVER RECORDS SIT BESIDE IT. `folder.yml` refuses two
166
+ * sub-folders of one name at one level (`site/records-config.js::resolveFolder`), so a branch
167
+ * is counted among the branches beside it. A leaf's chain names it only when nothing beside
168
+ * it, branch or leaf, has its name: a leaf has its record's key, and never takes a branch's.
169
+ * ⛔ Until 2026-11-16 a branch was counted among every item beside it, so a record named like
170
+ * a sub-folder (`template/blog` at the top, beside the sub-folder `blog`) left the sub-folder
171
+ * with no key. A key an earlier push had banked kept it bound while the map was merged; once
172
+ * the map was written whole (2026-11-13), the next push sent the sub-folder with no `$uuid`,
173
+ * as a new item, and the backend refused it: "409 Conflict — another item already has this
174
+ * name" (measured on a site, 2026-11-15).
164
175
  *
165
176
  * ⛔ IT MUST RECURSE INTO `$children`. `contents` is SELF-NESTING: a walk of the
166
177
  * top level sees the branches and misses every record under them — which is 6 of
@@ -170,13 +181,17 @@ function recordOf(item) {
170
181
  function walkFolderItems(contents, cb, prefix = '') {
171
182
  const items = (contents || []).filter((item) => item && typeof item === 'object')
172
183
  const count = new Map()
184
+ const branches = new Map()
173
185
  for (const item of items) {
174
- if (typeof item.name === 'string') count.set(item.name, (count.get(item.name) || 0) + 1)
186
+ if (typeof item.name !== 'string') continue
187
+ count.set(item.name, (count.get(item.name) || 0) + 1)
188
+ if (item.kind === 'branch') branches.set(item.name, (branches.get(item.name) || 0) + 1)
175
189
  }
176
190
  for (const item of items) {
177
191
  const seg = typeof item.name === 'string' ? item.name : null
178
192
  const path = seg ? (prefix ? `${prefix}/${seg}` : seg) : prefix
179
- if (seg) cb({ path, unique: count.get(seg) === 1, record: recordOf(item) }, item)
193
+ const unique = item.kind === 'branch' ? branches.get(seg) === 1 : count.get(seg) === 1
194
+ if (seg) cb({ path, unique, record: recordOf(item) }, item)
180
195
  walkFolderItems(item.$children, cb, path)
181
196
  }
182
197
  }
@@ -186,8 +201,9 @@ function walkFolderItems(contents, cb, prefix = '') {
186
201
  *
187
202
  * ⭐ A PLACEMENT IS KEYED BY THE RECORD IT REFERENCES — `@<record uuid>` — because a
188
203
  * record has one placement, so that key is unique in the folder whatever the names
189
- * are. A branch, and a leaf whose name no sibling shares, is ALSO keyed by its `name`
190
- * chain, which is what every placement map banked before 2026-09-21 holds.
204
+ * are. A branch is keyed by its `name` chain, and so is a leaf whose name nothing beside
205
+ * it shares (`walkFolderItems`), which is what every placement map banked before
206
+ * 2026-09-21 holds.
191
207
  *
192
208
  * ⛔ The chain alone assumed no two siblings share a name. Two records of different
193
209
  * schemas can (`article/intro`, `person/intro`), and keyed by `intro` both would
@@ -240,7 +256,8 @@ export function collectFolderRecordTypes(doc) {
240
256
  * by a comment in this file that was true of the entity and false of its contents.
241
257
  *
242
258
  * ⭐ A leaf takes the uuid banked under its record (`@<record uuid>`) first, and its
243
- * `name` chain only when no sibling shares the name — the one key an older map has.
259
+ * `name` chain only when no sibling shares the name — the one key an older map has. A
260
+ * branch takes its chain's, which no other branch beside it has.
244
261
  * ⛔ No uuid is stamped twice: two items claiming one row is the failure the record
245
262
  * key exists to prevent, so a second claimant goes out without one, as a new row.
246
263
  *
package/src/uwx/index.js CHANGED
@@ -50,14 +50,18 @@ export {
50
50
  extensionDeclaration,
51
51
  isExtensionUrl,
52
52
  isSiteRelativeExtensionUrl,
53
+ buildRouteOf,
53
54
  } from './site.js'
55
+ // A `page:` reference read as the runtime reads one — a page's id, else its route — over pages a
56
+ // caller lists (`uniweb promote` names a post's page so, on the site as pushed).
57
+ export { pageRefIndex } from './page-refs.js'
54
58
  export {
55
59
  resolveQueriesConfig,
56
60
  queriesYmlPath,
57
61
  QUERIES_YML_RELPATH,
58
62
  } from './queries-config.js'
59
63
  // Edits to a YAML file an author wrote — the one editor; files are written through project-writer.js.
60
- export { editYamlText, setYamlKey, replaceInYamlList } from './yaml-edit.js'
64
+ export { editYamlText, setYamlKey, setYamlKeyFirst, replaceInYamlList } from './yaml-edit.js'
61
65
  export { buildFolderEntity,
62
66
  collectFolderItemUuids,
63
67
  collectFolderRecordTypes,
@@ -313,8 +313,9 @@ function loadYamlFile(filePath) {
313
313
  // rewritten, and every comment, blank line and list the author wrote stays (`editYamlText`). ⛔ Until then
314
314
  // every writer here dumped the whole file — a pull that changed one key of `site.yml` left the Starter
315
315
  // template's 93 lines as 10, and a `pull --merge` conflicted on the whole commented header. The whole dump
316
- // remains for a file with nothing to keep (none yet, unreadable) and one the editor declines (an alias or a
317
- // `<<` merge key, or a result that would read differently).
316
+ // remains for a file with nothing to keep (none yet, unreadable) and one the editor declines (a `<<` merge
317
+ // key in the file's own map, or a result that would read differently). An anchor and its aliases no longer
318
+ // stop an edit (2026-11-16).
318
319
  function writeYamlIfChanged(filePath, value, prior) {
319
320
  if (prior.read && canonicalJson(value) === canonicalJson(prior.value)) return 'unchanged'
320
321
  const edited = prior.read ? editYamlText(prior.text, prior.value, value, YAML_DUMP_OPTS) : null
@@ -73,6 +73,11 @@ import { loadFreeformRecord } from '../i18n/freeform.js'
73
73
  import { isDraftRecord } from '../site/record-draft.js'
74
74
  import { LINK_MODEL, linkRecordRefusal } from './link-records.js'
75
75
  import { FILE_MODEL } from './file-records.js'
76
+ import { isBackendModel, backendRecordsRefusal } from '../backend-models.js'
77
+
78
+ // What `typedFor` answers for a data key typed by a Model only a site backend holds: known, with no
79
+ // declaration to map records by.
80
+ const BACKEND_HELD = Symbol('backend-held')
76
81
 
77
82
  const DATE_KINDS = new Set(['date', 'datetime'])
78
83
  // The record's OWN keys — identity and transport, never a field of any section, never
@@ -1076,6 +1081,12 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1076
1081
  const key = keyOfDefaultRef(schema)
1077
1082
  const type = key ? keyTypes.get(key) : null
1078
1083
  if (!type || explicitBy.has(schema)) return null
1084
+ // A type only a site backend holds (`@uniweb/catalog`) has no declaration to read, here or from
1085
+ // the backend, and is a type all the same: the query names it, and a folder of it is refused.
1086
+ if (isBackendModel(type)) {
1087
+ keyTyped.set(schema, type)
1088
+ return BACKEND_HELD
1089
+ }
1079
1090
  const declaration = await declarationFor(modelFor(type, `data key "${key}"`))
1080
1091
  if (!declaration) return null
1081
1092
  keyTyped.set(schema, type)
@@ -1209,8 +1220,18 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1209
1220
  for (const [schema, poolEntities] of poolBySchema) {
1210
1221
  if (schema === LINK_MODEL || schema === FILE_MODEL) continue
1211
1222
  const label = poolEntities[0].dirs.join('/')
1223
+ // ⛔ Records only a site backend holds (`@uniweb/catalog`, `../backend-models.js`) are never a
1224
+ // site's files: the owner writes them in the app. Refused, as a build refuses them.
1225
+ if (isBackendModel(schema)) {
1226
+ refusals.push(backendRecordsRefusal(`${pool.dir}/${label}/`, schema))
1227
+ continue
1228
+ }
1212
1229
  const modelName = modelFor(schema, `${pool.dir}/${label}/`)
1213
1230
  const declaration = (await declarationFor(modelName)) || (await typedFor(schema))
1231
+ if (declaration === BACKEND_HELD) {
1232
+ refusals.push(backendRecordsRefusal(`${pool.dir}/${label}/`, keyTyped.get(schema)))
1233
+ continue
1234
+ }
1214
1235
  if (!declaration) {
1215
1236
  // An explicit schema the author asked for is a hard error; one only the
1216
1237
  // folder's name supplied is refused for the folder, with the rest of the push.
@@ -1376,8 +1397,12 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1376
1397
  for (const { name, decl } of queries) {
1377
1398
  const schema = decl.schema || decl.model
1378
1399
  const hasRecords = poolBySchema.has(schema)
1379
- // A query over link records names a system Model, which resolves whatever the foundation holds.
1380
- const resolved = schema === LINK_MODEL || schema === FILE_MODEL || (hasRecords
1400
+ // A query over link records names a system Model, which resolves whatever the foundation holds,
1401
+ // and so does one over a Model only a site backend holds (`@uniweb/catalog`): its declaration
1402
+ // goes up, and the published site's records service answers it. The backend's data-schema read
1403
+ // answers neither (404, measured 2026-11-16), so asking it would refuse the push.
1404
+ const backendHeld = isBackendModel(schema)
1405
+ const resolved = schema === LINK_MODEL || schema === FILE_MODEL || backendHeld || (hasRecords
1381
1406
  ? !unresolved.has(schema)
1382
1407
  : Boolean((await declarationFor(modelFor(schema, `query "${name}"`))) || (await typedFor(schema))))
1383
1408
  if (!resolved) {
@@ -1385,7 +1410,8 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
1385
1410
  if (!hasRecords) refusals.push(noDataSchema(`query "${name}"`, qualifyRef(schema, scope)))
1386
1411
  continue
1387
1412
  }
1388
- if (!hasRecords) {
1413
+ // A query a data key types by such a Model (`store: {}`, typed `@uniweb/catalog`) has none either.
1414
+ if (!hasRecords && !backendHeld && !isBackendModel(keyTyped.get(schema))) {
1389
1415
  // "Nothing pushed" and "nothing there" look identical, so say which.
1390
1416
  const dirs = poolDirsForSchema(schema)
1391
1417
  warnings.push(
@@ -20,7 +20,7 @@
20
20
  // beside a comment, a new key PREPENDED above a file's header comments.*
21
21
 
22
22
  import yaml from 'js-yaml'
23
- import { parseDocument, isMap, isSeq, isScalar, Scalar, visit } from 'yaml'
23
+ import { parseDocument, isAlias, isMap, isSeq, isScalar, Scalar } from 'yaml'
24
24
  import { YAML_OPTIONS } from '../utils/yaml-schema.js'
25
25
 
26
26
  /** js-yaml's options for every value the framework writes into YAML, so output is byte-stable. */
@@ -48,7 +48,8 @@ function columnOf(text, key) {
48
48
  /**
49
49
  * Where a pair's text ends: after its value, its trailing comment and its newline.
50
50
  *
51
- * ⛔ A SCALAR ENDS WHERE ITS OWN TEXT DOES — `range[1]`, then the rest of that line. Its
51
+ * ⛔ A SCALAR ENDS WHERE ITS OWN TEXT DOES — `range[1]`, then the rest of that line, and so
52
+ * does an alias (`*persona`). Its
52
53
  * `range[2]` also spans the comment lines that follow it, and for an empty value (`team:`)
53
54
  * every comment and blank line up to the next key, at any indentation: those belong to what
54
55
  * comes next. ⛔ Until 2026-10-08 this read `range[2]`, and a pull that gave a bare `team:` its
@@ -56,7 +57,7 @@ function columnOf(text, key) {
56
57
  */
57
58
  function pairEnd(text, pair) {
58
59
  const node = pair.value ?? pair.key
59
- let end = isScalar(node) ? node.range[1] : node.range[2]
60
+ let end = isScalar(node) || isAlias(node) ? node.range[1] : node.range[2]
60
61
  if (text[end - 1] !== '\n') {
61
62
  const nl = text.indexOf('\n', end)
62
63
  const rest = nl === -1 ? text.slice(end) : text.slice(end, nl)
@@ -75,22 +76,69 @@ function indented(text, col, first) {
75
76
  .join('\n')
76
77
  }
77
78
 
78
- /** An alias or a `<<` merge key: one edit could change what another place says. */
79
- function usesReferences(doc) {
80
- let found = false
81
- visit(doc, {
82
- Alias() {
83
- found = true
84
- return visit.BREAK
85
- },
86
- Pair(_, pair) {
87
- if (isScalar(pair.key) && pair.key.value === '<<') {
88
- found = true
89
- return visit.BREAK
79
+ /** A map that merges another into it (`<<: *base`): some of what it says is not its own to edit. */
80
+ const holdsMergeKey = (map) => map.items.some((pair) => isScalar(pair.key) && pair.key.value === '<<')
81
+
82
+ /** What a value read from YAML holds at `path` (keys and list indexes); undefined where it holds nothing. */
83
+ function valueAt(value, path) {
84
+ let v = value
85
+ for (const step of path) {
86
+ if (v === null || typeof v !== 'object') return undefined
87
+ v = v[step]
88
+ }
89
+ return v
90
+ }
91
+
92
+ /**
93
+ * Every place whose value another place gives it: each alias (`*persona`), with the path of the
94
+ * anchor it names (`&persona`), and each map that merges another into it (`<<`). Walked in the
95
+ * file's order, so an alias names the last anchor of its name before it, as YAML reads it.
96
+ */
97
+ function referencesOf(root) {
98
+ const places = []
99
+ const anchorPathOf = new Map()
100
+ const anchors = new Map()
101
+ const walk = (node, path) => {
102
+ if (!node) return
103
+ if (isAlias(node)) {
104
+ places.push({ node, path })
105
+ if (anchors.has(node.source)) anchorPathOf.set(node, anchors.get(node.source))
106
+ return
107
+ }
108
+ if (node.anchor) anchors.set(node.anchor, path)
109
+ if (isMap(node)) {
110
+ if (holdsMergeKey(node)) places.push({ node, path })
111
+ for (const pair of node.items) {
112
+ if (!isScalar(pair.key) || pair.key.value === '<<') continue
113
+ walk(pair.value, [...path, String(pair.key.value)])
90
114
  }
115
+ } else if (isSeq(node)) {
116
+ node.items.forEach((item, i) => walk(item, [...path, i]))
91
117
  }
92
- })
93
- return found
118
+ }
119
+ walk(root, [])
120
+ return { places, anchorPathOf }
121
+ }
122
+
123
+ /** Whether an alias, left as it is, says `value`: whether its anchor's place is to say it. */
124
+ function aliasHolds(cx, alias, value) {
125
+ const at = cx.anchorPathOf.get(alias)
126
+ return at !== undefined && sameValue(valueAt(cx.after, at), value)
127
+ }
128
+
129
+ /** Whether `node`, or anything in it, is a place that must be written as its own value. */
130
+ function holdsForced(cx, node) {
131
+ if (!cx.force.size || !node) return false
132
+ if (cx.force.has(node)) return true
133
+ if (isMap(node)) return node.items.some((pair) => holdsForced(cx, pair.value))
134
+ if (isSeq(node)) return node.items.some((item) => holdsForced(cx, item))
135
+ return false
136
+ }
137
+
138
+ /** `key: value` as js-yaml writes it, with the value's anchor kept: `key: &persona value`. */
139
+ function anchored(whole, key, anchor, dump) {
140
+ const head = dump({ [key]: null }).replace(/ null\n$/, '')
141
+ return whole.startsWith(head) ? `${head} &${anchor}${whole.slice(head.length)}` : whole
94
142
  }
95
143
 
96
144
  /**
@@ -117,15 +165,20 @@ function scalarText(text, node, value, dump, inFlow) {
117
165
  /**
118
166
  * Make one list say `after` — `before` is what it says now, the same length — by
119
167
  * rewriting each changed entry where it stands. False for anything else (a list that
120
- * grew or shrank, an entry that is not a one-line scalar): the caller writes it whole.
168
+ * grew or shrank, an entry that is not a one-line scalar, an alias that would no longer
169
+ * say its entry): the caller writes it whole.
121
170
  */
122
- function editSeq(text, seq, before, after, edits, dump) {
171
+ function editSeq(cx, seq, before, after, edits) {
123
172
  if (seq.items.length !== before.length || before.length !== after.length) return false
124
173
  const inner = []
125
174
  for (let i = 0; i < after.length; i++) {
126
- if (sameValue(before[i], after[i])) continue
127
175
  const node = seq.items[i]
128
- const now = isScalar(node) ? scalarText(text, node, after[i], dump, seq.flow) : null
176
+ if (isAlias(node)) {
177
+ if (!cx.force.has(node) && aliasHolds(cx, node, after[i])) continue
178
+ return false
179
+ }
180
+ if (sameValue(before[i], after[i]) && !holdsForced(cx, node)) continue
181
+ const now = isScalar(node) ? scalarText(cx.text, node, after[i], cx.dump, seq.flow) : null
129
182
  if (now === null) return false
130
183
  inner.push({ start: node.range[0], end: node.range[1], text: now })
131
184
  }
@@ -137,11 +190,14 @@ function editSeq(text, seq, before, after, edits, dump) {
137
190
  * Make one block map say `after` — `before` is what it says now — by edits to its own
138
191
  * entries: a removed key's lines go, a changed scalar is rewritten where it stands, a
139
192
  * changed map or same-length list is edited the same way one level down, anything else
140
- * is written whole in its place, and a new key goes after the last one. False when the
141
- * map is not one this can edit (a key that is not a plain scalar, or not first on its line).
193
+ * is written whole in its place, and a new key goes after the last one. An alias stays
194
+ * where its anchor's place is to say what it says, and is written as its own value where
195
+ * not; a value written whole keeps its anchor. False when the map is not one this can edit
196
+ * (a key that is not a plain scalar, or not first on its line, or a `<<` merge key).
142
197
  */
143
- function editMap(text, map, before, after, edits, dump) {
144
- if (!map.items.length || !map.items[0].key?.range) return false
198
+ function editMap(cx, map, before, after, edits) {
199
+ const { text, dump } = cx
200
+ if (!map.items.length || !map.items[0].key?.range || holdsMergeKey(map)) return false
145
201
  const col = columnOf(text, map.items[0].key)
146
202
  if (col === null) return false
147
203
  const seen = new Set()
@@ -158,44 +214,49 @@ function editMap(text, map, before, after, edits, dump) {
158
214
  edits.push({ start: lineStart(text, pair.key.range[0]), end: stop, text: '' })
159
215
  continue
160
216
  }
161
- if (Object.hasOwn(before, key) && sameValue(before[key], after[key])) continue
162
217
  const next = after[key]
163
- const inner = []
164
- if (isMap(value) && !value.flow && isPlainObject(before[key]) && isPlainObject(next)) {
165
- if (editMap(text, value, before[key], next, inner, dump)) {
166
- edits.push(...inner)
167
- continue
218
+ if (isAlias(value)) {
219
+ // ⭐ An alias stays where its anchor's place is to say what this one says; written whole
220
+ // below where it is not, as its own value.
221
+ if (!cx.force.has(value) && aliasHolds(cx, value, next)) continue
222
+ } else {
223
+ if (Object.hasOwn(before, key) && sameValue(before[key], next) && !holdsForced(cx, value)) continue
224
+ const inner = []
225
+ if (isMap(value) && !value.flow && isPlainObject(before[key]) && isPlainObject(next)) {
226
+ if (editMap(cx, value, before[key], next, inner)) {
227
+ edits.push(...inner)
228
+ continue
229
+ }
230
+ } else if (isSeq(value) && Array.isArray(before[key]) && Array.isArray(next)) {
231
+ if (editSeq(cx, value, before[key], next, inner)) {
232
+ edits.push(...inner)
233
+ continue
234
+ }
235
+ } else if (isScalar(value)) {
236
+ const now = scalarText(text, value, next, dump, false)
237
+ if (now !== null) {
238
+ edits.push({ start: value.range[0], end: value.range[1], text: now })
239
+ continue
240
+ }
168
241
  }
169
- } else if (isSeq(value) && Array.isArray(before[key]) && Array.isArray(next)) {
170
- if (editSeq(text, value, before[key], next, inner, dump)) {
171
- edits.push(...inner)
172
- continue
173
- }
174
- } else if (isScalar(value)) {
175
- const now = scalarText(text, value, next, dump, false)
176
- if (now !== null) {
177
- edits.push({ start: value.range[0], end: value.range[1], text: now })
178
- continue
242
+ // ⭐ A BARE KEY GIVEN A VALUE KEEPS ITS LINE — and any comment the author wrote on it — and
243
+ // the value goes under it: `team: # the people` gains ` schema: '@/team'` beneath.
244
+ const bare = isScalar(value) && value.value === null && value.range[0] === value.range[1]
245
+ if (bare && (isPlainObject(next) || Array.isArray(next))) {
246
+ const whole = indented(dump({ [key]: next }), col, false)
247
+ const nl = whole.indexOf('\n')
248
+ if (nl !== -1 && nl < whole.length - 1) {
249
+ edits.push({ start: stop, end: stop, text: (text[stop - 1] === '\n' ? '' : '\n') + whole.slice(nl + 1) })
250
+ continue
251
+ }
179
252
  }
180
253
  }
181
- // ⭐ A BARE KEY GIVEN A VALUE KEEPS ITS LINE — and any comment the author wrote on it — and
182
- // the value goes under it: `team: # the people` gains ` schema: '@/team'` beneath.
183
- const bare = isScalar(value) && value.value === null && value.range[0] === value.range[1]
184
- if (bare && (isPlainObject(next) || Array.isArray(next))) {
185
- const whole = indented(dump({ [key]: next }), col, false)
186
- const nl = whole.indexOf('\n')
187
- if (nl !== -1 && nl < whole.length - 1) {
188
- edits.push({ start: stop, end: stop, text: (text[stop - 1] === '\n' ? '' : '\n') + whole.slice(nl + 1) })
189
- continue
190
- }
191
- }
192
- // Written whole — in flow style when the author wrote it that way (`tags: [a, b]`).
254
+ // Written whole — in flow style when the author wrote it that way (`tags: [a, b]`), and
255
+ // with its anchor, so an alias that names it still does.
193
256
  const flow = (isMap(value) || isSeq(value)) && value.flow
194
- edits.push({
195
- start: pair.key.range[0],
196
- end: stop,
197
- text: indented(dump({ [key]: next }, flow ? { flowLevel: 1 } : {}), col, false)
198
- })
257
+ let whole = dump({ [key]: next }, flow ? { flowLevel: 1 } : {})
258
+ if (!isAlias(value) && value?.anchor) whole = anchored(whole, key, value.anchor, dump)
259
+ edits.push({ start: pair.key.range[0], end: stop, text: indented(whole, col, false) })
199
260
  }
200
261
  for (const key of Object.keys(after)) {
201
262
  if (seen.has(key) || after[key] === undefined) continue
@@ -224,12 +285,24 @@ function editMap(text, map, before, after, edits, dump) {
224
285
  * of `site.yml` left the Starter template's 93 lines as 10 — every comment gone — and a
225
286
  * `pull --merge` then conflicted on the whole commented header (F1, F12).*
226
287
  *
288
+ * ⭐ AN ANCHOR AND ITS ALIASES STAY. A value written once and named again (`&persona` …
289
+ * `*persona`) is edited where its anchor is, and an alias stays wherever its anchor's place
290
+ * is to say what it says. Where it is not (the app changed one of the two places), the
291
+ * alias's place is written as its own value: an edit that changed what an alias says is
292
+ * found by the read back, and made again with that place written whole. ⛔ Until 2026-11-16
293
+ * any alias or `<<` merge key made the engine decline the file, and the writer then dumped
294
+ * it whole: a pull that changed one key of a docs site's `site.yml` took all its comments,
295
+ * turned its anchor into two copies and a folded `>` block into `|` (measured on a site,
296
+ * 2026-11-16). A map that merges another into it (`<<`) is still written whole by the map it
297
+ * is in, and the file whole when it is the file's own.
298
+ *
227
299
  * @param {string} text - the file as it is
228
300
  * @param {object} before - what it says, read by the build's reader
229
301
  * @param {object} after - what it must say
230
302
  * @param {object} [dumpOptions] - js-yaml's, for what is written
231
303
  * @returns {string|null} the edited text; null when the file cannot be edited in place —
232
- * not a map, an alias or merge key, a parse error, or a result that reads differently
304
+ * not a map, a `<<` merge key in the file's own map, a parse error, or a result that
305
+ * reads differently
233
306
  */
234
307
  export function editYamlText(text, before, after, dumpOptions = YAML_DUMP_OPTS) {
235
308
  if (typeof text !== 'string' || !isPlainObject(before) || !isPlainObject(after)) return null
@@ -239,29 +312,51 @@ export function editYamlText(text, before, after, dumpOptions = YAML_DUMP_OPTS)
239
312
  } catch {
240
313
  return null
241
314
  }
242
- if (doc.errors.length || usesReferences(doc)) return null
315
+ if (doc.errors.length) return null
243
316
  const dump = (value, extra = {}) => yaml.dump(value, { ...dumpOptions, ...extra })
244
- const edits = []
245
317
  if (doc.contents === null || doc.contents === undefined) {
246
318
  // Comments and nothing else: what the file says goes after them.
247
- const lead = text && !text.endsWith('\n') ? '\n' : ''
248
- edits.push({ start: text.length, end: text.length, text: lead + dump(after) })
249
- } else if (!isMap(doc.contents) || doc.contents.flow || !editMap(text, doc.contents, before, after, edits, dump)) {
250
- return null
319
+ const out = text + (text && !text.endsWith('\n') ? '\n' : '') + dump(after)
320
+ return sameValue(readOrUndefined(out), after) ? out : null
251
321
  }
252
- // Last first, so an offset is never moved by an edit before it. At one offset: a removal
253
- // before an insertion, and the outer map's new keys before the inner map's, so the inner
254
- // map's land first in the text.
322
+ if (!isMap(doc.contents) || doc.contents.flow) return null
323
+ const { places, anchorPathOf } = referencesOf(doc.contents)
324
+ const cx = { text, dump, after, anchorPathOf, force: new Set() }
325
+ // Each round writes at least one more place as its own value, so there are at most as many
326
+ // rounds as places.
327
+ for (;;) {
328
+ const edits = []
329
+ if (!editMap(cx, doc.contents, before, after, edits)) return null
330
+ const out = applyEdits(text, edits)
331
+ const read = readOrUndefined(out)
332
+ if (read !== undefined && sameValue(read, after)) return out
333
+ // A place another gives its value to that does not say what `after` says there — or every
334
+ // one, when an anchor was lost and the text no longer reads — is written as its own value.
335
+ const wrong = places.filter(
336
+ (p) => !cx.force.has(p.node) && (read === undefined || !sameValue(valueAt(read, p.path), valueAt(after, p.path)))
337
+ )
338
+ if (!wrong.length) return null
339
+ for (const p of wrong) cx.force.add(p.node)
340
+ }
341
+ }
342
+
343
+ // Last first, so an offset is never moved by an edit before it. At one offset: a removal
344
+ // before an insertion, and the outer map's new keys before the inner map's, so the inner
345
+ // map's land first in the text.
346
+ function applyEdits(text, edits) {
255
347
  const order = edits.map((e, i) => ({ ...e, i })).sort((a, b) => b.start - a.start || b.end - a.end || b.i - a.i)
256
348
  let out = text
257
349
  for (const e of order) out = out.slice(0, e.start) + e.text + out.slice(e.end)
258
- let read
350
+ return out
351
+ }
352
+
353
+ /** What `text` says, as the build reads it — undefined when it does not read. */
354
+ function readOrUndefined(text) {
259
355
  try {
260
- read = yaml.load(out, YAML_OPTIONS) ?? {}
356
+ return yaml.load(text, YAML_OPTIONS) ?? {}
261
357
  } catch {
262
- return null
358
+ return undefined
263
359
  }
264
- return sameValue(read, after) ? out : null
265
360
  }
266
361
 
267
362
  /** What `text` says, as the build reads it — null when it is not YAML, or not a map. */
@@ -301,7 +396,8 @@ export function setYamlKey(text, key, value) {
301
396
  * @param {string} key
302
397
  * @param {*} value
303
398
  * @returns {string|null} the new contents; null when the text cannot be edited in place — not a
304
- * block map, an alias or merge key, a parse error, or a result that reads differently
399
+ * block map, a parse error, or a result that reads differently. A line before the first key
400
+ * changes nothing an anchor or an alias says, so neither stops it.
305
401
  */
306
402
  export function setYamlKeyFirst(text, key, value) {
307
403
  const before = readMap(text)
@@ -313,7 +409,7 @@ export function setYamlKeyFirst(text, key, value) {
313
409
  } catch {
314
410
  return null
315
411
  }
316
- if (doc.errors.length || usesReferences(doc)) return null
412
+ if (doc.errors.length) return null
317
413
  const line = yaml.dump({ [key]: value }, YAML_DUMP_OPTS)
318
414
  let out
319
415
  if (doc.contents === null || doc.contents === undefined) {