@xemahq/repo-build-tooling 0.21.1 → 0.21.3

package/README.md

@@ -31,7 +31,7 @@ pnpm exec xema-scrub-swagger-paths dist
 | `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-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-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 digest carries an `image-promotion/v1` attestation signed by a `--release-workflow` identity on main, with exactly one verified statement about the digest and a `ghcr.io/<owner>/dev/<name>` source; no dev-ref probe), `copied` (the proven develop digest, digest-preserving; fails closed if the release digest differs) or `miss` (build it; a reuse whose release digest has no `image-promotion/v1` attestation, a legacy image, is a miss with `reason=reuse-no-promotion` on the stdout line; a signature or identity failure, or a source outside `dev/`, is an error; a copy whose dev digest carries no SLSA v1 provenance at all, an image reused on develop from before provenance, is a miss with `reason=copy-no-develop-provenance`, while provenance that is present but fails a leg is an error). 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 every non-miss result it writes the `https://xema.dev/attestations/image-promotion/v1` predicate for the caller to attest: a copy states the facts just proved; a reuse states this run's `release` and `promotedCommit` and carries `source` and `developProvenance` from the earlier promotion. Writes `result`, `digest`, `source`, `revision`, `evidence`, `provenance_digest`, `promotion_predicate`, `promotion_predicate_type` to `$GITHUB_OUTPUT`. Needs `docker`, `cosign` (major v2, the same as the develop attest step and xema-deploy's verify; it runs `cosign version` first and refuses any other major or an unparsable version), `git` and full history. It does not sign |
+| `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>... [--release-index-workflow <file>] --promotion-predicate-out <path> -- <tag command>` | Publishes the develop image's digest under the release tag instead of rebuilding: `reused` (the release digest carries an `image-promotion/v1` attestation signed by a `--release-workflow` identity on main, with exactly one verified statement about the digest and a `ghcr.io/<owner>/dev/<name>` source; no dev-ref probe), `copied` (the proven develop digest, digest-preserving; fails closed if the release digest differs) or `miss` (build it; a reuse whose release digest has no `image-promotion/v1` attestation, a legacy image, is a miss with `reason=reuse-no-promotion` on the stdout line; with `--release-index-workflow`, a release tag that names an image index signed by that workflow on main, with exactly one `linux/amd64` child whose own digest passes that same reuse check, is instead `reused` with `evidence=release-index`, `digest` = the amd64 child A, `index_digest` = the index D and no predicate, but only when A's selected promotion statement promotes `--commit` itself (a rerun; a later commit with the same content takes the existing miss and attests its own promotion). On `evidence=release-index` the caller skips sign/attest, tags `:<sha>` and `main-<sha>` to the amd64 subject `digest` (release-arm64 resolves `:<sha>` to it and verifies its promotion), and points only the content tag (and `latest`, if it moves it) at the index `index_digest`. Any failed step keeps the miss, and two amd64 children are an error; a signature or identity failure, or a source outside `dev/`, is an error; a copy whose dev digest carries no SLSA v1 provenance at all, an image reused on develop from before provenance, is a miss with `reason=copy-no-develop-provenance`, while provenance that is present but fails a leg is an error). 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 every non-miss result it writes the `https://xema.dev/attestations/image-promotion/v1` predicate for the caller to attest: a copy states the facts just proved; a reuse states this run's `release` and `promotedCommit` and carries `source` and `developProvenance` from the earlier promotion. Writes `result`, `digest`, `source`, `revision`, `evidence`, `provenance_digest`, `promotion_predicate`, `promotion_predicate_type` to `$GITHUB_OUTPUT`. Needs `docker`, `cosign` (major v2, the same as the develop attest step and xema-deploy's verify; it runs `cosign version` first and refuses any other major or an unparsable version), `git` and full history. It does not sign |
 | `xema-buildx-builder ensure` | Ensures the runner's persistent, capped buildkitd container (`xema-buildkit-signed-<runner>`, state volume `-state`) is up and is the current buildx builder. Env: `RUNNER_NAME`, `BUILDKIT_IMAGE`, `BUILDKIT_LIMITS` (JSON `cpus`, `memory`, `maxParallelism`, `gcMaxUsedSpace`, all required and positive), optional `BUILDKIT_READY_DEADLINE_SECONDS` (positive integer, default 180). The slot is `RUNNER_NAME` with a trailing `-<hostname>` stripped only when it equals this container's own hostname, so a recreated runner container reuses its builder and cache. Pinned to the runner's cgroup cpuset; caps are clamped so every `xema-buildkit-signed-*` builder on the host fits (memory at most half of `docker info` MemTotal divided by N, CPUs at most NCPU divided by N). On each run it removes this verb's labelled builders, and their `-state` volumes, whose recorded runner container is no longer running; unlabelled containers are never touched. Recreated once when the image, effective caps, config or runner container change. Prints `buildx-boot path= secs= builder=`. |
 | `xema-check-no-vendored-deps` | Fails on a `workspace:` range for a package the repository does not own |
 | `xema-prepush-sanity` | Lefthook `pre-push`: turbo `lint` and `typecheck` on what the push changes plus dependents (root `lint` only without turbo; typecheck is CI-only there); CI is the proof |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.21.1",
+  "version": "0.21.3",
   "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)",
@@ -49,9 +49,9 @@
     "@xemahq/release-policy": "^14.0.0"
   },
   "scripts": {
-    "test": "node --test src/buildx-builder.test.mjs && 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 && node --test src/prepush-sanity.test.mjs"
+    "test": "node --test src/buildx-builder.test.mjs && 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-image-prisma-engine.test.mjs && node --test src/composed-migrate.test.mjs && node --test src/promote-image.test.mjs && node --test src/arm64-supplement-needed.test.mjs && node --test src/prepush-sanity.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:7c602b30aa27cb65d2c46fbe77f0c93da23bde8525e571943fb8ed5ea48dd924"
+    "sourceDigest": "sha256:57594caa2c2d04aedf32ce374f8e0d5806022c23e5d14451c3263c925a641de4"
   }
 }

package/src/buildx-builder.test.mjs

@@ -6,8 +6,11 @@ import { join } from 'node:path';
 import test from 'node:test';
 import { fileURLToPath } from 'node:url';
 
+import { runnerSlot } from './buildx-builder-host.mjs';
+
 const BIN = fileURLToPath(new URL('./buildx-builder.mjs', import.meta.url));
 const HOST = hostname();
+const OTHER_HOST = `${HOST}-other`;
 const OWN = 'xema-buildkit-signed-owl-runner-1';
 const ownRow = (host = HOST) => `${OWN}|xema-buildx-builder|${host}`;
 const LIMITS = '{"cpus":"4","memory":"8g","maxParallelism":4,"gcMaxUsedSpace":"5GB"}';
@@ -150,22 +153,29 @@ test('a recreated runner container (new hostname) recreates its builder once, ke
     const first = s.run({});
     const label = /--label xema\.buildkit\.cfg=([0-9a-f]{64})/.exec(first.calls)[1];
     rmSync(join(s.dir, 'calls.log'));
-    const r = s.run({ FAKE_LIST: ownRow('0123456789ab'), FAKE_HOST: '0123456789ab', FAKE_LABEL: label, FAKE_RUNNING: 'true' });
+    const r = s.run({ FAKE_LIST: ownRow(OTHER_HOST), FAKE_HOST: OTHER_HOST, FAKE_LABEL: label, FAKE_RUNNING: 'true' });
     assert.match(r.stdout, /path=recreated/);
     assert.doesNotMatch(r.calls, /volume rm/);
   } finally { rmSync(s.dir, { recursive: true, force: true }); }
 });
 
-test('the slot strips a trailing -<hostname> only when it is exactly this container\'s hostname', () => {
+test('runnerSlot strips a trailing -<hostname> only when it is exactly the injected hostname', () => {
+  assert.equal(runnerSlot('xema-fox1-2f7dad65784b', '2f7dad65784b'), 'xema-fox1');
+  assert.equal(runnerSlot('xema-fox1-2f7dad65784b', 'aaaaaaaaaaaa'), 'xema-fox1-2f7dad65784b');
+  assert.equal(runnerSlot('xema-fox1-2f7dad65784b', 'f7dad65784b'), 'xema-fox1-2f7dad65784b', 'a suffix of the id is not the id');
+  assert.equal(runnerSlot('xema-fox1-2f7dad65784b', 'ad65784b'), 'xema-fox1-2f7dad65784b');
+  assert.equal(runnerSlot('2f7dad65784b', '2f7dad65784b'), '2f7dad65784b', 'the whole name is kept: there is no slot left to strip to');
+  assert.equal(runnerSlot('Owl Runner/1', ''), 'owl-runner-1');
+  assert.throws(() => runnerSlot('', 'host'), /RUNNER_NAME/);
+});
+
+test('the verb names the builder and its volume from the stripped slot', () => {
   const s = sandbox();
   try {
-    const same = s.run({ RUNNER_NAME: `xema-fox1-${HOST}` });
-    assert.match(same.stdout, /builder=xema-buildkit-signed-xema-fox1 /);
-    assert.match(same.calls, /-v xema-buildkit-signed-xema-fox1-state:/);
-    const other = s.run({ RUNNER_NAME: 'xema-fox1-2f7dad65784b' });
-    assert.match(other.stdout, /builder=xema-buildkit-signed-xema-fox1-2f7dad65784b /);
-    const whole = s.run({ RUNNER_NAME: HOST });
-    assert.match(whole.stdout, new RegExp(`builder=xema-buildkit-signed-${HOST.toLowerCase().replace(/[^a-z0-9_.-]/g, '-')} `));
+    // HOST is only the value the process under test will read; the case is true whatever it is.
+    const r = s.run({ RUNNER_NAME: `xema-fox1-${HOST}` });
+    assert.match(r.stdout, /builder=xema-buildkit-signed-xema-fox1 /);
+    assert.match(r.calls, /-v xema-buildkit-signed-xema-fox1-state:/);
   } finally { rmSync(s.dir, { recursive: true, force: true }); }
 });
 

package/src/composed-image-in-image.mjs

@@ -3,11 +3,13 @@
 // THE IN-IMAGE HALF OF THE COMPOSED-PROCESS BUILD.
 //
 // The prebuilt Dockerfile bind-mounts a copy of this package's `package.json` + `src/`
-// (NO node_modules) and runs THIS file for `pins`, `index`, `load`, `sync-injected` and
-// `prisma-check`. So this module and everything it imports load only `node:` builtins and
-// relative modules; a bare package import would die with ERR_MODULE_NOT_FOUND in the image
-// (`composed-image-in-image-closure.test.mjs` proves it). `composed-image.mjs` re-exports
-// these functions and dispatches the same verbs outside Docker.
+// (NO node_modules) and runs THIS file for `pins`, `index`, `load`, `sync-injected`,
+// `prisma-check` and `prisma-schema-engine`. So this module and everything it imports
+// load only `node:` builtins and relative modules; a bare package import would die with
+// ERR_MODULE_NOT_FOUND in the image (`composed-image-in-image-closure.test.mjs` proves
+// it). `composed-image.mjs` re-exports these functions and dispatches the same verbs
+// outside Docker, except `prisma-schema-engine`, which writes into the installed tree and
+// so runs only in the image.
 // ═══════════════════════════════════════════════════════════════════════════
 
 import { spawnSync } from 'node:child_process';
@@ -20,6 +22,7 @@ import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
 import { readMembers } from './composed-image-members.mjs';
 import { syncInjected } from './composed-image-sync-injected.mjs';
 import { prismaCheck } from './composed-image-prisma-check.mjs';
+import { installPrismaSchemaEngine } from './composed-image-prisma-engine.mjs';
 
 export const MEMBER_INDEX_FILE = 'xema-composed-member-index.json';
 export const HOST_LINK = 'xema-composed-process';
@@ -182,7 +185,7 @@ export function loadMembersEach({ root = process.cwd(), imageDir = COMPOSED_IMAG
 
 const USAGE =
   'usage: composed-image-in-image <command> [--root <dir>] [--image-dir <dir>]\n' +
-  '  pins <committed-lockfile> | index <commit> --build-source <repo> | load [--each] | sync-injected | prisma-check';
+  '  pins <committed-lockfile> | index <commit> --build-source <repo> | load [--each] | sync-injected | prisma-check | prisma-schema-engine <staged dir>';
 
 function parseInImageArguments(argv) {
   const positional = [];
@@ -234,6 +237,8 @@ export function main(argv, { log = console.log } = {}) {
       return;
     case 'prisma-check':
       return prismaCheck({ root, imageDir, log }).then(() => undefined);
+    case 'prisma-schema-engine':
+      return installPrismaSchemaEngine({ root, stagedDir: argument === undefined ? undefined : resolve(argument), log }).then(() => undefined);
     default:
       throw new Error(USAGE);
   }

package/src/composed-image-prebuilt-dockerfile.mjs

@@ -11,6 +11,7 @@ import { COMPOSED_IMAGE_DIR, IN_IMAGE_ENTRY } from './composed-image-paths.mjs';
 import { toolVersion } from './composed-image-stage.mjs';
 import { NODE_BASE, npmrcUsesToken } from './composed-image-dockerfile.mjs';
 import { memberClosure, memberFilters, memberManifests } from './composed-image-members.mjs';
+import { needsPrismaSchemaEngine } from './composed-image-prisma-engine.mjs';
 
 export const DEFAULT_STAGE_DIR = '.xema-stage';
 const DIRECTORY = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*\/?$/;
@@ -139,6 +140,31 @@ export function memberProdPackages({ root = process.cwd(), imageDir = COMPOSED_I
   return [...seen].map(([name, dir]) => ({ name, dir }));
 }
 
+/** Where the deps stage bind-mounts `<stage dir>/prisma-engines` (`<enginesVersion>/schema-engine-<binaryTarget>`). */
+const PRISMA_ENGINES_MOUNT = '/xema-prisma-engines';
+
+/**
+ * The deps-stage step that puts the Prisma schema engine where Prisma looks, rendered only when the
+ * prod closure carries the prisma CLI (the one thing that runs the engine). It runs in DEPS so the
+ * engine lands in `node_modules/.pnpm/@prisma+engines@<v>/node_modules/@prisma/engines/`, which the
+ * final stage takes from deps (layer 1); assemble's copy excludes the .pnpm store.
+ */
+function prismaSchemaEngineStep({ toolMount, node, stageDir }) {
+  return `
+# The Prisma SCHEMA ENGINE for this image's platform. \`prisma migrate deploy\` runs it (the
+# Rust-free client does not replace it), and the prisma CLI downloads it into @prisma/engines
+# at RUNTIME when it is missing, which the read-only, non-root container refuses. The install
+# above is --ignore-scripts, so @prisma/engines' postinstall never fetched it. The runner
+# staged it for every image platform at the lockfile's engines version (Prisma's downloader,
+# sha256-checked) in \`${stageDir}/prisma-engines/\`; this copies the one for the platform
+# Prisma computes HERE into each @prisma/engines a prisma CLI resolves, and fails the build
+# unless it runs and reports that version. Here in deps, so the final stage carries it.
+RUN --network=none ${toolMount} \\
+  --mount=type=bind,source=${stageDir}/prisma-engines,target=${PRISMA_ENGINES_MOUNT} \\
+  node ${node} prisma-schema-engine ${PRISMA_ENGINES_MOUNT}
+`;
+}
+
 const parts = (sources) => sources.map((source) => `    ${source} \\`).join('\n');
 
 /** The prebuilt Dockerfile text. The closure and the members' literal filters are derived from `root` (`memberClosure`); `exec` is injectable for tests. */
@@ -252,7 +278,7 @@ ${secret}  ${toolMount} \\
   node ${node} pins${dirFlag} /tmp/pnpm-lock.committed.yaml && \\
   pnpm install --prod --offline --ignore-scripts \${INJECT} ${filters} --frozen-lockfile${rebuild.length === 0 ? '' : ` && \\
   pnpm rebuild ${rebuild.join(' ')} ${filters}`}
-
+${needsPrismaSchemaEngine(prodPackages) ? prismaSchemaEngineStep({ toolMount, node, stageDir }) : ''}
 FROM deps AS assemble
 COPY --parents \\
 ${parts(assembleSources)}

package/src/composed-image-prebuilt-dockerfile.test.mjs

@@ -175,3 +175,27 @@ test('memberProdPackages reads the installed prod closure and refuses an empty o
   assert.deepEqual(depsCopyDirs(dockerfile), ['tooling/dev/', 'tooling/ci/']);
   assert.deepEqual(depsCopyDirs(renderPrebuiltDockerfile(options(root, { copy: [] })).dockerfile), []);
 });
+
+test('the Prisma schema engine step renders in deps only when the prod closure carries the prisma CLI; otherwise the bytes are unchanged', () => {
+  const root = workspace();
+  const without = renderPrebuiltDockerfile(options(root, { prodPackages: [installed(root, 'left-pad'), installed(root, '@prisma/client')] })).dockerfile;
+  assert.equal(without, renderPrebuiltDockerfile(options(root)).dockerfile);
+  assert.doesNotMatch(without, /prisma-schema-engine|prisma-engines/);
+
+  const withCli = renderPrebuiltDockerfile(options(root, { prodPackages: [installed(root, 'prisma'), installed(root, '@prisma/engines')] })).dockerfile;
+  const step =
+    'RUN --network=none --mount=type=bind,source=.xema-stage/tool,target=/opt/xema-composed-image \\\n' +
+    '  --mount=type=bind,source=.xema-stage/prisma-engines,target=/xema-prisma-engines \\\n' +
+    '  node /opt/xema-composed-image/src/composed-image-in-image.mjs prisma-schema-engine /xema-prisma-engines\n';
+  assert.equal(withCli.split(step).length, 2, 'exactly one engine step');
+  const [deps, rest] = withCli.split('FROM deps AS assemble');
+  assert.ok(deps.includes(step), 'the step is in deps, whose /monorepo the final stage copies whole (.pnpm included)');
+  assert.ok(deps.indexOf(step) > deps.indexOf('pnpm install --prod --offline --ignore-scripts'), 'after the install');
+  assert.doesNotMatch(rest, /prisma-schema-engine/);
+  // Only the commented step is added: removing it gives back the render without the CLI.
+  const added = /\n# The Prisma SCHEMA ENGINE[\s\S]*?prisma-schema-engine \/xema-prisma-engines\n/.exec(withCli)[0];
+  assert.equal(withCli.replace(added, ''), without);
+
+  const custom = renderPrebuiltDockerfile(options(root, { stageDir: 'build/stage', prodPackages: [installed(root, 'prisma')] })).dockerfile;
+  assert.match(custom, /--mount=type=bind,source=build\/stage\/prisma-engines,target=\/xema-prisma-engines/);
+});

package/src/composed-image-prisma-engine.mjs

@@ -0,0 +1,89 @@
+// `xema-composed-image prisma-schema-engine <staged dir>`, INSIDE the prebuilt image
+// build, `--network=none`, on the TARGET arch, right after the deps stage's offline
+// `pnpm install --prod --ignore-scripts`.
+//
+// `prisma migrate deploy` runs Prisma's NATIVE schema engine (the Rust-free client does
+// not replace it). Before every migrate command the prisma CLI calls @prisma/engines'
+// `ensureNeededBinariesExist`, which looks for `schema-engine-<binaryTarget>` in the
+// @prisma/engines package directory and, when it is absent or reports another version,
+// downloads it INTO that directory. A read-only, non-root container refuses the write
+// ("Can't write to …/@prisma/engines"). The install runs `--ignore-scripts`, so the
+// postinstall that would have fetched it never ran.
+//
+// The runner staged the engine for every image platform with Prisma's own downloader
+// (which verifies each file against its published sha256), at the engines version the
+// lockfile pins, as `<staged dir>/<enginesVersion>/schema-engine-<binaryTarget>`. This
+// copies, for every prisma CLI the install carries, the engine for the platform Prisma
+// computes HERE to the exact path Prisma looks at, then runs it and refuses the build
+// unless it reports the pinned engines version: the same check Prisma makes before it
+// decides to download. No environment variable points at it.
+//
+// Loads only `node:` builtins (see composed-image-in-image.mjs); Prisma's own modules are
+// resolved from the installed tree.
+import { spawnSync } from 'node:child_process';
+import { chmodSync, copyFileSync, existsSync, readdirSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+/** The prod-closure package whose presence makes the image need the schema engine: the CLI that runs it. */
+export const PRISMA_CLI = 'prisma';
+
+/** True when the members' prod closure (`[{ name }]`) carries the prisma CLI. */
+export const needsPrismaSchemaEngine = (prodPackages) => prodPackages.some((p) => p.name === PRISMA_CLI);
+
+/** Every distinct @prisma/engines directory (realpath) a prisma CLI under `<root>/node_modules/.pnpm` resolves. */
+export function prismaEnginesDirectories(root) {
+  const store = join(root, 'node_modules', '.pnpm');
+  if (!existsSync(store)) throw new Error(`${store} does not exist: run the install first`);
+  const directories = new Set();
+  for (const entry of readdirSync(store).filter((name) => name.startsWith(`${PRISMA_CLI}@`)).sort()) {
+    const manifest = join(store, entry, 'node_modules', PRISMA_CLI, 'package.json');
+    if (!existsSync(manifest)) continue;
+    let engines;
+    try {
+      engines = createRequire(manifest).resolve('@prisma/engines/package.json');
+    } catch (error) {
+      throw new Error(`${dirname(manifest)} does not resolve @prisma/engines: ${error?.message ?? String(error)}`);
+    }
+    directories.add(dirname(realpathSync(engines)));
+  }
+  return [...directories];
+}
+
+const runVersion = (file) => spawnSync(file, ['--version'], { encoding: 'utf8' });
+
+/**
+ * Install the staged schema engine into every @prisma/engines directory a prisma CLI resolves.
+ * `binaryTarget` and `version` are injectable for tests; by default they are Prisma's own
+ * (`@prisma/get-platform` and the engine's `--version`, resolved from each @prisma/engines).
+ */
+export async function installPrismaSchemaEngine({ root = process.cwd(), stagedDir, log = console.log, binaryTarget, version = runVersion } = {}) {
+  if (typeof stagedDir !== 'string' || stagedDir.length === 0) throw new Error('prisma-schema-engine needs the staged engines directory');
+  if (!existsSync(stagedDir)) throw new Error(`${stagedDir} does not exist: stage the Prisma schema engines into it before the image build`);
+  const directories = prismaEnginesDirectories(root);
+  if (directories.length === 0) {
+    throw new Error(`no ${PRISMA_CLI} CLI is installed under ${join(root, 'node_modules', '.pnpm')}, yet the Dockerfile was rendered for one: re-render it`);
+  }
+  const installed = [];
+  for (const enginesDir of directories) {
+    const fromEngines = createRequire(join(enginesDir, 'package.json'));
+    const { enginesVersion } = fromEngines('@prisma/engines-version');
+    const target = binaryTarget ?? (await fromEngines('@prisma/get-platform').getBinaryTargetForCurrentPlatform());
+    const fileName = `schema-engine-${target}`;
+    const source = join(stagedDir, enginesVersion, fileName);
+    if (!existsSync(source)) {
+      throw new Error(`no staged schema engine ${source} (engines ${enginesVersion}, platform ${target}): stage it for every image platform at the lockfile's engines version`);
+    }
+    const destination = join(enginesDir, fileName);
+    copyFileSync(source, destination);
+    chmodSync(destination, 0o755);
+    const result = version(destination);
+    if (result.error || result.status !== 0 || !String(result.stdout ?? '').includes(enginesVersion)) {
+      const detail = String(result.stdout || result.stderr || result.error?.message || '').trim();
+      throw new Error(`${destination} --version did not report ${enginesVersion}: status ${result.status}${detail === '' ? '' : `, ${detail}`}`);
+    }
+    log(`prisma schema engine: ${destination} (${String(result.stdout).trim()})`);
+    installed.push(destination);
+  }
+  return installed;
+}

package/src/composed-image-prisma-engine.test.mjs

@@ -0,0 +1,73 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test, { after } from 'node:test';
+
+import { installPrismaSchemaEngine, needsPrismaSchemaEngine, prismaEnginesDirectories } from './composed-image-prisma-engine.mjs';
+
+const VERSION = '7.8.0-6.abc';
+const temps = [];
+after(() => {
+  for (const dir of temps) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function write(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text);
+}
+
+/** A pnpm-layout tree: prisma@7.8.0 -> @prisma/engines@7.8.0 -> @prisma/engines-version, and a staged engines dir. */
+function tree({ stagedTargets = ['debian-openssl-3.0.x', 'linux-arm64-openssl-3.0.x'], cli = true } = {}) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-prisma-engine-'));
+  temps.push(root);
+  const store = path.join(root, 'node_modules', '.pnpm');
+  const engines = path.join(store, '@prisma+engines@7.8.0', 'node_modules', '@prisma', 'engines');
+  write(path.join(engines, 'package.json'), JSON.stringify({ name: '@prisma/engines', main: 'index.js' }));
+  write(path.join(engines, 'index.js'), 'module.exports = {};');
+  const version = path.join(store, '@prisma+engines@7.8.0', 'node_modules', '@prisma', 'engines-version');
+  write(path.join(version, 'package.json'), JSON.stringify({ name: '@prisma/engines-version', main: 'index.js' }));
+  write(path.join(version, 'index.js'), `module.exports = { enginesVersion: ${JSON.stringify(VERSION)} };`);
+  if (cli) {
+    const prisma = path.join(store, 'prisma@7.8.0_typescript@5.9.3', 'node_modules');
+    write(path.join(prisma, 'prisma', 'package.json'), JSON.stringify({ name: 'prisma' }));
+    fs.mkdirSync(path.join(prisma, '@prisma'), { recursive: true });
+    fs.symlinkSync(engines, path.join(prisma, '@prisma', 'engines'));
+  }
+  const staged = path.join(root, 'staged');
+  for (const target of stagedTargets) write(path.join(staged, VERSION, `schema-engine-${target}`), `engine ${target}`);
+  return { root, engines: fs.realpathSync(engines), staged };
+}
+
+const reports = (text) => () => ({ status: 0, stdout: `schema-engine-cli ${text}\n` });
+
+test('needsPrismaSchemaEngine: only the prisma CLI in the prod closure asks for the engine', () => {
+  assert.equal(needsPrismaSchemaEngine([{ name: 'prisma' }, { name: 'x' }]), true);
+  assert.equal(needsPrismaSchemaEngine([{ name: '@prisma/client' }, { name: '@prisma/engines' }]), false);
+  assert.equal(needsPrismaSchemaEngine([]), false);
+});
+
+test('the engine for the computed platform lands in the @prisma/engines the CLI resolves (realpath), executable, version-checked', async () => {
+  const { root, engines, staged } = tree();
+  assert.deepEqual(prismaEnginesDirectories(root), [engines]);
+  const lines = [];
+  const installed = await installPrismaSchemaEngine({ root, stagedDir: staged, binaryTarget: 'linux-arm64-openssl-3.0.x', version: reports(VERSION), log: (l) => lines.push(l) });
+  const target = path.join(engines, 'schema-engine-linux-arm64-openssl-3.0.x');
+  assert.deepEqual(installed, [target]);
+  assert.equal(fs.readFileSync(target, 'utf8'), 'engine linux-arm64-openssl-3.0.x');
+  assert.equal(fs.statSync(target).mode & 0o777, 0o755);
+  assert.equal(fs.existsSync(path.join(engines, 'schema-engine-debian-openssl-3.0.x')), false, 'only the computed platform');
+  assert.match(lines[0], new RegExp(`${VERSION}`));
+});
+
+test('the build fails loudly: no staged file for the platform, a wrong version, a failing engine, no CLI, no staged dir', async () => {
+  const { root, staged } = tree({ stagedTargets: ['debian-openssl-3.0.x'] });
+  const run = (extra) => installPrismaSchemaEngine({ root, stagedDir: staged, binaryTarget: 'debian-openssl-3.0.x', version: reports(VERSION), log: () => {}, ...extra });
+  await assert.rejects(run({ binaryTarget: 'linux-arm64-openssl-3.0.x' }), /no staged schema engine .*schema-engine-linux-arm64-openssl-3\.0\.x \(engines 7\.8\.0-6\.abc, platform linux-arm64/);
+  await assert.rejects(run({ version: reports('7.7.0-1.other') }), /--version did not report 7\.8\.0-6\.abc/);
+  await assert.rejects(run({ version: () => ({ status: null, error: new Error('Exec format error') }) }), /did not report .*Exec format error/);
+  await assert.rejects(run({ stagedDir: path.join(root, 'absent') }), /does not exist: stage the Prisma schema engines/);
+  await assert.rejects(run({ stagedDir: undefined }), /needs the staged engines directory/);
+  const bare = tree({ cli: false });
+  await assert.rejects(installPrismaSchemaEngine({ root: bare.root, stagedDir: bare.staged, binaryTarget: 'debian-openssl-3.0.x', log: () => {} }), /no prisma CLI is installed/);
+});

package/src/prepush-sanity.mjs

@@ -6,8 +6,8 @@
 //
 // With turbo (a `turbo.json` and a turbo dependency): turbo `lint` and `typecheck` run only on the packages
 // the pushed commits change plus their dependents. A change to the lockfile,
-// root package.json or turbo.json invalidates everything and runs the full
-// graph. A repo whose turbo carries no `lint` task also runs its root `lint`
+// turbo.json, or anything in the root package.json other than its `scripts`
+// table invalidates everything and runs the full graph. A repo whose turbo carries no `lint` task also runs its root `lint`
 // script. Without turbo: the root `lint` script only (typecheck needs a build, which the hook never runs; CI has it).
 //
 // The pushed SHA is what is graded. In place when the tree is clean and the SHA
@@ -80,9 +80,20 @@ export function parseRefs(stdin) {
   return refs;
 }
 
-/** True when a changed path invalidates every package. */
-export function isFleetWide(changedPaths) {
-  return changedPaths.some((p) => p === 'pnpm-lock.yaml' || p === 'package.json' || p === 'turbo.json');
+/** True when two root package.json texts differ only in the top-level `scripts` key; a missing side or unparseable JSON is false. */
+export function scriptsOnlyChange(baseText, tipText) {
+  try {
+    const { scripts: _baseScripts, ...base } = JSON.parse(baseText);
+    const { scripts: _tipScripts, ...tip } = JSON.parse(tipText);
+    return JSON.stringify(base) === JSON.stringify(tip);
+  } catch {
+    return false;
+  }
+}
+
+/** True when a changed path invalidates every package. `rootScriptsOnly`: the root package.json change is the `scripts` table alone. */
+export function isFleetWide(changedPaths, rootScriptsOnly = false) {
+  return changedPaths.some((p) => p === 'pnpm-lock.yaml' || p === 'turbo.json' || (p === 'package.json' && !rootScriptsOnly));
 }
 
 /**
@@ -148,8 +159,9 @@ function rangeFor(ctx, base, sha) {
     return '';
   }
   const changed = (ctx.gitOut(['diff', '--name-only', `${base}...${sha}`]) ?? '').split('\n').filter(Boolean);
-  if (isFleetWide(changed)) {
-    console.error('pre-push: lockfile, root package.json or turbo.json changed — fleet-wide, running the FULL graph.');
+  const rootScriptsOnly = changed.includes('package.json') && scriptsOnlyChange(ctx.gitOut(['show', `${base}:package.json`]) ?? '', ctx.gitOut(['show', `${sha}:package.json`]) ?? '');
+  if (isFleetWide(changed, rootScriptsOnly)) {
+    console.error('pre-push: lockfile, turbo.json or root package.json beyond its scripts changed — fleet-wide, running the FULL graph.');
     return '';
   }
   return `${base}...${sha}`;

package/src/prepush-sanity.test.mjs

@@ -5,7 +5,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { test } from 'node:test';
 import { fileURLToPath } from 'node:url';
-import { blockingPath, isFleetWide, parseRefs, stripJsonc, turboCacheDir, turboTasks } from './prepush-sanity.mjs';
+import { blockingPath, isFleetWide, parseRefs, scriptsOnlyChange, stripJsonc, turboCacheDir, turboTasks } from './prepush-sanity.mjs';
 
 const VERB = fileURLToPath(new URL('./prepush-sanity.mjs', import.meta.url));
 const SHA_A = 'a'.repeat(40);
@@ -29,12 +29,26 @@ test('parseRefs dedupes shas and drops deletes and junk', () => {
   assert.deepEqual(parseRefs(''), []);
 });
 
-test('isFleetWide flags only the lockfile, root package.json and turbo.json', () => {
+test('isFleetWide flags the lockfile, turbo.json and a root package.json change beyond scripts', () => {
   assert.equal(isFleetWide(['pnpm-lock.yaml']), true);
+  assert.equal(isFleetWide(['turbo.json']), true);
   assert.equal(isFleetWide(['package.json']), true);
+  assert.equal(isFleetWide(['package.json'], true), false);
+  assert.equal(isFleetWide(['package.json', 'pnpm-lock.yaml'], true), true);
   assert.equal(isFleetWide(['packages/a/package.json', 'src/x.ts']), false);
 });
 
+test('scriptsOnlyChange: only the scripts key may differ; anything else or unreadable is fleet-wide', () => {
+  const base = { name: 't', scripts: { a: '1' }, dependencies: { x: '1' }, packageManager: 'pnpm@10.0.0' };
+  const text = (o) => JSON.stringify(o);
+  assert.equal(scriptsOnlyChange(text(base), text({ ...base, scripts: { a: '2', b: '3' } })), true);
+  for (const change of [{ dependencies: { x: '2' } }, { packageManager: 'pnpm@10.1.0' }, { pnpm: { overrides: {} } }, { engines: { node: '22' } }]) {
+    assert.equal(scriptsOnlyChange(text(base), text({ ...base, ...change })), false, Object.keys(change)[0]);
+  }
+  assert.equal(scriptsOnlyChange('', text(base)), false);
+  assert.equal(scriptsOnlyChange(text(base), '{ nope'), false);
+});
+
 test('blockingPath: package reads and repo-root files block, root markdown does not', () => {
   const owned = (p) => p.startsWith('packages/');
   assert.equal(blockingPath(['packages/a/src/x.ts'], ['packages/a'], owned)?.why, 'is in a package this run reads');

package/src/promote-image-provenance.mjs

@@ -22,7 +22,7 @@
 // nearest commit, is an error; the selected statements must all yield the same source and developProvenance.
 
 import { createHash } from 'node:crypto';
-import { describeFailure, runTool } from './promote-image-registry.mjs';
+import { DIGEST_PATTERN, describeFailure, isImageIndex, readManifestByDigest, runTool } from './promote-image-registry.mjs';
 
 export const GITHUB_SERVER = 'https://github.com';
 export const GITHUB_OIDC_ISSUER = 'https://token.actions.githubusercontent.com';
@@ -145,7 +145,7 @@ function attestationTypes(subject, label, run) {
  * Returns `undefined` when the digest carries no promotion attestation (a legacy image); a registry error, a signature or identity
  * failure, or a source outside `<registry>/<owner>/dev/`, is an error.
  */
-export function reuseEarlierPromotion({ releaseRef, tag, digest, repository, releaseWorkflows, commit }, run = runTool) {
+export function reuseEarlierPromotion({ releaseRef, tag, digest, repository, releaseWorkflows, commit, exactCommit = false }, run = runTool) {
   const subject = `${releaseRef}@${digest}`;
   const label = 'reuse';
   // (a) presence, without identity verification: only the predicate types are read
@@ -165,6 +165,8 @@ export function reuseEarlierPromotion({ releaseRef, tag, digest, repository, rel
   const nearest = nearestPromotedCommit(
     new Set(about.map(promoted).filter((value) => typeof value === 'string' && COMMIT.test(value))), commit, subject, label, run,
   );
+  // `exactCommit`: only a statement promoting this very commit counts; an ancestor's is `undefined` (the caller's miss)
+  if (exactCommit && nearest !== commit) return undefined;
   const selected = about.filter((statement) => promoted(statement) === nearest);
   const admitted = new Set(selected.map((statement) => JSON.stringify(admissible(statement, { subject, tag, digest, releaseRef, repository, label }))));
   if (admitted.size !== 1) {
@@ -201,6 +203,60 @@ function admissible(statement, { subject, tag, digest, releaseRef, repository, l
   };
 }
 
+// cosign v2's definite "this digest is not signed by that identity" answers; any other failure is an error.
+const NO_MATCHING_SIGNATURE = /\bno (?:matching )?signatures\b/i;
+
+/**
+ * Whether `subject` carries a signature by `pattern` (GitHub OIDC issuer). A definite "no matching signature" is
+ * `false`; a failure to run cosign or any other cosign failure is an error.
+ */
+function hasSignature(subject, pattern, label, run) {
+  const verified = run('cosign', ['verify', '--certificate-identity-regexp', pattern, '--certificate-oidc-issuer', GITHUB_OIDC_ISSUER, subject]);
+  if (verified.error) throw new Error(`${label}: could not run cosign to verify ${subject}: ${verified.error.message}`);
+  if (verified.status === 0) return true;
+  const detail = describeFailure(verified);
+  if (verified.status === 1 && NO_MATCHING_SIGNATURE.test(detail)) return false;
+  throw new Error(`${label}: verifying the signature of ${subject} failed: ${detail}`);
+}
+
+/**
+ * Reuse of a release tag that release-arm64 already moved from main's amd64 digest A to a multi-arch index D. Every
+ * step fails closed: `undefined` (the caller's existing miss) unless ALL of
+ *   (1) `releaseDigest` (what `<releaseRef>:<tag>` resolves to), read by digest, is an image index D;
+ *   (2) D is signed by `indexWorkflow` of `repository` on main;
+ *   (3) D has exactly one linux/amd64 child A (two are refused as ambiguous);
+ *   (4) A carries a verified image-promotion/v1 statement under main's `releaseWorkflows` whose selected (nearest)
+ *       promotedCommit IS `commit` (a rerun; an ancestor's is the miss), bound to this repository, tag and digest A
+ *       (`reuseEarlierPromotion`, whose refusals stay errors).
+ * Returns `{ digest: A, index: D, source, developProvenance }`.
+ */
+export function reuseThroughReleaseIndex({ releaseRef, tag, releaseDigest, repository, releaseWorkflows, indexWorkflow, commit }, run = runTool) {
+  const label = 'reuse via release index';
+  const index = releaseDigest;
+  // (1) an index, read by digest and hash-checked
+  const manifest = readManifestByDigest(releaseRef, index, run);
+  if (!isImageIndex(manifest)) return undefined;
+  // (2) signed by the index workflow on main
+  if (!hasSignature(`${releaseRef}@${index}`, workflowIdentityPattern(repository, [indexWorkflow], 'main'), label, run)) return undefined;
+  // (3) exactly one linux/amd64 child
+  const amd64 = (Array.isArray(manifest.manifests) ? manifest.manifests : [])
+    .filter((child) => child?.platform?.os === 'linux' && child.platform.architecture === 'amd64');
+  if (amd64.length === 0) return undefined;
+  if (amd64.length > 1) {
+    throw new Error(`${label}: ambiguous: index ${releaseRef}@${index} has ${amd64.length} linux/amd64 children (${amd64.map((child) => child.digest).join(', ')})`);
+  }
+  const digest = amd64[0].digest;
+  if (typeof digest !== 'string' || !DIGEST_PATTERN.test(digest) || digest === index) {
+    throw new Error(`${label}: index ${releaseRef}@${index} names no sha256 linux/amd64 child digest: ${digest}`);
+  }
+  // (4) the existing promotion verification of A, select-by-promotedCommit included
+  // ... restricted to a statement promoting this very `commit` (a rerun): a later commit with the same content must
+  // take the existing path and attest its own promotion, never reuse one that carries none
+  const earlier = reuseEarlierPromotion({ releaseRef, tag, digest, repository, releaseWorkflows, commit, exactCommit: true }, run);
+  if (earlier === undefined) return undefined;
+  return { digest, index, ...earlier };
+}
+
 /**
  * Whether `<devRef>@<digest>` carries any SLSA v1 provenance attestation, listed without verifying a signature. A digest
  * with none (an image reused on develop from before provenance) is not promotable but not an error; a registry error is.

package/src/promote-image-registry.mjs

@@ -9,6 +9,7 @@
 // behind a rebuild.
 
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 
 export const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
 
@@ -61,3 +62,28 @@ export function copyByDigest(source, target, run = runTool) {
     throw new Error(`copying ${source} to ${target} failed: ${describeFailure(result)}`);
   }
 }
+
+const INDEX_MEDIA_TYPES = Object.freeze(['application/vnd.oci.image.index.v1+json', 'application/vnd.docker.distribution.manifest.list.v2+json']);
+
+/**
+ * Reads the manifest `<repository>@<digest>` BY DIGEST (`imagetools inspect --raw`) and returns it parsed, refusing
+ * unless the bytes hash to `digest` (one trailing newline the printer may add is not part of the manifest).
+ */
+export function readManifestByDigest(repository, digest, run = runTool) {
+  const reference = `${repository}@${digest}`;
+  const result = run('docker', ['buildx', 'imagetools', 'inspect', reference, '--raw']);
+  if (result.error || result.status !== 0) throw new Error(`reading the manifest of ${reference} failed: ${describeFailure(result)}`);
+  const raw = String(result.stdout ?? '');
+  const hashes = (text) => `sha256:${createHash('sha256').update(text, 'utf8').digest('hex')}` === digest;
+  if (!hashes(raw) && !(raw.endsWith('\n') && hashes(raw.slice(0, -1)))) {
+    throw new Error(`the manifest read for ${reference} does not hash to ${digest}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`the manifest of ${reference} is not JSON`, { cause: error });
+  }
+}
+
+/** Whether a parsed manifest is an image index (OCI index or Docker manifest list). */
+export const isImageIndex = (manifest) => INDEX_MEDIA_TYPES.includes(manifest?.mediaType);

package/src/promote-image.mjs

@@ -7,7 +7,13 @@
 //      `--release-workflow` identities; the statement of the nearest promotedCommit that is an ancestor of
 //      (or equal to) `--commit` is the evidence (as xema-deploy's deploy verifier selects), and its source must be a
 //      `ghcr.io/<owner>/dev/<name>` reference                  -> reused (evidence=prior-promotion)
-//      - no image-promotion/v1 attestation (a legacy image)    -> miss (reason=reuse-no-promotion): the caller builds
+//      - no image-promotion/v1 attestation (a legacy image)    -> miss (reason=reuse-no-promotion): the caller builds,
+//        unless `--release-index-workflow` is given and the tag names release-arm64's index over main's amd64 digest A:
+//        the index is signed by that workflow on main, has exactly one linux/amd64 child A, and A passes this very
+//        reuse check with a statement promoting `--commit` itself (a rerun)
+//                                                               -> reused (evidence=release-index, digest=A, index_digest=D,
+//        no predicate: the caller neither signs nor attests, tags :<sha>/main-<sha> to A and only the content tag (and
+//        latest) to D); any failed step keeps the miss
 //      - a signature / identity failure, or a source outside dev/ -> error, never a miss
 //   2. else `<dev-ref>:<tag>` exists: prove it (legs a, b, c in
 //      promote-image-provenance.mjs), copy it by digest (`imagetools create`
@@ -17,7 +23,7 @@
 //      - provenance present but any leg fails                  -> error, never a miss
 //   3. else                                                  -> miss: the caller builds.
 //
-// On every non-miss result it writes the promotion predicate
+// On every non-miss result except `evidence=release-index` it writes the promotion predicate
 // (`https://xema.dev/attestations/image-promotion/v1`) to `--promotion-predicate-out`, for the caller to
 // `cosign attest` under main's own identity. A copy states the facts it just proved; a reuse states this run's
 // release and commit and carries `source` and `developProvenance` from main's earlier promotion. It signs
@@ -33,7 +39,7 @@
 // No retries. Every refusal is an error, never a miss.
 //
 // Outputs: `result`, `digest`, `source`, `revision`, `evidence`,
-// `provenance_digest`, `promotion_predicate` and `promotion_predicate_type` appended to `$GITHUB_OUTPUT`
+// `provenance_digest`, `promotion_predicate`, `promotion_predicate_type` (and `index_digest` on evidence=release-index) appended to `$GITHUB_OUTPUT`
 // (required; empty values where a fact does not apply), and one stdout line
 // `promote-image result=<r> digest=<d> src=<repository>@<d> revision=<sha> evidence=<e>`, with ` reason=<why>` appended
 // to a miss that has a reason.
@@ -43,13 +49,14 @@ import process from 'node:process';
 import { describeErrorChain } from '@xemahq/release-policy/registry';
 import { invokedDirectly } from './readiness.mjs';
 import { IMAGE_PROMOTION_PREDICATE_TYPE, promotionPredicate, reusedPromotionPredicate, writePromotionPredicate } from './promote-image-predicate.mjs';
-import { hasDevelopProvenance, reuseEarlierPromotion, verifyDevelopProvenance } from './promote-image-provenance.mjs';
+import { hasDevelopProvenance, reuseEarlierPromotion, reuseThroughReleaseIndex, verifyDevelopProvenance } from './promote-image-provenance.mjs';
 import { copyByDigest, probeDigest, runTool } from './promote-image-registry.mjs';
 
 export const PromoteResult = Object.freeze({ REUSED: 'reused', COPIED: 'copied', MISS: 'miss' });
 export const PromoteEvidence = Object.freeze({
   PRIOR_PROMOTION: 'prior-promotion',
   DEVELOP_PROVENANCE: 'develop-provenance',
+  RELEASE_INDEX: 'release-index',
   NONE: 'none',
 });
 export const PromoteMissReason = Object.freeze({ NO_PROMOTION: 'reuse-no-promotion', NO_DEVELOP_PROVENANCE: 'copy-no-develop-provenance' });
@@ -78,11 +85,13 @@ export function assertCosignMajor(run = runTool) {
 const USAGE =
   'usage: xema-promote-image --service <name> --dev-ref <registry/repository> --release-ref <registry/repository> ' +
   '--tag <content tag> --commit <40-hex> --main-ref <git ref> --signer-repository <owner/repo> ' +
-  '--develop-workflow <file.yaml> --release-workflow <file.yaml>... --promotion-predicate-out <path> -- <tag command>...';
+  '--develop-workflow <file.yaml> --release-workflow <file.yaml>... [--release-index-workflow <file.yaml>] ' +
+  '--promotion-predicate-out <path> -- <tag command>...';
 
 const SINGLE = Object.freeze(['service', 'dev-ref', 'release-ref', 'tag', 'commit', 'main-ref', 'signer-repository',
   'develop-workflow', 'promotion-predicate-out']);
 const REPEATABLE = Object.freeze(['release-workflow']);
+const OPTIONAL = Object.freeze(['release-index-workflow']);
 // A repository reference with no tag and no digest (those are passed separately).
 const REPOSITORY_REF = /^[a-z0-9][a-z0-9.-]*(:[0-9]+)?(\/[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*)+$/;
 // The OCI distribution tag grammar.
@@ -104,7 +113,7 @@ export function parsePromoteArguments(argv) {
     const arg = flags[i];
     const name = arg.startsWith('--') ? arg.slice(2) : undefined;
     const repeatable = REPEATABLE.includes(name);
-    if (name === undefined || (!SINGLE.includes(name) && !repeatable)) throw new Error(`unknown argument ${arg}\n${USAGE}`);
+    if (name === undefined || (!SINGLE.includes(name) && !OPTIONAL.includes(name) && !repeatable)) throw new Error(`unknown argument ${arg}\n${USAGE}`);
     if (!repeatable && options[name] !== undefined) throw new Error(`${arg} given twice`);
     const value = flags[i + 1];
     if (value === undefined || value.startsWith('--') || value === '') throw new Error(`${arg} needs a value`);
@@ -123,7 +132,8 @@ export function parsePromoteArguments(argv) {
   if (!COMMIT.test(options.commit)) refuse('commit', options.commit, 'a 40-hex commit');
   if (options['main-ref'].startsWith('-')) refuse('main-ref', options['main-ref'], 'a git ref');
   if (!GITHUB_REPOSITORY.test(options['signer-repository'])) refuse('signer-repository', options['signer-repository'], 'an owner/repo');
-  for (const file of [options['develop-workflow'], ...options['release-workflow']]) {
+  const indexWorkflow = options['release-index-workflow'];
+  for (const file of [options['develop-workflow'], ...options['release-workflow'], ...(indexWorkflow === undefined ? [] : [indexWorkflow])]) {
     if (!WORKFLOW_FILE.test(file)) throw new Error(`workflow '${file}' is not a workflow file name under .github/workflows`);
   }
   return {
@@ -136,6 +146,7 @@ export function parsePromoteArguments(argv) {
     repository: options['signer-repository'],
     developWorkflow: options['develop-workflow'],
     releaseWorkflows: options['release-workflow'],
+    indexWorkflow,
     predicateOut: options['promotion-predicate-out'],
     tagCommand,
   };
@@ -145,16 +156,31 @@ const MISS = Object.freeze({ result: PromoteResult.MISS, digest: '', source: '',
 
 /**
  * Runs the steps. Returns `{ result, digest, source, evidence, predicate?, revision?, provenanceDigest?, reason? }`;
- * `predicate` is set on every non-miss result, `reason` on a miss that has one.
+ * `predicate` is set on every non-miss result except `evidence=release-index`, `reason` on a miss that has one.
  */
 export function promoteImage(options, run = runTool) {
-  const { service, devRef, releaseRef, tag, commit, repository, releaseWorkflows } = options;
+  const { service, devRef, releaseRef, tag, commit, repository, releaseWorkflows, indexWorkflow } = options;
   assertCosignMajor(run);
   const releaseTagged = `${releaseRef}:${tag}`;
   const released = probeDigest(releaseTagged, run);
   if (released !== undefined) {
     const earlier = reuseEarlierPromotion({ releaseRef, tag, digest: released, repository, releaseWorkflows, commit }, run);
-    if (earlier === undefined) return { ...MISS, reason: PromoteMissReason.NO_PROMOTION };
+    if (earlier === undefined) {
+      const viaIndex = indexWorkflow === undefined
+        ? undefined
+        : reuseThroughReleaseIndex({ releaseRef, tag, releaseDigest: released, repository, releaseWorkflows, indexWorkflow, commit }, run);
+      if (viaIndex === undefined) return { ...MISS, reason: PromoteMissReason.NO_PROMOTION };
+      // release-arm64 already merged A into the index the tag names: nothing to sign or attest, no predicate.
+      return {
+        result: PromoteResult.REUSED,
+        digest: viaIndex.digest,
+        source: viaIndex.source.reference,
+        evidence: PromoteEvidence.RELEASE_INDEX,
+        revision: viaIndex.source.revision,
+        provenanceDigest: viaIndex.developProvenance.payloadDigest,
+        indexDigest: viaIndex.index,
+      };
+    }
     return {
       result: PromoteResult.REUSED,
       digest: released,
@@ -196,7 +222,7 @@ export function main(argv, { githubOutput, run = runTool, write = (text) => proc
   if (existsSync(options.predicateOut)) {
     throw new Error(`--promotion-predicate-out ${options.predicateOut} already exists; refusing to leave a stale predicate to attest`);
   }
-  const { result, digest, source, evidence, predicate, revision, provenanceDigest, reason } = promoteImage(options, run);
+  const { result, digest, source, evidence, predicate, revision, provenanceDigest, reason, indexDigest } = promoteImage(options, run);
   if (predicate !== undefined) writePromotionPredicate(options.predicateOut, predicate);
   const outputs = {
     result,
@@ -207,6 +233,7 @@ export function main(argv, { githubOutput, run = runTool, write = (text) => proc
     provenance_digest: provenanceDigest ?? '',
     promotion_predicate: predicate === undefined ? '' : options.predicateOut,
     promotion_predicate_type: predicate === undefined ? '' : IMAGE_PROMOTION_PREDICATE_TYPE,
+    ...(indexDigest === undefined ? {} : { index_digest: indexDigest }),
   };
   appendFileSync(githubOutput, Object.entries(outputs).map(([key, value]) => `${key}=${value}\n`).join(''));
   write(`promote-image result=${result} digest=${digest} src=${source} revision=${outputs.revision} evidence=${evidence}${reason === undefined ? '' : ` reason=${reason}`}\n`);

package/src/promote-image.test.mjs

@@ -22,6 +22,7 @@ const PROMOTION_TYPE = 'https://xema.dev/attestations/image-promotion/v1';
 // A fake `docker`, `cosign` and `git` on PATH, and a fake tag command, all
 // answering from one JSON state file:
 //   tags / errors / copyDigest   `docker buildx imagetools inspect|create`
+//   raw[repository@digest]       the manifest bytes `docker buildx imagetools inspect --raw` prints
 //   signatures[subject]          the identity `cosign verify` finds
 //   downloadErrors[subject]      what `cosign download attestation` fails with
 //   attestations[subject]        { identity, statements, type? } (type defaults to slsaprovenance1) `cosign verify-attestation` finds
@@ -45,6 +46,11 @@ if (tool === 'docker') {
   if (args[2] === 'inspect') {
     const ref = args[3];
     if (state.errors[ref]) fail(state.errors[ref]);
+    if (args[4] === '--raw') {
+      if (state.raw?.[ref] === undefined) fail('ERROR: ' + ref + ': not found\\n');
+      process.stdout.write(state.raw[ref]);
+      process.exit(0);
+    }
     if (!state.tags[ref]) fail('ERROR: ' + ref + ': not found\\n');
     process.stdout.write(JSON.stringify({ mediaType: 'application/vnd.oci.image.index.v1+json', digest: state.tags[ref] }));
     process.exit(0);
@@ -203,10 +209,10 @@ function promotionStatement({ subjectDigest = OTHER, predicateType = PROMOTION_T
 
 // A release digest main already promoted: its image-promotion/v1 attestation(s), signed by a main workflow.
 // `lineage` defaults to EARLIER_COMMIT being an ancestor of COMMIT.
-function promotedRelease({ source, identity = MAIN_IDENTITY, type = PROMOTION_TYPE, extra, statements, lineage = [[EARLIER_COMMIT, COMMIT]] } = {}) {
+function promotedRelease({ source, identity = MAIN_IDENTITY, type = PROMOTION_TYPE, extra, statements, lineage = [[EARLIER_COMMIT, COMMIT]], promotedCommit } = {}) {
   return {
     tags: { [`${RELEASE}:${TAG}`]: OTHER },
-    attestations: { [`${RELEASE}@${OTHER}`]: { identity, type, statements: statements ?? [promotionStatement({ source, extra })] } },
+    attestations: { [`${RELEASE}@${OTHER}`]: { identity, type, statements: statements ?? [promotionStatement({ source, extra, promotedCommit })] } },
     lineage,
   };
 }
@@ -610,3 +616,150 @@ test('an unparsable cosign version is refused', () => {
   const r = refused({ ...provenDevelop(), cosignVersion: 'GitVersion:    devel\n' }, /no parsable GitVersion/);
   assert.deepEqual(r.state.calls, [['cosign', 'version']]);
 });
+
+// ---- reuse through release-arm64's index: `:<tag>` names index D over main's amd64 digest A (= OTHER) ----
+const ARM64_IDENTITY = 'https://github.com/acme/svc/.github/workflows/release-arm64.yaml@refs/heads/main';
+const ARM64_CHILD = `sha256:${'a'.repeat(64)}`;
+const child = (digest, architecture) => ({ mediaType: 'application/vnd.oci.image.manifest.v1+json', digest, size: 1, platform: { os: 'linux', architecture } });
+const ATTESTATION_CHILD = {
+  mediaType: 'application/vnd.oci.image.manifest.v1+json', digest: `sha256:${'b'.repeat(64)}`, size: 1,
+  platform: { os: 'unknown', architecture: 'unknown' }, annotations: { 'vnd.docker.reference.type': 'attestation-manifest' },
+};
+const indexBytes = (manifests, mediaType = 'application/vnd.oci.image.index.v1+json') => JSON.stringify({ schemaVersion: 2, mediaType, manifests });
+
+// `children` / `mediaType` shape D; `signer` signs D; `amd64` is A's state (promoted by main by default).
+function releasedIndex({ children = [child(OTHER, 'amd64'), child(ARM64_CHILD, 'arm64'), ATTESTATION_CHILD], mediaType, signer = ARM64_IDENTITY, amd64 = promotedRelease({ promotedCommit: COMMIT }), raw } = {}) {
+  const bytes = indexBytes(children, mediaType);
+  const index = sha(bytes);
+  return {
+    index,
+    state: {
+      ...amd64,
+      tags: { [`${RELEASE}:${TAG}`]: index },
+      raw: { [`${RELEASE}@${index}`]: raw ?? `${bytes}\n` },
+      signatures: signer === null ? {} : { [`${RELEASE}@${index}`]: signer },
+      attestations: { ...amd64.attestations, [`${RELEASE}@${index}`]: { identity: ARM64_IDENTITY, statements: [provenance(index)] } },
+    },
+  };
+}
+
+function runIndexed(state) {
+  const { run, flags, cleanup } = scenario(state);
+  const at = flags.indexOf('--promotion-predicate-out');
+  try {
+    // spread now: it reads the predicate file before cleanup removes it
+    return { ...run([...flags.slice(0, at), '--release-index-workflow', 'release-arm64.yaml', ...flags.slice(at)]) };
+  } finally {
+    cleanup();
+  }
+}
+
+const MISS_LINE = 'promote-image result=miss digest= src= revision= evidence=none reason=reuse-no-promotion\n';
+const assertIndexMiss = (r) => {
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(r.stdout, MISS_LINE);
+  assert.equal(r.outputs.result, 'miss');
+  assert.equal(r.predicate, undefined);
+  assert.deepEqual(creates(r.state), []);
+};
+const assertIndexRefused = (r, pattern) => {
+  assert.equal(r.status, 1, r.stdout);
+  assert.match(r.stderr, pattern);
+  assert.deepEqual(r.outputs, {});
+  assert.equal(r.predicate, undefined);
+};
+
+test('release index: the tag names release-arm64\'s index over main\'s promoted amd64 digest: reused at A, no predicate, nothing copied', () => {
+  const { index, state } = releasedIndex();
+  const r = runIndexed(state);
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(r.stdout, `promote-image result=reused digest=${OTHER} src=${DEV}@${OTHER} revision=${REVISION} evidence=release-index\n`);
+  assert.deepEqual(r.outputs, {
+    result: 'reused', digest: OTHER, source: `${DEV}@${OTHER}`, revision: REVISION, evidence: 'release-index',
+    provenance_digest: EARLIER_PROVENANCE.payloadDigest, promotion_predicate: '', promotion_predicate_type: '', index_digest: index,
+  });
+  assert.equal(r.predicate, undefined);
+  assert.deepEqual(creates(r.state), []);
+  assert.ok(r.state.calls.some((call) => call[0] === 'docker' && call[4] === `${RELEASE}@${index}` && call[5] === '--raw'));
+  assert.ok(r.state.calls.some((call) => call[0] === 'cosign' && call[1] === 'verify' && call.at(-1) === `${RELEASE}@${index}`));
+  assert.equal(r.state.calls.some((call) => call[0] === 'docker' && call[3] === `${DEV}:${TAG}`), false);
+});
+
+test('release index: without --release-index-workflow the index stays the existing miss', () => {
+  const { run, cleanup } = scenario(releasedIndex().state);
+  try {
+    const r = run();
+    assertIndexMiss(r);
+    assert.equal(r.state.calls.some((call) => call[5] === '--raw'), false);
+  } finally {
+    cleanup();
+  }
+});
+
+test('release index check 1: a tag naming a plain image without a promotion stays the existing miss', () => {
+  const bytes = JSON.stringify({ schemaVersion: 2, mediaType: 'application/vnd.oci.image.manifest.v1+json', layers: [] });
+  const plain = sha(bytes);
+  assertIndexMiss(runIndexed({
+    tags: { [`${RELEASE}:${TAG}`]: plain }, raw: { [`${RELEASE}@${plain}`]: bytes },
+    attestations: { [`${RELEASE}@${plain}`]: { identity: MAIN_IDENTITY, statements: [provenance(plain)] } },
+  }));
+});
+
+test('release index check 1: manifest bytes that do not hash to the tag digest are refused', () => {
+  const { state } = releasedIndex({ raw: indexBytes([child(DIGEST, 'amd64')]) });
+  assertIndexRefused(runIndexed(state), /does not hash to sha256:/);
+});
+
+test('release index: a tag naming a plain promoted image keeps the existing reuse unchanged (no index read)', () => {
+  const r = runIndexed(promotedRelease());
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(r.outputs.evidence, 'prior-promotion');
+  assert.equal(r.outputs.digest, OTHER);
+  assert.equal(r.predicate.promotedCommit, COMMIT);
+  assert.equal(r.state.calls.some((call) => call[5] === '--raw'), false);
+});
+
+test('release index check 2: an index signed by another main workflow is the existing miss', () => {
+  assertIndexMiss(runIndexed(releasedIndex({ signer: MAIN_IDENTITY }).state));
+});
+
+test('release index check 2: an unsigned index is the existing miss', () => {
+  assertIndexMiss(runIndexed(releasedIndex({ signer: null }).state));
+});
+
+test('release index check 2: an index signed by release-arm64 off main is the existing miss', () => {
+  assertIndexMiss(runIndexed(releasedIndex({ signer: ARM64_IDENTITY.replace('refs/heads/main', 'refs/heads/develop') }).state));
+});
+
+test('release index check 3: an index with no linux/amd64 child is the existing miss', () => {
+  assertIndexMiss(runIndexed(releasedIndex({ children: [child(ARM64_CHILD, 'arm64'), ATTESTATION_CHILD] }).state));
+});
+
+test('release index check 3: an index with two linux/amd64 children is refused as ambiguous', () => {
+  const { state } = releasedIndex({ children: [child(OTHER, 'amd64'), child(DIGEST, 'amd64'), child(ARM64_CHILD, 'arm64')] });
+  assertIndexRefused(runIndexed(state), /reuse via release index: ambiguous: .* has 2 linux\/amd64 children/);
+});
+
+test('release index check 4: an amd64 child with no promotion attestation is the existing miss', () => {
+  const amd64 = { attestations: { [`${RELEASE}@${OTHER}`]: { identity: MAIN_IDENTITY, statements: [provenance(OTHER)] } } };
+  assertIndexMiss(runIndexed(releasedIndex({ amd64 }).state));
+});
+
+test('release index check 4: an amd64 promotion stating another tag is refused', () => {
+  const amd64 = promotedRelease({ promotedCommit: COMMIT, extra: { release: { repository: RELEASE, tag: 'a'.repeat(64), digest: OTHER } } });
+  assertIndexRefused(runIndexed(releasedIndex({ amd64 }).state), /states release tag a+, not c+/);
+});
+
+test('release index check 4: an amd64 promotion signed off main is refused', () => {
+  assertIndexRefused(runIndexed(releasedIndex({ amd64: promotedRelease({ promotedCommit: COMMIT, identity: DEVELOP_IDENTITY }) }).state), /reuse: .* has no image-promotion\/v1 attestation signed by/);
+});
+
+test('release index check 4: an amd64 promotion of no ancestor commit is refused', () => {
+  assertIndexRefused(runIndexed(releasedIndex({ amd64: promotedRelease({ lineage: [] }) }).state), /reuse: no image-promotion\/v1 statement on .* promotes/);
+});
+
+test('release index check 4: an amd64 promotion of an ancestor commit (a later commit, same content) falls through to the existing miss', () => {
+  const r = runIndexed(releasedIndex({ amd64: promotedRelease() }).state);
+  assertIndexMiss(r);
+  assert.equal(r.outputs.index_digest, undefined);
+});