@xemahq/xema 0.40.3 → 0.41.1

package/edition/oras.mjs

@@ -255,7 +255,7 @@ export function prepareTrustedOras({ env = process.env, trustedDigests, notice =
 /** The default runner: the trusted oras of the configured data root, under the scrubbed environment. */
 function defaultRunner(trust = configuredOrasTrust) {
   let prepared;
-  return async (args, { stdin } = {}) => {
+  return async (args, { stdin, cwd } = {}) => {
     if (prepared === undefined) {
       prepared = prepareTrustedOras({ trustedDigests: trust() });
       process.once('exit', prepared.dispose);
@@ -263,6 +263,7 @@ function defaultRunner(trust = configuredOrasTrust) {
     try {
       return await runExecutable(prepared.path(), args, {
         input: stdin,
+        ...(cwd === undefined ? {} : { cwd }),
         env: orasEnvironment(prepared.home),
         timeoutMs: ORAS_RUN_TIMEOUT_MS,
         maxBufferBytes: ORAS_MAX_BUFFER_BYTES,
@@ -364,7 +365,7 @@ export function disposeRegistrySessions() {
 }
 
 /**
- * A read-only OCI registry client bound to ONE registry authority and ONE
+ * An OCI registry client (reads, and `attach`) bound to ONE registry authority and ONE
  * resolved credential, doing every operation with the pinned oras.
  */
 export class OrasRegistry {
@@ -456,7 +457,7 @@ export class OrasRegistry {
   }
 
   /** One oras invocation under this registry's shared empty config; returns stdout bytes. */
-  async #oras(subcommand, flags, ref) {
+  async #oras(subcommand, flags, ref, { cwd, operands = [] } = {}) {
     await this.#ensureRealmIsSameOrigin();
     const { configPath } = registrySession(this.authority);
     const args = [...subcommand, '--registry-config', configPath];
@@ -465,9 +466,9 @@ export class OrasRegistry {
       args.push('--username', this.#username, '--password-stdin');
       stdin = this.#token;
     }
-    args.push(...flags, ref);
+    args.push(...flags, ref, ...operands);
     try {
-      const out = await this.#run(args, { stdin });
+      const out = await this.#run(args, { stdin, ...(cwd === undefined ? {} : { cwd }) });
       return Buffer.isBuffer(out) ? out : Buffer.from(out ?? '');
     } catch (error) {
       throw this.#failure(ref, error);
@@ -559,6 +560,47 @@ export class OrasRegistry {
     return descriptor;
   }
 
+  /**
+   * ATTACH `files` (paths relative to `cwd`, each with its media type) as an artifact of `artifactType` that is a referrer
+   * of `subjectDigest`, under the same referrers form discover reads ({@link REFERRERS_DISTRIBUTION_SPEC}). Returns the
+   * digest of the referrer manifest oras reports. The only write this client does; the caller states every byte.
+   *
+   * @param {string} repository
+   * @param {string} subjectDigest
+   * @param {{ artifactType: string, files: {path: string, mediaType: string}[], annotations?: Record<string,string>, cwd: string }} attachment
+   */
+  async attach(repository, subjectDigest, { artifactType, files, annotations = {}, cwd }) {
+    if (!SHA256_DIGEST_PATTERN.test(subjectDigest)) {
+      throw new Error(`"${subjectDigest}" is not a canonical lowercase sha256 digest`);
+    }
+    if (typeof artifactType !== 'string' || artifactType.length === 0) {
+      throw new Error('an attach requires a non-empty artifact type');
+    }
+    if (!Array.isArray(files) || files.length === 0 || typeof cwd !== 'string' || !isAbsolute(cwd)) {
+      throw new Error('an attach requires at least one file and an absolute working directory');
+    }
+    const ref = `${this.#ref(repository)}@${subjectDigest}`;
+    const flags = ['--distribution-spec', REFERRERS_DISTRIBUTION_SPEC, '--artifact-type', artifactType];
+    for (const [key, value] of Object.entries(annotations)) {
+      flags.push('--annotation', `${key}=${value}`);
+    }
+    flags.push('--format', 'json');
+    const out = await this.#oras(['attach'], flags, ref, {
+      cwd,
+      operands: files.map((file) => `${file.path}:${file.mediaType}`),
+    });
+    let document;
+    try {
+      document = JSON.parse(out.toString('utf8'));
+    } catch (error) {
+      throw new Error(`${ref} attach did not report JSON: ${error.message}`);
+    }
+    if (!SHA256_DIGEST_PATTERN.test(document?.digest)) {
+      throw new Error(`${ref} attach reported no canonical referrer digest`);
+    }
+    return document.digest;
+  }
+
   /** Every tag of a repository; oras follows the registry's pagination. A failure throws, never an empty list. */
   async listTags(repository) {
     const ref = this.#ref(repository);

package/edition/produce-edition-catalogue-evidence.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+// The edition catalogue statement (E4): "this offering artifact's catalogue layer and lock layer are these digests, on this
+// channel", signed by the vendor's release workflow and attached to the artifact as an `oras attach` referrer.
+//
+//   xema edition evidence statement catalogue stage|accept …
+//
+// `stage` reads the artifact manifest by digest, derives the statement from its catalogue layer and lock layer and writes
+// the canonical statement into a NEW staging directory, printing the signing plan; the caller signs it (`cosign
+// attest-blob`); `accept` re-derives the statement from the same flags, refuses staged bytes that differ, verifies the
+// signed bundle with cosign against the declared signer, seals the output (built from the re-derived files, never renamed
+// from the staging) and ATTACHES statement.json and bundle.sigstore.json to the artifact digest as a referrer carrying the
+// signing workflow's commit. A customer's pinned verifier reads exactly that referrer (catalogue-evidence.mjs).
+// This module never signs and never requests an OIDC token.
+
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+
+import {
+  CATALOGUE_EVIDENCE_BUNDLE_TITLE,
+  CATALOGUE_EVIDENCE_STATEMENT_MEDIA_TYPE,
+  CATALOGUE_EVIDENCE_STATEMENT_TITLE,
+  CATALOGUE_EVIDENCE_WORKFLOW_SHA_ANNOTATION,
+} from './catalogue-evidence.mjs';
+import { layerTitled, parseCatalogueRef } from './catalogue-fetch.mjs';
+import { CATALOGUE_FILE } from './catalogue.mjs';
+import {
+  acceptSignedEvidenceStatement,
+  assertPinnedCosignVersion,
+  evidenceChannelOfSigner,
+  loadPinnedTrustPolicy,
+  parseEvidenceCliFlags,
+  stageEvidenceStatement,
+} from './distribution-evidence-set.mjs';
+import { EDITION_ARTIFACT_TYPE, EditionLockFile } from './edition-constants.mjs';
+import { WorkspaceRoot, configureEditionWorkspaceFromArgv, dataRoot, isEntryModule } from './edition-workspace.mjs';
+import { serializeJson } from './lib.mjs';
+import { EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE, createRegistryClientResolver } from './oci-image-source-evidence.mjs';
+import { githubWorkflowSigner } from './produce-distribution-completeness-evidence.mjs';
+import {
+  BUNDLE_MEDIA_TYPE,
+  assertGitHubProducerContext,
+  createCosignVerifier,
+  loadProducerKernelSchemas,
+} from './produce-image-source-evidence.mjs';
+import { assertStagedExactly, discardStaging, reserveSealing, sealAccepted } from './sealed-evidence-accept.mjs';
+
+const STATEMENT_TYPE = 'https://in-toto.io/Statement/v1';
+const hexOf = (digest) => digest.slice('sha256:'.length);
+
+const SHARED_FLAGS = Object.freeze([
+  'artifact',
+  'offering',
+  'staging',
+  'signer-repository',
+  'signer-ref',
+  'signer-workflow-path',
+  'github-repository',
+  'github-ref',
+  'github-sha',
+  'github-workflow-ref',
+]);
+
+/**
+ * The E4 statement of the offering artifact `artifact` (`oci://<repository>@sha256:<d>`), derived from the manifest the
+ * registry serves for that digest: its catalogue layer and lock layer, exactly as a customer's `fetchCatalogue` reads them.
+ * The channel is the signer's, and must be the repository's.
+ */
+export async function deriveEditionCatalogueStatement({ artifact, offeringId, signer, schemas, client }) {
+  const { repository, digest, edition } = parseCatalogueRef(artifact);
+  const channel = evidenceChannelOfSigner(signer, schemas);
+  if (edition.distributionId !== offeringId) {
+    throw new Error(`--offering ${offeringId} is not the offering of ${artifact} (its repository is the offering ${edition.distributionId})`);
+  }
+  if (edition.channel !== channel) {
+    throw new Error(`${artifact} is in a ${edition.channel} repository, but the signer signs for the ${channel} channel`);
+  }
+  const manifest = await client.getManifestByDigest(repository, digest);
+  if (manifest.isIndex || manifest.document.artifactType !== EDITION_ARTIFACT_TYPE) {
+    throw new Error(`${artifact} is not an edition artifact (artifactType ${JSON.stringify(manifest.document.artifactType)}, expected ${EDITION_ARTIFACT_TYPE})`);
+  }
+  const catalogueLayer = layerTitled(manifest, CATALOGUE_FILE, artifact);
+  const lockLayer = layerTitled(manifest, EditionLockFile.Distribution, artifact);
+  const statement = {
+    _type: STATEMENT_TYPE,
+    subject: [{ name: `xema-edition-${offeringId}`, digest: { sha256: hexOf(digest) } }],
+    predicateType: schemas.EDITION_CATALOGUE_PREDICATE_TYPE,
+    predicate: {
+      schemaVersion: 1,
+      offeringId,
+      channel,
+      catalogueDigest: catalogueLayer.digest,
+      lockDigest: hexOf(lockLayer.digest),
+    },
+  };
+  schemas.parseEditionCatalogueStatement(statement);
+  return { statement, channel, repository, subjectDigest: digest };
+}
+
+function signingOf({ derived, options }) {
+  return {
+    statement: derived.statement,
+    root: options.stagingDirectory,
+    statementPath: CATALOGUE_EVIDENCE_STATEMENT_TITLE,
+    bundlePath: CATALOGUE_EVIDENCE_BUNDLE_TITLE,
+    signer: options.signer,
+    certificateWorkflowSha: options.signingWorkflowSha,
+    predicateType: options.schemas.EDITION_CATALOGUE_PREDICATE_TYPE,
+  };
+}
+
+/** Stage the catalogue statement of an artifact for signing. Returns the signing plan and the statement. */
+export async function stageEditionCatalogueEvidence(options) {
+  const { stagingDirectory } = options;
+  if (typeof stagingDirectory !== 'string' || !isAbsolute(stagingDirectory)) {
+    throw new Error('the catalogue staging directory must be absolute');
+  }
+  if (existsSync(stagingDirectory)) {
+    throw new Error(`catalogue staging directory already exists: ${stagingDirectory}`);
+  }
+  assertGitHubProducerContext({ signer: options.signer, producerWorkflowSha: options.signingWorkflowSha }, options.githubContext);
+  const derived = await deriveEditionCatalogueStatement(options);
+  mkdirSync(stagingDirectory, { recursive: true, mode: 0o700 });
+  try {
+    const plan = stageEvidenceStatement(signingOf({ derived, options }));
+    return {
+      plan: { ...plan, kind: 'edition-catalogue', offeringId: options.offeringId, channel: derived.channel, subjectDigest: derived.subjectDigest },
+      statement: derived.statement,
+    };
+  } catch (error) {
+    rmSync(stagingDirectory, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+/**
+ * Accept the signed catalogue bundle, seal `outputDirectory` and attach its two files to the artifact digest as an
+ * `EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE` referrer. The output is BUILT from the re-derived statement and the
+ * canonicalized bundle, never renamed from the staging, which must hold exactly what stage recorded and does not outlive
+ * the accept.
+ */
+export async function acceptEditionCatalogueEvidence(options) {
+  const { outputDirectory, stagingDirectory, readCosignVersion, runCosign, client } = options;
+  if (
+    typeof outputDirectory !== 'string' ||
+    !isAbsolute(outputDirectory) ||
+    typeof stagingDirectory !== 'string' ||
+    !isAbsolute(stagingDirectory)
+  ) {
+    throw new Error('the catalogue output and staging directories must be absolute');
+  }
+  if (typeof readCosignVersion !== 'function' || typeof runCosign !== 'function') {
+    throw new Error('cosign seams are required');
+  }
+  const sealing = reserveSealing(outputDirectory, 'catalogue');
+  let derived;
+  try {
+    assertGitHubProducerContext({ signer: options.signer, producerWorkflowSha: options.signingWorkflowSha }, options.githubContext);
+    assertPinnedCosignVersion(readCosignVersion(), options.policy?.cosignVersion);
+    derived = await deriveEditionCatalogueStatement(options);
+  } catch (error) {
+    discardStaging(stagingDirectory);
+    throw error;
+  }
+  const descriptor = sealAccepted({
+    stagingDirectory,
+    sealing,
+    outputDirectory,
+    build: () => {
+      assertStagedExactly(stagingDirectory, [CATALOGUE_EVIDENCE_STATEMENT_TITLE, CATALOGUE_EVIDENCE_BUNDLE_TITLE]);
+      return acceptSignedEvidenceStatement({ ...signingOf({ derived, options }), sealingRoot: sealing, runCosign });
+    },
+  });
+  const referrerDigest = await client.attach(derived.repository, derived.subjectDigest, {
+    artifactType: EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE,
+    files: [
+      { path: descriptor.statementPath, mediaType: CATALOGUE_EVIDENCE_STATEMENT_MEDIA_TYPE },
+      { path: descriptor.bundlePath, mediaType: BUNDLE_MEDIA_TYPE },
+    ],
+    annotations: { [CATALOGUE_EVIDENCE_WORKFLOW_SHA_ANNOTATION]: options.signingWorkflowSha },
+    cwd: outputDirectory,
+  });
+  return {
+    outputDirectory,
+    statement: derived.statement,
+    channel: derived.channel,
+    subjectDigest: derived.subjectDigest,
+    referrerDigest,
+    descriptor,
+  };
+}
+
+async function main() {
+  const [phase, ...args] = configureEditionWorkspaceFromArgv(process.argv.slice(2), [WorkspaceRoot.Data, WorkspaceRoot.Kernel]);
+  if (phase !== 'stage' && phase !== 'accept') {
+    throw new Error('usage: xema edition evidence statement catalogue <stage|accept> …');
+  }
+  const flags = parseEvidenceCliFlags(args, {
+    single: phase === 'stage' ? SHARED_FLAGS : [...SHARED_FLAGS, 'output', 'cosign'],
+    repeated: [],
+  });
+  const { schemas } = await loadProducerKernelSchemas({ dataRoot: dataRoot() });
+  const artifact = flags.require('artifact');
+  const githubSha = flags.require('github-sha');
+  const { authority } = parseCatalogueRef(artifact);
+  const options = {
+    artifact,
+    offeringId: flags.require('offering'),
+    stagingDirectory: resolve(flags.require('staging')),
+    schemas,
+    policy: loadPinnedTrustPolicy({ dataRoot: dataRoot(), schemas }),
+    client: createRegistryClientResolver({ dataRoot: dataRoot() })(authority),
+    signer: githubWorkflowSigner({
+      repository: flags.require('signer-repository'),
+      ref: flags.require('signer-ref'),
+      path: flags.require('signer-workflow-path'),
+    }),
+    githubContext: {
+      repository: flags.require('github-repository'),
+      ref: flags.require('github-ref'),
+      sha: githubSha,
+      workflowRef: flags.require('github-workflow-ref'),
+    },
+    signingWorkflowSha: githubSha,
+  };
+  if (phase === 'stage') {
+    process.stdout.write(serializeJson((await stageEditionCatalogueEvidence(options)).plan));
+    return;
+  }
+  const result = await acceptEditionCatalogueEvidence({
+    ...options,
+    outputDirectory: resolve(flags.require('output')),
+    ...createCosignVerifier(resolve(flags.require('cosign'))),
+  });
+  process.stdout.write(
+    serializeJson({
+      schemaVersion: 1,
+      kind: 'edition-catalogue',
+      offeringId: options.offeringId,
+      channel: result.channel,
+      subjectDigest: result.subjectDigest,
+      referrerDigest: result.referrerDigest,
+      evidence: result.descriptor,
+    }),
+  );
+}
+
+if (isEntryModule(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`[edition-catalogue] ${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/edition/produce-image-source-evidence.mjs

@@ -36,6 +36,8 @@ import {
 } from './edition-workspace.mjs';
 import { COMMIT_PATTERN, GITHUB_REF_PATTERN, GITHUB_REPOSITORY_PATTERN, SHA256_DIGEST_PATTERN } from './evidence-grammars.mjs';
 import {
+  KERNEL_CONTRACT_AUTHORITY_NOT_PINNED_ONE,
+  KernelContractAuthorityPinError,
   RUNTIME_IMAGE_SOURCE_INDEX_FILE,
   loadPinnedDeclaredTrustPolicy,
   readEvidenceTrustPin,
@@ -50,9 +52,9 @@ import {
 import { assertKernelContractAuthorityEqual } from './kernel-contract-authority.mjs';
 import { serializeJson } from './lib.mjs';
 import { assertStagedExactly, reserveSealing, sealAccepted } from './sealed-evidence-accept.mjs';
+import { BUNDLE_MEDIA_TYPE } from './sigstore-bundle-media-type.mjs';
 
-export const BUNDLE_MEDIA_TYPE =
-  'application/vnd.dev.sigstore.bundle.v0.3+json';
+export { BUNDLE_MEDIA_TYPE };
 const STAGED_STATEMENTS_DIRECTORY = 'statements';
 const STAGED_BUNDLES_DIRECTORY = 'bundles';
 
@@ -135,6 +137,13 @@ export async function loadProducerKernelSchemas({
   }
   const expected = readRawContractAuthority(root);
   const pinned = readEvidenceTrustPin({ dataRoot: root, declaration }).kernelContractAuthority;
+  if (pinned === null) {
+    throw new KernelContractAuthorityPinError(
+      KERNEL_CONTRACT_AUTHORITY_NOT_PINNED_ONE,
+      `${RUNTIME_IMAGE_SOURCE_INDEX_FILE} at ${root} states kernel contract authority commit ${expected.sourceCommit} ` +
+        'but the evidence-trust pin records none; re-pin with `xema edition repin-evidence-trust`',
+    );
+  }
   if (expected.sourceCommit !== pinned.sourceCommit) {
     throw new Error(
       `${RUNTIME_IMAGE_SOURCE_INDEX_FILE} at ${root} states kernel contract authority commit ` +

package/edition/release-edition.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// release-edition — the customer RELEASE edition's command line: `xema edition release <verb> --definition <file>`.
+//
+// It is `xema edition develop <verb> --definition <file>` on the release channel: the same parser, the same frame
+// and the same verbs (customer-edition-verbs.mjs); only the inputs differ. The id is the definition's, and the
+// catalogue is the one pinned for `release` in catalogue.pin.json beside the definition.
+//
+//   freeze-sources --definition <file> --out <file>
+//       one `sources/<name>` pin per source the definition declares, each at the source's DECLARED ref (a branch,
+//       or a tag taken at its peeled commit); a ref that is both a branch and a tag, or missing, is refused.
+//       Written exclusively (wx).
+//   target --definition <file> --pins <file> --registry <root> --engine-image <repository>@sha256:<digest>
+//          [--source-image <source>=<registry>/<prefix>]...
+//       print <root>/<release segment>/xema-edition-<id>:<tag>, the tag being snapshotEditionTag of the CLI
+//       version, the engine image, the pins and the source-image map (as on develop).
+//   check-existing --definition <file> --pins <file> --artifact <dir> --engine-image <repository>@sha256:<digest>
+//                  [--catalogue-username <name> --catalogue-token-env <VAR>] [--source-image <source>=<registry>/<prefix>]...
+//       refuse to reuse a pulled artifact whose descriptor disagrees with this snapshot.
+//   resolve --definition <file> --pins <file> --out <dir> --registry <root> --engine-image <repository>@sha256:<digest>
+//           [--source-image <source>=<registry>/<prefix>]... [--catalogue-username <name> --catalogue-token-env <VAR>] [--local]
+//       resolve the edition against the pinned release catalogue, seal the customer's own image rows at the digests
+//       the registry serves for `<repository>:<contentHash>` (it never builds an image), and write the descriptor and
+//       the four locks to <dir>.
+//
+// `resolve` and `check-existing` read the release catalogue only after its signed E4 evidence verified against the
+// CUSTOMER's own evidence trust policy (catalogue-evidence.mjs), and require that policy armed on the release channel.
+// Until the E4 referrer layout lands, no catalogue verifies and both refuse. Takes the roots of the
+// develop customer form (--data-root, --editions-root, --sources-root, --cache-dir per verb), never the kernel.
+
+import { customerRootsOf, parseEditionVerbArgs, runCustomerVerb } from './customer-edition-verbs.mjs';
+import { EditionChannel } from './edition-constants.mjs';
+import { configureEditionWorkspaceFromProcess, isEntryModule } from './edition-workspace.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  const [command] = process.argv.slice(2);
+  try {
+    configureEditionWorkspaceFromProcess(customerRootsOf(command), { refuseOthers: true });
+  } catch (error) {
+    console.error(`[release-edition] ${error.message}`);
+    process.exit(1);
+  }
+}
+
+async function run(argv, env) {
+  const { command, options } = parseEditionVerbArgs(EditionChannel.Release, argv);
+  await runCustomerVerb({ channel: EditionChannel.Release, command, options, env });
+}
+
+if (isEntryModule(import.meta.url)) {
+  run(process.argv.slice(2), process.env).catch((error) => {
+    console.error(`[release-edition] ${error.message}`);
+    process.exit(1);
+  });
+}

package/edition/repin-evidence-trust.mjs

@@ -2,8 +2,9 @@
 // `xema edition repin-evidence-trust` - write the data root's evidence trust
 // pin: the digest of the declared policy, the digests of THIS CLI's built
 // verifier bundle and provenance, the kernel contract authority the data
-// root's runtime image source index states, and the oras binaries that may
-// read a registry. The result is a data-root change to review; nothing here is
+// root's runtime image source index states (a customer data root has no such
+// index: the pin then records none and pins only what exists), and the oras
+// binaries that may read a registry. The result is a data-root change to review; nothing here is
 // generated into the library.
 //
 //   [--trusted-oras-digest sha256:<64 hex>]…   the oras binaries to trust. Without
@@ -24,6 +25,7 @@ import {
 } from './edition-workspace.mjs';
 import {
   loadDeclaredTrustPolicy,
+  hasRuntimeImageSourceIndex,
   readEvidenceTrustPin,
   readStatedKernelContractAuthority,
   requireOrasDigests,
@@ -62,7 +64,7 @@ export async function repinEvidenceTrust({
     declaration,
     policyDigest,
     verifier,
-    kernelContractAuthority: readStatedKernelContractAuthority({ dataRoot: root, schemas }),
+    kernelContractAuthority: hasRuntimeImageSourceIndex(root) ? readStatedKernelContractAuthority({ dataRoot: root, schemas }) : null,
     trustedOrasBinaryDigests: orasDigests,
   });
 }

package/edition/resolve-images.mjs

@@ -40,7 +40,10 @@ import { setImmediate as yieldToEventLoop } from 'node:timers/promises';
 import { assertBuildLedgerComplete } from './build-ledger-completeness.mjs';
 import { BUILD_LEDGER_FILE, readBuildLedger } from './build-ledger.mjs';
 import { CROSS_REPO_BUILD_INPUTS_PATH, crossRepoInputKey, resolveCrossRepoVendoredInputs } from './cross-repo-build-inputs.mjs';
-import { resolveDispatchedRuntimeComponents } from './dispatched-runtime-components.mjs';
+import {
+  resolveDispatchedRuntimeComponents,
+  UndeclaredSupplementalRuntimeComponentError,
+} from './dispatched-runtime-components.mjs';
 import {
   assertCanonicalDistributionId,
   distributionOutputPath,
@@ -681,6 +684,28 @@ export function resolveImageStructure(
     dispatchers,
     biomeIndex,
   )) {
+    if (dispatched.supplementalRuntimeComponentId !== undefined) {
+      // THE REFUSAL: a dispatched supplemental runtime component must be one the
+      // runtime image source index declares as a runtime-component subject.
+      // Every image lock is produced here, so this is the one place it is checked.
+      const declared = runtimeSourceIndex.supplementalSubjects.find(
+        (subject) =>
+          subject.kind === enums.RuntimeImageSubjectKind.RuntimeComponent &&
+          subject.id === dispatched.supplementalRuntimeComponentId,
+      );
+      if (declared === undefined) {
+        throw new UndeclaredSupplementalRuntimeComponentError(
+          dispatched.supplementalRuntimeComponentId,
+          dispatched.consumers,
+          `distribution "${lock.distributionId}"`,
+        );
+      }
+      addSupplementalSubject(
+        declared,
+        dispatched.consumers.map((biomeId) => ({ kind: enums.RuntimeImageOwnerKind.Biome, biomeId })),
+      );
+      continue;
+    }
     const { target } = dispatched;
     addSubject(subjects, {
       kind: enums.RuntimeImageSubjectKind.RuntimeComponent,
@@ -717,6 +742,16 @@ export function resolveImageStructure(
   const boundSubjects = new Set(
     runtimeSourceIndex.platformServiceBindings.map((binding) => bindingKey(binding)),
   );
+  // A biome's `supplemental:<id>` dispatch edge also carries the subject: the
+  // catalogue check reads the whole first-party index, not this roster, so a
+  // subject reached only by a dispatch is not "unreachable" in any edition.
+  const dispatchedSubjects = new Set(
+    biomeIndex
+      .filter((entry) => entry.source === undefined)
+      .flatMap((entry) => entry.dispatchesRuntimeComponents ?? [])
+      .filter((edge) => edge.supplementalRuntimeComponentId !== undefined)
+      .map((edge) => `${enums.RuntimeImageSubjectKind.RuntimeComponent}\0${edge.supplementalRuntimeComponentId}`),
+  );
   const launchers = new Map(
     supplementalSources
       .filter((source) => source.launchedBy !== undefined)
@@ -733,11 +768,11 @@ export function resolveImageStructure(
   for (const [key, supplemental] of supplementalSubjects) {
     const launcher = launchers.get(key);
     if (launcher === undefined) {
-      if (!boundSubjects.has(key)) {
+      if (!boundSubjects.has(key) && !dispatchedSubjects.has(key)) {
         throw new Error(
-          `supplemental subject "${supplemental.kind}:${supplemental.id}" has neither a launchedBy nor a ` +
-            'platform-service binding, so no edition could ever carry it — declare what launches it ' +
-            '(runtimeImageSources.supplementalSources[].launchedBy) or bind it to a platform service',
+          `supplemental subject "${supplemental.kind}:${supplemental.id}" has neither a launchedBy, a ` +
+            'platform-service binding nor a biome dispatching it, so no edition could ever carry it — declare what launches it ' +
+            '(runtimeImageSources.supplementalSources[].launchedBy), bind it to a platform service or dispatch it from a biome',
         );
       }
       continue;

package/edition/sigstore-bundle-media-type.mjs

@@ -0,0 +1,4 @@
+// The one Sigstore bundle media type this plane stores. Its own module because the evidence verifier bundle needs it and
+// must not import a producer entry (every module of a bundle shares one `import.meta.url`, so a producer's entry guard
+// would run inside the verifier).
+export const BUNDLE_MEDIA_TYPE = 'application/vnd.dev.sigstore.bundle.v0.3+json';

package/edition/trust-policy-arming.mjs

@@ -21,6 +21,11 @@
 //   trustedGitBinaryDigests     -> same, for the git binary that pins the
 //                                 graded checkouts.
 //
+// THE REQUIRED RELEASE ROWS ARE ONE RULE: the edition-catalogue (E4) predicate iff the edition consumes a catalogue
+// (`consumesCatalogue`: a customer edition does, a vendor edition does not), plus the image producer, distribution
+// completeness and delivery entitlement predicates. The same function judges the data root before the catalogue's
+// kernel is adopted (inside the pinned verifier bundle, with its own embedded kernel) and after it (descriptorEvidenceTrust).
+//
 // The three predicate types are checked separately because a policy can be
 // non-empty and still be unarmed for a stage: the verifier resolves candidates
 // per predicate type, so authorizing only the producer identity leaves the
@@ -60,7 +65,7 @@ export function assertArmingChannel(schemas, channel) {
  * field and what makes verification impossible, so the failure is actionable
  * without reading the verifier.
  */
-export function assessTrustPolicyArming(policy, schemas, channel) {
+export function assessTrustPolicyArming(policy, schemas, channel, { consumesCatalogue = false } = {}) {
   assertArmingChannel(schemas, channel);
   const unmet = [];
   const stages = [
@@ -68,6 +73,14 @@ export function assessTrustPolicyArming(policy, schemas, channel) {
     ['distribution-completeness', schemas.DISTRIBUTION_IMAGES_PREDICATE_TYPE],
     ['delivery-entitlement', schemas.IMAGE_DELIVERY_ENTITLEMENT_PREDICATE_TYPE],
   ];
+  if (consumesCatalogue) {
+    // A kernel that states no E4 predicate cannot arm a catalogue consumer: an unmet entry, never a skip.
+    if (typeof schemas.EDITION_CATALOGUE_PREDICATE_TYPE !== 'string') {
+      unmet.push('this kernel states no edition-catalogue predicate (EDITION_CATALOGUE_PREDICATE_TYPE), so a catalogue consumer cannot be armed against it.');
+    } else {
+      stages.push(['edition-catalogue', schemas.EDITION_CATALOGUE_PREDICATE_TYPE]);
+    }
+  }
   const onChannel = policy.policies.filter((candidate) => candidate.channel === channel);
   const authorized = stages.filter(([, predicateType]) => onChannel.some((candidate) => candidate.predicateTypes.includes(predicateType)));