@xemahq/repo-build-tooling 0.31.1 → 0.33.0

package/README.md

@@ -27,7 +27,7 @@ pnpm exec xema-scrub-swagger-paths dist
 | Bin | What it does |
 | --- | --- |
 | `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-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. Also derives each component's boot-required environment and edition delivery from its entry source (`oci-default` gives `src/main.ts`, `node-module` `dist/<x>` gives `src/<x>.ts`) with `@xemahq/peer-analysis`, writes `src/generated/<component>.component-facts.generated.json`, and inlines the same `bootEnv` (and `editionDelivery`, when reached) in the descriptor |
 | `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`, `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 stage reaches the build as the named context `xema-service` (`--build-context xema-service=.xema-stage`); the authoritative name is `STAGED_SERVICE_CONTEXT` in `@xemahq/distribution-source-hash`, whose image hash frames such a service from its tracked tree, closure, turbo globalDependencies and tsconfig chain, so the stage must be built from no other repository input. The final stage only COPYs |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.31.1",
+  "version": "0.33.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,13 +46,14 @@
     "./service-image": "./src/service-image.mjs"
   },
   "dependencies": {
-    "@xemahq/contracts": "^0.118.1",
-    "@xemahq/release-policy": "^16.0.0"
+    "@xemahq/contracts": "^0.119.0",
+    "@xemahq/release-policy": "^16.0.0",
+    "@xemahq/peer-analysis": "^0.3.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-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"
+    "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-component-facts.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/canonical-hidden-hoist.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/turbo-config-projection.test.mjs && node --test src/effective-input.test.mjs && node --test src/effective-input-deployed-files.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:a1e1068eca88fad502417b887f16c732ecf0c9ed0ca339849880ea780aa894d4"
+    "sourceDigest": "sha256:561f8561b0ff23023de261c59ca6f4067fc05f585edda41117a75f6d3d3f60e1"
   }
 }

package/src/canonical-hidden-hoist.mjs

@@ -0,0 +1,138 @@
+// pnpm's hidden hoist (`node_modules/.pnpm/node_modules/<alias>`) is where a package in the virtual store resolves a
+// dependency it does not declare. When several versions of one alias are installed, the version pnpm 10.33 links there
+// is not a function of the lockfile: its hoister gives each package the depth at which a depth-first walk FIRST reaches
+// it, and the walk starts from the importers in their selection order (the `--filter` order among them), so the same
+// lockfile hoists `signal-exit@4.1.0` in one install and `signal-exit@3.0.7` in another. It also records an alias twice
+// when its first candidate is skipped for the platform, and links both concurrently: the later write wins.
+//
+// The hoist stays on. Every development install has it, so a registry package that requires an undeclared dependency
+// works there; an image without it would fail only in production, at the first such require. Instead, after the
+// install, each hidden-hoist link into the virtual store is re-pointed at ONE candidate chosen from the installed tree
+// alone: of the packages that depend on the alias, the nearest to the importers (an importer is depth -1, a store
+// package its SHORTEST distance from the importers' direct dependencies), ties broken by the dependent's path. That is
+// pnpm's rule without the walk-order dependence. A link outside the virtual store (a workspace project) is pnpm's
+// hoisting of a unique name and is left alone.
+//
+// `.pnpm/node_modules/.bin` is removed: its shims embed the version pnpm picked, and nothing in an image runs them (the
+// staged install runs no scripts, the image starts `node` directly, and Prisma runs from its dependent's own `.bin`).
+import { existsSync, lstatSync, readdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, unlinkSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+import { lockSections } from './effective-input.mjs';
+
+const isDirectory = (path) => lstatSync(path, { throwIfNoEntry: false })?.isDirectory() === true;
+
+/** `[alias, linkPath]` of every symlink directly in a modules directory, scoped ones included, sorted by alias. */
+function modulesLinks(modulesDir) {
+  const found = [];
+  if (!isDirectory(modulesDir)) return found;
+  for (const entry of readdirSync(modulesDir, { withFileTypes: true })) {
+    if (entry.isSymbolicLink()) found.push([entry.name, join(modulesDir, entry.name)]);
+    else if (entry.isDirectory() && entry.name.startsWith('@')) {
+      for (const scoped of readdirSync(join(modulesDir, entry.name), { withFileTypes: true })) {
+        if (scoped.isSymbolicLink()) found.push([`${entry.name}/${scoped.name}`, join(modulesDir, entry.name, scoped.name)]);
+      }
+    }
+  }
+  return found.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+const linkTarget = (linkPath) => resolve(dirname(linkPath), readlinkSync(linkPath));
+
+/** The virtual-store entry (`<name>@<version>…` directory) a path lies in, or undefined outside the store. */
+function storeEntryOf(store, path) {
+  const rel = relative(store, path);
+  if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) return undefined;
+  const entry = rel.split(sep)[0];
+  return entry === 'node_modules' ? undefined : entry;
+}
+
+const compare = (a, b) => a.depth - b.depth || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0) || (a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : 0);
+
+/**
+ * The hidden-hoist links of the install at `treeRoot` (which holds its `pnpm-lock.yaml`) that do not point at their
+ * canonical candidate: `[{ alias, linkPath, current, canonical }]` (absolute directories). Reads only.
+ */
+export function hiddenHoistPlan(treeRoot) {
+  const store = join(treeRoot, 'node_modules', '.pnpm');
+  const hoistDir = join(store, 'node_modules');
+  if (!isDirectory(hoistDir)) return [];
+
+  // dependents: alias -> [{ depth, key, dir }]; edges: store entry -> store entries it links.
+  const dependents = new Map();
+  const depend = (alias, candidate) => {
+    if (!dependents.has(alias)) dependents.set(alias, []);
+    dependents.get(alias).push(candidate);
+  };
+  const edges = new Map();
+  const entries = readdirSync(store, { withFileTypes: true }).filter((e) => e.isDirectory() && e.name !== 'node_modules').map((e) => e.name).sort();
+  for (const entry of entries) {
+    const children = [];
+    for (const [alias, linkPath] of modulesLinks(join(store, entry, 'node_modules'))) {
+      const dir = linkTarget(linkPath);
+      const child = storeEntryOf(store, dir);
+      if (child === undefined) continue;
+      children.push({ alias, dir, child });
+    }
+    edges.set(entry, children);
+  }
+
+  const importers = Object.keys(lockSections(readFileSync(join(treeRoot, 'pnpm-lock.yaml'), 'utf8')).importers ?? {})
+    .filter((id) => isDirectory(join(treeRoot, id, 'node_modules')))
+    .sort();
+  const depth = new Map();
+  let frontier = [];
+  for (const id of importers) {
+    for (const [alias, linkPath] of modulesLinks(join(treeRoot, id, 'node_modules'))) {
+      const dir = linkTarget(linkPath);
+      const child = storeEntryOf(store, dir);
+      if (child === undefined) continue;
+      depend(alias, { depth: -1, key: id, dir });
+      if (!depth.has(child)) {
+        depth.set(child, 0);
+        frontier.push(child);
+      }
+    }
+  }
+  for (let level = 1; frontier.length > 0; level += 1) {
+    const next = [];
+    for (const entry of frontier) {
+      for (const { child } of edges.get(entry) ?? []) {
+        if (!depth.has(child)) {
+          depth.set(child, level);
+          next.push(child);
+        }
+      }
+    }
+    frontier = next;
+  }
+  for (const [entry, children] of edges) {
+    for (const { alias, dir } of children) depend(alias, { depth: depth.get(entry) ?? Number.POSITIVE_INFINITY, key: entry, dir });
+  }
+
+  const plan = [];
+  for (const [alias, linkPath] of modulesLinks(hoistDir)) {
+    const current = linkTarget(linkPath);
+    if (storeEntryOf(store, current) === undefined) continue;
+    const candidates = dependents.get(alias);
+    if (candidates === undefined) continue;
+    const { dir } = [...candidates].sort(compare)[0];
+    if (dir !== current) plan.push({ alias, linkPath, current, canonical: dir });
+  }
+  return plan;
+}
+
+/**
+ * Re-point every hidden-hoist link of the install at `treeRoot` at its canonical candidate (`hiddenHoistPlan`) and
+ * remove the hidden `.bin`. Returns the number of links re-pointed. A tree without a virtual store is left as it is.
+ */
+export function canonicalizeHiddenHoist(treeRoot) {
+  const plan = hiddenHoistPlan(treeRoot);
+  for (const { linkPath, canonical } of plan) {
+    unlinkSync(linkPath);
+    symlinkSync(relative(dirname(linkPath), canonical), linkPath);
+  }
+  const bin = join(treeRoot, 'node_modules', '.pnpm', 'node_modules', '.bin');
+  if (existsSync(bin)) rmSync(bin, { recursive: true, force: true });
+  return plan.length;
+}

package/src/canonical-hidden-hoist.test.mjs

@@ -0,0 +1,133 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { canonicalizeHiddenHoist } from './canonical-hidden-hoist.mjs';
+import { installClosure, injectFlags } from './composed-image-install.mjs';
+
+// Real pnpm, no registry: `file:` packages only. `sig` is installed at 1.0.0 (under zzz-r) and 2.0.0 (under aaa-s).
+//   @t/a -> pa -> a1 -> a2 -> { zzz-r, aaa-s }        @t/b -> pb -> b1 -> zzz-r
+// zzz-r is two hops from @t/b's direct dependency and three from @t/a's, so the canonical choice is sig@1. Which one
+// pnpm 10.33 itself hoists is not a function of the lockfile: on macOS it usually follows the --filter order (sig@2
+// with @t/a first, sig@1 with @t/b first) but not always, and on Linux it picks sig@2 in either order. The test does
+// not depend on that: it links each tree's hidden hoist at a different candidate itself, right after pnpm's install.
+function fixture() {
+  const treeRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-hidden-hoist-'));
+  const write = (file, content) => {
+    fs.mkdirSync(path.dirname(path.join(treeRoot, file)), { recursive: true });
+    fs.writeFileSync(path.join(treeRoot, file), typeof content === 'string' ? content : JSON.stringify(content));
+  };
+  const vendor = (dir, name, version, deps = {}) => {
+    const dependencies = Object.fromEntries(Object.entries(deps).map(([dep, target]) => [dep, `file:../${target}`]));
+    write(`vendor/${dir}/package.json`, { name, version, main: 'index.js', dependencies });
+    write(`vendor/${dir}/index.js`, `module.exports = ${JSON.stringify(`${name}@${version}`)};\n`);
+  };
+  write('package.json', { name: 'root', private: true });
+  write('pnpm-workspace.yaml', "packages:\n  - 'apps/*'\n");
+  vendor('sig-v1', 'sig', '1.0.0');
+  vendor('sig-v2', 'sig', '2.0.0');
+  vendor('zzz-r', 'zzz-r', '1.0.0', { sig: 'sig-v1' });
+  vendor('aaa-s', 'aaa-s', '1.0.0', { sig: 'sig-v2' });
+  vendor('a2', 'a2', '1.0.0', { 'zzz-r': 'zzz-r', 'aaa-s': 'aaa-s' });
+  vendor('a1', 'a1', '1.0.0', { a2: 'a2' });
+  vendor('pa', 'pa', '1.0.0', { a1: 'a1' });
+  vendor('b1', 'b1', '1.0.0', { 'zzz-r': 'zzz-r' });
+  vendor('pb', 'pb', '1.0.0', { b1: 'b1' });
+  write('apps/a/package.json', { name: '@t/a', version: '1.0.0', dependencies: { pa: 'file:../../vendor/pa' } });
+  write('apps/b/package.json', { name: '@t/b', version: '1.0.0', dependencies: { pb: 'file:../../vendor/pb' } });
+  execFileSync('pnpm', ['install', '--lockfile-only', '--offline', ...injectFlags()], { cwd: treeRoot, stdio: 'ignore' });
+  return treeRoot;
+}
+
+// CI=true as on the runner, where pnpm keeps a modules directory it would otherwise refuse to reuse without a TTY.
+const exec = (file, args, { cwd }) => execFileSync(file, args, { cwd, stdio: 'pipe', env: { ...process.env, CI: 'true' } });
+
+/** Every path under `root` (pnpm's per-run state files aside, as the stage removes them): link target, file hash or dir. */
+function snapshot(root) {
+  const entries = {};
+  const walk = (rel) => {
+    for (const name of fs.readdirSync(path.join(root, rel)).sort()) {
+      const child = path.join(rel, name);
+      if (['.modules.yaml', '.pnpm-workspace-state-v1.json'].includes(name)) continue;
+      const stat = fs.lstatSync(path.join(root, child));
+      if (stat.isSymbolicLink()) entries[child] = `link ${fs.readlinkSync(path.join(root, child))}`;
+      else if (stat.isDirectory()) {
+        entries[child] = 'dir';
+        walk(child);
+      } else entries[child] = `file ${createHash('sha256').update(fs.readFileSync(path.join(root, child))).digest('hex')}`;
+    }
+  };
+  walk('');
+  return entries;
+}
+
+const storePackage = (treeRoot, name) => {
+  const store = path.join(treeRoot, 'node_modules', '.pnpm');
+  const entry = fs.readdirSync(store).find((e) => e.startsWith(`${name}@`));
+  return path.join(store, entry, 'node_modules', name);
+};
+const resolvedFrom = (dir, specifier) => createRequire(path.join(dir, 'package.json'))(specifier);
+
+test('two installs of the same lockfile with the importers in either order stage byte-identical trees, and every require still resolves', () => {
+  const orders = [['--filter', '@t/a...', '--filter', '@t/b...'], ['--filter', '@t/b...', '--filter', '@t/a...']];
+  const trees = orders.map(() => fixture());
+  try {
+    // Each tree's hidden hoist is linked at a different installed sig after pnpm's install and before the canonical step,
+    // as two walk orders leave it: sig@2 in the first tree, sig@1 in the second.
+    const divergent = ['sig@file+vendor+sig-v2', 'sig@file+vendor+sig-v1'];
+    const raw = trees.map((treeRoot, i) => {
+      let hoisted;
+      const diverging = (file, args, options) => {
+        exec(file, args, options);
+        if (!args.includes('--frozen-lockfile')) return;
+        const link = path.join(treeRoot, 'node_modules', '.pnpm', 'node_modules', 'sig');
+        fs.unlinkSync(link);
+        fs.symlinkSync(path.join('..', divergent[i], 'node_modules', 'sig'), link);
+        hoisted = fs.readlinkSync(link);
+      };
+      installClosure({ treeRoot, filters: orders[i], arch: 'arm64', exec: diverging });
+      return hoisted;
+    });
+    assert.notEqual(raw[0], raw[1], 'the two trees enter the canonical step with different hidden hoists');
+    assert.deepEqual(snapshot(trees[0]), snapshot(trees[1]));
+    for (const treeRoot of trees) {
+      const hoisted = fs.readlinkSync(path.join(treeRoot, 'node_modules', '.pnpm', 'node_modules', 'sig'));
+      assert.match(hoisted, /sig@file\+vendor\+sig-v1/, 'the hoisted sig is the one nearest the importers');
+      assert.equal(resolvedFrom(storePackage(treeRoot, 'b1'), 'sig'), 'sig@1.0.0', 'an undeclared require resolves through the hidden hoist');
+      assert.equal(resolvedFrom(storePackage(treeRoot, 'zzz-r'), 'sig'), 'sig@1.0.0');
+      assert.equal(resolvedFrom(storePackage(treeRoot, 'aaa-s'), 'sig'), 'sig@2.0.0', 'a declared dependency still resolves to its own version');
+      assert.equal(resolvedFrom(path.join(treeRoot, 'apps', 'a'), 'pa'), 'pa@1.0.0');
+      assert.equal(resolvedFrom(path.join(treeRoot, 'apps', 'b'), 'pb'), 'pb@1.0.0');
+    }
+  } finally {
+    for (const treeRoot of trees) fs.rmSync(treeRoot, { recursive: true, force: true });
+  }
+});
+
+test('the canonical choice is a no-op on a tree already canonical, and the hidden .bin is removed', () => {
+  const treeRoot = fixture();
+  try {
+    installClosure({ treeRoot, filters: ['--filter', '@t/b...', '--filter', '@t/a...'], arch: 'arm64', exec });
+    const before = snapshot(treeRoot);
+    fs.mkdirSync(path.join(treeRoot, 'node_modules', '.pnpm', 'node_modules', '.bin'));
+    assert.equal(canonicalizeHiddenHoist(treeRoot), 0);
+    assert.deepEqual(snapshot(treeRoot), before);
+  } finally {
+    fs.rmSync(treeRoot, { recursive: true, force: true });
+  }
+});
+
+test('a tree without a virtual store is left as it is', () => {
+  const treeRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-hidden-hoist-empty-'));
+  try {
+    assert.equal(canonicalizeHiddenHoist(treeRoot), 0);
+    assert.deepEqual(fs.readdirSync(treeRoot), []);
+  } finally {
+    fs.rmSync(treeRoot, { recursive: true, force: true });
+  }
+});

package/src/canonical-json.mjs

@@ -0,0 +1,9 @@
+/** Canonical JSON: keys sorted recursively, no whitespace. */
+export function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+

package/src/component-facts.mjs

@@ -0,0 +1,131 @@
+/**
+ * Facts per generated component (its boot-required environment, and how it
+ * receives its resolved deployment): which source file is the component's entry,
+ * what `deriveComponentFacts` reads from it, and how the result is written (a
+ * per-component JSON fact, and `bootEnv` / `editionDelivery` properties inlined
+ * in the generated descriptor). Pure functions around one derivation call, so
+ * the generator's tests drive them without a checkout.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { BiomeComponentEntrypointKind } from '@xemahq/contracts/biome';
+import {
+  COMPONENT_FACTS_GENERATED_FILE_SUFFIX,
+  ComponentFactsFileSchema,
+} from '@xemahq/contracts/boot-env';
+import { deriveComponentFacts } from '@xemahq/peer-analysis';
+
+/**
+ * The fact file's retired spelling. No generator writes it any more, so any file
+ * with it is a leftover: the lock builder must never read it.
+ */
+const RETIRED_BOOT_ENV_SUFFIX = '.boot-env.generated.json';
+
+/** The source module a `oci-default` entrypoint runs: the shared Dockerfile's `node dist/main`. */
+const OCI_DEFAULT_ENTRY = 'src/main.ts';
+const NODE_MODULE_PATTERN = /^dist\/([^/].*?)(?:\.js)?$/u;
+
+const refuse = (manifestRel, component, why) =>
+  new Error(
+    `[xema-service-bootstrap] ${manifestRel} component "${component?.key}": cannot determine its source entry to derive its boot environment — ${why}`,
+  );
+
+/**
+ * The package-relative source file a component's runtime entry is compiled from.
+ *
+ * - `oci-default` runs the image's default `node dist/main` (the kernel schema
+ *   documents that default), so the entry is `src/main.ts`.
+ * - `node-module` names `dist/<x>` literally, so the entry is `src/<x>.ts`.
+ *
+ * Anything else is refused: the entry is never guessed.
+ */
+export function componentEntrySource(component, manifestRel) {
+  const entrypoint = component?.entrypoint;
+  if (entrypoint?.kind === BiomeComponentEntrypointKind.OciDefault) {
+    return OCI_DEFAULT_ENTRY;
+  }
+  if (entrypoint?.kind === BiomeComponentEntrypointKind.NodeModule) {
+    const match = typeof entrypoint.module === 'string' ? NODE_MODULE_PATTERN.exec(entrypoint.module) : null;
+    if (match === null) {
+      throw refuse(
+        manifestRel,
+        component,
+        `entrypoint.module ${JSON.stringify(entrypoint.module)} must be \`dist/<name>\`, which maps to \`src/<name>.ts\``,
+      );
+    }
+    return `src/${match[1]}.ts`;
+  }
+  throw refuse(
+    manifestRel,
+    component,
+    `entrypoint.kind ${JSON.stringify(entrypoint?.kind)} is neither \`${BiomeComponentEntrypointKind.OciDefault}\` nor \`${BiomeComponentEntrypointKind.NodeModule}\``,
+  );
+}
+
+/**
+ * Derive one component's facts from its entry source. Any finding fails, naming
+ * the component and every `path:line` with its reason.
+ *
+ * @returns {{ bootEnv: { required: string[], optional: string[] }, editionDelivery?: string }}
+ */
+export function deriveFacts({ component, packageDir, manifestRel }) {
+  const entryFile = componentEntrySource(component, manifestRel);
+  let result;
+  try {
+    result = deriveComponentFacts({ packageDir, entryFile });
+  } catch (error) {
+    throw new Error(
+      `[xema-service-bootstrap] ${manifestRel} component "${component.key}": cannot derive its facts from ${entryFile}: ${error.message}`,
+      { cause: error },
+    );
+  }
+  if (result.findings.length > 0) {
+    throw new Error(
+      `[xema-service-bootstrap] ${manifestRel} component "${component.key}": its facts cannot be derived from ${entryFile} (${result.findings.length} finding(s)):\n` +
+        result.findings.map((f) => `  ${f.path}:${f.line} [${f.seam}] ${f.reason}`).join('\n'),
+    );
+  }
+  return {
+    bootEnv: result.bootEnv,
+    ...(result.editionDelivery === undefined ? {} : { editionDelivery: result.editionDelivery }),
+  };
+}
+
+export const componentFactsFileName = (name) => `${name}${COMPONENT_FACTS_GENERATED_FILE_SUFFIX}`;
+
+/** The per-component fact file, validated against the contract before it is written. */
+export function renderComponentFactsFile(name, facts) {
+  const file = ComponentFactsFileSchema.parse({ factsVersion: 1, component: name, ...facts });
+  return `${JSON.stringify(file, null, 2)}\n`;
+}
+
+const names = (xs) => (xs.length === 0 ? '[]' : `[${xs.map((x) => `'${x}'`).join(', ')}]`);
+
+/** The `bootEnv` (and, when reached, `editionDelivery`) properties inlined in a generated descriptor. */
+export function renderFactsProperties({ bootEnv, editionDelivery }) {
+  const lines = [`  bootEnv: { required: ${names(bootEnv.required)}, optional: ${names(bootEnv.optional)} },`];
+  if (editionDelivery !== undefined) {
+    lines.push(`  editionDelivery: '${editionDelivery}',`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * The fact files in a generated directory that no emitted component owns, and
+ * every file in the retired boot-env spelling: a renamed or removed component
+ * leaves its file behind, and the lock builder reads every one it finds.
+ */
+export function extraFactsFiles(generatedDir, expectedFileNames) {
+  if (!existsSync(generatedDir)) {
+    return [];
+  }
+  return readdirSync(generatedDir)
+    .filter(
+      (file) =>
+        file.endsWith(RETIRED_BOOT_ENV_SUFFIX) ||
+        (file.endsWith(COMPONENT_FACTS_GENERATED_FILE_SUFFIX) && !expectedFileNames.has(file)),
+    )
+    .sort()
+    .map((file) => join(generatedDir, file));
+}

package/src/composed-image-dockerfile.mjs

@@ -16,7 +16,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, posix } from 'node:path';
 
-import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
+import { COMPOSED_DOCKERFILE_HEADER, COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
 import { toolVersion } from './composed-image-stage.mjs';
 
 const TOKEN_REFERENCE = /_authToken\b|\$\{(?:NPM_TOKEN|GH_PACKAGES_TOKEN)\}/;
@@ -59,7 +59,7 @@ export function renderComposedDockerfile({ copy, cacheId, buildSource, usesToken
     ? 'export NPM_TOKEN="$(cat /run/secrets/npm_token)" && export GH_PACKAGES_TOKEN="$NPM_TOKEN" && \\\n  '
     : '';
   const metadata = `--mount=type=cache,id=pnpm-metadata-${cacheId},target=/root/.cache/pnpm`;
-  return `# @generated by \`xema-composed-image dockerfile --write\` (@xemahq/repo-build-tooling@${toolingVersion}) — DO NOT EDIT.
+  return `${COMPOSED_DOCKERFILE_HEADER} --write\` (@xemahq/repo-build-tooling@${toolingVersion}) — DO NOT EDIT.
 # Re-render with the same options; \`--check\` refuses a stale file.
 #
 # The COMPOSED-PROCESS image of this repository: ONE image per build (repository at

package/src/composed-image-install.mjs

@@ -8,11 +8,15 @@
 // The re-resolve runs in a scratch copy of the tree's manifests, never in the tree: pnpm 10.33 `--lockfile-only`
 // with a filter that leaves workspace projects out still links a full `node_modules` (dev dependencies included),
 // and the `--prod` install after it does not prune it, so dev-only packages would ship and be scanned.
+//
+// pnpm's hidden-hoist choice depends on its walk order, not on the lockfile alone, so the install ends by making it
+// canonical (`canonical-hidden-hoist.mjs`): the same lockfile then stages byte-identical trees.
 import { execFileSync } from 'node:child_process';
 import { copyFileSync, mkdirSync, mkdtempSync, readdirSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
+import { canonicalizeHiddenHoist } from './canonical-hidden-hoist.mjs';
 import { assertPinsUnchanged } from './composed-image-in-image.mjs';
 import { pruneForeignLibcPackages } from './prune-foreign-libc.mjs';
 import { libcOf, nodeArch } from './service-image-platform.mjs';
@@ -74,6 +78,7 @@ export function installClosure({ treeRoot, filters, arch, exec = defaultExec })
     exec(installFile, installArgs, { cwd: treeRoot });
     // pnpm 10.33 frozen offline install does not filter by libc; cpu/os do.
     pruneForeignLibcPackages(treeRoot, libcOf(arch));
+    canonicalizeHiddenHoist(treeRoot);
   } finally {
     rmSync(scratch, { recursive: true, force: true });
   }

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

@@ -12,12 +12,12 @@ const GLOB = /[*?[\]{}!]/;
 const ignoredFile = (name) => name.endsWith('.tsbuildinfo') || name.endsWith('.log');
 
 /**
- * Repository-relative COPY sources for `directory`: `package.json` and each plain `files` entry. An entry the
- * `.dockerignore` excludes (e.g. `dist`) is built output, staged separately, and is not a source here.
- * A package with no `files` array, or a glob entry, is refused: `files` is what says what ships.
+ * The package-relative `files` entries of `manifest` (the package at `directory`), normalized: what `pnpm pack` ships
+ * beside `package.json`. A package with no `files` array, a glob or negated entry, or an entry outside the package is
+ * refused: `files` is what says what ships. The effective-input key reads the same entries (one definition).
  */
-export function packageSources({ root, directory }) {
-  const files = JSON.parse(readFileSync(join(root, directory, 'package.json'), 'utf8')).files;
+export function shippedFilesEntries({ manifest, directory }) {
+  const files = manifest.files;
   if (!Array.isArray(files)) throw new Error(`${directory}/package.json has no "files" field — nothing says which of its files ship in the image`);
   const globs = files.filter((entry) => typeof entry !== 'string' || GLOB.test(entry));
   if (globs.length > 0) throw new Error(`${directory}/package.json "files" has glob or non-string entries (${globs.join(', ')}); list plain paths`);
@@ -25,7 +25,16 @@ export function packageSources({ root, directory }) {
   for (const entry of entries) {
     if (entry === '.' || entry.startsWith('/') || entry.split('/').includes('..')) throw new Error(`${directory}/package.json "files" entry "${entry}" is not inside the package`);
   }
-  const shipped = entries.filter((entry) => {
+  return [...new Set(entries)];
+}
+
+/**
+ * Repository-relative COPY sources for `directory`: `package.json` and each plain `files` entry. An entry the
+ * `.dockerignore` excludes (e.g. `dist`) is built output, staged separately, and is not a source here.
+ */
+export function packageSources({ root, directory }) {
+  const manifest = JSON.parse(readFileSync(join(root, directory, 'package.json'), 'utf8'));
+  const shipped = shippedFilesEntries({ manifest, directory }).filter((entry) => {
     const parts = entry.split('/');
     return !parts.some((part) => IGNORED_DIRECTORIES.includes(part)) && !ignoredFile(parts.at(-1));
   });

package/src/composed-image-paths.mjs

@@ -1,5 +1,7 @@
 // Where a repository keeps its composed-process image: the one place this is spelled.
 export const COMPOSED_IMAGE_DIR = 'infra/composed-process';
+/** How every composed-image Dockerfile (in-Docker and prebuilt) begins: both COPY whole `--copy` directories. */
+export const COMPOSED_DOCKERFILE_HEADER = '# @generated by `xema-composed-image dockerfile';
 
 // 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';

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

@@ -6,7 +6,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, posix } from 'node:path';
 
-import { COMPOSED_IMAGE_DIR, COMPOSED_MANIFEST_FILE, IN_IMAGE_ENTRY, NODE_MAJOR_LABEL, PROOF_DIRECTORY, STAGE_DIST_LAYER, STAGE_PROOF_DIRECTORY, STAGE_STORE_LAYER, STAGE_WORKSPACE_LAYER, VERIFIED_IMAGE_FILE } from './composed-image-paths.mjs';
+import { COMPOSED_DOCKERFILE_HEADER, COMPOSED_IMAGE_DIR, COMPOSED_MANIFEST_FILE, IN_IMAGE_ENTRY, NODE_MAJOR_LABEL, PROOF_DIRECTORY, STAGE_DIST_LAYER, STAGE_PROOF_DIRECTORY, STAGE_STORE_LAYER, STAGE_WORKSPACE_LAYER, VERIFIED_IMAGE_FILE } from './composed-image-paths.mjs';
 import { toolVersion } from './composed-image-stage.mjs';
 import { IGNORED_DIRECTORIES, IGNORED_FILE_PATTERNS } from './composed-image-package-files.mjs';
 import { BaseKind, CLASS_RECIPE, TOOLSET_FILES, assertImageClass } from './composed-image-class.mjs';
@@ -96,10 +96,10 @@ export function renderPrebuiltDockerfile({ root = process.cwd(), imageDir = COMP
   const node = `${toolDir}/${IN_IMAGE_ENTRY}`;
   const copies = normalizedCopy(copy).map(copyLine).join('\n');
   const stageLayer = (layer) => `COPY ${stageDir}/${layer}/ /`;
-  const allLayers = [STAGE_STORE_LAYER, STAGE_WORKSPACE_LAYER, STAGE_DIST_LAYER].map(stageLayer).join('\n');
+  const stableLayers = [STAGE_STORE_LAYER, STAGE_WORKSPACE_LAYER].map(stageLayer).join('\n');
   const toolsetStages = recipe.toolsets.map((name) => `FROM ${toolsets[name]} AS ${name}\n`).join('');
   const toolsetCopies = recipe.toolsets.map((name) => `COPY --from=${name} ${TOOLSET_FILES[name].from} ${TOOLSET_FILES[name].to}\n`).join('');
-  const dockerfile = `# @generated by \`xema-composed-image dockerfile --prebuilt --write\` (@xemahq/repo-build-tooling@${toolingVersion}) — DO NOT EDIT.
+  const dockerfile = `${COMPOSED_DOCKERFILE_HEADER} --prebuilt --write\` (@xemahq/repo-build-tooling@${toolingVersion}) — DO NOT EDIT.
 # Re-render with the same options; \`--check\` refuses a stale file (and a stale Dockerfile.dockerignore).
 #
 # The ${imageClass.toUpperCase()} COMPOSED-PROCESS image of this repository, COPIED from a tree the CI runner staged: one
@@ -118,7 +118,8 @@ export function renderPrebuiltDockerfile({ root = process.cwd(), imageDir = COMP
 # \`${stageDir}/tool/\` is this tool, bind-mounted into the steps below and never copied into a layer.
 #
 # Stages:
-#   proof  The staged tree and the repository's inputs meet. The root build inputs that decide the
+#   proof  (COPYs run least to most often changed: store, workspace, root inputs, \`--copy\` directories, dist, manifest, so a source change keeps the store layer cached.)
+#          The staged tree and the repository's inputs meet. The root build inputs that decide the
 #          staged tree are COPIED into \`/${PROOF_DIRECTORY}/${CONTEXT_DIRECTORY}/\` and the \`--copy\` directories into
 #          \`/${COPIED_DIRECTORY}/\`, which puts them in the image's content tag. \`prove\` refuses the build unless the
 #          stage's manifest names BUILD_SHA and those bytes, this tool and this platform, and
@@ -134,9 +135,10 @@ ${toolsetStages}FROM ${from} AS base
 FROM base AS proof
 WORKDIR /${PROOF_DIRECTORY}
 ARG BUILD_SHA
-COPY ${stageDir}/${STAGE_PROOF_DIRECTORY}/${COMPOSED_MANIFEST_FILE} /${PROOF_DIRECTORY}/
+${stableLayers}
 COPY ${rootInputs.join(' ')} /${PROOF_DIRECTORY}/${CONTEXT_DIRECTORY}/
-${copies === '' ? '' : `${copies}\n`}${allLayers}
+${copies === '' ? '' : `${copies}\n`}${stageLayer(STAGE_DIST_LAYER)}
+COPY ${stageDir}/${STAGE_PROOF_DIRECTORY}/${COMPOSED_MANIFEST_FILE} /${PROOF_DIRECTORY}/
 RUN --network=none ${toolMount} \\
   : "\${BUILD_SHA:?BUILD_SHA build-arg is required}" && \\
   T="node ${node}" && \\

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

@@ -28,12 +28,24 @@ test('the proof stage COPYs the root build inputs flat, the --copy directories,
   assert.match(proof, /^COPY \.xema-stage\/proof\/xema-composed-image\.json \/proof\/$/m);
   assert.match(proof, /^COPY \.npmrc package\.json pnpm-lock\.yaml pnpm-workspace\.yaml \/proof\/context\/$/m);
   assert.match(proof, /^COPY tooling\/dev\/ \/proof\/copied\/tooling\/dev\/$/m);
-  assert.match(proof, /^COPY \.xema-stage\/layers\/store\/ \/\nCOPY \.xema-stage\/layers\/workspace\/ \/\nCOPY \.xema-stage\/layers\/dist\/ \/$/m);
+  assert.match(proof, /^COPY \.xema-stage\/layers\/store\/ \/\nCOPY \.xema-stage\/layers\/workspace\/ \/$/m);
+  assert.match(proof, /^COPY \.xema-stage\/layers\/dist\/ \/$/m);
   assert.match(proof, /prove \/proof --root \/monorepo --commit "\$\{BUILD_SHA\}" --filter @t\/alpha-api\.\.\. --filter @t\/alpha-db-api\.\.\./);
   assert.match(proof, /prisma-check --root \/monorepo/);
   assert.match(proof, /USER node\nRUN --network=none \S+ \\\n {2}NODE_ENV=production node \S+ load --each --root \/monorepo/);
 });
 
+test('the proof stage COPYs in stability order: store, workspace, root inputs, --copy trees, dist, manifest', () => {
+  const { dockerfile } = renderPrebuiltDockerfile(options(workspace()));
+  const proof = dockerfile.split('FROM base AS proof\n')[1].split('\nFROM base\n')[0];
+  const copies = proof.split('\n').filter((line) => line.startsWith('COPY '));
+  const at = (re) => copies.findIndex((line) => re.test(line));
+  const order = [/layers\/store\//, /layers\/workspace\//, /\/proof\/context\/$/, /\/proof\/copied\//, /layers\/dist\//, /xema-composed-image\.json/].map(at);
+  assert.ok(order.every((i) => i >= 0), `every COPY is present: ${order}`);
+  assert.deepEqual(order, [...order].sort((a, b) => a - b));
+  assert.equal(order[0], 0, 'the store COPY precedes every source-tree COPY');
+});
+
 test('the root inputs the Dockerfile COPYs are exactly the ROOT_BUILD_INPUT files present', () => {
   const root = workspace();
   const opts = options(root);