@xemahq/repo-build-tooling 0.19.0 → 0.21.0

package/README.md

@@ -32,14 +32,24 @@ pnpm exec xema-scrub-swagger-paths dist
 | `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-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). Pinned to the runner's cgroup cpuset; recreated once when the image, caps or config 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 (plain scripts without turbo); CI is the proof |
+| `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 |
 | `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>`. `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.
 
+## Security model of `xema-buildx-builder`
+
+The persistent builder and its cache mounts are for signed develop and main builds only.
+
+- The verb refuses any `GITHUB_EVENT_NAME` other than `push` and `workflow_dispatch`, and any `GITHUB_REF` other than `refs/heads/main` and `refs/heads/develop`, before any docker call. A pull request never touches the persistent builder or its cache.
+- Callers also gate the step on the opt-in org variable: the develop-images lane runs the verb only `if: vars.XEMA_BUILDKIT_MODE == 'persistent'` and uses the stock `setup-buildx-action` otherwise.
+- The builder, its container and its state volume are named `xema-buildkit-signed-<runner>`; the `xema-buildkit-signed-*` prefix is reserved for signed lanes, so no other lane shares those cache mounts.
+- Owner decision D97 (2026-10-14): pull request jobs run on the same runners. The in-process guards above are the accepted mitigation, because only we push to our repositories.
+
 ## Resolution
 
 Inside the `xema-monorepo` aggregator, `@xemahq/repo-build-tooling` resolves to this directory through a workspace override. In an independent repository's CI it resolves from npm by the declared range, so a change here reaches a consumer only after it is published and the consumer's range admits it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.19.0",
+  "version": "0.21.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)",
@@ -22,6 +22,7 @@
   ],
   "bin": {
     "xema-arm64-supplement-needed": "src/arm64-supplement-needed.mjs",
+    "xema-buildx-builder": "src/buildx-builder.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",
@@ -33,6 +34,7 @@
   },
   "exports": {
     "./arm64-supplement-needed": "./src/arm64-supplement-needed.mjs",
+    "./buildx-builder": "./src/buildx-builder.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",
@@ -47,9 +49,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 && 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-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:83e791d902527383230de73310281ab3f1b6c8a79a640e686ffba5bd4b102def"
+    "sourceDigest": "sha256:bc219d66a33857aaeb74bad77ae50b0f53228368249eb16803ecfd7ef6a8fe03"
   }
 }

package/src/buildx-builder-limits.mjs

@@ -0,0 +1,46 @@
+// The caps of the persistent buildkitd: parsing and the config derived from them. A persistent builder with
+// no caps is unrepresentable, so every field is required and positive; nothing here loosens a cap.
+
+const CPUS = /^[0-9]+(\.[0-9]+)?$/;
+const MEMORY = /^([0-9]+)[bkmgBKMG]?$/;
+const GC_SPACE = /^[0-9]+(\.[0-9]+)?[KMGT]?B$/;
+
+/**
+ * Parse BUILDKIT_LIMITS, JSON `{"cpus":"<n>","memory":"<n>[bkmg]","maxParallelism":<n>,"gcMaxUsedSpace":"<n>GB"}`.
+ * @returns {{ cpus: string, memory: string, maxParallelism: number, gcMaxUsedSpace: string }}
+ */
+export function parseLimits(raw) {
+  if (raw === undefined || raw === '') {
+    throw new Error('BUILDKIT_LIMITS is empty or unset: a persistent builder must be capped (set the XEMA_BUILDKIT_LIMITS org variable)');
+  }
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`BUILDKIT_LIMITS is invalid (${error.message})`);
+  }
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new Error('BUILDKIT_LIMITS is invalid (not a JSON object)');
+  const { cpus, memory, maxParallelism, gcMaxUsedSpace } = value;
+  if (typeof cpus !== 'string' || !CPUS.test(cpus) || Number(cpus) <= 0) throw new Error('BUILDKIT_LIMITS is invalid (cpus must be a positive number string)');
+  const size = typeof memory === 'string' ? MEMORY.exec(memory) : null;
+  if (size === null || Number(size[1]) <= 0) throw new Error('BUILDKIT_LIMITS is invalid (memory must be a positive size such as 2g)');
+  if (typeof gcMaxUsedSpace !== 'string' || !GC_SPACE.test(gcMaxUsedSpace)) throw new Error('BUILDKIT_LIMITS is invalid (gcMaxUsedSpace must be a size string such as 5GB)');
+  if (!Number.isInteger(maxParallelism) || maxParallelism <= 0) throw new Error('BUILDKIT_LIMITS is invalid (maxParallelism must be a positive integer)');
+  return { cpus, memory, maxParallelism, gcMaxUsedSpace };
+}
+
+export function buildkitdToml(limits) {
+  return `[worker.oci]\n  gc = true\n  maxUsedSpace = "${limits.gcMaxUsedSpace}"\n  max-parallelism = ${limits.maxParallelism}\n`;
+}
+
+/** The label value: a change of image, caps, cpuset or config recreates the container exactly once. */
+export function configHash(image, limits, cpuset, toml, sha256) {
+  const caps = `cpus=${limits.cpus} memory=${limits.memory} memory-swap=${limits.memory} cpuset=${cpuset}`;
+  return sha256(`${image}\n${caps}\n${toml}`);
+}
+
+/** The builder key: `xema-buildkit-signed-*` is reserved for signed lanes (T133), so a PR build can never share its cache mounts. The lowercased runner name with anything outside [a-z0-9_.-] mapped to '-'. */
+export function builderName(runnerName) {
+  if (runnerName === undefined || runnerName === '') throw new Error('RUNNER_NAME is empty or unset: the builder key is derived from it');
+  return `xema-buildkit-signed-${runnerName.toLowerCase().replace(/[^a-z0-9_.-]/g, '-')}`;
+}

package/src/buildx-builder.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+// INVOKER: a signed develop/main workflow job, once before its first build-push-action step:
+//   BUILDKIT_IMAGE=<pinned image> BUILDKIT_LIMITS=<json> pnpm exec xema-buildx-builder ensure
+//
+// Ensures the runner's persistent buildkitd container is up and is the current buildx builder.
+// Key: the runner's registered name, RUNNER_NAME. The container is --restart unless-stopped with a named
+// state volume; a label holds sha256(image + caps + config) so a change recreates it exactly once, keeping
+// the volume. The sibling container escapes the runner's own cap, so it is bounded explicitly: the runner's
+// own cpuset plus the caller's BUILDKIT_LIMITS. Readiness is ONE explicit deadline (not a retry).
+//
+// A pull_request build must never reach this: only push and workflow_dispatch on refs/heads/main or
+// refs/heads/develop are admitted, refused BEFORE any docker call.
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { invokedDirectly } from './readiness.mjs';
+import { buildkitdToml, builderName, configHash, parseLimits } from './buildx-builder-limits.mjs';
+
+const ADMITTED_EVENTS = ['push', 'workflow_dispatch'];
+const ADMITTED_REFS = ['refs/heads/main', 'refs/heads/develop'];
+const LABEL = 'xema.buildkit.cfg';
+const CHECK_INTERVAL_MS = 2000;
+const DEFAULT_CPUSET_FILE = '/sys/fs/cgroup/cpuset.cpus.effective';
+const DEFAULT_DEADLINE_SECONDS = 180;
+
+export function refuseUnsignedLane(env) {
+  if (!ADMITTED_EVENTS.includes(env.GITHUB_EVENT_NAME ?? '')) {
+    throw new Error(`GITHUB_EVENT_NAME='${env.GITHUB_EVENT_NAME ?? ''}' may not use the persistent buildx builder: only push and workflow_dispatch builds may; a pull_request gets an ephemeral builder or no build`);
+  }
+  if (!ADMITTED_REFS.includes(env.GITHUB_REF ?? '')) {
+    throw new Error(`GITHUB_REF='${env.GITHUB_REF ?? ''}' may not use the persistent buildx builder: only refs/heads/main and refs/heads/develop may`);
+  }
+}
+
+function docker(args, { allowFailure = false } = {}) {
+  const result = spawnSync('docker', args, { encoding: 'utf8' });
+  if (result.error) throw new Error(`docker ${args[0]}: ${result.error.message}`);
+  if (result.status !== 0 && !allowFailure) throw new Error(`docker ${args.join(' ')} failed (${result.status}): ${(result.stderr || result.stdout).trim()}`);
+  return { ok: result.status === 0, out: `${result.stdout}${result.stderr}`.trim(), stdout: result.stdout.trim() };
+}
+
+const sha256 = (text) => createHash('sha256').update(text).digest('hex');
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+
+/** Unset is the default; anything else must be a positive integer, or the readiness loop could never end. */
+export function parseDeadlineSeconds(raw) {
+  if (raw === undefined) return DEFAULT_DEADLINE_SECONDS;
+  if (!/^[1-9][0-9]*$/.test(raw)) throw new Error(`BUILDKIT_READY_DEADLINE_SECONDS='${raw}' must be a positive integer`);
+  return Number(raw);
+}
+
+export async function ensure(env, log = console.log) {
+  refuseUnsignedLane(env);
+  const image = env.BUILDKIT_IMAGE;
+  if (image === undefined || image === '') throw new Error('BUILDKIT_IMAGE is required');
+  const limits = parseLimits(env.BUILDKIT_LIMITS);
+  const key = builderName(env.RUNNER_NAME);
+  const cpusetFile = env.BUILDKIT_CPUSET_FILE ?? DEFAULT_CPUSET_FILE;
+  let cpuset = '';
+  try {
+    cpuset = readFileSync(cpusetFile, 'utf8').trim();
+  } catch {
+    // reported below with the file name
+  }
+  if (cpuset === '') throw new Error(`${cpusetFile} is missing or empty: cannot bound the builder to the runner's cpuset (cgroup v2 required)`);
+  const deadlineSeconds = parseDeadlineSeconds(env.BUILDKIT_READY_DEADLINE_SECONDS);
+  const toml = buildkitdToml(limits);
+  const cfg = configHash(image, limits, cpuset, toml, sha256);
+
+  const scratch = mkdtempSync(join(tmpdir(), 'xema-buildkitd-'));
+  try {
+    const configFile = join(scratch, 'buildkitd.toml');
+    writeFileSync(configFile, toml);
+    const start = Date.now();
+    const create = () => {
+      docker(['create', '--name', key, '--restart', 'unless-stopped', '--privileged',
+        '--cpus', limits.cpus, '--memory', limits.memory, '--memory-swap', limits.memory, '--cpuset-cpus', cpuset,
+        '-v', `${key}-state:/var/lib/buildkit`, '--label', `${LABEL}=${cfg}`,
+        image, '--config', '/etc/buildkitd.toml']);
+      docker(['cp', configFile, `${key}:/etc/buildkitd.toml`]);
+      docker(['start', key]);
+    };
+
+    let path;
+    if (docker(['ps', '-a', '--filter', `name=^/${key}$`, '--format', '{{.Names}}']).stdout === '') {
+      path = 'created';
+      create();
+    } else {
+      const have = docker(['inspect', '-f', `{{ index .Config.Labels "${LABEL}" }}`, key]).stdout;
+      const haveImage = docker(['inspect', '-f', '{{.Config.Image}}', key]).stdout;
+      if (have !== cfg || haveImage !== image) {
+        log(`::notice::buildkitd ${key} config or image changed (${have || 'none'} ${haveImage} -> ${cfg} ${image}): recreating once, state volume kept`);
+        docker(['rm', '-f', key]);
+        path = 'recreated';
+        create();
+      } else if (docker(['inspect', '-f', '{{.State.Running}}', key]).stdout === 'true') {
+        path = 'running';
+      } else {
+        path = 'started';
+        docker(['start', key]);
+      }
+    }
+    log(`buildx-boot ${key}: ${path}; caps cpus=${limits.cpus} memory=${limits.memory} cpuset=${cpuset} max-parallelism=${limits.maxParallelism}; waiting for workers (deadline ${deadlineSeconds}s)`);
+
+    let check = 0;
+    for (;;) {
+      const probe = docker(['exec', key, 'buildctl', 'debug', 'workers'], { allowFailure: true });
+      check += 1;
+      const waited = Math.floor((Date.now() - start) / 1000);
+      if (probe.ok) {
+        log(`check ${check} at ${waited}s: ready`);
+        break;
+      }
+      const last = probe.out.split('\n').pop();
+      log(`check ${check} at ${waited}s: not ready: ${last}`);
+      if (waited >= deadlineSeconds) {
+        const state = docker(['inspect', '-f', '{{.State.Status}}', key], { allowFailure: true }).out;
+        log(docker(['logs', '--tail', '50', key], { allowFailure: true }).out);
+        throw new Error(`runner ${key}: buildkitd (path=${path}) not ready after ${deadlineSeconds}s; state=${state}; last buildctl error: ${last}`);
+      }
+      await sleep(CHECK_INTERVAL_MS);
+    }
+
+    if (!docker(['buildx', 'inspect', key], { allowFailure: true }).ok) {
+      docker(['buildx', 'create', '--name', key, '--driver', 'remote', `docker-container://${key}`]);
+    }
+    docker(['buildx', 'use', key]);
+    docker(['buildx', 'inspect', '--bootstrap', key]);
+
+    const secs = Math.floor((Date.now() - start) / 1000);
+    const line = `buildx-boot path=${path} secs=${secs} builder=${key}`;
+    log(line);
+    return { path, secs, builder: key, line };
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+async function main(argv, env) {
+  if (argv[0] !== 'ensure' || argv.length !== 1) throw new Error('usage: xema-buildx-builder ensure');
+  const { line } = await ensure(env);
+  if (env.GITHUB_STEP_SUMMARY) writeFileSync(env.GITHUB_STEP_SUMMARY, `### Docker Buildx\n${line}\n`, { flag: 'a' });
+}
+
+if (invokedDirectly(process.argv[1], import.meta.url)) {
+  main(process.argv.slice(2), process.env).catch((error) => {
+    console.error(`::error::${error.message}`);
+    process.exit(1);
+  });
+}

package/src/buildx-builder.test.mjs

@@ -0,0 +1,151 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const BIN = fileURLToPath(new URL('./buildx-builder.mjs', import.meta.url));
+const LIMITS = '{"cpus":"4","memory":"8g","maxParallelism":4,"gcMaxUsedSpace":"5GB"}';
+
+// A fake docker on PATH: appends every call to calls.log; `ps` answers $FAKE_PS, `inspect -f ...Labels...` answers $FAKE_LABEL,
+// `inspect ...Running...` answers $FAKE_RUNNING, `exec` fails $FAKE_EXEC_FAIL times then succeeds.
+function sandbox() {
+  const dir = mkdtempSync(join(tmpdir(), 'buildx-builder-test-'));
+  const log = join(dir, 'calls.log');
+  const fake = join(dir, 'docker');
+  writeFileSync(fake, `#!/bin/sh
+echo "$@" >> "${log}"
+case "$1" in
+  ps) printf '%s' "$FAKE_PS" ;;
+  inspect) case "$*" in *Labels*) printf '%s' "$FAKE_LABEL" ;; *Config.Image*) printf '%s' "\${FAKE_IMAGE:-moby/buildkit:v0.1}" ;; *Running*) printf '%s' "$FAKE_RUNNING" ;; esac ;;
+  exec) if [ "\${FAKE_EXEC_FAIL:-0}" = 1 ]; then echo "no workers" >&2; exit 1; fi ;;
+  buildx) [ "$2" = inspect ] && [ "$3" != --bootstrap ] && exit 1; exit 0 ;;
+esac
+exit 0
+`);
+  chmodSync(fake, 0o755);
+  const cpuset = join(dir, 'cpuset');
+  writeFileSync(cpuset, '10-27\n');
+  const run = (extra = {}) => {
+    const env = {
+      PATH: `${dir}:${process.env.PATH}`, RUNNER_NAME: 'Owl Runner/1', BUILDKIT_IMAGE: 'moby/buildkit:v0.1',
+      BUILDKIT_LIMITS: LIMITS, BUILDKIT_CPUSET_FILE: cpuset, GITHUB_EVENT_NAME: 'push', GITHUB_REF: 'refs/heads/develop', ...extra,
+    };
+    for (const [k, v] of Object.entries(env)) if (v === undefined) delete env[k];
+    const r = spawnSync(process.execPath, [BIN, 'ensure'], { env, encoding: 'utf8' });
+    let calls = '';
+    try { calls = readFileSync(log, 'utf8'); } catch { /* no docker call */ }
+    return { ...r, calls };
+  };
+  return { dir, run, cpuset };
+}
+
+test('a pull_request, an empty event and any non push/workflow_dispatch event is refused before any docker call', () => {
+  const s = sandbox();
+  try {
+    for (const GITHUB_EVENT_NAME of ['pull_request', 'pull_request_target', 'schedule', 'workflow_call', '']) {
+      const r = s.run({ GITHUB_EVENT_NAME });
+      assert.equal(r.status, 1, GITHUB_EVENT_NAME);
+      assert.match(r.stderr, /may not use the persistent buildx builder/);
+      assert.equal(r.calls, '');
+    }
+    assert.equal(s.run({ GITHUB_EVENT_NAME: undefined }).calls, '');
+  } finally { rmSync(s.dir, { recursive: true, force: true }); }
+});
+
+test('a ref other than refs/heads/main and refs/heads/develop is refused before any docker call', () => {
+  const s = sandbox();
+  try {
+    for (const GITHUB_REF of ['refs/heads/feature/x', 'refs/pull/1/merge', 'refs/tags/v1', '']) {
+      const r = s.run({ GITHUB_EVENT_NAME: 'workflow_dispatch', GITHUB_REF });
+      assert.equal(r.status, 1, GITHUB_REF);
+      assert.match(r.stderr, /GITHUB_REF/);
+      assert.equal(r.calls, '');
+    }
+  } finally { rmSync(s.dir, { recursive: true, force: true }); }
+});
+
+test('missing or invalid limits, runner name, image and cpuset fail before any docker call', () => {
+  const s = sandbox();
+  try {
+    const cases = [
+      [{ BUILDKIT_LIMITS: undefined }, /BUILDKIT_LIMITS is empty/],
+      [{ BUILDKIT_LIMITS: '{"cpus":"0","memory":"8g","maxParallelism":4,"gcMaxUsedSpace":"5GB"}' }, /cpus must be positive|cpus must be a positive/],
+      [{ BUILDKIT_LIMITS: '{"cpus":"4","memory":"8g","maxParallelism":0,"gcMaxUsedSpace":"5GB"}' }, /maxParallelism/],
+      [{ RUNNER_NAME: '' }, /RUNNER_NAME/],
+      [{ BUILDKIT_IMAGE: '' }, /BUILDKIT_IMAGE/],
+      [{ BUILDKIT_READY_DEADLINE_SECONDS: 'abc' }, /positive integer/],
+      [{ BUILDKIT_READY_DEADLINE_SECONDS: '0' }, /positive integer/],
+      [{ BUILDKIT_READY_DEADLINE_SECONDS: '-5' }, /positive integer/],
+      [{ BUILDKIT_READY_DEADLINE_SECONDS: '' }, /positive integer/],
+      [{ BUILDKIT_READY_DEADLINE_SECONDS: '1.5' }, /positive integer/],
+      [{ BUILDKIT_CPUSET_FILE: join(s.dir, 'absent') }, /cpuset/],
+    ];
+    for (const [extra, pattern] of cases) {
+      const r = s.run(extra);
+      assert.equal(r.status, 1, JSON.stringify(extra));
+      assert.match(r.stderr, pattern);
+      assert.equal(r.calls, '');
+    }
+    writeFileSync(s.cpuset, '\n');
+    assert.match(s.run().stderr, /missing or empty/);
+  } finally { rmSync(s.dir, { recursive: true, force: true }); }
+});
+
+test('first run creates the capped container pinned to the runner cpuset, then prints the buildx-boot line', () => {
+  const s = sandbox();
+  try {
+    const r = s.run({ FAKE_PS: '' });
+    assert.equal(r.status, 0, r.stderr);
+    const create = r.calls.split('\n').find((l) => l.startsWith('create '));
+    assert.match(create, /--name xema-buildkit-signed-owl-runner-1 /);
+    assert.match(create, /--cpus 4 --memory 8g --memory-swap 8g --cpuset-cpus 10-27/);
+    assert.match(create, /--privileged/);
+    assert.match(create, /-v xema-buildkit-signed-owl-runner-1-state:\/var\/lib\/buildkit/);
+    assert.match(r.calls, /cp .*buildkitd\.toml xema-buildkit-signed-owl-runner-1:\/etc\/buildkitd\.toml/);
+    assert.match(r.calls, /buildx create --name xema-buildkit-signed-owl-runner-1 --driver remote/);
+    assert.match(r.calls, /buildx use xema-buildkit-signed-owl-runner-1/);
+    assert.match(r.stdout, /^buildx-boot path=created secs=\d+ builder=xema-buildkit-signed-owl-runner-1$/m);
+  } finally { rmSync(s.dir, { recursive: true, force: true }); }
+});
+
+test('a changed hash recreates once, keeping the state volume; the same hash reuses', () => {
+  const s = sandbox();
+  try {
+    const first = s.run({ FAKE_PS: '' });
+    const label = /--label xema\.buildkit\.cfg=([0-9a-f]{64})/.exec(first.calls)[1];
+    rmSync(join(s.dir, 'calls.log'));
+    const recreated = s.run({ FAKE_PS: 'xema-buildkit-signed-owl-runner-1', FAKE_LABEL: 'stale' });
+    assert.match(recreated.calls, /rm -f xema-buildkit-signed-owl-runner-1/);
+    assert.doesNotMatch(recreated.calls, /volume rm/);
+    assert.match(recreated.stdout, /path=recreated/);
+    rmSync(join(s.dir, 'calls.log'));
+    const reused = s.run({ FAKE_PS: 'xema-buildkit-signed-owl-runner-1', FAKE_LABEL: label, FAKE_RUNNING: 'true' });
+    assert.doesNotMatch(reused.calls, /^(create|rm) /m);
+    assert.match(reused.stdout, /path=running/);
+  } finally { rmSync(s.dir, { recursive: true, force: true }); }
+});
+
+test('a matching label but a different running image recreates once', () => {
+  const s = sandbox();
+  try {
+    const first = s.run({ FAKE_PS: '' });
+    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_PS: 'xema-buildkit-signed-owl-runner-1', FAKE_LABEL: label, FAKE_RUNNING: 'true', FAKE_IMAGE: 'moby/buildkit:old' });
+    assert.match(r.calls, /rm -f xema-buildkit-signed-owl-runner-1/);
+    assert.match(r.stdout, /path=recreated/);
+  } finally { rmSync(s.dir, { recursive: true, force: true }); }
+});
+
+test('a builder that never becomes ready fails at the deadline with the container logs', () => {
+  const s = sandbox();
+  try {
+    const r = s.run({ FAKE_PS: '', FAKE_EXEC_FAIL: '1', BUILDKIT_READY_DEADLINE_SECONDS: '1' });
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /not ready after 1s/);
+    assert.match(r.calls, /logs --tail 50/);
+  } finally { rmSync(s.dir, { recursive: true, force: true }); }
+});

package/src/composed-image-coordinate.mjs

@@ -1,4 +1,4 @@
-// `xema-composed-image coordinate --image-name <name>`: the release coordinate of a
+// `xema-composed-image coordinate --image-name <name> [--service <subjectId>]`: the release coordinate of a
 // repository's composed-process image and how many cross-repository inputs it hashes.
 //
 // The tag is the ORDINARY build-input key, `xema-compute-image-tag` over the
@@ -77,8 +77,12 @@ export function resolveHashBin(root) {
 }
 
 /** `{ image, content_tag, cross_repo_pins, entry }` for the composed image of the repository at `root`. */
-export function composedCoordinate({ root, imageName, imageDir, env = process.env, hash }) {
+export function composedCoordinate({ root, imageName, imageDir, service, env = process.env, hash }) {
   if (typeof imageName !== 'string' || imageName.length === 0) throw new Error('coordinate needs --image-name');
+  // The hash SERVICE is the subject id (`<source id>-composed-process`), which differs from the
+  // published image name when the name carries a namespace prefix; it defaults to the name.
+  const subjectId = service ?? imageName;
+  if (typeof subjectId !== 'string' || subjectId.length === 0) throw new Error('--service must not be empty');
   const sha = required(env, 'SHA');
   if (!/^[a-f0-9]{40}$/.test(sha)) throw new Error(`SHA '${sha}' is not an exact 40-hex commit`);
   const registry = required(env, 'REGISTRY');
@@ -90,7 +94,7 @@ export function composedCoordinate({ root, imageName, imageDir, env = process.en
     tagArgs = readFileSync(tagArgsFile, 'utf8').split('\n').filter(Boolean);
   }
 
-  const hashArguments = ['--service', imageName, '--path', imageDir, '--commit', sha, '--repo-dir', root, ...tagArgs];
+  const hashArguments = ['--service', subjectId, '--path', imageDir, '--commit', sha, '--repo-dir', root, ...tagArgs];
   const contentHash = (
     hash ??
     ((args) =>
@@ -108,7 +112,7 @@ export function composedCoordinate({ root, imageName, imageDir, env = process.en
   // The same entry shape a service matrix entry has, so the arm64 supplement
   // lane reads this image's receipt exactly as it reads a service's.
   const entry = {
-    service: imageName,
+    service: subjectId,
     path: imageDir,
     workspace: false,
     runtimeImage: false,

package/src/composed-image-coordinate.test.mjs

@@ -116,3 +116,27 @@ test('a read error other than absence is rethrown with its real message, not map
   fs.mkdirSync(path.join(root, 'node_modules/@xemahq/distribution-source-hash/package.json'), { recursive: true });
   assert.throws(() => resolveHashBin(root), (error) => error.code === 'EISDIR' && !/not installed/.test(error.message));
 });
+
+test('--service sets the hash subject id and entry.service; the published image name stays the prefixed name', () => {
+  const root = consumer();
+  const out = composedCoordinate({
+    root,
+    imageName: 'presenca-biomes-composed-process-prefixed',
+    service: 'biomes-composed-process',
+    imageDir: 'infra/composed-process',
+    env: ENV,
+  });
+  assert.deepEqual(JSON.parse(fs.readFileSync(path.join(root, 'args.json'), 'utf8')), [
+    '--service', 'biomes-composed-process', '--path', 'infra/composed-process', '--commit', SHA, '--repo-dir', root,
+  ]);
+  assert.equal(out.image, 'ghcr.io/xema-dev/presenca-biomes-composed-process-prefixed');
+  const entry = JSON.parse(out.entry);
+  assert.equal(entry.service, 'biomes-composed-process');
+  assert.equal(entry.imageRepository, out.image);
+});
+
+test('without --service the output is identical to passing the image name as the service', () => {
+  const a = composedCoordinate({ root: consumer(), imageName: 'x', imageDir: 'd', env: ENV });
+  const b = composedCoordinate({ root: consumer(), imageName: 'x', service: 'x', imageDir: 'd', env: ENV });
+  assert.deepEqual(a, b);
+});

package/src/composed-image.mjs

@@ -58,7 +58,10 @@
 //   load-image <image>
 //            the same check against the SHIPPED image (`docker run`), as its own
 //            user and NODE_ENV: `load` runs in the builder, which is not what ships.
-//   coordinate --image-name <name>
+//   coordinate --image-name <name> [--service <subjectId>]
+//            --service is the hash subject id (default: the image name); a prefixed
+//            image name needs it, e.g. `--service presenca-biomes-composed-process
+//            --image-name presenca-presenca-biomes-composed-process`.
 //            the image's content tag (computed ONLY by the repository's own
 //            `xema-compute-image-tag`) and its cross-repository pin count; pure, no
 //            registry probe or credential (`composed-image-coordinate.mjs`;
@@ -321,7 +324,7 @@ const USAGE =
   '  filters [--also <pkg>]… | dirs | pins <committed-lockfile> | index <commit> --build-source <repo> | load [--each]\n' +
   '  pnpm-context <dir> (--subject <svc>… | --image-dir <composed>)\n' +
   '  stage <dir> [--output <rel>]… [--also <pkg>]…   | sync-injected | prisma-check | migrate <member> [--root <dir>]\n' +
-  '  coordinate --image-name <name>   (env: SHA REGISTRY REGISTRY_ORG [TAG_ARGS_FILE])\n' +
+  '  coordinate --image-name <name> [--service <subjectId>]   (env: SHA REGISTRY REGISTRY_ORG [TAG_ARGS_FILE])\n' +
   '  load-image <image>\n' +
   '  smoke-refusal <image> [--member <biomeId>/<componentKey>]x2\n' +
   '  dockerfile --write|--check --copy <dir>… --cache-id <id> --build-source <repo>\n' +
@@ -330,7 +333,7 @@ const USAGE =
 const REPEATABLE = new Set(['manifests', 'copy', 'member', 'output', 'also', 'subject']);
 const BOOLEAN = new Set(['prebuilt', 'each']);
 const VALUED = new Set(['root', 'image-dir', 'manifests', 'canonical-dockerfile', 'cross-repo-manifest', 'build-source',
-  'image-name', 'cache-id', 'copy', 'member', 'stage-dir', 'output', 'also', 'subject',
+  'image-name', 'service', 'cache-id', 'copy', 'member', 'stage-dir', 'output', 'also', 'subject',
 ]);
 
 export function parseArguments(argv) {
@@ -432,7 +435,7 @@ export function main(argv, { log = console.log, write = (text) => process.stdout
 
     }
     case 'coordinate':
-      emitCoordinate(composedCoordinate({ root, imageDir, imageName: options['image-name'] }), { log });
+      emitCoordinate(composedCoordinate({ root, imageDir, imageName: options['image-name'], service: options.service }), { log });
       return;
     case 'load-image':
       runImageLoad({ image: argument, log });

package/src/prepush-sanity.mjs

@@ -8,7 +8,7 @@
 // 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`
-// script. Without turbo: root `typecheck` and `lint` scripts.
+// 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
 // is HEAD, or when no differing path lies in a package the run reads or at the
@@ -182,10 +182,10 @@ function hasRootLint(dir) {
 /** Run the sanity tasks in `dir`; `range` '' is the full graph. Returns the verdict. */
 function runHere(ctx, dir, range, bin) {
   if (!bin) {
-    console.log('pre-push: pnpm run typecheck && pnpm run lint (this repository declares no turbo)');
-    const typecheck = ctx.inherit('pnpm', ['run', 'typecheck'], dir);
-    const lint = ctx.inherit('pnpm', ['run', 'lint'], dir);
-    return typecheck && lint;
+    // Without turbo nothing orders the builds a workspace typecheck needs, and the hook never
+    // builds: typecheck there is CI's.
+    console.log('pre-push: pnpm run lint (this repository declares no turbo; typecheck is CI-only)');
+    return ctx.inherit('pnpm', ['run', 'lint'], dir);
   }
   let tasks;
   try {
@@ -325,7 +325,7 @@ export function main(stdin) {
   }
   const failed = refs.filter((ref) => !gradeSha(ctx, ref, bin)).map((ref) => ctx.gitOut(['rev-parse', '--short', ref.sha])?.trim() ?? ref.sha);
   if (failed.length === 0) {
-    console.log(`pre-push: GREEN — lint typecheck passed on ${refs.length} pushed commit(s).`);
+    console.log(`pre-push: GREEN — sanity passed on ${refs.length} pushed commit(s).`);
     return 0;
   }
   console.log(`::error::pre-push FAILED — ${failed.join(' ')}`);

package/src/prepush-sanity.test.mjs

@@ -60,19 +60,19 @@ function hook(dir, stdin) {
   return spawnSync('node', [VERB], { cwd: dir, input: stdin, encoding: 'utf8' });
 }
 
-test('no turbo: a failing typecheck refuses the push, a passing one is green', () => {
-  const bad = repo({ typecheck: 'exit 1', lint: 'exit 0' });
-  const good = repo({ typecheck: 'exit 0', lint: 'exit 0' });
+test('no turbo: lint only. A failing lint refuses the push; a failing typecheck is CI-only', () => {
+  const badLint = repo({ typecheck: 'exit 0', lint: 'exit 1' });
+  const badTypecheck = repo({ typecheck: 'exit 1', lint: 'exit 0' });
   try {
-    const refused = hook(bad.dir, `refs/heads/x ${bad.sha} refs/heads/develop ${'0'.repeat(40)}\n`);
+    const refused = hook(badLint.dir, `refs/heads/x ${badLint.sha} refs/heads/develop ${'0'.repeat(40)}\n`);
     assert.equal(refused.status, 1, refused.stdout + refused.stderr);
     assert.match(refused.stdout, /pre-push: FAILED/);
-    const green = hook(good.dir, `refs/heads/x ${good.sha} refs/heads/develop ${'0'.repeat(40)}\n`);
+    const green = hook(badTypecheck.dir, `refs/heads/x ${badTypecheck.sha} refs/heads/develop ${'0'.repeat(40)}\n`);
     assert.equal(green.status, 0, green.stdout + green.stderr);
     assert.match(green.stdout, /GREEN/);
   } finally {
-    rmSync(bad.dir, { recursive: true, force: true });
-    rmSync(good.dir, { recursive: true, force: true });
+    rmSync(badLint.dir, { recursive: true, force: true });
+    rmSync(badTypecheck.dir, { recursive: true, force: true });
   }
 });
 

package/src/promote-image-provenance.mjs

@@ -11,6 +11,15 @@
 //   (c) content: the caller's tag command at that revision AND at the promoted
 //       commit both print the content tag being promoted.
 // Every refusal names its leg and is an error, never a miss.
+//
+// A release digest main already promoted is REUSED from its image-promotion/v1 statements. Two main commits that
+// promote identical content share one release digest, so the digest carries one statement per promotedCommit. The
+// evidence is SELECTED by promotedCommit, mirroring xema-deploy's deploy verifier (`assertPromotionPredicate`): only
+// statements whose promotedCommit is a 40-hex ancestor of (or equal to) the commit being promoted are candidates, and
+// the nearest such commit wins (the one every other candidate is an ancestor of). Statements of other commits are
+// ignored, whatever their shape or subject. Only then is every selected statement checked in full (predicate type,
+// subject digest, release bindings, source, developProvenance); one failing is an error. No candidate, or no single
+// 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';
@@ -46,11 +55,8 @@ function readStatements(stdout, subject, label) {
   return byDigest;
 }
 
-/**
- * Runs `cosign verify-attestation` of `type` on `subject` under `pattern` and requires exactly one distinct verified
- * statement whose subject is the digest. Returns `{ statement, payloadDigest }`.
- */
-function verifiedStatement({ subject, digest, type, predicateType, what, noun, pattern, label }, run) {
+/** Runs `cosign verify-attestation` of `type` on `subject` under `pattern`; returns every distinct verified statement by payload digest. */
+function verifiedStatements({ subject, type, what, pattern, label }, run) {
   const verified = run('cosign', [
     'verify-attestation',
     '--type', type,
@@ -63,18 +69,55 @@ function verifiedStatement({ subject, digest, type, predicateType, what, noun, p
     const detail = describeFailure(verified);
     throw new Error(`${label}: ${subject} has no ${what} signed by ${pattern}: ${detail}`);
   }
-  const statements = readStatements(verified.stdout, subject, label);
+  return readStatements(verified.stdout, subject, label);
+}
+
+const isStatementAbout = (statement, digest, predicateType) =>
+  statement?.predicateType === predicateType && Boolean(statement.subject?.some((entry) => entry?.digest?.sha256 === digest.slice('sha256:'.length)));
+
+/**
+ * Runs `cosign verify-attestation` of `type` on `subject` under `pattern` and requires exactly one distinct verified
+ * statement whose subject is the digest. Returns `{ statement, payloadDigest }`.
+ */
+function verifiedStatement({ subject, digest, type, predicateType, what, noun, pattern, label }, run) {
+  const statements = verifiedStatements({ subject, type, what, pattern, label }, run);
   if (statements.size !== 1) {
     throw new Error(`${label}: ${subject} carries ${statements.size} distinct verified ${noun} statements; exactly one is promotable`);
   }
   const [[payloadDigest, statement]] = statements;
-  const hex = digest.slice('sha256:'.length);
-  if (statement.predicateType !== predicateType || !statement.subject?.some((entry) => entry?.digest?.sha256 === hex)) {
+  if (!isStatementAbout(statement, digest, predicateType)) {
     throw new Error(`${label}: the verified statement is not ${what} about ${subject}`);
   }
   return { statement, payloadDigest };
 }
 
+/** Whether `ancestor` is `descendant` or one of its ancestors; any git failure other than "no" is an error. */
+function isAncestorOrEqual(ancestor, descendant, label, run) {
+  if (ancestor === descendant) return true;
+  const ordered = run('git', ['merge-base', '--is-ancestor', ancestor, descendant]);
+  if (ordered.error || (ordered.status !== 0 && ordered.status !== 1)) {
+    throw new Error(`${label}: git could not order ${ancestor} against ${descendant}: ${describeFailure(ordered)}`);
+  }
+  return ordered.status === 0;
+}
+
+/**
+ * The promotedCommit whose statements are the evidence for a reuse at `commit`: the nearest ancestor of (or equal to)
+ * `commit` among the 40-hex `promotedCommits` the digest carries. Anything not a commit is never passed to git.
+ */
+function nearestPromotedCommit(promotedCommits, commit, subject, label, run) {
+  const found = [...promotedCommits].sort();
+  const ancestors = found.filter((candidate) => isAncestorOrEqual(candidate, commit, label, run));
+  if (ancestors.length === 0) {
+    throw new Error(`${label}: no image-promotion/v1 statement on ${subject} promotes ${commit} or an ancestor of it; the digest carries promotions of: ${found.join(', ') || 'none'}`);
+  }
+  const nearest = ancestors.filter((candidate) => ancestors.every((other) => isAncestorOrEqual(other, candidate, label, run)));
+  if (nearest.length !== 1) {
+    throw new Error(`${label}: ambiguous: the promotions of ${subject} at ${ancestors.join(', ')} are ancestors of ${commit} but none contains all the others`);
+  }
+  return nearest[0];
+}
+
 // cosign v2 exits 1 with this exact stderr line (and empty stdout) for an image that carries no attestations.
 const NO_ATTESTATIONS_LINE = 'Error: found no attestations';
 
@@ -102,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 }, run = runTool) {
+export function reuseEarlierPromotion({ releaseRef, tag, digest, repository, releaseWorkflows, commit }, run = runTool) {
   const subject = `${releaseRef}@${digest}`;
   const label = 'reuse';
   // (a) presence, without identity verification: only the predicate types are read
@@ -112,12 +155,31 @@ export function reuseEarlierPromotion({ releaseRef, tag, digest, repository, rel
   }
   if (!types.includes(IMAGE_PROMOTION_PREDICATE_TYPE)) return undefined;
   // (b) a promotion attestation is present: any verification failure is an error
-  const found = verifiedStatement({
-    subject, digest, type: IMAGE_PROMOTION_PREDICATE_TYPE, predicateType: IMAGE_PROMOTION_PREDICATE_TYPE,
-    what: 'image-promotion/v1 attestation', noun: 'promotion', pattern: workflowIdentityPattern(repository, releaseWorkflows, 'main'),
-    label,
+  const verified = verifiedStatements({
+    subject, type: IMAGE_PROMOTION_PREDICATE_TYPE, what: 'image-promotion/v1 attestation',
+    pattern: workflowIdentityPattern(repository, releaseWorkflows, 'main'), label,
   }, run);
-  const { source, developProvenance, release } = found.statement.predicate ?? {};
+  // (c) select by promotedCommit first; a statement about any other commit is ignored, whatever its shape or subject
+  const about = [...verified.values()];
+  const promoted = (statement) => statement.predicate?.promotedCommit;
+  const nearest = nearestPromotedCommit(
+    new Set(about.map(promoted).filter((value) => typeof value === 'string' && COMMIT.test(value))), commit, subject, label, run,
+  );
+  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) {
+    throw new Error(`${label}: ${subject} carries ${admitted.size} distinct promotion statements for ${nearest}; exactly one is admissible`);
+  }
+  const [only] = admitted;
+  return JSON.parse(only);
+}
+
+/** Checks one promotion statement in full against this release; returns `{ source, developProvenance }` copied from it. */
+function admissible(statement, { subject, tag, digest, releaseRef, repository, label }) {
+  if (!isStatementAbout(statement, digest, IMAGE_PROMOTION_PREDICATE_TYPE)) {
+    throw new Error(`${label}: the selected statement is not an image-promotion/v1 attestation about ${subject}`);
+  }
+  const { source, developProvenance, release } = statement.predicate ?? {};
   for (const [field, expected, stated] of [['digest', digest, release?.digest], ['repository', releaseRef, release?.repository], ['tag', tag, release?.tag]]) {
     if (stated !== expected) throw new Error(`${label}: the promotion attestation of ${subject} states release ${field} ${stated}, not ${expected}`);
   }

package/src/promote-image.mjs

@@ -4,7 +4,8 @@
 // rebuilding them, and only when the develop bytes are PROVEN promotable.
 //
 //   1. `<release-ref>:<tag>` exists: its image-promotion/v1 attestation must verify under one of main's
-//      `--release-workflow` identities (exactly one statement about the digest), and its source must be a
+//      `--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
 //      - a signature / identity failure, or a source outside dev/ -> error, never a miss
@@ -152,7 +153,7 @@ export function promoteImage(options, run = runTool) {
   const releaseTagged = `${releaseRef}:${tag}`;
   const released = probeDigest(releaseTagged, run);
   if (released !== undefined) {
-    const earlier = reuseEarlierPromotion({ releaseRef, tag, digest: released, repository, releaseWorkflows }, run);
+    const earlier = reuseEarlierPromotion({ releaseRef, tag, digest: released, repository, releaseWorkflows, commit }, run);
     if (earlier === undefined) return { ...MISS, reason: PromoteMissReason.NO_PROMOTION };
     return {
       result: PromoteResult.REUSED,

package/src/promote-image.test.mjs

@@ -25,7 +25,8 @@ const PROMOTION_TYPE = 'https://xema.dev/attestations/image-promotion/v1';
 //   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
-//   ancestors                    revisions `git merge-base --is-ancestor` accepts
+//   ancestors                    revisions `git merge-base --is-ancestor` accepts against origin/main
+//   lineage                      [ancestor, descendant] pairs it accepts against any other ref (equal commits are ancestors)
 //   hashes[commit]               what the tag command prints for `--commit <commit>`
 // Every call is recorded in `calls` as [tool, ...args].
 const SHIM = `#!${process.execPath}
@@ -87,6 +88,10 @@ if (tool === 'cosign') {
 }
 if (tool === 'git') {
   if (args[0] === 'merge-base' && args[1] === '--is-ancestor' && args[3] === 'origin/main') process.exit(state.ancestors.includes(args[2]) ? 0 : 1);
+  if (args[0] === 'merge-base' && args[1] === '--is-ancestor') {
+    const yes = args[2] === args[3] || (state.lineage ?? []).some(([ancestor, descendant]) => ancestor === args[2] && descendant === args[3]);
+    process.exit(yes ? 0 : 1);
+  }
   fail('unexpected git ' + args.join(' '), 2);
 }
 if (tool === 'tag-command') {
@@ -180,23 +185,29 @@ const EARLIER_PROVENANCE = {
 };
 const EARLIER_COMMIT = '5'.repeat(40);
 
-// A release digest main already promoted: its image-promotion/v1 attestation, signed by a main workflow.
-function promotedRelease({ source = `${DEV}@${OTHER}`, identity = MAIN_IDENTITY, type = PROMOTION_TYPE, extra = {} } = {}) {
-  const statement = JSON.stringify({
+// One signed image-promotion/v1 statement about the release digest.
+function promotionStatement({ subjectDigest = OTHER, predicateType = PROMOTION_TYPE, release = { repository: RELEASE, tag: TAG, digest: OTHER }, source = `${DEV}@${OTHER}`, revision = REVISION, promotedCommit = EARLIER_COMMIT, provenance = EARLIER_PROVENANCE, extra = {} } = {}) {
+  return JSON.stringify({
     _type: 'https://in-toto.io/Statement/v1',
-    subject: [{ name: RELEASE, digest: { sha256: OTHER.slice('sha256:'.length) } }],
-    predicateType: PROMOTION_TYPE,
+    subject: [{ name: RELEASE, digest: { sha256: subjectDigest.slice('sha256:'.length) } }],
+    predicateType,
     predicate: {
-      release: { repository: RELEASE, tag: TAG, digest: OTHER },
-      source: { reference: source, revision: REVISION },
-      promotedCommit: EARLIER_COMMIT,
-      developProvenance: EARLIER_PROVENANCE,
+      release,
+      source: { reference: source, revision },
+      promotedCommit,
+      developProvenance: provenance,
       ...extra,
     },
   });
+}
+
+// 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]] } = {}) {
   return {
     tags: { [`${RELEASE}:${TAG}`]: OTHER },
-    attestations: { [`${RELEASE}@${OTHER}`]: { identity, type, statements: [statement] } },
+    attestations: { [`${RELEASE}@${OTHER}`]: { identity, type, statements: statements ?? [promotionStatement({ source, extra })] } },
+    lineage,
   };
 }
 
@@ -277,6 +288,136 @@ test('a promotion attestation stating another release digest is refused', () =>
   refused(promotedRelease({ extra: { release: { repository: RELEASE, tag: TAG, digest: DIGEST } } }), /states release digest sha256:d+, not /);
 });
 
+const MIDDLE_COMMIT = '6'.repeat(40);
+const OTHER_BRANCH_COMMIT = '7'.repeat(40);
+const gitCalls = (state) => state.calls.filter((call) => call[0] === 'git');
+
+test('reuse: statements only about non-ancestor commits are refused, naming them', () => {
+  refused(
+    promotedRelease({ lineage: [], statements: [promotionStatement({ promotedCommit: EARLIER_COMMIT }), promotionStatement({ promotedCommit: OTHER_BRANCH_COMMIT })] }),
+    new RegExp(`reuse: no image-promotion/v1 statement on .* promotes ${COMMIT} or an ancestor of it; the digest carries promotions of: ${EARLIER_COMMIT}, ${OTHER_BRANCH_COMMIT}`),
+  );
+});
+
+test('reuse: two incomparable ancestor promotions are refused as ambiguous', () => {
+  refused(
+    promotedRelease({
+      lineage: [[EARLIER_COMMIT, COMMIT], [OTHER_BRANCH_COMMIT, COMMIT]],
+      statements: [promotionStatement({ promotedCommit: EARLIER_COMMIT }), promotionStatement({ promotedCommit: OTHER_BRANCH_COMMIT })],
+    }),
+    new RegExp(`reuse: ambiguous: .*${EARLIER_COMMIT}, ${OTHER_BRANCH_COMMIT}`),
+  );
+});
+
+test('reuse: two statements of the nearest commit that disagree are refused', () => {
+  refused(
+    promotedRelease({ statements: [promotionStatement(), promotionStatement({ revision: '8'.repeat(40) })] }),
+    new RegExp(`reuse: .* carries 2 distinct promotion statements for ${EARLIER_COMMIT}; exactly one is admissible`),
+  );
+});
+
+test('reuse: two selected statements citing different developProvenance are refused', () => {
+  refused(
+    promotedRelease({ statements: [promotionStatement(), promotionStatement({ provenance: { ...EARLIER_PROVENANCE, payloadDigest: sha('other') } })] }),
+    /carries 2 distinct promotion statements for .*; exactly one is admissible/,
+  );
+});
+
+test('reuse: two selected statements with different release.tag are refused', () => {
+  refused(
+    promotedRelease({ statements: [promotionStatement(), promotionStatement({ release: { repository: RELEASE, tag: 'other-tag', digest: OTHER } })] }),
+    /states release tag other-tag, not /,
+  );
+});
+
+test('reuse: a selected statement whose subject is another digest is refused', () => {
+  refused(
+    promotedRelease({ statements: [promotionStatement({ subjectDigest: DIGEST })] }),
+    /the selected statement is not an image-promotion\/v1 attestation about /,
+  );
+});
+
+test('reuse: a selected statement of another predicateType is refused', () => {
+  refused(
+    // the registry listing must still show an image-promotion/v1 attestation, or the digest is a legacy miss
+    promotedRelease({ statements: [promotionStatement({ promotedCommit: OTHER_BRANCH_COMMIT }), promotionStatement({ predicateType: 'https://slsa.dev/provenance/v1' })] }),
+    /the selected statement is not an image-promotion\/v1 attestation about /,
+  );
+});
+
+test('reuse: a promotedCommit that is not a 40-hex commit is ignored and never reaches git', () => {
+  const { run, cleanup } = scenario(promotedRelease({
+    statements: [promotionStatement(), promotionStatement({ promotedCommit: '--output=/tmp/x' }), promotionStatement({ promotedCommit: 'main' })],
+  }));
+  try {
+    const r = run();
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(r.outputs.result, 'reused');
+    assert.deepEqual(gitCalls(r.state), [['git', 'merge-base', '--is-ancestor', EARLIER_COMMIT, COMMIT]]);
+  } finally {
+    cleanup();
+  }
+});
+
+test('reuse: an invalid statement about a non-ancestor commit is ignored while the valid nearest one is reused', () => {
+  const { run, cleanup } = scenario(promotedRelease({
+    statements: [promotionStatement({ promotedCommit: OTHER_BRANCH_COMMIT, source: 'ghcr.io/acme/svc@x', revision: 'nope' }), promotionStatement()],
+  }));
+  try {
+    const r = run();
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(r.outputs.revision, REVISION);
+  } finally {
+    cleanup();
+  }
+});
+
+test('reuse: the nearest ancestor promotion is the evidence', () => {
+  const middleRevision = '9'.repeat(40);
+  const middleProvenance = { ...EARLIER_PROVENANCE, payloadDigest: sha('middle-provenance') };
+  const { run, cleanup } = scenario(promotedRelease({
+    lineage: [[EARLIER_COMMIT, MIDDLE_COMMIT], [EARLIER_COMMIT, COMMIT], [MIDDLE_COMMIT, COMMIT]],
+    statements: [promotionStatement(), promotionStatement({ promotedCommit: MIDDLE_COMMIT, revision: middleRevision, provenance: middleProvenance })],
+  }));
+  try {
+    const r = run();
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(r.predicate.source.revision, middleRevision);
+    assert.deepEqual(r.predicate.developProvenance, middleProvenance);
+    assert.equal(r.predicate.promotedCommit, COMMIT);
+  } finally {
+    cleanup();
+  }
+});
+
+test('reuse: a re-run (a statement promoting this very commit) selects that statement over an older one', () => {
+  const rerunRevision = '9'.repeat(40);
+  const { run, cleanup } = scenario(promotedRelease({
+    statements: [promotionStatement(), promotionStatement({ promotedCommit: COMMIT, revision: rerunRevision })],
+  }));
+  try {
+    const r = run();
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(r.predicate.source.revision, rerunRevision);
+  } finally {
+    cleanup();
+  }
+});
+
+test('reuse: two identical-evidence statements for the nearest commit are reused', () => {
+  const { run, cleanup } = scenario(promotedRelease({
+    statements: [promotionStatement(), promotionStatement({ extra: { attestedAt: 'second' } })],
+  }));
+  try {
+    const r = run();
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(r.outputs.result, 'reused');
+    assert.equal(r.predicate.source.revision, REVISION);
+  } finally {
+    cleanup();
+  }
+});
+
 test('a proven develop digest is copied by digest and the promotion predicate states the facts', () => {
   const { run, predicatePath, cleanup } = scenario(provenDevelop());
   try {