@uniweb/build 0.57.0 → 0.59.0

package/src/uwx/self-scope.js

@@ -1,9 +1,9 @@
-// `@/x` — a Model ref in the site's own foundation scope — and its qualified form.
+// `@/x` — a Model ref in the site's foundation's own 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 —
+// `@<scope>/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.
 //
@@ -13,7 +13,7 @@
 //   - 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
+// ⛔ They must agree on one scope. 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
@@ -21,39 +21,52 @@
 // `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.
+// ⭐ THE SCOPE IS THE FOUNDATION'S — the one in its name (`@acme/marketing`), which is
+// the scope `register` stored the foundation's own data schemas under
+// (`registry-package.js`). ⛔ Until 2026-09-22 every path above qualified with the org
+// that owns the SITE instead — a stand-in that holds only when one org owns both, and
+// a foundation may be registered under any org its author belongs to [Diego]. A site
+// owned by `@client` on a foundation registered as `@acme/fnd` shipped its records as
+// `@client/member`, a Model `register` never stored; a personal site shipped
+// `@/member` unresolved (both measured). `siteSelfScope` is where the scope comes from.
+
+import { readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
+import { detectFoundationType, parseCatalogRef } from '../site/foundation-ref.js'
+import { readFoundationName } from '../schema.js'
+import { splitFoundationName } from '../foundation-name.js'
 
 /**
- * An org handle as `--org` or `sync.json` gives it — `@acme`, `acme`, or
- * `@acme/…` — reduced to the bare handle, or `''`.
+ * A scope as it may be written — `@acme`, `acme`, or `@acme/…` — reduced to the bare
+ * handle, or `''`.
  *
- * @param {unknown} org
+ * @param {unknown} scope
  * @returns {string}
  */
-export function bareOrg(org) {
-  return typeof org === 'string' ? org.replace(/^@/, '').replace(/\/.*$/, '') : ''
+export function bareOrg(scope) {
+  return typeof scope === 'string' ? scope.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
+ * `@/x` → `@<scope>/x`. Any other ref (`@std/x`, `@acme/x`) passes through, and so
+ * does `@/x` when no scope is known — callers that ship an unresolved alias say so
  * themselves (`buildRecordEntities` warns per query).
  *
  * @param {unknown} ref
- * @param {unknown} org
+ * @param {unknown} scope - the site's foundation's scope (`siteSelfScope`)
  * @returns {unknown}
  */
-export function resolveSelfScope(ref, org) {
-  const handle = bareOrg(org)
+export function resolveSelfScope(ref, scope) {
+  const handle = bareOrg(scope)
   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.
+ * The inverse, for a pull: `@<scope>/x` → `@/x` for the site's foundation's scope.
  *
  * ⛔ WITHOUT THIS THE ROUND TRIP IS NOT A FIXED POINT, and the failure is silent
  * on both ends. A record authored under `records/article/` comes back as
@@ -63,16 +76,90 @@ export function resolveSelfScope(ref, org) {
  * relied on the query-name default comes back with an explicit schema it never
  * had.
  *
- * ⭐ The site records its own org at create (`site.org` in `sync.json`, per backend —
- * "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.
+ * A model scoped to ANY OTHER scope is left alone: it genuinely is that org's, and
+ * `@/` would be a lie.
  *
  * @param {unknown} ref
- * @param {unknown} org
+ * @param {unknown} scope - the scope the pulled records were qualified with
  * @returns {unknown}
  */
-export function unresolveSelfScope(ref, org) {
-  const handle = bareOrg(org)
+export function unresolveSelfScope(ref, scope) {
+  const handle = bareOrg(scope)
   if (typeof ref !== 'string' || !handle) return ref
   return ref.startsWith(`@${handle}/`) ? `@/${ref.slice(handle.length + 2)}` : ref
 }
+
+/**
+ * The scope a site's `@/x` refs resolve into: its foundation's, `@org` — or null
+ * when it has none yet.
+ *
+ * - `foundation` given (a pull passes the pinned ref the pushed site carries) — a
+ *   catalog ref's scope, or a local foundation's, resolved from that value.
+ * - else `foundationDir` — that local foundation's.
+ * - else `site.yml::foundation`, the same way.
+ *
+ * A local foundation's scope is the one in its name, read by the one rule
+ * (`readFoundationName`, the reader `register` and `push` use), so what a push pins
+ * and what it qualifies with cannot differ. A bare name has no scope until `register`
+ * gives it one; a URL foundation has none.
+ *
+ * ⚠️ A foundation whose name cannot be read (a leftover `uniweb.scope`, a `main.js`
+ * that fails to load) answers null here. `register` — which a push and a publish run
+ * first — says why; this only qualifies.
+ *
+ * @param {string} siteRoot
+ * @param {{ foundation?: unknown, foundationDir?: string }} [opts]
+ * @returns {Promise<string|null>}
+ */
+export async function siteSelfScope(siteRoot, { foundation, foundationDir } = {}) {
+  if (foundation === undefined && foundationDir) return localFoundationScope(resolve(foundationDir))
+  const declared = foundation !== undefined ? foundation : readDeclaredFoundation(siteRoot)
+  const value = declared && typeof declared === 'object' ? declared.name : declared
+  if (typeof value !== 'string' || !value) return null
+  const ref = parseCatalogRef(value)
+  if (ref) return ref.scope
+  let info = null
+  try {
+    info = detectFoundationType(value, siteRoot)
+  } catch {
+    return null
+  }
+  return info?.type === 'local' && info.path ? localFoundationScope(info.path) : null
+}
+
+async function localFoundationScope(dir) {
+  try {
+    const { name } = await readFoundationName(dir)
+    return splitFoundationName(name).scope
+  } catch {
+    return null
+  }
+}
+
+function readDeclaredFoundation(siteRoot) {
+  try {
+    const siteYml = yaml.load(readFileSync(join(siteRoot, 'site.yml'), 'utf8'), YAML_OPTIONS) || {}
+    return siteYml.foundation ?? null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Refuse the retired `org` option.
+ *
+ * ⛔ It carried the org that owns the SITE, and qualified a site's `@/x` refs with it
+ * (until 2026-09-22). Ignoring it would be silent, so a caller still passing it is told
+ * what replaced it: the foundation's scope, derived — or `scope`, to state it.
+ *
+ * @param {object|undefined} opts
+ * @param {string} where - the function, for the message
+ */
+export function refuseOrgOption(opts, where) {
+  if (opts && opts.org !== undefined) {
+    throw new Error(
+      `${where}: \`org\` is no longer read — a site's \`@/x\` refs resolve into its ` +
+        `foundation's scope (the one in the foundation's name). Pass \`scope\` to state it.`
+    )
+  }
+}

package/src/uwx/site-project.js

@@ -868,9 +868,12 @@ function projectLayout(layoutSections, layoutBaseDir, report, prune, ctx) {
  *        files that have no corresponding incoming item (git-pull-like). Off by
  *        default; `uniweb pull` opts in. Guarded against wiping a level on an
  *        empty set.
+ * @param {string|null} [params.scope] - the scope the push qualified a query's
+ *        `@/x` schema with, so it is written back as `@/x` — see
+ *        `declarationsToQueriesYml`, whose default it overrides.
  * @returns {{ config: object, collections: object, locales: object, pages: string[], sections: string[], layout: string[], deleted: string[], renamed: object[] }}
  */
-export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, prune = false, keepAuthoredFoundation = false }) {
+export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, prune = false, keepAuthoredFoundation = false, scope }) {
   const report = { config: null, collections: null, locales: null, assets: null, pages: [], sections: [], layout: [], deleted: [], renamed: [] }
 
   // Collects target-locale translations of localized scalars as they're projected;
@@ -893,7 +896,7 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
   )
 
   report.config = siteInfoToConfig({ document, siteRoot, backend, sourceLocale, collector, keepAuthoredFoundation })
-  report.queries = declarationsToQueriesYml({ document, siteRoot, backend })
+  report.queries = declarationsToQueriesYml({ document, siteRoot, scope })
 
   // The uuid identity index (gitignored `.uniweb/`): read the prior map to anchor
   // rename detection, build a fresh one as we project, then persist it. Items not

package/src/uwx/site.js

@@ -1,5 +1,5 @@
 // Map a file site project to one `@uniweb/site-content` entity, as the
-// section-keyed `-document (docs/reference/entity-content.md), then to a
+// section-keyed `$`-document (docs/reference/entity-content.md), then to a
 // `subtype: entity` .uwx on the SYNC lane.
 //
 // SOURCE LAYER: the content-collector's return is flattened and lossy for
@@ -8,9 +8,13 @@
 // processMarkdownFile, ordering, mode detection) so those semantics stay
 // identical to a normal build — only the directory/mode/order *walk* is ours.
 //
-// The document mirrors the @uniweb/site-content Model: `info` (brief) · `pages`
-// (self-nesting; each page carries its `page_sections` as an inline field) ·
-// `layout_sections` · `extensions` · `queries`. `info.foundation`
+// The document mirrors the @uniweb/site-content Model: `info` (brief) · `settings`
+// · `pages` (self-nesting; each page carries its `page_sections` as an inline
+// field) · `layout_sections` · `extensions` · `queries` · `services` · `secrets`.
+// `settings` is emitted only when non-empty; `services` and `secrets` only when the
+// backend being pushed to has that key in `sync.json` (absent is not empty — see
+// below). `emit-surface.json` states which `site.yml` key lands in `info` and
+// `settings`. `info.foundation`
 // carries the verbatim `site.yml::foundation` string (the round-trip source of
 // truth).
 //
@@ -73,7 +77,7 @@ import { loadFreeformTranslation } from '../i18n/freeform.js'
 import { updateBackendState, readBackendState } from './sync-store.js'
 import { upsertYamlScalar } from './yaml-upsert.js'
 import { resolveQueriesConfig } from './queries-config.js'
-import { resolveSelfScope } from './self-scope.js'
+import { resolveSelfScope, siteSelfScope, refuseOrgOption } from './self-scope.js'
 import { siteContentDirs } from './site-dirs.js'
 
 const SITE_ENTITY_KEY = 'site-content' // one content entity per site project
@@ -915,7 +919,7 @@ function externalSource(d) {
   return source
 }
 
-function queriesNested(declarations, uuids = null, org = null) {
+function queriesNested(declarations, uuids = null, scope = null) {
   const out = []
   for (const [name, d] of Object.entries(declarations)) {
     refuseUnder(d.where, `queries.${name}`)
@@ -926,13 +930,13 @@ function queriesNested(declarations, uuids = null, org = null) {
     // the runtime fetches it from (never the records service).
     const source = d.path ? { path: d.path } : d.url !== undefined ? externalSource(d) : d.source
     setIf(data, 'source', source)
-    // ⛔ 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))
+    // ⛔ QUALIFIED, WITH THE SAME RULE AND THE SAME SCOPE AS THE RECORDS' `$model`
+    // (`records.js::buildRecordEntities`) — the site's foundation's. 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 `@acme/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, scope))
     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.
@@ -1009,16 +1013,19 @@ function queriesNested(declarations, uuids = null, org = null) {
 // ⛔ ABSENT IS NOT EMPTY, and the difference is destructive. The Section is
 // REPLACED by what we send, so `[]` means "drop every stored config row" while a
 // missing key means "I am not telling you about this". A project that has never
-// pulled has no `$services`, and its ordinary push must not read as a request to
-// wipe a service the operator configured in the app. So: emit the Section only when
-// the file declares the key. Clearing is available and explicit — `$services: []`.
+// pulled has no `services` for that backend, and its ordinary push must not read as
+// a request to wipe a service the operator configured in the app. So: emit the
+// Section only when that backend's entry in `sync.json` carries the key. Clearing is
+// available and explicit — `services: []` there. *(Both said `site.yml::$services`
+// until the move on 2026-09-20.)*
 //
 // ⚠️ The push gate is NOT what makes this safe, though it usually catches it: its
 // tokens live in a gitignored per-clone cache, so a fresh clone pushes
 // unconditionally. Correctness has to sit here.
 
 /**
- * `$services` / `$secrets` → Section records, or undefined when the key is absent.
+ * A backend's provisioned `services` / `secrets` (its `sync.json` entry) → Section
+ * records, or undefined when the key is absent.
  *
  * ⭐ PASSTHROUGH, NOT AN ALLOWLIST — the same rule and the same reason as
  * `queriesNested` above. The field set belongs to the backend's Model, a service's
@@ -1027,7 +1034,8 @@ function queriesNested(declarations, uuids = null, org = null) {
  * would DESTROY whatever is stored under it on every push. Framework can enumerate
  * its own vocabulary and cannot enumerate theirs; withhold ours, forward the rest.
  *
- * @param {*} declared - the raw `$services` / `$secrets` value from site.yml
+ * @param {*} declared - the raw `services` / `secrets` value from that backend's
+ *        `sync.json` entry
  * @param {(entry: object) => string|null} identify - the record's stable `$id`
  * @param {string} label - the key name, for the one warning below
  * @returns {object[]|undefined}
@@ -1229,13 +1237,16 @@ 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.
+ * @param {string|null} [opts.scope] - the scope a query's foundation-relative `schema`
+ *        resolves into (`@/x` → `@scope/x`): the site's foundation's. Defaults to
+ *        `siteSelfScope`; pass the scope the records are emitted with. With none
+ *        known, `@/x` ships as written.
  * @returns {Promise<object>} the section-keyed `$`-document:
- *        `{ $uuid?, $id, $model, info, pages, layout_sections, extensions, queries }`
+ *        `{ $uuid?, $id, $model, info, settings?, pages, layout_sections, extensions,
+ *        queries, services?, secrets? }`
  */
 export async function siteProjectToDocument(siteRoot, opts = {}) {
+  refuseOrgOption(opts, 'uwx/site')
   const siteYml = await readYamlFile(join(siteRoot, 'site.yml'))
   const sourceLocale = opts.sourceLocale || resolveDefaultLocale(siteYml)
   if (!siteYml.name) {
@@ -1533,7 +1544,8 @@ 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, opts.org)
+  const scope = opts.scope !== undefined ? opts.scope : await siteSelfScope(siteRoot)
+  doc.queries = queriesNested(colConfig.declarations, opts.queryUuids, scope)
   // 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.
@@ -1618,53 +1630,13 @@ export function writeSiteEntityUuid(siteRoot, backend, uuid) {
   return updateBackendState(siteRoot, backend, { site: { uuid } })
 }
 
-/**
- * Record the org the site was CREATED under — `backend`'s `site.org` in `sync.json`,
- * beside the site's uuid. (It was `site.yml::$org` until 2026-09-20.)
- *
- * The org is consumed at exactly one moment — the `as_org` on the create that
- * mints `$uuid` — and after that the uuid carries the ownership binding. So this
- * is not a knob the backend re-reads; it is the answer to *"whose workspace is
- * this site's storage charged to?"*, which `$uuid` alone cannot answer and which
- * otherwise costs a backend round-trip (or is simply unknowable from the repo).
- *
- * Stored as the BARE handle, never `@handle` — the canonical form everywhere else
- * (`deriveScope` returns it, `createOrg` echoes it as `org.handle`,
- * `validateHandle` validates it); the `@` is display sugar the reader re-adds. In
- * `site.yml` it was also the only form that parsed: `@` is a reserved YAML
- * indicator, so `$org: @acme` is an error.
- *
- * ⛔ NOT `deploy.yml`, though that file already holds the bound `backend` and the
- * two look like the same class of fact. Four reasons, and the first is the one that
- * settles it:
- *
- *  1. CARDINALITY. `deploy.yml` is multi-TARGET and `backend` sits *under* a target,
- *     so its shape says "this may vary per target." An org may not: one site has one
- *     owning org, fixed at create and preserved on replace. The org is a property of
- *     the site's uuid, and sits beside it in the same backend's section — filing it
- *     under a target would encode a freedom that does not exist.
- *  2. WHO WRITES. Three paths mint a site (`ensureSiteExists`, the media-less push's
- *     content-lane create, and `clone` seeding an existing one) and **none of them
- *     write `deploy.yml`** — only `deploy` and `publish` call `recordLastDeploy`. The
- *     record would exist or not depending on which verb the developer reached for.
- *  3. SUPPRESSIBLE. `recordLastDeploy` is a no-op under `autoSave: off` / `--no-save`.
- *     Turning off deploy *receipts* would silently drop an *ownership* record.
- *  4. SEMANTICS. `deploy.yml` describes the act of shipping (`lastDeploy` is a
- *     receipt) and is optional entirely. But `push` creates a site and never
- *     publishes — a site can exist, be owned, and accrue storage charges without
- *     ever being deployed. Ownership does not belong in a record of a deploy that
- *     may not have happened.
- *
- * `backend` answers *where this ships*; `site.org` answers *whose this is*.
- *
- * @param {string} siteRoot
- * @param {string} backend - the origin of the backend the site was created on
- * @param {string} handle - the bare org handle (no leading `@`)
- * @returns {boolean} true if sync.json changed
- */
-export function writeSiteOrg(siteRoot, backend, handle) {
-  return updateBackendState(siteRoot, backend, { site: { org: handle } })
-}
+// ⛔ `writeSiteOrg` is GONE (2026-09-23). The workspace a project's requests name is two
+// keys of `site` now — `org` (a handle, bare) and `unit` (the uuid of a workspace with no
+// handle), at most one set — and every site request names it, so it is no longer a note
+// written once at the create. A writer of one key would leave the other stale; write
+// both through `updateBackendState`. Why it lives here rather than in `deploy.yml`: a
+// site has one workspace per backend, fixed by the create, while `deploy.yml` is per
+// target and records the act of shipping, which `push` never does.
 
 // ⛔ `writeSiteBackend` and `site.yml::$backend` are GONE (2026-09-20). The scope is
 // no longer a value recorded beside the uuid — it is the KEY the identity is stored

package/src/uwx/sync-package.js

@@ -23,6 +23,7 @@ import { buildRecordEntities, entityContentHash } from './records.js'
 import { ASSET_SLOTS } from '@uniweb/semantic-parser'
 import { buildFolderEntity } from './folder.js'
 import { siteProjectToDocument } from './site.js'
+import { siteSelfScope, refuseOrgOption } from './self-scope.js'
 import { stampUnitUuids, collectUnitUuids } from './site-diff.js'
 import { emitEntitySyncPackage } from './entity-document.js'
 import { isLocalAssetPath } from '../site/assets.js'
@@ -205,6 +206,9 @@ function rewriteEntityAssets(node, map, ids, noStamp = null) {
  * @param {string} siteRoot - directory containing site.yml
  * @param {object} [opts]
  * @param {string} [opts.foundationDir]   - local foundation root (collection Models)
+ * @param {string|null} [opts.scope]      - the scope the site's `@/x` refs resolve
+ *        into. Defaults to its foundation's (`siteSelfScope`) — the one in the
+ *        foundation's name. `org` is refused: it carried the site owner's.
  * @param {Function} [opts.resolveModel]  - async non-local Model resolver
  * @param {string} [opts.sourceLocale]    - localized-field wrap locale
  * @param {Object<string,string>} [opts.priorHashes] - sync-cache (send-only-changed)
@@ -271,6 +275,13 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   const stamp = withBaseVersion(opts.baseVersions || {}, opts.itemBaseVersions || {})
   const exporter = opts.exporter
   const exportedAt = opts.exportedAt
+  refuseOrgOption(opts, 'emitSyncPackages')
+  // ⭐ ONE SCOPE FOR THE WHOLE EMIT — the site's foundation's, the one `register`
+  // stored its Models under — so a record's `$model` and a query's `schema` are
+  // qualified alike. Read once here and handed to both. ⛔ It was the org that owns
+  // the SITE until 2026-09-22 (`self-scope.js`).
+  const scope =
+    opts.scope !== undefined ? opts.scope : await siteSelfScope(siteRoot, { foundationDir: opts.foundationDir })
 
   const col = await buildRecordEntities(siteRoot, {
     // Which backend's record uuids go on the wire (sync.json) — see records.js.
@@ -278,10 +289,10 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     ...(opts.foundationDir ? { foundationDir: opts.foundationDir } : {}),
     ...(opts.resolveModel ? { resolveModel: opts.resolveModel } : {}),
     ...(sourceLocale ? { sourceLocale } : {}),
-    // The publish org — resolves a foundation-relative `@/x` model ref into
-    // `@org/x` before it ships. Absent on an offline probe, which is why
-    // buildRecordEntities warns rather than throws.
-    ...(opts.org ? { org: opts.org } : {}),
+    // Resolves a foundation-relative `@/x` model ref into `@scope/x` before it ships.
+    // Null for a foundation with no scope yet, which is why buildRecordEntities
+    // warns rather than throws.
+    scope,
   })
   const warnings = [...col.warnings, ...(col.folder?.warnings ?? [])]
 
@@ -291,9 +302,9 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     recordEntities: col.entities,
     ...(sourceLocale ? { sourceLocale } : {}),
     // ⭐ Every record in the directory, at the top of the folder or in the
-    // sub-folder `records.yml` places it in — and NOTHING when there is no folder to
+    // sub-folder `folder.yml` places it in — and NOTHING when there is no folder to
     // state. ⛔ Gated here as well as by `declared`, because the builder sends any
-    // non-empty tree: a `records.yml` whose folders hold only records that resolved
+    // non-empty tree: a `folder.yml` whose folders hold only records that resolved
     // no schema is a tree of empty branches, and sending it would replace the
     // backend's folder with them (measured on the `dynamic` template, 2026-09-21).
     folderNodes: col.sendFolder === true ? (col.folder?.nodes ?? []) : [],
@@ -325,10 +336,10 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
         // Whose $uuid belongs on this wire document — see siteProjectToDocument.
         ...(opts.backend ? { backend: opts.backend } : {}),
         ...(opts.queryUuids ? { queryUuids: opts.queryUuids } : {}),
-        // ⛔ THE SAME ORG `buildRecordEntities` WAS GIVEN ABOVE. A query's `schema`
+        // ⛔ THE SAME SCOPE `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 } : {}),
+        // from one `@/x` by one rule (`./self-scope.js`) — so they take one scope.
+        scope,
         // 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