@uniweb/build 0.47.2 → 0.48.0

package/src/site/data-fetcher.js

@@ -1,17 +1,16 @@
 /**
  * Data Fetcher Utilities
  *
- * Handles parsing fetch configurations and executing data fetches
- * from local files (public/) or remote URLs.
- *
- * Supports:
- * - Simple string paths: "/data/team.json"
- * - Full config objects with schema, prerender, merge, transform options
- * - Named-query references: { query: 'articles', limit: 3 }
- * - Local JSON/YAML files
- * - Remote URLs
- * - Transform paths to extract nested data
- * - Post-processing: limit, sort
+ * Parses an authored `fetch:` — a BINDING, which names a query — and executes a
+ * resolved config: a compiled `/data/<query>.json` under `public/`, or an external
+ * query's address.
+ *
+ * ⭐ A binding always names a query (ruled 2026-09-13 [Diego]): `fetch: team` and
+ * `fetch: [team]` mean `fetch: { query: team }` and `fetch: [{ query: team }]`.
+ * The query decides where its records live — the compiled file a static build
+ * generates, a host's live records, or an external API — so one declaration
+ * debugs locally against static data and reads live records once published,
+ * with nothing changed. ⛔ `/data/…` is that generated file, never authored.
  *
  * @module @uniweb/build/site/data-fetcher
  */
@@ -20,29 +19,7 @@ import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { existsSync } from 'node:fs'
 import yaml from 'js-yaml'
-import { matchWhere, sortRecords, queryDataUrl, applyScope } from '@uniweb/core'
-
-/**
- * Infer schema name from path or URL
- * Extracts filename without extension as the schema key
- *
- * @param {string} pathOrUrl - File path or URL
- * @returns {string} Schema name
- *
- * @example
- * inferSchemaFromPath('/data/team-members.json') // 'team-members'
- * inferSchemaFromPath('https://api.com/users')   // 'users'
- */
-function inferSchemaFromPath(pathOrUrl) {
-  if (!pathOrUrl) return 'data'
-
-  // Get the last path segment
-  const segment = pathOrUrl.split('/').pop()
-  // Remove query string
-  const filename = segment.split('?')[0]
-  // Remove extension
-  return filename.replace(/\.(json|yaml|yml)$/i, '')
-}
+import { matchWhere, sortRecords, queryDataUrl, applyScope, whereOutsideLanguage, CURRENT_MODES } from '@uniweb/core'
 
 /**
  * Get a nested value from an object using dot notation
@@ -150,17 +127,13 @@ export function applyPostProcessing(data, config) {
  * @returns {object|null} Normalized config or null if invalid
  *
  * @example
- * // Simple string
- * parseFetchConfig('/data/team.json')
- * // Returns: { path: '/data/team.json', schema: 'team', prerender: true, merge: false }
- *
- * // Full config
- * parseFetchConfig({ path: '/team', schema: 'person', prerender: false })
- * // Returns: { path: '/team', schema: 'person', prerender: false, merge: false }
+ * // A query name
+ * parseFetchConfig('team')
+ * // Returns: { query: 'team', path: '/data/team.json', as: 'team', merge: false }
  *
- * // Collection reference
- * parseFetchConfig({ query: 'articles', limit: 3, sort: 'date desc' })
- * // Returns: { path: '/data/articles.json', schema: 'articles', limit: 3, sort: 'date desc', ... }
+ * // A binding that adapts its query
+ * parseFetchConfig({ query: 'articles', as: 'latest', limit: 3, sort: 'date desc' })
+ * // Returns: { query: 'articles', path: '/data/articles.json', as: 'latest', limit: 3, sort: 'date desc', merge: false }
  */
 // ─── Unrecognized-key reporting ───────────────────────────────────────
 //
@@ -174,7 +147,6 @@ export function applyPostProcessing(data, config) {
 // not understand, but we can refuse to pretend it was never there. Reported
 // once per key name per process so a 200-record build does not print 200 lines.
 const RECOGNIZED_FETCH_KEYS = {
-  refine: new Set(['refine', 'detail', 'limit', 'sort', 'where']),
   // ⛔ `schema` IS NOT ON EITHER LIST, and its absence is the point. It was the
   // binding key until 2026-09-02 and stopped being READ on 2026-09-03 (`e4fe077`,
   // one name no alias) — but it was left on these lists, which exempted it from
@@ -182,17 +154,15 @@ const RECOGNIZED_FETCH_KEYS = {
   // dropped in the one way the author could not see: no warning, and a plausible
   // key inferred from the path in its place. It has its own message below, since
   // "unrecognized" understates a key that used to work.
-  // ⭐ `scope` is recognized since 2026-09-11, when a folder branch became `scope:`
-  // on both lanes and `where: { path: { under } }` was retired in its favour. It
-  // was dropped here as "unrecognized" until then, so a page could not narrow a
-  // query to a branch at all.
+  // ⛔ `scope` is not a binding key — it is the query's, and refused on a binding
+  // (`refuseBindingScope`, ruled 2026-09-13 [Diego]). It was recognized here from
+  // 2026-09-11 to 2026-09-13, and replaced the query's scope on the records service.
+  // ⛔ `path`, `url`, `method`, `body`, `transform` and `detail` are not binding keys
+  // either — a binding names a query, which supplies its source (`refuseBinding`).
+  // The source shape that took them (`{ path }`, `{ url }`) was retired on 2026-09-13.
   query: new Set([
-    'query', 'as', 'prerender', 'merge', 'transform',
-    'scope', 'where', 'limit', 'sort', 'detailPage',
-  ]),
-  source: new Set([
-    'path', 'url', 'as', 'prerender', 'merge', 'transform', 'detail',
-    'detailPage', 'scope', 'where', 'limit', 'sort',
+    'query', 'as', 'prerender', 'merge',
+    'where', 'limit', 'sort', 'current', 'detailPage',
   ]),
 }
 
@@ -226,6 +196,204 @@ export function refuseUnder(where, context) {
   walk(where)
 }
 
+/**
+ * ⛔ 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
+ * argument. Every lane answers such a where with no records (`@uniweb/core`'s
+ * `whereOutsideLanguage`), which on a page reads as "nothing matched"; an authoring
+ * error is said where the author wrote it instead. ⛔ `like` and `nin` worked in this
+ * evaluator until 2026-09-13, when it took the language ruled that day.
+ *
+ * @param {Object|undefined} where
+ * @param {string} context - where the declaration sits, for the message
+ */
+export function refuseOutsideLanguage(where, context) {
+  const problem = whereOutsideLanguage(where)
+  if (problem) throw new Error(`[uniweb] ${context}: ${problem}.`)
+}
+
+/**
+ * ⛔ `scope` ON A BINDING STOPS THE BUILD — ruled 2026-09-13 [Diego]: *"it belongs to
+ * the query."* Which branch of the folder a query reads decides what the query is;
+ * a binding reuses the query and adapts it with `where`, `sort` and `limit` only.
+ * Refused rather than ignored, because ignored it would read as a branch the page
+ * narrowed to while the query's whole scope arrived. Every lane reads the query's
+ * (`@uniweb/core/fetch-config`).
+ *
+ * @param {Object|undefined} fetch - one authored binding
+ * @param {string} context - where the declaration sits, for the message
+ */
+export function refuseBindingScope(fetch, context) {
+  if (!fetch || typeof fetch !== 'object' || Array.isArray(fetch)) return
+  if (fetch.scope === undefined || typeof fetch.query !== 'string') return
+  throw new Error(
+    `[uniweb] ${context}: \`scope\` is the query's, not a binding's. Put ` +
+      `\`scope: ${JSON.stringify(fetch.scope)}\` on the query \`${fetch.query}\` — or declare ` +
+      `another query with that scope — and narrow this binding with \`where\`, \`sort\` and \`limit\`.`
+  )
+}
+
+/**
+ * ⛔ `refine: true` IS RETIRED — ruled 2026-09-13 [Diego], for `current:`. It was a flag
+ * three methods consulted separately, and it did one thing: on a parametric page,
+ * `refine: true, detail: false` delivered the route query's records without the
+ * page's own. Its `sort` and `where` changed nothing. `inherit: true`, its earlier
+ * spelling, has been refused since 2026-09-02 and now names the same replacement.
+ *
+ * `current:` is validated here too: one of `only`, `exclude`, `include`, and only on
+ * a section's binding — how a page's record is used is a section's choice.
+ *
+ * @param {Object} fetch - one authored binding
+ * @param {string} context - where the declaration sits, for the message
+ * @param {'section'|'page'|'site'|null} level - the level it sits at, when known
+ */
+function refuseRefineAndMisplacedCurrent(fetch, context, level) {
+  const retired = fetch.refine !== undefined ? 'refine' : fetch.inherit !== undefined ? 'inherit' : null
+  if (retired) {
+    throw new Error(
+      `[uniweb] ${context}: \`${retired}: true\` is retired. Name the query, and say how this section uses ` +
+        `its page's record with \`current:\` — \`fetch: { query: <name>, current: exclude, limit: 3 }\` for ` +
+        `the others, \`current: include\` for all of them, \`current: only\` (the default) for the record.`
+    )
+  }
+  if (fetch.current === undefined) return
+  if (!CURRENT_MODES.includes(fetch.current)) {
+    throw new Error(
+      `[uniweb] ${context}: \`current: ${JSON.stringify(fetch.current)}\` — write \`only\`, \`exclude\` or \`include\`.`
+    )
+  }
+  if (level && level !== 'section') {
+    throw new Error(
+      `[uniweb] ${context}: \`current:\` is read on a section's binding, not on a ${level}'s — ` +
+        `each section of a parametric page says how it uses the page's record.`
+    )
+  }
+}
+
+/**
+ * ⭐ WHAT A BINDING MAY NOT SAY — every refusal, in one place, for the two readers
+ * of an authored binding: the build's parse (`parseFetchConfig`) and the sync push,
+ * which carries a page's declaration without parsing it (`uwx/site.js`). A site
+ * that cannot build must not sync either.
+ *
+ * @param {Object} fetch - one authored binding
+ * @param {string} context - where the declaration sits, for the message
+ * @param {Object} [options]
+ * @param {'section'|'page'|'site'|null} [options.level] - the level it sits at, when known
+ */
+export function refuseBinding(fetch, context, { level = null } = {}) {
+  if (fetch === null || fetch === undefined) return
+  if (typeof fetch === 'string') {
+    refuseQueryName(fetch, context)
+    return
+  }
+  if (typeof fetch !== 'object' || Array.isArray(fetch)) return
+  refuseRefineAndMisplacedCurrent(fetch, context, level)
+  refuseSourceKeys(fetch, context)
+  if (fetch.collection === undefined) refuseQueryName(fetch.query, context, { object: true })
+  refuseUnder(fetch.where, context)
+  refuseOutsideLanguage(fetch.where, context)
+  refuseBindingScope(fetch, context)
+}
+
+/**
+ * A binding's string, or the string it has for `query:` — is it a query name?
+ *
+ * ⛔ A NAME, NOT A PATH — ruled 2026-09-13 [Diego]: *"Referencing "/data" is never
+ * allowed."* `/data/<name>.json` is the file the build generates from a query for a
+ * site with no backend to answer it; naming the query is what lets the same page read
+ * that file locally and a host's live records once published. So a string with a
+ * slash, or a data file's extension, is refused rather than looked up as a name.
+ *
+ * @param {*} name
+ * @param {string} context
+ * @param {{ object?: boolean }} [options] - whether it came from `{ query: … }`
+ */
+function refuseQueryName(name, context, { object = false } = {}) {
+  if (typeof name === 'string' && name.trim() !== '' && !/[\\/]|\.(json|ya?ml)$/i.test(name)) return
+  if (typeof name === 'string' && name.trim() !== '') {
+    const guess = name.replace(/^.*[\\/]/, '').replace(/\.(json|ya?ml)$/i, '')
+    throw new Error(
+      `[uniweb] ${context}: ${object ? `\`query: ${JSON.stringify(name)}\`` : `\`fetch: ${JSON.stringify(name)}\``} — a fetch ` +
+        `names a query, and a query name is not a path. \`/data/…\` is the file the build generates from a query ` +
+        `for a site with no backend; declare the query in queries.yml and name it${guess ? ` — \`query: ${guess}\`` : ''}.`
+    )
+  }
+  throw new Error(
+    `[uniweb] ${context}: a fetch names a query — \`fetch: { query: <name>, … }\`, or the shorthand \`query: <name>\`. ` +
+      `Declare the query in queries.yml.`
+  )
+}
+
+/**
+ * ⛔ A BINDING HAS NO SOURCE OF ITS OWN — ruled 2026-09-13 [Diego]. `path:` is the
+ * generated file (above); `url:`, `method:`, `body:` and `transform:` describe an
+ * external source, which is a named query (*"Making the external source a named query
+ * is smart"*) — so every one a site uses is listed in one file; and `detail:` is
+ * `current:` on a parametric page's section, or `record:` on an external query.
+ *
+ * @param {Object} fetch - one authored binding
+ * @param {string} context
+ */
+function refuseSourceKeys(fetch, context) {
+  if (fetch.path !== undefined) {
+    throw new Error(
+      `[uniweb] ${context}: \`path:\` is not a fetch key — a fetch names a query, and \`/data/…\` is the file the ` +
+        `build generates from one for a site with no backend. ` +
+        (typeof fetch.query === 'string' ? 'Delete the `path:` line.' : 'Declare a query in queries.yml and write `query: <name>`.')
+    )
+  }
+  for (const key of ['url', 'method', 'body', 'transform']) {
+    if (fetch[key] === undefined) continue
+    throw new Error(
+      `[uniweb] ${context}: \`${key}:\` belongs on an external query, not on a fetch. Declare it in queries.yml — ` +
+        `\`<name>: { url: …${key === 'url' ? '' : `, ${key}: …`} }\` — and name it here with \`query: <name>\`.`
+    )
+  }
+  if (fetch.detail !== undefined) {
+    throw new Error(
+      `[uniweb] ${context}: \`detail:\` is retired. On a section of a parametric page, say how it uses the page's ` +
+        `record with \`current:\`; for an API's single-record endpoint, declare \`record: { url: … }\` on its external query.`
+    )
+  }
+}
+
+/**
+ * ⚠️ TWO BINDINGS UNDER ONE KEY AT ONE LEVEL — ruled 2026-09-13 [Diego]: *"Duplicates
+ * should not exist."* The first is used on every lane (`resolveFetchConfigs` keeps
+ * the first per key, and so does the build's prerender) and the rest are ignored;
+ * this says so once per key per file. Warned, not refused: the first binding still
+ * delivers what it says.
+ *
+ * @param {Array<Object>} list - one level's bindings, parsed or as authored
+ * @param {string} context - where the declaration sits, for the message
+ */
+const warnedDuplicateBindings = new Set()
+export function warnDuplicateBindings(list, context) {
+  if (!Array.isArray(list)) return
+  const seen = new Set()
+  for (const one of list) {
+    const key = one && typeof one === 'object' ? (one.as || one.query) : undefined
+    if (typeof key !== 'string' || !key) continue
+    if (!seen.has(key)) {
+      seen.add(key)
+      continue
+    }
+    const memo = `${context}::${key}`
+    if (warnedDuplicateBindings.has(memo)) continue
+    warnedDuplicateBindings.add(memo)
+    console.warn(
+      `[uniweb] ${context}: more than one binding delivers content.data.${key} — the first is used ` +
+        `and the rest are ignored. Give each binding its own \`as:\`.`
+    )
+  }
+}
+
+/** Test seam — reset the duplicate-binding memo so suites do not leak into each other. */
+export function _resetDuplicateBindingWarnings() {
+  warnedDuplicateBindings.clear()
+}
+
 // Keys that are neither recognized nor merely unknown: they USED to work, and a
 // generic "unrecognized key" line understates that. Each has a dedicated message
 // naming its replacement, so this table only has to keep the generic report from
@@ -297,70 +465,36 @@ export function toFetchList(fetch) {
  * already broken.)
  *
  * @param {string|Object|Array|null} fetch
+ * @param {string} [context='fetch'] - where the declaration sits (a file), for messages
+ * @param {Object} [options]
+ * @param {'section'|'page'|'site'|null} [options.level] - the level it sits at, when known
  * @returns {Object|Array<Object>|null}
  */
-export function parseFetchConfig(fetch) {
+export function parseFetchConfig(fetch, context = 'fetch', { level = null } = {}) {
   if (!fetch) return null
 
   if (Array.isArray(fetch)) {
-    const parsed = fetch.map((f) => parseFetchConfig(f)).filter(Boolean)
+    const parsed = fetch.map((f) => parseFetchConfig(f, context, { level })).filter(Boolean)
     // Flatten: a nested array is not a meaningful authoring shape, and letting
     // one through would put an array inside an array where every consumer
     // expects configs.
     const flat = parsed.flat()
     if (flat.length === 0) return null
+    warnDuplicateBindings(flat, context)
     return flat.length === 1 ? flat[0] : flat
   }
 
-  // Simple string: "/data/team.json"
+  // ⭐ A STRING IS A QUERY NAME — `fetch: team` ≡ `fetch: { query: team }`.
   if (typeof fetch === 'string') {
-    const inferred = inferSchemaFromPath(fetch)
-    return {
-      path: fetch,
-      url: undefined,
-      as: inferred,
-      prerender: true,
-      merge: false,
-      transform: undefined,
-    }
+    refuseBinding(fetch, context, { level })
+    return parseFetchConfig({ query: fetch }, context, { level })
   }
 
-  // Full config object
   if (typeof fetch !== 'object') return null
 
-  // ⛔ THE RETIRED ALIAS IS AN ERROR, NOT A WARNING — same reasoning as
-  // `collection:` below. `inherit: true` was the earlier spelling of
-  // `refine: true`, accepted with a warning from April 2026 and removed on
-  // 2026-09-02. Ignored, `{ inherit: true, limit: 3 }` would fall through to
-  // the source shape, find neither `path` nor `url`, and resolve to null — a
-  // silently empty block.
-  if (fetch.inherit !== undefined) {
-    throw new Error(
-      '[uniweb] fetch: `inherit: true` is retired. Write `refine: true` — the same ' +
-        'per-instance refinement of the ancestor fetch, under its current name.'
-    )
-  }
-  refuseUnder(fetch.where, 'fetch')
-
-  // Refine config: { refine: true, detail: false, limit: 3 }
-  // No URL — merges with the parent fetch config at runtime; only carries
-  // override props.
-  //
-  // Note on build-vs-runtime scope: this parser passes `sort`
-  // through on refine configs, but the runtime EntityStore only applies
-  // `detail`, `limit`, and `order` overrides. `sort` on a refine
-  // block are currently accepted by the parser but not honored at runtime.
-  // Preserved as-is in this rename commit; revisit separately if needed.
-  if (fetch.refine === true) {
-    warnUnknownFetchKeys(fetch, 'refine')
-    return {
-      refine: true,
-      ...(fetch.detail !== undefined ? { detail: fetch.detail } : {}),
-      ...(fetch.limit !== undefined ? { limit: fetch.limit } : {}),
-      ...(fetch.sort !== undefined ? { sort: fetch.sort } : {}),
-      ...(fetch.where !== undefined ? { where: fetch.where } : {}),
-    }
-  }
+  // ⛔ RETIRED SPELLINGS ARE ERRORS, NOT WARNINGS — ignored, a declaration falls
+  // through to a shape it is not and resolves to null: a silently empty block.
+  refuseBinding(fetch, context, { level })
 
   // ⛔ THE RETIRED SPELLING IS AN ERROR, NOT A WARNING. An unrecognized key is
   // warned about and IGNORED, so `fetch: { collection: X }` would fall through to
@@ -375,91 +509,52 @@ export function parseFetchConfig(fetch) {
     )
   }
 
-  // Named-query reference: { query: 'articles', limit: 3 }
-  if (fetch.query) {
-    warnUnknownFetchKeys(fetch, 'query')
-    warnSchemaRetired(fetch, fetch.as || fetch.query)
-    return {
-      // ⭐ **`query` IS EMITTED, and that is what makes the two producers agree.**
-      // The sync lane has always emitted it (`uwx/site.js`) and this one did not,
-      // for the same declaration — so `resolveQuerySource` fired on a published
-      // site and never on a `--link`-deployed one. Measured 2026-09-02 against a
-      // host offering the `records` service:
-      //
-      //   --link   endpoint undefined, path /data/articles.json   ← the STATIC file
-      //   publish  endpoint /_api/q/articles                       ← the live lane
-      //
-      // Same site, same declaration, two verbs, two data sources. Publishing to a
-      // platform that declares a live lane is supposed to READ from it — the
-      // compiled `/data/*.json` is the escape hatch for entities with no known
-      // data schema, which never sync, not a second way to serve the ones that do.
-      //
-      // ⚠️ Not in the cache key: `deriveCacheKey` hashes {path,url,endpoint,schema,
-      // transform}, so adding this moves no cached entry.
-      query: fetch.query,
-      path: queryDataUrl(fetch.query),
-      url: undefined,
-      // ⭐ **`as` is the BINDING KEY** — the `content.data.<key>` a component
-      // reads — defaulting to the query name. It was called `schema` until
-      // 2026-09-02, which collided with the MODEL REF of the same name on a
-      // `queries` declaration. ⛔ **The old spelling is NOT read here, by
-      // ruling (2026-09-03): one name, no alias.** A fetch authored as
-      // `schema: posts` binds to nothing and is re-authored, not translated.
-      as: fetch.as || fetch.query,
-      prerender: fetch.prerender ?? true,
-      merge: fetch.merge ?? false,
-      transform: fetch.transform,
-      // Query operators — a fetch's own override the named query's, per field
-      scope: fetch.scope,
-      where: fetch.where,
-      limit: fetch.limit,
-      sort: fetch.sort,
-      // Canonical detail page for a list card's href (page:<stable_id> ref;
-      // resolved to a route template + interpolated per record at runtime).
-      detailPage: fetch.detailPage,
-    }
-  }
-
-  warnUnknownFetchKeys(fetch, 'source')
-  const {
-    path,
-    url,
-    as,
-    prerender = url ? false : true,
-    merge = false,
-    transform,
-    detail,
-    detailPage,
-    // Query operators
-    scope,
-    where,
-    limit,
-    sort,
-  } = fetch
-
-  // Must have either path or url
-  if (!path && !url) return null
-
-  warnSchemaRetired(fetch, as ?? inferSchemaFromPath(path || url))
-
+  // A binding: { query: 'articles', limit: 3 }
+  warnUnknownFetchKeys(fetch, 'query')
+  warnSchemaRetired(fetch, fetch.as || fetch.query)
   return {
-    path,
-    url,
-    // ⛔ `schema` is NOT read here — by ruling (2026-09-03), the retired
-    // spelling has no alias anywhere, authored content included. A fetch that
-    // still says `schema:` gets the inferred key and is re-authored to `as:`.
-    as: as ?? inferSchemaFromPath(path || url),
-    prerender,
-    merge,
-    transform,
-    detail,
-    // Canonical detail page for a list card's href (page:<stable_id>).
-    detailPage,
-    // Query operators
-    scope,
-    where,
-    limit,
-    sort,
+    // ⭐ **`query` IS EMITTED, and that is what makes the two producers agree.**
+    // The sync lane has always emitted it (`uwx/site.js`) and this one did not,
+    // for the same declaration — so `resolveQuerySource` fired on a published
+    // site and never on a `--link`-deployed one. Measured 2026-09-02 against a
+    // host offering the `records` service:
+    //
+    //   --link   endpoint undefined, path /data/articles.json   ← the STATIC file
+    //   publish  endpoint /_api/q/articles                       ← the live lane
+    //
+    // Same site, same declaration, two verbs, two data sources. Publishing to a
+    // platform that declares a live lane is supposed to READ from it — the
+    // compiled `/data/*.json` is the escape hatch for entities with no known
+    // data schema, which never sync, not a second way to serve the ones that do.
+    //
+    // ⚠️ Not in the cache key: `deriveCacheKey` hashes {path,url,endpoint,schema,
+    // transform}, so adding this moves no cached entry.
+    query: fetch.query,
+    // The compiled file's address, for a consumer that cannot resolve the query —
+    // derived, never authored (`refuseSourceKeys`).
+    path: queryDataUrl(fetch.query),
+    // ⭐ **`as` is the BINDING KEY** — the `content.data.<key>` a component
+    // reads — defaulting to the query name. It was called `schema` until
+    // 2026-09-02, which collided with the MODEL REF of the same name on a
+    // `queries` declaration. ⛔ **The old spelling is NOT read here, by
+    // ruling (2026-09-03): one name, no alias.** A fetch authored as
+    // `schema: posts` binds to nothing and is re-authored, not translated.
+    as: fetch.as || fetch.query,
+    // ⚠️ Only when authored: its default depends on the query — a query over the
+    // site's records is prerendered, an external query is the browser's
+    // (`@uniweb/core/fetch-config`) — and the parser does not know which this is.
+    prerender: fetch.prerender,
+    merge: fetch.merge ?? false,
+    // A binding's adaptations of its query (`@uniweb/core/fetch-config`,
+    // `narrowQuery`): `where` joins the query's, `sort` and `limit` replace its.
+    where: fetch.where,
+    limit: fetch.limit,
+    sort: fetch.sort,
+    // How a section on a parametric page uses the page's record (`currentOf`).
+    current: fetch.current,
+    // Canonical detail page for a list card's href (page:<stable_id> ref;
+    // resolved to a route template + interpolated per record at runtime).
+    detailPage: fetch.detailPage,
   }
 }
 
@@ -598,7 +693,8 @@ export function stripBuildOnlyFetchKeys(siteContent) {
 /**
  * Execute a fetch operation
  *
- * @param {object} config - Normalized fetch config from parseFetchConfig
+ * @param {object} config - A resolved fetch config (`resolveFetchConfigs`): a compiled
+ *   `path`, or an external query's `url` with its `method`, `body` and `transform`
  * @param {object} options - Execution options
  * @param {string} options.siteRoot - Site root directory
  * @param {string} [options.publicDir='public'] - Public directory name
@@ -653,8 +749,18 @@ export async function executeFetch(config, options = {}) {
         }
       }
     } else if (url) {
-      // Remote URL
-      const response = await globalThis.fetch(url)
+      // An external query's address — a GET, or a POST with a JSON body, as the
+      // runtime's default fetcher sends it.
+      const post = typeof config.method === 'string' && config.method.toUpperCase() === 'POST'
+      const init = post
+        ? {
+            method: 'POST',
+            ...(config.body !== undefined && config.body !== null
+              ? { headers: { 'Content-Type': 'application/json' }, body: typeof config.body === 'string' ? config.body : JSON.stringify(config.body) }
+              : {}),
+          }
+        : undefined
+      const response = await globalThis.fetch(url, init)
       if (!response.ok) {
         throw new Error(`HTTP ${response.status}: ${response.statusText}`)
       }

package/src/site/fetch-shapes.js

@@ -1,11 +1,12 @@
 // What shape a `fetch:` declaration is, and what a PROJECTION may write back.
 //
-// ⛔ WHY THIS EXISTS. A `fetch:` declaration has three shapes, and the keys each one
-// accepts differ (`data-fetcher.js` RECOGNIZED_FETCH_KEYS):
+// ⛔ WHY THIS EXISTS. A `fetch:` declaration is a BINDING — it names a query — and
+// accepts `query · as · where · sort · limit · current · …`, NOT `path`/`url`
+// (`data-fetcher.js` RECOGNIZED_FETCH_KEYS). A string is a query name.
 //
-//   refine      refine · detail · limit · sort · where · filter
-//   query       query · schema · … — and NOT `path`/`url`
-//   source      path · url · schema · …
+// (The source shape — `{ path }`, `{ url }` — and `refine: true` were retired on
+// 2026-09-13; the build refuses both. `source` below classifies what a store may
+// still hold from before, so a pull passes it through rather than guessing.)
 
 //
 // The build RESOLVES a `query:` shorthand into a concrete location, so the
@@ -36,10 +37,9 @@
 // a `query` are recoverable from the query itself; anything else survives and the
 // validator's warning stays the honest signal.
 
-/** Which of the three shapes a declaration is — the same order `data-fetcher` uses. */
+/** Which shape a declaration is — the same order `data-fetcher` uses. */
 export function fetchShapeOf(fetch) {
   if (!fetch || typeof fetch !== 'object') return null
-  if (fetch.refine === true) return 'refine'
   if (fetch.query) return 'query'
   return 'source'
 }
@@ -47,7 +47,6 @@ export function fetchShapeOf(fetch) {
 /** Keys a shape derives rather than the author writing them. */
 const DERIVED_BY_SHAPE = {
   query: ['path', 'url'],
-  refine: [],
   source: []
 }
 
@@ -95,8 +94,10 @@ export const DECLARATION_KEYS = Object.freeze(['query', 'fetch', 'data'])
  */
 export function queryNamesOf(fetch) {
   const nameOf = (one) => {
+    if (typeof one === 'string' && one !== '') return one
     if (!one || typeof one !== 'object' || typeof one.query !== 'string' || one.query === '') return null
     for (const [key, value] of Object.entries(one)) {
+      if (value === undefined) continue
       if (key === 'query' || key === 'path' || key === 'url') continue
       if (key === 'as' && value === one.query) continue
       if (key === 'prerender' && value === true) continue