@uniweb/build 0.55.1 → 0.56.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.55.1",
+  "version": "0.56.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -58,9 +58,9 @@
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
     "@uniweb/schemas": "^0.3.3",
-    "@uniweb/content-reader": "^1.2.5",
-    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/projections": "^0.7.3",
+    "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/content-reader": "^1.2.5",
     "@uniweb/semantic-parser": "^1.4.1",
     "@uniweb/theming": "^0.1.15"
   },

package/src/site/deploy-config-writer.js

@@ -1,30 +1,36 @@
 /**
  * deploy.yml writer
  *
- * Updates the lastDeploy.<target> block of a site's deploy.yml without
+ * Updates the deploys.<target> block of a site's deploy.yml without
  * reformatting the rest of the file. Uses the eemeli/yaml Document API
  * because js-yaml does not preserve comments on round-trip — the writer
- * must not destroy a developer's comments on the targets:/autoSave:
+ * must not destroy a developer's comments on the targets:/saveDeploys:
  * regions of the file.
  *
  * This is the only place in @uniweb/build that depends on `yaml`. The
  * loader (deploy-config.js) stays on js-yaml for read-only ingestion.
  *
- * Auto-save semantics:
- *   - 'off'        : no-op (CI / `--no-save`)
- *   - 'lastDeploy' : touch ONLY lastDeploy.<targetName>
- *   - 'full'       : reserved; behaves as 'lastDeploy' for now
+ * `saveDeploys: false` (or `--no-save`) makes this a no-op; otherwise it
+ * touches ONLY deploys.<targetName> — plus targets.<targetName> when the file has no
+ * such target yet (a publish to a backend no target names). ⚠️ It was `autoSave: off|lastDeploy|full`
+ * until 2026-09-20, and `full` was reserved and behaved as `lastDeploy` — a
+ * boolean wearing a tri-state.
  *
  * First-deploy path: when deploy.yml does not exist, writes a fresh
  * file scaffolded with `default:`, a single entry under `targets:`, and
- * `autoSave: lastDeploy`. This is the only code path that writes the
+ * `saveDeploys: true`. This is the only code path that writes the
  * config region.
+ *
+ * And two removals, for `uniweb forget`: `forgetDeploys` drops the records one
+ * backend wrote and keeps every target; `forgetDeployYml` deletes the file, for a
+ * copy that is to become a new project.
  */
 
-import { readFile, writeFile } from 'node:fs/promises'
+import { readFile, writeFile, unlink } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { Document, parseDocument, isMap } from 'yaml'
+import { normalizeOrigin } from '../uwx/sync-store.js'
 
 // The header every generated deploy.yml carries. It has to answer the question
 // a reader has while looking AT the file — who wrote this, and may I edit it —
@@ -39,7 +45,7 @@ const SCAFFOLD_HEADER = [
   ' deploy.yml — written by `uniweb deploy` / `uniweb publish`.',
   '',
   ' You do not create this file. The first successful deploy does, recording the',
-  ' target you picked and what happened. Later deploys rewrite only `lastDeploy:`',
+  ' target you picked and what happened. Later deploys rewrite only `deploys:`',
   ' and leave the rest — including your comments — alone.',
   '',
   ' Safe to commit; no credentials live here. Host credentials come from the',
@@ -48,29 +54,34 @@ const SCAFFOLD_HEADER = [
   '   default:     which target is used when none is named',
   '   targets:     where this site ships. Edit to change the destination, or add',
   '                a target and pick it with `--target <name>`',
-  '   autoSave:    `lastDeploy` to keep the record below, `off` to stop writing it',
-  '   lastDeploy:  what the last deploy did. A record, not a setting — nothing',
-  '                reads it back, so a stale one is safe to delete',
+  '   deploys:     what each target\'s last deploy did. A record, not a setting.',
+  '                `publish` reads one field back — a fingerprint of the service',
+  '                request it last sent — so deleting it only means the next',
+  '                publish re-sends that request',
+  '   saveDeploys: false to stop recording deploys',
+  '',
+  ' Which site this is on each backend lives in sync.json, not here.',
 ].join('\n')
 
 /**
- * Update or create deploy.yml with a fresh lastDeploy.<target> entry.
+ * Update or create deploy.yml with a fresh deploys.<target> entry.
  *
  * @param {string} siteDir
  * @param {object} opts
  * @param {string} opts.targetName       e.g. 'production'
- * @param {object} [opts.targetConfig]   { host, ...host-specific }; only
- *                                       used on first-deploy scaffold.
+ * @param {object} [opts.targetConfig]   { host, ...host-specific }; the
+ *                                       first-deploy scaffold's target, and a
+ *                                       target to ADD when the file lacks it
  * @param {object} opts.lastDeploy       { at, url, foundation, runtime,
  *                                          artifactSha, ... }
- * @param {'off'|'lastDeploy'|'full'} opts.autoSave
+ * @param {boolean} opts.saveDeploys - false makes this a no-op
  * @returns {Promise<{ created: boolean, path: string } | null>}
- *          null when autoSave is 'off' (no-op).
+ *          null when saveDeploys is false (no-op).
  */
 export async function recordLastDeploy(siteDir, opts) {
-  const { targetName, targetConfig, lastDeploy, autoSave } = opts
+  const { targetName, targetConfig, lastDeploy, saveDeploys } = opts
 
-  if (autoSave === 'off') return null
+  if (saveDeploys === false) return null
 
   const path = join(siteDir, 'deploy.yml')
 
@@ -89,13 +100,29 @@ export async function recordLastDeploy(siteDir, opts) {
 
   const text = await readFile(path, 'utf8')
   const doc = parseDocument(text)
+  // Never rewrite a file we could not read — the caller reports it instead.
+  if (doc.errors.length) {
+    throw new Error(`deploy.yml did not parse: ${doc.errors[0].message.split('\n')[0]}`)
+  }
+
+  // A target the file does not have yet — a publish to a backend no target names
+  // (resolvePublishTarget) — is added beside the others. An existing target is never
+  // modified, and `default` / `saveDeploys` are never touched.
+  if (targetConfig?.host) {
+    const targetsNode = doc.get('targets', true)
+    if (!isMap(targetsNode)) {
+      if (targetsNode === undefined) doc.set('targets', { [targetName]: targetConfig })
+    } else if (!targetsNode.has(targetName)) {
+      targetsNode.set(targetName, targetConfig)
+    }
+  }
 
-  // Touch ONLY lastDeploy.<targetName>. Never reach into targets/default/autoSave.
-  let lastDeployNode = doc.get('lastDeploy', true)
-  if (!isMap(lastDeployNode)) {
-    doc.set('lastDeploy', { [targetName]: lastDeploy })
+  // Otherwise touch ONLY deploys.<targetName>.
+  let deploysNode = doc.get('deploys', true)
+  if (!isMap(deploysNode)) {
+    doc.set('deploys', { [targetName]: lastDeploy })
   } else {
-    lastDeployNode.set(targetName, lastDeploy)
+    deploysNode.set(targetName, lastDeploy)
   }
 
   await writeFile(path, doc.toString(), 'utf8')
@@ -106,8 +133,8 @@ function scaffold({ targetName, targetConfig, lastDeploy }) {
   const doc = new Document({
     default: targetName,
     targets: { [targetName]: targetConfig },
-    autoSave: 'lastDeploy',
-    lastDeploy: { [targetName]: lastDeploy },
+    deploys: { [targetName]: lastDeploy },
+    saveDeploys: true,
   })
   doc.commentBefore = SCAFFOLD_HEADER
   return doc
@@ -131,11 +158,11 @@ function scaffold({ targetName, targetConfig, lastDeploy }) {
  *
  * Behavior:
  *   - File missing: scaffold a fresh file with this target, set as
- *     default, autoSave: lastDeploy. No lastDeploy block (no deploy
+ *     default, saveDeploys: true. No deploys block (no deploy
  *     has happened yet).
  *   - File exists: merge targetConfig into targets.<targetName>
  *     (overlapping keys overwritten, other keys preserved). Never
- *     touches `default`, `autoSave`, `lastDeploy`, or other targets,
+ *     touches `default`, `saveDeploys`, `deploys`, or other targets,
  *     so adding a CI workflow to a project that already deploys
  *     elsewhere doesn't change its deploy semantics.
  */
@@ -155,7 +182,7 @@ export async function recordTarget(siteDir, opts) {
     const doc = new Document({
       default: targetName,
       targets: { [targetName]: targetConfig },
-      autoSave: 'lastDeploy',
+      saveDeploys: true,
     })
     doc.commentBefore = SCAFFOLD_HEADER
     await writeFile(path, doc.toString(), 'utf8')
@@ -187,3 +214,84 @@ export async function recordTarget(siteDir, opts) {
   await writeFile(path, doc.toString(), 'utf8')
   return { created: false, path, action: 'merge' }
 }
+
+/**
+ * Remove the deploy records one backend wrote — `uniweb forget --backend <url>`.
+ *
+ * A record belongs to the backend it names: every publish writes
+ * `deploys.<target>.backend`. A record naming none falls back to its target's
+ * `backend:`, which only a `host: uniweb` target has — so no other host's history
+ * can match, and a record that names no backend anywhere is left alone rather than
+ * guessed at.
+ *
+ * ⛔ **`targets:` stays.** A target is a CHOICE of where to ship, not something a
+ * backend told us — the spec's own line between this file and `sync.json`. After
+ * the forget, the next publish there simply creates a new site.
+ *
+ * Why the records go at all: each names the forgotten site (`siteUuid`, `url`), and
+ * its request fingerprint describes what was sent to THAT site. Kept, they would
+ * sit beside a target that now publishes somewhere else entirely.
+ *
+ * @param {string} siteDir
+ * @param {string} origin
+ * @returns {Promise<string[]>} the target names whose record was removed, sorted
+ * @throws when deploy.yml exists and does not parse — the caller decides whether
+ *   that blocks anything; this does not rewrite a file it could not read
+ */
+export async function forgetDeploys(siteDir, origin) {
+  const key = normalizeOrigin(origin)
+  const path = join(siteDir, 'deploy.yml')
+  if (!key || !existsSync(path)) return []
+
+  const doc = parseDocument(await readFile(path, 'utf8'))
+  if (doc.errors.length) {
+    throw new Error(`deploy.yml did not parse: ${doc.errors[0].message.split('\n')[0]}`)
+  }
+  const deploysNode = doc.get('deploys', true)
+  if (!isMap(deploysNode)) return []
+
+  const js = doc.toJS() || {}
+  const removed = []
+  for (const [name, record] of Object.entries(js.deploys || {})) {
+    const target = js.targets?.[name]
+    const named =
+      record?.backend ?? (target?.host === 'uniweb' ? target?.backend : undefined)
+    if (normalizeOrigin(named) === key) removed.push(name)
+  }
+  if (!removed.length) return []
+
+  for (const name of removed) deploysNode.delete(name)
+  // An empty `deploys: {}` says nothing and would be the only thing left of the
+  // backend in this file.
+  if (!deploysNode.items.length) doc.delete('deploys')
+  await writeFile(path, doc.toString(), 'utf8')
+  return removed.sort()
+}
+
+/**
+ * Delete deploy.yml outright — `uniweb forget --all`, for a copy that is to become a
+ * new project.
+ *
+ * ⭐ **The targets go too, not just the records** *[Diego, 2026-09-21: "if it's for
+ * duplicating a site project and making a new site from it, … the whole deploy.yml
+ * file has to be deleted"]*. They name the ORIGINAL's destinations — its Pages
+ * project, its bucket, its domain — so a deploy from the copy would overwrite the
+ * original there. The copy's first deploy writes a fresh file.
+ *
+ * @param {string} siteDir
+ * @returns {Promise<string[]|null>} the target names it held, or null when there
+ *   was no file. A file that does not parse is removed all the same and reports `[]`.
+ */
+export async function forgetDeployYml(siteDir) {
+  const path = join(siteDir, 'deploy.yml')
+  if (!existsSync(path)) return null
+  let names = []
+  try {
+    const doc = parseDocument(await readFile(path, 'utf8'))
+    if (!doc.errors.length) names = Object.keys(doc.toJS()?.targets || {}).sort()
+  } catch {
+    /* unreadable — still the original's, still removed */
+  }
+  await unlink(path)
+  return names
+}

package/src/site/deploy-config.js

@@ -5,14 +5,21 @@
  * by name. Read-only — never writes. See deploy-config-writer.js for
  * the write path.
  *
- * On-disk shape:
+ * On-disk shape (spec: kb/framework/reference/deploy-yml.md):
  *   default: production
  *   targets:
- *     production: { host, ...host-specific config }
+ *     production: { host, backend?, ...host-specific config }
  *     preview:    { host, ...host-specific config }
- *   autoSave: lastDeploy | off | full
- *   lastDeploy:
- *     production: { at, url, foundation, runtime, artifactSha, ... }
+ *   deploys:
+ *     production: { at, host, url?, git?, servicesRequest? }
+ *   saveDeploys: true
+ *
+ * ⚠️ `deploys` was `lastDeploy` and `saveDeploys` was `autoSave: off|lastDeploy|full`
+ * until 2026-09-20. `full` was "reserved; behaves as lastDeploy" — so the tri-state
+ * was already a boolean in practice, and the rename says so. `autoSave` also
+ * SOUNDED like it covered the whole file, which it never did.
+ *
+ * ⚠️ Nothing a backend minted lives here any more. Identity is `sync.json`'s.
  *
  * The CLI and the build pipeline both call resolveTarget() to turn a
  * loaded document + a (possibly null) --target flag into a concrete
@@ -26,9 +33,9 @@ import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
+import { normalizeOrigin } from '../uwx/sync-store.js'
 
 const DEFAULT_TARGET_NAME = 'production'
-const VALID_AUTOSAVE = new Set(['off', 'lastDeploy', 'full'])
 
 /**
  * Load and validate deploy.yml from `siteDir`. Returns null when the
@@ -57,7 +64,7 @@ export async function loadDeployYml(siteDir) {
  *   targetName: string,
  *   host: string,
  *   config: object,
- *   autoSave: 'off'|'lastDeploy'|'full',
+ *   saveDeploys: boolean,
  *   fromFile: boolean,
  * }}
  */
@@ -73,7 +80,7 @@ export function resolveTarget(deployYml, requestedTarget) {
       targetName: DEFAULT_TARGET_NAME,
       host: 'uniweb',
       config: {},
-      autoSave: 'lastDeploy',
+      saveDeploys: true,
       fromFile: false,
     }
   }
@@ -99,11 +106,73 @@ export function resolveTarget(deployYml, requestedTarget) {
     targetName: name,
     host,
     config,
-    autoSave: deployYml.autoSave || 'lastDeploy',
+    saveDeploys: deployYml.saveDeploys !== false,
     fromFile: true,
   }
 }
 
+/**
+ * The target a publish to `origin` records its deploy under.
+ *
+ * ⭐ **The target follows the backend, never the reverse.** A publish goes to ONE backend,
+ * decided before this runs — `--backend`, or the backend the user is logged in to
+ * *[Diego, 2026-09-21: "publish should publish to the backend the user logged in to"]*.
+ * The default target is only a tie-break, winning when it names that backend too.
+ *
+ *   1. no deploy.yml → the scaffold: `production`, naming `origin`
+ *   2. `host: uniweb` targets naming `origin` → the default one if it is among them,
+ *      else the first by name. A target with no `backend:` names `defaultBackend` —
+ *      its documented meaning
+ *   3. none → a NEW target, named after the backend's host (`uniweb.app`,
+ *      `localhost:8080`), `-2`, `-3`… if taken. The caller adds it when it persists.
+ *
+ * ⛔ Until 2026-09-21 publish always resolved the DEFAULT target, whatever backend it
+ * published to: a publish to a second backend recorded over the default target's deploy,
+ * and compared its service request against that target's fingerprint.
+ *
+ * @param {object|null} deployYml - from loadDeployYml
+ * @param {string} origin - the backend being published to
+ * @param {{ defaultBackend?: string }} [opts]
+ * @returns {{ targetName: string, host: 'uniweb', config: object, saveDeploys: boolean,
+ *   fromFile: boolean }} `fromFile: false` means the file has no such target yet
+ */
+export function resolvePublishTarget(deployYml, origin, { defaultBackend } = {}) {
+  const key = normalizeOrigin(origin)
+  if (!deployYml) {
+    return {
+      targetName: DEFAULT_TARGET_NAME,
+      host: 'uniweb',
+      config: { backend: key },
+      saveDeploys: true,
+      fromFile: false,
+    }
+  }
+  const saveDeploys = deployYml.saveDeploys !== false
+  const targets = deployYml.targets || {}
+  const naming = Object.keys(targets)
+    .filter((name) => {
+      const t = targets[name]
+      return t && t.host === 'uniweb' && normalizeOrigin(t.backend || defaultBackend) === key
+    })
+    .sort()
+  if (naming.length) {
+    const targetName = naming.includes(deployYml.default) ? deployYml.default : naming[0]
+    const { host, ...config } = targets[targetName]
+    return { targetName, host, config, saveDeploys, fromFile: true }
+  }
+  let base = 'uniweb'
+  try {
+    base = new URL(key).host || base
+  } catch {
+    /* keep the fallback */
+  }
+  let targetName = base
+  for (let i = 2; Object.prototype.hasOwnProperty.call(targets, targetName); i++) {
+    targetName = `${base}-${i}`
+  }
+  return { targetName, host: 'uniweb', config: { backend: key }, saveDeploys, fromFile: false }
+}
+
 function validate(doc, path) {
   if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) {
     throw new Error(`${path}: top level must be a map.`)
@@ -111,39 +180,19 @@ function validate(doc, path) {
   if (doc.targets !== undefined && (typeof doc.targets !== 'object' || Array.isArray(doc.targets))) {
     throw new Error(`${path}: \`targets\` must be a map.`)
   }
-  // A site has exactly ONE Uniweb identity — `site.yml::$uuid`, a single scalar,
-  // set by the create and never moved. So two targets naming `host: uniweb` cannot
-  // both be coherent: whichever one `default:` selects is the site, and the other
-  // silently describes a site that does not exist. The per-target `backend` key
-  // makes that look expressible, which is exactly why it is worth rejecting rather
-  // than leaving to be discovered.
-  //
-  // *(Diego, 2026-08-12: multiple deploys are not expected in general, and are not
-  // allowed for Uniweb Cloud specifically — the only host that reads `$uuid` at
-  // all. Every other host is stateless from the CLI's side, so any number of those
-  // targets is fine.)*
-  if (doc.targets && typeof doc.targets === 'object' && !Array.isArray(doc.targets)) {
-    const uniwebTargets = Object.entries(doc.targets)
-      .filter(([, t]) => t && typeof t === 'object' && t.host === 'uniweb')
-      .map(([name]) => name)
-    if (uniwebTargets.length > 1) {
-      throw new Error(
-        `${path}: only one target may use \`host: uniweb\` — found ${uniwebTargets.length} (${uniwebTargets.join(', ')}). ` +
-          'A site has a single Uniweb identity (site.yml::$uuid), so a second Uniweb target cannot describe a different site. ' +
-          'Keep one, or point the others at a third-party host.'
-      )
-    }
-  }
-  if (doc.autoSave !== undefined && !VALID_AUTOSAVE.has(doc.autoSave)) {
-    throw new Error(
-      `${path}: \`autoSave\` must be one of: ${[...VALID_AUTOSAVE].join(', ')}.`
-    )
+  // ⭐ SEVERAL `host: uniweb` TARGETS ARE LEGAL (2026-09-20). This rejected a second one
+  // because a site had a single identity, `site.yml::$uuid`, so two Uniweb targets
+  // could not both be coherent. Identity is keyed by backend origin in `sync.json`
+  // now: two targets naming DIFFERENT backends are two sites, and two naming the SAME
+  // backend are one site shipped twice. The reason is gone, so the rejection is too.
+  if (doc.saveDeploys !== undefined && typeof doc.saveDeploys !== 'boolean') {
+    throw new Error(`${path}: \`saveDeploys\` must be true or false.`)
   }
   if (doc.default !== undefined && typeof doc.default !== 'string') {
     throw new Error(`${path}: \`default\` must be a string.`)
   }
-  if (doc.lastDeploy !== undefined && (typeof doc.lastDeploy !== 'object' || Array.isArray(doc.lastDeploy))) {
-    throw new Error(`${path}: \`lastDeploy\` must be a map.`)
+  if (doc.deploys !== undefined && (typeof doc.deploys !== 'object' || Array.isArray(doc.deploys))) {
+    throw new Error(`${path}: \`deploys\` must be a map.`)
   }
   return doc
 }

package/src/site/index.js

@@ -50,5 +50,5 @@ export {
   applyPostProcessing,
   mergeDataIntoContent
 } from './data-fetcher.js'
-export { loadDeployYml, resolveTarget } from './deploy-config.js'
-export { recordLastDeploy, recordTarget } from './deploy-config-writer.js'
+export { loadDeployYml, resolveTarget, resolvePublishTarget } from './deploy-config.js'
+export { recordLastDeploy, recordTarget, forgetDeploys, forgetDeployYml } from './deploy-config-writer.js'

package/src/uwx/asset-map.js

@@ -1,156 +1,34 @@
 /**
- * `assets.json` — the site's committed map from a local asset path to the
- * backend's content-addressed id.
- *
- * ## Why it is COMMITTED, and why that is the whole point
- *
- * The same map used to be built on every push and thrown away
- * (`assetsByLocalUrl`, in memory, consumed by the content rewrite and dropped).
- * Rebuilt per push it is a private detail; committed it is a **log every machine
- * collaborating on this site can read**:
- *
- *   - a teammate who clones knows which bytes the project expects to exist and
- *     can fetch the ones they lack, instead of discovering a missing image at
- *     render;
- *   - `pull` can put an asset back at **the path its author wrote**, rather than
- *     inventing one — without this, a push turns `/images/hero.png` into an
- *     opaque id and nothing remembers it was ever called that;
- *   - a re-push of unchanged media is visibly a no-op rather than a silent one.
- *
- * ⇒ It is project state, not cache. `.uniweb/` is gitignored in both scaffolded
- * templates, which is why this does not live there.
- *
- * ## ⛔ Diff stability is a hard requirement, not tidiness
- *
- * A committed file that reorders itself produces a spurious diff on every push
- * and trains people to stop reading it — at which point a real change to what a
- * site ships passes unnoticed. Keys are therefore **sorted**, the shape is flat,
- * and the writer is a no-op when nothing changed (it does not rewrite an
- * identical file, so `git status` stays clean on a push that moved no assets).
- *
- * ## What it deliberately does NOT hold
- *
- * ⛔ **No serve URL.** A URL is a host's route layout, and storing one here would
- * re-create — in a committed file, on every machine — exactly the coupling that
- * deleting `buildAssetUrl` removed from this CLI. The id plus the host's
- * `config.assets.url` pattern is the whole address, and only the host owns the
- * second half.
- *
- * ⚖️ **What it holds instead is a FINGERPRINT of the served URL** (`served`), and the
- * difference is the point: a hash can recognize an address and cannot compose one.
- * It exists for references that are a BARE STRING — `info.preview`, `info.favicon`,
- * `seo.image`, a section param — where there is no object to stamp `assetId` beside,
- * so the stored value is the serve URL alone. `pull` hashes such a string and, when
- * it matches, puts back the path the author wrote. Should the host ever serve an
- * asset at a new address, the fingerprint simply stops matching and the pull leaves
- * the URL — the honest projection — until the next push records the new one.
- *
- * ⛔ **No mime or size.** The store validates those and they are its to change;
- * a second copy here is a second thing to disagree.
+ * Asset reference helpers — two pure functions, no file.
+ *
+ * ⚠️ **The MAP moved to `sync.json` on 2026-09-20** (`sync-store.js`,
+ * `backends.<origin>.assets`). It lived here as `assets.json`, a single flat
+ * `local path → id` file that assumed ONE backend — which is exactly what it
+ * could not represent once a project syncs with several: an id is minted by a
+ * backend and means nothing to any other one. `readAssetMap` / `updateAssetMap` /
+ * `refForAssetId` / `ASSET_MAP_FILE` went with it.
+ *
+ * What stays here is what never touched the filesystem:
+ *
+ * - **`servedFingerprint`** — hashes a serve URL. It exists for references that are
+ *   a BARE STRING (`info.preview`, `seo.image`, a section param), where there is no
+ *   object to stamp an id beside, so the stored value is the address alone. ⛔ A
+ *   fingerprint rather than the URL because a hash can RECOGNIZE an address and
+ *   cannot COMPOSE one — route layout is the host's and never ours to rebuild.
+ * - **`restoreAssetRefs`** — puts an author's own paths back into a document pulled
+ *   from a backend. Without it a push/pull cycle rewrites every image in a
+ *   developer's source to a backend route: a mangling of files they own, by a round
+ *   trip that changed nothing.
+ *
+ * ⭐ **`restoreAssetRefs` no-ops on an empty map**, which is what makes the store's
+ * `backend` parameter honest: a projection not tied to a backend has no known
+ * assets, so it restores nothing rather than guessing.
+ *
+ * @module
  */
 
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { createHash } from 'node:crypto'
 import { ASSET_SLOTS } from '@uniweb/semantic-parser'
-import { join } from 'node:path'
-
-export const ASSET_MAP_FILE = 'assets.json'
-
-/** Current on-disk shape. Bumped only for a breaking layout change. */
-const VERSION = 1
-
-const mapPath = (siteDir) => join(siteDir, ASSET_MAP_FILE)
-
-/**
- * Read the site's asset map. A missing, unreadable or malformed file reads as
- * empty rather than throwing: the map is an accelerator and a record, and a
- * corrupt one must never be the reason a push fails. The next write repairs it.
- *
- * @param {string} siteDir
- * @returns {Record<string, { id: string, ext: string }>} local ref → identity
- */
-export function readAssetMap(siteDir) {
-  const p = mapPath(siteDir)
-  if (!existsSync(p)) return {}
-  try {
-    const parsed = JSON.parse(readFileSync(p, 'utf8'))
-    const assets = parsed?.assets
-    if (!assets || typeof assets !== 'object') return {}
-    const out = {}
-    for (const [ref, v] of Object.entries(assets)) {
-      if (v && typeof v.id === 'string' && v.id) {
-        out[ref] = { id: v.id, ext: typeof v.ext === 'string' ? v.ext : '' }
-        if (typeof v.served === 'string' && v.served) out[ref].served = v.served
-      }
-    }
-    return out
-  } catch {
-    return {}
-  }
-}
-
-/**
- * Merge `entries` into the site's map and write it if anything changed.
- *
- * MERGE, not replace: a push carries only the refs that page's content touched,
- * so replacing would drop every asset this run happened not to mention — which
- * is most of them on a partial push. An entry whose id changed is overwritten
- * (the bytes at that path changed); an identical entry is left alone.
- *
- * @param {string} siteDir
- * @param {Record<string, { id: string, ext: string }>} entries
- * @returns {{ added: string[], changed: string[], written: boolean }}
- */
-export function updateAssetMap(siteDir, entries) {
-  const prior = readAssetMap(siteDir)
-  const added = []
-  const changed = []
-
-  for (const [ref, v] of Object.entries(entries || {})) {
-    if (!v?.id) continue
-    const was = prior[ref]
-    // A new `served` fingerprint is a change too: the host serves these bytes at
-    // another address now, and the old fingerprint would stop recognizing it. An
-    // entry that carries none — a download learns identity, not an upload's URL —
-    // keeps the one already recorded for the same bytes.
-    const served = v.served || (was && was.id === v.id ? was.served : undefined)
-    if (!was) added.push(ref)
-    else if (was.id !== v.id || (served || '') !== (was.served || '')) changed.push(ref)
-    else continue
-    prior[ref] = { id: v.id, ext: v.ext || '', ...(served ? { served } : {}) }
-  }
-
-  if (!added.length && !changed.length) return { added, changed, written: false }
-
-  // Sorted keys + a trailing newline: a committed file that reorders itself
-  // produces a diff on every push and teaches people to skip reading it.
-  const assets = {}
-  for (const ref of Object.keys(prior).sort()) assets[ref] = prior[ref]
-  writeFileSync(
-    mapPath(siteDir),
-    JSON.stringify({ version: VERSION, assets }, null, 2) + '\n'
-  )
-  return { added, changed, written: true }
-}
-
-/**
- * The local ref a given asset id is known at, or null.
- *
- * This is the direction `pull` needs and the reason the map is worth
- * committing: stored content carries an id, and only this can say the author
- * called it `/images/hero.png`. Without it a pull must invent a path.
- *
- * @param {Record<string, { id: string, ext: string }>} map
- * @param {string} id
- * @returns {string|null}
- */
-export function refForAssetId(map, id) {
-  if (!id) return null
-  for (const [ref, v] of Object.entries(map || {})) {
-    if (v.id === id) return ref
-  }
-  return null
-}
 
 /**
  * The fingerprint `assets.json` keeps of the URL a host serves an asset at.