@mosetta/build 0.0.0-stage → 0.0.9

package/src/release.mjs

@@ -0,0 +1,516 @@
+// THE RELEASE of a built distribution into a code store — the rules every publisher runs: the
+// direct `mosetta deploy` against a provider registry, and the platform's API on behalf of a
+// person. Portable (no node): a store is anything with `get(key) → Response` and
+// `put(key, body, meta) → Response` that honours the write conditions (`ifMatch`, `ifNoneMatch`) —
+// a provider handle, or a capability stub an isolate was granted.
+//
+// What a release keeps true:
+// - a deployed version never changes: a module whose id is there with other bytes is refused, and
+//   its version has to go up;
+// - the catalogs grow — every version deployed stays named, so pages naming an older one keep
+//   rendering;
+// - the artifacts land before the catalogs that name them, the private catalog last (its new ETag
+//   tells the runner the new generation is complete);
+// - two releases into one store at once both land or one is refused: every catalog is written
+//   over exactly the copy the plan was made from (`If-Match`), and a module file only where none is
+//   (`If-None-Match: *`).
+
+export const CATALOG_KEY = 'modules.json';
+export const PREFABS_PREFIX = 'prefabs/';
+// Artifact names are version-qualified and a deployed version never takes new bytes — yet the
+// stores still hold artifacts from the time 0.0.1 was re-deployed in place, and the shell pins
+// every artifact by SRI. Public objects keep a SHORT cache life until those are gone; the edge
+// revalidates by ETag after it.
+export const PUBLIC_CACHE_CONTROL = 'public, max-age=300';
+// The catalogs name the integrity of every artifact: a stale copy makes pages pin bytes that are
+// no longer there, so they are always revalidated.
+export const CATALOG_CACHE_CONTROL = 'no-cache';
+/** how many times a release starts over when another one wrote a catalog under it */
+const ATTEMPTS = 3;
+const CONCURRENCY = 8;
+
+const CONTENT_TYPES = {
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+  '.wasm': 'application/wasm',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/markdown; charset=utf-8',
+};
+
+/** the content type a file is stored with, by its extension */
+export function contentTypeOf(key) {
+  const dot = key.lastIndexOf('.');
+  const ext = dot > key.lastIndexOf('/') ? key.slice(dot).toLowerCase() : '';
+  return CONTENT_TYPES[ext] ?? 'application/octet-stream';
+}
+
+/**
+ * THE RELEASE PLAN: what the store's catalog already holds against what this build brings. A
+ * deployed version is immutable — a module (or a package built from the distribution's own
+ * sources) whose id is there with other bytes is a CONFLICT: the release is refused before anything
+ * is uploaded, and the version has to go up. A published package (react) may come out of another
+ * build tool with other bytes under the same version: its first deployed copy STAYS. The same bytes
+ * are nothing to do. New ids are uploaded, and the catalog grows by them — the versions already
+ * deployed stay in it, so pages that name them keep rendering.
+ *
+ * @param existing the store's catalog entities ([] for a store never deployed to)
+ * @param built this build's catalog entities
+ * @returns { catalog, fresh: Set<id>, same: id[], kept: id[], conflicts: { id, release }[] }
+ */
+export function releasePlan(existing, built) {
+  const held = new Map(existing.map((entity) => [entity.id, entity]));
+  const fingerprint = (entity) => entity.integrity ?? stableJson(entity);
+  const fresh = new Set();
+  const same = [];
+  const kept = [];
+  const conflicts = [];
+  for (const entity of built) {
+    const there = held.get(entity.id);
+    if (!there) {
+      fresh.add(entity.id);
+      held.set(entity.id, entity);
+    } else if (fingerprint(there) === fingerprint(entity)) {
+      same.push(entity.id);
+    } else if (entity.reference?.type === 'package' && !entity.local) {
+      kept.push(entity.id);
+    } else {
+      conflicts.push({ id: entity.id, release: releaseOf(entity) });
+    }
+  }
+  return { catalog: [...held.values()], fresh, same, kept, conflicts };
+}
+
+/** a framework package's id in code — its version is the page's business (aligned at run time) */
+const FRAMEWORK_DEPENDENCY_RE = /(_ns_package_t_package_n_a_mosetta_[A-Za-z0-9_.-]*?)_v_[0-9_]+/g;
+
+/**
+ * A module's code with the versions of the FRAMEWORK packages it names left out: a page runs one
+ * copy of each framework package, the newest its blocks need (the server aligns them), so a block
+ * rebuilt only because a new framework came out is the same block — not a new version of it.
+ */
+export function frameworkFreeShape(code) {
+  return String(code).replace(FRAMEWORK_DEPENDENCY_RE, '$1_v_*');
+}
+
+/**
+ * The conflicts that are only a rebuild for a new framework: the code the store holds and the code
+ * built differ in nothing but the framework's versions. Those modules stay as deployed — moved from
+ * `conflicts` to `rebuilt`; the catalog keeps naming the deployed bytes.
+ * @param readStored (id) → the deployed module's code, or null
+ * @param readBuilt (id) → this build's code, or null
+ */
+export async function settleRebuilds(plan, readStored, readBuilt) {
+  const conflicts = [];
+  const rebuilt = [];
+  for (const conflict of plan.conflicts) {
+    const [stored, built] = await Promise.all([readStored(conflict.id), readBuilt(conflict.id)]);
+    if (stored !== null && built !== null && frameworkFreeShape(stored) === frameworkFreeShape(built)) rebuilt.push(conflict.id);
+    else conflicts.push(conflict);
+  }
+  return { ...plan, conflicts, rebuilt };
+}
+
+/** what a version bump is asked of: a distribution (`mosetta-ui@0.0.1`) or a package of its own */
+function releaseOf(entity) {
+  const ref = entity.reference ?? {};
+  return ref.type === 'package' ? `package ${ref.specifier}@${ref.version}` : `${ref.namespace}@${ref.version}`;
+}
+
+/** JSON with sorted keys — two descriptors with the same fields compare equal */
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/** the refusal, said once per release that has to go up — with the command that raises it */
+export function conflictMessage(conflicts, storeLabel) {
+  const releases = [...new Set(conflicts.map((c) => c.release))];
+  const commands = releases.map((release) => {
+    const [, kind, name] = /^(package )?(.+)@[^@]+$/.exec(release) ?? [];
+    return kind ? `  ${release}: release a new version of the package` : `  ${release}: mosetta version patch --package ${name}`;
+  });
+  return `deploy refused: ${storeLabel} already holds these with other bytes, and a deployed version never changes:\n`
+    + `${commands.join('\n')}\nRaise each version, build again and deploy.`;
+}
+
+/** the module folder a dist key belongs to (`modules/<id>/…`), or null for anything else */
+export const moduleIdOf = (key) => /^modules\/([^/]+)\//.exec(key)?.[1] ?? null;
+
+/** the file of a module's code, by its id */
+export const moduleCodeKey = (id) => `modules/${id}/${id}.js`;
+
+/**
+ * The code upload, in phases: every artifact first, the catalogs last. A catalog names the
+ * integrities of the artifacts — published before them, a page rendered in between pins bytes
+ * that are not there yet (and a CDN caches the old bytes under the new content address). The
+ * distribution's PREFABS travel with the public catalog, uncached: a page embeds a prefab live, so
+ * a stale copy — or one naming modules not uploaded yet — would show in every such page. The
+ * private aggregate goes very last: its new ETag tells the runner the new generation is complete.
+ */
+export function uploadPhases(publicFiles, privateFiles) {
+  const isCatalog = (f) => f.key === CATALOG_KEY;
+  const isPublicCatalog = (f) => isCatalog(f) || f.key.startsWith(PREFABS_PREFIX);
+  return [
+    { label: 'public-code', store: 'public-code', files: publicFiles.filter((f) => !isPublicCatalog(f)), cacheControl: PUBLIC_CACHE_CONTROL },
+    { label: 'private-code', store: 'private-code', files: privateFiles.filter((f) => !isCatalog(f)) },
+    { label: 'public-code catalog', store: 'public-code', files: publicFiles.filter(isPublicCatalog), cacheControl: CATALOG_CACHE_CONTROL },
+    { label: 'private-code catalog', store: 'private-code', files: privateFiles.filter(isCatalog) },
+  ];
+}
+
+/** a release the rules refuse — the message says what to raise; `conflicts` name it */
+export class ReleaseRefused extends Error {
+  constructor(message, conflicts = []) {
+    super(message);
+    this.name = 'ReleaseRefused';
+    this.conflicts = conflicts;
+  }
+}
+
+const SIDES = ['public', 'private'];
+
+/** a store's catalog and the ETag it was read with (null: the store has none yet) */
+async function readCatalog(store, label) {
+  const res = await store.get(CATALOG_KEY);
+  if (res.status === 404) {
+    await res.arrayBuffer().catch(() => undefined);
+    return { entities: [], etag: null };
+  }
+  if (!res.ok) throw new Error(`release: reading the ${label} ${CATALOG_KEY} failed (${res.status})`);
+  // R2 behind Cloudflare compresses the answer and WEAKENS its ETag for it (`W/"…"`) — a write
+  // condition is compared with the stored object's strong ETag, which is the same value without
+  // the mark (checked live: a weak one never matches, the bare one does)
+  const etag = res.headers.get('etag')?.replace(/^W\//, '') ?? null;
+  const value = await res.json();
+  // without an ETag the catalog cannot be written over exactly this copy — and a release that
+  // cannot say so would silently drop what another one wrote
+  if (!etag) throw new Error(`release: the ${label} store gives no ETag for ${CATALOG_KEY} — it cannot be released into safely`);
+  return { entities: Array.isArray(value) ? value : [], etag };
+}
+
+const bytesOf = (body) => (typeof body === 'string' ? new TextEncoder().encode(body) : body);
+
+function sameBytes(a, b) {
+  if (a.byteLength !== b.byteLength) return false;
+  for (let i = 0; i < a.byteLength; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/** a store's answer as text, for a failure message */
+async function failure(res) {
+  return `${res.status} ${(await res.text().catch(() => '')).slice(0, 200)}`;
+}
+
+/**
+ * The plan of a release against the stores as they are now: the release plan of each side, its
+ * rebuilds settled, and the files to write. Conflicts are left in — `release` refuses them, a dry
+ * run reports them.
+ */
+async function planAgainst(stores, build) {
+  const catalogs = {};
+  const plans = {};
+  for (const side of SIDES) {
+    catalogs[side] = await readCatalog(stores[side], `${side}-code`);
+    const plan = releasePlan(catalogs[side].entities, build.catalogs[side]);
+    const readStored = async (id) => {
+      const res = await stores[side].get(moduleCodeKey(id));
+      return res.ok ? res.text() : (await res.arrayBuffer().catch(() => undefined), null);
+    };
+    const readBuilt = async (id) => {
+      const bytes = await build.read(side, moduleCodeKey(id));
+      return bytes === null ? null : new TextDecoder().decode(bytes);
+    };
+    plans[side] = await settleRebuilds(plan, readStored, readBuilt);
+  }
+  // a module folder goes up only when its id is new to the store; a map or a server facet of a
+  // public module rides with it. A folder no catalog names (a server-render facet) belongs to its
+  // component.
+  const fresh = new Set([...plans.public.fresh, ...plans.private.fresh]);
+  const known = new Set([...plans.public.catalog, ...plans.private.catalog].map((e) => e.id));
+  const ownerOf = (id) => (known.has(id) ? id : id.replace('_t_ssr_', '_t_component_'));
+  const wanted = (key) => {
+    const id = moduleIdOf(key);
+    if (id === null) return true;
+    const owner = ownerOf(id);
+    return fresh.has(owner) || !known.has(owner);
+  };
+  const files = Object.fromEntries(SIDES.map((side) => [side, build.files[side].filter((key) => key !== CATALOG_KEY && wanted(key))]));
+  // the bytes a fresh module's catalog entry vouches for — its code, or a stylesheet entity's sheet
+  // — must be them (the integrity the build writes; another kind is not this build's to check)
+  const vouched = new Map();
+  for (const side of SIDES) {
+    for (const entity of plans[side].catalog) {
+      if (!plans[side].fresh.has(entity.id) || !String(entity.integrity ?? '').startsWith('sha256-')) continue;
+      const ext = entity.reference?.type === 'css' ? 'css' : 'js';
+      vouched.set(`${side}/modules/${entity.id}/${entity.id}.${ext}`, entity.integrity);
+    }
+  }
+  return { catalogs, plans, files, vouched };
+}
+
+/** what a plan asks of the build: the files to write, and the code of each conflict to settle it */
+function neededOf(plans, files) {
+  return Object.fromEntries(SIDES.map((side) => [side, [...new Set([...files[side], ...plans[side].conflicts.map((c) => moduleCodeKey(c.id))])]]));
+}
+
+/**
+ * The plan of a release against the stores as they are, said without refusing: what is new, what
+ * conflicts (a conflict the build's code was not given for may still settle as a rebuild for a
+ * new framework), and which files a release will need — a platform answers a push's plan with it.
+ */
+export async function planRelease(stores, build) {
+  const { plans, files } = await planAgainst(stores, build);
+  return {
+    ...summaryOf(plans),
+    conflicts: [...plans.public.conflicts, ...plans.private.conflicts],
+    need: neededOf(plans, files),
+  };
+}
+
+/** a distribution by its namespace, a package (js or css) by its specifier — once each */
+function releasesOf(plan) {
+  return [...new Set([...plan.fresh].map((id) => plan.catalog.find((e) => e.id === id)?.reference)
+    .filter(Boolean)
+    .map((ref) => (ref.namespace ? `${ref.namespace}@${ref.version}` : `${ref.specifier}@${ref.version}`)))];
+}
+
+/** what a plan says, for a person and for the trace of the release — both sides of the code */
+function summaryOf(plans) {
+  const count = (field) => plans.public[field].length + plans.private[field].length;
+  return {
+    // a distribution of server modules only (a platform's API) is new in the private catalog alone
+    fresh: [...new Set([...releasesOf(plans.public), ...releasesOf(plans.private)])],
+    same: count('same'),
+    rebuilt: count('rebuilt'),
+    kept: count('kept'),
+  };
+}
+
+/**
+ * Write a module's file where none is: an object already there with the same bytes is the same
+ * release finishing (a retry, a rerun); with other bytes it is another release of the same version
+ * — in flight, or left over by one that failed — and both are cured the same way: a new version.
+ */
+async function putModuleFile(store, key, body, meta) {
+  const res = await store.put(key, body, { ...meta, ifNoneMatch: '*' });
+  if (res.ok) return void (await res.arrayBuffer().catch(() => undefined));
+  if (res.status !== 412) throw new Error(`put ${key} failed (${await failure(res)})`);
+  await res.arrayBuffer().catch(() => undefined);
+  const there = await store.get(key);
+  if (!there.ok) throw new Error(`put ${key}: the store refused it as present but does not give it back (${there.status})`);
+  if (!sameBytes(new Uint8Array(await there.arrayBuffer()), bytesOf(body))) {
+    throw new ReleaseRefused(`deploy refused: ${key} is already in the store with other bytes — another release of this version is in flight or left behind; raise the version, build again and deploy`);
+  }
+}
+
+async function putAll(store, keys, write) {
+  let done = 0;
+  const queue = [...keys];
+  const worker = async () => {
+    for (let key = queue.shift(); key !== undefined; key = queue.shift()) {
+      await write(key);
+      done++;
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(CONCURRENCY, keys.length) }, worker));
+  return done;
+}
+
+/**
+ * Release a build into a pair of code stores.
+ *
+ * @param stores `{ public, private }` — the public-code and private-code stores
+ * @param build `{ catalogs: { public, private }` (this build's entities)`, files: { public, private }`
+ *   (every key of the build, catalogs included)`, read(side, key) → Uint8Array | null }`
+ * @param options `label` names the stores in a refusal; `dryRun` plans and writes nothing; `log`
+ * @returns the plan's summary, and — when written — what went up and the catalogs' ETags before
+ *   and after. A refusal throws `ReleaseRefused`.
+ */
+export async function release(stores, build, { label = 'the store', dryRun = false, log = () => undefined } = {}) {
+  for (let attempt = 1; attempt <= ATTEMPTS; attempt++) {
+    const { catalogs, plans, files, vouched } = await planAgainst(stores, build);
+    const summary = summaryOf(plans);
+    log(`release: new ${summary.fresh.join(', ') || 'nothing'}; ${summary.same} tile(s) as deployed, `
+      + `${summary.rebuilt} rebuilt only for a new framework (kept as deployed), ${summary.kept} published package(s) kept as first deployed`);
+    const conflicts = [...plans.public.conflicts, ...plans.private.conflicts];
+    if (conflicts.length) throw new ReleaseRefused(conflictMessage(conflicts, label), conflicts);
+    if (dryRun) return { dryRun: true, ...summary, conflicts: [] };
+
+    const read = async (side, key) => {
+      const bytes = await build.read(side, key);
+      if (bytes === null) throw new Error(`release: ${side} ${key} is part of the release but was not given`);
+      return bytes;
+    };
+    const uploaded = {};
+    // the artifacts: a module's files where none are, anything else (pages.json) as built
+    for (const side of SIDES) {
+      const cacheControl = side === 'public' ? PUBLIC_CACHE_CONTROL : undefined;
+      const artifacts = files[side].filter((key) => side === 'private' || !key.startsWith(PREFABS_PREFIX));
+      uploaded[side] = await putAll(stores[side], artifacts, async (key) => {
+        const meta = { contentType: contentTypeOf(key), ...(cacheControl ? { cacheControl } : {}) };
+        const body = await read(side, key);
+        const integrity = vouched.get(`${side}/${key}`);
+        if (integrity && integrity !== await sriOf(body)) {
+          throw new ReleaseRefused(`deploy refused: ${key} is not the bytes its tile descriptor vouches for — build again`);
+        }
+        if (moduleIdOf(key) !== null) return putModuleFile(stores[side], key, body, meta);
+        const res = await stores[side].put(key, body, meta);
+        if (!res.ok) throw new Error(`${side}-code: put ${key} failed (${await failure(res)})`);
+        await res.arrayBuffer().catch(() => undefined);
+      });
+      log(`${side}-code: ${uploaded[side]} object(s) uploaded`);
+    }
+    // the distribution's prefabs, live, right before the public catalog
+    const prefabs = files.public.filter((key) => key.startsWith(PREFABS_PREFIX));
+    await putAll(stores.public, prefabs, async (key) => {
+      const res = await stores.public.put(key, await read('public', key), { contentType: contentTypeOf(key), cacheControl: CATALOG_CACHE_CONTROL });
+      if (!res.ok) throw new Error(`public-code: put ${key} failed (${await failure(res)})`);
+      await res.arrayBuffer().catch(() => undefined);
+    });
+    // the catalogs, each over exactly the copy the plan was made from: another release that wrote
+    // one in between makes this one start over — and its additions are in the next plan
+    const after = {};
+    let overtaken = false;
+    for (const side of SIDES) {
+      const condition = catalogs[side].etag ? { ifMatch: catalogs[side].etag } : { ifNoneMatch: '*' };
+      const body = JSON.stringify(plans[side].catalog, null, 2);
+      const res = await stores[side].put(CATALOG_KEY, body, {
+        contentType: contentTypeOf(CATALOG_KEY),
+        ...(side === 'public' ? { cacheControl: CATALOG_CACHE_CONTROL } : {}),
+        ...condition,
+      });
+      if (res.status === 412) {
+        await res.arrayBuffer().catch(() => undefined);
+        overtaken = true;
+        break;
+      }
+      if (!res.ok) throw new Error(`${side}-code: put ${CATALOG_KEY} failed (${await failure(res)})`);
+      after[side] = res.headers.get('etag');
+      await res.arrayBuffer().catch(() => undefined);
+    }
+    if (overtaken) {
+      if (attempt < ATTEMPTS) log(`release: another release wrote a tile host descriptor meanwhile — planning again (attempt ${attempt + 1} of ${ATTEMPTS})`);
+      continue;
+    }
+    log(`release: tile host descriptors written (${prefabs.length} prefab(s))`);
+    return {
+      ...summary,
+      uploaded: { ...uploaded, prefabs: prefabs.length },
+      catalogs: Object.fromEntries(SIDES.map((side) => [side, { before: catalogs[side].etag, after: after[side] ?? null }])),
+      attempts: attempt,
+    };
+  }
+  throw new Error(`release: other releases kept writing the tile host descriptors — ${ATTEMPTS} attempts were not enough; deploy again`);
+}
+
+// THE PUSH — a release sent to a platform rather than written by the publisher: a manifest of the
+// build (both catalogs, every file with its size and SHA-256, where it comes from), then the files
+// the platform's plan asked for. The platform checks every byte against the manifest and runs the
+// same release rules on its side.
+
+/** the manifest's entry in a push */
+export const RELEASE_MANIFEST = 'release.json';
+
+const hexOf = (digest) => [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+
+export async function sha256Hex(bytes) {
+  return hexOf(await crypto.subtle.digest('SHA-256', bytes));
+}
+
+/** the subresource integrity of bytes, as a catalog names it (`sha256-<base64>`) */
+export async function sriOf(bytes) {
+  const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', bytesOf(bytes)));
+  return `sha256-${btoa(String.fromCharCode(...digest))}`;
+}
+
+/**
+ * Why a build is not a TILE PALETTE of `brand` as a platform keeps one, said as a refusal: a
+ * palette holds tiles of its own brand and package tiles only, each vouching for its bytes with its
+ * integrity (a palette descriptor names no artifact and needs none) — the factory takes a tile of a
+ * host other than its primary only with it — and no fragments: a project's fragments are its
+ * content.
+ */
+export function checkPaletteBuild(catalogs, brand) {
+  const issues = [];
+  for (const side of SIDES) {
+    for (const entity of catalogs?.[side] ?? []) {
+      const id = String(entity?.id ?? '');
+      const of = /^_ns_([a-z0-9-]+)_t_/.exec(id)?.[1] ?? null;
+      const type = entity?.reference?.type;
+      if (of !== brand && of !== 'package') issues.push(`${id} is not of the brand ${brand}`);
+      else if (type === 'prefab') issues.push(`${id} is a fragment — a project's fragments are its content`);
+      else if (type !== 'distribution' && !String(entity.integrity ?? '').startsWith('sha256-')) issues.push(`${id} names no integrity`);
+    }
+  }
+  if (issues.length) {
+    const more = issues.length > 5 ? `; and ${issues.length - 5} more` : '';
+    throw new ReleaseRefused(`push refused: not a tile palette of ${brand} — ${issues.slice(0, 5).join('; ')}${more}`);
+  }
+}
+
+/** a build as a push describes it — `provenance` is what the publisher says of where it comes from */
+export async function manifestOf(build, provenance = {}) {
+  const files = {};
+  for (const side of SIDES) {
+    files[side] = [];
+    for (const key of build.files[side]) {
+      const bytes = await build.read(side, key);
+      if (bytes === null) throw new Error(`push: ${side} ${key} is listed but cannot be read`);
+      files[side].push({ key, size: bytes.byteLength, sha256: await sha256Hex(bytes) });
+    }
+  }
+  return { catalogs: build.catalogs, files, provenance };
+}
+
+const isFileList = (list) => Array.isArray(list) && list.every((f) => f && typeof f.key === 'string' && Number.isInteger(f.size) && typeof f.sha256 === 'string');
+
+/** a manifest as a platform accepts it, or a refusal saying what is wrong with it */
+export function readManifest(value) {
+  const ok = value && typeof value === 'object'
+    && SIDES.every((side) => Array.isArray(value.catalogs?.[side]) && isFileList(value.files?.[side]));
+  if (!ok) throw new ReleaseRefused('push refused: the manifest is not a build\'s (tile host descriptors and files of both sides)');
+  return { catalogs: value.catalogs, files: value.files, provenance: value.provenance && typeof value.provenance === 'object' ? value.provenance : {} };
+}
+
+/** the build a manifest names, without its bytes — what a plan is made from */
+export function describedBuild(manifest) {
+  return {
+    catalogs: manifest.catalogs,
+    files: Object.fromEntries(SIDES.map((side) => [side, manifest.files[side].map((f) => f.key)])),
+    read: async () => null,
+  };
+}
+
+/**
+ * The build a manifest names, with the bytes a push brought (`<side>/<key>` → bytes): each one the
+ * file the manifest names — its size and its SHA-256 — or the push is refused.
+ */
+export async function pushedBuild(manifest, provided) {
+  const named = new Map(SIDES.flatMap((side) => manifest.files[side].map((f) => [`${side}/${f.key}`, f])));
+  for (const [path, bytes] of provided) {
+    const file = named.get(path);
+    if (!file) throw new ReleaseRefused(`push refused: ${path} is not in the manifest`);
+    if (bytes.byteLength !== file.size || await sha256Hex(bytes) !== file.sha256) {
+      throw new ReleaseRefused(`push refused: ${path} is not the file the manifest names`);
+    }
+  }
+  return { ...describedBuild(manifest), read: async (side, key) => provided.get(`${side}/${key}`) ?? null };
+}