@uniweb/build 0.44.4 → 0.45.0

package/src/site/content-collector.js

@@ -30,7 +30,7 @@ import yaml from 'js-yaml'
 import { collectSectionAssets, mergeAssetCollections, collectConfigAssets } from './assets.js'
 import { collectSectionIcons, mergeIconCollections, buildIconManifest } from './icons.js'
 import { normalizeHideIn, dropUnpublishedPages } from './nav-visibility.js'
-import { parseFetchConfig, toFetchList } from './data-fetcher.js'
+import { parseFetchConfig } from './data-fetcher.js'
 import { resolveExtensionUrls } from './extension-urls.js'
 import { buildTheme, extractFoundationVars } from '../theme/index.js'
 import { resolveDefaultLocale, resolvePublishableLocales, validateLanguageConfig } from '@uniweb/core'
@@ -122,6 +122,51 @@ function extractRouteParam(folderName) {
   return match ? match[1] : null
 }
 
+/**
+ * Folders the build refuses on a route, ruled 2026-09-11 [Diego]:
+ *
+ *   - `[dir]` and `[path]` — `:dir` and `:path` are route variables every
+ *     parametric page already has, so a folder by either name would make one
+ *     name mean two values (and `[path]` is most often a mistyped `[...path]`);
+ *   - any folder inside a `[...path]` folder — the catch-all takes the rest of
+ *     the URL, so a page below it has a route (`/docs/:path*\/edit`) that can
+ *     never match. A folder that holds something other than a page is named
+ *     with a leading `_`, which the walk skips.
+ *
+ * @param {string} name - the folder's name
+ * @param {string} parentRoute - the route of the folder it sits in
+ */
+function assertRouteFolder(name, parentRoute) {
+  if (name === '[dir]' || name === '[path]') {
+    const hint = name === '[path]' ? ' Did you mean `[...path]`, which captures a path of any depth?' : ''
+    throw new Error(
+      `[uniweb] pages: a folder cannot be named \`${name}\` — \`:${name.slice(1, -1)}\` is a route ` +
+        `variable every parametric page already has.${hint}`
+    )
+  }
+  if (typeof parentRoute === 'string' && /\/:[A-Za-z0-9_-]+\*(\/|$)/.test(parentRoute)) {
+    throw new Error(
+      `[uniweb] pages: \`${name}\` sits inside a \`[...path]\` folder (${parentRoute}). The catch-all ` +
+        `takes the rest of the URL, so a page below it could never be reached. Move it beside the ` +
+        `\`[...path]\` folder, or name it \`_${name}\` if it holds something other than a page.`
+    )
+  }
+}
+
+/**
+ * The route param a page nested inside a parametric page binds — its nearest
+ * parametric ancestor's, the DEEPEST `:param` of the route it sits under. Null
+ * when no ancestor is parametric.
+ *
+ * @param {string} parentRoute
+ * @returns {string|null}
+ */
+function inheritedRouteParam(parentRoute) {
+  if (typeof parentRoute !== 'string') return null
+  const params = [...parentRoute.matchAll(/:([A-Za-z0-9_-]+)(?=\/|$)/g)].map((m) => m[1])
+  return params.length ? params[params.length - 1] : null
+}
+
 // ─────────────────────────────────────────────────────────────────
 // Version Detection
 // ─────────────────────────────────────────────────────────────────
@@ -866,7 +911,6 @@ async function processFileAsPage(filePath, fileName, siteRoot, parentRoute) {
       lastModified: fileStat.mtime?.toISOString() || null,
       isDynamic: false,
       paramName: null,
-      parentSchema: null,
       version: null,
       versionMeta: null,
       versionScope: null,
@@ -1467,12 +1511,19 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
   // Determine route
   // Index pages get the parent route as their canonical route (no dual routes)
   // sourcePath stores the original folder-based path for ancestor checking
-  const isDynamic = isDynamicRoute(pageName)
-  const paramName = isDynamic ? extractRouteParam(pageName) : null
+  // ⭐ A page is PARAMETRIC when its folder is a bracket name or it sits inside
+  // one (ruled 2026-09-11 [Diego]): `pages/members/[slug]/cv/` is `/members/:slug/cv`
+  // and binds its ancestor's `slug`. Every lane — the SPA, the prefetch, the static
+  // build — tells a parametric page by the parameter in its route; this flag says
+  // the same thing to a consumer that reads the flag.
+  const isBracket = isDynamicRoute(pageName)
+  const inheritedParam = isBracket ? null : inheritedRouteParam(parentRoute)
+  const isDynamic = isBracket || inheritedParam !== null
+  const paramName = isBracket ? extractRouteParam(pageName) : inheritedParam
 
   // First, calculate the folder-based route (what the route would be without index handling)
   let folderRoute
-  if (isDynamic) {
+  if (isBracket) {
     // Dynamic routes: /blog/[slug] → /blog/:slug (for route matching);
     // /blog/[...path] → /blog/:path* — the one multi-segment token the matcher knows.
     const token = isCatchAllRoute(pageName) ? ':path*' : `:${paramName}`
@@ -1500,23 +1551,13 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
   const layoutObj = mergeLayoutConfig(inheritedLayout, normalizeLayoutConfig(layoutConfig))
   const resolvedLayoutName = layoutObj.name || null
 
-  // For dynamic routes, determine the parent's data schema — this tells
-  // prerender which data array to iterate over.
-  //
-  // ⚖️ **A `[slug]` template expands over exactly ONE record set**, so a plural
-  // parent declaration has to resolve to one query here. The first is taken,
-  // matching what prerender records in `pageFetchedData`; the two must agree or
-  // expansion iterates a set the route was not built from.
-  //
-  // ⛔ This is a genuine cardinality constraint, not a limit worth lifting: a
-  // route pattern names one variable, and "which collection does `:slug` index"
-  // has no second answer. A page that needs another dataset alongside its
-  // dynamic one still declares it — plurality is what makes that sayable.
-  let parentSchema = null
-  if (isDynamic && parentFetch) {
-    const [first] = toFetchList(parentFetch)
-    parentSchema = first ? first.as : null
-  }
+  // ⛔ NO `parentSchema`. Which query a parametric page's URL names one record of
+  // — its ROUTE QUERY — is worked out where it is read, by one function every lane
+  // calls (`routeQuery`, `@uniweb/core/fetch-config`): the page's own query, its
+  // parent's, the site's, or its sections' shared key. This emitted a copy chosen
+  // by another rule (the closest ancestor with a query at ANY depth, never the
+  // page's own or the site's), so the URL narrowed nothing, or a key no section
+  // received — measured 2026-09-10. Removed 2026-09-11 [Diego].
 
   return {
     page: {
@@ -1535,10 +1576,9 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
         : {}),
       lastModified: lastModified?.toISOString(),
 
-      // Dynamic route metadata
+      // Parametric route metadata
       isDynamic,
-      paramName, // e.g., "slug" from [slug]
-      parentSchema, // e.g., "articles" - the data array to iterate over
+      paramName, // e.g., "slug" from [slug]; a nested page's ancestor's
 
       // Version metadata (if within a versioned section)
       version: versionContext?.version || null,
@@ -1872,6 +1912,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
     // Process subdirectories
     for (const folder of orderedFolders) {
       const { name: entry, path: entryPath, dirConfig, dirMode, mountedContentMode, childOrderConfig, childLayout } = folder
+      assertRouteFolder(entry, parentRoute)
       const isIndex = entry === indexName
       const effectiveLayout = mergeLayoutConfig(parentLayout, childLayout)
 
@@ -1930,7 +1971,6 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
           lastModified: null,
           isDynamic: false,
           paramName: null,
-          parentSchema: null,
           version: versionContext?.version || null,
           versionMeta: versionContext?.versionMeta || null,
           versionScope: versionContext?.scope || null,
@@ -2001,6 +2041,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
   // Second pass: process each page folder
   for (const folder of orderedFolders) {
     const { name: entry, path: entryPath, dirConfig, dirMode, mountedContentMode, childOrderConfig, childLayout } = folder
+    assertRouteFolder(entry, parentRoute)
     const isIndex = entry === indexPageName
     const effectiveLayout = mergeLayoutConfig(parentLayout, childLayout)
 
@@ -2024,7 +2065,6 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
         lastModified: null,
         isDynamic: false,
         paramName: null,
-        parentSchema: null,
         version: versionContext?.version || null,
         versionMeta: versionContext?.versionMeta || null,
         versionScope: versionContext?.scope || null,
@@ -2835,6 +2875,7 @@ function buildRouteTranslations(pages, { defaultLocale = 'en', languages = null
 }
 
 export {
+  assertRouteFolder,
   buildRouteTranslations,
   extractItemName,
   parseWildcardArray,

package/src/site/data-fetcher.js

@@ -20,7 +20,7 @@ import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { existsSync } from 'node:fs'
 import yaml from 'js-yaml'
-import { matchWhere, sortRecords, queryDataUrl } from '@uniweb/core'
+import { matchWhere, sortRecords, queryDataUrl, applyScope } from '@uniweb/core'
 
 /**
  * Infer schema name from path or URL
@@ -115,10 +115,16 @@ export function applyWhere(items, where) {
  */
 export function applyPostProcessing(data, config) {
   if (!data || !Array.isArray(data)) return data
-  if (!config.where && !config.sort && !config.limit) return data
+  if (!config.scope && !config.where && !config.sort && !config.limit) return data
 
   let result = data
 
+  // `scope` first — the folder branch the rest of the query reads, over each
+  // record's placement (`path`), as the runtime's default fetcher applies it.
+  if (typeof config.scope === 'string' && config.scope) {
+    result = applyScope(result, config.scope)
+  }
+
   // Apply where-object predicate first (new path)
   if (config.where) {
     result = applyWhere(result, config.where)
@@ -176,16 +182,50 @@ const RECOGNIZED_FETCH_KEYS = {
   // dropped in the one way the author could not see: no warning, and a plausible
   // key inferred from the path in its place. It has its own message below, since
   // "unrecognized" understates a key that used to work.
+  // ⭐ `scope` is recognized since 2026-09-11, when a folder branch became `scope:`
+  // on both lanes and `where: { path: { under } }` was retired in its favour. It
+  // was dropped here as "unrecognized" until then, so a page could not narrow a
+  // query to a branch at all.
   query: new Set([
     'query', 'as', 'prerender', 'merge', 'transform',
-    'where', 'limit', 'sort', 'detailPage',
+    'scope', 'where', 'limit', 'sort', 'detailPage',
   ]),
   source: new Set([
     'path', 'url', 'as', 'prerender', 'merge', 'transform', 'detail',
-    'detailPage', 'where', 'limit', 'sort',
+    'detailPage', 'scope', 'where', 'limit', 'sort',
   ]),
 }
 
+/**
+ * ⛔ `under` IS RETIRED (2026-09-11 [Diego]) — refused, like every retired spelling
+ * here, because an ignored predicate is a silently wrong answer. It existed for
+ * `where: { path: { under: X } }`, a folder branch written before a query had
+ * `scope:`; a branch is `scope: X` now, on both lanes, and the evaluator no longer
+ * knows the operator, so a `where` still carrying it would match nothing.
+ *
+ * @param {Object|undefined} where
+ * @param {string} context - where the declaration sits, for the message
+ */
+export function refuseUnder(where, context) {
+  const walk = (node) => {
+    if (Array.isArray(node)) {
+      node.forEach(walk)
+      return
+    }
+    if (!node || typeof node !== 'object') return
+    for (const [key, value] of Object.entries(node)) {
+      if (value && typeof value === 'object' && !Array.isArray(value) && Object.prototype.hasOwnProperty.call(value, 'under')) {
+        const instead = key === 'path' && typeof value.under === 'string'
+          ? `Write \`scope: ${JSON.stringify(value.under)}\` — the same folder branch, on every lane.`
+          : 'A folder branch is `scope:`; `under` is no longer an operator.'
+        throw new Error(`[uniweb] ${context}: \`where: { ${key}: { under: … } }\` is retired. ${instead}`)
+      }
+      walk(value)
+    }
+  }
+  walk(where)
+}
+
 // Keys that are neither recognized nor merely unknown: they USED to work, and a
 // generic "unrecognized key" line understates that. Each has a dedicated message
 // naming its replacement, so this table only has to keep the generic report from
@@ -300,6 +340,7 @@ export function parseFetchConfig(fetch) {
         'per-instance refinement of the ancestor fetch, under its current name.'
     )
   }
+  refuseUnder(fetch.where, 'fetch')
 
   // Refine config: { refine: true, detail: false, limit: 3 }
   // No URL — merges with the parent fetch config at runtime; only carries
@@ -368,7 +409,8 @@ export function parseFetchConfig(fetch) {
       prerender: fetch.prerender ?? true,
       merge: fetch.merge ?? false,
       transform: fetch.transform,
-      // Query operators
+      // Query operators — a fetch's own override the named query's, per field
+      scope: fetch.scope,
       where: fetch.where,
       limit: fetch.limit,
       sort: fetch.sort,
@@ -389,6 +431,7 @@ export function parseFetchConfig(fetch) {
     detail,
     detailPage,
     // Query operators
+    scope,
     where,
     limit,
     sort,
@@ -413,6 +456,7 @@ export function parseFetchConfig(fetch) {
     // Canonical detail page for a list card's href (page:<stable_id>).
     detailPage,
     // Query operators
+    scope,
     where,
     limit,
     sort,

package/src/site/query-processor.js

@@ -54,8 +54,8 @@ import { join, basename, extname, dirname, relative, resolve, sep } from 'node:p
 import { existsSync } from 'node:fs'
 import yaml from 'js-yaml'
 import { parseBibtex } from '@citestyle/bibtex'
-import { DATA_DIR, fillRoutePattern } from '@uniweb/core'
-import { applyWhere, applySort } from './data-fetcher.js'
+import { DATA_DIR, fillRoutePattern, withoutRouteVariables } from '@uniweb/core'
+import { applyWhere, applySort, refuseUnder } from './data-fetcher.js'
 import { resolveAssetPath, walkContentAssets, isLocalAssetPath } from './assets.js'
 import { readEntityPool, groupPoolBySchema, ENTITIES_DIR } from './entity-pool.js'
 import { readRecordsConfig, resolveFolder, FOLDER_MISSING } from './records-config.js'
@@ -113,6 +113,7 @@ function parseQueryConfig(name, config) {
       schema: config,
       url: null,
       route: null,
+      scope: null,
       sort: null,
       where: null,
       filter: null,
@@ -122,6 +123,7 @@ function parseQueryConfig(name, config) {
     }
   }
 
+  refuseUnder(config.where, `queries.${name}`)
   return {
     name,
     // The query's schema selects its records from the pool — `entities/{schema}/`
@@ -129,6 +131,9 @@ function parseQueryConfig(name, config) {
     schema: config.schema || null,
     url: config.url || null,
     route: config.route || null,
+    // The folder branch the query reads (`records.yml` placement). ⛔ Not read
+    // here until 2026-09-11: a named query's `scope` was ignored on this lane.
+    scope: typeof config.scope === 'string' ? config.scope : null,
     sort: config.sort || null,
     // `where:` is the CANONICAL predicate; `filter:` is the deprecated string DSL
     // it replaced. Both are carried and both are applied below, in the same order
@@ -673,6 +678,19 @@ async function collectItems(siteDir, config, entitiesDir, basePath) {
   // Filter out nulls (unpublished items)
   items = items.filter(Boolean)
 
+  // ⭐ `$name` IS THE RECORD HANDLE ON EVERY SITE (ruled 2026-09-11 [Diego]) — the
+  // field a `[slug]` or `[...path]` page matches, and the one the records service
+  // serves. It is the record's FINAL slug: set here, after every format has been
+  // read and flattened, so a frontmatter `slug:` (which wins over the filename),
+  // a BibTeX cite key and an array-form file's own `slug` all count — exactly what
+  // our sync sends as the entry's name (`uwx/entity-source.js`). `slug` stays:
+  // foundations and templates read it.
+  items = items.map((item) => (
+    item && typeof item === 'object' && item.slug !== undefined && item.slug !== null && item.slug !== ''
+      ? { ...item, $name: String(item.slug) }
+      : item
+  ))
+
   warnDuplicateSlugs(items, config.name)
 
   // `route:` on the query — bake each record's canonical href.
@@ -711,8 +729,19 @@ async function collectItems(siteDir, config, entitiesDir, basePath) {
   // the sync wire, stored — and never applied, while the DEPRECATED one it replaced
   // worked. An author following current guidance got silence and shipped unfiltered
   // data. Pinned by `tests/collection-query-terms.test.js`.
-  if (config.where) {
-    items = applyWhere(items, config.where)
+  // ⭐ ONLY THE `where` FIXED FOR EVERY PAGE. A clause bound to the route —
+  // `where: { tag: :dir }` — cannot be applied to a file written once for every
+  // page; the runtime binds it per page (`@uniweb/core/fetch-config`,
+  // `resolveQuerySource`). ⛔ Until 2026-09-11 it was applied here to the literal
+  // `':dir'`, and the query compiled to no records (measured).
+  //
+  // ⛔ `scope` is NEVER baked, fixed or routed. The runtime applies the one that
+  // wins — a page fetch's own, else this query's — which is what the records
+  // service does. Baked here, a page's `scope:` could only narrow inside the
+  // query's branch on a static site and would replace it on a hosted one.
+  const fixed = withoutRouteVariables({ where: config.where })
+  if (fixed.where) {
+    items = applyWhere(items, fixed.where)
   }
 
   // Apply sort

package/src/uwx/asset-map.js

@@ -36,11 +36,21 @@
  * `config.assets.url` pattern is the whole address, and only the host owns the
  * second half.
  *
+ * ⚖️ **What it holds instead is a FINGERPRINT of the served URL** (`served`), and the
+ * difference is the point: a hash can recognize an address and cannot compose one.
+ * It exists for references that are a BARE STRING — `info.preview`, `info.favicon`,
+ * `seo.image`, a section param — where there is no object to stamp `assetId` beside,
+ * so the stored value is the serve URL alone. `pull` hashes such a string and, when
+ * it matches, puts back the path the author wrote. Should the host ever serve an
+ * asset at a new address, the fingerprint simply stops matching and the pull leaves
+ * the URL — the honest projection — until the next push records the new one.
+ *
  * ⛔ **No mime or size.** The store validates those and they are its to change;
  * a second copy here is a second thing to disagree.
  */
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
 import { ASSET_SLOTS } from '@uniweb/semantic-parser'
 import { join } from 'node:path'
 
@@ -70,6 +80,7 @@ export function readAssetMap(siteDir) {
     for (const [ref, v] of Object.entries(assets)) {
       if (v && typeof v.id === 'string' && v.id) {
         out[ref] = { id: v.id, ext: typeof v.ext === 'string' ? v.ext : '' }
+        if (typeof v.served === 'string' && v.served) out[ref].served = v.served
       }
     }
     return out
@@ -98,10 +109,15 @@ export function updateAssetMap(siteDir, entries) {
   for (const [ref, v] of Object.entries(entries || {})) {
     if (!v?.id) continue
     const was = prior[ref]
+    // A new `served` fingerprint is a change too: the host serves these bytes at
+    // another address now, and the old fingerprint would stop recognizing it. An
+    // entry that carries none — a download learns identity, not an upload's URL —
+    // keeps the one already recorded for the same bytes.
+    const served = v.served || (was && was.id === v.id ? was.served : undefined)
     if (!was) added.push(ref)
-    else if (was.id !== v.id) changed.push(ref)
+    else if (was.id !== v.id || (served || '') !== (was.served || '')) changed.push(ref)
     else continue
-    prior[ref] = { id: v.id, ext: v.ext || '' }
+    prior[ref] = { id: v.id, ext: v.ext || '', ...(served ? { served } : {}) }
   }
 
   if (!added.length && !changed.length) return { added, changed, written: false }
@@ -136,6 +152,26 @@ export function refForAssetId(map, id) {
   return null
 }
 
+/**
+ * The fingerprint `assets.json` keeps of the URL a host serves an asset at.
+ *
+ * A hash, never the URL: it can recognize an address a pull brings back and it
+ * cannot be used to compose one — see the header. Prefixed so a reader of the
+ * committed file cannot mistake it for something to fetch.
+ *
+ * ⛔ Why not carry identity on the wire instead, as content images do? A bare string
+ * has no object to put `assetId` beside, and folding it into the value (a URL
+ * fragment was tried, 2026-09-10) changes what every consumer receives — a
+ * foundation that tells video from image by `src.endsWith('.mp4')` would break on
+ * a hosted site. This way the wire value is exactly the host's URL.
+ *
+ * @param {string} url - the serve URL the upload plan returned, verbatim
+ * @returns {string} `sha256:<16 hex>`
+ */
+export function servedFingerprint(url) {
+  return `sha256:${createHash('sha256').update(String(url)).digest('hex').slice(0, 16)}`
+}
+
 /**
  * Restore authored asset paths on a document being projected back to files.
  *
@@ -188,5 +224,41 @@ export function restoreAssetRefs(document, map) {
     for (const v of Object.values(node)) visit(v)
   }
   visit(document)
+
+  // ⭐ BARE STRINGS — a reference with no object to carry identity beside it
+  // (`info.preview`, `info.favicon`, `seo.image`, a section param). The stored value
+  // is the serve URL alone, so it is recognized by the fingerprint the push recorded
+  // for it (`servedFingerprint`). A string the map has no fingerprint for stays as
+  // the URL that works — the same rule as an unknown id above.
+  const byServed = new Map()
+  for (const [ref, v] of Object.entries(map || {})) {
+    if (v?.served && !byServed.has(v.served)) byServed.set(v.served, ref)
+  }
+  if (byServed.size) {
+    const restore = (v) => {
+      if (typeof v !== 'string' || !looksLikeAddress(v)) return v
+      const ref = byServed.get(servedFingerprint(v))
+      if (!ref) return v
+      stats.restored++
+      return ref
+    }
+    const walk = (node) => {
+      if (Array.isArray(node)) {
+        for (let i = 0; i < node.length; i++) {
+          if (typeof node[i] === 'string') node[i] = restore(node[i])
+          else walk(node[i])
+        }
+      } else if (node && typeof node === 'object') {
+        for (const key of Object.keys(node)) {
+          if (typeof node[key] === 'string') node[key] = restore(node[key])
+          else walk(node[key])
+        }
+      }
+    }
+    walk(document)
+  }
   return stats
 }
+
+// Only a string that could be a served address is worth hashing.
+const looksLikeAddress = (v) => v.startsWith('/') || /^https?:\/\//i.test(v)

package/src/uwx/emit-surface.json

@@ -28,11 +28,17 @@
         "name": [
           "site.yml::name"
         ],
+        "preview": [
+          "site.yml::preview"
+        ],
         "tags": [
           "site.yml::tags"
         ],
         "template": [
           "site.yml::template"
+        ],
+        "url": [
+          "site.yml::$url"
         ]
       }
     },

package/src/uwx/index.js

@@ -54,7 +54,7 @@ export {
   queriesYmlPath,
   QUERIES_YML_RELPATH,
 } from './queries-config.js'
-export { upsertYamlScalar } from './yaml-upsert.js'
+export { upsertYamlScalar, removeYamlScalar } from './yaml-upsert.js'
 export { buildFolderEntity,
   collectFolderItemUuids,
   stampFolderItemUuids
@@ -83,6 +83,7 @@ export {
   refForAssetId,
   restoreAssetRefs,
   ASSET_MAP_FILE,
+  servedFingerprint,
 } from './asset-map.js'
 export {
   diffSiteUnits,

package/src/uwx/records-project.js

@@ -40,6 +40,7 @@ import { writeRecordFile, writeQueriesConfig, writeRecordsConfig } from './proje
 import { defaultSchema, deferredFromSchema, foundationDataSchemas } from './queries-config.js'
 import { poolDirsForSchema, ENTITIES_DIR } from '../site/entity-pool.js'
 import { isContentBodyField } from './data-schema.js'
+import { unresolveSelfScope } from './self-scope.js'
 import { unwrapLocalized } from './backfill.js'
 import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations } from './locale-sync.js'
 import { buildFreeformRecordPath } from '../i18n/freeform.js'
@@ -155,29 +156,10 @@ function recordDirFor(siteRoot, model, selfOrg) {
   return dirs ? join(siteRoot, ENTITIES_DIR, ...dirs) : null
 }
 
-/**
- * Undo the self-scope resolution the producer applies before shipping.
- *
- * ⛔ WITHOUT THIS THE ROUND TRIP IS NOT A FIXED POINT, and the failure is silent
- * on both ends. `@/article` is a FOUNDATION-RELATIVE alias: the producer resolves
- * it to `@acme/article` before it ships, because the backend resolves Models by
- * name and never mints. So a record authored under `entities/article/` comes back
- * as `@acme/article` and, placed literally, lands under `entities/acme/article/` —
- * a different schema folder, which the next build reads as a different schema.
- *
- * ⚠️ It did not show before records were placed by their model: every record went
- * to `collections/<collection>/` regardless, so the resolution had nowhere to leak.
- *
- * ⭐ The site records its own org at create (`site.yml::$org` — "whose this is"),
- * which is exactly the inverse. A model scoped to ANOTHER org is left alone: it
- * genuinely is that org's, and `@/` would be a lie.
- */
-export function unresolveSelfScope(model, selfOrg) {
-  if (typeof model !== 'string' || !selfOrg) return model
-  const org = String(selfOrg).replace(/^@/, '').replace(/\/.*$/, '')
-  if (!org) return model
-  return model.startsWith(`@${org}/`) ? `@/${model.slice(org.length + 2)}` : model
-}
+// ⚠️ Undoing the producer's self-scope resolution (`unresolveSelfScope`) lives in
+// `./self-scope.js`, beside the forward rule it inverts. It did not show before
+// records were placed by their model: every record went to
+// `collections/<collection>/` regardless, so the resolution had nowhere to leak.
 
 // Resolve a record's (collection, slug): the folder index first (authoritative on
 // a read), the record document's `$id` (`<collection>/<slug>`) as a fallback.
@@ -252,7 +234,16 @@ function isDerivedDeferred(d, dataSchemas) {
   return d.deferred.every((f) => a.has(f))
 }
 
-function declToFileShape(d, dataSchemas = null) {
+function declToFileShape(wire, dataSchemas = null, selfOrg = null) {
+  // ⛔ UNDO THE PRODUCER'S QUALIFICATION FIRST, before anything compares against
+  // `schema`. The push qualifies a foundation-relative `@/x` to `@org/x`
+  // (`site.js::queriesNested`), and both checks below are keyed by the author's
+  // `@/x`: against `@org/x` the query-name default would never match — writing an
+  // explicit schema the author never had — and the derived-`deferred` lookup would
+  // miss, persisting a derivation into their file (the 2026-08-29 defect).
+  const d = selfOrg && typeof wire.schema === 'string'
+    ? { ...wire, schema: unresolveSelfScope(wire.schema, selfOrg) }
+    : wire
   const name = d.name || d.$id
   const decl = {}
 
@@ -328,9 +319,12 @@ function declToFileShape(d, dataSchemas = null) {
  * @param {object} params
  * @param {object} params.document - a site-content `$`-document (`{ queries }`)
  * @param {string} params.siteRoot
+ * @param {string} [params.org] - the site's own org, so a `schema` the producer
+ *        qualified from `@/x` is written back as `@/x`. Defaults to `site.yml::$org`,
+ *        the same default `recordsToProject` places records by.
  * @returns {{ collections?: 'updated'|'unchanged' }}
  */
-export function declarationsToQueriesYml({ document, siteRoot }) {
+export function declarationsToQueriesYml({ document, siteRoot, org }) {
   const decls = Array.isArray(document?.queries) ? document.queries : []
   const report = {}
   if (decls.length === 0) return report
@@ -348,10 +342,11 @@ export function declarationsToQueriesYml({ document, siteRoot }) {
     siteYml = null
   }
   const dataSchemas = siteYml ? foundationDataSchemas(siteRoot, siteYml) : null
+  const selfOrg = org ?? readSiteOrg(siteRoot)
 
   const queries = {}
   for (const d of decls) {
-    const { name, decl } = declToFileShape(d, dataSchemas)
+    const { name, decl } = declToFileShape(d, dataSchemas, selfOrg)
     if (!name) continue
     queries[name] = decl
   }

package/src/uwx/records.js

@@ -55,6 +55,7 @@ import {
 } from '../site/entity-pool.js'
 import { toDataSchemaDeclaration, isProseMirrorField, isMarkupTextField, isContentBodyField } from './data-schema.js'
 import { emitEntitySyncPackage } from './entity-document.js'
+import { resolveSelfScope } from './self-scope.js'
 import { sha256Hex, toJsonBuffer } from './manifest.js'
 import { markdownToProseMirror } from '@uniweb/content-reader'
 import { LOCALIZED_FIELD_ASSUMPTION, localize } from './localize.js'
@@ -631,12 +632,10 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
   // `resolveDeclaration` already matches a fully-qualified name against the
   // foundation's `@/`-keyed `dataSchemas`, so a resolved name looks up correctly and
   // `declaration.name` — the value that becomes `$model` — is the resolved one.
-  const selfScopeOrg =
-    typeof opts.org === 'string' ? opts.org.replace(/^@/, '').replace(/\/.*$/, '') : ''
-  const resolveSelfScope = (ref) =>
-    typeof ref === 'string' && ref.startsWith('@/') && selfScopeOrg
-      ? `@${selfScopeOrg}/${ref.slice(2)}`
-      : ref
+  //
+  // ⛔ The rule lives in `./self-scope.js`, shared with the `queries` Section
+  // (`site.js::queriesNested`): a query's `schema` must name exactly the Model
+  // these records are stored under, so both go through one function with one org.
   // Collections that resolved no data schema (the convention-default soft-skip
   // below) — not synced as folder entities. The composite deploy delivers these
   // statically (the "data ball") instead, so the caller can route them there.
@@ -647,7 +646,7 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
   const seen = new Set()
   for (const { name, decl } of mapped) {
     const declaredModel = decl.schema || decl.model
-    const modelName = resolveSelfScope(declaredModel)
+    const modelName = resolveSelfScope(declaredModel, opts.org)
     // Unresolvable `@/` — no org is known. Ship it rather than throwing (a `status`
     // probe on a never-pushed site has no org and must still count), but say so:
     // the backend's refusal names a missing Model and cannot name this cause.