@xemahq/repo-build-tooling 0.25.0 → 0.26.0

package/README.md

@@ -29,7 +29,7 @@ pnpm exec xema-scrub-swagger-paths dist
 | `xema-readiness` | Runs the ordered checks between a source change and a push |
 | `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-composed-image <command>` | Build-time half of a composed-process image: `members`, `filters`, `dirs`, `pins`, `index`, `load`, `stage`, `stage-tree`, `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 |
@@ -37,7 +37,11 @@ pnpm exec xema-scrub-swagger-paths dist
 | `xema-prepush-sanity` | Lefthook `pre-push`: turbo `lint` and `typecheck` on what the push changes plus dependents, and `test` and `openapi:current` (where defined) only on the packages the push changed; a fleet-wide change runs only `lint` and `typecheck` on the full graph; root `lint` only without turbo; a park-only push (`refs/xema-session/*`) skips |
 | `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` and `--base <ref@sha256:…>`, the digest-pinned image the stages start FROM; a reference without a digest is refused; `--copy` and `--stage-dir` optional). The assemble stage copies per package only `package.json` and its plain `files` entries (what `pnpm pack` ships), so a README or test edit changes no image; a package without a `files` array or with a glob entry is refused; `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.
+`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 that only COPIES a tree the CI runner staged: no `RUN pnpm install`, no corepack, no secret, no network (every RUN is `--network=none`). It requires `--build-source`, `--base <ref@sha256:…>` (the digest-pinned image the stages start FROM; a reference without a digest is refused) and `--node-major <n>` (that base's Node major, rendered as the `dev.xema.composed-image.node-major` label, which the stage compares with the runner's Node); `--copy` and `--stage-dir` are optional and `--cache-id` is refused (there is no cache). The proof stage COPIES the root build inputs (`pnpm-lock.yaml`, root `package.json`, `pnpm-workspace.yaml`, `.npmrc`, `.pnpmfile.cjs`, `turbo.json`, `tsconfig*.json`, whichever exist) into `/proof/context/` and the `--copy` directories into `/proof/copied/`, which puts exactly the bytes that decided the staged tree in the image's content tag, and runs `prove`, `prisma-check` and `load --each`; the final stage COPIES the two staged layers and the proof's verdict. The `--filter <package>...` words in the `prove` line are literal: the content hash reads them to narrow the lockfile.
+
+`stage-tree <dir> --platform linux/<amd64|arm64> [--output <rel>]…` is the runner half, run after the build and the job's own `pnpm install --frozen-lockfile`. It checks the members' build outputs (as `stage` does), then runs an OFFLINE, frozen, `--ignore-scripts` production install of the members' closures into a staging tree from the job's pnpm store, selected for the target platform (`--os=linux --cpu=<arch> --libc=glibc`, workspace packages injected, the re-resolved lockfile checked to pin nothing new); copies in only each package's `package.json` and declared `files` (plus the built outputs among them), the `--copy` directories, the biome manifests and `image-build-inputs.json`; writes the member index and host link; fetches the platform's Prisma schema engine (checksum-verified, never cached) when the closure carries the prisma CLI; and refuses a dependency that needs its build script on the target, a package whose native code holds no ELF for the platform, an uncommitted change to a tracked file and an untracked root build input. Output: `<dir>/layers/store` (the registry packages, stable until the lockfile changes), `<dir>/layers/app` (everything else), `<dir>/proof/xema-composed-image.json` (commit, sha256 of each root build input and `--copy` directory, the literal filters, members, natives, engine, tool version, platform) and `<dir>/tool`. `--also` is not accepted. A refused stage leaves nothing behind. The in-image `prove` refuses the build unless the stage was made at `BUILD_SHA`, from the context's bytes, with this tool version, for the platform the build runs on, with the Dockerfile's filters, and every addon loads and the engine runs there. `stage <dir> [--output <rel>]… [--also <pkg>]…` remains as the outputs-only stage (`<dir>/out`, `<dir>/tool`) for per-service prebuilt images that still read it. `pnpm-context <dir> --subject <svc>…` builds the offline `xema-pnpm` context for those images (`staged.json`, `corepack/pnpm.tgz`); it prints `XEMA_PNPM_CONTEXT=<dir>` and `XEMA_PNPM_STORE=<store root>` and refuses a non-empty `<dir>`. `load --each` loads every member in its own process. Run `xema-composed-image` with no arguments for the full usage.
 
 Every step refuses rather than skips. The package has no dependencies.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.25.0",
+  "version": "0.26.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)",
@@ -51,9 +51,9 @@
     "@xemahq/release-policy": "^16.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-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 && node --test src/install-git-hooks.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-stage-tree.test.mjs && node --test src/composed-image-install.test.mjs && node --test src/composed-image-proof.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 && node --test src/install-git-hooks.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:60086692452e7d72167195fe99ab5634a798fd8b2461a6e0b09bb27b894b7aa4"
+    "sourceDigest": "sha256:eb28744794a3da50dbb000a38b05bdd4da61176ff6495a664e1d58d22d1979ad"
   }
 }

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

@@ -9,7 +9,7 @@ import test, { after } from 'node:test';
 
 import { renderPrebuiltDockerfile } from './composed-image-prebuilt-dockerfile.mjs';
 import { copyTool } from './composed-image-stage.mjs';
-import { BASE, fakePnpm, workspace } from './composed-image-fixture.test.mjs';
+import { BASE, workspace } from './composed-image-fixture.test.mjs';
 
 const temps = [];
 after(() => {
@@ -27,29 +27,21 @@ function renderedEntries() {
   const { dockerfile } = renderPrebuiltDockerfile({
     root,
     copy: ['tooling/dev'],
-    cacheId: 'alpha-composed-process',
-    buildSource: 'alpha', base: BASE,
-    usesToken: true,
-    exec: fakePnpm(root),
+    buildSource: 'alpha', base: BASE, nodeMajor: '22',
   });
   const entries = [...new Set([...dockerfile.matchAll(/node \/opt\/xema-composed-image\/(\S+\.mjs)/g)].map((m) => m[1]))];
   assert.ok(entries.length > 0, 'the rendered Dockerfile runs at least one tool entry');
   return entries;
 }
 
-const LOCKFILE = "lockfileVersion: '9.0'\n\npackages:\n\n  left-pad@1.3.0:\n    resolution: {integrity: sha512-x}\n";
-
-test('every in-image entry runs from the copied tool directory with no node_modules', () => {
+test('every in-image entry runs from the copied tool directory with no node_modules (it reaches its own usage error, never a missing module)', () => {
   const tool = path.join(temp('xema-tool-'), 'tool');
   copyTool(tool);
-  const root = temp('xema-root-');
-  fs.writeFileSync(path.join(root, 'pnpm-lock.yaml'), LOCKFILE);
-  const committed = path.join(root, 'committed.yaml');
-  fs.copyFileSync(path.join(root, 'pnpm-lock.yaml'), committed);
   for (const entry of renderedEntries()) {
-    const result = spawnSync(process.execPath, [path.join(tool, entry), 'pins', committed, '--root', root], { encoding: 'utf8' });
+    const result = spawnSync(process.execPath, [path.join(tool, entry), 'nonsense'], { encoding: 'utf8' });
     assert.doesNotMatch(result.stderr, /ERR_MODULE_NOT_FOUND/, `${entry}: ${result.stderr}`);
-    assert.equal(result.status, 0, `${entry} exited ${result.status}: ${result.stderr}`);
+    assert.equal(result.status, 1, `${entry} exited ${result.status}`);
+    assert.match(result.stderr, /usage: composed-image-in-image/);
   }
 });
 

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

@@ -3,13 +3,12 @@
 // 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`,
-// `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.
+// (NO node_modules) and runs THIS file for `prove`, `prisma-check` and `load --each`. 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; the runner's staging (`index`, `pins`,
+// `sync-injected`) uses them directly.
 // ═══════════════════════════════════════════════════════════════════════════
 
 import { spawnSync } from 'node:child_process';
@@ -20,9 +19,8 @@ import { pathToFileURL } from 'node:url';
 
 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';
+import { proveComposed } from './composed-image-proof.mjs';
 
 export const MEMBER_INDEX_FILE = 'xema-composed-member-index.json';
 export const HOST_LINK = 'xema-composed-process';
@@ -185,7 +183,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 | prisma-schema-engine <staged dir>';
+  '  prove <proof dir> --commit <sha> --filter <word>… | index <commit> --build-source <repo> | load [--each] | prisma-check';
 
 function parseInImageArguments(argv) {
   const positional = [];
@@ -201,11 +199,12 @@ function parseInImageArguments(argv) {
       options.each = true;
       continue;
     }
-    if (name !== 'root' && name !== 'image-dir' && name !== 'build-source') throw new Error(`unknown option ${arg}\n${USAGE}`);
+    if (name !== 'root' && name !== 'image-dir' && name !== 'build-source' && name !== 'commit' && name !== 'filter') throw new Error(`unknown option ${arg}\n${USAGE}`);
     const value = argv[i + 1];
     if (value === undefined || value.startsWith('--')) throw new Error(`${arg} needs a value`);
     i += 1;
-    options[name] = value;
+    if (name === 'filter') (options.filter ??= []).push(value);
+    else options[name] = value;
   }
   return { command: positional[0], argument: positional[1], options };
 }
@@ -215,11 +214,6 @@ export function main(argv, { log = console.log } = {}) {
   const root = resolve(options.root ?? process.cwd());
   const imageDir = options['image-dir'] ?? COMPOSED_IMAGE_DIR;
   switch (command) {
-    case 'pins': {
-      const count = assertPinsUnchanged({ root, committedLockfile: argument });
-      log(`composed install: every registry pin is the committed lockfile's (${count})`);
-      return;
-    }
     case 'index': {
       const result = writeMemberIndex({ root, imageDir, commit: argument, buildSourceRepository: options['build-source'] });
       log(`composed member index: ${result.members} member(s) at ${argument}; host ${result.host}`);
@@ -232,13 +226,14 @@ export function main(argv, { log = console.log } = {}) {
       }
       log(`composed members: all ${loadMembers({ root, imageDir })} module graph(s) load`);
       return;
-    case 'sync-injected':
-      syncInjected({ root, imageDir, 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);
+    case 'prove': {
+      if (argument === undefined) throw new Error(USAGE);
+      if (!COMMIT.test(options.commit ?? '')) throw new Error(`--commit must be the 40-hex commit the image is built for (BUILD_SHA)\n${USAGE}`);
+      const filters = (options.filter ?? []).map((word) => `--filter ${word}`);
+      return proveComposed({ proofDir: resolve(argument), root, commit: options.commit, filters, imageDir, log }).then(() => undefined);
+    }
     default:
       throw new Error(USAGE);
   }

package/src/composed-image-install.mjs

@@ -0,0 +1,46 @@
+// The composed image's production install, run on the CI RUNNER inside the staged tree
+// (`composed-image-stage-tree.mjs`), never in Docker. It is the install the image used to run
+// itself, with the same words: the workspace packages are INJECTED, the lockfile is re-resolved
+// for the members' closures only and checked to pin nothing new, then production dependencies are
+// installed from the runner's pnpm store alone (`--offline`, `--ignore-scripts`), selected for the
+// TARGET platform (`--os/--cpu/--libc`) so no foreign-platform binary is staged.
+import { execFileSync } from 'node:child_process';
+import { copyFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { assertPinsUnchanged } from './composed-image-in-image.mjs';
+
+/** The install-flag words that make pnpm copy workspace packages into the store layout. */
+export const injectFlags = () => ['--config.inject-workspace-packages=true', '--config.dedupe-injected-deps=false'];
+
+/** The `--lockfile-only` re-resolve for `filters` (`['--filter', '<pkg>...', ...]`) as `[file, ...args]`. */
+export const lockfileOnlyCommand = (filters) => ['pnpm', 'install', '--lockfile-only', '--prefer-offline', ...injectFlags(), ...filters];
+
+/** The production install for `filters` on `linux/<arch>` as `[file, ...args]`. */
+export const productionInstallCommand = (filters, arch) => [
+  'pnpm', 'install', '--prod', '--offline', '--ignore-scripts', ...injectFlags(), ...filters, '--frozen-lockfile',
+  '--os=linux', `--cpu=${arch}`, '--libc=glibc',
+];
+
+const defaultExec = (file, args, { cwd }) => execFileSync(file, args, { cwd, stdio: 'inherit' });
+
+/**
+ * Install the members' production closure into `treeRoot` (which holds the root manifests, the lockfile and the
+ * closure's package files). `filters` are the members' literal `--filter <package>...` words. Throws when the
+ * re-resolve pinned a registry package the committed lockfile does not.
+ */
+export function installClosure({ treeRoot, filters, arch, exec = defaultExec }) {
+  const scratch = mkdtempSync(join(tmpdir(), 'xema-composed-lock-'));
+  try {
+    const committed = join(scratch, 'pnpm-lock.committed.yaml');
+    copyFileSync(join(treeRoot, 'pnpm-lock.yaml'), committed);
+    const [resolveFile, ...resolveArgs] = lockfileOnlyCommand(filters);
+    exec(resolveFile, resolveArgs, { cwd: treeRoot });
+    assertPinsUnchanged({ root: treeRoot, committedLockfile: committed });
+    const [installFile, ...installArgs] = productionInstallCommand(filters, arch);
+    exec(installFile, installArgs, { cwd: treeRoot });
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}

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

@@ -0,0 +1,40 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { installClosure, lockfileOnlyCommand, productionInstallCommand } from './composed-image-install.mjs';
+
+const lock = (...pins) => `lockfileVersion: '9.0'\n\npackages:\n\n${pins.map((p) => `  ${p}:\n    resolution: {integrity: sha512-x}\n`).join('\n')}`;
+const FILTERS = ['--filter', '@t/a...', '--filter', '@t/b...'];
+
+function tree(committed) {
+  const treeRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-install-'));
+  fs.writeFileSync(path.join(treeRoot, 'pnpm-lock.yaml'), committed);
+  return treeRoot;
+}
+
+test('the re-resolve then the production install run in the tree, offline and frozen, for the target platform, with the literal filters', () => {
+  const treeRoot = tree(lock('left-pad@1.3.0'));
+  const calls = [];
+  installClosure({ treeRoot, filters: FILTERS, arch: 'arm64', exec: (file, args, options) => calls.push({ line: [file, ...args], cwd: options.cwd }) });
+  assert.deepEqual(calls.map((c) => c.cwd), [treeRoot, treeRoot]);
+  assert.deepEqual(calls[0].line, lockfileOnlyCommand(FILTERS));
+  assert.deepEqual(calls[1].line, productionInstallCommand(FILTERS, 'arm64'));
+  const install = calls[1].line.join(' ');
+  for (const word of ['install --prod --offline --ignore-scripts', '--frozen-lockfile', '--os=linux --cpu=arm64 --libc=glibc', '--config.inject-workspace-packages=true', '--filter @t/a... --filter @t/b...']) assert.ok(install.includes(word), word);
+  assert.doesNotMatch(install, /--prefer-offline/);
+  assert.ok(calls[0].line.includes('--lockfile-only') && !calls[0].line.includes('--frozen-lockfile'));
+});
+
+test('a re-resolution that pins a registry package the committed lockfile does not stops before the install', () => {
+  const treeRoot = tree(lock('left-pad@1.3.0'));
+  const calls = [];
+  const exec = (file, args) => {
+    calls.push(args);
+    if (args.includes('--lockfile-only')) fs.writeFileSync(path.join(treeRoot, 'pnpm-lock.yaml'), lock('left-pad@1.3.0', 'evil@9.9.9'));
+  };
+  assert.throws(() => installClosure({ treeRoot, filters: FILTERS, arch: 'amd64', exec }), /pinned registry package\(s\) the committed lockfile does not:\n {2}- evil@9\.9\.9/);
+  assert.equal(calls.length, 1, 'the production install never ran');
+});

package/src/composed-image-paths.mjs

@@ -3,3 +3,23 @@ export const COMPOSED_IMAGE_DIR = 'infra/composed-process';
 
 // The one entry the prebuilt image runs from the bind-mounted tool directory: loads only `node:` and relative modules.
 export const IN_IMAGE_ENTRY = 'src/composed-image-in-image.mjs';
+
+/** The image label that carries the Node major of the pinned base: a digest reference does not name it, and the stage compares the runner's Node with it. */
+export const NODE_MAJOR_LABEL = 'dev.xema.composed-image.node-major';
+
+// The layout of the stage directory the prebuilt Dockerfile COPYs from (relative to the stage dir).
+/** Production packages (`node_modules/.pnpm`): stable until the lockfile changes. Copied to `/`. */
+export const STAGE_STORE_LAYER = 'layers/store';
+/** Everything else of `/monorepo`. Copied to `/`. */
+export const STAGE_APP_LAYER = 'layers/app';
+/** The stage manifest the proof reads. */
+export const STAGE_PROOF_DIRECTORY = 'proof';
+/** The image's root directory, under each layer. */
+export const IMAGE_ROOT_DIRECTORY = 'monorepo';
+/** Where the proof stage keeps its inputs, in the image build. */
+export const PROOF_DIRECTORY = 'proof';
+/** The proof's verdict (a copy of the manifest it accepted), which the final image carries. */
+export const VERIFIED_IMAGE_FILE = 'xema-composed-verified.json';
+/** The stage manifest's file name and schema version. */
+export const COMPOSED_MANIFEST_FILE = 'xema-composed-image.json';
+export const COMPOSED_MANIFEST_SCHEMA = 1;

package/src/composed-image-pnpm-context.mjs

@@ -1,38 +1,23 @@
-// `xema-composed-image pnpm-context <dir> (--subject <svc>... | --image-dir <composed>)`:
-// builds, on the CI runner and AFTER its `pnpm install --frozen-lockfile`, the pnpm context an
-// offline prebuilt image build consumes as the named BuildKit context `xema-pnpm`. The runner's
-// own pnpm store is the second context (`xema-pnpm-store`); it is never copied.
+// `xema-composed-image pnpm-context <dir> --subject <svc>...`: builds, on the CI runner and AFTER its
+// `pnpm install --frozen-lockfile`, the pnpm context an offline per-service prebuilt image build consumes as the
+// named BuildKit context `xema-pnpm`. The runner's own pnpm store is the second context (`xema-pnpm-store`);
+// it is never copied. (The composed image no longer uses it: it is staged whole by `stage-tree`.)
 //
-//   <dir>/staged.json         { tool, pnpm, storeDir, subjects[], cache, imageDir? } — the sentinel the image checks
+//   <dir>/staged.json         { tool, pnpm, storeDir, subjects[] } — the sentinel the image checks
 //   <dir>/corepack/pnpm.tgz   `corepack pack pnpm@<root packageManager>`
-//   <dir>/cache/              --image-dir only: pnpm `cache-dir` (registry metadata), seeded from the runner's and warmed
-//                             (--subject writes no cache/: the member deploy is lockfile-driven and offline)
 //
 // stdout is exactly two lines for `$GITHUB_ENV`: `XEMA_PNPM_CONTEXT=<dir>` and
-// `XEMA_PNPM_STORE=<store root>`. Everything else goes to stderr. pnpm's own request-level
-// fetch retries apply; nothing here retries a command.
+// `XEMA_PNPM_STORE=<store root>`. Everything else goes to stderr.
 import { execFileSync } from 'node:child_process';
-import { cpSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
-import { homedir, tmpdir } from 'node:os';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 
-import { memberClosure, memberFilters } from './composed-image-members.mjs';
-import { depsCopyDirs, lockfileOnlyCommand } from './composed-image-prebuilt-dockerfile.mjs';
 import { toolVersion } from './composed-image-stage.mjs';
 
 /** Runs a command, returns stdout; stderr is the caller's. Injectable for tests. */
 const defaultExec = (file, args, { cwd } = {}) =>
   execFileSync(file, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'inherit'], maxBuffer: 64 * 1024 * 1024 });
 
-/** `pnpm config get cache-dir` prints `undefined` when unset; then pnpm's own default applies. */
-export function resolveCacheDir(printed, { platform = process.platform, env = process.env, home = homedir() } = {}) {
-  const value = printed.trim();
-  if (value !== '' && value !== 'undefined') return value;
-  if (platform === 'darwin') return join(home, 'Library', 'Caches', 'pnpm');
-  if (platform === 'win32') return join(env.LOCALAPPDATA ?? join(home, 'AppData', 'Local'), 'pnpm-cache');
-  return join(env.XDG_CACHE_HOME ?? join(home, '.cache'), 'pnpm');
-}
-
 /** `pnpm@10.33.0+sha512.…` → `10.33.0`. */
 function pnpmVersion(root) {
   const manager = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).packageManager;
@@ -41,52 +26,9 @@ function pnpmVersion(root) {
   return found[1];
 }
 
-function seedCache(exec, source, target, log) {
-  mkdirSync(dirname(target), { recursive: true });
-  if (!existsSync(source)) {
-    mkdirSync(target);
-    return 'empty';
-  }
-  try {
-    exec('cp', ['-al', source, target], {});
-    return 'hardlinked';
-  } catch (error) {
-    log(`pnpm-context: cp -al failed (${String(error?.message ?? error).split('\n')[0]}); copying the cache instead`);
-    rmSync(target, { recursive: true, force: true });
-    cpSync(source, target, { recursive: true });
-    return 'copied';
-  }
-}
-
-/** A scratch tree holding exactly the deps stage's inputs, so `--lockfile-only` never touches the repository. */
-function scratchLockfileInputs({ root, imageDir, exec }) {
-  // The directories the deps stage COPYs are read back from the committed Dockerfile (`depsCopyDirs`), so there is one definition.
-  const dockerfile = join(root, imageDir, 'Dockerfile');
-  if (!existsSync(dockerfile)) throw new Error(`${imageDir}/Dockerfile is absent — render it first: xema-composed-image dockerfile --prebuilt --write`);
-  const copy = depsCopyDirs(readFileSync(dockerfile, 'utf8'));
-  const scratch = mkdtempSync(join(tmpdir(), 'xema-pnpm-lock-'));
-  const put = (rel) => {
-    if (!existsSync(join(root, rel))) return;
-    mkdirSync(dirname(join(scratch, rel)), { recursive: true });
-    copyFileSync(join(root, rel), join(scratch, rel));
-  };
-  for (const rel of ['package.json', 'pnpm-lock.yaml', 'pnpm-workspace.yaml', '.npmrc']) put(rel);
-  for (const directory of memberClosure({ root, imageDir, exec })) put(`${directory}/package.json`);
-  for (const directory of copy) cpSync(join(root, directory), join(scratch, directory), { recursive: true });
-  return scratch;
-}
-
-export function buildPnpmContext({
-  root = process.cwd(),
-  dir,
-  subjects = [],
-  imageDir,
-  exec = defaultExec,
-  log = () => {},
-}) {
+export function buildPnpmContext({ root = process.cwd(), dir, subjects = [], exec = defaultExec }) {
   if (typeof dir !== 'string' || dir.length === 0) throw new Error('pnpm-context needs the output directory: pnpm-context <dir>');
-  if (subjects.length === 0 && imageDir === undefined) throw new Error('pnpm-context needs --subject <svc>… or --image-dir <composed>');
-  if (subjects.length > 0 && imageDir !== undefined) throw new Error('pnpm-context takes --subject or --image-dir, not both');
+  if (subjects.length === 0) throw new Error('pnpm-context needs --subject <svc>…');
   const target = resolve(dir);
   if (existsSync(target) && readdirSync(target).length > 0) throw new Error(`${dir} already exists and is not empty`);
 
@@ -98,25 +40,7 @@ export function buildPnpmContext({
   }
   mkdirSync(join(target, 'corepack'), { recursive: true });
   exec('corepack', ['pack', `pnpm@${pnpm}`, '-o', join(target, 'corepack', 'pnpm.tgz')], { cwd: root });
-
-  // --subject: the member image runs the lockfile-driven `pnpm deploy --offline` from the store alone, so no
-  // metadata cache is seeded or warmed. --image-dir: its `--lockfile-only` resolve needs registry metadata, warmed here.
-  const withCache = subjects.length === 0;
-  if (withCache) {
-    const cacheSource = resolveCacheDir(exec('pnpm', ['config', 'get', 'cache-dir'], { cwd: root }));
-    const cache = join(target, 'cache');
-    log(`pnpm-context: cache ${seedCache(exec, cacheSource, cache, log)} from ${cacheSource}`);
-    const scratch = scratchLockfileInputs({ root, imageDir, exec });
-    try {
-      const [file, ...args] = lockfileOnlyCommand(memberFilters({ root, imageDir }).flatMap((f) => f.split(' ')), { offline: false });
-      exec(file, [...args, `--config.cache-dir=${cache}`], { cwd: scratch });
-      log(`pnpm-context: warmed the ${imageDir} lockfile-only resolve`);
-    } finally {
-      rmSync(scratch, { recursive: true, force: true });
-    }
-  }
-
-  const sentinel = { tool: toolVersion(), pnpm, storeDir: storeRoot, subjects: [...subjects], cache: withCache, ...(imageDir === undefined ? {} : { imageDir }) };
+  const sentinel = { tool: toolVersion(), pnpm, storeDir: storeRoot, subjects: [...subjects] };
   writeFileSync(join(target, 'staged.json'), `${JSON.stringify(sentinel, null, 2)}\n`);
   return { context: target, store: storeRoot };
 }

package/src/composed-image-pnpm-context.test.mjs

@@ -4,59 +4,40 @@ import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
 
-import { buildPnpmContext, resolveCacheDir } from './composed-image-pnpm-context.mjs';
-import { lockfileOnlyCommand, renderPrebuiltDockerfile } from './composed-image-prebuilt-dockerfile.mjs';
-import { BASE, CLOSURE, fakePnpm, workspace, write } from './composed-image-fixture.test.mjs';
+import { buildPnpmContext } from './composed-image-pnpm-context.mjs';
+import { workspace, write } from './composed-image-fixture.test.mjs';
 
-function setup({ store = true, cache = true } = {}) {
+function setup({ store = true } = {}) {
   const root = workspace();
   write(root, 'package.json', { name: 'r', packageManager: 'pnpm@10.33.0+sha512.abc' });
-  write(root, 'pnpm-lock.yaml', 'lockfileVersion: 9\n');
-  write(root, 'tooling/dev/x.txt', 'x');
-  write(root, 'infra/composed-process/Dockerfile', renderPrebuiltDockerfile({ root, copy: ['tooling/dev'], cacheId: 'x', buildSource: 'repo', base: BASE, usesToken: false, exec: fakePnpm(root) }).dockerfile);
   const home = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-pnpm-home-'));
   const storePath = path.join(home, '.pnpm-store', 'v10');
-  const cacheDir = path.join(home, 'cache');
   if (store) fs.mkdirSync(storePath, { recursive: true });
-  if (cache) write(home, 'cache/metadata-v1.3/registry.npmjs.org/x.json', '{}');
   const out = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'xema-pnpm-out-')), 'ctx');
-  const pnpmLs = fakePnpm(root, CLOSURE);
   const calls = [];
-  const exec = (file, args, options = {}) => {
-    calls.push({ file, args, cwd: options.cwd, scratch: options.cwd !== root && options.cwd !== undefined ? fs.readdirSync(options.cwd) : undefined });
-    if (file === 'pnpm' && args[0] === 'ls') return pnpmLs(file, args, options);
+  const exec = (file, args) => {
+    calls.push({ file, args });
     if (file === 'pnpm' && args[0] === 'store') return `${storePath}\n`;
-    if (file === 'pnpm' && args[0] === 'config') return `${cacheDir}\n`;
-    if (file === 'corepack') {
-      fs.writeFileSync(args[args.indexOf('-o') + 1], 'tgz');
-      return '';
-    }
-    if (file === 'cp') {
-      fs.cpSync(args[1], args[2], { recursive: true });
-      return '';
-    }
+    if (file === 'corepack') fs.writeFileSync(args[args.indexOf('-o') + 1], 'tgz');
     return '';
   };
-  return { root, out, exec, calls, storePath, home };
+  return { root, out, exec, calls, home };
 }
 
-test('--subject: writes the corepack tgz and the sentinel, no cache dir and no deploy warm-up; returns the two env values', () => {
+test('writes the corepack tgz and the sentinel; returns the two env values', () => {
   const { root, out, exec, calls, home } = setup();
   const result = buildPnpmContext({ root, dir: out, subjects: ['svc-a', 'svc-b'], exec });
   assert.deepEqual(result, { context: out, store: path.join(home, '.pnpm-store') });
   assert.equal(fs.readFileSync(path.join(out, 'corepack/pnpm.tgz'), 'utf8'), 'tgz');
   assert.equal(fs.existsSync(path.join(out, 'cache')), false);
   const staged = JSON.parse(fs.readFileSync(path.join(out, 'staged.json'), 'utf8'));
-  assert.deepEqual(Object.keys(staged), ['tool', 'pnpm', 'storeDir', 'subjects', 'cache']);
+  assert.deepEqual(Object.keys(staged), ['tool', 'pnpm', 'storeDir', 'subjects']);
   assert.equal(staged.pnpm, '10.33.0');
-  assert.equal(staged.cache, false);
   assert.deepEqual(staged.subjects, ['svc-a', 'svc-b']);
   assert.deepEqual(calls.find((c) => c.file === 'corepack').args.slice(0, 2), ['pack', 'pnpm@10.33.0']);
-  assert.equal(calls.filter((c) => c.args[0] === 'deploy' || c.args.includes('--lockfile-only')).length, 0, 'no warm-up');
-  assert.ok(!calls.some((c) => c.args[0] === 'config'));
 });
 
-test('refuses a non-empty directory, a missing store, and a bad invocation, writing nothing', () => {
+test('refuses a non-empty directory, a missing store, and a missing subject, writing nothing', () => {
   const full = setup();
   write(full.out, 'old', 'x');
   assert.throws(() => buildPnpmContext({ root: full.root, dir: full.out, subjects: ['s'], exec: full.exec }), /not empty/);
@@ -64,52 +45,4 @@ test('refuses a non-empty directory, a missing store, and a bad invocation, writ
   assert.throws(() => buildPnpmContext({ root: none.root, dir: none.out, subjects: ['s'], exec: none.exec }), /pnpm store .* does not exist/);
   assert.equal(fs.existsSync(none.out), false);
   assert.throws(() => buildPnpmContext({ root: none.root, dir: none.out, exec: none.exec }), /--subject/);
-  assert.throws(() => buildPnpmContext({ root: none.root, dir: none.out, subjects: ['s'], imageDir: 'x', exec: none.exec }), /not both/);
-});
-
-test('--image-dir: runs the generator\'s lockfile-only command on a scratch copy and leaves the repository lockfile alone', () => {
-  const { root, out, exec, calls } = setup({ cache: false });
-  buildPnpmContext({ root, dir: out, imageDir: 'infra/composed-process', exec });
-  const resolve = calls.find((c) => c.args.includes('--lockfile-only'));
-  assert.notEqual(resolve.cwd, root);
-  assert.ok(resolve.scratch.includes('pnpm-lock.yaml') && resolve.scratch.includes('package.json'));
-  assert.ok(resolve.scratch.includes('tooling'), 'the deps stage COPY directories come from the committed Dockerfile');
-  assert.ok(resolve.args.includes('--prefer-offline') && !resolve.args.includes('--offline'), 'the warm-up fetches; the image resolves --offline');
-  assert.ok(resolve.args.includes(`--config.cache-dir=${path.join(out, 'cache')}`));
-  assert.equal(fs.existsSync(resolve.cwd), false, 'the scratch tree is deleted');
-  assert.equal(fs.readFileSync(path.join(root, 'pnpm-lock.yaml'), 'utf8'), 'lockfileVersion: 9\n');
-  const staged = JSON.parse(fs.readFileSync(path.join(out, 'staged.json'), 'utf8'));
-  assert.equal(staged.imageDir, 'infra/composed-process');
-  assert.equal(staged.cache, true);
-});
-
-test('the lockfile-only command is the one the generated Dockerfile runs (no drift)', () => {
-  const root = workspace();
-  const words = lockfileOnlyCommand(['--filter', '@t/alpha-api...']);
-  assert.deepEqual(words.slice(0, 4), ['pnpm', 'install', '--lockfile-only', '--offline']);
-  assert.equal(lockfileOnlyCommand(['--filter', 'x'], { offline: false })[3], '--prefer-offline');
-  assert.ok(words.includes('--config.inject-workspace-packages=true') && words.includes('--config.dedupe-injected-deps=false'));
-  const { dockerfile: text } = renderPrebuiltDockerfile({ root, cacheId: 'x', buildSource: 'repo', base: BASE, usesToken: false, exec: fakePnpm(root) });
-  assert.ok(text.includes('pnpm install --lockfile-only --offline ${INJECT} --filter @t/alpha-api... --filter @t/alpha-db-api... &&'));
-  assert.ok(text.includes('INJECT="--config.inject-workspace-packages=true --config.dedupe-injected-deps=false"'));
-});
-
-test('a failed cp -al falls back to a copy and logs why', () => {
-  const { root, out, exec, home } = setup();
-  const logs = [];
-  const failing = (file, args, options) => {
-    if (file === 'cp') throw new Error('cross-device link');
-    return exec(file, args, options);
-  };
-  buildPnpmContext({ root, dir: out, imageDir: 'infra/composed-process', exec: failing, log: (m) => logs.push(m) });
-  assert.ok(logs.some((m) => /cp -al failed \(cross-device link\)/.test(m)));
-  assert.ok(fs.existsSync(path.join(out, 'cache/metadata-v1.3/registry.npmjs.org/x.json')));
-  assert.ok(home);
-});
-
-test('an unset cache-dir ("undefined") resolves to the pnpm default per platform', () => {
-  assert.equal(resolveCacheDir('/x/c\n'), '/x/c');
-  assert.equal(resolveCacheDir('undefined\n', { platform: 'darwin', home: '/h' }), '/h/Library/Caches/pnpm');
-  assert.equal(resolveCacheDir('undefined', { platform: 'linux', env: {}, home: '/h' }), '/h/.cache/pnpm');
-  assert.equal(resolveCacheDir('', { platform: 'linux', env: { XDG_CACHE_HOME: '/xdg' }, home: '/h' }), '/xdg/pnpm');
 });