@uniweb/build 0.76.1 → 0.78.0

package/src/uwx/site-project.js

@@ -36,6 +36,7 @@ import { foldOpenGraph } from './open-graph.js'
 import { join, relative, extname, basename, dirname } from 'node:path'
 import { restoreAssetRefs } from './asset-map.js'
 import { readBackendState, updateBackendState } from './sync-store.js'
+import { servicesFromDocument, heldServices } from './services-request.js'
 import { readFileSync, existsSync, unlinkSync, renameSync, rmSync, readdirSync, statSync, mkdirSync } from 'node:fs'
 import { isMarkdownFile, isIgnoredFolder } from '../utils/content-files.js'
 import { createHash } from 'node:crypto'
@@ -123,33 +124,15 @@ const INFO_TO_SITE_YML = {
   // Publish intent — verbatim both ways, dangling codes included (they carry
   // the preserved publish intent of a temporarily-undeclared language).
   favicon: 'favicon',
-  // Safe to project back because nothing STAMPS it: `submit` is authored-only,
-  // so a pull can never launder a deploy-derived value into authored config the
-  // way a key carried by both would. A host-supplied destination is resolved at
-  // render time and never enters `info`.
-  // Authored-only, like `submit` above — a host's assistant endpoint is offered
-  // through `config.services` and resolved at render time, so it never enters
-  // `info` and a pull cannot launder it into authored config.
-  //
-  // ⚠️ Credential-shaped keys are STRIPPED ON PUSH (`stripCredentials`), so the
-  // backend never stores one and it cannot come back. What that does to the
-  // author's file depends on which direction they are pulling into, and the two
-  // differ — ⛔ this comment asserted the wrong one until it was run:
-  //
-  //   - `pull` over an EXISTING site.yml — the local `apiKey` SURVIVES.
-  //     `mergeYamlConfig` spreads one level (`{...existing[key], ...value}`), so
-  //     the projected `{endpoint, …}` merges over the local block and nothing
-  //     removes a key the document does not carry.
-  //   - `clone` into a fresh directory — no local block exists, so the file is
-  //     written from the document alone and has no `apiKey`.
-  //
-  // Both are correct: a pull does not silently delete something the author
-  // typed, and the push already warned them. The security property is upheld at
-  // the push, not by the pull. Measured end-to-end against a live uniwebd —
-  // every unit test passed before and after, so only a real push touched it.
-  // Authored-only, like `submit` and `assistant`: a host's tracking endpoint is
-  // offered through `config.services.tracking` and resolved at render, so it
-  // never enters `info` and a pull cannot launder it into authored config.
+  // ⛔ `submit` / `assistant` / `tracking` are not `info` keys: they left it for the
+  // `settings` Section on 2026-09-09, and on 2026-10-06 left that for each service's
+  // row — a pull writes `site.yml::services` from the rows (`servicesFromDocument`).
+  // Two behaviours measured while they were here still hold, now in
+  // `keepCredentials`: a credential is stripped on push and a pull over an existing
+  // file keeps the author's (a `clone` into a fresh directory has none to keep) — a
+  // pull does not silently delete what the author typed, and the push already warned
+  // them; and a host's endpoint never enters the record, so a pull cannot launder it
+  // into authored config.
   // ⛔ The site's declaration is not verbatim — see the explicit `settings.fetch`
   // branch below: it projects to `site.yml::query` or `site.yml::fetch`.
   template: 'template',
@@ -199,14 +182,12 @@ const SETTINGS_TO_SITE_YML = {
   paths: 'paths',
   seo: 'seo',
   layout: 'layout',
-  // Authored-only service declarations: nothing STAMPS them, so a pull cannot
-  // launder a host-supplied endpoint into authored config. A host's own address is
+  // ⛔ `search` / `submit` / `assistant` / `tracking` are not here: each service rides
+  // its row in the `services` Section, whole, and a pull writes it into
+  // `site.yml::services` (`servicesFromDocument`, below). They were top-level keys
+  // until 2026-10-06 and `settings` keys until that evening. A host's own address is
   // offered through `config.services` and resolved at render, never entering the
-  // stored record.
-  search: 'search',
-  submit: 'submit',
-  assistant: 'assistant',
-  tracking: 'tracking',
+  // stored record, so a pull cannot launder it into authored config.
   agents: 'agents',
 }
 
@@ -309,36 +290,36 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
     : []
   if (extensions.length > 0) siteChanges.extensions = extensions
 
-  // services[] / secrets[] → sync.json::backends.<origin>.{services,secrets}.
-  //
-  // ⭐ The `$` prefix, and not the bare name, for the reason spelled out in
-  // `uwx/site.js`: `site.yml::services` already means "pretend a host offers these"
-  // on the bundle lane, and one key cannot mean two things.
+  // services → site.yml::services, one entry per service; which services this copy
+  // now holds → sync.json.
   //
-  // ⭐ `$id` is DROPPED — it is derived (a service's `name`; a secret's
-  // `service:name` pair), so writing it back would put a redundant handle in the
-  // author's file and invite them to edit the one field that must not drift from
-  // the fields it is derived from. Same call as `extensions` above.
+  // ⭐ `site.yml` TAKES WHAT WAS DECIDED [Diego, 2026-10-06: "pull writes it"]. Each
+  // entry is its row in the `services` Section — the whole entry in its `config`
+  // (`servicesFromDocument`) — except an off service with no settings, written only
+  // where the file already names it [Diego, 2026-10-07]. The map is written whole,
+  // keeping only the credentials an author typed, which a push never sends; a document
+  // with no Section writes nothing. The retired top-level keys go, so a pulled file
+  // builds.
   //
-  // ⛔ Everything else rides VERBATIM, `config` included: it is opaque, per-service
-  // and will grow, so projecting a known subset would quietly drop whatever the
-  // service gained since this line was written — and the next push would then send
-  // the truncated version back as authoritative.
-  //
-  // ⚠️ An EMPTY section is written as an empty list, not skipped. `[]` is a real
-  // state — "this site has no service rows" — and it is the state a `pull` must be
-  // able to deliver after the last one was removed. Skipping would leave a stale
-  // `$services` on disk that the next push would resurrect.
-  // ⭐ To `sync.json`, under the backend that provisioned them — not `site.yml`.
-  // A service is bought on one backend, so its rows describe that backend alone.
-  // ⛔ Needs a backend: with none there is nowhere coherent to file them, and
-  // writing them to a shared place is exactly the single-copy bug this removed.
+  // ⭐ `sync.json` takes, under this backend, the services this copy now HOLDS —
+  // `{ name: $uuid }`, every row the site has, written to the file or not
+  // (`heldServices`). A push states each one the file does not list as off, so the site
+  // keeps what it has. `secrets` is an inventory of names whose values are set in the
+  // app, `$id` dropped. ⛔ *Until 2026-10-07 `services` held the rows themselves, the
+  // record a push compared the file against, with `servicesNamed` beside it.*
+  // ⛔ What is held needs a backend: with none there is nowhere coherent to file it.
+  if (Array.isArray(document?.services)) {
+    siteChanges.services = servicesFromDocument({
+      rows: document.services,
+      local: readAuthoredYaml(join(siteRoot, 'site.yml'))?.services
+    })
+    for (const retired of ['search', 'submit', 'assistant', 'tracking', 'api']) siteChanges[retired] = null
+  }
   if (backend) {
     const provisioned = {}
-    for (const section of ['services', 'secrets']) {
-      const records = document?.[section]
-      if (!Array.isArray(records)) continue
-      provisioned[section] = records.map(({ $id: _id, ...fields }) => fields)
+    if (Array.isArray(document?.services)) provisioned.services = heldServices({ written: document.services })
+    if (Array.isArray(document?.secrets)) {
+      provisioned.secrets = document.secrets.map(({ $id: _id, ...fields }) => fields)
     }
     if (Object.keys(provisioned).length) {
       updateBackendState(siteRoot, backend, provisioned)

package/src/uwx/site.js

@@ -80,6 +80,11 @@ import { resolveLocaleList } from '../i18n/locales.js'
 import { translationContext, SITE_META_CONTEXT } from '../i18n/extract.js'
 import { splitOpenGraph, openGraphValue, seoBesideOpenGraph } from './open-graph.js'
 import { updateBackendState, readBackendState } from './sync-store.js'
+import {
+  readServicesRequest,
+  statedServices,
+  refuseRetiredServiceKeys
+} from './services-request.js'
 import { upsertYamlScalar } from './yaml-upsert.js'
 import { resolveQueriesConfig } from './queries-config.js'
 import { resolveSelfScope, siteSelfScope, refuseOrgOption } from './self-scope.js'
@@ -102,46 +107,6 @@ function scalarString(value) {
   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
-// other.
-const CREDENTIAL_KEYS = ['apiKey', 'api_key', 'key', 'token', 'secret']
-
-/**
- * Drop credential-shaped keys out of an authored service block.
- *
- * An authored block crosses into backend storage here and is served from there
- * in a published payload — which is world-readable. So a credential in
- * `site.yml` is not merely untidy, it is disclosed. The host's secret store is
- * the only right home, resolved at request time.
- *
- * Warns rather than throwing: the fix belongs to the author, a failed push
- * helps nobody, and the block is still useful without the key. Returns the
- * value untouched when there is nothing to strip, so `setIf`'s absent-vs-empty
- * behaviour is unchanged — a block that carried ONLY a credential arrives as
- * `{}` rather than vanishing, keeping the mistake visible where the author
- * looks for it.
- *
- * @param {*} block - the authored value, any shape
- * @param {string} label - the site.yml key, for the warning
- * @returns {*} the block, minus anything credential-shaped
- */
-function stripCredentials(block, label) {
-  if (!block || typeof block !== 'object' || Array.isArray(block)) return block
-  const found = CREDENTIAL_KEYS.filter(key => key in block)
-  if (found.length === 0) return block
-
-  console.warn(
-    `uwx/site: dropped ${found.join(', ')} from \`${label}:\` — authored config is published ` +
-      'world-readable, so a credential belongs in the host secret store, never in site.yml.'
-  )
-
-  const cleaned = { ...block }
-  for (const key of found) delete cleaned[key]
-  return cleaned
-}
-
 // page_sections and layout_sections share this content shape.
 // processMarkdownFile takes only type/hidden/props/fetch/query/data/id out of the
 // frontmatter (and drops preset/input), so `background:` and `theme:` stay
@@ -1037,8 +1002,8 @@ const DECL_NOT_ON_WIRE = new Set([
   // passed unknown keys through blindly and would have sent `route` from every site
   // that declared one.
   'route',
-  // Legacy predicate, translated to the canonical `where` upstream. No legacy
-  // fields on the wire.
+  // ⛔ RETIRED 2026-10-06 — the build refuses it (`refuseQueryDeclaration`), so it is never sent.
+  // ⚠️ This said it was "translated to the canonical `where` upstream"; nothing translated it.
   'filter',
   // ⛔ RETIRED 2026-09-27 — the build refuses it (`refuseQueryDeclaration`), so it is never sent.
   'deferred',
@@ -1088,8 +1053,6 @@ function queriesNested(declarations, uuids = null, scope = null, keyTyped = null
     // → `siteContent.queryFields`), since one that does not refuses a push carrying it.
     if (typed && Array.isArray(queryFields) && queryFields.includes('typed_by_data_key')) data.typed_by_data_key = true
     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.
     setIf(data, 'where', d.where)
     setIf(data, 'limit', d.limit)
     setIf(data, 'excerpt', d.excerpt)
@@ -1129,48 +1092,33 @@ function queriesNested(declarations, uuids = null, scope = null, keyTyped = null
   return out
 }
 
-// ── `services` + `secrets` — a site's own service records ─────────────────────
-//
-// ⚠️ THESE WERE `site.yml::$services` / `$secrets` UNTIL 2026-09-20. They now live in
-// `sync.json::backends.<origin>.{services,secrets}`, because what a site is PROVISIONED
-// with is a fact about one backend — a service is bought on the backend that sold it.
-// The `$` prefix existed to keep them off `site.yml::services`, which means something
-// else on the bundle lane (the HOST tier); out of `site.yml` entirely, that collision
-// is gone too.
+// ── `services` + `secrets` — what a site asks of its host ─────────────────────────
 //
-// The original note, kept because it explains why the names could not simply be reused: `site.yml::services` is ALREADY TAKEN,
-// on the other lane: the bundle lane spreads site.yml whole into the payload, so a
-// `services:` block there lands at `config.services` — the HOST tier — which is the
-// documented way to simulate a host locally (`kit/src/utils/submitTarget.js`).
-// Reusing the name would give one key two meanings that differ per lane, which is
-// the shape of bug nobody finds.
+// ⭐ THE `services` SECTION IS THE OWNER'S REQUEST, AUTHORED IN `site.yml::services` — a
+// map from service name to `true`, `false` or the service's settings (spec:
+// kb/framework/reference/site-services-request.md). A push STATES: every service the
+// file lists, as it says it, and OFF for every service this copy holds that the file no
+// longer lists (`statedServices`). The services it holds are named in that backend's
+// entry in `sync.json`, `{ name: $uuid }`, written by pull and by a push that succeeded;
+// one it never saw is not sent, and the site keeps it. The backend decides per service
+// from the versions the push sends [Diego, 2026-10-07 — kb/framework/plans/services-exchange.md].
+// ⛔ *Until then the Section went as a FULL LIST — the site's rows, read just before the
+// push, with the file's changed asks applied — because the backend replaced the Section
+// with what it was sent; and from 2026-09-20 to 2026-10-06 the rows lived only in
+// `sync.json`, which left a CLI user nowhere to ask.*
 //
-// `$` already means "backend-scoped, round-tripped, not hand-authored" in this file
-// (`$uuid`, `$org`, `$backend`), and that is exactly what these are: a service's
-// config is bound where the service is provisioned, and arrives here by `pull`.
+// `secrets` stays in `sync.json`: an inventory of names a pull writes, whose values are
+// set in the app — `#ref` marks one as set.
 //
 // ⚖️ WHAT THESE ARE NOT. A site's OWN service declarations — `search:`, `submit:`,
 // `assistant:`, `tracking:` — ride the `settings` Section and are untouched here.
-// (They were top-level `info.*` keys until 2026-09-09; `settingsNested` below is
-// where they are now written.) Those
-// are authored, they resolve at the SITE tier (`config.<name>`, first choice in
-// `@uniweb/core`'s `resolveService`), and moving them here would flip them to the
-// host tier, where a block's mere presence declines every service it does not name.
-// These Sections carry the services a site is PROVISIONED with — `api` above all,
-// which has no file-authored form because it is bought, not declared.
-//
-// ⛔ 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` 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.)*
+// Those are authored addresses and land at the SITE tier, `config.<name>`, which
+// `@uniweb/core`'s `resolveService` reads for any service the host does not offer.
+// A row here is read by the service's owner and reaches neither tier, so an address
+// filed here would reach no page.
 //
-// ⚠️ 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.
+// The Section is emitted only when there is something to state: a file that lists no
+// service, on a copy that holds none, sends no `services`.
 
 /**
  * A backend's provisioned `services` / `secrets` (its `sync.json` entry) → Section
@@ -1223,14 +1171,33 @@ function serviceRecords(declared, identify, label) {
 }
 
 /** One service per `name` — the same keyspace `config.services` uses at runtime. */
-function servicesNested(provisioned) {
+function servicesNested(rows) {
   return serviceRecords(
-    provisioned?.services,
+    rows,
     (e) => (typeof e.name === 'string' && e.name ? e.name : null),
-    '$services'
+    'services'
   )
 }
 
+/**
+ * The `services` Section for this push — the file's services, and the held ones it no
+ * longer lists stated off (`statedServices`) — or undefined when there is nothing to state.
+ *
+ * @param {object} siteYml
+ * @param {object|null} provisioned - the backend's entry in `sync.json`; its `services`
+ *   is `{ <name>: <$uuid> }`, the services this copy holds
+ * @returns {object[]|undefined}
+ */
+function requestedServices(siteYml, provisioned) {
+  const held = provisioned?.services
+  const rows = statedServices(
+    readServicesRequest(siteYml.services),
+    held && typeof held === 'object' && !Array.isArray(held) ? held : {}
+  )
+  // `$uuid` rides beside the payload-local `$id`, as on a query's row.
+  return rows.length ? servicesNested(rows) : undefined
+}
+
 /**
  * One secret per `(service, name)` — the pair the backend merges on. A site-level
  * secret belongs to no service, so `service` is optional and the handle degrades to
@@ -1342,17 +1309,11 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
   // carries the translation collector with it.
   setIf(settings, 'keywords', localizeScalarList(siteYml.keywords, sourceLocale, translations))
 
-  // Authored service declarations. ⛔ These must NOT be filed with the `$services`
-  // Section: authored ones resolve at the SITE tier (`config.<name>`, first choice
-  // in `@uniweb/core`'s `resolveService`) while `$services` is the HOST tier, where
-  // a block's mere PRESENCE declines every service it does not name
-  // (`core/src/services.js`). Moving them there would invert their precedence and
-  // turn a site's own search off with no error and no message.
-  setIf(settings, 'search', siteYml.search)
-  setIf(settings, 'submit', siteYml.submit)
-  // ⛔ Credentials are stripped, not trusted — this block is published world-readable.
-  setIf(settings, 'assistant', stripCredentials(siteYml.assistant, 'assistant'))
-  setIf(settings, 'tracking', stripCredentials(siteYml.tracking, 'tracking'))
+  // ⛔ NO SERVICE IS HERE. A service's address and options ride its row in the
+  // `services` Section, whole (`requestedServices`) [Diego, 2026-10-06: "If it's on and
+  // has configuration, it can all be in the same place"]. *Until that evening
+  // `settings.search` / `.submit` / `.assistant` / `.tracking` carried them beside the
+  // row, and until that morning they were top-level `site.yml` keys.*
 
   // Projections opt-out + route exclusions. Carried because the app is a second
   // PUBLISHER of projections and derives them from stored content: without this it
@@ -1410,6 +1371,7 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
 export async function siteProjectToDocument(siteRoot, opts = {}) {
   refuseOrgOption(opts, 'uwx/site')
   const siteYml = await readYamlFile(join(siteRoot, 'site.yml'))
+  refuseRetiredServiceKeys(siteYml)
   const sourceLocale = opts.sourceLocale || resolveDefaultLocale(siteYml)
   if (!siteYml.name) {
     throw new Error('uwx/site: site.yml::name is required')
@@ -1498,67 +1460,29 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // and default keywords exist for any share/SSR/crawler. `seo` rides verbatim
   // as authored config (round-trips like favicon); `keywords` is a localized
   // list (like page keywords).
-  // `submit` — where this site's forms send submissions. Same family as
-  // `fetcher`/`search`: the site declares it, the runtime reads it, and it
-  // round-trips verbatim. It has to be listed HERE because this lane is an
-  // explicit allowlist while the bundle lane spreads all of site.yml — without
-  // the line a `submit:` block works on a static host and vanishes silently on
-  // the synced lane, which is the worst shape a config bug can take.
   // `agents` — the projections opt-out + route exclusions. Carried because the
   // app is a second PUBLISHER of projections and derives them from stored
   // content: without this block it cannot see `agents: false` or
   // `agents.exclude`, so an author's opt-out is silently reversed and an
   // excluded branch becomes both discoverable AND summarized by the index.
   // (The CLI lane reads site.yml directly and honors it either way.)
-  // `assistant` — the site's own declaration for an AI assistant: where it
-  // lives (`endpoint`, read by kit's `resolveService`) plus authored settings a
-  // host reads (`system` persona, model hints). Same family as
-  // `search`/`submit`, and here for the reason spelled out above them — the
-  // bundle lane spreads all of site.yml while this one is an allowlist, so
-  // without this line the block works on a static host and vanishes silently
-  // on the synced lane.
   //
-  // ⚠️ That is not hypothetical: this replaces `intelligence.yml`, a SEPARATE
-  // file, which needed a bespoke line in each lane and got one in only the
-  // bundle lane — so an authored persona never reached a hosted site at all.
-  // A key inside site.yml cannot repeat that, because only this lane needs a
-  // line.
+  // The services — `site.yml::services` — ride the `services` Section: one row per
+  // entry, the whole entry in its `config` (`requestedServices`). ⚠️ An entry must
+  // reach this lane whole because the bundle lane spreads it into the payload, and a
+  // block that works on a static host and vanishes on the synced lane is the worst
+  // shape a config bug can take — `intelligence.yml`, a separate file the assistant's
+  // persona once lived in, reached only the bundle lane, so a persona never reached a
+  // hosted site. ⛔ A credential is dropped (`readServicesRequest`) — but only as a
+  // KEYED FIELD: one embedded in an endpoint URL (`https://collector/e?key=…`) is
+  // invisible there and is disclosed. The host's secret store is the only right home.
   //
-  // ⛔ Credentials are stripped, not trusted — see `stripCredentials`.
-  // `tracking` — where this site's usage events go (`endpoint`, read by the
-  // runtime through `resolveService`, plus `consent:`). Same family as
-  // `search`/`submit`/`assistant` and here for the same reason: the bundle lane
-  // spreads all of site.yml while this one is an allowlist, so without this line
-  // an authored `tracking:` works on a static host and vanishes silently on the
-  // synced lane.
-  //
-  // ⛔ Credentials stripped like `assistant`. A collector that wants a write key
-  // is a real shape, and this block is published world-readable — but note the
-  // strip only reaches a KEYED FIELD: a key embedded in the endpoint URL itself
-  // (`https://collector/e?key=…`) is invisible here and is disclosed. The host's
-  // secret store is the only right home either way.
-
-  // ⛔ `api` IS DELIBERATELY NOT HERE, and this note exists because every comment
-  // above it argues the opposite — three services are on this allowlist precisely so
-  // an authored block cannot work on a static host and vanish on the synced one.
-  // Without this paragraph the next reader adds the missing fourth line and calls it
-  // a bug fix.
-  //
-  // ⭐ `api` is the one service a site does not AUTHOR. It is a real backend that is
-  // provisioned, so its address is the host's to supply — it arrives as
-  // `config.services.api` and `@uniweb/api` reads it there (`resolveBase`). An
-  // authored `api:` is the SITE tier: it yields to a host that offers the service,
-  // and is the answer wherever one does not.
-  //
-  // ⇒ Carrying it would turn a local-dev address into a production one the moment
-  // someone pushed: the host would store `settings.api` and serve it back as
-  // `config.api`, and a site with no `api` service of its own would draw sign-in
-  // against an address nobody answers — where the absence would have drawn
-  // nothing. The vanish on this lane is the correct behaviour, not the bug the
-  // comments above describe — there, a dropped block leaves a site with NO
-  // endpoint; here it leaves the site with the RIGHT answer.
-  //
-  // The provisioned record rides the `$services` section instead (see servicesNested).
+  // ⛔ `api`'S ADDRESS IS THE HOST'S TO SUPPLY — `config.services.api`, read by
+  // `@uniweb/api` (`resolveBase`). Asking for it is `services: { api: true }`, or a map
+  // of the host's settings; an address of the site's own asks the host to leave its own
+  // off, and `readServicesRequest` says so, because `api: /_api` — where a local mock
+  // used to answer — reads that way. In `uniweb dev`, `$devApi` supplies the mock's
+  // address (`dev/api-mount.js`).
   // ⛔ THE CONFIGURATION KEYS ARE NOT HERE — they ride the `settings` Section
   // (`settingsNested` above). `info` is the BRIEF: what a card or a select dropdown
   // renders, plus what a listing can filter on. Eighteen keys moved off it on
@@ -1722,33 +1646,14 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
     opts.queryFields,
     Array.isArray(opts.schemaless) ? new Set(opts.schemaless) : null
   )
-  // 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.
-  //
-  // ⭐ AND ONLY WHEN THE CALLER SAYS THE DECLARATION IS A REQUEST.
-  // `opts.declareServices === false` withholds both Sections for THIS push, which
-  // is not the same as the file having no key — the file still declares one; the
-  // caller has determined the owner is not asking for anything new by it.
-  //
-  // ⛔ Why this decision cannot live here: the Sections are REPLACED wholesale by
-  // what we send (`SectionScope::DeclaredOnly`), so re-sending an unchanged block
-  // OVERWRITES whatever the stored request has become since — including a decision
-  // the owner made in the app, where the consent workflow's publish happens. But
-  // "has it changed since we last agreed?" needs the last agreed state, which is
-  // project memory (`deploy.yml`) the CLI owns and this pure mapper must not read.
-  // ⇒ The CLI decides; this honours the decision.
-  //
-  // ⚖️ Default is to declare, so every existing caller is unchanged and the
-  // withholding is opt-in.
-  const declare = opts.declareServices !== false
-  // ⭐ Provisioned per backend — a service is bought on the backend that sold it,
-  // so which rows exist is a question about ONE backend. They were `site.yml::$services`
-  // / `$secrets`, a single copy that could only ever describe one.
+  // Emitted only when there is something to state — see the header above
+  // `serviceRecords`. ⭐ What this copy holds is per backend — a service is bought on
+  // the backend that sold it — and the request is one, in `site.yml`. Push, publish,
+  // `status` and a pull's re-bank all build it alike, from the file and `sync.json`.
   const provisioned = opts.backend ? readBackendState(siteRoot, opts.backend) : null
-  const services = declare ? servicesNested(provisioned) : undefined
+  const services = requestedServices(siteYml, provisioned)
   if (services) doc.services = services
-  const secrets = declare ? secretsNested(provisioned) : undefined
+  const secrets = secretsNested(provisioned)
   if (secrets) doc.secrets = secrets
   return doc
 }

package/src/uwx/sync-package.js

@@ -28,6 +28,7 @@ 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 { recordQueriesShown } from './shown-records.js'
 import { isLocalAssetPath } from '../site/assets.js'
 
 const SITE_MODEL_NAME = '@uniweb/site-content'
@@ -42,17 +43,28 @@ const cacheKey = (entity) => `${entity.model} ${entity.id}`
 // uuid→version map (the sync-cache); an entity the map doesn't know is left
 // unconditional rather than guessed at. See entity-document.js for what the
 // token means on the wire.
-const withBaseVersion = (baseVersions, itemBaseVersions) => (entity) => {
+const withBaseVersion = (baseVersions, itemBaseVersions, { every = false } = {}) => (entity) => {
   const uuid = entity?.document?.$uuid
   const v = uuid ? baseVersions[uuid] : null
-  // Per-item preconditions, narrowed to the records THIS package actually carries.
-  // The cache spans the whole site, but a package holds only what changed; sending
-  // tokens for absent records would bloat the manifest and assert preconditions on
-  // items we are not touching.
+  // Per-item preconditions.
+  //
+  // ⭐ THE SITE-CONTENT ENTITY SENDS EVERY VERSION THIS COPY HOLDS (`every`), for items
+  // present AND for items the files dropped. A push deletes only the items it holds a
+  // version for, and only while the site left them unchanged — so a dropped item's
+  // version is what makes leaving it out a deletion, and without it the item is kept
+  // [Diego, 2026-10-07; backend's gate, kb/framework/plans/services-exchange.md]. The
+  // caller holds a version only for an item it has seen (`heldTokens`, cli), so none is
+  // ever sent for an item the backend holds and this copy does not.
+  // ⛔ Until then this narrowed to the units the document carried: a dropped page was
+  // deleted by today's rule anyway, and nothing else was sent a version.
+  //
+  // Any other entity: narrowed to the units it carries, as before — the records lane
+  // is gated by its entity version, and sends none.
   let items = null
   if (itemBaseVersions && Object.keys(itemBaseVersions).length) {
     items = {}
-    for (const itemUuid of Object.values(collectUnitUuids(entity.document))) {
+    const uuids = every ? Object.keys(itemBaseVersions) : Object.values(collectUnitUuids(entity.document))
+    for (const itemUuid of uuids) {
       const t = itemBaseVersions[itemUuid]
       if (t) items[itemUuid] = t
     }
@@ -223,11 +235,12 @@ function rewriteEntityAssets(node, map, ids, noStamp = null) {
  *        identity of its list items, as a previous push or pull banked it
  *        (`record-items.js`); stamped onto each record the backend holds, so a re-sent
  *        record updates its items instead of replacing them.
- * @param {Object<string,string>} [opts.itemBaseVersions] - record `$uuid` → opaque
- *        per-ITEM `version`. Narrowed at emit to the records the package carries and
- *        sent as `entries[].item_base_versions`, so the backend can refuse only the
- *        records that genuinely moved instead of the whole document. Omit to push
- *        those records unconditionally.
+ * @param {Object<string,string>} [opts.itemBaseVersions] - item `$uuid` → opaque
+ *        per-ITEM `version`, for every site-content item this copy has seen. Sent
+ *        whole on the site-content entity as `entries[].item_base_versions` — items
+ *        present and items the files dropped — so the backend refuses only the items
+ *        that genuinely moved, and deletes only what this copy saw (`withBaseVersion`).
+ *        Omit to push unconditionally.
  * @param {Object<string,string>} [opts.baseVersions] - backend-uuid → opaque
  *        `version` token, the push gate's optimistic-concurrency precondition.
  *        Each sent entity whose `$uuid` the map knows carries it as a top-level
@@ -290,6 +303,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   const priorHashes = opts.priorHashes || {}
   const sendAll = !!opts.sendAll
   const stamp = withBaseVersion(opts.baseVersions || {}, opts.itemBaseVersions || {})
+  const stampSite = withBaseVersion(opts.baseVersions || {}, opts.itemBaseVersions || {}, { every: true })
   const exporter = opts.exporter
   const exportedAt = opts.exportedAt
   refuseOrgOption(opts, 'emitSyncPackages')
@@ -374,12 +388,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
         // and the page and `settings` keys that carry Open Graph texts per language.
         ...(Array.isArray(opts.queryFields) ? { queryFields: opts.queryFields } : {}),
         ...(Array.isArray(opts.pageFields) ? { pageFields: opts.pageFields } : {}),
-        ...(Array.isArray(opts.settingsFields) ? { settingsFields: opts.settingsFields } : {}),
-        // 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
-        // memory the CLI owns. See site.js at `declareServices`.
-        ...(opts.declareServices === false ? { declareServices: false } : {})
+        ...(Array.isArray(opts.settingsFields) ? { settingsFields: opts.settingsFields } : {})
       })
     : null
   // Deploy-derived `info` fields are stamped here — NOT authored in site.yml, so they
@@ -581,7 +590,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   // --- site-content lane -------------------------------------------------------
   let siteContent = null
   if (siteEntity && changed(siteEntity)) {
-    siteContent = { ...emitLane([stamp(siteEntity)], exporter, exportedAt), index: [{ kind: 'site' }] }
+    siteContent = { ...emitLane([stampSite(siteEntity)], exporter, exportedAt), index: [{ kind: 'site' }] }
   }
 
   // The site's current uuid (from site.yml): the verb keys the folder push route on
@@ -633,5 +642,8 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     // records this package SENDS that the backend holds with list items and no bank entry
     // (their uuids) — sent as they are, the backend refuses each one (`identity_required`).
     recordItemIdentity,
+    // The queries whose records the site's pages show live — what the `records` service
+    // delivers on a published site (`shown-records.js`). Whether it changed or not.
+    recordsShown: siteDoc ? recordQueriesShown(siteDoc) : [],
   }
 }