@xemahq/xema 0.40.3 → 0.41.1

package/edition/develop-edition.mjs

@@ -18,7 +18,7 @@
 //       --sources-root, --cache-dir (no --deploy-root, no --kernel: the kernel is the catalogue's, from npm).
 //   target  <id> --pins <file> --registry <root> --engine-image <repository>@sha256:<digest>
 //       print <root>/<develop segment>/xema-edition-<id>:<tag>, the tag being sha256 of the canonical
-//       { cli, engine, pins, sourceImages } (developEditionTag): every input of the bytes the artifact records,
+//       { cli, engine, pins, sourceImages } (snapshotEditionTag): every input of the bytes the artifact records,
 //       so the same pins with another engine, source-image map or CLI version are another artifact. The root is always the caller's
 //       registry root (e.g. registry.example.com/acme); the develop namespace segment and the repository
 //       prefix come from edition-contract.json, and no root is implied.
@@ -38,6 +38,12 @@
 //       the same for a customer artifact; its descriptor's catalogue provenance pin must also equal the
 //       pinned develop catalogue digest, and its own image rows must be the rows the --source-image map composes. It fetches that catalogue (as `resolve --definition` does) to take the
 //       kernel from it. Takes --data-root, --cache-dir.
+//   coverage <id> --pins <file> --cosign <absolute-path> [--json]
+//       READ-ONLY: for every image subject of the snapshot, whether its develop image is producer-signed
+//       in the form T72 resolve accepts (attested | signature-verified | no-row | unsigned |
+//       annotations-missing | annotation-mismatch | not-built). Prints a table grouped by producer repo
+//       and `covered N/M` (--json: the same as data). Exit 0 only when every subject is covered, 1 when
+//       not, 2 on an operational error. Takes the roots `resolve` takes; writes nothing.
 //   check-overrides --overrides <json>
 //       refuse a pins override that would select the tooling this run executes
 //       (the edition tooling's own repository); the workflow runs it before any other checkout.
@@ -51,27 +57,21 @@
 // Tokens come from the environment (EVIDENCE_REPOSITORIES_TOKEN, XEMA_GHCR_PULL_TOKEN),
 // never argv. Nothing here writes git or publishes a release edition.
 
-import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 
-import { fetchCatalogue } from './catalogue-fetch.mjs';
-import { readCataloguePin } from './catalogue-pin.mjs';
 import { writeCatalogue } from './catalogue.mjs';
-import { CATALOGUE_TOKEN_ENV_FLAG, CATALOGUE_USERNAME_FLAG, DEFINITION_FLAG, SOURCE_IMAGE_FLAG } from './customer-flags.mjs';
-import { assertOwnImageRowsMatch, customerDevelopFrame, resolveCustomerDevelopEdition } from './develop-customer-edition.mjs';
+import { CUSTOMER_ROOTS, headResolver, parseEditionVerbArgs, runCustomerVerb, writeOnce } from './customer-edition-verbs.mjs';
+import { DEFINITION_FLAG } from './customer-flags.mjs';
+import { runDevelopCoverage } from './develop-coverage-run.mjs';
+import { CoverageExit } from './develop-coverage.mjs';
 import { resolveDevelopEdition } from './develop-edition-resolve.mjs';
-import { assertNoToolingOverride, freezeCustomerSources, freezeGraph, freezeSources, lsRemoteDevelopHead } from './develop-freeze.mjs';
-import { assertCanonicalDistributionId } from './distribution-paths.mjs';
-import { LOCAL_WORKFLOW, assertEngineImage, assertExistingArtifactMatches, developEditionTarget, workflowFromEnv, writeEditionArtifact } from './edition-artifact.mjs';
-import { editionWorkspaceConfig } from './edition-config.mjs';
+import { assertNoToolingOverride, freezeGraph, freezeSources } from './develop-freeze.mjs';
+import { LOCAL_WORKFLOW, assertExistingArtifactMatches, developEditionTarget, workflowFromEnv, writeEditionArtifact } from './edition-artifact.mjs';
 import { EditionChannel } from './edition-constants.mjs';
 import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, runtimeImageSourceIndexPath } from './edition-workspace.mjs';
 import { descriptorEvidenceTrust } from './evidence-trust-policy.mjs';
-import { holdSource } from './git-source-auth.mjs';
-import { adoptCatalogueKernel } from './kernel-package.mjs';
-import { loadKernelDistributionSchemas, serializeJson } from './lib.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
 import { snapshotPinSource } from './pin-source.mjs';
-import { assertSourceImagesCoverDefinition, parseSourceImages } from './resolve-customer-edition.mjs';
 import { composeEdition } from './resolve-distribution.mjs';
 import { readStrictJsonFile } from './strict-json.mjs';
 
@@ -81,12 +81,9 @@ import { readStrictJsonFile } from './strict-json.mjs';
 // takes only the data root in either form: it judges its --overrides JSON against the pin roles the data
 // root declares, so it reads nothing else and refuses every other root flag.
 const VENDOR_ROOTS = Object.freeze([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Deploy, WorkspaceRoot.Cache]);
-const CUSTOMER_ROOTS = Object.freeze({
-  resolve: [WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Cache],
-  target: [],
-  'check-existing': [WorkspaceRoot.Data, WorkspaceRoot.Cache],
-  'freeze-sources': [WorkspaceRoot.Data],
-});
+// `coverage` is the P2b gate: 1 means "not covered", so an operational error is a distinct 2.
+const COVERAGE_COMMAND = 'coverage';
+const COVERAGE_OPERATIONAL_EXIT = CoverageExit.Operational;
 const DATA_ROOT_ONLY_COMMANDS = Object.freeze(['check-overrides']);
 
 if (isEntryModule(import.meta.url)) {
@@ -95,103 +92,15 @@ if (isEntryModule(import.meta.url)) {
     configureEditionWorkspaceFromProcess([WorkspaceRoot.Data], { refuseOthers: true });
   } else {
     const customerForm = process.argv.includes(DEFINITION_FLAG);
-    configureEditionWorkspaceFromProcess(customerForm ? (CUSTOMER_ROOTS[command] ?? VENDOR_ROOTS) : VENDOR_ROOTS, { refuseOthers: customerForm && CUSTOMER_ROOTS[command] !== undefined });
+    configureEditionWorkspaceFromProcess(customerForm ? (CUSTOMER_ROOTS[command] ?? VENDOR_ROOTS) : VENDOR_ROOTS, {
+      refuseOthers: customerForm && CUSTOMER_ROOTS[command] !== undefined,
+      ...(command === COVERAGE_COMMAND ? { failureExitCode: COVERAGE_OPERATIONAL_EXIT } : {}),
+    });
   }
 }
 
-// Per verb: the vendor form (`positional` id, `values`, `switches`) and, where the verb has one, the customer
-// form: the flags only it takes, the further flags it requires, and the vendor flags it refuses.
-const CREDENTIAL_FLAGS = Object.freeze([CATALOGUE_USERNAME_FLAG, CATALOGUE_TOKEN_ENV_FLAG]);
-const REPEATABLE = Object.freeze([SOURCE_IMAGE_FLAG]);
-
-const COMMANDS = Object.freeze({
-  resolve: {
-    positional: true,
-    values: ['--pins', '--out', '--registry', '--engine-image'],
-    switches: ['--local'],
-    required: ['--pins', '--out', '--registry', '--engine-image'],
-    customer: { values: [DEFINITION_FLAG, ...CREDENTIAL_FLAGS, SOURCE_IMAGE_FLAG], required: ['--pins', '--out', '--registry', '--engine-image'], refused: [] },
-  },
-  target: {
-    positional: true,
-    values: ['--pins', '--registry', '--engine-image'],
-    switches: [],
-    required: ['--pins', '--registry', '--engine-image'],
-    customer: { values: [DEFINITION_FLAG, SOURCE_IMAGE_FLAG], required: ['--pins', '--registry', '--engine-image'], refused: [] },
-  },
-  'freeze-graph': {
-    positional: false,
-    values: ['--data-sha', '--kernel-sha', '--deploy-sha', '--editions-root-url', '--overrides', '--out'],
-    switches: [],
-    required: ['--data-sha', '--kernel-sha', '--deploy-sha', '--out'],
-  },
-  'freeze-sources': {
-    positional: true,
-    values: ['--pins', '--overrides', '--out'],
-    switches: [],
-    required: ['--pins', '--out'],
-    customer: { values: [DEFINITION_FLAG], required: ['--out'], refused: ['--pins', '--overrides'] },
-  },
-  'check-overrides': { positional: false, values: ['--overrides'], switches: [], required: ['--overrides'] },
-  'check-existing': {
-    positional: true,
-    values: ['--pins', '--artifact', '--engine-image'],
-    switches: [],
-    required: ['--pins', '--artifact', '--engine-image'],
-    customer: { values: [DEFINITION_FLAG, ...CREDENTIAL_FLAGS, SOURCE_IMAGE_FLAG], required: ['--pins', '--artifact', '--engine-image'], refused: [] },
-  },
-});
-
-/** Parse `<command> [<id>] --flag value ...` against the closed vocabulary of the command. */
-export function parseDevelopEditionArgs(argv) {
-  const [command, ...rest] = argv;
-  const spec = COMMANDS[command];
-  if (spec === undefined) {
-    throw new Error(`unknown command ${JSON.stringify(command)}; expected ${Object.keys(COMMANDS).join(' | ')}`);
-  }
-  const customerValues = spec.customer?.values ?? [];
-  const options = {};
-  const positional = [];
-  for (let i = 0; i < rest.length; i += 1) {
-    const arg = rest[i];
-    if (spec.switches.includes(arg)) {
-      options[arg] = true;
-    } else if (spec.values.includes(arg) || customerValues.includes(arg)) {
-      const value = rest[i + 1];
-      if (value === undefined || (value.startsWith('--') && value.length > 2)) {
-        throw new Error(`${arg} requires a value`);
-      }
-      if (REPEATABLE.includes(arg)) {
-        options[arg] = [...(options[arg] ?? []), value];
-      } else if (options[arg] !== undefined) {
-        throw new Error(`${arg} given twice`);
-      } else {
-        options[arg] = value;
-      }
-      i += 1;
-    } else if (arg.startsWith('--')) {
-      throw new Error(`unknown argument ${arg} for ${command}`);
-    } else {
-      positional.push(arg);
-    }
-  }
-  const customer = spec.customer !== undefined && customerValues.some((flag) => options[flag] !== undefined);
-  if (customer) {
-    if (options[DEFINITION_FLAG] === undefined) {throw new Error(`a customer ${command} requires ${DEFINITION_FLAG}`);}
-    for (const refused of spec.customer.refused) {
-      if (options[refused] !== undefined) {throw new Error(`a customer ${command} takes no ${refused}`);}
-    }
-    if (positional.length !== 0) {throw new Error(`a customer ${command} takes no <distribution-id>: the id is the definition's`);}
-  } else if (spec.positional ? positional.length !== 1 : positional.length !== 0) {
-    throw new Error(`${command} takes ${spec.positional ? 'exactly one <distribution-id>' : 'no positional argument'}`);
-  }
-  for (const required of customer ? spec.customer.required : spec.required) {
-    if (options[required] === undefined) {throw new Error(`${command} requires ${required}`);}
-  }
-  if (spec.positional && !customer) {assertCanonicalDistributionId(positional[0]);}
-  if (options['--engine-image'] !== undefined) {assertEngineImage(options['--engine-image']);}
-  return { command, id: positional[0], options, customer };
-}
+/** Parse `<command> [<id>] --flag value ...` against the closed vocabulary of the develop command. */
+export const parseDevelopEditionArgs = (argv) => parseEditionVerbArgs(EditionChannel.Develop, argv);
 
 function parseOverrides(text) {
   if (text === undefined || text.trim() === '') {return {};}
@@ -202,102 +111,16 @@ function parseOverrides(text) {
   return parsed;
 }
 
-function writeOnce(path, value) {
-  writeFileSync(path, serializeJson(value), { flag: 'wx' });
-}
-
-function headResolver(env) {
-  const workspace = editionWorkspaceConfig();
-  return { resolveHead: (source) => lsRemoteDevelopHead(source, { workspace, env }), holdSource: (source) => holdSource(source, workspace, env) };
-}
-
-/** The pinned develop catalogue of a customer definition: fetched by its digest, as every customer develop verb does. */
-function fetchPinnedDevelopCatalogue(options, env) {
-  return fetchCatalogue({
-    ref: readCataloguePin({ definitionFile: options[DEFINITION_FLAG], channel: EditionChannel.Develop }),
-    channel: EditionChannel.Develop,
-    username: options[CATALOGUE_USERNAME_FLAG],
-    tokenEnv: options[CATALOGUE_TOKEN_ENV_FLAG],
-    env,
-  });
-}
-
-/** A customer develop resolve: the artifact (descriptor and four locks, no catalogue: it is not an offering) goes to --out. */
-async function resolveCustomer(options, env) {
-  const { catalogue, digest } = await fetchPinnedDevelopCatalogue(options, env);
-  const rawDefinition = readStrictJsonFile(options[DEFINITION_FLAG]);
-  const sourceImages = parseSourceImages(options[SOURCE_IMAGE_FLAG] ?? []);
-  // The catalogue's kernel is adopted inside the resolve, before any kernel schema is loaded; the evidence trust
-  // state loads kernel schemas, so it is read after.
-  const { id, pins, ...resolved } = await resolveCustomerDevelopEdition({
-    rawDefinition,
-    catalogue,
-    catalogueDigest: digest,
-    pins: readStrictJsonFile(options['--pins']),
-    sourceImages,
-    env,
-  });
-  const evidenceTrustPolicy = await descriptorEvidenceTrust({ channel: EditionChannel.Develop });
-  const target = developEditionTarget(id, pins, { registry: options['--registry'], engineImage: options['--engine-image'], sourceImages });
-  writeEditionArtifact({
-    outDir: resolve(options['--out']),
-    channel: EditionChannel.Develop,
-    distributionId: id,
-    pins,
-    workflow: options['--local'] ? LOCAL_WORKFLOW : workflowFromEnv(env),
-    evidenceTrustPolicy,
-    engineImage: options['--engine-image'],
-    distributionLock: resolved.distributionLock,
-    imageLock: resolved.imageLock,
-    authorizationLock: resolved.authorizationLock,
-    chartSetLock: resolved.chartSetLock,
-  });
-  console.log(target);
-}
-
-/** A customer check-existing: the pinned catalogue is fetched to take its kernel; the digest fetched is the digest the artifact is compared with. */
-export async function checkExistingCustomer(options, env, { adopt = adoptCatalogueKernel } = {}) {
-  const frame = customerDevelopFrame({ definitionFile: options[DEFINITION_FLAG], pinsFile: options['--pins'] });
-  const sourceImages = customerSourceImages(options, frame.rawDefinition);
-  const { catalogue, digest } = await fetchPinnedDevelopCatalogue(options, env);
-  if (digest !== frame.catalogueDigest) {
-    throw new Error(`the fetched catalogue is ${digest}, not the pinned ${frame.catalogueDigest}`);
-  }
-  await adopt(catalogue);
-  assertExistingArtifactMatches({
-    artifactDir: resolve(options['--artifact']),
-    distributionId: frame.id,
-    channel: EditionChannel.Develop,
-    evidenceTrustPolicy: await descriptorEvidenceTrust({ channel: EditionChannel.Develop }),
-    pins: frame.pins,
-    engineImage: options['--engine-image'],
-    catalogueDigest: frame.catalogueDigest,
-  });
-  assertOwnImageRowsMatch({ artifactDir: resolve(options['--artifact']), sourceImages });
-}
-
-/** The parsed --source-image map of a customer verb, covering exactly the definition's declared sources. */
-function customerSourceImages(options, rawDefinition) {
-  const sourceImages = parseSourceImages(options[SOURCE_IMAGE_FLAG] ?? []);
-  assertSourceImagesCoverDefinition(rawDefinition, sourceImages);
-  return sourceImages;
-}
-
 async function run(argv, env) {
   const { command, id, options, customer } = parseDevelopEditionArgs(argv);
   switch (command) {
     case 'target': {
-      if (customer) {
-        const frame = customerDevelopFrame({ definitionFile: options[DEFINITION_FLAG], pinsFile: options['--pins'] });
-        const sourceImages = customerSourceImages(options, frame.rawDefinition);
-        console.log(developEditionTarget(frame.id, frame.pins, { registry: options['--registry'], engineImage: options['--engine-image'], sourceImages }));
-        return;
-      }
+      if (customer) {return runCustomerVerb({ channel: EditionChannel.Develop, command, options, env });}
       console.log(developEditionTarget(id, readStrictJsonFile(options['--pins']), { registry: options['--registry'], engineImage: options['--engine-image'] }));
       return;
     }
     case 'resolve': {
-      if (customer) {return resolveCustomer(options, env);}
+      if (customer) {return runCustomerVerb({ channel: EditionChannel.Develop, command, options, env });}
       const pins = readStrictJsonFile(options['--pins']);
       const workflow = options['--local'] ? LOCAL_WORKFLOW : workflowFromEnv(env);
       const target = developEditionTarget(id, pins, { registry: options['--registry'], engineImage: options['--engine-image'] });
@@ -318,8 +141,16 @@ async function run(argv, env) {
       console.log(target);
       return;
     }
+    case 'coverage':
+      return runDevelopCoverage({
+        id,
+        pins: readStrictJsonFile(options['--pins']),
+        cosignBinary: options['--cosign'],
+        json: options['--json'] === true,
+        env,
+      });
     case 'check-existing': {
-      if (customer) {return checkExistingCustomer(options, env);}
+      if (customer) {return runCustomerVerb({ channel: EditionChannel.Develop, command, options, env });}
       assertExistingArtifactMatches({
         artifactDir: resolve(options['--artifact']),
         distributionId: id,
@@ -342,29 +173,19 @@ async function run(argv, env) {
         deploySha: options['--deploy-sha'],
         editionsRootUrl: options['--editions-root-url'],
         overrides: parseOverrides(options['--overrides']),
-        ...headResolver(env),
+        ...headResolver(EditionChannel.Develop, env),
       });
       writeOnce(options['--out'], pins);
       return;
     }
     case 'freeze-sources': {
-      if (customer) {
-        writeOnce(
-          options['--out'],
-          freezeCustomerSources({
-            definition: readStrictJsonFile(options[DEFINITION_FLAG]),
-            ...headResolver(env),
-            sourceRepositoryUrlPrefix: editionWorkspaceConfig().sourceRepositoryUrlPrefix,
-          }),
-        );
-        return;
-      }
+      if (customer) {return runCustomerVerb({ channel: EditionChannel.Develop, command, options, env });}
       const pins = readStrictJsonFile(options['--pins']);
       const { parseDistribution } = await loadKernelDistributionSchemas();
       const declaredSources = composeEdition(parseDistribution, id, snapshotPinSource(pins)).declaredSources;
       writeOnce(
         options['--out'],
-        freezeSources({ pins, declaredSources, overrides: parseOverrides(options['--overrides']), ...headResolver(env) }),
+        freezeSources({ pins, declaredSources, overrides: parseOverrides(options['--overrides']), ...headResolver(EditionChannel.Develop, env) }),
       );
       return;
     }
@@ -374,8 +195,14 @@ async function run(argv, env) {
 }
 
 if (isEntryModule(import.meta.url)) {
-  run(process.argv.slice(2), process.env).catch((error) => {
-    console.error(`[develop-edition] ${error.message}`);
-    process.exit(1);
-  });
+  const argv = process.argv.slice(2);
+  run(argv, process.env).then(
+    (code) => {
+      if (typeof code === 'number') {process.exitCode = code;}
+    },
+    (error) => {
+      console.error(`[develop-edition] ${error.message}`);
+      process.exit(argv[0] === COVERAGE_COMMAND ? COVERAGE_OPERATIONAL_EXIT : 1);
+    },
+  );
 }

package/edition/develop-freeze.mjs

@@ -15,6 +15,7 @@
 
 import { execFileSync } from 'node:child_process';
 
+import { EditionChannel } from './edition-channel.mjs';
 import { assertCanonicalSourceUrl, assertSourceDeclaresNoCredential, isUnderSourcePrefix, withSourceGitEnv } from './git-source-auth.mjs';
 import { canonicalPublicHttpsRepositoryUrl } from './lib.mjs';
 import {
@@ -29,35 +30,71 @@ import {
   sourcePinKey,
 } from './pin-source.mjs';
 
-const DEVELOP_REF = 'refs/heads/develop';
 const SHA_PATTERN = /^[0-9a-f]{40}$/;
 
+/** The ref namespaces a freeze may resolve a ref in. */
+export const RefKind = Object.freeze({ Branch: 'branch', Tag: 'tag' });
+
+const REF_PREFIX = Object.freeze({ [RefKind.Branch]: 'refs/heads/', [RefKind.Tag]: 'refs/tags/' });
+const PEELED_SUFFIX = '^{}';
+
+/**
+ * What each channel freezes a source at. A develop edition freezes the head of the `develop` BRANCH of every
+ * repository; a release edition freezes each source at the ref its definition declares, a branch or a tag.
+ */
+const FREEZE_REF_KINDS = Object.freeze({
+  [EditionChannel.Develop]: Object.freeze([RefKind.Branch]),
+  [EditionChannel.Release]: Object.freeze([RefKind.Branch, RefKind.Tag]),
+});
+
 /**
- * `git ls-remote <url> refs/heads/develop` for one source `{ name, url }`; throws naming the repository when
- * absent. The source is held and its git environment built by `withSourceGitEnv`: the workspace credential
- * reaches only a repository under `sourceRepositoryUrlPrefix`.
+ * The commit `ref` names in one source `{ name, url }`, by `git ls-remote <url> <refs/heads/ref | refs/tags/ref |
+ * refs/tags/ref^{}>` (only the namespaces the channel freezes at). A tag resolves to its peeled commit when it is annotated.
+ * Throws naming the repository when the ref is absent, or when it is both a branch and a tag. The source is held and its
+ * git environment built by `withSourceGitEnv`: the workspace credential reaches only a repository under `sourceRepositoryUrlPrefix`.
  */
-export function lsRemoteDevelopHead(source, { workspace, env = process.env, runGit = execFileSync }) {
+export function lsRemoteRef(source, ref, { channel, workspace, env = process.env, runGit = execFileSync }) {
+  const kinds = FREEZE_REF_KINDS[channel];
+  if (kinds === undefined) {throw new Error(`unknown edition channel ${JSON.stringify(channel)}`);}
+  if (typeof ref !== 'string' || ref.length === 0) {
+    throw new Error(`source "${source.name}" declares no ref; a ${channel} edition cannot be frozen without one`);
+  }
+  const names = kinds.flatMap((kind) => (kind === RefKind.Tag ? [`${REF_PREFIX[kind]}${ref}`, `${REF_PREFIX[kind]}${ref}${PEELED_SUFFIX}`] : [`${REF_PREFIX[kind]}${ref}`]));
   const output = withSourceGitEnv(source, { workspace, env }, (gitEnv) =>
-    runGit('git', ['ls-remote', source.url, DEVELOP_REF], {
+    runGit('git', ['ls-remote', source.url, ...names], {
       env: gitEnv,
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
     }),
   ).trim();
-  const [sha, ref] = output.split(/\s+/);
-  if (!SHA_PATTERN.test(sha ?? '') || ref !== DEVELOP_REF) {
-    throw new Error(`${source.url} has no ${DEVELOP_REF}; a develop edition cannot be frozen without it`);
+  const served = new Map();
+  for (const line of output.split('\n')) {
+    const [sha, name] = line.trim().split(/\s+/);
+    if (names.includes(name)) {
+      if (!SHA_PATTERN.test(sha ?? '')) {throw new Error(`${source.url}: git ls-remote answered ${JSON.stringify(line)} for ${name}`);}
+      served.set(name, sha);
+    }
+  }
+  const branch = served.get(`${REF_PREFIX[RefKind.Branch]}${ref}`);
+  const tagName = `${REF_PREFIX[RefKind.Tag]}${ref}`;
+  const tag = served.get(`${tagName}${PEELED_SUFFIX}`) ?? served.get(tagName);
+  if (branch !== undefined && tag !== undefined) {
+    throw new Error(`${source.url}: ${JSON.stringify(ref)} is both a branch and a tag; a ${channel} edition cannot be frozen at an ambiguous ref`);
+  }
+  const commit = branch ?? tag;
+  if (commit === undefined) {
+    throw new Error(`${source.url} has no ${kinds.map((kind) => `${REF_PREFIX[kind]}${ref}`).join(' or ')}; a ${channel} edition cannot be frozen without it`);
   }
-  return sha;
+  return commit;
 }
 
-/** A resolver that asks `resolveHead` at most once per distinct URL; it takes the source `{ name, url }`. */
+/** A resolver that asks `resolveHead` at most once per distinct URL and ref; it takes the source `{ name, url, ref? }`. */
 function memoizedHeads(resolveHead) {
   const heads = new Map();
   return (source) => {
-    if (!heads.has(source.url)) {heads.set(source.url, resolveHead(source));}
-    return heads.get(source.url);
+    const key = JSON.stringify([source.url, source.ref]);
+    if (!heads.has(key)) {heads.set(key, resolveHead(source));}
+    return heads.get(key);
   };
 }
 

package/edition/develop-image-probe.mjs

@@ -18,20 +18,20 @@ import { registryClientsFor } from './verify-image-platforms.mjs';
 
 const DEFAULT_PROBE_CONCURRENCY = 6;
 
-/** One subject's line in the "not built yet" refusal. */
-export function notBuiltYetMessage(subject) {
+/** One subject's line in the "not built yet" refusal of `channel` (develop unless named). */
+export function notBuiltYetMessage(subject, channel = 'develop') {
   return (
-    `${subject.repo}@${subject.sourceCommit} develop image ` +
+    `${subject.repo}@${subject.sourceCommit} ${channel} image ` +
     `${subject.imageRef}:${subject.contentHash} not built yet`
   );
 }
 
-/** The ONE refusal naming every develop subject whose coordinate is absent. */
-export function notBuiltYetError(distributionId, missingSubjects) {
+/** The ONE refusal naming every subject of `channel` (develop unless named) whose coordinate is absent. */
+export function notBuiltYetError(distributionId, missingSubjects, channel = 'develop') {
   return new Error(
-    `${missingSubjects.length} develop image(s) of "${distributionId}" are not built yet ` +
+    `${missingSubjects.length} ${channel} image(s) of "${distributionId}" are not built yet ` +
       "(the producer's CI is not green or still running):\n  " +
-      missingSubjects.map(notBuiltYetMessage).join('\n  '),
+      missingSubjects.map((subject) => notBuiltYetMessage(subject, channel)).join('\n  '),
   );
 }
 

package/edition/dispatched-runtime-components.mjs

@@ -1,5 +1,70 @@
 import { compareStrings } from './string-order.mjs';
 
+/** A `runtime-image` edge target that is neither `{biomeId, componentKey}` nor `{supplementalRuntimeComponentId}`, or is both. */
+export class DispatchedEdgeError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'DispatchedEdgeError';
+  }
+}
+
+/** A dispatched `supplemental:<id>` the runtime-image source index does not declare as a supplemental subject. */
+export class UndeclaredSupplementalRuntimeComponentError extends Error {
+  constructor(supplementalRuntimeComponentId, dispatchingBiomes, context) {
+    super(
+      `${context}: supplemental runtime component "${supplementalRuntimeComponentId}", dispatched by biome ` +
+        `${dispatchingBiomes.map((id) => `"${id}"`).join(', ')}, is not declared as a runtime-component subject ` +
+        'by the runtime image source index — refusing rather than shipping the dispatcher without the image it launches.',
+    );
+    this.name = 'UndeclaredSupplementalRuntimeComponentError';
+    this.supplementalRuntimeComponentId = supplementalRuntimeComponentId;
+    this.dispatchingBiomes = dispatchingBiomes;
+  }
+}
+
+// The `supplementalRuntimeComponentId` field is read as plain data: this CLI is on
+// @xemahq/contracts 0.83, which does not type it. XEMA-171 (CLI edition protocol
+// v9) adopts the typed field from @xemahq/contracts >= 0.91.
+const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0;
+
+/** True for the supplemental form of a projected edge. */
+export const isSupplementalEdge = (edge) => edge.supplementalRuntimeComponentId !== undefined;
+
+/** The identity of a projected edge: `supplemental:<id>` or `<biomeId>\0<componentKey>`. */
+export const dispatchedEdgeIdentity = (edge) =>
+  isSupplementalEdge(edge)
+    ? `supplemental:${edge.supplementalRuntimeComponentId}`
+    : `${edge.biomeId}\0${edge.componentKey}`;
+
+/**
+ * Project one generated-index `runtime-image` edge target into the typed union
+ * the index entry carries. A target that is neither form, or both, is refused
+ * naming the dispatching biome; no `undefined` identity can form.
+ */
+export function projectDispatchedTarget(dispatchingBiomeId, target) {
+  const supplemental = target?.supplementalRuntimeComponentId;
+  const biomeForm = target?.biomeId !== undefined || target?.componentKey !== undefined;
+  if (supplemental !== undefined) {
+    if (biomeForm || !isNonEmptyString(supplemental)) {
+      throw new DispatchedEdgeError(
+        `biome "${dispatchingBiomeId}" has a runtime-image edge target that mixes supplementalRuntimeComponentId with ` +
+          'biomeId/componentKey, or names an empty id — a target is exactly one form',
+      );
+    }
+    return { supplementalRuntimeComponentId: supplemental };
+  }
+  if (!isNonEmptyString(target?.biomeId) || !isNonEmptyString(target?.componentKey)) {
+    throw new DispatchedEdgeError(
+      `biome "${dispatchingBiomeId}" has a runtime-image edge target that is neither { biomeId, componentKey } nor ` +
+        '{ supplementalRuntimeComponentId }',
+    );
+  }
+  return { biomeId: target.biomeId, componentKey: target.componentKey };
+}
+
+const edgeLabel = (edge) =>
+  isSupplementalEdge(edge) ? `supplemental:${edge.supplementalRuntimeComponentId}` : `${edge.biomeId}/${edge.componentKey}`;
+
 /**
  * The runtime components an edition must carry because a biome it rosters
  * DISPATCHES them: the kernel's `runtime-image` edges, projected per biome into
@@ -21,6 +86,10 @@ import { compareStrings } from './string-order.mjs';
  * no biome drawn from a declared source. A biome drawn from a declared source
  * that dispatches is refused for the same reason.
  *
+ * A supplemental edge (`{supplementalRuntimeComponentId}`) names no biome: it
+ * is carried as a row `{ supplementalRuntimeComponentId, consumers }` without
+ * a biome lookup.
+ *
  * Returns one row per distinct (target biome, component key), sorted, with the
  * rostered biomes that dispatch it. Every unresolvable edge is refused, naming
  * the consumer and the target.
@@ -37,12 +106,24 @@ export function resolveDispatchedRuntimeComponents(context, consumers, index) {
     if (consumer.source !== undefined) {
       throw new Error(
         `${context}: biome "${consumer.id}", drawn from declared source "${consumer.source}", dispatches ` +
-          `runtime components (${edges.map((edge) => `${edge.biomeId}/${edge.componentKey}`).join(', ')}). ` +
+          `runtime components (${edges.map(edgeLabel).join(', ')}). ` +
           'A dispatched image is resolved from the first-party biome index, which carries no biome from a ' +
           'declared source — refusing rather than shipping the dispatcher without the images it launches.',
       );
     }
     for (const edge of edges) {
+      if (isSupplementalEdge(edge)) {
+        // Carried as a requirement owned by the dispatching biome. Whether the
+        // runtime image source index declares it is the image plane's refusal.
+        const supplementalKey = dispatchedEdgeIdentity(edge);
+        const row = rows.get(supplementalKey) ?? {
+          supplementalRuntimeComponentId: edge.supplementalRuntimeComponentId,
+          consumers: [],
+        };
+        if (!row.consumers.includes(consumer.id)) {row.consumers.push(consumer.id);}
+        rows.set(supplementalKey, row);
+        continue;
+      }
       const edgeText = `biome "${consumer.id}" dispatches runtime component "${edge.componentKey}" of biome "${edge.biomeId}"`;
       const candidates = index.filter(
         (entry) => entry.id === edge.biomeId && entry.target === 'server' && entry.source === undefined,
@@ -80,3 +161,11 @@ export function resolveDispatchedRuntimeComponents(context, consumers, index) {
     .sort(([a], [b]) => compareStrings(a, b))
     .map(([, row]) => row);
 }
+
+/** Sort order of projected edges: biome edges by (biomeId, componentKey), then supplemental edges by id. */
+export function compareDispatchedEdges(a, b) {
+  if (isSupplementalEdge(a) !== isSupplementalEdge(b)) {return isSupplementalEdge(a) ? 1 : -1;}
+  return isSupplementalEdge(a)
+    ? compareStrings(a.supplementalRuntimeComponentId, b.supplementalRuntimeComponentId)
+    : compareStrings(a.biomeId, b.biomeId) || compareStrings(a.componentKey, b.componentKey);
+}