@xemahq/repo-build-tooling 0.29.0 → 0.31.0

package/README.md

@@ -40,7 +40,9 @@ pnpm exec xema-scrub-swagger-paths dist
 
 `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 the inputs 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 (checked against a sha256 COMMITTED in this tool per engines commit and binaryTarget, never against the checksum Prisma publishes beside it; an engines commit or target not in the table is refused; 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` binds the stage to the build: it refuses unless the manifest names `BUILD_SHA`, the context's root build inputs and `--copy` directories, this tool version, the platform the build runs on and the Dockerfile's filters, and every addon loads and the engine runs there. It does not detect a stage altered on the runner after `stage-tree` wrote it (manifest and layers come from the same job); the image digest and provenance cover what ships. The lockfile re-resolve runs `--prefer-offline` (its pins are checked unchanged; the production install is `--offline`). `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.
+**Image classes.** One build produces one image per class: `common | privileged | web-access` (the closed enum `ComposedImageClass`). A component's class is `imageClass` in its biome manifest (absent means common, the contracts default; the grammar is the contracts component schema, which the packager parses every manifest component through and never restates); `members --write|--check` derives the member set of every class and writes `<image-dir>/<class>/image-build-inputs.json` for each class that has members, so there is no separate list. A declared class (privileged, web-access) is authoritative: a worker or a runtime-scheduled service is a member, no derived exclusion applies, and `load --each` is the gate that refuses a member whose entry the host cannot load. Every other image command takes `--class <class>` and works in `<image-dir>/<class>/` (`dockerfile --prebuilt`, `stage`, `stage-tree`, `index`, `load`, `coordinate`, …). The class decides the recipe, not the members: web-access is built on the Chromium base (`--chromium-base <ref@sha256:…>`, refused for any other class); privileged carries the cosign and oras toolsets (`--toolset cosign=<ref@sha256:…> --toolset oras=<ref@sha256:…>`, pinned by digest into the Dockerfile so the content tag covers them; the set must match the recipe exactly). A class's image is `FROM base@digest`, its toolsets, the store layer, the workspace layer, then ONE tail layer (the dist layer and the proof verdict). Every member of a class runs in ONE node process behind the `xema-composed-process` host; the deployment selects the member set with `XEMA_PROCESS_DEFINITION`, and no class spawns a child process per member.
+
+`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 (checked against a sha256 COMMITTED in this tool per engines commit and binaryTarget, never against the checksum Prisma publishes beside it; an engines commit or target not in the table is refused; 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, three layers from least to most often changed: `<dir>/layers/store` (the registry packages, stable until the lockfile changes), `<dir>/layers/workspace` (the injected workspace packages, Prisma clients and engine, package files: changes with a library or the lockfile), `<dir>/layers/dist` (the members' `--output` directories, the member index and its host link: the only layer a commit that changes no dependency changes), files keep their real mtimes (an epoch mtime would let BuildKit's context transfer skip a same-size edit and ship stale bytes); the build must run with `SOURCE_DATE_EPOCH=0` and `--output type=image,rewrite-timestamp=true` so an unchanged layer keeps its digest build after build; `<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` binds the stage to the build: it refuses unless the manifest names `BUILD_SHA`, the context's root build inputs and `--copy` directories, this tool version, the platform the build runs on and the Dockerfile's filters, and every addon loads and the engine runs there. It does not detect a stage altered on the runner after `stage-tree` wrote it (manifest and layers come from the same job); the image digest and provenance cover what ships. The lockfile re-resolve runs `--prefer-offline` (its pins are checked unchanged; the production install is `--offline`). `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.29.0",
+  "version": "0.31.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)",
@@ -46,12 +46,13 @@
     "./service-image": "./src/service-image.mjs"
   },
   "dependencies": {
+    "@xemahq/contracts": "^0.118.1",
     "@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-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/service-image.test.mjs && node --test src/image-cpu-arch.test.mjs && node --test src/staged-image-proof.test.mjs && node --test src/effective-input.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-class.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/service-image.test.mjs && node --test src/image-cpu-arch.test.mjs && node --test src/staged-image-proof.test.mjs && node --test src/effective-input.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:a5327bf366fb31aeef8adb584888e52a5ae4da7aa5602eb672eb2876ed912a8b"
+    "sourceDigest": "sha256:724bdf902b48fed78564a3b6d52abb15d5ed2a6962da85e7a88f17eab1b085c2"
   }
 }

package/src/composed-image-class.mjs

@@ -0,0 +1,60 @@
+// What an image CLASS is to the packager: which directory holds its declaration and Dockerfile, which base it is
+// built on and which toolsets its image carries. A class is DECLARED by a component's `imageClass` in its biome manifest
+// (absent means the contracts default, common); the recipe below only says what each class needs, never which services are in it.
+//
+// Build-time only: nothing the image runs (`composed-image-in-image.mjs`'s closure) may import this file.
+import { posix } from 'node:path';
+
+import { ComposedImageClass, ComposedImageClassSchema, DEFAULT_COMPOSED_IMAGE_CLASS } from '@xemahq/contracts/distribution';
+
+export { ComposedImageClass, DEFAULT_COMPOSED_IMAGE_CLASS };
+export const IMAGE_CLASSES = Object.freeze(Object.values(ComposedImageClass));
+
+/** Which pinned base a class is built `FROM`. */
+export const BaseKind = Object.freeze({ NodeRuntime: 'node-runtime', Chromium: 'chromium' });
+
+/** A toolset is a binary copied from a pinned upstream image into the class's image. */
+export const Toolset = Object.freeze({ Cosign: 'cosign', Oras: 'oras' });
+export const TOOLSET_FILES = Object.freeze({
+  [Toolset.Cosign]: Object.freeze({ from: '/ko-app/cosign', to: '/usr/local/bin/cosign' }),
+  [Toolset.Oras]: Object.freeze({ from: '/bin/oras', to: '/usr/local/bin/oras' }),
+});
+
+/** The recipe: what a class's image is made of. Membership is never here. */
+export const CLASS_RECIPE = Object.freeze({
+  [ComposedImageClass.Common]: Object.freeze({ base: BaseKind.NodeRuntime, toolsets: Object.freeze([]) }),
+  [ComposedImageClass.Privileged]: Object.freeze({ base: BaseKind.NodeRuntime, toolsets: Object.freeze([Toolset.Cosign, Toolset.Oras]) }),
+  [ComposedImageClass.WebAccess]: Object.freeze({ base: BaseKind.Chromium, toolsets: Object.freeze([]) }),
+});
+
+export function assertImageClass(imageClass) {
+  if (!ComposedImageClassSchema.safeParse(imageClass).success) throw new Error(`image class must be one of ${IMAGE_CLASSES.join(', ')}, got "${imageClass}"`);
+  return imageClass;
+}
+
+/** Where a class keeps its `image-build-inputs.json`, Dockerfile and Dockerfile.dockerignore: `<image-dir>/<class>`. */
+export function classImageDir(imageDir, imageClass) {
+  return posix.join(imageDir, assertImageClass(imageClass));
+}
+
+/** A composed image's members do not agree on one class: they declare several, or the image has no member to declare one. */
+export class ComposedImageClassError extends Error {
+  constructor({ image, members, reason }) {
+    super(`composed image ${image}: ${reason} (members: ${members.length === 0 ? 'none' : members.map(({ key, imageClass }) => `${key}=${imageClass}`).join(', ')})`);
+    this.name = 'ComposedImageClassError';
+    this.image = image;
+    this.members = members;
+  }
+}
+
+/**
+ * The class of a composed image, derived from its members' biome-manifest `imageClass`, as the contracts component schema parsed it (absent means the contracts default). Never
+ * hand-written: `members` is `[{ key, imageClass }]` read from the manifests. Refuses an image with no member, and one
+ * whose members declare different classes.
+ */
+export function deriveImageClass({ image, members }) {
+  const classes = [...new Set(members.map(({ imageClass }) => imageClass))];
+  if (classes.length === 0) throw new ComposedImageClassError({ image, members, reason: 'has no member, so no class can be derived' });
+  if (classes.length > 1) throw new ComposedImageClassError({ image, members, reason: `members declare different classes (${classes.sort().join(', ')})` });
+  return assertImageClass(classes[0]);
+}

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

@@ -0,0 +1,218 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { CLASS_RECIPE, ComposedImageClass, DEFAULT_COMPOSED_IMAGE_CLASS, ComposedImageClassError, IMAGE_CLASSES, TOOLSET_FILES, assertImageClass, classImageDir, deriveImageClass } from './composed-image-class.mjs';
+import { deriveComposedMembers, main, parseToolsets, syncImageBuildInputs } from './composed-image.mjs';
+import { readImageClass } from './composed-image-committed-class.mjs';
+import { renderPrebuiltDockerfile } from './composed-image-prebuilt-dockerfile.mjs';
+import { BASE, CONTENT_COMPONENT, workspace, write } from './composed-image-fixture.test.mjs';
+
+const COMPOSABLE = 'void bootstrapXemaService({ appModule: AppModule });\n';
+const WORKER = 'void bootstrapXemaWorker({ appModule: AppModule });\n';
+const digest = (name) => `ghcr.io/example/${name}@sha256:${name.length.toString(16).padStart(64, 'd')}`;
+const CHROMIUM = digest('chromium');
+const TOOLSETS = { cosign: digest('cosign'), oras: digest('oras') };
+
+const component = (key, extra = {}) => ({ key, kind: 'service', scheduler: 'platform', artifact: { kind: 'oci-image', path: `api/${key}` }, ...extra });
+
+function repository(components) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-classes-'));
+  write(root, 'biomes/alpha/xema-biome.json', { xema: { id: 'alpha', components } });
+  for (const { key, kind } of components) write(root, `biomes/alpha/api/${key}/src/main.ts`, kind === 'worker' ? WORKER : COMPOSABLE);
+  execFileSync('git', ['init', '-q'], { cwd: root });
+  execFileSync('git', ['add', '-A'], { cwd: root });
+  return root;
+}
+
+const classed = () =>
+  repository([
+    component('plain-api'),
+    component('fetch-api', { imageClass: ComposedImageClass.Privileged }),
+    component('platform-worker', { kind: 'worker', imageClass: ComposedImageClass.Privileged }),
+    component('runtime-server', { scheduler: 'runtime', imageClass: ComposedImageClass.Privileged }),
+    component('browser-api', { imageClass: ComposedImageClass.WebAccess }),
+    component('explicit-api', { imageClass: ComposedImageClass.Common }),
+    component('runtime-api', { scheduler: 'runtime' }),
+  ]);
+
+test('the class set is the closed enum and the recipe covers exactly it', () => {
+  assert.deepEqual(IMAGE_CLASSES, ['common', 'privileged', 'web-access']);
+  assert.deepEqual(Object.keys(CLASS_RECIPE).sort(), [...IMAGE_CLASSES].sort());
+  assert.deepEqual([...CLASS_RECIPE[ComposedImageClass.Privileged].toolsets].sort(), Object.keys(TOOLSET_FILES).sort());
+  assert.throws(() => assertImageClass('root'), /image class must be one of common, privileged, web-access/);
+  assert.equal(classImageDir('infra/composed-process', 'web-access'), 'infra/composed-process/web-access');
+});
+
+test('members come from each component\'s imageClass: absent is common, and a declared class takes workers and runtime-scheduled services whole', () => {
+  const derived = deriveComposedMembers({ root: classed() });
+  assert.deepEqual(derived.members, {
+    common: { 'alpha/explicit-api': 'biomes/alpha/api/explicit-api', 'alpha/plain-api': 'biomes/alpha/api/plain-api' },
+    privileged: {
+      'alpha/fetch-api': 'biomes/alpha/api/fetch-api',
+      'alpha/runtime-server': 'biomes/alpha/api/runtime-server',
+      'alpha/platform-worker': 'biomes/alpha/api/platform-worker',
+    },
+    'web-access': { 'alpha/browser-api': 'biomes/alpha/api/browser-api' },
+  });
+  assert.deepEqual(derived.excluded, {});
+});
+
+test('a class with no member is absent; an unknown class or a class on a non-service is refused', () => {
+  assert.deepEqual(Object.keys(deriveComposedMembers({ root: repository([component('plain-api')]) }).members), ['common']);
+  assert.throws(() => deriveComposedMembers({ root: repository([component('x-api', { imageClass: 'root' })]) }), /component "x-api" is not a valid biome component: imageClass: Invalid option/);
+  // The refusal is the contracts schema's, not the packager's: the same content component is accepted without a class.
+  assert.doesNotThrow(() => deriveComposedMembers({ root: repository([component('plain-api'), CONTENT_COMPONENT]) }));
+  const content = repository([component('plain-api'), { ...CONTENT_COMPONENT, imageClass: ComposedImageClass.Privileged }]);
+  assert.throws(() => deriveComposedMembers({ root: content }), /component "alpha-content" is not a valid biome component: imageClass: imageClass is only valid on a service or worker component, not content/);
+});
+
+test('members --write declares one image per class that has members; --check refuses a missing, stale or unclassed declaration', () => {
+  const root = classed();
+  syncImageBuildInputs({ mode: 'write', root });
+  for (const imageClass of IMAGE_CLASSES) {
+    assert.ok(fs.existsSync(path.join(root, 'infra/composed-process', imageClass, 'image-build-inputs.json')), imageClass);
+  }
+  assert.deepEqual(JSON.parse(fs.readFileSync(path.join(root, 'infra/composed-process/web-access/image-build-inputs.json'), 'utf8')), { imageClass: ComposedImageClass.WebAccess, workspacePackages: ['biomes/alpha/api/browser-api'] });
+  syncImageBuildInputs({ mode: 'check', root });
+  write(root, 'infra/composed-process/image-build-inputs.json', { workspacePackages: [] });
+  assert.throws(() => syncImageBuildInputs({ mode: 'check', root }), /infra\/composed-process\/image-build-inputs\.json is stale/);
+  syncImageBuildInputs({ mode: 'write', root });
+  assert.equal(fs.existsSync(path.join(root, 'infra/composed-process/image-build-inputs.json')), false);
+
+  // The web-access service leaves the class: its declaration must go, and --check says so before --write does.
+  const manifest = path.join(root, 'biomes/alpha/xema-biome.json');
+  const edited = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+  delete edited.xema.components.find((c) => c.key === 'browser-api').imageClass;
+  fs.writeFileSync(manifest, JSON.stringify(edited));
+  assert.throws(() => syncImageBuildInputs({ mode: 'check', root }), /web-access\/image-build-inputs\.json.* stale/);
+  syncImageBuildInputs({ mode: 'write', root });
+  assert.equal(fs.existsSync(path.join(root, 'infra/composed-process/web-access/image-build-inputs.json')), false);
+});
+
+test('an image command needs --class; members refuses one', () => {
+  assert.throws(() => main(['dirs'], { log() {} }), /dirs works on one image class: pass --class <common\|privileged\|web-access>/);
+  assert.throws(() => main(['dirs', '--class', 'root'], { log() {} }), /image class must be one of/);
+  assert.throws(() => main(['members', '--check', '--class', 'common'], { log() {} }), /--class does not apply to members/);
+});
+
+test('--toolset parses name=digest reference pairs and refuses a malformed or repeated one', () => {
+  assert.deepEqual(parseToolsets(['cosign=a@sha256:x', 'oras=b']), { cosign: 'a@sha256:x', oras: 'b' });
+  assert.throws(() => parseToolsets(['cosign']), /--toolset must be <name>=/);
+  assert.throws(() => parseToolsets(['cosign=a', 'cosign=b']), /given twice/);
+});
+
+function render(imageClass, extra = {}) {
+  const root = workspace();
+  write(root, 'pnpm-lock.yaml', "lockfileVersion: '9.0'\n");
+  write(root, 'package.json', { name: 'r' });
+  return renderPrebuiltDockerfile({ root, imageClass, copy: [], buildSource: 'alpha', base: BASE, nodeMajor: '22', ...extra }).dockerfile;
+}
+
+test('common is built on the node-runtime base with no toolset; it carries its class label', () => {
+  const dockerfile = render(ComposedImageClass.Common);
+  assert.match(dockerfile, /^FROM ghcr\.io\/example\/base\/node-runtime@sha256:a{64} AS base$/m);
+  assert.doesNotMatch(dockerfile, /AS cosign|AS oras|chromium/);
+  assert.match(dockerfile, /^LABEL dev\.xema\.composed-image\.class="common"$/m);
+  assert.throws(() => render(ComposedImageClass.Common, { chromiumBase: CHROMIUM }), /--chromium-base belongs to the web-access class/);
+  assert.throws(() => render(ComposedImageClass.Common, { toolsets: TOOLSETS }), /carries the toolset\(s\) none; --toolset gave cosign, oras/);
+});
+
+test('web-access is its own third class, built FROM the Chromium base and not the node-runtime base', () => {
+  const dockerfile = render(ComposedImageClass.WebAccess, { chromiumBase: CHROMIUM });
+  assert.match(dockerfile, new RegExp(`^FROM ${CHROMIUM.replaceAll('.', '\\.')} AS base$`, 'm'));
+  assert.doesNotMatch(dockerfile, /node-runtime/);
+  assert.match(dockerfile, /^LABEL dev\.xema\.composed-image\.class="web-access"$/m);
+  assert.throws(() => render(ComposedImageClass.WebAccess), /--chromium-base must be pinned by digest/);
+  assert.throws(() => render(ComposedImageClass.WebAccess, { chromiumBase: 'chromium:latest' }), /pinned by digest/);
+});
+
+test('privileged carries its toolsets, pinned by digest, in the layers right after the base and before the store layer', () => {
+  const dockerfile = render(ComposedImageClass.Privileged, { toolsets: TOOLSETS });
+  assert.match(dockerfile, new RegExp(`^FROM ${TOOLSETS.cosign.replaceAll('.', '\\.')} AS cosign$`, 'm'));
+  assert.match(dockerfile, new RegExp(`^FROM ${TOOLSETS.oras.replaceAll('.', '\\.')} AS oras$`, 'm'));
+  const final = dockerfile.split('\nFROM base\n')[1];
+  const copies = final.split('\n').filter((line) => line.startsWith('COPY '));
+  assert.deepEqual(copies, [
+    'COPY --from=cosign /ko-app/cosign /usr/local/bin/cosign',
+    'COPY --from=oras /bin/oras /usr/local/bin/oras',
+    'COPY .xema-stage/layers/store/ /',
+    'COPY .xema-stage/layers/workspace/ /',
+    'COPY --from=tail / /',
+  ]);
+  assert.throws(() => render(ComposedImageClass.Privileged), /carries the toolset\(s\) cosign, oras; --toolset gave none/);
+  assert.throws(() => render(ComposedImageClass.Privileged, { toolsets: { cosign: TOOLSETS.cosign, oras: 'oras:latest' } }), /--toolset oras must be an image reference pinned by digest/);
+});
+
+test('every class: the image layers are base, [toolsets], store, workspace, ONE tail (dist + verdict); a single process hosts the members', () => {
+  for (const [imageClass, extra] of [[ComposedImageClass.Common, {}], [ComposedImageClass.Privileged, { toolsets: TOOLSETS }], [ComposedImageClass.WebAccess, { chromiumBase: CHROMIUM }]]) {
+    const dockerfile = render(imageClass, extra);
+    const final = dockerfile.split('\nFROM base\n')[1];
+    const layerSteps = final.split('\n').filter((line) => /^(COPY|RUN|ADD) /.test(line));
+    assert.ok(layerSteps.every((line) => line.startsWith('COPY ')), `${imageClass}: the final stage adds layers only by COPY`);
+    assert.equal(layerSteps.at(-1), 'COPY --from=tail / /', `${imageClass}: dist is the last layer`);
+    assert.equal(layerSteps.filter((line) => line.includes('layers/dist')).length, 0, `${imageClass}: dist reaches the image only through the tail`);
+    assert.ok(final.indexOf('COPY .xema-stage/layers/store/ /') < final.indexOf('\nWORKDIR /monorepo\n'), 'WORKDIR follows the store layer, which creates /monorepo');
+    assert.match(final, /CMD \["node", "\/monorepo\/xema-composed-process"\]\n$/);
+    assert.doesNotMatch(dockerfile, /child_process|fork\(|spawn/);
+  }
+});
+
+test('an image class is derived from its members\' manifests: one agreed class passes, mixed and none are refused with the image and members named', () => {
+  const root = repository([
+    component('a-api', { imageClass: ComposedImageClass.Privileged }),
+    component('b-api', { imageClass: ComposedImageClass.Privileged }),
+    component('c-api'),
+  ]);
+  const declare = (...keys) => write(root, 'infra/composed-process/privileged/image-build-inputs.json', { workspacePackages: keys.map((key) => `biomes/alpha/api/${key}`) });
+  const imageDir = 'infra/composed-process/privileged';
+
+  declare('a-api', 'b-api');
+  assert.equal(readImageClass({ root, imageDir }), ComposedImageClass.Privileged);
+  assert.equal(deriveImageClass({ image: 'x', members: [{ key: 'alpha/a-api', imageClass: ComposedImageClass.WebAccess }] }), ComposedImageClass.WebAccess);
+
+  declare('a-api', 'c-api');
+  assert.throws(() => readImageClass({ root, imageDir }), (error) => error.image === imageDir && /alpha\/a-api=privileged, alpha\/c-api=common/.test(error.message) && /different classes/.test(error.message));
+
+  declare('c-api');
+  assert.equal(readImageClass({ root, imageDir }), ComposedImageClass.Common, 'a member that declares no class is common');
+
+  declare();
+  assert.throws(() => readImageClass({ root, imageDir }), (error) => error instanceof ComposedImageClassError && error.image === imageDir && /has no member/.test(error.message));
+});
+
+test('a worker member carries its imageClass through the contracts schema; absent resolves to the contracts default; a mixed set is refused', () => {
+  const worker = (key, extra = {}) => component(key, { kind: 'worker', ...extra });
+  const root = repository([
+    worker('priv-worker', { imageClass: ComposedImageClass.Privileged }),
+    worker('web-worker', { imageClass: ComposedImageClass.WebAccess }),
+    worker('plain-worker'),
+    component('priv-api', { imageClass: ComposedImageClass.Privileged }),
+  ]);
+  const imageDir = 'infra/composed-process/privileged';
+  const declare = (...keys) => write(root, `${imageDir}/image-build-inputs.json`, { workspacePackages: keys.map((key) => `biomes/alpha/api/${key}`) });
+
+  declare('priv-worker');
+  assert.equal(readImageClass({ root, imageDir }), ComposedImageClass.Privileged, 'a worker alone declares its class');
+  declare('priv-worker', 'priv-api');
+  assert.equal(readImageClass({ root, imageDir }), ComposedImageClass.Privileged, 'a worker and a service agree');
+  declare('web-worker');
+  assert.equal(readImageClass({ root, imageDir }), ComposedImageClass.WebAccess);
+
+  assert.equal(DEFAULT_COMPOSED_IMAGE_CLASS, 'common');
+  declare('plain-worker');
+  assert.equal(readImageClass({ root, imageDir }), DEFAULT_COMPOSED_IMAGE_CLASS, 'a worker that declares no class is the contracts default');
+
+  declare('priv-worker', 'plain-worker');
+  assert.throws(() => readImageClass({ root, imageDir }), (error) => error instanceof ComposedImageClassError && /alpha\/priv-worker=privileged, alpha\/plain-worker=common/.test(error.message));
+  declare('priv-worker', 'web-worker');
+  assert.throws(() => readImageClass({ root, imageDir }), ComposedImageClassError);
+
+  const derived = deriveComposedMembers({ root });
+  assert.deepEqual(Object.keys(derived.members.privileged).sort(), ['alpha/priv-api', 'alpha/priv-worker']);
+  assert.deepEqual(Object.keys(derived.members['web-access']), ['alpha/web-worker']);
+  assert.equal(derived.memberClasses['alpha/plain-worker'], undefined, 'an undeclared worker is no member');
+});

package/src/composed-image-committed-class.mjs

@@ -0,0 +1,19 @@
+// The class of a COMMITTED composed image, read back from its members' biome manifests. Build-time only: it imports the
+// class module, so nothing the image runs (`composed-image-in-image.mjs`'s closure) may import this file.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { deriveImageClass } from './composed-image-class.mjs';
+import { parseManifestComponent, componentImageClass } from './composed-image-manifest-components.mjs';
+import { IMAGE_BUILD_INPUTS_FILE, memberComponent } from './composed-image-members.mjs';
+import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
+
+/** The class of the image declared at `imageDir`, derived from its members' manifests (absent means the contracts default); refuses members that disagree. */
+export function readImageClass({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR } = {}) {
+  const directories = JSON.parse(readFileSync(join(root, imageDir, IMAGE_BUILD_INPUTS_FILE), 'utf8')).workspacePackages ?? [];
+  const members = directories.map((directory) => {
+    const { key, component } = memberComponent(root, directory);
+    return { key, imageClass: componentImageClass(parseManifestComponent(component, key)) };
+  });
+  return deriveImageClass({ image: imageDir, members });
+}

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

@@ -29,7 +29,7 @@ test('the CLI prints content_tag and cross_repo_pins under an environment with n
   try {
     const tagArgs = path.join(root, 'tag-args.txt');
     fs.writeFileSync(tagArgs, `--vendored\nd=r@${'b'.repeat(40)}:s\n`);
-    const result = spawnSync(process.execPath, [BIN, 'coordinate', '--image-name', 'img'], {
+    const result = spawnSync(process.execPath, [BIN, 'coordinate', '--class', 'common', '--image-name', 'img'], {
       cwd: root,
       encoding: 'utf8',
       env: { PATH: process.env.PATH, SHA: 'b'.repeat(40), REGISTRY: 'ghcr.io', REGISTRY_ORG: 'org', TAG_ARGS_FILE: tagArgs },
@@ -47,7 +47,7 @@ test('the CLI fails with the real message when the hash package is not installed
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'coordinate-cli-'));
   try {
     fs.writeFileSync(path.join(root, 'package.json'), '{}');
-    const result = spawnSync(process.execPath, [BIN, 'coordinate', '--image-name', 'img'], {
+    const result = spawnSync(process.execPath, [BIN, 'coordinate', '--class', 'common', '--image-name', 'img'], {
       cwd: root,
       encoding: 'utf8',
       env: { PATH: process.env.PATH, SHA: 'b'.repeat(40), REGISTRY: 'ghcr.io', REGISTRY_ORG: 'org' },

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

@@ -4,9 +4,81 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
+const REQUIREMENTS = Object.freeze({
+  tenancy: { allowed: ['org', 'project'], tenantContext: 'verified' },
+  isolation: { minimum: 'none' },
+  trust: { minimum: 'verified' },
+  locality: { allowed: ['cloud', 'customer-private'] },
+  state: { kind: 'stateless' },
+  resources: { minimum: { cpu: '100m', memory: '128Mi', ephemeralStorage: '64Mi' }, preferred: { cpu: '250m', memory: '256Mi', ephemeralStorage: '128Mi' } },
+  runtime: { kind: 'node', versionRange: '>=24', architectures: ['amd64', 'arm64'] },
+  io: { ingress: 'http', egress: 'platform', rawBody: false, devices: [] },
+  scaling: {
+    mode: 'horizontal',
+    concurrency: { handling: 'parallel', maximumPerInstance: 100 },
+    readiness: { kind: 'protocol', initialDelaySeconds: 2 },
+    drain: { kind: 'graceful', maximumSeconds: 30 },
+    hints: { cpu: 'latency', memory: 'steady', startup: 'fast' },
+  },
+});
+
+const protocolOf = (kind, key) =>
+  kind === 'service' ? { kind: 'http', revision: 'v1', serviceName: key, authScopes: ['org'] } : PROTOCOLS[kind] ?? { kind: 'none' };
+
+const PROTOCOLS = Object.freeze({
+  worker: { kind: 'worker', revision: 'v2', taskQueues: [{ name: 'default', serves: ['workflows', 'activities'], fairness: 'org' }] },
+});
+
+/**
+ * A component the contracts component schema accepts: the fields a test names win, every other required field is
+ * filled. The packager parses each manifest component through that schema (the one grammar), so a fixture that names only
+ * `key`, `kind`, `scheduler` and `artifact` must still be a whole component.
+ */
+export function validComponent(partial) {
+  const artifact = partial.artifact?.kind === undefined && partial.artifact?.path !== undefined ? { kind: 'oci-image', ...partial.artifact } : partial.artifact;
+  return {
+    entrypoint: artifact?.kind === 'shared-oci-image' ? { kind: 'node-module', module: './dist/main.js' } : { kind: 'oci-default' },
+    protocol: protocolOf(partial.kind, partial.key),
+    executionModes: ['isolated'],
+    requirements: REQUIREMENTS,
+    ...partial,
+    artifact,
+  };
+}
+
+/** A whole `content` component: a kind that is neither service nor worker, so it cannot declare an `imageClass`. */
+export const CONTENT_COMPONENT = Object.freeze({
+  key: 'alpha-content',
+  kind: 'content',
+  artifact: { kind: 'package-content', path: '.' },
+  entrypoint: { kind: 'materialize' },
+  protocol: { kind: 'none' },
+  executionModes: ['materialized'],
+  requirements: {
+    tenancy: { allowed: ['org'], tenantContext: 'verified' },
+    isolation: { minimum: 'none' },
+    trust: { minimum: 'untrusted' },
+    locality: { allowed: ['cloud', 'customer-private'] },
+    state: { kind: 'stateless' },
+    resources: { minimum: { cpu: '1m', memory: '1Mi', ephemeralStorage: '1Mi' } },
+    runtime: { kind: 'none' },
+    io: { ingress: 'none', egress: 'none', rawBody: false, devices: [] },
+    scaling: {
+      mode: 'singleton',
+      concurrency: { handling: 'serial', maximumPerInstance: 1 },
+      readiness: { kind: 'none' },
+      drain: { kind: 'none' },
+      hints: { cpu: 'batch', memory: 'steady', startup: 'fast' },
+    },
+  },
+});
+
+/** Write a fixture file. A biome manifest's components are completed with `validComponent`, so a test names only what it varies. */
 export function write(root, rel, content) {
+  const manifest = typeof content !== 'string' && path.basename(rel) === 'xema-biome.json' && Array.isArray(content.xema?.components);
+  const body = manifest ? { ...content, xema: { ...content.xema, components: content.xema.components.map(validComponent) } } : content;
   fs.mkdirSync(path.join(root, path.dirname(rel)), { recursive: true });
-  fs.writeFileSync(path.join(root, rel), typeof content === 'string' ? content : JSON.stringify(content, null, 2));
+  fs.writeFileSync(path.join(root, rel), typeof body === 'string' ? body : JSON.stringify(body, null, 2));
 }
 
 export const BASE = 'ghcr.io/example/base/node-runtime@sha256:' + 'a'.repeat(64);

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

@@ -7,6 +7,7 @@ import os from 'node:os';
 import path from 'node:path';
 import test, { after } from 'node:test';
 
+import { ComposedImageClass } from './composed-image-class.mjs';
 import { renderPrebuiltDockerfile } from './composed-image-prebuilt-dockerfile.mjs';
 import { copyTool } from './composed-image-stage.mjs';
 import { BASE, workspace } from './composed-image-fixture.test.mjs';
@@ -26,6 +27,7 @@ function renderedEntries() {
   const root = workspace();
   const { dockerfile } = renderPrebuiltDockerfile({
     root,
+    imageClass: ComposedImageClass.Common,
     copy: ['tooling/dev'],
     buildSource: 'alpha', base: BASE, nodeMajor: '22',
   });

package/src/composed-image-manifest-components.mjs

@@ -0,0 +1,28 @@
+// The ONE grammar for a biome manifest component is the contracts component schema, `imageClass` included: which kinds
+// may declare a class, which values it may take. The packager parses through it and keeps no copy of any of it.
+//
+// Build-time only: it imports `@xemahq/contracts`, so nothing the image runs (`composed-image-in-image.mjs`'s closure)
+// may import this file.
+import { BiomeComponentSchema } from '@xemahq/contracts/biome';
+
+import { DEFAULT_COMPOSED_IMAGE_CLASS } from './composed-image-class.mjs';
+
+/** One manifest component parsed by the contracts schema; a component it refuses names the manifest and the component. */
+export function parseManifestComponent(component, manifestPath) {
+  const parsed = BiomeComponentSchema.safeParse(component);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((issue) => `${issue.path.join('.') || '(component)'}: ${issue.message}`).join('; ');
+    throw new Error(`${manifestPath}: component "${component?.key}" is not a valid biome component: ${issues}`);
+  }
+  return parsed.data;
+}
+
+/** The components of a biome manifest, each parsed by the contracts schema. */
+export function parseManifestComponents(manifest, manifestPath) {
+  return (manifest.xema?.components ?? []).map((component) => parseManifestComponent(component, manifestPath));
+}
+
+/** The class a parsed component runs in: its `imageClass`, or the contracts default when it declares none. */
+export function componentImageClass(component) {
+  return component.imageClass ?? DEFAULT_COMPOSED_IMAGE_CLASS;
+}

package/src/composed-image-members.mjs

@@ -9,22 +9,22 @@ import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
 
 export const IMAGE_BUILD_INPUTS_FILE = 'image-build-inputs.json';
 
-/** The `<biomeId>/<componentKey>` of the one service whose artifact is `directory`. */
-function memberKey(root, directory) {
+/** The `<biomeId>/<componentKey>` and the manifest component (raw: this module runs in the image, so it parses nothing) of the one service or worker whose artifact is `directory`. */
+export function memberComponent(root, directory) {
   for (let dir = dirname(directory); dir !== '.' && dir !== dirname(dir); dir = dirname(dir)) {
     const manifestPath = join(root, dir, 'xema-biome.json');
     if (!existsSync(manifestPath)) continue;
     const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
     const matches = (manifest.xema?.components ?? []).filter(
       (component) =>
-        component.kind === 'service' &&
+        (component.kind === 'service' || component.kind === 'worker') &&
         typeof component.artifact?.path === 'string' &&
         posix.normalize(posix.join(dir, component.artifact.path)) === directory,
     );
     if (matches.length !== 1) {
-      throw new Error(`${dir}/xema-biome.json declares ${matches.length} service(s) at ${directory}, not exactly one`);
+      throw new Error(`${dir}/xema-biome.json declares ${matches.length} service or worker component(s) at ${directory}, not exactly one`);
     }
-    return `${manifest.xema.id}/${matches[0].key}`;
+    return { key: `${manifest.xema.id}/${matches[0].key}`, component: matches[0] };
   }
   throw new Error(`no biome manifest above ${directory}`);
 }
@@ -34,7 +34,7 @@ export function readMembers({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DI
   const inputs = join(root, imageDir, IMAGE_BUILD_INPUTS_FILE);
   const directories = JSON.parse(readFileSync(inputs, 'utf8')).workspacePackages ?? [];
   if (directories.length === 0) throw new Error(`${inputs} declares no workspacePackages`);
-  return directories.map((directory) => [memberKey(root, directory), directory]);
+  return directories.map((directory) => [memberComponent(root, directory).key, directory]);
 }
 
 function packageName(root, directory) {

package/src/composed-image-paths.mjs

@@ -10,8 +10,10 @@ 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 injected workspace packages, the Prisma clients, the closure's package files and root manifests: everything of `/monorepo` that is neither a registry package nor a member's own output. Copied to `/`. */
+export const STAGE_WORKSPACE_LAYER = 'layers/workspace';
+/** The members' build outputs (default `dist`) and the member index with its host link: what changes on every commit. Copied to `/` LAST, so a commit that changes no dependency rebuilds only this layer. */
+export const STAGE_DIST_LAYER = 'layers/dist';
 /** The stage manifest the proof reads. */
 export const STAGE_PROOF_DIRECTORY = 'proof';
 /** The image's root directory, under each layer. */