@uniweb/build 0.44.4 → 0.44.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.44.4",
+  "version": "0.44.5",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,12 +57,12 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
+    "@uniweb/content-reader": "^1.2.4",
     "@uniweb/content-writer": "^0.3.4",
     "@uniweb/projections": "^0.6.0",
-    "@uniweb/schemas": "^0.2.13",
     "@uniweb/semantic-parser": "^1.4.0",
-    "@uniweb/theming": "^0.1.15",
-    "@uniweb/content-reader": "^1.2.4"
+    "@uniweb/schemas": "^0.2.13",
+    "@uniweb/theming": "^0.1.15"
   },
   "optionalDependencies": {
     "@uniweb/runtime": "^0.19.5"

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.

package/src/uwx/self-scope.js

@@ -0,0 +1,78 @@
+// `@/x` — a Model ref in the site's own foundation scope — and its qualified form.
+//
+// `@/member` names a data schema in the foundation's own `schemas/`. It is
+// AUTHORING shorthand: a backend resolves Models by name and never mints one, so a
+// ref that leaves the CLI must be the name the Model was stored under,
+// `@<org>/member`. Everything that reads a ref off the wire matches it exactly —
+// the entity store at restore, and a records service answering a hosted page's
+// query.
+//
+// ⭐ ONE RULE FOR EVERY PATH THAT SHIPS A REF FROM ONE PUBLISH, and its inverse:
+//
+//   - a record's `$model`             `records.js::buildRecordEntities`
+//   - a query's `schema`              `site.js::queriesNested` (the `queries` Section)
+//   - the author's spelling, on pull  `records-project.js` (placement and declarations)
+//
+// ⛔ They must agree on one alias. When the query path shipped `@/member` verbatim
+// while the records beside it were qualified, the query named a Model its own
+// records were not stored under: a hosted page's question named a Model that does
+// not exist, the records service refused that key, and the section rendered
+// nothing — the key absent from `content.data`, the reason only on
+// `block.dataError`, the console clean. Nothing on either side was malformed; the
+// two paths disagreed.
+//
+// Registering a foundation qualifies its declarations separately, from the
+// foundation's publish scope (`registry-package.js`). That is a different input
+// (the foundation's scope, not the site's publish org) and stays there.
+
+/**
+ * An org handle as `--org` or `site.yml::$org` gives it — `@acme`, `acme`, or
+ * `@acme/…` — reduced to the bare handle, or `''`.
+ *
+ * @param {unknown} org
+ * @returns {string}
+ */
+export function bareOrg(org) {
+  return typeof org === 'string' ? org.replace(/^@/, '').replace(/\/.*$/, '') : ''
+}
+
+/**
+ * `@/x` → `@<org>/x`. Any other ref (`@std/x`, `@acme/x`) passes through, and so
+ * does `@/x` when no org is known — callers that ship an unresolved alias say so
+ * themselves (`buildRecordEntities` warns per query).
+ *
+ * @param {unknown} ref
+ * @param {unknown} org
+ * @returns {unknown}
+ */
+export function resolveSelfScope(ref, org) {
+  const handle = bareOrg(org)
+  return typeof ref === 'string' && ref.startsWith('@/') && handle
+    ? `@${handle}/${ref.slice(2)}`
+    : ref
+}
+
+/**
+ * The inverse, for a pull: `@<org>/x` → `@/x` for the site's own org.
+ *
+ * ⛔ WITHOUT THIS THE ROUND TRIP IS NOT A FIXED POINT, and the failure is silent
+ * on both ends. 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. A
+ * query declared `schema: '@/member'` comes back as `@acme/member`, and one that
+ * relied on the query-name default comes back with an explicit schema it never
+ * had.
+ *
+ * ⭐ 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.
+ *
+ * @param {unknown} ref
+ * @param {unknown} org
+ * @returns {unknown}
+ */
+export function unresolveSelfScope(ref, org) {
+  const handle = bareOrg(org)
+  if (typeof ref !== 'string' || !handle) return ref
+  return ref.startsWith(`@${handle}/`) ? `@/${ref.slice(handle.length + 2)}` : ref
+}

package/src/uwx/site-project.js

@@ -144,11 +144,19 @@ const INFO_TO_SITE_YML = {
   // ⭐ `tags` — authored, non-localized tokens; the filter facet for a list of site
   // cards. Round-trips verbatim like any authored list.
   tags: 'tags',
-  // ⛔ `url` and `preview_image` ARE DELIBERATELY ABSENT and must stay absent. Both are
-  // BACKEND-STAMPED — a site's live address and its card image URL are assigned by
-  // the host — so writing either into `site.yml` would launder a deploy-derived value
-  // into authored config, which is the hazard `submit` / `assistant` / `tracking` are
-  // annotated against above. Framework emits neither and must project neither.
+  // ⭐ `preview` — the card image, verbatim: the app's timestamp, an author's URL, or
+  // the path an author wrote for an image in the project, which `restoreAssetRefs`
+  // has already put back by recognizing the serve URL the push recorded in
+  // `assets.json` (asset-map.js). [Diego, 2026-09-10]
+  preview: 'preview',
+  // ⭐ `url` — where the site is live → `site.yml::$url`. The backend records it at
+  // every publish, and pull is its only way onto disk; recorded rather than authored,
+  // so it lands under the `$` like `$uuid`.
+  //
+  // ⚠️ Both were listed here as "DELIBERATELY ABSENT… BACKEND-STAMPED" until
+  // 2026-09-10. Leaving an app-written field out of this map is what lets the next
+  // push destroy it, since `info` is replaced whole.
+  url: '$url',
 }
 
 // ── `settings` Section → site.yml ─────────────────────────────────────────────

package/src/uwx/site.js

@@ -62,6 +62,7 @@ import { unwrapLocalized } from './backfill.js'
 import { loadFreeformTranslation } from '../i18n/freeform.js'
 import { upsertYamlScalar } from './yaml-upsert.js'
 import { resolveQueriesConfig } from './queries-config.js'
+import { resolveSelfScope } from './self-scope.js'
 
 const SITE_ENTITY_KEY = 'site-content' // one content entity per site project
 
@@ -69,6 +70,16 @@ function setIf(obj, key, value) {
   if (value !== undefined) obj[key] = value
 }
 
+// A YAML scalar the author may have written unquoted: `20260910` loads as a number
+// and `2026-09-10` as a Date. Carry either as the string it stands for; anything
+// else that is not a string is not a value a string field can hold.
+function scalarString(value) {
+  if (typeof value === 'string') return value
+  if (typeof value === 'number') return String(value)
+  if (value instanceof Date) return value.toISOString()
+  return undefined
+}
+
 // Credential-shaped keys, mirroring the set the delivery edge strips on the
 // reading side. Deliberately the SAME list rather than a stricter one, so the
 // two guards are visibly twins and a key added to one is obviously owed to the
@@ -731,6 +742,9 @@ export function isSiteRelativeExtensionUrl(decl) {
  * @param {object} declarations resolved collection declarations, keyed by name
  * @param {Object<string,string>} [uuids] `name` → backend `$uuid`, from a push
  *        response or a pull. Absent on a first sync, where minting is correct.
+ * @param {string} [org] the publish org. A foundation-relative `schema` (`@/x`)
+ *        is qualified with it (`./self-scope.js`), exactly as the records' `$model`
+ *        is — see the note at the `schema` line below.
  */
 // ⛔ KEYS THAT MUST NOT REACH THE WIRE. Everything else on an authored declaration
 // is emitted, including fields this build does not model — see the note in
@@ -786,13 +800,19 @@ const DECL_NOT_ON_WIRE = new Set([
   'filter'
 ])
 
-function queriesNested(declarations, uuids = null) {
+function queriesNested(declarations, uuids = null, org = null) {
   const out = []
   for (const [name, d] of Object.entries(declarations)) {
     const data = {}
     const source = d.path ? { path: d.path } : d.url ? { url: d.url } : d.source
     setIf(data, 'source', source)
-    setIf(data, 'schema', d.schema)
+    // ⛔ QUALIFIED, WITH THE SAME RULE AND THE SAME ORG AS THE RECORDS' `$model`
+    // (`records.js::buildRecordEntities`). A consumer answers a query by matching
+    // this name against the Models its records were stored under, so a verbatim
+    // `@/member` beside records stored as `@org/member` names nothing: the query
+    // resolves no Model and the page that binds it renders empty. The pull puts the
+    // author's `@/` back (`records-project.js::declarationsToQueriesYml`).
+    setIf(data, 'schema', resolveSelfScope(d.schema, org))
     setIf(data, 'sort', d.sort)
     // Legacy `filter:` is not synced — it is translated to `where` upstream
     // (the canonical predicate). No legacy fields on the wire.
@@ -1021,7 +1041,7 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
   // `ogTitle`, `ogDescription`, `noindex`, `canonical`, `changefreq`, `priority`
   // (`core/src/seo.js`). Two of those are literally sitemap.xml columns. It only
   // ever passed the card test because `image` was inside it; the card's picture is
-  // `info.preview_image` now.
+  // `info.preview` now.
   setIf(settings, 'seo', siteYml.seo)
   // ⭐ `keywords` IS seo by function — it renders into `<meta name="keywords">`
   // (`runtime/src/ssr-renderer.js`). It is top-level in site.yml for authoring
@@ -1076,6 +1096,9 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
  * @param {string} [opts.sourceLocale] - localized-field wrap locale. Defaults to
  *        the site's effective default locale (`defaultLanguage || languages[0] ||
  *        'en'` — the shared `resolveDefaultLocale` rule), NOT a bare 'en'.
+ * @param {string} [opts.org] - the publish org, which qualifies a query's
+ *        foundation-relative `schema` (`@/x` → `@org/x`). Pass the same org the
+ *        records are emitted with; absent, `@/x` ships as written.
  * @returns {Promise<object>} the section-keyed `$`-document:
  *        `{ $uuid?, $id, $model, info, pages, layout_sections, extensions, queries }`
  */
@@ -1271,11 +1294,28 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // over an already-fetched list and never asks the database, while a DB-filterable
   // facet is separately useful — only the second needs a predicable brief field.
   setIf(info, 'tags', siteYml.tags)
-  // ⛔ `url` and `preview_image` are BACKEND-STAMPED and framework emits NEITHER.
-  // A site's live address is assigned at publish and its card image needs a servable
-  // URL; a serve location is a per-response answer the host owns — read, never
-  // constructed. `site-project.js` must also never write them into `site.yml`, or a
-  // pull launders a deploy-derived value into authored config.
+  // ⭐ `preview` — the site card's image. ONE field, TWO writers, and it round-trips
+  // whichever wrote it [Diego, 2026-09-10]:
+  //   · the APP, when it generates a card image — a timestamp, carried verbatim;
+  //   · an AUTHOR, deliberately — typically a template site's custom image: a URL, or
+  //     a site-root path to an image in the project, which push uploads like any
+  //     content image and sends as its serve URL, and which pull puts back as the
+  //     path the author wrote (`restoreAssetRefs` recognizes the URL by the
+  //     fingerprint `assets.json` recorded for it).
+  // The app leaves an author's value alone.
+  //
+  // ⚠️ This read "`url` and `preview_image` are BACKEND-STAMPED and framework emits
+  // NEITHER" until 2026-09-10. Neither half held: nothing stamped `url`, and leaving
+  // an app-written field off an allowlist destroys it on every push, because `info`
+  // is replaced whole.
+  setIf(info, 'preview', scalarString(siteYml.preview))
+  // ⭐ `url` — where the site is live, so a site card can link to it without opening
+  // the editor. The backend records it at every publish (stated by backend,
+  // 2026-09-10) and pull brings it into `site.yml::$url`; nothing in framework writes
+  // it. The `$` marks it as recorded rather than authored, like `$uuid` — and keeps it
+  // out of the rendered payload, where a bare `url:` would sit beside `seo.baseUrl`,
+  // the authored canonical address.
+  setIf(info, 'url', siteYml.$url)
 
   const ctx = { siteRoot, siteIndex: siteYml.index, sourceLocale, translations }
   const pagesPath = siteYml.paths?.pages
@@ -1327,7 +1367,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   //
   // ⚠️ `queriesNested` keeps its name. §2's rule: rename what an author or a
   // consumer sees, leave the identifier alone.
-  doc.queries = queriesNested(colConfig.declarations, opts.queryUuids)
+  doc.queries = queriesNested(colConfig.declarations, opts.queryUuids, opts.org)
   // Emitted ONLY when the file declares the key — see the header above
   // `serviceRecords`: on a replaced Section, absent and empty are different
   // requests and one of them is destructive.

package/src/uwx/sync-package.js

@@ -126,10 +126,13 @@ function walkEntityAssets(node, visitor) {
 //
 //     ⚠️ **This bullet used to justify itself with "no deployment emits
 //     `config.assets.url` yet". FALSIFIED 2026-08-18** by the backend lane:
-//     `serve` publishes the pattern **unconditionally**, falling back to the
-//     direct form, so a deployment with no asset storage emits the honest
-//     `/gateway/asset/dist/{id}/base.{ext}` rather than nothing (measured by
-//     them on a running daemon, not read off a type). ⛔ Scoped to deployments
+//     `serve` publishes the pattern **unconditionally**, falling back to a
+//     direct form, so a deployment with no asset storage emits a pattern rather
+//     than nothing (measured by them on a running daemon, not read off a type).
+//     ⛔ This named that direct form `/gateway/asset/dist/{id}/base.{ext}` until
+//     2026-09-10, and there is no such route [Diego] — the name had spread into
+//     tests and kb as if it were THE serve URL. A serve URL is whatever the host
+//     returns; nothing here depends on its shape. ⛔ Scoped to deployments
 //     running code from 2026-08-17 or later; an older one emits nothing, and
 //     absent stays absent. A present-tense negative about someone else's
 //     deployments is the claim nothing in this repo can ever contradict — it
@@ -157,19 +160,22 @@ function walkEntityAssets(node, visitor) {
 // ProseMirror image node's attrs (`{src, alt, …}`) and a section background's
 // media object (`{image: {src}}`) with one rule — the two shapes framework
 // resolves, reached through the same walk.
-function rewriteEntityAssets(node, map, ids) {
+//
+// `noStamp` is the one object that must get NO identity attrs even when a slot
+// matches — the site's `info`, whose fields the host declares (see the call site).
+function rewriteEntityAssets(node, map, ids, noStamp = null) {
   if (Array.isArray(node)) {
     for (let i = 0; i < node.length; i++) {
       const v = node[i]
       if (typeof v === 'string') { if (map[v]) node[i] = map[v] }
-      else rewriteEntityAssets(v, map, ids)
+      else rewriteEntityAssets(v, map, ids, noStamp)
     }
     return node
   }
   if (node && typeof node === 'object') {
     // Stamp BEFORE the string swap below, while the reference is still the
     // local ref the ids map is keyed by.
-    if (ids) {
+    if (ids && node !== noStamp) {
       // Every asset slot, not just the primary: a video's `poster` and a
       // document's `preview` are assets like any other, and each has identity
       // attrs naming which reference they belong to (ASSET_SLOTS).
@@ -187,7 +193,7 @@ function rewriteEntityAssets(node, map, ids) {
     for (const key of Object.keys(node)) {
       const v = node[key]
       if (typeof v === 'string') { if (map[v]) node[key] = map[v] }
-      else rewriteEntityAssets(v, map, ids)
+      else rewriteEntityAssets(v, map, ids, noStamp)
     }
   }
   return node
@@ -311,6 +317,10 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     ? await siteProjectToDocument(siteRoot, {
         sourceLocale,
         ...(opts.queryUuids ? { queryUuids: opts.queryUuids } : {}),
+        // ⛔ THE SAME ORG `buildRecordEntities` WAS GIVEN ABOVE. A query's `schema`
+        // must name the Model its records are stored under, and both are qualified
+        // from one `@/x` by one rule (`./self-scope.js`) — so they take one org.
+        ...(opts.org ? { org: opts.org } : {}),
         // Withhold the `$services`/`$secrets` Sections when the caller has
         // determined the file is not asking for anything new by them. Passed
         // through rather than decided here: the last-agreed state is project
@@ -387,7 +397,12 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   const assetIds =
     opts.assetIds && typeof opts.assetIds === 'object' ? opts.assetIds : null
   if (assetRewrite) {
-    if (siteDoc) rewriteEntityAssets(siteDoc, assetRewrite, assetIds)
+    // ⛔ No identity attrs on `info`: it is a Section whose fields the host declares,
+    // and `preview` is a real ASSET_SLOTS slot, so stamping would add
+    // `previewAssetId`/`previewAssetExt` — fields the host refuses. Its bare strings
+    // are still swapped for their serve URLs, which `assets.json` recognizes on pull
+    // by fingerprint (asset-map.js → `servedFingerprint`).
+    if (siteDoc) rewriteEntityAssets(siteDoc, assetRewrite, assetIds, siteDoc.info)
     for (const e of col.entities) rewriteEntityAssets(e.document, assetRewrite, assetIds)
   }
   // Collect the site-root local refs the deploy must upload (`/images/x.png`).

package/src/uwx/yaml-upsert.js

@@ -51,3 +51,29 @@ export function upsertYamlScalar(filePath, key, value) {
   writeFileSync(filePath, next)
   return true
 }
+
+/**
+ * Remove a TOP-LEVEL scalar key from the YAML file at `filePath`, preserving every
+ * other line (comments included) — the inverse of `upsertYamlScalar`, with the same
+ * scope: one `key: value` line at column 0. A key followed by indented lines, or
+ * opening a block scalar (`|` / `>`), is not a one-line scalar and is left alone
+ * rather than half-removed.
+ *
+ * @param {string} filePath
+ * @param {string} key - a top-level scalar key (e.g. `$url`)
+ * @returns {boolean} true if the file changed
+ */
+export function removeYamlScalar(filePath, key) {
+  if (!existsSync(filePath)) return false
+  const lines = readFileSync(filePath, 'utf8').split('\n')
+  const esc = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const re = new RegExp(`^${esc}:(.*)$`)
+  const at = lines.findIndex((l) => re.test(l))
+  if (at === -1) return false
+  const inline = lines[at].replace(re, '$1').trim()
+  const continues = at + 1 < lines.length && /^[ \t]+\S/.test(lines[at + 1])
+  if (continues || /^[|>]/.test(inline)) return false
+  lines.splice(at, 1)
+  writeFileSync(filePath, lines.join('\n'))
+  return true
+}