@xemahq/xema 0.59.1 → 0.60.1

package/edition/customer-edition-verbs.mjs

@@ -1,617 +0,0 @@
-// 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 { customerLockCatalogueField } from './catalogue-lock-field.mjs';
-import { readCataloguePin } from './catalogue-pin.mjs';
-import { CATALOGUE_TOKEN_ENV_FLAG, CATALOGUE_USERNAME_FLAG, COSIGN_FLAG, DEFINITION_AT_FLAG, DEFINITION_FLAG, OFFERING_FLAG, OFFERING_PREVIOUS_LOCK_FLAG, OFFERING_PREVIOUS_LOCK_SHA256_FLAG, SOURCE_IMAGE_FLAG } from './customer-flags.mjs';
-import { freezeCustomerSources, lsRemoteRef } from './develop-freeze.mjs';
-import { customerDevelopGitBundleVerifier } from './develop-git-bundles.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, CustomerPinForm, DEFINITION_PIN_KEY, EditionChannel, EditionKind, EditionLockFile, customerPinFormAdmitted } 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 { GitSourcedBundle } from './locked-bundle-signer.mjs';
-import { isSourcePinKey, sortedSnapshotPins, sourcePinKey } from './pin-source.mjs';
-import { PREVIOUS_SEAL_SIGNER_FLAG } from './previous-seal-registry.mjs';
-import { assertSealedImageLock } from './release-edition-artifact.mjs';
-import { assertSourceImagesCoverDefinition, parseSourceImages, resolveCustomerEdition } from './resolve-customer-edition.mjs';
-import { externalSourceTrees, imageRefForSubject, resolvePreviousSeal, 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, vendorPins }) {
-  const catalogueFree = vendorPins !== undefined;
-  if (catalogueFree && !customerPinFormAdmitted(CustomerPinForm.CatalogueFree, EditionKind.Resolved, channel)) {
-    throw new CustomerEditionPinsError(`a ${channel} customer edition is never resolved catalogue-free`);
-  }
-  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 (catalogueFree) {throw new CustomerEditionPinsError(`--pins names "${CATALOGUE_PIN_KEY}", but a catalogue-free edition pins no catalogue: the catalogue's digest goes into the distribution lock only`);}
-      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`);}
-  }
-  if (!catalogueFree) {return sortedSnapshotPins({ ...own, [CATALOGUE_PIN_KEY]: catalogueDigest, [DEFINITION_PIN_KEY]: definitionDigest });}
-  for (const key of Object.keys(vendorPins)) {
-    if (key === CATALOGUE_PIN_KEY || key === DEFINITION_PIN_KEY || key in own) {
-      throw new CustomerEditionPinsError(`the vendor pins of a catalogue-free edition name "${key}", which is the customer's own`);
-    }
-  }
-  return sortedSnapshotPins({ ...vendorPins, ...own, [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. The pin form
- * decides the lock's catalogue field: catalogue-free (`vendorPins`) records `catalogueContentDigest`, the catalogue form
- * `catalogueDigest`. `previousSeal(id)` answers the customer's own previous seal (resolvePreviousSeal; absent: a first seal).
- */
-export async function resolveCustomerChannelEdition({ channel, rawDefinition, catalogue, catalogueDigest, catalogueContentDigest, pins, vendorPins, previousSeal, sourceImages, env = process.env, sealOptions = {}, adoptKernel, materialize, developGitBundles }) {
-  const catalogueField = customerLockCatalogueField({ catalogueFree: vendorPins !== undefined, catalogueDigest, catalogueContentDigest }, { what: `a ${channel} customer resolve`, ErrorType: CustomerEditionPinsError });
-  const frozen = customerEditionPins({ channel, pins, declaredSourceNames: declaredSourceNamesOf(rawDefinition), catalogueDigest, definitionDigest: customerDefinitionDigest(rawDefinition), ...(vendorPins === undefined ? {} : { vendorPins }) });
-  const resolved = await resolveCustomerEdition({
-    rawDefinition,
-    catalogue,
-    channel,
-    sourceImages,
-    pins: frozen,
-    [catalogueField.key]: catalogueField.digest,
-    ...(previousSeal === undefined ? {} : { previousSeal }),
-    ...(adoptKernel === undefined ? {} : { adoptKernel }),
-    ...(materialize === undefined ? {} : { materialize }),
-    ...(developGitBundles === undefined ? {} : { developGitBundles }),
-    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,
-    [catalogueField.key]: catalogueField.digest,
-    storePublisherAnchorKeys: resolved.storePublisherAnchorKeys,
-    // A row the develop verifier kept carries its bundle and develop signer; the seal admits exactly those.
-    gitSourcedBundle: developGitBundles === undefined ? GitSourcedBundle.Refused : GitSourcedBundle.DevelopVerified,
-  });
-  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]);
-// A vendor develop resolve finds and proves its engine itself (develop-engine-image.mjs); a customer resolve is handed one.
-const ENGINE_IMAGE_FLAG = '--engine-image';
-const ENGINE_REPOSITORY_FLAG = '--engine-repository';
-const ENGINE_SIGNER_FLAG = '--engine-signer';
-export const IMAGES_FROM_FLAG = '--images-from';
-export const PREVIOUS_LOCK_FLAG = '--previous-lock';
-export const PREVIOUS_LOCK_SHA256_FLAG = '--previous-lock-sha256';
-export const FIRST_SEAL_FLAG = '--first-seal';
-
-const COMMANDS = Object.freeze({
-  resolve: {
-    positional: true,
-    // --images-from: the everyday job's image build record (images-from-record.mjs) instead of the registry probe; vendor only.
-    // The previous seal whose composed artifacts carry their generation forward, exactly one of: --previous-seal-signer <identity> (the CLI reads
-    // the latest edition that identity signed in this edition's repository; the workflow runs under the per-edition concurrency group),
-    // --previous-lock with --previous-lock-sha256 (that edition's images.lock layer, taken by the caller) or --first-seal; vendor only.
-    values: ['--pins', '--out', '--registry', ENGINE_REPOSITORY_FLAG, ENGINE_SIGNER_FLAG, COSIGN_FLAG, IMAGES_FROM_FLAG, PREVIOUS_LOCK_FLAG, PREVIOUS_LOCK_SHA256_FLAG, PREVIOUS_SEAL_SIGNER_FLAG],
-    switches: ['--local', FIRST_SEAL_FLAG],
-    required: ['--pins', '--out', '--registry', ENGINE_REPOSITORY_FLAG, ENGINE_SIGNER_FLAG, COSIGN_FLAG],
-    customer: { values: [DEFINITION_FLAG, ...CREDENTIAL_FLAGS, SOURCE_IMAGE_FLAG, COSIGN_FLAG, ENGINE_IMAGE_FLAG], required: ['--pins', '--out', '--registry', '--engine-image'], refused: [IMAGES_FROM_FLAG, PREVIOUS_SEAL_SIGNER_FLAG], cosign: true, developCosign: true },
-    // The customer's own previous seal (customerPreviousSeal): --previous-lock with --previous-lock-sha256, or --first-seal, on develop only.
-    customerPreviousSeal: [PREVIOUS_LOCK_FLAG, PREVIOUS_LOCK_SHA256_FLAG, FIRST_SEAL_FLAG],
-    // The catalogue-free customer form (develop only, develop-catalogue-free-resolve.mjs): the vendor offering is resolved in
-    // the same call, so it names both definitions as triples, the vendor step's engine flags and the offering's frozen previous
-    // seal; --previous-lock/--first-seal are the customer's own.
-    catalogueFree: {
-      markers: [DEFINITION_AT_FLAG, OFFERING_FLAG],
-      values: [DEFINITION_AT_FLAG, OFFERING_FLAG, SOURCE_IMAGE_FLAG, OFFERING_PREVIOUS_LOCK_FLAG, OFFERING_PREVIOUS_LOCK_SHA256_FLAG],
-      required: [DEFINITION_AT_FLAG, OFFERING_FLAG, '--pins', '--out', '--registry', ENGINE_REPOSITORY_FLAG, ENGINE_SIGNER_FLAG, COSIGN_FLAG, OFFERING_PREVIOUS_LOCK_FLAG, OFFERING_PREVIOUS_LOCK_SHA256_FLAG],
-      refused: [DEFINITION_FLAG, ...CREDENTIAL_FLAGS, ENGINE_IMAGE_FLAG, IMAGES_FROM_FLAG, PREVIOUS_SEAL_SIGNER_FLAG],
-    },
-    // developCosign: on develop, --cosign verifies the git-sourced OCI bundles under the data root's pinned policy (develop-git-bundles.mjs).
-    // A vendor resolve finds its engine itself; the old flag is refused by name, never read as a customer flag.
-    removedFromVendor: { [ENGINE_IMAGE_FLAG]: `use ${ENGINE_REPOSITORY_FLAG} and ${ENGINE_SIGNER_FLAG}` },
-  },
-  engine: {
-    positional: true,
-    values: ['--pins', ENGINE_REPOSITORY_FLAG, ENGINE_SIGNER_FLAG, COSIGN_FLAG],
-    switches: [],
-    required: ['--pins', ENGINE_REPOSITORY_FLAG, ENGINE_SIGNER_FLAG, COSIGN_FLAG],
-  },
-  target: {
-    positional: true,
-    values: ['--pins', '--registry', '--engine-image', IMAGES_FROM_FLAG],
-    switches: [],
-    required: ['--pins', '--registry', '--engine-image'],
-    customer: { values: [DEFINITION_FLAG, SOURCE_IMAGE_FLAG], required: ['--pins', '--registry', '--engine-image'], refused: [IMAGES_FROM_FLAG] },
-  },
-  'freeze-graph': {
-    positional: false,
-    values: ['--data-sha', '--kernel-sha', '--deploy-sha', '--editions-root-url', '--overrides', '--member-pins', '--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'],
-  },
-  follow: {
-    positional: false,
-    values: [DEFINITION_AT_FLAG, '--data-sha', '--kernel-sha', '--deploy-sha', ENGINE_REPOSITORY_FLAG, '--registry', COSIGN_FLAG, '--current-pins', '--out', '--seals-out', PREVIOUS_SEAL_SIGNER_FLAG, PREVIOUS_LOCK_FLAG, PREVIOUS_LOCK_SHA256_FLAG],
-    // exactly one of --first and --current-pins (develop-follow.mjs followStartOf); the customer's own previous seal is
-    // exactly one of --previous-lock with --previous-lock-sha256, or --first-seal (customerPreviousLockInput)
-    switches: ['--first', FIRST_SEAL_FLAG],
-    required: [DEFINITION_AT_FLAG, '--data-sha', '--kernel-sha', '--deploy-sha', ENGINE_REPOSITORY_FLAG, '--registry', COSIGN_FLAG, '--out', '--seals-out', PREVIOUS_SEAL_SIGNER_FLAG],
-  },
-  'select-records': {
-    positional: false,
-    values: ['--branch', '--registry', '--cosign', '--out', '--at', '--published-pins'],
-    switches: [],
-    required: ['--branch', '--registry', '--cosign', '--out'],
-  },
-  'image-record': {
-    positional: true,
-    values: ['--selection', '--pins', '--out'],
-    switches: [],
-    required: ['--selection', '--pins', '--out'],
-  },
-  'verify-image-record': {
-    positional: false,
-    values: ['--image', '--producer', '--registry', '--cosign'],
-    switches: [],
-    required: ['--image', '--producer', '--registry', '--cosign'],
-  },
-  'check-overrides': { positional: false, values: ['--overrides'], switches: [], required: ['--overrides'] },
-  'choose-kernel': { positional: false, values: ['--kernel-pin', '--out'], switches: [], required: ['--out'] },
-  '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)}`);
-}
-
-/** The catalogue-free customer form of a develop verb: no positional id (it is the definition's), no catalogue flags. */
-function catalogueFreeArgs(command, spec, options, positional) {
-  for (const refused of spec.refused) {
-    if (options[refused] !== undefined) {
-      throw new Error(`a catalogue-free ${command} takes no ${refused}: it names the definition and the offering as ${DEFINITION_AT_FLAG} and ${OFFERING_FLAG}, pins no catalogue, and its vendor step finds its engine itself`);
-    }
-  }
-  if (positional.length !== 0) {throw new Error(`a catalogue-free ${command} takes no <distribution-id>: the id is the definition's`);}
-  for (const required of spec.required) {
-    if (options[required] === undefined) {throw new Error(`a catalogue-free ${command} requires ${required}`);}
-  }
-  if (!isAbsolute(options[COSIGN_FLAG])) {throw new Error(`${COSIGN_FLAG} must be an absolute path, got ${JSON.stringify(options[COSIGN_FLAG])}`);}
-  return { command, id: undefined, options, customer: false, catalogueFree: true };
-}
-
-/** 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(' | ')}`);
-  }
-  // The flags only the customer form takes: a flag the vendor form takes too (`--cosign` of a develop resolve) does not make it one.
-  const customerValues = (spec.customer?.values ?? []).filter((flag) => !spec.values.includes(flag));
-  const catalogueFreeValues = channel === EditionChannel.Develop ? (spec.catalogueFree?.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) || catalogueFreeValues.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);
-    }
-  }
-  if (catalogueFreeValues.length > 0 && spec.catalogueFree.markers.some((flag) => options[flag] !== undefined)) {
-    return catalogueFreeArgs(command, spec.catalogueFree, options, positional);
-  }
-  for (const flag of catalogueFreeValues.filter((value) => !customerValues.includes(value) && !spec.values.includes(value))) {
-    if (options[flag] !== undefined) {throw new Error(`${flag} belongs to the catalogue-free form of ${command} (${spec.catalogueFree.markers.join(' and ')})`);}
-  }
-  const customer = spec.customer !== undefined && customerValues.some((flag) => options[flag] !== undefined);
-  // `--cosign` of a customer form verifies a release catalogue, and on a develop resolve the git-sourced OCI bundles
-  // (`developCosign`); a vendor verb (develop `coverage`, `resolve`, `engine`) takes its own `--cosign`.
-  if (customer && spec.customer?.cosign === true && options[COSIGN_FLAG] !== undefined && channel !== EditionChannel.Release && spec.customer.developCosign !== true) {
-    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}`);
-  }
-  // A removed vendor flag with no other sign of a customer form (no --definition, no customer-only flag) is a stale vendor call.
-  const removedFlags = Object.keys(spec.removedFromVendor ?? {});
-  if (!customerValues.some((flag) => !removedFlags.includes(flag) && options[flag] !== undefined)) {
-    for (const flag of removedFlags) {
-      if (options[flag] !== undefined) {throw new Error(`${flag} was removed from a vendor ${command}: ${spec.removedFromVendor[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}`);}
-    }
-    // The customer's own previous seal is a develop resolve's (customerPreviousSeal); a release customer resolve takes none.
-    for (const flag of spec.customerPreviousSeal ?? []) {
-      if (channel !== EditionChannel.Develop && options[flag] !== undefined) {throw new Error(`a ${channel} customer ${command} takes no ${flag}`);}
-    }
-    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 && options[COSIGN_FLAG] === undefined) {
-      throw new Error(`a release ${command} requires ${COSIGN_FLAG} <absolute path of the cosign binary>`);
-    }
-    if (spec.customer.cosign === true && options[COSIGN_FLAG] !== undefined && !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 }),
-  });
-}
-
-/**
- * The customer's own previous seal of a develop resolve, as `previousSeal(id)` (resolveCustomerChannelEdition): exactly
- * one of `--previous-lock <path> --previous-lock-sha256 <hex>` (the customer edition's own last images lock, its bytes
- * held to the sha256 and its id to the edition's) or `--first-seal`. No signer form: a resolve reads no "newest", so the
- * same frozen inputs resolve the same bytes. A release customer resolve takes none (refused at the parse).
- */
-export function customerPreviousSeal(channel, options) {
-  if (channel !== EditionChannel.Develop) {return undefined;}
-  return (distributionId) =>
-    resolvePreviousSeal({
-      distributionId,
-      previousLockPath: options[PREVIOUS_LOCK_FLAG],
-      previousLockSha256: options[PREVIOUS_LOCK_SHA256_FLAG],
-      firstSeal: Boolean(options[FIRST_SEAL_FLAG]),
-    });
-}
-
-/** 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']),
-    previousSeal: customerPreviousSeal(channel, options),
-    sourceImages,
-    env,
-    // Develop, under a declared customer policy: the git-sourced OCI bundles are verified with --cosign (none: refused when a subject exists).
-    developGitBundles: customerDevelopGitBundleVerifier({ channel, cosignBinary: options[COSIGN_FLAG], env }),
-  });
-  const evidenceTrustPolicy = await descriptorEvidenceTrust({ kind: EditionKind.Resolved, 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({ kind: EditionKind.Resolved, 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

@@ -1,15 +0,0 @@
-// The flags that make a resolve a CUSTOMER resolve (against a catalogue).
-export const DEFINITION_FLAG = '--definition';
-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';
-/** A definition named as `<owner>/<repo>,<path>,<dataRoot>` at a pinned commit (`develop follow`); `--definition` is a file. */
-export const DEFINITION_AT_FLAG = '--definition-at';
-/** The vendor offering a catalogue-free resolve resolves in the same call, as `<owner>/<repo>,<path>,<dataRoot>` of the vendor data checkout. */
-export const OFFERING_FLAG = '--offering';
-/** The offering's own previous seal a catalogue-free resolve's vendor step carries forward: the images lock `develop follow` froze, and its sha256. */
-export const OFFERING_PREVIOUS_LOCK_FLAG = '--offering-previous-lock';
-export const OFFERING_PREVIOUS_LOCK_SHA256_FLAG = '--offering-previous-lock-sha256';