@xemahq/repo-build-tooling 0.8.2 → 0.9.0

package/src/composed-image.test.mjs

@@ -0,0 +1,249 @@
+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 { fileURLToPath } from 'node:url';
+
+import {
+  ExclusionReason,
+  assertPinsUnchanged,
+  codeWithoutComments,
+  deriveComposedMembers,
+  isComposableEntry,
+  loadMembers,
+  main,
+  memberFilters,
+  parseArguments,
+  readMembers,
+  registryPins,
+  syncImageBuildInputs,
+  writeMemberIndex,
+} from './composed-image.mjs';
+
+const BIN = path.join(path.dirname(fileURLToPath(import.meta.url)), 'composed-image.mjs');
+const COMMIT = 'a'.repeat(40);
+const COMPOSABLE = "import { bootstrapXemaService } from '@xemahq/xema-service-nest';\n\n// bootstrapXemaService(once more, in prose)\nvoid bootstrapXemaService({ appModule: AppModule });\n";
+
+function write(root, rel, 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));
+}
+
+function service(key, artifactPath, extra = {}) {
+  return { key, kind: 'service', scheduler: 'platform', artifact: { kind: 'oci-image', path: artifactPath }, ...extra };
+}
+
+/**
+ * Two repository layouts in one tree, so the same tool is exercised the way its two
+ * consumers are shaped: a `biomes/**` platform repository and a `products/**` product one.
+ */
+function fixture() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-composed-image-'));
+  write(root, 'biomes/alpha/xema-biome.json', {
+    xema: {
+      id: 'alpha',
+      components: [
+        service('alpha-api', 'api/alpha-api'),
+        service('alpha-own-api', 'api/alpha-own-api'),
+        service('alpha-tool-api', 'api/alpha-tool-api'),
+        service('alpha-vendor-api', 'api/alpha-vendor-api'),
+        service('alpha-shape-api', 'api/alpha-shape-api'),
+        service('alpha-runtime', 'api/alpha-runtime', { scheduler: 'runtime' }),
+        { key: 'alpha-worker', kind: 'worker', scheduler: 'platform', artifact: { kind: 'shared-oci-image', component: 'alpha-api' } },
+      ],
+    },
+  });
+  for (const name of ['alpha-api', 'alpha-own-api', 'alpha-tool-api', 'alpha-vendor-api']) {
+    write(root, `biomes/alpha/api/${name}/src/main.ts`, COMPOSABLE);
+    write(root, `biomes/alpha/api/${name}/package.json`, { name: `@t/${name}` });
+  }
+  write(root, 'biomes/alpha/api/alpha-own-api/Dockerfile', 'FROM scratch\n');
+  write(root, 'biomes/alpha/api/alpha-shape-api/src/main.ts', 'async function main() { await bootstrapXemaService({}); }\nvoid main();\n');
+  write(root, 'products/pai/core/pai-core/xema-biome.json', {
+    xema: { id: 'pai-core', components: [service('pai-core-api', 'api/pai-core-api'), { key: 'pai-core-worker', kind: 'worker', scheduler: 'platform', artifact: { kind: 'shared-oci-image', component: 'pai-core-api' } }] },
+  });
+  write(root, 'products/pai/core/pai-core/api/pai-core-api/src/main.ts', COMPOSABLE);
+  write(root, 'products/pai/core/pai-core/api/pai-core-api/package.json', { name: '@p/pai-core-api' });
+  write(root, 'infra/docker/nestjs-service.dockerfile', 'FROM scratch\nARG SUPPLY_CHAIN_SIGSTORE_SERVICES="alpha-tool-api"\n');
+  write(root, 'infra/docker/plain.dockerfile', 'FROM scratch\n');
+  write(root, 'tooling/release/cross-repo-build-inputs.json', { inputs: [{ consumerService: 'alpha-vendor-api' }] });
+  execFileSync('git', ['init', '-q'], { cwd: root });
+  execFileSync('git', ['add', '-A'], { cwd: root });
+  return root;
+}
+
+test('codeWithoutComments blanks comments and keeps strings and line positions', () => {
+  const source = "a // x\n/* b\n c */ d 'e // f' \"/* g */\" `h // i`\n";
+  const code = codeWithoutComments(source);
+  assert.equal(code.split('\n').length, source.split('\n').length);
+  assert.ok(!code.includes('x') && !code.includes(' b'));
+  assert.ok(code.includes("'e // f'") && code.includes('"/* g */"') && code.includes('`h // i`'));
+});
+
+test('isComposableEntry: one top-level void call, comments ignored', () => {
+  assert.equal(isComposableEntry(COMPOSABLE), true);
+  assert.equal(isComposableEntry('/*\nvoid bootstrapXemaService({});\n*/\n'), false);
+  assert.equal(isComposableEntry('void bootstrapXemaService({});\nvoid bootstrapXemaService({});\n'), false);
+  assert.equal(isComposableEntry('async function m() { await bootstrapXemaService({}); }\nvoid m();\n'), false);
+});
+
+test('deriveComposedMembers derives each exclusion from a repository fact; workers and runtime services are never members', () => {
+  const root = fixture();
+  const derived = deriveComposedMembers({
+    root,
+    manifestGlobs: ['biomes/**/xema-biome.json'],
+    canonicalDockerfile: 'infra/docker/nestjs-service.dockerfile',
+    crossRepoManifest: 'tooling/release/cross-repo-build-inputs.json',
+  });
+  assert.deepEqual(derived.members, { 'alpha/alpha-api': 'biomes/alpha/api/alpha-api' });
+  assert.deepEqual(derived.excluded, {
+    'alpha/alpha-own-api': ExclusionReason.OwnDockerfile,
+    'alpha/alpha-shape-api': ExclusionReason.EntryShape,
+    'alpha/alpha-tool-api': ExclusionReason.ImageToolchain,
+    'alpha/alpha-vendor-api': ExclusionReason.VendoredInputs,
+  });
+});
+
+test('deriveComposedMembers works for a product layout with no canonical or cross-repo inputs', () => {
+  const root = fixture();
+  const derived = deriveComposedMembers({ root, manifestGlobs: ['products/**/xema-biome.json'] });
+  assert.deepEqual(derived.members, { 'pai-core/pai-core-api': 'products/pai/core/pai-core/api/pai-core-api' });
+  assert.deepEqual(derived.excluded, {});
+});
+
+test('deriveComposedMembers refuses rather than derives a wrong set', () => {
+  const root = fixture();
+  assert.throws(
+    () => deriveComposedMembers({ root, manifestGlobs: ['biomes/**/xema-biome.json'], canonicalDockerfile: 'infra/docker/plain.dockerfile' }),
+    /declares no ARG SUPPLY_CHAIN/,
+  );
+  assert.throws(() => deriveComposedMembers({ root, manifestGlobs: ['nowhere/**/xema-biome.json'] }), /no tracked biome manifest/);
+  assert.throws(() => deriveComposedMembers({ root, manifestGlobs: [] }), /at least one glob/);
+});
+
+test('members --write then --check is current; a changed set is stale', () => {
+  const root = fixture();
+  const argv = ['members', '--root', root, '--manifests', 'products/**/xema-biome.json'];
+  fs.mkdirSync(path.join(root, 'infra/composed-process'), { recursive: true });
+  assert.throws(() => main([...argv, '--check'], { log() {} }), /is stale/);
+  main([...argv, '--write'], { log() {} });
+  assert.deepEqual(JSON.parse(fs.readFileSync(path.join(root, 'infra/composed-process/image-build-inputs.json'), 'utf8')), {
+    workspacePackages: ['products/pai/core/pai-core/api/pai-core-api'],
+  });
+  main([...argv, '--check'], { log() {} });
+  assert.throws(
+    () => syncImageBuildInputs({ mode: 'check', root, manifestGlobs: ['products/**/xema-biome.json', 'biomes/**/xema-biome.json'] }),
+    /is stale/,
+  );
+});
+
+test('parseArguments refuses unknown options and valueless flags', () => {
+  assert.deepEqual(parseArguments(['members', '--write', '--manifests', 'a', '--manifests', 'b']).options, { mode: 'write', manifests: ['a', 'b'] });
+  assert.throws(() => parseArguments(['index', '--bogus', 'x']), /unknown option --bogus/);
+  assert.throws(() => parseArguments(['index', '--build-source']), /needs a value/);
+  assert.throws(() => main(['nope'], { log() {} }), /usage:/);
+});
+
+/** A built image tree: two members, a host SDK with its bin, and the kernel schema. */
+function builtTree({ secondCopyOf } = {}) {
+  const root = fixture();
+  write(root, 'infra/composed-process/image-build-inputs.json', {
+    workspacePackages: ['biomes/alpha/api/alpha-api', 'products/pai/core/pai-core/api/pai-core-api'],
+  });
+  const sdk = (base) => {
+    write(root, `${base}/node_modules/@xemahq/xema-service-nest/package.json`, {
+      name: '@xemahq/xema-service-nest',
+      main: 'index.js',
+      bin: { 'xema-composed-process': 'dist/bin/xema-composed-process.js' },
+    });
+    write(root, `${base}/node_modules/@xemahq/xema-service-nest/dist/bin/xema-composed-process.js`, '');
+    write(
+      root,
+      `${base}/node_modules/@xemahq/xema-service-nest/index.js`,
+      "exports.readServiceEntry = (entry) => { if (entry.includes('pai-core')) throw new Error('graph does not load'); return {}; };\n",
+    );
+  };
+  sdk('.');
+  if (secondCopyOf) sdk(secondCopyOf);
+  write(root, 'node_modules/@xemahq/contracts/package.json', { name: '@xemahq/contracts', exports: { './*': './dist/*/index.js' } });
+  write(
+    root,
+    'node_modules/@xemahq/contracts/dist/process-topology/index.js',
+    "exports.ComposedProcessMemberIndexSchema = { parse(d) { if (d.schemaVersion !== 1 || !d.buildSource.repository) throw new Error('invalid index'); return d; } };\n",
+  );
+  for (const dir of ['biomes/alpha/api/alpha-api', 'products/pai/core/pai-core/api/pai-core-api']) write(root, `${dir}/dist/main.js`, '');
+  return root;
+}
+
+test('filters and dirs name every declared member', () => {
+  const root = builtTree();
+  assert.deepEqual(memberFilters({ root }), ['--filter @t/alpha-api...', '--filter @p/pai-core-api...']);
+  assert.deepEqual(readMembers({ root }).map(([key]) => key), ['alpha/alpha-api', 'pai-core/pai-core-api']);
+  write(root, 'infra/composed-process/image-build-inputs.json', { workspacePackages: ['biomes/alpha/api/missing-api'] });
+  assert.throws(() => readMembers({ root }), /declares 0 service\(s\)/);
+});
+
+test('index writes the member index under the declared build source and links the host', () => {
+  const root = builtTree();
+  assert.throws(() => writeMemberIndex({ root, commit: 'abc', buildSourceRepository: 'r' }), /40-hex/);
+  assert.throws(() => writeMemberIndex({ root, commit: COMMIT }), /--build-source/);
+  const result = writeMemberIndex({ root, commit: COMMIT, buildSourceRepository: 'presenca-biomes' });
+  assert.equal(result.members, 2);
+  const index = JSON.parse(fs.readFileSync(path.join(root, 'xema-composed-member-index.json'), 'utf8'));
+  assert.deepEqual(index.buildSource, { repository: 'presenca-biomes', commit: COMMIT });
+  assert.deepEqual(index.members['pai-core/pai-core-api'], { entry: 'products/pai/core/pai-core/api/pai-core-api/dist/main.js' });
+  assert.equal(
+    fs.readlinkSync(path.join(root, 'xema-composed-process')),
+    'node_modules/@xemahq/xema-service-nest/dist/bin/xema-composed-process.js',
+  );
+});
+
+test('index refuses two copies of the host and a missing built entry', () => {
+  const twoCopies = builtTree({ secondCopyOf: 'products/pai/core/pai-core/api/pai-core-api' });
+  assert.throws(() => writeMemberIndex({ root: twoCopies, commit: COMMIT, buildSourceRepository: 'r' }), /resolves @xemahq\/xema-service-nest at/);
+  const unbuilt = builtTree();
+  fs.rmSync(path.join(unbuilt, 'biomes/alpha/api/alpha-api/dist/main.js'));
+  assert.throws(() => writeMemberIndex({ root: unbuilt, commit: COMMIT, buildSourceRepository: 'r' }), /built entry .* does not exist/);
+});
+
+test('load reports every member whose graph does not load', () => {
+  const root = builtTree();
+  assert.throws(() => loadMembers({ root }), /1 of 2 member\(s\) do not load:\n {2}- pai-core\/pai-core-api: graph does not load/);
+});
+
+test('pins refuses a registry pin the committed lockfile lacks and ignores injected file: entries', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-composed-pins-'));
+  const lock = (...keys) => `lockfileVersion: '9.0'\n\npackages:\n\n${keys.map((k) => `  ${k}:\n    resolution: {}\n`).join('\n')}\nsnapshots: {}\n`;
+  write(root, 'committed.yaml', lock('a@1.0.0', "'@s/b@2.0.0'"));
+  write(root, 'pnpm-lock.yaml', lock('a@1.0.0', "'@s/b@2.0.0'", '@t/member@file:biomes/x'));
+  assert.deepEqual([...registryPins(path.join(root, 'committed.yaml'))], ['a@1.0.0', '@s/b@2.0.0']);
+  assert.equal(assertPinsUnchanged({ root, committedLockfile: path.join(root, 'committed.yaml') }), 2);
+  write(root, 'pnpm-lock.yaml', lock('a@1.0.1', "'@s/b@2.0.0'"));
+  assert.throws(() => assertPinsUnchanged({ root, committedLockfile: path.join(root, 'committed.yaml') }), /- a@1\.0\.1/);
+  write(root, 'v6.yaml', "lockfileVersion: '6.0'\n");
+  assert.throws(() => registryPins(path.join(root, 'v6.yaml')), /not a v9 lockfile/);
+});
+
+test('the bin runs through a symlink, as npm installs it, and exits non-zero on refusal', () => {
+  const root = builtTree();
+  const link = path.join(root, 'xema-composed-image');
+  fs.symlinkSync(BIN, link);
+  const out = execFileSync(process.execPath, [link, 'dirs', '--root', root], { encoding: 'utf8' });
+  assert.equal(out, 'biomes/alpha/api/alpha-api\nproducts/pai/core/pai-core/api/pai-core-api\n');
+  assert.throws(
+    () => execFileSync(process.execPath, [link, 'load', '--root', root], { encoding: 'utf8', stdio: 'pipe' }),
+    (error) => error.status === 1 && /xema-composed-image: 1 of 2 member/.test(error.stderr),
+  );
+});
+
+test('the new commands parse their options; coordinate is asynchronous and refuses without an image name', async () => {
+  const parsed = parseArguments(['dockerfile', '--write', '--copy', 'a', '--copy', 'b', '--cache-id', 'c', '--tooling-version', '1.2.3']);
+  assert.deepEqual(parsed.options.copy, ['a', 'b']);
+  assert.equal(parsed.options['cache-id'], 'c');
+  assert.deepEqual(parseArguments(['smoke-refusal', 'img', '--member', 'x/y', '--member', 'x/z']).options.member, ['x/y', 'x/z']);
+  await assert.rejects(main(['coordinate'], { log() {} }), /--image-name/);
+  assert.throws(() => main(['dockerfile', '--write'], { log() {} }), /exact x\.y\.z/);
+  assert.throws(() => main(['smoke-refusal'], { log() {} }), /usage/);
+});

package/src/declaration-refusal.mjs

@@ -0,0 +1,56 @@
+// The declaration-level refusal of the composed-process host, as data: the
+// scenario the smoke boots and the grade of what the host did with it.
+//
+// Scenario: two members of the image on ONE port. The host must refuse it while
+// grading the declaration — before any member is constructed — exit non-zero,
+// and name the collision. A host that constructs a member first, starts anyway,
+// or refuses for some other reason fails the grade.
+
+export const REFUSAL_PROCESS_NAME = 'declaration-refusal-smoke';
+export const PROCESS_PORT = 8080;
+export const SHARED_MEMBER_PORT = 8081;
+
+const HOST_REFUSAL = '[xema-composed-process] refused to start';
+/** Logged by the host for each member it previews or creates — after the declaration passed. */
+const MEMBER_CONSTRUCTION_MARKERS = ['previewing its module graph', '" created ('];
+
+function memberOf(key) {
+  const [biomeId, componentKey] = key.split('/');
+  return { biomeId, componentKey };
+}
+
+export function portCollisionMessage(keys) {
+  return `${keys.length} members listen on port ${SHARED_MEMBER_PORT} (${keys.join(', ')})`;
+}
+
+/** The host environment for `keys` (two member keys) sharing one port, with `memberFacts` derived from the image. */
+export function refusalEnvironment(keys, memberFacts) {
+  if (keys.length !== 2) throw new Error(`the refusal scenario takes exactly two members, got ${keys.length}`);
+  const prefixes = Object.fromEntries(keys.map((key, index) => [key, `M${index}_`]));
+  return {
+    XEMA_PROCESS_DEFINITION: JSON.stringify({
+      name: REFUSAL_PROCESS_NAME,
+      members: keys.map(memberOf),
+      replicas: { min: 1, max: 1 },
+      listen: { port: PROCESS_PORT },
+    }),
+    XEMA_PROCESS_MEMBER_FACTS: JSON.stringify(memberFacts),
+    XEMA_PROCESS_MEMBER_ENV_PREFIXES: JSON.stringify(prefixes),
+    ...Object.fromEntries(Object.values(prefixes).map((prefix) => [`${prefix}PORT`, String(SHARED_MEMBER_PORT)])),
+  };
+}
+
+/** Every way the host's run of the scenario is not the declaration-level refusal. Empty means it is. */
+export function gradeRefusal({ status, output }, keys) {
+  const problems = [];
+  if (status === 0) problems.push('the host exited 0 — it did not refuse');
+  if (status === null) problems.push('the host did not exit on its own');
+  if (!output.includes(HOST_REFUSAL)) problems.push(`the host never printed "${HOST_REFUSAL}"`);
+  const named = portCollisionMessage(keys);
+  if (!output.includes(named)) problems.push(`the refusal does not name the collision ("${named}")`);
+  for (const marker of MEMBER_CONSTRUCTION_MARKERS) {
+    const line = output.split('\n').find((candidate) => candidate.includes(marker));
+    if (line !== undefined) problems.push(`a member was constructed before the refusal: ${line.trim()}`);
+  }
+  return problems;
+}

package/src/declaration-refusal.test.mjs

@@ -0,0 +1,59 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import {
+  gradeRefusal,
+  portCollisionMessage,
+  refusalEnvironment,
+  SHARED_MEMBER_PORT,
+} from './declaration-refusal.mjs';
+
+const KEYS = ['activity-feed/activity-feed-api', 'agent-runtime/agent-session-api'];
+const REFUSED =
+  '[xema-composed-process] refused to start — Error: composeXemaProcess: process "declaration-refusal-smoke" ' +
+  `was handed mounts that do not match its declared members (1 problem):\n  - ${portCollisionMessage(KEYS)} — give each member its own PORT\n`;
+
+test('the scenario puts both members on one port, apart from the process port', () => {
+  const env = refusalEnvironment(KEYS, []);
+  const definition = JSON.parse(env.XEMA_PROCESS_DEFINITION);
+  assert.deepEqual(definition.members, [
+    { biomeId: 'activity-feed', componentKey: 'activity-feed-api' },
+    { biomeId: 'agent-runtime', componentKey: 'agent-session-api' },
+  ]);
+  assert.notEqual(definition.listen.port, SHARED_MEMBER_PORT);
+  const prefixes = JSON.parse(env.XEMA_PROCESS_MEMBER_ENV_PREFIXES);
+  for (const key of KEYS) assert.equal(env[`${prefixes[key]}PORT`], String(SHARED_MEMBER_PORT));
+});
+
+test('a declaration-level refusal grades clean', () => {
+  assert.deepEqual(gradeRefusal({ status: 1, output: REFUSED }, KEYS), []);
+});
+
+test('a host that starts is not a refusal', () => {
+  const problems = gradeRefusal({ status: 0, output: 'process "x" probes on 8080' }, KEYS);
+  assert.ok(problems.some((problem) => problem.includes('exited 0')));
+  assert.ok(problems.some((problem) => problem.includes('never printed')));
+});
+
+test('a host that never exits is not a refusal', () => {
+  assert.ok(gradeRefusal({ status: null, output: REFUSED }, KEYS).some((p) => p.includes('did not exit')));
+});
+
+test('a refusal for another reason does not name the collision', () => {
+  const output = '[xema-composed-process] refused to start — Error: members are missing required environment\n';
+  assert.ok(gradeRefusal({ status: 1, output }, KEYS).some((p) => p.includes('does not name the collision')));
+});
+
+test('a refusal after a member was previewed or created is not declaration-level', () => {
+  for (const line of [
+    `[Nest] LOG [composeXemaProcess] member "${KEYS[0]}": previewing its module graph (nothing is constructed)`,
+    `[Nest] LOG [composeXemaProcess] member "${KEYS[0]}" created (0 config service(s) bound)`,
+  ]) {
+    const problems = gradeRefusal({ status: 1, output: `${line}\n${REFUSED}` }, KEYS);
+    assert.ok(problems.some((p) => p.includes('constructed before the refusal')), line);
+  }
+});
+
+test('the scenario takes exactly two members', () => {
+  assert.throws(() => refusalEnvironment(KEYS.slice(0, 1), []), /exactly two/);
+});

package/src/derive-member-facts.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// INVOKER: declaration-refusal-smoke.mjs, INSIDE the composed-process image
+// (piped to the image's own node on stdin). Self-contained on purpose:
+// it resolves nothing from this repository's checkout, only from the image.
+//
+// Prints `ProcessMemberFacts[]` (JSON) for the members named on argv, derived
+// by the KERNEL's own `deriveProcessMemberFacts` from the biome manifests the
+// image carries and the build its member index names — the same projection the
+// distribution lock's `serviceProcessFacts` is made of. Nothing is restated:
+// kind, scheduler, scaling and intrinsic facts come from the parsed manifest.
+//
+// Usage: docker run -i --entrypoint node <image> --input-type=module - <biomeId>/<componentKey>... < derive-member-facts.mjs
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+const indexPath = process.env.XEMA_COMPOSED_MEMBER_INDEX;
+if (!indexPath) throw new Error('XEMA_COMPOSED_MEMBER_INDEX is not set — not a composed-process image');
+const root = dirname(indexPath);
+const index = JSON.parse(readFileSync(indexPath, 'utf8'));
+
+function manifestAbove(entry) {
+  for (let dir = dirname(join(root, entry)); dir !== root && dir !== dirname(dir); dir = dirname(dir)) {
+    const candidate = join(dir, 'xema-biome.json');
+    if (existsSync(candidate)) return candidate;
+  }
+  throw new Error(`no xema-biome.json above ${entry}`);
+}
+
+const keys = process.argv.slice(2);
+if (keys.length === 0) throw new Error('usage: derive-member-facts.mjs <biomeId>/<componentKey>...');
+
+const facts = keys.map((key) => {
+  const carried = index.members[key];
+  if (carried === undefined) throw new Error(`${key} is not in the image's member index`);
+  const requireFromMember = createRequire(join(root, carried.entry));
+  const { parseBiomeManifest, BiomeOrigin } = requireFromMember('@xemahq/contracts/biome');
+  const { deriveProcessMemberFacts, ProcessMemberFactsSchema } = requireFromMember(
+    '@xemahq/contracts/process-topology',
+  );
+  const manifest = parseBiomeManifest(JSON.parse(readFileSync(manifestAbove(carried.entry), 'utf8')));
+  const [biomeId, componentKey] = key.split('/');
+  if (manifest.xema.id !== biomeId) throw new Error(`${key}: manifest declares biome ${manifest.xema.id}`);
+  const component = manifest.xema.components.find((candidate) => candidate.key === componentKey);
+  if (component === undefined) throw new Error(`${key}: manifest declares no component ${componentKey}`);
+  return ProcessMemberFactsSchema.parse(
+    deriveProcessMemberFacts(component, {
+      biomeId,
+      // Every member of this image is built from this first-party repository.
+      origin: BiomeOrigin.FirstParty,
+      version: manifest.version,
+      buildSource: index.buildSource,
+    }),
+  );
+});
+process.stdout.write(`${JSON.stringify(facts)}\n`);

package/src/ghcr-manifest.mjs

@@ -0,0 +1,70 @@
+// Is a content-addressed image coordinate already in GHCR? Shared by every
+// repository that plans a build from a content tag (service matrix, composed image).
+//
+// Only 200 and 404 are answers; anything else throws, so an unreachable or
+// unauthorised registry can never read as "missing" and trigger a rebuild.
+
+const MANIFEST_ACCEPT = [
+  'application/vnd.oci.image.index.v1+json',
+  'application/vnd.oci.image.manifest.v1+json',
+  'application/vnd.docker.distribution.manifest.list.v2+json',
+  'application/vnd.docker.distribution.manifest.v2+json',
+].join(', ');
+
+function assertNonEmpty(value, label) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`${label} is missing or empty`);
+  }
+  return value;
+}
+
+function basicAuthorization(user, token) {
+  return `Basic ${Buffer.from(`${user}:${token}`, 'utf8').toString('base64')}`;
+}
+
+/**
+ * Acquire a pull-only GHCR bearer token for one repository.
+ *
+ * The endpoint is deliberately fixed to the configured GHCR host. Following a
+ * challenge-provided realm while carrying the long-lived credential would let
+ * an untrusted/misconfigured registry redirect that credential elsewhere.
+ */
+export async function acquireGhcrPullToken({ registry, repository, user, token, fetchImpl = fetch }) {
+  if (registry !== 'ghcr.io') {
+    throw new Error(`GHCR manifest check cannot send credentials to registry '${registry}'`);
+  }
+  assertNonEmpty(user, 'REGISTRY_USER');
+  assertNonEmpty(token, 'REGISTRY_TOKEN');
+  const url = new URL(`https://${registry}/token`);
+  url.searchParams.set('service', registry);
+  url.searchParams.set('scope', `repository:${repository}:pull`);
+  const response = await fetchImpl(url, {
+    method: 'GET',
+    headers: { Authorization: basicAuthorization(user, token), Accept: 'application/json' },
+  });
+  if (response.status !== 200) {
+    throw new Error(`${registry}: pull-token request for ${repository} returned HTTP ${response.status}`);
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    throw new Error(`${registry}: pull-token response for ${repository} was not JSON`);
+  }
+  if (typeof body?.token !== 'string' || body.token.length === 0) {
+    throw new Error(`${registry}: pull-token response for ${repository} contained no token`);
+  }
+  return body.token;
+}
+
+/** Returns `true` only for a proven existing manifest and `false` only for 404. */
+export async function ghcrManifestExists({ registry, repository, contentHash, user, token, fetchImpl = fetch }) {
+  const bearer = await acquireGhcrPullToken({ registry, repository, user, token, fetchImpl });
+  const response = await fetchImpl(`https://${registry}/v2/${repository}/manifests/${contentHash}`, {
+    method: 'HEAD',
+    headers: { Authorization: `Bearer ${bearer}`, Accept: MANIFEST_ACCEPT },
+  });
+  if (response.status === 200) return true;
+  if (response.status === 404) return false;
+  throw new Error(`${registry}: manifest lookup for ${repository}:${contentHash} returned HTTP ${response.status}`);
+}

package/src/ghcr-manifest.test.mjs

@@ -0,0 +1,96 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { acquireGhcrPullToken, ghcrManifestExists } from './ghcr-manifest.mjs';
+
+const HASH = 'a'.repeat(64);
+const COMMON = { registry: 'ghcr.io', repository: 'xema-dev/alpha-api', user: 'runner', token: 'secret' };
+
+function response(status, body) {
+  return {
+    status,
+    async json() {
+      if (body instanceof Error) throw body;
+      return body;
+    },
+  };
+}
+
+test('a pull token is requested with the exact repository scope', async () => {
+  let captured;
+  const token = await acquireGhcrPullToken({
+    ...COMMON,
+    fetchImpl: async (url, init) => {
+      captured = { url: String(url), init };
+      return response(200, { token: 'bearer-token' });
+    },
+  });
+  assert.equal(token, 'bearer-token');
+  const url = new URL(captured.url);
+  assert.equal(url.origin + url.pathname, 'https://ghcr.io/token');
+  assert.equal(url.searchParams.get('service'), 'ghcr.io');
+  assert.equal(url.searchParams.get('scope'), 'repository:xema-dev/alpha-api:pull');
+  assert.equal(captured.init.method, 'GET');
+  assert.match(captured.init.headers.Authorization, /^Basic /);
+});
+
+test('the long-lived credential can only be sent to GHCR', async () => {
+  let called = false;
+  await assert.rejects(
+    acquireGhcrPullToken({
+      ...COMMON,
+      registry: 'registry.example.com',
+      fetchImpl: async () => {
+        called = true;
+        return response(200, { token: 'bearer-token' });
+      },
+    }),
+    /cannot send credentials/,
+  );
+  assert.equal(called, false);
+});
+
+test('a missing credential is refused before any request', async () => {
+  await assert.rejects(acquireGhcrPullToken({ ...COMMON, token: '', fetchImpl: async () => assert.fail('requested') }), /REGISTRY_TOKEN/);
+});
+
+test('token acquisition fails closed on every uncertain response', async () => {
+  for (const status of [401, 403, 404, 429, 500]) {
+    await assert.rejects(acquireGhcrPullToken({ ...COMMON, fetchImpl: async () => response(status, {}) }), new RegExp(`HTTP ${status}`));
+  }
+  for (const body of [{}, { token: '' }, new Error('invalid json')]) {
+    await assert.rejects(acquireGhcrPullToken({ ...COMMON, fetchImpl: async () => response(200, body) }), /token response/);
+  }
+});
+
+test('only authenticated 200 and 404 are classified', async () => {
+  for (const [status, expected] of [[200, true], [404, false]]) {
+    const calls = [];
+    const exists = await ghcrManifestExists({
+      ...COMMON,
+      contentHash: HASH,
+      fetchImpl: async (url, init) => {
+        calls.push({ url: String(url), init });
+        return calls.length === 1 ? response(200, { token: 'bearer-token' }) : response(status, {});
+      },
+    });
+    assert.equal(exists, expected);
+    assert.equal(calls[1].url, `https://ghcr.io/v2/xema-dev/alpha-api/manifests/${HASH}`);
+    assert.equal(calls[1].init.method, 'HEAD');
+    assert.equal(calls[1].init.headers.Authorization, 'Bearer bearer-token');
+  }
+  for (const status of [401, 403, 429, 500]) {
+    let count = 0;
+    await assert.rejects(
+      ghcrManifestExists({
+        ...COMMON,
+        contentHash: HASH,
+        fetchImpl: async () => {
+          count += 1;
+          return count === 1 ? response(200, { token: 'bearer-token' }) : response(status, {});
+        },
+      }),
+      new RegExp(`HTTP ${status}`),
+    );
+  }
+});