@xemahq/repo-build-tooling 0.21.2 → 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.2",
+  "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-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:417658f5270347a7cfc99992c7004050eb9f0603498c75094f9610da66f6ccb2"
+    "sourceDigest": "sha256:0b63df80f6c68f70cb652dfc51f08288aeac11bbee2445cfa6fc440242a7bcf9"
   }
 }

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

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

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

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

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

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

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

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

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

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

package/src/prepush-sanity.mjs

@@ -6,14 +6,16 @@
 //
 // With turbo (a `turbo.json` and a turbo dependency): turbo `lint` and `typecheck` run only on the packages
 // the pushed commits change plus their dependents. A change to the lockfile,
-// root package.json or turbo.json invalidates everything and runs the full
-// graph. A repo whose turbo carries no `lint` task also runs its root `lint`
+// turbo.json, or anything in the root package.json other than its `scripts`
+// table invalidates everything and runs the full graph. A repo whose turbo carries no `lint` task also runs its root `lint`
 // script. Without turbo: the root `lint` script only (typecheck needs a build, which the hook never runs; CI has it).
 //
 // The pushed SHA is what is graded. In place when the tree is clean and the SHA
 // 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,9 +82,32 @@ export function parseRefs(stdin) {
   return refs;
 }
 
-/** True when a changed path invalidates every package. */
-export function isFleetWide(changedPaths) {
-  return changedPaths.some((p) => p === 'pnpm-lock.yaml' || p === 'package.json' || p === 'turbo.json');
+/** 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 {
+    const { scripts: _baseScripts, ...base } = JSON.parse(baseText);
+    const { scripts: _tipScripts, ...tip } = JSON.parse(tipText);
+    return JSON.stringify(base) === JSON.stringify(tip);
+  } catch {
+    return false;
+  }
+}
+
+/** True when a changed path invalidates every package. `rootScriptsOnly`: the root package.json change is the `scripts` table alone. */
+export function isFleetWide(changedPaths, rootScriptsOnly = false) {
+  return changedPaths.some((p) => p === 'pnpm-lock.yaml' || p === 'turbo.json' || (p === 'package.json' && !rootScriptsOnly));
 }
 
 /**
@@ -148,8 +173,9 @@ function rangeFor(ctx, base, sha) {
     return '';
   }
   const changed = (ctx.gitOut(['diff', '--name-only', `${base}...${sha}`]) ?? '').split('\n').filter(Boolean);
-  if (isFleetWide(changed)) {
-    console.error('pre-push: lockfile, root package.json or turbo.json changed — fleet-wide, running the FULL graph.');
+  const rootScriptsOnly = changed.includes('package.json') && scriptsOnlyChange(ctx.gitOut(['show', `${base}:package.json`]) ?? '', ctx.gitOut(['show', `${sha}:package.json`]) ?? '');
+  if (isFleetWide(changed, rootScriptsOnly)) {
+    console.error('pre-push: lockfile, turbo.json or root package.json beyond its scripts changed — fleet-wide, running the FULL graph.');
     return '';
   }
   return `${base}...${sha}`;
@@ -306,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, 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);
@@ -29,12 +29,26 @@ test('parseRefs dedupes shas and drops deletes and junk', () => {
   assert.deepEqual(parseRefs(''), []);
 });
 
-test('isFleetWide flags only the lockfile, root package.json and turbo.json', () => {
+test('isFleetWide flags the lockfile, turbo.json and a root package.json change beyond scripts', () => {
   assert.equal(isFleetWide(['pnpm-lock.yaml']), true);
+  assert.equal(isFleetWide(['turbo.json']), true);
   assert.equal(isFleetWide(['package.json']), true);
+  assert.equal(isFleetWide(['package.json'], true), false);
+  assert.equal(isFleetWide(['package.json', 'pnpm-lock.yaml'], true), true);
   assert.equal(isFleetWide(['packages/a/package.json', 'src/x.ts']), false);
 });
 
+test('scriptsOnlyChange: only the scripts key may differ; anything else or unreadable is fleet-wide', () => {
+  const base = { name: 't', scripts: { a: '1' }, dependencies: { x: '1' }, packageManager: 'pnpm@10.0.0' };
+  const text = (o) => JSON.stringify(o);
+  assert.equal(scriptsOnlyChange(text(base), text({ ...base, scripts: { a: '2', b: '3' } })), true);
+  for (const change of [{ dependencies: { x: '2' } }, { packageManager: 'pnpm@10.1.0' }, { pnpm: { overrides: {} } }, { engines: { node: '22' } }]) {
+    assert.equal(scriptsOnlyChange(text(base), text({ ...base, ...change })), false, Object.keys(change)[0]);
+  }
+  assert.equal(scriptsOnlyChange('', text(base)), false);
+  assert.equal(scriptsOnlyChange(text(base), '{ nope'), false);
+});
+
 test('blockingPath: package reads and repo-root files block, root markdown does not', () => {
   const owned = (p) => p.startsWith('packages/');
   assert.equal(blockingPath(['packages/a/src/x.ts'], ['packages/a'], owned)?.why, 'is in a package this run reads');
@@ -122,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 });
+  }
+});