@uniweb/build 0.76.1 → 0.78.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.76.1",
+  "version": "0.78.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,15 +57,15 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/content-reader": "^1.2.8",
-    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/projections": "^0.7.14",
-    "@uniweb/schemas": "^0.12.0",
+    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/semantic-parser": "^1.5.1",
+    "@uniweb/content-reader": "^1.2.8",
+    "@uniweb/schemas": "^0.12.0",
     "@uniweb/theming": "^0.2.0"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.29.1"
+    "@uniweb/runtime": "^0.29.2"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,8 +74,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/runtime": "^0.29.1",
-    "@uniweb/core": "^0.37.1"
+    "@uniweb/core": "^0.37.2",
+    "@uniweb/runtime": "^0.29.2"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/content/index.js

@@ -19,7 +19,6 @@ export { collectSiteContent } from '../site/content-collector.js'
 export {
   processQueries,
   writeQueryFiles,
-  getQueryLastModified,
 } from '../site/query-processor.js'
 // Where a site's records live — `paths.records`, else `records/` — so a caller
 // holding its own config (a document's, not a `site.yml`) asks the one resolver.

package/src/dev/api-mount.js

@@ -4,20 +4,35 @@ import { pathToFileURL } from 'node:url'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 
+/**
+ * Where `uniweb dev` answers the site's `api` service when `$devApi` names a handler.
+ * The dev server is the host here, so the address is its own.
+ */
+export const DEV_API_ADDRESS = '/_api'
+
 /**
  * Mount a site's own request handler in the dev server.
  *
  * A site that talks to a backend needs one running to be developed against, and
  * making that a live deployment is slow, costs money, and puts a shared database
- * behind a developer's experiments. So a site may name a **local handler** and the
- * dev server mounts it at the site's own service address:
+ * behind a developer's experiments. So a site may name a **local handler**, and in
+ * `uniweb dev` the dev server answers the site's `api` service with it:
  *
  * ```yaml
  * # site.yml
- * api: /_api                 # where the site's app backend answers
- * devApi: ./mock/api.js      # what answers it, in development only
+ * services:
+ *   api: true                # ask your host for an app backend (in production)
+ * $devApi: ./mock/api.js     # what answers it in `uniweb dev`, at /_api
  * ```
  *
+ * ⭐ THE DEV SERVER SUPPLIES THE ADDRESS [Diego, 2026-10-06]. In `uniweb dev` it is
+ * the host, so where it answers is its own to choose — `DEV_API_ADDRESS` — and the
+ * plugin puts that address in the dev payload's `config.api`, the site tier
+ * `resolveService` reads when no host speaks. ⛔ *Until then the site wrote it, as a
+ * top-level `api: /_api` "the same in development and in production" — an address
+ * that, under `services:`, would read as "the site brings its own backend" and ask the
+ * host to turn its own off.*
+ *
  * ```js
  * // mock/api.js — default-export a fetch handler
  * export default (request) => new Response('{}', { headers: { 'content-type': 'application/json' } })
@@ -35,10 +50,9 @@ import { YAML_OPTIONS } from '../utils/yaml-schema.js'
  *
  * ## ⛔ Development only, and it cannot leak
  *
- * `devApi` is read by the dev plugin and by nothing else: no build reads it, no
- * `info` key carries it, and nothing writes it into a payload. A site's *address*
- * (`api:`) is authored config and travels; what answers that address locally is a
- * fact about one machine.
+ * `$devApi` is read by the dev plugin and by nothing else: no build reads it, no
+ * `info` key carries it, and only the dev server's payload names its address. What
+ * answers the site's `api` service locally is a fact about one machine.
  *
  * ⚠️ **Same-origin on purpose.** Mounting inside the dev server means cookies and
  * `credentials: 'same-origin'` behave as they do in production, where a site's app
@@ -59,7 +73,7 @@ import { YAML_OPTIONS } from '../utils/yaml-schema.js'
  * @param {import('vite').ViteDevServer} server
  * @param {object} options
  * @param {string} options.root - the site directory
- * @returns {boolean} whether a handler was mounted
+ * @returns {string|null} the address the handler answers on, or null when none was mounted
  */
 export function mountDevApi(server, { root }) {
   // ⛔ Read from the RAW site.yml, never from the collected `config`. `$`-prefixed
@@ -70,18 +84,12 @@ export function mountDevApi(server, { root }) {
   try {
     site = yaml.load(readFileSync(join(root, 'site.yml'), 'utf8'), YAML_OPTIONS) || {}
   } catch {
-    return false
+    return null
   }
 
   const spec = site.$devApi
-  if (!spec) return false
-
-  const declared = site.api
-  const mount = typeof declared === 'string' ? declared : declared?.endpoint
-  if (!mount) {
-    console.error("[dev-api] `$devApi` needs an `api:` address to answer on — add `api: /_api` to site.yml.")
-    return false
-  }
+  if (!spec) return null
+  const mount = DEV_API_ADDRESS
 
   // Loaded once, lazily, and awaited by the middleware. ⚠️ Loud and specific on
   // failure: a dev API that silently fails to load looks exactly like a backend
@@ -139,5 +147,5 @@ export function mountDevApi(server, { root }) {
   })
 
   console.log(`[dev-api] '${spec}' answering ${prefix}/*`)
-  return true
+  return mount
 }

package/src/site/content-collector.js

@@ -41,6 +41,7 @@ import { resolveDefaultLocale, resolvePublishableLocales, validateLanguageConfig
 import { authoredRedirectTarget } from '@uniweb/core/resolve-route'
 import { parseFrontmatter } from '../utils/frontmatter.js'
 import { parseGrid } from '@uniweb/schemas/grid'
+import { runtimeServicesConfig, refuseRetiredServiceKeys } from '../uwx/services-request.js'
 
 // Try to import content-reader, fall back to simplified parser
 let markdownToProseMirror
@@ -2437,6 +2438,60 @@ async function collectLayouts(layoutDir, siteRoot) {
  * @param {boolean} [options.strict=false] - Fail on content problems that would ship broken output rather than warning about them. A production build passes true; dev leaves it false, because a folder an author just created is empty for a moment and that is not an error.
  * @returns {Promise<Object>} Site content object with assets manifest
  */
+/**
+ * `site.yml` as a payload carries it — without what is authoring or publish intent,
+ * and without the backend-scoped `$` keys. One rule for every path that ships a
+ * site's config.
+ *
+ * `publishLanguages` is authoring/publish intent — it has no runtime consumer and
+ * never ships in a payload (the visitor runtime is list-unaware; the sync lane reads
+ * site.yml directly, not this output). The `query:` shorthand ships as
+ * `config.fetch`, desugared by the caller; carried raw it would sit beside
+ * `config.queries`, the declarations, and read as one.
+ *
+ * ⭐ `services` ships as each service's SITE TIER, `config.<name>`
+ * (`runtimeServicesConfig`), and never whole: at `config.services` it would be the HOST
+ * tier, where a present block declines every service it does not name, and its
+ * request half is not an answer. *(Until 2026-10-06 the whole block shipped there, and
+ * doubled as an undocumented way to simulate a host's offer locally; the site tier was
+ * the top-level `search:` / `submit:` / `assistant:` / `tracking:` / `api:` keys,
+ * refused now.)*
+ *
+ * ⛔ `$`-prefixed keys were the project's BACKEND-SCOPED state — `$uuid`, `$org`,
+ * `$backend`, `$services`, `$secrets` — until they moved to `sync.json` (2026-09-20),
+ * and a `site.yml` written before then can still carry them. This payload is a
+ * PUBLISHED artifact that a visitor can fetch. They have no runtime reader (nothing in
+ * core, runtime or kit reads a `config.$*` key), so this removes noise for four of
+ * them and a real disclosure for the fifth: `$secrets` carries no values, but its
+ * entries name every secret the site has, and an inventory of credential names is not
+ * something an `export` should publish.
+ *
+ * @param {object} siteConfig
+ * @returns {object}
+ */
+function payloadSiteConfig(siteConfig) {
+  const {
+    publishLanguages: _publishLanguages,
+    query: _query,
+    services,
+    ...runtimeSiteConfig
+  } = siteConfig
+  for (const key of Object.keys(runtimeSiteConfig)) {
+    if (key.startsWith('$')) delete runtimeSiteConfig[key]
+  }
+  // ⭐ Each service's SITE TIER, from its entry: `config.<name>` — the switch, an
+  // address the site brings, its options — never the request, and never a credential.
+  const warn = (m) => console.warn(`[site-content] ${m}`)
+  for (const [name, value] of Object.entries(runtimeServicesConfig(services, { warn }))) {
+    if (name in runtimeSiteConfig) {
+      warn(`\`services.${name}\` names a site.yml key that is not a service — ignoring it.`)
+      continue
+    }
+    runtimeSiteConfig[name] = value
+  }
+  return runtimeSiteConfig
+}
+
 export async function collectSiteContent(sitePath, options = {}) {
   const { foundationPath, configFile = 'site.yml', profile: profileName, dropUnpublished = false, base = '/', strict = false } = options
 
@@ -2447,6 +2502,7 @@ export async function collectSiteContent(sitePath, options = {}) {
 
   // Read site config and raw theme config
   const siteConfig = await readYamlFile(join(sitePath, configFile))
+  refuseRetiredServiceKeys(siteConfig, configFile)
 
   // Queries are declared in TWO files — `site.yml::queries` and `queries.yml`,
   // the latter winning per key — and resolving them is one question with one
@@ -2547,7 +2603,7 @@ export async function collectSiteContent(sitePath, options = {}) {
   // Check if pages directory exists
   if (!existsSync(pagesPath)) {
     return {
-      config: siteConfig,
+      config: payloadSiteConfig(siteConfig),
       theme: {
         ...processedTheme,
         css: themeCSS,
@@ -2725,23 +2781,7 @@ export async function collectSiteContent(sitePath, options = {}) {
     if (page.slug) delete page.slug
   }
 
-  // `publishLanguages` is authoring/publish intent — it has no runtime
-  // consumer and never ships in a payload (the visitor runtime is
-  // list-unaware; the sync lane reads site.yml directly, not this output).
-  // The `query:` shorthand ships as `config.fetch`, desugared below; carried raw
-  // it would sit beside `config.queries`, the declarations, and read as one.
-  const { publishLanguages: _publishLanguages, query: _query, ...runtimeSiteConfig } = siteConfig
-  // ⛔ `$`-prefixed keys were the project's BACKEND-SCOPED state — `$uuid`, `$org`,
-  // `$backend`, `$services`, `$secrets` — until they moved to `sync.json`
-  // (2026-09-20), and a `site.yml` written before then can still carry them. This
-  // payload is a PUBLISHED artifact that a visitor can fetch. They have no runtime reader (nothing in core, runtime
-  // or kit reads a `config.$*` key), so this removes noise for four of them and a
-  // real disclosure for the fifth: `$secrets` carries no values, but its entries
-  // name every secret the site has, and an inventory of credential names is not
-  // something an `export` should publish.
-  for (const key of Object.keys(runtimeSiteConfig)) {
-    if (key.startsWith('$')) delete runtimeSiteConfig[key]
-  }
+  const runtimeSiteConfig = payloadSiteConfig(siteConfig)
 
   // ⛔ **A BUILD does not ship a site whose config failed to parse.**
   // `strict` is already this codebase's word for it — `build-site-data.js` sets

package/src/site/data-fetcher.js

@@ -203,6 +203,24 @@ export function refuseUnder(where, context) {
   walk(where)
 }
 
+/**
+ * ⛔ `filter:` IS RETIRED (2026-10-06 [Diego]: "it should not be supported. We don't need to keep
+ * legacy concepts around") — refused on a query and on a fetch. It was the string predicate
+ * (`tags contains featured`) that `where:` replaced. A fetch has not read it since 2026-09-05; a
+ * query carried it into `config.queries` and applied it nowhere, so a query that said `filter:`
+ * delivered every record with nothing said (measured 2026-10-06).
+ *
+ * @param {Object|undefined} declaration - a query declaration or a binding
+ * @param {string} context - where it sits, for the message
+ */
+export function refuseFilter(declaration, context) {
+  if (!declaration || typeof declaration !== 'object' || declaration.filter === undefined) return
+  throw new Error(
+    `[uniweb] ${context}: \`filter:\` is retired. Write the predicate as \`where:\`, a where-object — ` +
+      `e.g. \`where: { tags: { contains: featured } }\`.`
+  )
+}
+
 /**
  * ⛔ A `where` OUTSIDE THE LANGUAGE STOPS THE BUILD — a retired operator (`like`,
  * `nin`), an unknown one, an empty `and` / `or`, a text operator with an empty
@@ -340,6 +358,7 @@ export function refuseBinding(fetch, context, { level = null } = {}) {
   if (typeof fetch !== 'object' || Array.isArray(fetch)) return
   refuseRefineAndMisplacedCurrent(fetch, context, level)
   refuseMerge(fetch, context)
+  refuseFilter(fetch, context)
   refuseSourceKeys(fetch, context)
   if (fetch.collection === undefined) refuseQueryName(fetch.query, context, { object: true })
   refuseUnder(fetch.where, context)

package/src/site/index.js

@@ -41,8 +41,7 @@ export {
 } from './advanced-processors.js'
 export {
   processQueries,
-  writeQueryFiles,
-  getQueryLastModified
+  writeQueryFiles
 } from './query-processor.js'
 export { collectSchemalessData, collectSchemalessDataAssets, rewriteSchemalessDataAssets } from './schemaless-data.js'
 export {

package/src/site/plugin.js

@@ -655,6 +655,18 @@ export function siteContentPlugin(options = {}) {
   }
 
   let siteContent = null
+  // Where `uniweb dev` answers the site's `api` service with `$devApi`'s handler — set
+  // in `configureServer`, so never in a build.
+  let devApiAddress = null
+  /**
+   * The dev payload names `$devApi`'s address as the site's `api` service: the site
+   * tier, which `resolveService` reads when no host speaks. A build never gets here
+   * with one.
+   */
+  const withDevApi = (content) => {
+    if (devApiAddress && content?.config) content.config.api = devApiAddress
+    return content
+  }
   // What each section type declares its data blocks are — read once per collection of the site.
   let dataModelPromise = null
   const dataModels = () => (dataModelPromise ||= dataBlockModels(resolvedSitePath).catch(() => NO_DATA_MODELS))
@@ -955,7 +967,7 @@ export function siteContentPlugin(options = {}) {
         // pages stay in the graph so in-progress drafts remain previewable.
         // strict on a production build: a mount that contributes no pages is a
         // warning while you author and a broken deploy once you ship.
-        siteContent = await collectForBundle(resolvedSitePath, { foundationPath, dropUnpublished: isProduction, base: basePath, strict: isProduction })
+        siteContent = withDevApi(await collectForBundle(resolvedSitePath, { foundationPath, dropUnpublished: isProduction, base: basePath, strict: isProduction }))
         dataModelPromise = null
         headHtml = await loadHeadHtml()
         console.log(`[site-content] Collected ${siteContent.pages?.length || 0} pages`)
@@ -998,13 +1010,14 @@ export function siteContentPlugin(options = {}) {
       server = devServer
 
       // A site's own backend, answered locally in development. `site.yml::$devApi`
-      // names a module that default-exports a fetch handler, mounted at the site's
-      // own `api:` address so the address is identical in dev and in production.
+      // names a module that default-exports a fetch handler; the dev server mounts it
+      // at an address of its own and names that address in the payload it serves
+      // (`withDevApi`), so the site's `api` service resolves to it.
       // ⚠️ Synchronous on purpose — see mountDevApi. An await here and the
       // middleware lands after Vite's SPA fallback, which answers the API with
       // index.html and says nothing about why.
       try {
-        mountDevApi(devServer, { root: resolvedSitePath })
+        devApiAddress = mountDevApi(devServer, { root: resolvedSitePath })
       } catch (err) {
         console.error(`[dev-api] ${err.message}`)
       }
@@ -1025,7 +1038,7 @@ export function siteContentPlugin(options = {}) {
             rebuildQueries = false
             console.log('[site-content] Content changed, rebuilding...')
             try {
-              siteContent = await collectForBundle(resolvedSitePath, { foundationPath, base: basePath })
+              siteContent = withDevApi(await collectForBundle(resolvedSitePath, { foundationPath, base: basePath }))
               dataModelPromise = null
               headHtml = await loadHeadHtml()
               if (materialize) {

package/src/site/queries-config.js

@@ -37,7 +37,7 @@ import { readRegisteredFoundation } from './registered-foundation.js'
 import { buildDataSchemaMap, SCHEMA_NOT_FOUND } from '../resolve-data-schema.js'
 import { resolveFoundationSrcPath } from '../utils/foundation-source-root.js'
 import { buildSchema } from '../schema.js'
-import { refuseQueryRoute, refuseLimit } from './data-fetcher.js'
+import { refuseQueryRoute, refuseLimit, refuseFilter } from './data-fetcher.js'
 import { readFile } from 'node:fs/promises'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
@@ -248,6 +248,7 @@ export function refuseQueryDeclaration(decl) {
   }
   refuseQueryRoute(decl, where)
   refuseLimit(decl.limit, where)
+  refuseFilter(decl, where)
   // ⛔ `sync:` IS RETIRED (2026-09-21). `sync: false` kept a query's records off a
   // backend while a query owned its records; every record in `records/` is pushed
   // now, whatever reads it, so an ignored `sync: false` would push exactly what the

package/src/site/query-processor.js

@@ -51,7 +51,7 @@
  * await writeQueryFiles(siteDir, byQuery)
  */
 
-import { readFile, readdir, stat, writeFile, mkdir, copyFile, rm } from 'node:fs/promises'
+import { readFile, readdir, writeFile, mkdir, copyFile, rm } from 'node:fs/promises'
 import { join, basename, extname, dirname, relative, resolve, sep, isAbsolute } from 'node:path'
 import { existsSync } from 'node:fs'
 import { createHash } from 'node:crypto'
@@ -59,7 +59,7 @@ import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { parseBibtex } from '@citestyle/bibtex'
 import { DATA_DIR, withoutRouteVariables, mapQueryPaths, BRANCH_KEY } from '@uniweb/core'
-import { applyWhere, applySort, refuseUnder, refuseOutsideLanguage, refuseQueryRoute, refuseLimit } from './data-fetcher.js'
+import { applyWhere, applySort, refuseUnder, refuseOutsideLanguage, refuseQueryRoute, refuseLimit, refuseFilter } from './data-fetcher.js'
 import { resolveAssetPath, walkContentAssets, isLocalAssetPath } from './assets.js'
 import { readEntityPool, groupPoolBySchema, poolDirsForSchema } from './entity-pool.js'
 import { readRecordsConfig, resolveFolder, folderTreeOrder } from './records-config.js'
@@ -126,7 +126,6 @@ function parseQueryConfig(name, config) {
       scope: null,
       sort: null,
       where: null,
-      filter: null,
       limit: 0,
       excerpt: { maxLength: 160 },
     }
@@ -136,6 +135,7 @@ function parseQueryConfig(name, config) {
   refuseOutsideLanguage(config.where, `queries.${name}`)
   refuseQueryRoute(config, `queries.${name}`)
   refuseLimit(config.limit, `queries.${name}`)
+  refuseFilter(config, `queries.${name}`)
   return {
     name,
     // The query's schema selects its records — `records/{schema}/` declares the
@@ -146,11 +146,8 @@ function parseQueryConfig(name, config) {
     // here until 2026-09-11: a named query's `scope` was ignored on this lane.
     scope: typeof config.scope === 'string' ? config.scope : null,
     sort: config.sort || null,
-    // `where:` is the CANONICAL predicate; `filter:` is the deprecated string DSL
-    // it replaced. Both are carried and both are applied below, in the same order
-    // `data-fetcher.js::applyPostProcessing` uses — see the note there.
+    // The predicate. ⛔ `filter:`, the string DSL it replaced, is refused above.
     where: config.where || null,
-    filter: config.filter || null,
     limit: config.limit || 0,
     excerpt: {
       maxLength: config.excerpt?.maxLength || 160,
@@ -1419,36 +1416,3 @@ export async function writeQueryFiles(siteDir, byQuery, queriesConfig = null) {
     }
   }
 }
-
-/**
- * Get last modified time for a collection
- *
- * @param {string} siteDir - Site root directory
- * @param {Object} config - Collection config
- * @returns {Promise<Date|null>} Most recent modification time
- */
-export async function getQueryLastModified(siteDir, config) {
-  const parsed = parseQueryConfig('temp', config)
-  const poolDir = join(siteDir, parsed.path)
-
-  if (!existsSync(poolDir)) {
-    return null
-  }
-
-  const files = await readdir(poolDir)
-  const itemFiles = files.filter(f =>
-    !f.startsWith('_') &&
-    (f.endsWith('.md') || f.endsWith('.yml') || f.endsWith('.yaml') || f.endsWith('.json') || f.endsWith('.bib'))
-  )
-
-  let lastModified = null
-
-  for (const file of itemFiles) {
-    const fileStat = await stat(join(poolDir, file))
-    if (!lastModified || fileStat.mtime > lastModified) {
-      lastModified = fileStat.mtime
-    }
-  }
-
-  return lastModified
-}

package/src/uwx/emit-surface.json

@@ -45,9 +45,6 @@
         "agents": [
           "site.yml::agents"
         ],
-        "assistant": [
-          "site.yml::assistant"
-        ],
         "base": [
           "site.yml::base"
         ],
@@ -89,28 +86,19 @@
         "publish_languages": [
           "site.yml::publishLanguages"
         ],
-        "search": [
-          "site.yml::search"
-        ],
         "seo": [
           "site.yml::seo"
         ],
-        "submit": [
-          "site.yml::submit"
-        ],
-        "theme": null,
-        "tracking": [
-          "site.yml::tracking"
-        ]
+        "theme": null
       }
     },
     "services": {
       "kind": "passthrough",
-      "authoredAs": "site.yml::$services"
+      "authoredAs": "site.yml::services"
     },
     "secrets": {
       "kind": "passthrough",
-      "authoredAs": "site.yml::$secrets"
+      "authoredAs": "sync.json::backends.<origin>.secrets"
     },
     "pages": {
       "kind": "records"

package/src/uwx/index.js

@@ -12,6 +12,8 @@
 
 export { mintUuidV7 } from './uuid.js'
 export { createZip, readZip } from './zip.js'
+// The queries whose records a site's pages show live — what `records` is for.
+export { recordQueriesShown } from './shown-records.js'
 export {
   sha256Hex,
   toJsonBuffer,
@@ -113,6 +115,16 @@ export {
   refForAssetId,
   normalizeOrigin as normalizeBackendOrigin,
 } from './sync-store.js'
+// A site's services request — `site.yml::services`, applied over the site's own rows.
+// Spec: kb/framework/reference/site-services-request.md
+export {
+  RUNTIME_KEYS,
+  readServicesRequest,
+  statedServices,
+  heldServices,
+  servicesFromDocument,
+  sameServiceRow,
+} from './services-request.js'
 export {
   diffSiteUnits,
   describeSiteDiff,
@@ -121,6 +133,7 @@ export {
   walkSiteUnits,
   collectUnitUuids,
   collectQueryUuids,
+  siteItemsByKey,
   stampUnitUuids,
 } from './site-diff.js'
 export {

package/src/uwx/project-writer.js

@@ -268,13 +268,17 @@ const isPlainObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArr
  * ⛔ The declaration keys (`query` / `fetch` / `data`) are written WHOLE, never
  * merged: a declaration is one value, and merging an incoming `fetch:` into the
  * local one kept whatever key the remote no longer has — a stale `limit` survived
- * every pull.
+ * every pull. So is `services`: it is the site's settled request, and a service
+ * merged in from the old map would be an ask nobody made.
  * @returns {'updated'|'unchanged'}
  */
 export function writeSiteConfig(siteRoot, config) {
-  return mergeYamlConfig(join(siteRoot, 'site.yml'), config, { replace: DECLARATION_KEYS })
+  return mergeYamlConfig(join(siteRoot, 'site.yml'), config, { replace: SITE_CONFIG_WHOLE })
 }
 
+/** `site.yml` keys a writer replaces whole rather than merging into. */
+const SITE_CONFIG_WHOLE = Object.freeze([...DECLARATION_KEYS, 'services'])
+
 /**
  * Write a YAML object to a file (full dump, idempotent) — for machine-owned
  * config the projector authors wholesale, e.g. a projected `page.yml`/`folder.yml`.