@xemahq/repo-build-tooling 0.21.3 → 0.22.0

package/README.md

@@ -30,9 +30,9 @@ pnpm exec xema-scrub-swagger-paths dist
 | `xema-service-bootstrap [--check] [--filter <key>] [--root <dir>]` | Generates `src/generated/*.generated.ts` service and worker descriptors from the repository's `xema-biome.json` manifests; `--check` fails on drift |
 | `xema-scrub-swagger-paths <dist-dir>...` | Rewrites `@nestjs/swagger` plugin output that names a private install path, then fails the build if any leak remains (`--self-test` available) |
 | `xema-composed-image <command>` | Build-time half of a composed-process image: `members`, `filters`, `dirs`, `pins`, `index`, `load`, `stage`, `pnpm-context`, `sync-injected`, `prisma-check`, `migrate`, `coordinate`, `load-image`, `smoke-refusal`, `dockerfile` |
+| `xema-service-image stage --service <pkg> --path <dir> --platform linux/<amd64\|arm64> [--stage-dir <dir>]` | Runner half of a per-service image: `pnpm deploy --prod --offline --ignore-scripts` of a service already built on the runner, selected for the TARGET platform (`--os=linux --cpu=<arch> --libc=glibc`), into `<stage>/service/app`, with its Prisma client and the target's schema engine. Refuses a package whose native code holds no ELF for the target (a multi-platform package that also ships the target's binary is accepted) and production dependencies whose build script would have to run, uncommitted changes to tracked files, an untracked root build input, and running as any tool but the one the root installs. Fetches the schema engine from Prisma for every stage, checks it against both published checksums, and caches nothing. Writes `<stage>/service/xema-service-image.json` (commit, sha256 of each root build input: lockfile, root `package.json`, `pnpm-workspace.yaml`, `.npmrc`, `.pnpmfile.cjs`, `turbo.json`, `tsconfig*.json`; tool version; natives per package; engine sha256) and `<stage>/tool`. The Dockerfile COPYs those root inputs into `/proof/context/`, which puts them in the content tag, and its proof stage runs `src/service-image-in-image.mjs prove <app> <proof dir> --service <svc> --commit <BUILD_SHA>` on the target, offline: it checks the commit, the root inputs, the tool version, the platform and Node ABI, that each package's addons `dlopen`, and the engine's sha256 and version. The final stage only COPYs |
 | `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>... [--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 |
 | `xema-check-workspace-ranges` | Fails on a `workspace:` range the local package does not satisfy |
@@ -41,15 +41,6 @@ pnpm exec xema-scrub-swagger-paths dist
 
 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.21.3",
+  "version": "0.22.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,7 +22,6 @@
   ],
   "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",
@@ -30,11 +29,11 @@
     "xema-promote-image": "src/promote-image.mjs",
     "xema-readiness": "src/readiness.mjs",
     "xema-scrub-swagger-paths": "src/scrub-swagger-plugin-paths.mjs",
-    "xema-service-bootstrap": "src/service-bootstrap.mjs"
+    "xema-service-bootstrap": "src/service-bootstrap.mjs",
+    "xema-service-image": "src/service-image.mjs"
   },
   "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",
@@ -43,15 +42,16 @@
     "./promote-image": "./src/promote-image.mjs",
     "./readiness": "./src/readiness.mjs",
     "./scrub-swagger-plugin-paths": "./src/scrub-swagger-plugin-paths.mjs",
-    "./service-bootstrap": "./src/service-bootstrap.mjs"
+    "./service-bootstrap": "./src/service-bootstrap.mjs",
+    "./service-image": "./src/service-image.mjs"
   },
   "dependencies": {
     "@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-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"
+    "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-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 && node --test src/service-image.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:57594caa2c2d04aedf32ce374f8e0d5806022c23e5d14451c3263c925a641de4"
+    "sourceDigest": "sha256:0b63df80f6c68f70cb652dfc51f08288aeac11bbee2445cfa6fc440242a7bcf9"
   }
 }

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

@@ -52,6 +52,19 @@ export function prismaEnginesDirectories(root) {
 
 const runVersion = (file) => spawnSync(file, ['--version'], { encoding: 'utf8' });
 
+/**
+ * Run a schema engine and refuse it unless it reports `enginesVersion`: the check Prisma makes before it
+ * decides to download one. Returns the engine's version line.
+ */
+export function verifySchemaEngine(file, enginesVersion, version = runVersion) {
+  const result = version(file);
+  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(`${file} --version did not report ${enginesVersion}: status ${result.status}${detail === '' ? '' : `, ${detail}`}`);
+  }
+  return String(result.stdout).trim();
+}
+
 /**
  * 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
@@ -77,12 +90,7 @@ export async function installPrismaSchemaEngine({ root = process.cwd(), stagedDi
     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()})`);
+    log(`prisma schema engine: ${destination} (${verifySchemaEngine(destination, enginesVersion, version)})`);
     installed.push(destination);
   }
   return installed;

package/src/prepush-sanity.mjs

@@ -13,7 +13,9 @@
 // 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
 // repository root; otherwise from a `git archive` export. A delete-only push
-// (or no ref on stdin) grades nothing.
+// (or no ref on stdin) grades nothing. A push whose every remote ref is a
+// session park (`refs/xema-session/*`) grades nothing either: a park is not a
+// landing, and the work is graded when it lands on a branch.
 //
 // Never builds for its own sake, never runs tests, docker or `pnpm check`.
 //
@@ -80,6 +82,18 @@ export function parseRefs(stdin) {
   return refs;
 }
 
+/** Remote refs under this prefix are session parks, not landings. */
+export const PARK_REF_PREFIX = 'refs/xema-session/';
+
+/** True when stdin names at least one ref and every remote ref is a session park. A branch anywhere in the push grades the push. */
+export function parkOnly(stdin) {
+  const remoteRefs = stdin
+    .split('\n')
+    .map((line) => line.trim().split(/\s+/)[2])
+    .filter(Boolean);
+  return remoteRefs.length > 0 && remoteRefs.every((ref) => ref.startsWith(PARK_REF_PREFIX));
+}
+
 /** 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 {
@@ -318,6 +332,10 @@ export function main(stdin) {
     console.error('pre-push: not inside a git repository — FAILED');
     return 1;
   }
+  if (parkOnly(stdin)) {
+    console.log(`pre-push: skipped — every ref is a session park under ${PARK_REF_PREFIX}; parks are not landings, the gate runs when the work lands.`);
+    return 0;
+  }
   const ctx = createContext(top.stdout.trim());
   const refs = parseRefs(stdin);
   if (refs.length === 0) {

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, scriptsOnlyChange, stripJsonc, turboCacheDir, turboTasks } from './prepush-sanity.mjs';
+import { blockingPath, isFleetWide, parkOnly, 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);
@@ -136,3 +136,29 @@ test('the turbo invocation receives TURBO_CACHE_DIR', () => {
     rmSync(r.dir, { recursive: true, force: true });
   }
 });
+
+test('parkOnly: only a push whose every remote ref is a session park', () => {
+  const park = `refs/heads/x ${SHA_A} refs/xema-session/lead/T1/x ${'0'.repeat(40)}`;
+  const dev = `refs/heads/x ${SHA_A} refs/heads/develop ${SHA_B}`;
+  assert.equal(parkOnly(`${park}\n`), true);
+  assert.equal(parkOnly(`(delete) ${'0'.repeat(40)} refs/xema-session/lead/T1/x ${SHA_A}\n`), true);
+  assert.equal(parkOnly(`${park}\n${dev}\n`), false);
+  assert.equal(parkOnly(`${dev}\n`), false);
+  assert.equal(parkOnly(`refs/heads/x ${SHA_A} refs/heads/main ${SHA_B}\n`), false);
+  assert.equal(parkOnly(`refs/heads/x ${SHA_A} refs/heads/xema-session/x ${SHA_B}\n`), false);
+  assert.equal(parkOnly(''), false);
+});
+
+test('a park-only push skips and says why; a park beside develop still grades', () => {
+  const r = repo({ typecheck: 'exit 1', lint: 'exit 1' });
+  try {
+    const parked = hook(r.dir, `refs/heads/x ${r.sha} refs/xema-session/lead/T1/x ${'0'.repeat(40)}\n`);
+    assert.equal(parked.status, 0, parked.stdout + parked.stderr);
+    assert.match(parked.stdout, /skipped — every ref is a session park/);
+    const mixed = hook(r.dir, `refs/heads/x ${r.sha} refs/xema-session/lead/T1/x ${'0'.repeat(40)}\nrefs/heads/x ${r.sha} refs/heads/develop ${'0'.repeat(40)}\n`);
+    assert.equal(mixed.status, 1, mixed.stdout + mixed.stderr);
+    assert.match(mixed.stdout, /pre-push: FAILED/);
+  } finally {
+    rmSync(r.dir, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+// `prove`: the IN-IMAGE half of a per-service image (`xema-service-image`). The Dockerfile's
+// proof stage runs it on the TARGET platform, `--network=none`, with the staged app and this
+// tool bind-mounted, the stage manifest COPYed into <proof dir>, and the repository's root build
+// inputs COPYed from the build context into <proof dir>/context:
+//
+//   node <tool>/src/service-image-in-image.mjs prove <app dir> <proof dir> --service <service> --commit <sha>
+//
+// The image's content tag is computed from the build context, not from the stage, so the stage
+// must be proved to be the build context's. `prove` refuses the image unless: the manifest names
+// <service>; it was staged at <sha> (the BUILD_SHA the image is built for, so a stale stage
+// cannot ship); the root build inputs in the build context (`ROOT_BUILD_INPUT`: the lockfile,
+// the root manifest, the workspace, .npmrc, .pnpmfile.cjs, turbo.json, tsconfig*.json) are
+// exactly the ones the stage hashed, which also proves the Dockerfile COPYs every one of them
+// (and so the content tag covers them); this tool is the version the stage recorded; this
+// process runs on the manifest's platform; the Node ABI is the stager's when the app carries
+// Node addons; every package's addons load here (`process.dlopen`: an ELF for the right
+// machine can still need a newer glibc than the image has), where a package that ships several
+// builds needs one that loads; Prisma computes, HERE, the binaryTarget whose schema engine was
+// staged, and that engine has the staged sha256 and reports the pinned version; dist/main.js
+// exists. It then writes <proof dir>/verified.json, which the final stage ships, so the image
+// cannot be built without the proof.
+//
+// Loads only `node:` builtins and relative modules that do too (Prisma's own modules are
+// resolved from the app).
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { prismaEnginesDirectories, verifySchemaEngine } from './composed-image-prisma-engine.mjs';
+import { currentPlatform } from './service-image-platform.mjs';
+
+export const MANIFEST_FILE = 'xema-service-image.json';
+export const MANIFEST_SCHEMA = 2;
+export const VERIFIED_FILE = 'verified.json';
+export const LOCKFILE = 'pnpm-lock.yaml';
+/** The proof dir's subdirectory the Dockerfile COPYs the root build inputs into. */
+export const CONTEXT_DIRECTORY = 'context';
+/**
+ * Repository-root files that steer the runner's install and build, so they decide the staged
+ * bytes. The stage hashes every one present; the Dockerfile must COPY each into the proof
+ * context, which puts it in the content tag.
+ */
+export const ROOT_BUILD_INPUT = /^(pnpm-lock\.yaml|package\.json|pnpm-workspace\.yaml|\.npmrc|\.pnpmfile\.cjs|turbo\.json|tsconfig[^/]*\.json)$/;
+export const TOOL_NAME = '@xemahq/repo-build-tooling';
+const TOOL_DIRECTORY = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+export const sha256File = (file) => createHash('sha256').update(readFileSync(file)).digest('hex');
+
+/** The version of the tool running this code (the stage's copy, in the image). */
+export const ownToolVersion = () => JSON.parse(readFileSync(join(TOOL_DIRECTORY, 'package.json'), 'utf8')).version;
+
+/** Load one Node addon the way `require` does. */
+const dlopen = (file) => process.dlopen({ exports: {} }, file);
+
+const getBinaryTarget = (enginesDir) =>
+  createRequire(join(enginesDir, 'package.json'))('@prisma/get-platform').getBinaryTargetForCurrentPlatform();
+
+/** The problems that keep the root build inputs in `contextDir` from being the ones `inputs` recorded. */
+function contextProblems(contextDir, inputs) {
+  const problems = [];
+  const carried = existsSync(contextDir) ? readdirSync(contextDir).sort() : [];
+  for (const name of Object.keys(inputs).sort()) {
+    if (!carried.includes(name)) {
+      problems.push(`${name} is a root build input of the stage, and the build context does not carry it: ` +
+        `COPY it into /proof/${CONTEXT_DIRECTORY}/ in the Dockerfile and admit it in its .dockerignore, so the content tag covers it`);
+    } else if (sha256File(join(contextDir, name)) !== inputs[name]) {
+      problems.push(`the build context's ${name} is not the one the stage was built from: re-stage`);
+    }
+  }
+  for (const name of carried) {
+    if (!Object.hasOwn(inputs, name)) problems.push(`the build context carries ${name}, which the stage did not hash as a root build input`);
+  }
+  return problems;
+}
+
+/** Each package's addons (`natives`: package dir -> its target ELF files) must load: one per package. */
+function loadProblems(appDir, natives, load) {
+  const problems = [];
+  for (const [owner, files] of Object.entries(natives)) {
+    const addons = files.filter((file) => file.endsWith('.node'));
+    const failures = [];
+    for (const addon of addons) {
+      try {
+        load(join(appDir, addon));
+        break;
+      } catch (error) {
+        failures.push(`${addon}: ${String(error.message).split('\n')[0]}`);
+      }
+    }
+    if (addons.length > 0 && failures.length === addons.length) {
+      problems.push(`no Node addon of ${owner} loads on this image:\n${failures.map((f) => `      ${f}`).join('\n')}`);
+    }
+  }
+  return problems;
+}
+
+/**
+ * Check a staged app against its manifest and the build context, on this platform. Throws once,
+ * naming every failed check. `platform`, `nodeAbi`, `binaryTarget`, `version`, `load` and
+ * `toolVersion` are injectable for tests.
+ */
+export async function prove({
+  appDir,
+  proofDir,
+  service,
+  commit,
+  platform = currentPlatform(),
+  nodeAbi = process.versions.modules,
+  binaryTarget = getBinaryTarget,
+  version,
+  load = dlopen,
+  toolVersion = ownToolVersion(),
+  log = console.log,
+}) {
+  const manifest = JSON.parse(readFileSync(join(proofDir, MANIFEST_FILE), 'utf8'));
+  if (manifest.schema !== MANIFEST_SCHEMA) {
+    throw new Error(`the stage manifest is schema ${manifest.schema}, this proof reads schema ${MANIFEST_SCHEMA}: re-stage with this tool`);
+  }
+  const problems = [];
+  if (manifest.service !== service) problems.push(`the stage is for '${manifest.service}', this build is for '${service}'`);
+  if (manifest.commit !== commit) problems.push(`the stage was built at ${manifest.commit}, this image is for ${commit}: re-stage`);
+  problems.push(...contextProblems(join(proofDir, CONTEXT_DIRECTORY), manifest.inputs));
+  if (manifest.tool?.name !== TOOL_NAME || manifest.tool?.version !== toolVersion) {
+    problems.push(`the stage was made by ${manifest.tool?.name}@${manifest.tool?.version}, this proof is ${TOOL_NAME}@${toolVersion}`);
+  }
+  const onPlatform = manifest.platform === platform;
+  if (!onPlatform) problems.push(`the stage is for ${manifest.platform}, this build runs on ${platform}`);
+  const addons = Object.values(manifest.natives).flat().filter((file) => file.endsWith('.node'));
+  const sameAbi = addons.length === 0 || manifest.nodeAbi === nodeAbi;
+  if (!sameAbi) {
+    problems.push(`the app carries Node addons (${addons.join(', ')}) built for Node ABI ${manifest.nodeAbi}, the image's Node is ABI ${nodeAbi}`);
+  }
+  if (onPlatform && sameAbi) problems.push(...loadProblems(appDir, manifest.natives, load));
+  if (!existsSync(join(appDir, 'dist', 'main.js'))) problems.push('dist/main.js does not exist');
+
+  const enginesDirs = existsSync(join(appDir, 'node_modules', '.pnpm')) ? prismaEnginesDirectories(appDir) : [];
+  if (manifest.prisma === null && enginesDirs.length > 0) problems.push('the app carries a prisma CLI, but the stage staged no schema engine');
+  if (manifest.prisma !== null && enginesDirs.length === 0) problems.push('the stage staged a schema engine, but the app carries no prisma CLI');
+  for (const enginesDir of manifest.prisma === null ? [] : enginesDirs) {
+    const target = await binaryTarget(enginesDir);
+    if (target !== manifest.prisma.binaryTarget) {
+      problems.push(`Prisma computes binaryTarget ${target} here, the stage staged ${manifest.prisma.binaryTarget}`);
+      continue;
+    }
+    const engine = join(enginesDir, `schema-engine-${target}`);
+    if (!existsSync(engine)) {
+      problems.push(`${engine} does not exist`);
+      continue;
+    }
+    if (sha256File(engine) !== manifest.prisma.sha256) {
+      problems.push(`${engine} is not the schema engine the stage fetched and verified (sha256 ${manifest.prisma.sha256})`);
+      continue;
+    }
+    try {
+      log(`prisma schema engine: ${engine} (${verifySchemaEngine(engine, manifest.prisma.enginesVersion, version)})`);
+    } catch (error) {
+      problems.push(error.message);
+    }
+  }
+  if (problems.length > 0) throw new Error(`the staged ${manifest.service} is not this image's:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+  copyFileSync(join(proofDir, MANIFEST_FILE), join(proofDir, VERIFIED_FILE));
+  log(`proved ${service} at ${commit} on ${platform}`);
+  return manifest;
+}
+
+const USAGE = 'usage: service-image-in-image.mjs prove <app dir> <proof dir> --service <service> --commit <40-hex sha>';
+
+export function parseProveArgs(argv) {
+  const [verb, appDir, proofDir, ...rest] = argv;
+  if (verb !== 'prove' || appDir === undefined || proofDir === undefined || rest.length !== 4) throw new Error(USAGE);
+  const options = {};
+  for (let i = 0; i < rest.length; i += 2) {
+    const name = { '--service': 'service', '--commit': 'commit' }[rest[i]];
+    if (name === undefined || Object.hasOwn(options, name)) throw new Error(USAGE);
+    options[name] = rest[i + 1];
+  }
+  if (!/^[a-z0-9@][a-z0-9@/._-]*$/.test(options.service ?? '')) throw new Error(`--service must name a workspace package\n${USAGE}`);
+  if (!/^[0-9a-f]{40}$/.test(options.commit ?? '')) throw new Error(`--commit must be the 40-hex commit the image is built for (BUILD_SHA)\n${USAGE}`);
+  return { appDir: resolve(appDir), proofDir: resolve(proofDir), service: options.service, commit: options.commit };
+}
+
+// realpath both sides: Node resolves the entry module's symlinks, `process.argv[1]` keeps them.
+const invokedPath = process.argv[1] ? realpathSync(process.argv[1]) : undefined;
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  Promise.resolve()
+    .then(() => prove(parseProveArgs(process.argv.slice(2))))
+    .catch((error) => {
+      console.error(error.message);
+      process.exit(1);
+    });
+}

package/src/service-image-platform.mjs

@@ -0,0 +1,128 @@
+// The target platform of a per-service image (`xema-service-image`), and the proof that a
+// staged tree holds native code for that platform only. Loads only `node:` builtins: the
+// in-image `prove` step imports it from the bind-mounted tool directory.
+import { closeSync, existsSync, openSync, readSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * The image platforms this recipe builds, keyed by Docker's `TARGETARCH`. `node` is Node's
+ * `process.arch`, `elfMachine` the ELF `e_machine` of native code for it, `prismaBinaryTarget`
+ * the binaryTarget Prisma's get-platform computes inside the runtime base image
+ * (node:22-bookworm-slim + openssl 3.0). The in-image `prove` step re-computes the last one on
+ * the target and refuses the image when it differs, so a base image change cannot ship a
+ * schema engine Prisma would not use.
+ */
+export const IMAGE_PLATFORMS = Object.freeze({
+  amd64: Object.freeze({ node: 'x64', elfMachine: 62, prismaBinaryTarget: 'debian-openssl-3.0.x' }),
+  arm64: Object.freeze({ node: 'arm64', elfMachine: 183, prismaBinaryTarget: 'linux-arm64-openssl-3.0.x' }),
+});
+
+/** `linux/<arch>` → `<arch>`; refuses any platform this recipe does not build. */
+export function platformArch(platform) {
+  const match = /^linux\/([a-z0-9]+)$/.exec(String(platform ?? ''));
+  if (match === null || !Object.hasOwn(IMAGE_PLATFORMS, match[1])) {
+    throw new Error(`--platform must be one of ${Object.keys(IMAGE_PLATFORMS).map((a) => `linux/${a}`).join(', ')}, got '${platform}'`);
+  }
+  return match[1];
+}
+
+/** The `linux/<arch>` this Node process runs on (the in-image check of the target). */
+export function currentPlatform(nodeArch = process.arch) {
+  const arch = Object.keys(IMAGE_PLATFORMS).find((key) => IMAGE_PLATFORMS[key].node === nodeArch);
+  if (arch === undefined) throw new Error(`Node arch '${nodeArch}' is not an image platform this recipe builds`);
+  return `linux/${arch}`;
+}
+
+const MACH_O = new Set([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe, 0xcafebabe]);
+
+/** What the first bytes of a file say it is: `{ format: 'elf', machine }`, `{ format: 'mach-o' }`, `{ format: 'pe' }` or `undefined`. */
+export function nativeFormat(header) {
+  if (header.length >= 20 && header[0] === 0x7f && header[1] === 0x45 && header[2] === 0x4c && header[3] === 0x46) {
+    const littleEndian = header[5] === 1;
+    return { format: 'elf', machine: littleEndian ? header.readUInt16LE(18) : header.readUInt16BE(18) };
+  }
+  if (header.length >= 4 && MACH_O.has(header.readUInt32BE(0))) return { format: 'mach-o' };
+  if (header.length >= 2 && header[0] === 0x4d && header[1] === 0x5a) return { format: 'pe' };
+  return undefined;
+}
+
+function readHeader(file) {
+  const fd = openSync(file, 'r');
+  try {
+    const buffer = Buffer.alloc(20);
+    const read = readSync(fd, buffer, 0, 20, 0);
+    return buffer.subarray(0, read);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** The directory of the nearest `package.json` at or above `dir`, stopping at `root` (`root` itself when none). */
+function owningPackage(root, rel) {
+  const parts = rel.split('/').slice(0, -1);
+  for (let n = parts.length; n > 0; n -= 1) {
+    const candidate = parts.slice(0, n).join('/');
+    if (existsSync(join(root, candidate, 'package.json'))) return candidate;
+  }
+  return '.';
+}
+
+/**
+ * Every native file under `root` for `arch` (relative, sorted), and the problems that keep the tree out
+ * of a linux/`arch` image. Native code is judged PER PACKAGE (the nearest `package.json`): a package may
+ * ship prebuilt binaries for several platforms and load the one for the platform it runs on
+ * (`@temporalio/core-bridge` carries `releases/<triple>/index.node`). A package is refused when it
+ * carries native code (an ELF object, a Mach-O, a `.node` addon; a PE header counts only on
+ * `.node`/`.exe`/`.dll`, as `MZ` also opens ordinary data) and NONE of it is an ELF for `arch`: then the
+ * binary it would load was built for another machine (a host build) and cannot run here.
+ * `natives` lists the ELF objects for `arch`; `byPackage` groups them by owning package (the in-image
+ * proof loads each package's addons on the target); `foreign` the other platforms' files a refused
+ * package did not cause. Symlinks are not followed.
+ */
+export function scanNatives(root, arch) {
+  const { elfMachine } = IMAGE_PLATFORMS[arch];
+  const packages = new Map(); // package dir -> { target: [], foreign: [] }
+  const record = (rel, isTarget, why) => {
+    const owner = owningPackage(root, rel);
+    if (!packages.has(owner)) packages.set(owner, { target: [], foreign: [] });
+    const entry = packages.get(owner);
+    if (isTarget) entry.target.push(rel);
+    else entry.foreign.push(`${rel}: ${why}`);
+  };
+  const walk = (dir, prefix) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      const rel = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+      if (entry.isDirectory()) {
+        walk(join(dir, entry.name), rel);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const kind = nativeFormat(readHeader(join(dir, entry.name)));
+      if (kind?.format === 'elf') {
+        if (kind.machine === elfMachine) record(rel, true);
+        else record(rel, false, `ELF e_machine ${kind.machine}, the linux/${arch} image needs ${elfMachine}`);
+      } else if (kind?.format === 'mach-o') {
+        record(rel, false, 'a Mach-O binary');
+      } else if (kind?.format === 'pe' && /\.(node|exe|dll)$/.test(entry.name)) {
+        record(rel, false, 'a Windows binary');
+      } else if (entry.name.endsWith('.node')) {
+        record(rel, false, 'a native addon that is not an ELF object');
+      }
+    }
+  };
+  walk(root, '');
+  const natives = [];
+  const byPackage = {};
+  const foreign = [];
+  const problems = [];
+  for (const [owner, { target, foreign: others }] of [...packages].sort(([a], [b]) => (a < b ? -1 : 1))) {
+    natives.push(...target);
+    if (target.length > 0) byPackage[owner] = [...target].sort();
+    if (target.length === 0) {
+      problems.push(`${owner} carries native code and none of it is for linux/${arch}:\n${others.map((o) => `      ${o}`).join('\n')}`);
+    } else {
+      foreign.push(...others.map((o) => o.slice(0, o.indexOf(': '))));
+    }
+  }
+  return { natives: natives.sort(), byPackage, foreign: foreign.sort(), problems };
+}