@xemahq/xema 0.40.3 → 0.41.0

package/edition/customer-edition-verbs.mjs

@@ -0,0 +1,477 @@
+// customer-edition-verbs — the verbs of a CUSTOMER edition, for either channel.
+//
+//   xema edition develop <verb> --definition <file> ...    channel develop
+//   xema edition release <verb> --definition <file> ...    channel release
+//
+// ONE parser, ONE frame and ONE set of verbs: the channel is an input, never a mode. A customer
+// definition is resolved against the catalogue pinned for the channel in catalogue.pin.json beside
+// it, frozen at the customer's OWN repository pins. The pins file holds one `sources/<name>` commit
+// per source the definition declares and nothing else (the vendor repositories are the catalogue's,
+// not the customer's). The digest of the catalogue artifact the edition was resolved against is
+// frozen into the descriptor's provenance pins as `catalogue`; the artifact tag (snapshotEditionTag)
+// covers it. The vendor image rows arrive sealed from the catalogue; only the customer's own image
+// rows are sealed, in the repositories of the channel (edition-image-seal.mjs).
+
+import { writeFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+
+import { sealLock } from './biome-content.mjs';
+import { assertCatalogueConsumerArmed } from './catalogue-evidence.mjs';
+import { fetchCatalogue, parseCatalogueRef } from './catalogue-fetch.mjs';
+import { readCataloguePin } from './catalogue-pin.mjs';
+import { CATALOGUE_TOKEN_ENV_FLAG, CATALOGUE_USERNAME_FLAG, COSIGN_FLAG, DEFINITION_FLAG, SOURCE_IMAGE_FLAG } from './customer-flags.mjs';
+import { freezeCustomerSources, lsRemoteRef } from './develop-freeze.mjs';
+import { isDevelopImageRef } from './develop-image-coordinate.mjs';
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import { LOCAL_WORKFLOW, assertEngineImage, assertExistingArtifactMatches, snapshotEditionTarget, workflowFromEnv, writeEditionArtifact } from './edition-artifact.mjs';
+import { editionWorkspaceConfig } from './edition-config.mjs';
+import { CATALOGUE_PIN_KEY, DEFINITION_PIN_KEY, EditionChannel, EditionLockFile } from './edition-constants.mjs';
+import { channelImageRef, sealImageSubjects } from './edition-image-seal.mjs';
+import { WorkspaceRoot } from './edition-workspace.mjs';
+import { descriptorEvidenceTrust } from './evidence-trust-policy.mjs';
+import { holdSource } from './git-source-auth.mjs';
+import { canonicalJson, sha256Digest } from './image-evidence.mjs';
+import { adoptCatalogueKernel } from './kernel-package.mjs';
+import { loadKernelDistributionSchemas, serializeJson } from './lib.mjs';
+import { isSourcePinKey, sortedSnapshotPins, sourcePinKey } from './pin-source.mjs';
+import { assertSealedImageLock } from './release-edition-artifact.mjs';
+import { assertSourceImagesCoverDefinition, parseSourceImages, resolveCustomerEdition } from './resolve-customer-edition.mjs';
+import { externalSourceTrees, imageRefForSubject, sourceTreeLocator } from './resolve-images.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+
+export class CustomerEditionPinsError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CustomerEditionPinsError';
+  }
+}
+
+/**
+ * The digest of a customer definition: sha256 of its canonical JSON (keys sorted). It covers everything the definition
+ * decides that no other pin fixes: the vendor biomes it selects, its image registry mirror, its Store publisher anchor
+ * keys and its declared sources.
+ */
+export function customerDefinitionDigest(rawDefinition) {
+  return sha256Digest(Buffer.from(canonicalJson(rawDefinition), 'utf8'));
+}
+
+/**
+ * The pins of a customer edition of `channel`: `sources/<name>` commits for exactly
+ * the definition's declared sources, plus `catalogue` = the digest of the
+ * catalogue artifact and `definition` = the digest of the definition (customerDefinitionDigest).
+ * A `catalogue` or `definition` entry in the file must equal that digest.
+ */
+export function customerEditionPins({ channel, pins, declaredSourceNames, catalogueDigest, definitionDigest }) {
+  if (typeof definitionDigest !== 'string') {throw new CustomerEditionPinsError('a customer edition pins the digest of its definition');}
+  if (pins === null || typeof pins !== 'object' || Array.isArray(pins)) {
+    throw new CustomerEditionPinsError('--pins must be an object mapping sources/<name> -> 40-hex commit');
+  }
+  const own = {};
+  for (const [key, value] of Object.entries(pins)) {
+    if (key === CATALOGUE_PIN_KEY) {
+      if (value !== catalogueDigest) {
+        throw new CustomerEditionPinsError(`--pins "${CATALOGUE_PIN_KEY}" is ${JSON.stringify(value)}, but the pinned ${channel} catalogue is ${catalogueDigest}`);
+      }
+      continue;
+    }
+    if (key === DEFINITION_PIN_KEY) {
+      if (value !== definitionDigest) {
+        throw new CustomerEditionPinsError(`--pins "${DEFINITION_PIN_KEY}" is ${JSON.stringify(value)}, but the definition is ${definitionDigest}`);
+      }
+      continue;
+    }
+    if (!isSourcePinKey(key)) {
+      throw new CustomerEditionPinsError(`--pins "${key}" is not one of the customer's own repositories: a customer ${channel} pins only sources/<name> (the vendor's pins are the catalogue's)`);
+    }
+    if (typeof value !== 'string' || !SHA_PATTERN.test(value)) {
+      throw new CustomerEditionPinsError(`--pins "${key}" is not a 40-hex commit SHA: ${JSON.stringify(value)}`);
+    }
+    own[key] = value;
+  }
+  const declared = new Set(declaredSourceNames.map(sourcePinKey));
+  for (const key of declared) {
+    if (!(key in own)) {throw new CustomerEditionPinsError(`--pins is missing "${key}": the definition declares that source`);}
+  }
+  for (const key of Object.keys(own)) {
+    if (!declared.has(key)) {throw new CustomerEditionPinsError(`--pins names "${key}", but the definition declares no such source`);}
+  }
+  return sortedSnapshotPins({ ...own, [CATALOGUE_PIN_KEY]: catalogueDigest, [DEFINITION_PIN_KEY]: definitionDigest });
+}
+
+/** The source names a raw definition declares (the pins are checked before the definition is composed). */
+export function declaredSourceNamesOf(rawDefinition) {
+  const sources = rawDefinition?.sources;
+  return Array.isArray(sources) ? sources.map((source) => source?.name) : [];
+}
+
+/** Resolve and seal the customer edition of `channel`; returns the four locks and the frozen provenance pins. */
+export async function resolveCustomerChannelEdition({ channel, rawDefinition, catalogue, catalogueDigest, pins, sourceImages, env = process.env, sealOptions = {}, adoptKernel, materialize }) {
+  const frozen = customerEditionPins({ channel, pins, declaredSourceNames: declaredSourceNamesOf(rawDefinition), catalogueDigest, definitionDigest: customerDefinitionDigest(rawDefinition) });
+  const resolved = await resolveCustomerEdition({
+    rawDefinition,
+    catalogue,
+    channel,
+    sourceImages,
+    pins: frozen,
+    catalogueDigest,
+    ...(adoptKernel === undefined ? {} : { adoptKernel }),
+    ...(materialize === undefined ? {} : { materialize }),
+    sealOwn: ({ distributionId, subjects }) => sealImageSubjects({ channel, distributionId, subjects, env, ...sealOptions }),
+  });
+  // The customer edition is sealed here: every biomeContentHash is recomputed through the
+  // same code as the vendor's, vendor biomes on the CATALOGUE's authority (biome-content.mjs).
+  const schemas = await loadKernelDistributionSchemas();
+  const distributionLock = await sealLock({
+    schemas,
+    unsealed: resolved.distributionLock,
+    imageLock: resolved.imageLock,
+    locate: sourceTreeLocator(externalSourceTrees(resolved.distributionLock)),
+    vendoredCommit: (repo) => {
+      throw new Error(`customer biome source "${repo}" is first-party to no checkout; vendor biomes are taken from the catalogue`);
+    },
+    catalogue,
+    catalogueDigest,
+    storePublisherAnchorKeys: resolved.storePublisherAnchorKeys,
+  });
+  return { ...resolved, distributionLock, pins: frozen };
+}
+
+/**
+ * What a verb of a customer edition of `channel` derives from its definition file and its `--pins` file with no
+ * network: the id (the definition's), the pinned catalogue reference and digest, and the frozen
+ * provenance pins (the customer's `sources/<name>` commits plus that digest).
+ */
+export function customerEditionFrame({ channel, definitionFile, pinsFile }) {
+  const rawDefinition = readStrictJsonFile(definitionFile);
+  assertCanonicalDistributionId(rawDefinition?.id);
+  const catalogueRef = readCataloguePin({ definitionFile, channel });
+  const { digest } = parseCatalogueRef(catalogueRef);
+  const definitionDigest = customerDefinitionDigest(rawDefinition);
+  const pins = customerEditionPins({ channel, pins: readStrictJsonFile(pinsFile), declaredSourceNames: declaredSourceNamesOf(rawDefinition), catalogueDigest: digest, definitionDigest });
+  return { id: rawDefinition.id, rawDefinition, catalogueRef, catalogueDigest: digest, definitionDigest, pins };
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// The command line: one grammar for both channels.
+// ---------------------------------------------------------------------------------------------------------------
+
+/** The roots a verb takes in its customer form. The kernel is never one: the catalogue's kernel is downloaded from npm into the cache root. */
+export 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],
+});
+
+/** The roots of a customer verb; an unknown verb is refused naming the verbs there are. */
+export function customerRootsOf(command) {
+  const roots = CUSTOMER_ROOTS[command];
+  if (roots === undefined) {
+    throw new Error(`unknown command ${JSON.stringify(command)}; expected ${Object.keys(CUSTOMER_ROOTS).join(' | ')}`);
+  }
+  return roots;
+}
+
+// Per verb: the vendor form (`positional` id, `values`, `switches`; develop only) 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, COSIGN_FLAG], required: ['--pins', '--out', '--registry', '--engine-image'], refused: [], cosign: true },
+  },
+  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'] },
+  },
+  coverage: {
+    positional: true,
+    values: ['--pins', '--cosign'],
+    switches: ['--json'],
+    required: ['--pins', '--cosign'],
+  },
+  '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, COSIGN_FLAG], required: ['--pins', '--artifact', '--engine-image'], refused: [], cosign: true },
+  },
+});
+
+/**
+ * The verbs of a channel. Develop has the vendor form of every verb as well as the customer form; a release edition
+ * is a customer edition only (the vendor release is `xema edition artifact`), so release has the customer verbs.
+ */
+function commandsOf(channel) {
+  if (channel === EditionChannel.Develop) {return COMMANDS;}
+  if (channel === EditionChannel.Release) {
+    return Object.fromEntries(Object.entries(COMMANDS).filter(([, spec]) => spec.customer !== undefined));
+  }
+  throw new Error(`unknown edition channel ${JSON.stringify(channel)}`);
+}
+
+/** Parse `<command> [<id>] --flag value ...` of `channel` against the closed vocabulary of the command. */
+export function parseEditionVerbArgs(channel, argv) {
+  const commands = commandsOf(channel);
+  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);
+  // `--cosign` of a customer form verifies a release catalogue; a vendor verb (develop `coverage`) takes its own `--cosign`.
+  if (spec.customer?.cosign === true && options[COSIGN_FLAG] !== undefined && channel !== EditionChannel.Release) {
+    throw new Error(`${COSIGN_FLAG} verifies a release catalogue's evidence; a ${channel} ${command} takes none`);
+  }
+  if (channel === EditionChannel.Release && options[DEFINITION_FLAG] === undefined) {
+    throw new Error(`a ${channel} ${command} requires ${DEFINITION_FLAG}`);
+  }
+  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`);}
+    if (spec.customer.cosign === true && channel === EditionChannel.Release) {
+      if (options[COSIGN_FLAG] === undefined) {throw new Error(`a release ${command} requires ${COSIGN_FLAG} <absolute path of the cosign binary>`);}
+      if (!isAbsolute(options[COSIGN_FLAG])) {throw new Error(`${COSIGN_FLAG} must be an absolute path, got ${JSON.stringify(options[COSIGN_FLAG])}`);}
+    }
+  } 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 };
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// The verbs.
+// ---------------------------------------------------------------------------------------------------------------
+
+/** The ref a channel freezes a source at: develop the `develop` branch of every repository, release the ref the source declares. */
+const FREEZE_REF = Object.freeze({
+  [EditionChannel.Develop]: () => 'develop',
+  [EditionChannel.Release]: (source) => source.ref,
+});
+
+/** The head lookup and the hold of one source, for the freeze of `channel`. */
+export function headResolver(channel, env) {
+  const workspace = editionWorkspaceConfig();
+  return {
+    resolveHead: (source) => lsRemoteRef(source, FREEZE_REF[channel](source), { channel, workspace, env }),
+    holdSource: (source) => holdSource(source, workspace, env),
+  };
+}
+
+/**
+ * The pinned catalogue of a customer definition on `channel`, fetched by its digest. A release edition is resolved only
+ * under the CUSTOMER's own evidence trust policy (its data root's, never the vendor's): before any registry call the policy
+ * must be declared, the built verifier must be the pinned one, and the policy ARMED on the release channel with the E4 row
+ * (`assertCatalogueConsumerArmed`, the one arming rule judged by the pinned bundle with its own kernel). The catalogue's E4
+ * evidence is then verified before the catalogue is parsed (`fetchCatalogue`).
+ */
+async function fetchPinnedCatalogue(channel, options, env, fetch = fetchCatalogue, { assertArmed = assertCatalogueConsumerArmed, locateVerifier } = {}) {
+  if (channel === EditionChannel.Release) {assertArmed({ channel, ...(locateVerifier === undefined ? {} : { locateVerifier }) });}
+  return fetch({
+    ref: readCataloguePin({ definitionFile: options[DEFINITION_FLAG], channel }),
+    channel,
+    username: options[CATALOGUE_USERNAME_FLAG],
+    tokenEnv: options[CATALOGUE_TOKEN_ENV_FLAG],
+    env,
+    cosign: options[COSIGN_FLAG],
+    ...(locateVerifier === undefined ? {} : { locateVerifier }),
+  });
+}
+
+/** A customer resolve: the artifact (descriptor and four locks, no catalogue: it is not an offering) goes to --out. */
+async function resolveCustomer(channel, options, env) {
+  const { catalogue, digest } = await fetchPinnedCatalogue(channel, options, env);
+  const rawDefinition = readStrictJsonFile(options[DEFINITION_FLAG]);
+  const sourceImages = customerSourceImages(options, rawDefinition);
+  // 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 resolveCustomerChannelEdition({
+    channel,
+    rawDefinition,
+    catalogue,
+    catalogueDigest: digest,
+    pins: readStrictJsonFile(options['--pins']),
+    sourceImages,
+    env,
+  });
+  const evidenceTrustPolicy = await descriptorEvidenceTrust({ channel, consumesCatalogue: true });
+  const target = snapshotEditionTarget(channel, id, pins, { registry: options['--registry'], engineImage: options['--engine-image'], sourceImages });
+  // A release edition is admitted only sealed: every image names the digest the registry serves. (A develop edition is not held to it today.)
+  if (channel === EditionChannel.Release) {assertSealedImageLock(resolved.imageLock, `the images lock of "${id}"`);}
+  writeEditionArtifact({
+    outDir: resolve(options['--out']),
+    channel,
+    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(channel, options, env, { adopt = adoptCatalogueKernel, fetch = fetchCatalogue, locateVerifier, assertArmed } = {}) {
+  const frame = customerEditionFrame({ channel, definitionFile: options[DEFINITION_FLAG], pinsFile: options['--pins'] });
+  const sourceImages = customerSourceImages(options, frame.rawDefinition);
+  const { catalogue, digest } = await fetchPinnedCatalogue(channel, options, env, fetch, { assertArmed, locateVerifier });
+  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,
+    evidenceTrustPolicy: await descriptorEvidenceTrust({ channel, locateVerifier, consumesCatalogue: true }),
+    pins: frame.pins,
+    engineImage: options['--engine-image'],
+    catalogueDigest: frame.catalogueDigest,
+    definitionDigest: frame.definitionDigest,
+  });
+  assertOwnImageRowsMatch({ channel, artifactDir: resolve(options['--artifact']), sourceImages });
+}
+
+/**
+ * The parsed --source-image map of a customer verb, covering exactly the definition's declared sources. Every entry
+ * names RELEASE repositories on either channel: a develop edition maps them to the develop namespace itself
+ * (developImageRef), and a release edition seals them as they are, so an entry already in the develop namespace is
+ * refused here (a release edition would otherwise seal develop images).
+ */
+export function customerSourceImages(options, rawDefinition) {
+  const sourceImages = parseSourceImages(options[SOURCE_IMAGE_FLAG] ?? []);
+  assertSourceImagesCoverDefinition(rawDefinition, sourceImages);
+  for (const [name, { imageRegistry, imageNamePrefix }] of sourceImages) {
+    if (isDevelopImageRef(imageRefForSubject('probe', imageRegistry, imageNamePrefix))) {
+      throw new Error(
+        `--source-image ${name}=${imageRegistry}/${imageNamePrefix} names the develop image namespace; ` +
+          'a --source-image names the release repositories (a develop edition maps them to develop itself)',
+      );
+    }
+  }
+  return sourceImages;
+}
+
+/**
+ * The own image rows of an existing customer artifact of `channel` are the rows this `--source-image` map composes:
+ * every subject owned by a biome drawn from a declared source is `<registry>/<prefix><subject>` mapped to its
+ * repository on the channel. The tag covers the map, but a tag is mutable registry state, so the pulled bytes are
+ * compared too. Throws naming the first row that differs.
+ */
+export function assertOwnImageRowsMatch({ channel, artifactDir, sourceImages }) {
+  const lock = readStrictJsonFile(join(artifactDir, EditionLockFile.Distribution));
+  const imageLock = readStrictJsonFile(join(artifactDir, EditionLockFile.Images));
+  const sourceOf = new Map((lock.biomes ?? []).filter((biome) => biome.source !== undefined).map((biome) => [biome.id, biome.source.name]));
+  for (const subject of imageLock.subjects ?? []) {
+    const biomeId = (subject.owners ?? []).find((owner) => sourceOf.has(owner.biomeId))?.biomeId;
+    if (biomeId === undefined) {continue;}
+    const name = sourceOf.get(biomeId);
+    const image = sourceImages.get(name);
+    if (image === undefined) {
+      throw new Error(`the existing artifact draws biome "${biomeId}" from source "${name}", which has no --source-image; refusing to reuse it`);
+    }
+    const expected = channelImageRef(channel, imageRefForSubject(subject.id, image.imageRegistry, image.imageNamePrefix));
+    if (subject.imageRef !== expected) {
+      throw new Error(
+        `the existing artifact's own image row ${subject.kind}:${subject.id} is ${subject.imageRef}, not ${expected} ` +
+          '(the --source-image map differs); refusing to reuse it',
+      );
+    }
+  }
+}
+
+/** Write a file exclusively (wx): a second run over the same path is refused. */
+export function writeOnce(path, value) {
+  writeFileSync(path, serializeJson(value), { flag: 'wx' });
+}
+
+/** Run one verb in its customer form on `channel`. */
+export async function runCustomerVerb({ channel, command, options, env }) {
+  switch (command) {
+    case 'target': {
+      const frame = customerEditionFrame({ channel, definitionFile: options[DEFINITION_FLAG], pinsFile: options['--pins'] });
+      const sourceImages = customerSourceImages(options, frame.rawDefinition);
+      console.log(snapshotEditionTarget(channel, frame.id, frame.pins, { registry: options['--registry'], engineImage: options['--engine-image'], sourceImages }));
+      return;
+    }
+    case 'resolve':
+      return resolveCustomer(channel, options, env);
+    case 'check-existing':
+      return checkExistingCustomer(channel, options, env);
+    case 'freeze-sources':
+      writeOnce(
+        options['--out'],
+        freezeCustomerSources({
+          definition: readStrictJsonFile(options[DEFINITION_FLAG]),
+          ...headResolver(channel, env),
+          sourceRepositoryUrlPrefix: editionWorkspaceConfig().sourceRepositoryUrlPrefix,
+        }),
+      );
+      return;
+    default:
+      throw new Error(`${command} has no customer form`);
+  }
+}

package/edition/customer-flags.mjs

@@ -4,3 +4,5 @@ export const CHANNEL_FLAG = '--channel';
 export const SOURCE_IMAGE_FLAG = '--source-image';
 export const CATALOGUE_USERNAME_FLAG = '--catalogue-username';
 export const CATALOGUE_TOKEN_ENV_FLAG = '--catalogue-token-env';
+/** The absolute path of the cosign binary that verifies a release catalogue's E4 evidence (release only). */
+export const COSIGN_FLAG = '--cosign';