@xemahq/xema 0.29.1 → 0.31.0

package/edition/develop-edition-resolve.mjs

@@ -6,12 +6,14 @@
 // xema-deploy charts' registry manifest digests, in the release roster shape. Nothing here writes to the editions
 // trees; the caller writes the artifact (edition-artifact.mjs).
 
+import { adapterHostRow, assertAdapterBundlesMatchHost, fetchRegistryManifest } from './adapter-bundled-versions.mjs';
 import { biomeSourceTreeIds, sealLock } from './biome-content.mjs';
 import { buildCatalogue } from './catalogue.mjs';
 import { sealDevelopImages } from './develop-seal.mjs';
 import { assertFrozenCheckouts, buildSnapshotInputs } from './develop-snapshot-inputs.mjs';
 import { EditionChannel } from './edition-constants.mjs';
-import { deployRoot } from './edition-workspace.mjs';
+import { deployRoot, kernelPackageDir } from './edition-workspace.mjs';
+import { kernelPackageOfAuthority } from './kernel-package.mjs';
 import { loadKernelDistributionSchemas } from './lib.mjs';
 import { deployPinKey } from './pin-source.mjs';
 import { resolveDevelopChartSet } from './resolve-chart-set.mjs';
@@ -19,11 +21,12 @@ import { composeAuthorizationBase, resolveDistributionWithIndex } from './resolv
 import { externalSourceTrees, resolveImages, sourceTreeLocator } from './resolve-images.mjs';
 import { createPinnedSourceAuthority } from './source-authority.mjs';
 
-export async function resolveDevelopEdition({ id, pins, env = process.env, sealOptions = {}, chartDigestLookup }) {
+export async function resolveDevelopEdition({ id, pins, env = process.env, sealOptions = {}, chartDigestLookup, fetchKernelTarball, fetchManifest = fetchRegistryManifest }) {
   const schemas = await loadKernelDistributionSchemas();
   assertFrozenCheckouts(pins);
   const inputs = await buildSnapshotInputs({ id, pins, schemas });
   const { lock, index } = await resolveDistributionWithIndex(id, { inputs });
+  await assertAdapterBundlesMatchHost({ lock, hostRow: adapterHostRow(index), fetchManifest });
   const authorizationLock = await composeAuthorizationBase(id, lock, index);
   const { imageLock } = await resolveImages(id, { inputs, lock });
   const sealedImageLock = await sealDevelopImages({ imageLock, env, ...sealOptions });
@@ -59,6 +62,11 @@ export async function resolveDevelopEdition({ id, pins, env = process.env, sealO
     biomeIndex: inputs.biomeIndex,
     platformServiceIndex: inputs.platformServiceIndex,
     contractAuthority: inputs.runtimeImageSourceIndex.contractAuthority,
+    kernel: await kernelPackageOfAuthority({
+      kernelPackageDir: kernelPackageDir(),
+      contractAuthority: inputs.runtimeImageSourceIndex.contractAuthority,
+      ...(fetchKernelTarball === undefined ? {} : { fetchTarball: fetchKernelTarball }),
+    }),
     leaf: inputs.composed.leaf,
   });
   return { distributionLock: sealedLock, imageLock: sealedImageLock, authorizationLock, chartSetLock, catalogue };

package/edition/develop-edition.mjs

@@ -15,7 +15,7 @@
 //       customer's own pins. --pins holds exactly one `sources/<name>` commit per source the definition
 //       declares (`freeze-sources --definition` writes it); the catalogue digest is frozen into the descriptor's
 //       provenance pins as `catalogue`. The id is the definition's. Takes --data-root, --editions-root,
-//       --sources-root, --kernel, --cache-dir (no --deploy-root).
+//       --sources-root, --cache-dir (no --deploy-root, no --kernel: the kernel is the catalogue's, from npm).
 //   target  <id> --pins <file> --registry <root>
 //       print <root>/<develop segment>/xema-edition-<id>:<snapshot hash>. The root is always the caller's
 //       registry root (e.g. registry.example.com/acme); the develop namespace segment and the repository
@@ -31,8 +31,10 @@
 //   check-existing <id> --pins <file> --artifact <dir> --engine-image <repository>@sha256:<digest>
 //       refuse to reuse a pulled artifact whose descriptor disagrees with this snapshot.
 //   check-existing --definition <file> --pins <file> --artifact <dir> --engine-image <repository>@sha256:<digest>
+//                  [--catalogue-username <name> --catalogue-token-env <VAR>]
 //       the same for a customer artifact; its descriptor's catalogue provenance pin must also equal the
-//       pinned develop catalogue digest.
+//       pinned develop catalogue digest. It fetches that catalogue (as `resolve --definition` does) to take the
+//       kernel from it. Takes --data-root, --cache-dir.
 //   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.
@@ -42,9 +44,6 @@
 //   freeze-sources --definition <file> --out <file>
 //       a CUSTOMER edition: one `sources/<name>` pin per source the definition declares, each the head of
 //       refs/heads/develop of that source's repository, resolved once; written exclusively (wx).
-//   kernel-commit --definition <file> [--catalogue-username <name> --catalogue-token-env <VAR>]
-//       fetch the pinned develop catalogue and print its contractAuthority.sourceCommit (one 40-hex line):
-//       the commit the kernel contracts are checked out at. Takes --data-root only (no --kernel).
 //
 // Tokens come from the environment (EVIDENCE_REPOSITORIES_TOKEN, XEMA_GHCR_PULL_TOKEN),
 // never argv. Nothing here writes git or publishes a release edition.
@@ -54,7 +53,7 @@ import { resolve } from 'node:path';
 
 import { fetchCatalogue } from './catalogue-fetch.mjs';
 import { readCataloguePin } from './catalogue-pin.mjs';
-import { contractAuthoritySourceCommit, writeCatalogue } from './catalogue.mjs';
+import { writeCatalogue } from './catalogue.mjs';
 import { CATALOGUE_TOKEN_ENV_FLAG, CATALOGUE_USERNAME_FLAG, DEFINITION_FLAG, SOURCE_IMAGE_FLAG } from './customer-flags.mjs';
 import { customerDevelopFrame, resolveCustomerDevelopEdition } from './develop-customer-edition.mjs';
 import { resolveDevelopEdition } from './develop-edition-resolve.mjs';
@@ -65,28 +64,36 @@ import { editionWorkspaceConfig } from './edition-config.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 { snapshotPinSource } from './pin-source.mjs';
 import { parseSourceImages } from './resolve-customer-edition.mjs';
 import { composeEdition } from './resolve-distribution.mjs';
 import { readStrictJsonFile } from './strict-json.mjs';
 
-// The roots a verb takes. A customer form (it names --definition) takes fewer: `target` none, `check-existing`
-// the data root and the kernel, `freeze-sources` and `kernel-commit` the data root only (`kernel-commit` runs
-// before the kernel is checked out), `resolve` all but the deploy root.
+// The roots a verb takes. A customer form (it names --definition) takes fewer, and never the kernel (the
+// catalogue's kernel is downloaded from npm into the cache root): `target` none, `check-existing` the data
+// root and the cache, `freeze-sources` the data root only, `resolve` all but the deploy root. `check-overrides`
+// 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.Kernel, WorkspaceRoot.Cache],
+  resolve: [WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Cache],
   target: [],
-  'check-existing': [WorkspaceRoot.Data, WorkspaceRoot.Kernel],
+  'check-existing': [WorkspaceRoot.Data, WorkspaceRoot.Cache],
   'freeze-sources': [WorkspaceRoot.Data],
-  'kernel-commit': [WorkspaceRoot.Data],
 });
+const DATA_ROOT_ONLY_COMMANDS = Object.freeze(['check-overrides']);
 
 if (isEntryModule(import.meta.url)) {
   const [command] = process.argv.slice(2);
-  const customerForm = process.argv.includes(DEFINITION_FLAG) || command === 'kernel-commit';
-  configureEditionWorkspaceFromProcess(customerForm ? (CUSTOMER_ROOTS[command] ?? VENDOR_ROOTS) : VENDOR_ROOTS, { refuseOthers: customerForm && CUSTOMER_ROOTS[command] !== undefined });
+  if (DATA_ROOT_ONLY_COMMANDS.includes(command)) {
+    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 });
+  }
 }
 
 // Per verb: the vendor form (`positional` id, `values`, `switches`) and, where the verb has one, the customer
@@ -128,15 +135,7 @@ const COMMANDS = Object.freeze({
     values: ['--pins', '--artifact', '--engine-image'],
     switches: [],
     required: ['--pins', '--artifact', '--engine-image'],
-    customer: { values: [DEFINITION_FLAG], required: ['--pins', '--artifact', '--engine-image'], refused: [] },
-  },
-  'kernel-commit': {
-    positional: false,
-    values: [],
-    switches: [],
-    required: [],
-    customerOnly: true,
-    customer: { values: [DEFINITION_FLAG, ...CREDENTIAL_FLAGS], required: [], refused: [] },
+    customer: { values: [DEFINITION_FLAG, ...CREDENTIAL_FLAGS], required: ['--pins', '--artifact', '--engine-image'], refused: [] },
   },
 });
 
@@ -173,7 +172,7 @@ export function parseDevelopEditionArgs(argv) {
       positional.push(arg);
     }
   }
-  const customer = spec.customer !== undefined && (spec.customerOnly === true || customerValues.some((flag) => options[flag] !== undefined));
+  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) {
@@ -205,21 +204,27 @@ function writeOnce(path, value) {
 }
 
 function headResolver(env) {
-  return (source) => lsRemoteDevelopHead(source, { workspace: editionWorkspaceConfig(), env });
+  const workspace = editionWorkspaceConfig();
+  return { resolveHead: (source) => lsRemoteDevelopHead(source, { workspace, env }), holdSource: (source) => holdSource(source, workspace, 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 ref = readCataloguePin({ definitionFile: options[DEFINITION_FLAG], channel: EditionChannel.Develop });
-  const { catalogue, digest } = await fetchCatalogue({
-    ref,
+/** 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 evidenceTrustPolicy = await descriptorEvidenceTrust({ channel: EditionChannel.Develop });
+  // 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,
@@ -228,6 +233,7 @@ async function resolveCustomer(options, env) {
     sourceImages: parseSourceImages(options[SOURCE_IMAGE_FLAG] ?? []),
     env,
   });
+  const evidenceTrustPolicy = await descriptorEvidenceTrust({ channel: EditionChannel.Develop });
   const target = developEditionTarget(id, pins, { registry: options['--registry'] });
   writeEditionArtifact({
     outDir: resolve(options['--out']),
@@ -245,21 +251,23 @@ async function resolveCustomer(options, env) {
   console.log(target);
 }
 
-/**
- * The commit the pinned develop catalogue's contract authority was taken at. The kernel contracts are
- * not checked out yet when this runs, so nothing here validates against kernel schemas: the catalogue
- * parser is kernel-free, and the one field read is `contractAuthority.sourceCommit`, held to 40 hex.
- */
-async function customerKernelCommit(options, env) {
-  const ref = readCataloguePin({ definitionFile: options[DEFINITION_FLAG], channel: EditionChannel.Develop });
-  const { catalogue } = await fetchCatalogue({
-    ref,
+/** 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 { 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,
-    username: options[CATALOGUE_USERNAME_FLAG],
-    tokenEnv: options[CATALOGUE_TOKEN_ENV_FLAG],
-    env,
+    evidenceTrustPolicy: await descriptorEvidenceTrust({ channel: EditionChannel.Develop }),
+    pins: frame.pins,
+    engineImage: options['--engine-image'],
+    catalogueDigest: frame.catalogueDigest,
   });
-  console.log(contractAuthoritySourceCommit(catalogue));
 }
 
 async function run(argv, env) {
@@ -297,19 +305,7 @@ async function run(argv, env) {
       return;
     }
     case 'check-existing': {
-      if (customer) {
-        const frame = customerDevelopFrame({ definitionFile: options[DEFINITION_FLAG], pinsFile: options['--pins'] });
-        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,
-        });
-        return;
-      }
+      if (customer) {return checkExistingCustomer(options, env);}
       assertExistingArtifactMatches({
         artifactDir: resolve(options['--artifact']),
         distributionId: id,
@@ -332,7 +328,7 @@ async function run(argv, env) {
         deploySha: options['--deploy-sha'],
         editionsRootUrl: options['--editions-root-url'],
         overrides: parseOverrides(options['--overrides']),
-        resolveHead: headResolver(env),
+        ...headResolver(env),
       });
       writeOnce(options['--out'], pins);
       return;
@@ -343,7 +339,7 @@ async function run(argv, env) {
           options['--out'],
           freezeCustomerSources({
             definition: readStrictJsonFile(options[DEFINITION_FLAG]),
-            resolveHead: headResolver(env),
+            ...headResolver(env),
             sourceRepositoryUrlPrefix: editionWorkspaceConfig().sourceRepositoryUrlPrefix,
           }),
         );
@@ -354,12 +350,10 @@ async function run(argv, env) {
       const declaredSources = composeEdition(parseDistribution, id, snapshotPinSource(pins)).declaredSources;
       writeOnce(
         options['--out'],
-        freezeSources({ pins, declaredSources, overrides: parseOverrides(options['--overrides']), resolveHead: headResolver(env) }),
+        freezeSources({ pins, declaredSources, overrides: parseOverrides(options['--overrides']), ...headResolver(env) }),
       );
       return;
     }
-    case 'kernel-commit':
-      return customerKernelCommit(options, env);
     default:
       throw new Error(`unhandled command ${command}`);
   }

package/edition/develop-freeze.mjs

@@ -112,6 +112,7 @@ function assertCheckedOutPin({ key, sha, flag, what, overrides }) {
  * @param {string} request.kernelSha the commit the kernel checkout is at
  * @param {string} request.deploySha the commit the deploy checkout is at
  * @param {string} [request.editionsRootUrl] https URL of the editions root; absent = this repository
+ * @param {(source: {name: string, url: string}) => void} request.holdSource the hold of one source; runs for ALL graph sources before the first head
  */
 export function freezeGraph({
   runtimeSourceIndex,
@@ -121,6 +122,7 @@ export function freezeGraph({
   editionsRootUrl,
   overrides = {},
   resolveHead,
+  holdSource,
 }) {
   assertNoToolingOverride(overrides);
   assertOverrides(overrides, GRAPH_PHASE);
@@ -137,6 +139,12 @@ export function freezeGraph({
     { key: deployPinKey(), sha: deploySha, flag: '--deploy-sha', what: 'the deploy checkout' },
   ];
   for (const { key, sha, flag, what } of checkedOut) {assertCheckedOutPin({ key, sha, flag, what, overrides });}
+  const toResolve = runtimeSourceIndex.repositoryPins.map((pin) => ({ name: pin.repo, url: pin.repositoryUrl }));
+  if (editionsRootUrl !== undefined) {
+    toResolve.push({ name: EDITIONS_ROOT_PIN_KEY, url: canonicalPublicHttpsRepositoryUrl(editionsRootUrl, '--editions-root-url') });
+  }
+  // Every source is held before the first head is asked: a refusal of the last leaves no git call behind.
+  for (const source of toResolve) {holdSource(source);}
   if (editionsRootUrl === undefined && overrides[EDITIONS_ROOT_PIN_KEY] !== undefined) {
     throw new Error(`override names "${EDITIONS_ROOT_PIN_KEY}", but the editions root is this repository`);
   }
@@ -155,8 +163,9 @@ export function freezeGraph({
  * @param {object} request
  * @param {Record<string,string>} request.pins the graph phase's pins
  * @param {object[]} request.declaredSources every `sources[]` entry in the chain (`{ name, url, ... }`)
+ * @param {(source: {name: string, url: string}) => void} request.holdSource the hold of one source (`holdSource` of git-source-auth with the workspace and env); runs for ALL sources before the first head
  */
-export function freezeSources({ pins, declaredSources, overrides = {}, resolveHead }) {
+export function freezeSources({ pins, declaredSources, overrides = {}, resolveHead, holdSource }) {
   assertOverrides(overrides, SOURCE_PHASE);
   const head = memoizedHeads(resolveHead);
   const sourceByName = new Map();
@@ -172,6 +181,8 @@ export function freezeSources({ pins, declaredSources, overrides = {}, resolveHe
       throw new Error(`override names "${key}", but the chain declares no such source`);
     }
   }
+  // Every source is held before the first head is asked: a refusal of the last leaves no git call behind.
+  for (const source of sourceByName.values()) {holdSource(source);}
   const frozen = { ...pins };
   for (const [name, source] of sourceByName) {
     frozen[sourcePinKey(name)] = overrides[sourcePinKey(name)] ?? head(source);
@@ -207,11 +218,11 @@ export function assertCustomerSourceUrls(sources, sourceRepositoryUrlPrefix) {
  * each the head of refs/heads/develop of that source's repository, resolved once. Every URL is held by
  * `assertCustomerSourceUrls` before the first head is asked.
  */
-export function freezeCustomerSources({ definition, resolveHead, sourceRepositoryUrlPrefix }) {
+export function freezeCustomerSources({ definition, resolveHead, holdSource, sourceRepositoryUrlPrefix }) {
   const sources = definition?.sources ?? [];
   if (!Array.isArray(sources) || sources.some((source) => typeof source?.name !== 'string' || typeof source?.url !== 'string')) {
     throw new Error('the definition\'s sources must be an array of {name, url}');
   }
   assertCustomerSourceUrls(sources, sourceRepositoryUrlPrefix);
-  return freezeSources({ pins: {}, declaredSources: sources, resolveHead });
+  return freezeSources({ pins: {}, declaredSources: sources, resolveHead, holdSource });
 }

package/edition/dispatched-runtime-components.mjs

@@ -0,0 +1,82 @@
+import { compareStrings } from './string-order.mjs';
+
+/**
+ * The runtime components an edition must carry because a biome it rosters
+ * DISPATCHES them: the kernel's `runtime-image` edges, projected per biome into
+ * the index as `dispatchesRuntimeComponents` and followed here against the
+ * index entry of each target biome.
+ *
+ * "Needs that image" and nothing else. The target biome is NOT rostered — it is
+ * not installed, booted or required — only its runtime component's image
+ * enters the edition, as a runtime-component row of the image lock.
+ *
+ * The closure is one step by construction: the kernel admits
+ * `dispatchesRuntimeComponents` on a `service` component only, and a target is
+ * a runtime component, which is never a standing service — so a dispatched
+ * image dispatches nothing further, and an unrostered target biome's own
+ * services (and their edges) are not in the edition at all.
+ *
+ * Targets are resolved against FIRST-PARTY server entries only: the image plane
+ * reads a target's coordinates from the first-party biome index, which carries
+ * no biome drawn from a declared source. A biome drawn from a declared source
+ * that dispatches is refused for the same reason.
+ *
+ * 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.
+ *
+ * @param {string} context  the edition the refusal names, e.g. `distribution "core"`
+ * @param {object[]} consumers  the rostered index entries
+ * @param {object[]} index  the index the targets are resolved against
+ */
+export function resolveDispatchedRuntimeComponents(context, consumers, index) {
+  const rows = new Map();
+  for (const consumer of [...consumers].sort((a, b) => compareStrings(a.id, b.id))) {
+    const edges = consumer.dispatchesRuntimeComponents ?? [];
+    if (edges.length === 0) {continue;}
+    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(', ')}). ` +
+          '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) {
+      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,
+      );
+      if (candidates.length === 0) {
+        throw new Error(
+          `${context}: ${edgeText}, but the biome index has no first-party server biome "${edge.biomeId}" — ` +
+            'refusing rather than shipping the dispatcher without the image it launches.',
+        );
+      }
+      if (candidates.length > 1) {
+        throw new Error(
+          `${context}: ${edgeText}, but the biome index has ${candidates.length} first-party server biomes ` +
+            `"${edge.biomeId}" (${candidates.map((entry) => entry.repo).join(', ')}), so the target is ambiguous.`,
+        );
+      }
+      const [target] = candidates;
+      const image = (target.runtimeComponentKeys ?? {})[edge.componentKey];
+      if (image === undefined) {
+        const keys = Object.keys(target.runtimeComponentKeys ?? {});
+        throw new Error(
+          `${context}: ${edgeText}, but "${edge.biomeId}" declares no runtime component keyed ` +
+            `"${edge.componentKey}" (its runtime components: ${keys.length > 0 ? keys.join(', ') : 'none'}). ` +
+            'Either no component has that key, or it is a standing service or worker — a dispatched ' +
+            'component must be one its own biome never schedules.',
+        );
+      }
+      const key = `${target.id}\0${edge.componentKey}`;
+      const row = rows.get(key) ?? { target, componentKey: edge.componentKey, image, consumers: [] };
+      if (!row.consumers.includes(consumer.id)) {row.consumers.push(consumer.id);}
+      rows.set(key, row);
+    }
+  }
+  return [...rows.entries()]
+    .sort(([a], [b]) => compareStrings(a, b))
+    .map(([, row]) => row);
+}

package/edition/dist-check.mjs

@@ -194,6 +194,7 @@ async function checkAuthorizationLock(id, kernel, index) {
       distributionId: id,
       editionDir,
       lockBiomes: lock.biomes,
+      biomeOrigins: (await loadKernelDistributionSchemas()).biomeOriginsOfLock(lock),
       index,
       kernel,
       serialize: serializeJson,

package/edition/distribution-evidence-set.mjs

@@ -464,6 +464,7 @@ export async function resolveProducerEvidence({
   schemas,
   expectedContractAuthority,
   registryClientFactory,
+  channel,
 }) {
   assertCanonicalDistributionId(distributionId);
   assertAbsolutePath(dataRoot, 'data root');
@@ -472,7 +473,7 @@ export async function resolveProducerEvidence({
     throw new Error('the expected kernel contract authority is required');
   }
   const { distributionLock, imageLock, repositoryPins, runtimeSourceIndex } =
-    await loadValidatedLocks(distributionId, dataRoot, schemas, { editionsRoot });
+    await loadValidatedLocks(distributionId, dataRoot, schemas, { editionsRoot, channel });
   assertKernelContractAuthorityEqual(
     runtimeSourceIndex.contractAuthority,
     expectedContractAuthority,
@@ -581,6 +582,22 @@ export async function resolveProducerEvidence({
 // Statement shapes
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * The evidence channel a signer signs for: the one whose kernel-assigned ref (`EVIDENCE_CHANNEL_REFS`) is the
+ * signer's workflow ref. The kernel's policy schema ties each policy row to exactly that ref, so the signer's ref
+ * IS the channel the verifying row will state. A ref no channel owns is refused.
+ */
+export function evidenceChannelOfSigner(signer, schemas) {
+  const ref = signer?.githubWorkflow?.ref;
+  const channel = schemas.EVIDENCE_CHANNELS.find((candidate) => schemas.EVIDENCE_CHANNEL_REFS[candidate] === ref);
+  if (channel === undefined) {
+    throw new Error(
+      `the signer workflow ref "${String(ref)}" is the ref of no evidence channel (${schemas.EVIDENCE_CHANNELS.map((candidate) => `${candidate}: ${schemas.EVIDENCE_CHANNEL_REFS[candidate]}`).join(', ')})`,
+    );
+  }
+  return channel;
+}
+
 /**
  * The distribution-completeness statement: "these EXACT images, produced by
  * these EXACT bundles, are the complete image set of this edition at this
@@ -590,6 +607,7 @@ export function buildDistributionImagesStatement({
   distributionLock,
   imageLock,
   images,
+  channel,
   releaseSequence,
   releaseSourceCommit,
   runId,
@@ -599,7 +617,7 @@ export function buildDistributionImagesStatement({
   maxTtlSeconds,
   schemas,
 }) {
-  if (!schemas?.parseDistributionImagesStatement) {
+  if (!schemas?.parseDistributionImagesStatement || typeof schemas.distributionLockDigest !== 'function') {
     throw new Error('trusted kernel distribution schemas are required');
   }
   if (
@@ -664,7 +682,9 @@ export function buildDistributionImagesStatement({
     ],
     predicateType: schemas.DISTRIBUTION_IMAGES_PREDICATE_TYPE,
     predicate: {
-      schemaVersion: 1,
+      schemaVersion: 2,
+      channel,
+      lockDigest: schemas.distributionLockDigest(distributionLock),
       distributionId: imageLock.distributionId,
       distributionInputHash: distributionLock.inputHash,
       normalizedImageLockDigest: normalizedLockDigest,
@@ -706,6 +726,7 @@ export function buildDistributionImagesStatement({
  * decision that already has an owner.
  */
 export function buildImageDeliveryEntitlementStatement({
+  distributionLock,
   distributionId,
   completenessStatementDigest,
   customerId,
@@ -719,10 +740,13 @@ export function buildImageDeliveryEntitlementStatement({
   maxTtlSeconds,
   schemas,
 }) {
-  if (!schemas?.parseImageDeliveryEntitlementStatement) {
+  if (!schemas?.parseImageDeliveryEntitlementStatement || typeof schemas.distributionLockDigest !== 'function') {
     throw new Error('trusted kernel distribution schemas are required');
   }
   assertCanonicalDistributionId(distributionId);
+  if (distributionLock?.distributionId !== distributionId) {
+    throw new Error(`delivery entitlement for ${String(customerId)} requires the distribution lock of ${distributionId}`);
+  }
   const label = `delivery entitlement for ${String(customerId)}`;
   if (!SHA256_DIGEST_PATTERN.test(completenessStatementDigest ?? '')) {
     throw new Error(
@@ -751,9 +775,12 @@ export function buildImageDeliveryEntitlementStatement({
     ],
     predicateType: schemas.IMAGE_DELIVERY_ENTITLEMENT_PREDICATE_TYPE,
     predicate: {
-      schemaVersion: 1,
+      schemaVersion: 2,
       customerId,
       distributionId,
+      lockDigest: schemas.distributionLockDigest(distributionLock),
+      // Present-and-nullable: null states the lock carries no catalogue; the lock digest binds the lock either way.
+      catalogueDigest: distributionLock.catalogueDigest ?? null,
       distributionStatementDigest: completenessStatementDigest,
       mode,
       targetRegistry,

package/edition/edition-channel.mjs

@@ -2,5 +2,19 @@
 // validator (which a channel selects) and edition-constants (which imports the
 // chart-set file name) do not import each other.
 
-/** Where an edition was produced. Recorded in the descriptor's provenance; readers never branch on it. */
+/**
+ * Where an edition was produced. Recorded in the descriptor's provenance. verify-evidence selects its policy row by the
+ * descriptor's channel (a predicate channel mismatch is still refused after the signature check); lock readers require one.
+ */
 export const EditionChannel = Object.freeze({ Develop: 'develop', Release: 'release' });
+
+/**
+ * The channel of `--channel <channel>`, which must be all of `rest`; anything
+ * else is a usage error. Shared by every verb that operates on one channel.
+ */
+export function parseChannelArgs(rest) {
+  if (rest.length !== 2 || rest[0] !== '--channel' || !Object.values(EditionChannel).includes(rest[1])) {
+    throw new Error(`--channel <${Object.values(EditionChannel).join('|')}> is required and nothing else is accepted (got ${rest.length === 0 ? 'nothing' : JSON.stringify(rest.join(' '))})`);
+  }
+  return { channel: rest[1] };
+}

package/edition/edition-locks.mjs

@@ -1,15 +1,18 @@
 #!/usr/bin/env node
 // `xema edition locks <id>`: one edition's validated locks, as JSON.
 //
-// usage: xema edition locks <id> --data-root <dir> --editions-root <dir> --kernel <dir>
+// usage: xema edition locks <id> --channel <release|develop> --data-root <dir> --editions-root <dir> --kernel <dir>
 //
 // The locks are read and validated exactly as the evidence verifier reads
 // them: `images.lock.json` and `distribution.lock.json` under the kernel
 // schema, immutable coordinates only, and the image lock's kernel contract
-// authority equal to the data root's runtime image source index. A consumer
+// authority equal to the data root's runtime image source index. The
+// distribution lock is read for `--channel`: an unsealed lock on develop only,
+// a sealed one on every other channel. A consumer
 // reads this output instead of parsing or validating a lock itself.
 
 import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import { EditionChannel, parseChannelArgs } from './edition-channel.mjs';
 import {
   WorkspaceRoot,
   configureEditionWorkspaceFromArgv,
@@ -21,12 +24,12 @@ import { loadValidatedLocks } from './image-evidence.mjs';
 import { compareStrings, loadKernelDistributionSchemas, serializeJson } from './lib.mjs';
 
 const USAGE =
-  'usage: xema edition locks <id> --data-root <dir> --editions-root <dir> --kernel <dir>';
+  `usage: xema edition locks <id> --channel <${Object.values(EditionChannel).join('|')}> --data-root <dir> --editions-root <dir> --kernel <dir>`;
 
-export async function readEditionLocks({ distributionId, dataRoot: data, editionsRoot: editions, schemas }) {
+export async function readEditionLocks({ distributionId, channel, dataRoot: data, editionsRoot: editions, schemas }) {
   assertCanonicalDistributionId(distributionId);
   const { distributionLock, imageLock, repositoryPins, runtimeSourceIndex } =
-    await loadValidatedLocks(distributionId, data, schemas, { editionsRoot: editions });
+    await loadValidatedLocks(distributionId, data, schemas, { editionsRoot: editions, channel });
   return {
     schemaVersion: 1,
     distributionId,
@@ -45,14 +48,21 @@ async function main() {
     WorkspaceRoot.Editions,
     WorkspaceRoot.Kernel,
   ]);
-  if (rest.length !== 1) {
+  if (rest.length === 0 || rest[0].startsWith('--')) {
     throw new Error(USAGE);
   }
+  let channel;
+  try {
+    ({ channel } = parseChannelArgs(rest.slice(1)));
+  } catch (error) {
+    throw new Error(`${error.message}\n${USAGE}`);
+  }
   const schemas = await loadKernelDistributionSchemas();
   process.stdout.write(
     serializeJson(
       await readEditionLocks({
         distributionId: rest[0],
+        channel,
         dataRoot: dataRoot(),
         editionsRoot: editionsRoot(),
         schemas,