@xemahq/edition-tooling 0.0.0-stage → 0.1.1

package/edition/customer-edition-verbs.mjs

@@ -0,0 +1,610 @@
+// 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 { 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';
+  }
+}
+
+/** A customer's own image rows belong to no first-party source, so none roots their develop ref. */
+const CUSTOMER_DECLARED_SOURCES = Object.freeze({});
+
+/**
+ * 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, declaredSources: CUSTOMER_DECLARED_SOURCES, 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 vendor develop verb takes (the catalogue-free resolve's vendor step takes the same). */
+export const DEVELOP_VENDOR_ROOTS = Object.freeze([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Deploy, WorkspaceRoot.Cache]);
+
+/** The roots of develop `select-records`: no kernel, since it runs before any member pin exists and parses records with the CLI's own contracts. */
+export const SELECT_RECORDS_ROOTS = Object.freeze(DEVELOP_VENDOR_ROOTS.filter((root) => root !== WorkspaceRoot.Kernel));
+
+/** 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]);
+// Every resolve is handed its engine by digest, except the catalogue-free form, whose vendor step finds and proves it
+// (develop-catalogue-free-vendor.mjs) from --engine-repository and --engine-signer.
+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 SELECTION_FLAG = '--selection';
+export const CHANNEL_FLAG = '--channel';
+export const PREVIOUS_LOCK_FLAG = '--previous-lock';
+export const PREVIOUS_LOCK_SHA256_FLAG = '--previous-lock-sha256';
+export const FIRST_SEAL_FLAG = '--first-seal';
+/** Removed from the vendor resolve (the channel lane verifies no engine, bundle or previous seal): refused by name. */
+const CHANNEL_LANE_REMOVAL = `the vendor develop resolve takes ${ENGINE_IMAGE_FLAG} <repository>@sha256:<digest>, ${IMAGES_FROM_FLAG}, ${CHANNEL_FLAG} and ${SELECTION_FLAG}, and verifies no signature`;
+
+const COMMANDS = Object.freeze({
+  resolve: {
+    positional: true,
+    // The vendor form is the channel lane: the engine by digest, every image digest from the build record (--images-from,
+    // images-from-record.mjs) whose satellites are checked against the --channel records; no cosign. The previous seal
+    // whose composed artifacts carry their generation forward is exactly one of --previous-lock with --previous-lock-sha256
+    // (that edition's images.lock layer, taken by the caller) or --first-seal.
+    // --selection is the select-records file the run's image record came from: the satellite check reads the records it pinned.
+    values: ['--pins', '--out', '--registry', ENGINE_IMAGE_FLAG, IMAGES_FROM_FLAG, CHANNEL_FLAG, SELECTION_FLAG, PREVIOUS_LOCK_FLAG, PREVIOUS_LOCK_SHA256_FLAG],
+    switches: ['--local', FIRST_SEAL_FLAG],
+    required: ['--pins', '--out', '--registry', ENGINE_IMAGE_FLAG, IMAGES_FROM_FLAG, CHANNEL_FLAG, SELECTION_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, CHANNEL_FLAG, SELECTION_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 on the verified lane, 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, ENGINE_REPOSITORY_FLAG, ENGINE_SIGNER_FLAG, COSIGN_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, CHANNEL_FLAG, SELECTION_FLAG],
+    },
+    // developCosign: on a customer develop resolve, --cosign verifies the git-sourced OCI bundles under the data root's pinned policy (develop-git-bundles.mjs).
+    removedFromVendor: {
+      [ENGINE_REPOSITORY_FLAG]: CHANNEL_LANE_REMOVAL,
+      [ENGINE_SIGNER_FLAG]: CHANNEL_LANE_REMOVAL,
+      [COSIGN_FLAG]: CHANNEL_LANE_REMOVAL,
+    },
+  },
+  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', '--deploy-sha', '--out'],
+  },
+  'freeze-sources': {
+    positional: true,
+    values: ['--pins', '--overrides', '--out'],
+    switches: [],
+    required: ['--pins', '--out'],
+    customer: { values: [DEFINITION_FLAG], required: ['--out'], refused: ['--pins', '--overrides'] },
+  },
+  'select-records': {
+    positional: false,
+    // --registry is still accepted for one release (the workflow passes it) and is unused: the records live under each member's developImageRegistry
+    values: ['--branch', '--registry', '--out', CHANNEL_FLAG],
+    switches: [],
+    // the records are read through the channel tag their producer's CI moves (develop-select-records.mjs); no cosign
+    required: ['--branch', '--out', CHANNEL_FLAG],
+  },
+  'image-record': {
+    positional: true,
+    values: ['--selection', '--pins', '--out', CHANNEL_FLAG, '--registry'],
+    switches: [],
+    required: ['--selection', '--pins', '--out', CHANNEL_FLAG],
+  },
+  '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 (`--engine-image` 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);
+  }
+  // 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 = channel === EditionChannel.Develop ? 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]}`);}
+    }
+  }
+  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`); no vendor verb takes one.
+  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}`);
+  }
+  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, { imageRef: imageRefForSubject(subject.id, image.imageRegistry, image.imageNamePrefix) }, CUSTOMER_DECLARED_SOURCES);
+    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

@@ -0,0 +1,15 @@
+// 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; `--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 frozen offering images lock, and its sha256. */
+export const OFFERING_PREVIOUS_LOCK_FLAG = '--offering-previous-lock';
+export const OFFERING_PREVIOUS_LOCK_SHA256_FLAG = '--offering-previous-lock-sha256';