@xemahq/repo-build-tooling 0.15.1 → 0.17.0

package/README.md

@@ -30,10 +30,12 @@ pnpm exec xema-scrub-swagger-paths dist
 | `xema-service-bootstrap [--check] [--filter <key>] [--root <dir>]` | Generates `src/generated/*.generated.ts` service and worker descriptors from the repository's `xema-biome.json` manifests; `--check` fails on drift |
 | `xema-scrub-swagger-paths <dist-dir>...` | Rewrites `@nestjs/swagger` plugin output that names a private install path, then fails the build if any leak remains (`--self-test` available) |
 | `xema-composed-image <command>` | Build-time half of a composed-process image: `members`, `filters`, `dirs`, `pins`, `index`, `load`, `stage`, `pnpm-context`, `sync-injected`, `prisma-check`, `migrate`, `coordinate`, `load-image`, `smoke-refusal`, `dockerfile` |
+| `xema-promote-image --service <name> --dev-ref <repo> --release-ref <repo> --tag <tag> --commit <sha> --main-ref <ref> --signer-repository <owner/repo> --develop-workflow <file> --release-workflow <file>... --promotion-predicate-out <path> -- <tag command>` | Publishes the develop image's digest under the release tag instead of rebuilding: `reused` (the release tag is signed by a main workflow, or is the proven develop digest), `copied` (the proven develop digest, digest-preserving; fails closed if the release digest differs) or `miss` (build it). A develop digest is proven only if its SLSA v1 provenance is signed by the develop workflow at `refs/heads/develop`, its revision is an ancestor of the main ref, and the tag command prints the same tag at that revision and at `--commit`; any failed leg is an error, never a miss. On a promotion it writes the `https://xema.dev/attestations/image-promotion/v1` predicate for the caller to attest. Writes `result`, `digest`, `source`, `revision`, `evidence`, `provenance_digest`, `promotion_predicate`, `promotion_predicate_type` to `$GITHUB_OUTPUT`. Needs `docker`, `cosign`, `git` and full history. It does not sign |
+| `xema-arm64-supplement-needed` | Decides whether an arm64 supplement is still owed at `REGISTRY/IMAGE:CONTENT_TAG` (env: `REGISTRY`, `IMAGE`, `CONTENT_TAG`, `REGISTRY_USER`, `REGISTRY_TOKEN`). `needed=false` only when the coordinate serves an index whose linux/arm64 child is proven by its own image config; any other resolvable state is `needed=true`; a 401/403/5xx or an unresolvable child is an error. Writes `needed=true\|false` to `$GITHUB_OUTPUT`. Replaces the generated `arm64-supplement-needed.mjs` copy. |
 | `xema-check-no-vendored-deps` | Fails on a `workspace:` range for a package the repository does not own |
 | `xema-check-workspace-ranges` | Fails on a `workspace:` range the local package does not satisfy |
 
-`xema-composed-image members --write|--check` accepts `--manifests <glob>` (repeatable, default `**/xema-biome.json`), `--canonical-dockerfile <path>` and `--cross-repo-manifest <path>`. `xema-composed-image dockerfile` requires `--copy`, `--cache-id` and `--build-source`; it pins the version of this tool itself, and there is no flag for it (`--tooling-version` is refused as an unknown option). `dockerfile --prebuilt` renders the Dockerfile and `Dockerfile.dockerignore` of an image assembled from `stage <dir> [--output <rel>]… [--also <pkg>]…` output (requires `--cache-id`, `--build-source`; `--copy` and `--stage-dir` optional); `load --each` loads every member in its own process. `stage` and `filters` accept `--also <workspace package name>` (repeatable): the package's closure is built and staged (built outputs only, no Prisma checks) alongside the members; an unknown name is refused. `pnpm-context <dir> (--subject <svc>… | --image-dir <composed>)` runs on the CI runner after `pnpm install --frozen-lockfile` and builds the offline `xema-pnpm` build context (`staged.json`, `corepack/pnpm.tgz`, and, with `--image-dir` only, a warmed `cache/` of registry metadata; `--subject` writes no `cache/` and `staged.json` says `cache: false`); it prints `XEMA_PNPM_CONTEXT=<dir>` and `XEMA_PNPM_STORE=<store root>` on stdout (everything else on stderr) and refuses a non-empty `<dir>`. Run `xema-composed-image` with no arguments for the full usage.
+`xema-composed-image members --write|--check` accepts `--manifests <glob>` (repeatable, default `**/xema-biome.json`), `--canonical-dockerfile <path>` and `--cross-repo-manifest <path>`. `xema-composed-image dockerfile` requires `--copy`, `--cache-id` and `--build-source`; it pins the version of this tool itself, and there is no flag for it (`--tooling-version` is refused as an unknown option). `dockerfile --prebuilt` renders the Dockerfile and `Dockerfile.dockerignore` of an image assembled from `stage <dir> [--output <rel>]… [--also <pkg>]…` output (requires `--cache-id`, `--build-source`; `--copy` and `--stage-dir` optional); `load --each` loads every member in its own process. `stage` and `filters` accept `--also <workspace package name>` (repeatable): the package's closure is built and staged (built outputs only, no Prisma checks) alongside the members; an unknown name is refused. `pnpm-context <dir> (--subject <svc>… | --image-dir <composed>)` runs on the CI runner after `pnpm install --frozen-lockfile` and builds the offline `xema-pnpm` build context (`staged.json`, `corepack/pnpm.tgz`, and, with `--image-dir` only, a warmed `cache/` of registry metadata; `--subject` writes no `cache/` and `staged.json` says `cache: false`); it prints `XEMA_PNPM_CONTEXT=<dir>` and `XEMA_PNPM_STORE=<store root>` on stdout (everything else on stderr) and refuses a non-empty `<dir>`. `dockerfile --prebuilt` renders an OFFLINE image: every install RUN is `--network=none` and reads the runner's pnpm store and the `pnpm-context` output as the named build contexts `xema-pnpm-store` and `xema-pnpm`; without them the build fails with a message (no network fallback). `pnpm rebuild` runs only for `onlyBuiltDependencies` in the members' prod closure (less prisma, @prisma/client, @prisma/engines, @nestjs/core, esbuild, @swc/core) and the render needs `pnpm install` first; a node-gyp module with no optional prebuilt packages is refused. `pnpm-context --image-dir` reads the deps stage's COPY directories from the committed Dockerfile. Run `xema-composed-image` with no arguments for the full usage.
 
 Every step refuses rather than skips. The package has no dependencies.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "description": "Dev-time build tooling shared by every Xema repository. Ships as plain ESM, depending only on @xemahq/release-policy for registry access, so the published artifact is the reviewed source.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
@@ -21,18 +21,22 @@
     "src"
   ],
   "bin": {
+    "xema-arm64-supplement-needed": "src/arm64-supplement-needed.mjs",
     "xema-check-no-vendored-deps": "src/check-no-vendored-deps.mjs",
     "xema-check-workspace-ranges": "src/check-workspace-range-matches-local.mjs",
     "xema-composed-image": "src/composed-image.mjs",
+    "xema-promote-image": "src/promote-image.mjs",
     "xema-readiness": "src/readiness.mjs",
     "xema-scrub-swagger-paths": "src/scrub-swagger-plugin-paths.mjs",
     "xema-service-bootstrap": "src/service-bootstrap.mjs"
   },
   "exports": {
+    "./arm64-supplement-needed": "./src/arm64-supplement-needed.mjs",
     "./check-no-vendored-deps": "./src/check-no-vendored-deps.mjs",
     "./check-workspace-range-matches-local": "./src/check-workspace-range-matches-local.mjs",
     "./composed-image": "./src/composed-image.mjs",
     "./package.json": "./package.json",
+    "./promote-image": "./src/promote-image.mjs",
     "./readiness": "./src/readiness.mjs",
     "./scrub-swagger-plugin-paths": "./src/scrub-swagger-plugin-paths.mjs",
     "./service-bootstrap": "./src/service-bootstrap.mjs"
@@ -41,9 +45,9 @@
     "@xemahq/release-policy": "^14.0.0"
   },
   "scripts": {
-    "test": "node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs && node --test src/check-no-vendored-deps.test.mjs && node --test src/readiness.test.mjs && node --test src/composed-image.test.mjs && node --test src/composed-image-coordinate-cli.test.mjs && node --test src/declaration-refusal.test.mjs && node --test src/smoke-refusal.test.mjs && node --test src/load-image.test.mjs && node --test src/composed-image-coordinate.test.mjs && node --test src/composed-image-dockerfile.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.test.mjs && node --test src/composed-image-prebuilt-dockerfile.test.mjs && node --test src/composed-image-in-image-closure.test.mjs && node --test src/composed-image-stage.test.mjs && node --test src/composed-image-pnpm-context.test.mjs && node --test src/composed-image-sync-injected.test.mjs && node --test src/composed-image-prisma-check.test.mjs && node --test src/composed-migrate.test.mjs"
+    "test": "node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs && node --test src/check-no-vendored-deps.test.mjs && node --test src/readiness.test.mjs && node --test src/composed-image.test.mjs && node --test src/composed-image-coordinate-cli.test.mjs && node --test src/declaration-refusal.test.mjs && node --test src/smoke-refusal.test.mjs && node --test src/load-image.test.mjs && node --test src/composed-image-coordinate.test.mjs && node --test src/composed-image-dockerfile.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.test.mjs && node --test src/composed-image-prebuilt-dockerfile.test.mjs && node --test src/composed-image-in-image-closure.test.mjs && node --test src/composed-image-stage.test.mjs && node --test src/composed-image-pnpm-context.test.mjs && node --test src/composed-image-sync-injected.test.mjs && node --test src/composed-image-prisma-check.test.mjs && node --test src/composed-migrate.test.mjs && node --test src/promote-image.test.mjs && node --test src/arm64-supplement-needed.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:fa45efe38d666b11ffa8841595cec6f19d065d77f286bf2b7c1e6eb3c93aed0e"
+    "sourceDigest": "sha256:150d82fb857d535b44f1e29686108056532bc9a7827b51260c88bf3270a00eeb"
   }
 }

package/src/arm64-supplement-needed.mjs

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+// ═══════════════════════════════════════════════════════════════════════════
+// DOES THIS COORDINATE STILL NEED AN arm64 SUPPLEMENT?
+//
+// An arm64 supplement lane that rebuilds and re-merges UNCONDITIONALLY does
+// more than waste a run. `imagetools create -t :<contentHash>` republishes the
+// canonical coordinate by design, so supplementing an ALREADY-COMPLETE index
+// MOVES A TAG somebody may already have sealed.
+//
+// ── WHY A RE-RUN MOVES THE DIGEST AT ALL ────────────────────────────────────
+//
+// Two builds of the SAME source do not produce the same arm64 manifest unless
+// the build is reproducible. Absent a `SOURCE_DATE_EPOCH`, the image config's
+// `created` and `history[].created` are WALL-CLOCK, so a rebuild changes the
+// config digest and therefore the manifest digest even when every layer byte is
+// identical. The amd64 side does not move only because it is never rebuilt by a
+// supplement lane — the merge REFERENCES its existing per-commit tag.
+//
+// Making the arm64 build reproducible is a separate and much larger decision:
+// it would move every coordinate's digest on the next build. This probe instead
+// makes the question MOOT for a coordinate that is already final, which is the
+// cheap half and the one that stops a sealed tag moving under a release.
+//
+// ── WHY A PROOF AND NOT A READ ──────────────────────────────────────────────
+//
+// An index descriptor DECLARES a child's platform. The merge is exactly where a
+// mislabelled arm64 child would enter, so trusting the declaration would let one
+// bad index become permanent: the supplement lane is the only thing that can
+// repair it, and a descriptor-only check would skip the repair forever.
+//
+// So a skip is EARNED — by resolving the child manifest BY DIGEST and reading
+// the architecture out of its image CONFIG. A mislabelled index reads as NOT
+// SUPPLEMENTED and is rebuilt.
+//
+// ── FAIL LOUD, NEVER GUESS ──────────────────────────────────────────────────
+//
+// Only 200 and 404 are answers. A 401/403 on a private package is
+// indistinguishable from an image that was never pushed, so anything else
+// throws. That direction is deliberate: a supplement lane is off the deploy
+// graph, so a red run there costs nothing, whereas a guessed answer either
+// moves a sealed tag or silently leaves a coordinate single-platform.
+//
+// The same posture governs the ENTRYPOINT GUARD at the foot of this file. It
+// uses `invokedDirectly` (realpath on both sides) because the alternative fails
+// in the dangerous direction: a guard that does not match runs no `main()`,
+// writes no `needed=` output, and a workflow gating its merge on
+// `needed == 'true'` then SKIPS a supplement that was genuinely owed —
+// silently, and with a green tick.
+//
+// Registry transport (retry, redaction, the GHCR pull token) is
+// `@xemahq/release-policy/registry`, not a copy of it.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { appendFileSync } from 'node:fs';
+
+import {
+  acquireGhcrPullToken,
+  describeErrorChain,
+  registryFetch,
+} from '@xemahq/release-policy/registry';
+
+import { invokedDirectly } from './readiness.mjs';
+
+const SHA256_HEX = /^[a-f0-9]{64}$/u;
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+
+const MANIFEST_ACCEPT = [
+  'application/vnd.oci.image.index.v1+json',
+  'application/vnd.oci.image.manifest.v1+json',
+  'application/vnd.docker.distribution.manifest.list.v2+json',
+  'application/vnd.docker.distribution.manifest.v2+json',
+].join(', ');
+
+/** The platform a supplement exists to add. */
+export const SUPPLEMENT_OS = 'linux';
+export const SUPPLEMENT_ARCHITECTURE = 'arm64';
+
+async function getJson({
+  registry,
+  repository,
+  reference,
+  bearer,
+  fetchImpl,
+  sleep,
+}) {
+  const response = await registryFetch(
+    fetchImpl,
+    `https://${registry}/v2/${repository}/manifests/${reference}`,
+    {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${bearer}`, Accept: MANIFEST_ACCEPT },
+    },
+    { sleep },
+  );
+  if (response.status === 404) return { status: 404, document: undefined };
+  if (response.status !== 200) {
+    throw new Error(
+      `${registry}: manifest lookup for ${repository}:${reference} returned HTTP ${response.status}`,
+    );
+  }
+  let document;
+  try {
+    document = await response.json();
+  } catch {
+    throw new Error(
+      `${registry}: manifest ${repository}:${reference} was not JSON`,
+    );
+  }
+  return { status: 200, document };
+}
+
+/**
+ * Children whose DESCRIPTOR claims the supplemented platform.
+ *
+ * BuildKit attestation manifests declare `unknown/unknown` and are excluded by
+ * the same predicate that selects the runnable child — deliberately, rather
+ * than by naming them, so an unrecognised child is never silently treated as a
+ * platform it did not claim.
+ *
+ * @param {unknown} document a manifest or an index
+ * @returns {string[]} candidate child digests
+ */
+export function declaredArm64Children(document) {
+  const manifests = document?.manifests;
+  if (!Array.isArray(manifests)) return [];
+  return manifests
+    .filter(
+      (child) =>
+        child?.platform?.os === SUPPLEMENT_OS &&
+        child?.platform?.architecture === SUPPLEMENT_ARCHITECTURE,
+    )
+    .map((child) => child?.digest)
+    .filter((digest) => typeof digest === 'string' && DIGEST.test(digest));
+}
+
+/**
+ * Prove one child really is a linux/arm64 image by reading its CONFIG.
+ *
+ * @returns {Promise<boolean>}
+ */
+async function childIsArm64({
+  registry,
+  repository,
+  digest,
+  bearer,
+  fetchImpl,
+  sleep,
+}) {
+  const { status, document } = await getJson({
+    registry,
+    repository,
+    reference: digest,
+    bearer,
+    fetchImpl,
+    sleep,
+  });
+  // A child an index REFERENCES must resolve. A 404 here is a broken index,
+  // not an absent supplement — say which, rather than quietly rebuilding.
+  if (status === 404) {
+    throw new Error(
+      `${registry}: ${repository} index references child ${digest}, which the registry does not serve`,
+    );
+  }
+  const configDigest = document?.config?.digest;
+  if (typeof configDigest !== 'string' || !DIGEST.test(configDigest)) {
+    throw new Error(
+      `${registry}: ${repository}@${digest} declares no usable config digest`,
+    );
+  }
+  const response = await registryFetch(
+    fetchImpl,
+    `https://${registry}/v2/${repository}/blobs/${configDigest}`,
+    { method: 'GET', headers: { Authorization: `Bearer ${bearer}` } },
+    { sleep },
+  );
+  if (response.status !== 200) {
+    throw new Error(
+      `${registry}: config blob ${repository}@${configDigest} returned HTTP ${response.status}`,
+    );
+  }
+  let config;
+  try {
+    config = await response.json();
+  } catch {
+    throw new Error(
+      `${registry}: config blob ${repository}@${configDigest} was not JSON`,
+    );
+  }
+  return (
+    config?.os === SUPPLEMENT_OS &&
+    config?.architecture === SUPPLEMENT_ARCHITECTURE
+  );
+}
+
+/**
+ * Is an arm64 supplement still owed at `registry/repository:contentHash`?
+ *
+ * `needed: false` ONLY when the canonical coordinate already serves an index
+ * whose linux/arm64 child is proven by its own config. Every other resolvable
+ * state — absent, single-platform, index without arm64, index whose arm64 child
+ * does not prove out — is `needed: true`.
+ *
+ * @returns {Promise<{ needed: boolean, reason: string }>}
+ */
+export async function arm64SupplementNeeded({
+  registry,
+  repository,
+  contentHash,
+  user,
+  token,
+  fetchImpl = fetch,
+  sleep,
+}) {
+  if (!SHA256_HEX.test(contentHash ?? '')) {
+    throw new Error(
+      `'${contentHash}' is not a 64-character lowercase content hash`,
+    );
+  }
+  const bearer = await acquireGhcrPullToken({
+    registry,
+    repository,
+    user,
+    token,
+    fetchImpl,
+  });
+  const { status, document } = await getJson({
+    registry,
+    repository,
+    reference: contentHash,
+    bearer,
+    fetchImpl,
+    sleep,
+  });
+  if (status === 404) {
+    return { needed: true, reason: 'the canonical coordinate does not exist' };
+  }
+  if (!Array.isArray(document?.manifests)) {
+    return {
+      needed: true,
+      reason: `the canonical coordinate is a single manifest (${document?.mediaType ?? 'unknown media type'}), not an index`,
+    };
+  }
+  const candidates = declaredArm64Children(document);
+  if (candidates.length === 0) {
+    return {
+      needed: true,
+      reason: `the index declares no ${SUPPLEMENT_OS}/${SUPPLEMENT_ARCHITECTURE} child`,
+    };
+  }
+  for (const digest of candidates) {
+    if (
+      await childIsArm64({
+        registry,
+        repository,
+        digest,
+        bearer,
+        fetchImpl,
+        sleep,
+      })
+    ) {
+      return {
+        needed: false,
+        reason: `the index already carries a proven ${SUPPLEMENT_OS}/${SUPPLEMENT_ARCHITECTURE} child (${digest})`,
+      };
+    }
+  }
+  return {
+    needed: true,
+    reason: `the index declares ${candidates.length} ${SUPPLEMENT_OS}/${SUPPLEMENT_ARCHITECTURE} child(ren) but none proved out against its own config`,
+  };
+}
+
+/**
+ * The CLI entry layer: the only reader of the process environment.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ */
+async function main(env) {
+  const registry = env.REGISTRY;
+  const image = env.IMAGE;
+  const contentHash = env.CONTENT_TAG;
+  if (!registry) throw new Error('REGISTRY is required.');
+  if (!image) throw new Error('IMAGE is required.');
+  const prefix = `${registry}/`;
+  if (!image.startsWith(prefix)) {
+    throw new Error(`IMAGE '${image}' is not hosted on '${registry}'`);
+  }
+  const repository = image.slice(prefix.length);
+
+  const { needed, reason } = await arm64SupplementNeeded({
+    registry,
+    repository,
+    contentHash,
+    user: env.REGISTRY_USER,
+    token: env.REGISTRY_TOKEN,
+  });
+
+  // THE CORPUS LINE. A skipped supplement and a supplement that silently did
+  // nothing exit the same way and print the same tick; the coordinate it
+  // graded and the reason are the only things that tell them apart.
+  console.log(
+    `arm64 supplement ${needed ? 'NEEDED' : 'ALREADY PUBLISHED'} for ` +
+      `${image}:${contentHash} — ${reason}`,
+  );
+  if (!needed) {
+    console.log(
+      '::notice::Skipping the arm64 build and the index merge. Re-merging an ' +
+        'already-complete coordinate would republish the tag under a new digest ' +
+        'and move any seal that names it.',
+    );
+  }
+
+  const out = env.GITHUB_OUTPUT;
+  if (out) appendFileSync(out, `needed=${needed ? 'true' : 'false'}\n`);
+}
+
+if (invokedDirectly(process.argv[1], import.meta.url)) {
+  main(process.env).catch((error) => {
+    console.error(
+      `::error title=arm64 supplement probe failed::${error.message}`,
+    );
+    for (const line of describeErrorChain(error)) console.error(`  ${line}`);
+    process.exit(1);
+  });
+}

package/src/arm64-supplement-needed.test.mjs

@@ -0,0 +1,257 @@
+// Cases for `arm64-supplement-needed.mjs` (the `xema-arm64-supplement-needed` bin).
+// Registry transport (retry, redaction, abort) is tested in @xemahq/release-policy.
+//
+// The probe decides whether the arm64 lane REBUILDS and RE-MERGES. A wrong
+// answer is expensive in both directions and neither shows up as a failure:
+//
+//   wrongly `true`  -> the lane republishes `:<contentHash>` under a NEW digest
+//                      and MOVES a seal that names it. `seal-image-digests`
+//                      then refuses every edition carrying that coordinate —
+//                      which is exactly what happened to app-forge-api on
+//                      2026-09-21 and blocked five of nine editions.
+//   wrongly `false` -> the coordinate stays amd64-only, forever: the amd64
+//                      matrix is content-addressed and never re-selects an
+//                      existing coordinate, so this lane never re-arms for it.
+//
+// So both directions are asserted, and the mislabelled-child case is asserted
+// SEPARATELY from the absent-child case: it is the only one that fails if the
+// config proof is downgraded to reading the index descriptor.
+
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  arm64SupplementNeeded,
+  declaredArm64Children,
+} from './arm64-supplement-needed.mjs';
+
+const HASH = 'a'.repeat(64);
+const ARM_CHILD = `sha256:${'1'.repeat(64)}`;
+const AMD_CHILD = `sha256:${'2'.repeat(64)}`;
+const ARM_CONFIG = `sha256:${'3'.repeat(64)}`;
+const AMD_CONFIG = `sha256:${'4'.repeat(64)}`;
+
+const json = (body, status = 200) => ({
+  status,
+  json: async () => body,
+});
+
+const INDEX_BOTH = {
+  mediaType: 'application/vnd.oci.image.index.v1+json',
+  manifests: [
+    { digest: AMD_CHILD, platform: { os: 'linux', architecture: 'amd64' } },
+    { digest: ARM_CHILD, platform: { os: 'linux', architecture: 'arm64' } },
+    {
+      digest: `sha256:${'9'.repeat(64)}`,
+      platform: { os: 'unknown', architecture: 'unknown' },
+      annotations: { 'vnd.docker.reference.type': 'attestation-manifest' },
+    },
+  ],
+};
+
+/**
+ * A registry whose arm64 child's CONFIG declares `configArchitecture`.
+ * Setting it to `amd64` is the mislabelled index the proof exists to catch.
+ */
+function registry({
+  manifest = INDEX_BOTH,
+  manifestStatus = 200,
+  configArchitecture = 'arm64',
+  childStatus = 200,
+  tokenStatus = 200,
+} = {}) {
+  const seen = [];
+  const fetchImpl = async (url, init = {}) => {
+    const href = String(url);
+    seen.push(href);
+    if (href.includes('/token?') || href.includes('/token&') || href.endsWith('/token')) {
+      return json({ token: 'bearer-value' }, tokenStatus);
+    }
+    if (href.endsWith(`/manifests/${HASH}`)) {
+      return manifestStatus === 200
+        ? json(manifest)
+        : { status: manifestStatus, json: async () => ({}) };
+    }
+    if (href.endsWith(`/manifests/${ARM_CHILD}`)) {
+      return childStatus === 200
+        ? json({ config: { digest: ARM_CONFIG } })
+        : { status: childStatus, json: async () => ({}) };
+    }
+    if (href.endsWith(`/blobs/${ARM_CONFIG}`)) {
+      return json({ os: 'linux', architecture: configArchitecture });
+    }
+    if (href.endsWith(`/blobs/${AMD_CONFIG}`)) {
+      return json({ os: 'linux', architecture: 'amd64' });
+    }
+    assert.fail(`unexpected request: ${href} ${JSON.stringify(init.method)}`);
+  };
+  return { fetchImpl, seen };
+}
+
+const noSleep = async () => {};
+
+const probe = (options) =>
+  arm64SupplementNeeded({
+    registry: 'ghcr.io',
+    repository: 'xema-dev/app-forge-api',
+    contentHash: HASH,
+    user: 'x',
+    token: 'y',
+    fetchImpl: registry(options).fetchImpl,
+    sleep: noSleep,
+  });
+
+test('a complete index with a PROVEN arm64 child needs no supplement', async () => {
+  const { needed, reason } = await probe();
+  assert.equal(needed, false);
+  assert.match(reason, /already carries a proven linux\/arm64 child/u);
+});
+
+test('an index whose arm64 child is MISLABELLED still needs a supplement', async () => {
+  // The descriptor says linux/arm64; the image config says amd64. Reading the
+  // descriptor alone would skip the rebuild and make a broken index permanent,
+  // because this lane is the only thing that can repair one.
+  const { needed, reason } = await probe({ configArchitecture: 'amd64' });
+  assert.equal(needed, true);
+  assert.match(reason, /none proved out against its own config/u);
+});
+
+test('an index with amd64 only needs a supplement', async () => {
+  const { needed, reason } = await probe({
+    manifest: {
+      mediaType: 'application/vnd.oci.image.index.v1+json',
+      manifests: [
+        { digest: AMD_CHILD, platform: { os: 'linux', architecture: 'amd64' } },
+      ],
+    },
+  });
+  assert.equal(needed, true);
+  assert.match(reason, /declares no linux\/arm64 child/u);
+});
+
+test('an index carrying ONLY attestations needs a supplement', async () => {
+  const { needed } = await probe({
+    manifest: {
+      mediaType: 'application/vnd.oci.image.index.v1+json',
+      manifests: [
+        {
+          digest: `sha256:${'9'.repeat(64)}`,
+          platform: { os: 'unknown', architecture: 'unknown' },
+          annotations: { 'vnd.docker.reference.type': 'attestation-manifest' },
+        },
+      ],
+    },
+  });
+  assert.equal(needed, true);
+});
+
+test('a single-platform manifest needs a supplement', async () => {
+  const { needed, reason } = await probe({
+    manifest: {
+      mediaType: 'application/vnd.oci.image.manifest.v1+json',
+      config: { digest: AMD_CONFIG },
+    },
+  });
+  assert.equal(needed, true);
+  assert.match(reason, /single manifest/u);
+});
+
+test('an ABSENT coordinate needs a supplement', async () => {
+  const { needed, reason } = await probe({ manifestStatus: 404 });
+  assert.equal(needed, true);
+  assert.match(reason, /does not exist/u);
+});
+
+test('a 403 THROWS rather than answering', async () => {
+  // A 403 on a private package is indistinguishable from an image that was
+  // never pushed. Answering either way is a guess; one moves a sealed tag and
+  // the other strands a coordinate amd64-only.
+  await assert.rejects(probe({ manifestStatus: 403 }), /returned HTTP 403/u);
+});
+
+test('a 500 THROWS rather than answering', async () => {
+  await assert.rejects(probe({ manifestStatus: 500 }), /returned HTTP 500/u);
+});
+
+test('an index referencing an UNRESOLVABLE child THROWS', async () => {
+  await assert.rejects(
+    probe({ childStatus: 404 }),
+    /does not serve/u,
+  );
+});
+
+test('a non-sha256 content hash THROWS before any request', async () => {
+  await assert.rejects(
+    arm64SupplementNeeded({
+      registry: 'ghcr.io',
+      repository: 'xema-dev/app-forge-api',
+      contentHash: 'not-a-hash',
+      user: 'x',
+      token: 'y',
+      fetchImpl: async () => assert.fail('no request may be made'),
+    }),
+    /not a 64-character lowercase content hash/u,
+  );
+});
+
+test('credentials never leave the configured registry host', async () => {
+  await assert.rejects(
+    arm64SupplementNeeded({
+      registry: 'evil.example.com',
+      repository: 'xema-dev/app-forge-api',
+      contentHash: HASH,
+      user: 'x',
+      token: 'y',
+      fetchImpl: async () => assert.fail('no request may be made'),
+    }),
+    /cannot send credentials to registry/u,
+  );
+});
+
+test('declaredArm64Children selects only linux/arm64 descriptors', () => {
+  assert.deepEqual(declaredArm64Children(INDEX_BOTH), [ARM_CHILD]);
+  assert.deepEqual(declaredArm64Children({ mediaType: 'x' }), []);
+  assert.deepEqual(declaredArm64Children(undefined), []);
+  // A descriptor with the right architecture but the wrong OS is not a
+  // supplement for this lane.
+  assert.deepEqual(
+    declaredArm64Children({
+      manifests: [
+        { digest: ARM_CHILD, platform: { os: 'windows', architecture: 'arm64' } },
+      ],
+    }),
+    [],
+  );
+});
+
+test('HTTP 404 on the manifest request makes exactly 1 manifest call', async () => {
+  const { fetchImpl, seen } = registry({ manifestStatus: 404 });
+  const { needed } = await arm64SupplementNeeded({
+    registry: 'ghcr.io',
+    repository: 'xema-dev/app-forge-api',
+    contentHash: HASH,
+    user: 'x',
+    token: 'y',
+    fetchImpl,
+    sleep: noSleep,
+  });
+  assert.equal(needed, true);
+  assert.equal(seen.filter((href) => href.endsWith(`/manifests/${HASH}`)).length, 1);
+});
+
+test('HTTP 403 on the manifest request makes 1 manifest call', async () => {
+  const { fetchImpl, seen } = registry({ manifestStatus: 403 });
+  await assert.rejects(
+    arm64SupplementNeeded({
+      registry: 'ghcr.io',
+      repository: 'xema-dev/app-forge-api',
+      contentHash: HASH,
+      user: 'x',
+      token: 'y',
+      fetchImpl,
+      sleep: noSleep,
+    }),
+    /HTTP 403/u,
+  );
+  assert.equal(seen.filter((href) => href.endsWith(`/manifests/${HASH}`)).length, 1);
+});