@xemahq/xema 0.26.0 → 0.28.0

package/edition/customer-definition.mjs

@@ -0,0 +1,183 @@
+// customer-definition — reading a CUSTOMER edition definition, and the image
+// registry mirror it may declare.
+//
+// A definition resolved against a catalogue is a customer edition. Its rules
+// live in the kernel (`parseCustomerEditionDefinition`, `customerTrustCeilingIssues`);
+// this module calls them and owns only the `imageRegistryMirror`, which is CLI
+// configuration the kernel document does not carry.
+
+import { SOURCE_IMAGE_FLAG } from './customer-flags.mjs';
+
+export class CustomerDefinitionError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = 'CustomerDefinitionError';
+  }
+}
+
+/** The mirror's refusals (overlap, ambiguity, partial segment, tag/digest alteration, self-mapping, uncovered row). */
+export class ImageRegistryMirrorError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ImageRegistryMirrorError';
+  }
+}
+
+export const MIRROR_KEY = 'imageRegistryMirror';
+
+/**
+ * Parse a raw customer definition. The RULES are the kernel's, in one place:
+ * `parseCustomerEditionDefinition` (a closed vocabulary - visibility, extends,
+ * exclude and sweeping selectors are not in it; `trustCeiling` required iff
+ * `sources`; `sources[].ref` a branch or a tag, never a commit; git-only
+ * sources; the one `{biome}` selector grammar). The CLI adds nothing to them
+ * except what the kernel document does not carry: it removes the mirror (CLI
+ * configuration, parsed by `parseImageRegistryMirror`) before the kernel sees
+ * the document, and refuses a source that states the registry its images come
+ * from, because that is handed in with `--source-image` and has no default.
+ * Returns the kernel's parsed definition and the raw mirror.
+ */
+export function parseCustomerDefinition(schemas, raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new CustomerDefinitionError('a customer definition must be a JSON object');
+  }
+  const { [MIRROR_KEY]: mirror, ...document } = raw;
+  for (const source of Array.isArray(document.sources) ? document.sources : []) {
+    const stated = ['imageRegistry', 'imageNamePrefix'].find((key) => source !== null && typeof source === 'object' && key in source);
+    if (stated !== undefined) {
+      throw new CustomerDefinitionError(
+        `customer definition "${raw.id}": source "${source.name}" states ${stated}; the registry is configuration, ` +
+          `handed in with ${SOURCE_IMAGE_FLAG} ${source.name}=<registry>/<prefix>`,
+      );
+    }
+  }
+  let definition;
+  try {
+    definition = schemas.parseCustomerEditionDefinition(document);
+  } catch (error) {
+    throw new CustomerDefinitionError(error.message, { cause: error });
+  }
+  assertNoVendorReservedDomain(schemas, definition);
+  return { definition, mirror };
+}
+
+/** The trust domains only the vendor places a biome in: the kernel's first-party domain. */
+export const vendorReservedTrustDomains = (schemas) => [schemas.FIRST_PARTY_TRUST_DOMAIN];
+
+/** A customer's `trustCeiling` assigns its own biomes and never into a vendor-reserved domain. */
+function assertNoVendorReservedDomain(schemas, definition) {
+  const reserved = new Set(vendorReservedTrustDomains(schemas));
+  for (const assignment of definition.trustCeiling?.assignments ?? []) {
+    if (reserved.has(assignment.domain)) {
+      throw new CustomerDefinitionError(
+        `customer definition "${definition.id}": \`trustCeiling\` assigns ${assignment.biomes.map((biome) => `biome "${biome}"`).join(', ')} ` +
+          `to trust domain "${assignment.domain}", which is reserved to the vendor; a customer's biomes are assigned a domain of the customer's own`,
+      );
+    }
+  }
+}
+
+/**
+ * The trustCeiling must assign every customer-source biome (a biome the resolved lock draws
+ * from the definition's own `sources[]`) and no other: the kernel's `customerTrustCeilingIssues`.
+ */
+export function assertTrustCeilingAssignsCustomerBiomes(schemas, definition, customerBiomeIds) {
+  const issues = schemas.customerTrustCeilingIssues(definition, customerBiomeIds);
+  if (issues.length > 0) {
+    throw new CustomerDefinitionError(`customer definition "${definition.id}": ${issues.join('; ')}`);
+  }
+}
+
+const HOST_PATH = /^[a-z0-9.-]+(:[0-9]+)?(\/[a-z0-9._-]+)*$/;
+const segmentsOf = (prefix) => prefix.split('/');
+const isSegmentPrefix = (shorter, longer) => {
+  const a = segmentsOf(shorter);
+  const b = segmentsOf(longer);
+  return a.length <= b.length && a.every((segment, index) => segment === b[index]);
+};
+
+/** The strict parse of `imageRegistryMirror`: `{complete: boolean, map: [{source, target}]}`, no defaults. */
+export function parseImageRegistryMirror(value) {
+  if (value === undefined) {return undefined;}
+  const exact = (candidate, keys, where) => {
+    if (candidate === null || typeof candidate !== 'object' || Array.isArray(candidate) || Object.keys(candidate).sort().join() !== [...keys].sort().join()) {
+      throw new ImageRegistryMirrorError(`${where} must be exactly {${keys.join(', ')}}`);
+    }
+  };
+  if (value === null || typeof value !== 'object' || !('complete' in value)) {
+    throw new ImageRegistryMirrorError(`${MIRROR_KEY}.complete is required and must be a boolean (no default)`);
+  }
+  exact(value, ['complete', 'map'], MIRROR_KEY);
+  if (typeof value.complete !== 'boolean') {
+    throw new ImageRegistryMirrorError(`${MIRROR_KEY}.complete is required and must be a boolean (no default)`);
+  }
+  if (!Array.isArray(value.map) || value.map.length === 0) {
+    throw new ImageRegistryMirrorError(`${MIRROR_KEY}.map must be a non-empty array of {source, target}`);
+  }
+  for (const entry of value.map) {
+    exact(entry, ['source', 'target'], `${MIRROR_KEY}.map entry`);
+    for (const side of ['source', 'target']) {
+      if (typeof entry[side] !== 'string' || !HOST_PATH.test(entry[side]) || !entry[side].includes('/')) {
+        throw new ImageRegistryMirrorError(
+          `${MIRROR_KEY}.map ${side} ${JSON.stringify(entry[side])} is not <host>/<path-prefix> ` +
+            '(lowercase, whole path segments, no tag, no digest, no wildcard)',
+        );
+      }
+    }
+    if (entry.source === entry.target) {
+      throw new ImageRegistryMirrorError(`${MIRROR_KEY}.map maps ${entry.source} to itself`);
+    }
+  }
+  const sources = value.map.map((entry) => entry.source);
+  sources.forEach((source, index) => {
+    sources.slice(index + 1).forEach((other) => {
+      if (isSegmentPrefix(source, other) || isSegmentPrefix(other, source)) {
+        throw new ImageRegistryMirrorError(
+          source === other
+            ? `${MIRROR_KEY}.map lists source ${source} twice`
+            : `${MIRROR_KEY}.map sources ${source} and ${other} overlap (one is a path-segment prefix of the other); a ref would match both`,
+        );
+      }
+    });
+  });
+  return { complete: value.complete, map: value.map.map(({ source, target }) => ({ source, target })) };
+}
+
+const REF_NAME = /^[a-z0-9.-]+(:[0-9]+)?(\/[a-z0-9._-]+)+$/;
+
+/**
+ * Re-home one image ref (name only, as the images lock records it) under the
+ * mirror. Whole path segments only; the remaining path is untouched; a ref that
+ * carries a tag or digest is refused. Returns the ref unchanged when no entry
+ * covers it (the caller decides whether that is an error: `complete`).
+ */
+export function mirrorImageRef(imageRef, mirror) {
+  if (typeof imageRef !== 'string' || !REF_NAME.test(imageRef)) {
+    throw new ImageRegistryMirrorError(`image ref ${JSON.stringify(imageRef)} is not a bare <host>/<path> name (a tag or digest cannot be rewritten)`);
+  }
+  const partial = mirror.map.find((entry) => imageRef.startsWith(entry.source) && !isSegmentPrefix(entry.source, imageRef));
+  if (partial !== undefined) {
+    throw new ImageRegistryMirrorError(
+      `${MIRROR_KEY} source ${partial.source} matches ${imageRef} only in part of a path segment; prefixes match whole segments`,
+    );
+  }
+  const matches = mirror.map.filter((entry) => isSegmentPrefix(entry.source, imageRef) && entry.source !== imageRef);
+  if (matches.length === 0) {return { imageRef, covered: false };}
+  const [{ source, target }] = matches;
+  const rest = segmentsOf(imageRef).slice(segmentsOf(source).length).join('/');
+  return { imageRef: `${target}/${rest}`, covered: true };
+}
+
+/** Re-home the vendor image rows; `complete: true` refuses a row no entry covers. */
+export function mirrorVendorSubjects(subjects, mirror) {
+  if (mirror === undefined) {return subjects;}
+  return subjects.map((subject) => {
+    const { imageRef, covered } = mirrorImageRef(subject.imageRef, mirror);
+    if (!covered && mirror.complete) {
+      throw new ImageRegistryMirrorError(
+        `${MIRROR_KEY} is complete:true but no map entry covers ${subject.kind}:${subject.id} (${subject.imageRef})`,
+      );
+    }
+    return { ...subject, imageRef };
+  });
+}

package/edition/customer-flags.mjs

@@ -0,0 +1,7 @@
+// The flags that make a resolve a CUSTOMER resolve (against a catalogue).
+export const DEFINITION_FLAG = '--definition';
+export const CATALOGUE_FLAG = '--catalogue';
+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';

package/edition/develop-customer-edition.mjs

@@ -0,0 +1,99 @@
+// develop-customer-edition — a DEVELOP customer edition: a customer definition
+// resolved against a catalogue, 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 snapshot hash (the artifact tag) covers it. The vendor image
+// rows arrive sealed from the catalogue; only the customer's own image rows are
+// sealed against the develop image repositories.
+
+import { sealLock } from './biome-content.mjs';
+import { sealDevelopImages } from './develop-seal.mjs';
+import { CATALOGUE_PIN_KEY, EditionChannel } from './edition-constants.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
+import { snapshotPinNamespace, SnapshotPinNamespace, sortedSnapshotPins, sourcePinKey } from './pin-source.mjs';
+import { resolveCustomerEdition } from './resolve-customer-edition.mjs';
+import { externalSourceTrees, sourceTreeLocator } from './resolve-images.mjs';
+
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+
+export class CustomerDevelopPinsError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CustomerDevelopPinsError';
+  }
+}
+
+/**
+ * The pins of a develop customer edition: `sources/<name>` commits for exactly
+ * the definition's declared sources, plus `catalogue` = the digest of the
+ * catalogue artifact. A `catalogue` entry in the file must equal that digest.
+ */
+export function customerDevelopPins({ pins, declaredSourceNames, catalogueDigest }) {
+  if (pins === null || typeof pins !== 'object' || Array.isArray(pins)) {
+    throw new CustomerDevelopPinsError('--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 CustomerDevelopPinsError(`--pins "${CATALOGUE_PIN_KEY}" is ${JSON.stringify(value)}, but --catalogue is ${catalogueDigest}`);
+      }
+      continue;
+    }
+    if (snapshotPinNamespace(key) !== SnapshotPinNamespace.Source) {
+      throw new CustomerDevelopPinsError(`--pins "${key}" is not one of the customer's own repositories: a customer develop pins only sources/<name> (the vendor's pins are the catalogue's)`);
+    }
+    if (typeof value !== 'string' || !SHA_PATTERN.test(value)) {
+      throw new CustomerDevelopPinsError(`--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 CustomerDevelopPinsError(`--pins is missing "${key}": the definition declares that source`);}
+  }
+  for (const key of Object.keys(own)) {
+    if (!declared.has(key)) {throw new CustomerDevelopPinsError(`--pins names "${key}", but the definition declares no such source`);}
+  }
+  return sortedSnapshotPins({ ...own, [CATALOGUE_PIN_KEY]: catalogueDigest });
+}
+
+/** 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 develop customer edition; returns the four locks and the frozen provenance pins. */
+export async function resolveCustomerDevelopEdition({ rawDefinition, catalogue, catalogueDigest, pins, sourceImages, env = process.env, sealOptions = {}, verifyAuthority, materialize }) {
+  const frozen = customerDevelopPins({ pins, declaredSourceNames: declaredSourceNamesOf(rawDefinition), catalogueDigest });
+  const resolved = await resolveCustomerEdition({
+    rawDefinition,
+    catalogue,
+    channel: EditionChannel.Develop,
+    sourceImages,
+    pins: frozen,
+    catalogueDigest,
+    ...(verifyAuthority === undefined ? {} : { verifyAuthority }),
+    ...(materialize === undefined ? {} : { materialize }),
+    sealOwn: (imageLock) => sealDevelopImages({ imageLock, 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,
+  });
+  return { ...resolved, distributionLock, pins: frozen };
+}

package/edition/develop-edition-resolve.mjs

@@ -0,0 +1,65 @@
+// develop-edition-resolve — resolve and seal one DEVELOP edition from a snapshot.
+//
+// The whole pipeline, in the order the release runs it, over the snapshot's
+// injected inputs: distribution lock -> authorization base (composed, never
+// written) -> images lock -> develop seal, plus the chart-set lock: the frozen
+// xema-deploy charts' registry manifest digests, in the release roster shape. Nothing here writes to the editions
+// trees; the caller writes the artifact (edition-artifact.mjs).
+
+import { biomeSourceTreeIds, sealLock } from './biome-content.mjs';
+import { buildCatalogue } from './catalogue.mjs';
+import { sealDevelopImages } from './develop-seal.mjs';
+import { assertFrozenCheckouts, buildSnapshotInputs } from './develop-snapshot-inputs.mjs';
+import { EditionChannel } from './edition-constants.mjs';
+import { deployRoot } from './edition-workspace.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
+import { deployPinKey } from './pin-source.mjs';
+import { resolveDevelopChartSet } from './resolve-chart-set.mjs';
+import { composeAuthorizationBase, resolveDistributionWithIndex } from './resolve-distribution.mjs';
+import { externalSourceTrees, resolveImages, sourceTreeLocator } from './resolve-images.mjs';
+import { createPinnedSourceAuthority } from './source-authority.mjs';
+
+export async function resolveDevelopEdition({ id, pins, env = process.env, sealOptions = {}, chartDigestLookup }) {
+  const schemas = await loadKernelDistributionSchemas();
+  assertFrozenCheckouts(pins);
+  const inputs = await buildSnapshotInputs({ id, pins, schemas });
+  const { lock, index } = await resolveDistributionWithIndex(id, { inputs });
+  const authorizationLock = await composeAuthorizationBase(id, lock, index);
+  const { imageLock } = await resolveImages(id, { inputs, lock });
+  const sealedImageLock = await sealDevelopImages({ imageLock, env, ...sealOptions });
+  // The unsealed lock becomes the one v5 grammar only here, once the images it
+  // owns are sealed: each biomeContentHash is recomputed from the frozen sources.
+  const authority = createPinnedSourceAuthority({ pins: inputs.runtimeImageSourceIndex.repositoryPins });
+  const sealedLock = await sealLock({
+    schemas,
+    unsealed: lock,
+    imageLock: sealedImageLock,
+    locate: sourceTreeLocator(externalSourceTrees(lock)),
+    vendoredCommit: (repo) => authority.vendoredSourceCommitForRepository(repo),
+  });
+  const chartSetLock = await resolveDevelopChartSet({
+    xemaDeployDir: deployRoot(),
+    xemaDeploySha: pins[deployPinKey()],
+    lookup: chartDigestLookup,
+  });
+  const sourceTreeIds = await biomeSourceTreeIds({
+    schemas,
+    lock,
+    imageLock: sealedImageLock,
+    locate: sourceTreeLocator(externalSourceTrees(lock)),
+    vendoredCommit: (repo) => authority.vendoredSourceCommitForRepository(repo),
+  });
+  const catalogue = buildCatalogue({
+    sourceTreeIds,
+    offeringId: id,
+    channel: EditionChannel.Develop,
+    distributionLock: lock,
+    imageLock: sealedImageLock,
+    chartSetLock,
+    biomeIndex: inputs.biomeIndex,
+    platformServiceIndex: inputs.platformServiceIndex,
+    contractAuthority: inputs.runtimeImageSourceIndex.contractAuthority,
+    leaf: inputs.composed.leaf,
+  });
+  return { distributionLock: sealedLock, imageLock: sealedImageLock, authorizationLock, chartSetLock, catalogue };
+}

package/edition/develop-edition.mjs

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+// develop-edition — the develop edition's command line.
+//
+//   resolve <id> --pins <file> --out <dir> --registry <namespace>
+//           --engine-image <repository>@sha256:<digest> [--local]
+//       resolve the edition from the snapshot, seal it against the develop image
+//       repositories, write the descriptor and the four locks to <dir>, print the target.
+//       The workflow run is recorded from GITHUB_REPOSITORY / GITHUB_RUN_ID;
+//       --local stamps `local` instead, for a resolve outside GitHub Actions.
+//   resolve --definition <file> --catalogue oci://<repo>@sha256:<digest> --pins <file> --out <dir> --registry <namespace>
+//           --engine-image <repository>@sha256:<digest> [--source-image <source>=<registry>/<prefix>]...
+//           [--catalogue-username <name> --catalogue-token-env <VAR>] [--local]
+//       a CUSTOMER develop edition: the definition resolved against the catalogue (see resolve-customer-edition.mjs),
+//       frozen at the customer's own pins. --pins holds exactly one `sources/<name>` commit per source the definition
+//       declares; the catalogue digest is frozen into the descriptor's provenance pins as `catalogue`. The id is the
+//       definition's. Takes --data-root, --editions-root, --sources-root, --kernel, --cache-dir (no --deploy-root).
+//   target  <id> --pins <file> --registry <namespace>
+//       print <namespace>/xema-edition-<id>:<snapshot hash>. The namespace is always the caller's
+//       (e.g. registry.example.com/acme); the repository prefix comes from
+//       edition-contract.json, and no namespace is implied.
+//   freeze-graph --data-sha <sha> --kernel-sha <sha>
+//                --deploy-sha <sha> [--editions-root-url <https url>]
+//                [--overrides <json>] --out <file>
+//       resolve refs/heads/develop once per graph repository (and the editions
+//       root) from this checkout's runtime-image-source-index.json; the three checked-out
+//       repositories are pinned at what the workflow checked out; write the pins.
+//   check-existing <id> --pins <file> --artifact <dir> --engine-image <repository>@sha256:<digest>
+//       refuse to reuse a pulled artifact whose descriptor disagrees with this snapshot.
+//   check-overrides --overrides <json>
+//       refuse a pins override that would select the tooling this run executes
+//       (the edition tooling's own repository); the workflow runs it before any other checkout.
+//   freeze-sources <id> --pins <file> [--overrides <json>] --out <file>
+//       add one pin per source the edition's chain declares (run after the editions
+//       root is checked out and passed as --editions-root); write the final pins.
+//
+// Tokens come from the environment (EVIDENCE_REPOSITORIES_TOKEN, XEMA_GHCR_PULL_TOKEN),
+// never argv. Nothing here writes git or publishes a release edition.
+
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { fetchCatalogue } from './catalogue-fetch.mjs';
+import { writeCatalogue } from './catalogue.mjs';
+import { CATALOGUE_FLAG, CATALOGUE_TOKEN_ENV_FLAG, CATALOGUE_USERNAME_FLAG, DEFINITION_FLAG, SOURCE_IMAGE_FLAG } from './customer-flags.mjs';
+import { resolveCustomerDevelopEdition } from './develop-customer-edition.mjs';
+import { resolveDevelopEdition } from './develop-edition-resolve.mjs';
+import { assertNoToolingOverride, freezeGraph, freezeSources, lsRemoteDevelopHead } from './develop-freeze.mjs';
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import { LOCAL_WORKFLOW, assertEngineImage, assertExistingArtifactMatches, developEditionTarget, workflowFromEnv, writeEditionArtifact } from './edition-artifact.mjs';
+import { editionWorkspaceConfig } from './edition-config.mjs';
+import { EditionChannel } from './edition-constants.mjs';
+import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, runtimeImageSourceIndexPath } from './edition-workspace.mjs';
+import { descriptorEvidenceTrust } from './evidence-trust-policy.mjs';
+import { loadKernelDistributionSchemas, serializeJson } from './lib.mjs';
+import { snapshotPinSource } from './pin-source.mjs';
+import { parseSourceImages } from './resolve-customer-edition.mjs';
+import { composeEdition } from './resolve-distribution.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess(
+    process.argv.includes(DEFINITION_FLAG)
+      ? [WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache, WorkspaceRoot.SourceHash]
+      : [WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Deploy, WorkspaceRoot.Cache, WorkspaceRoot.SourceHash],
+  );
+}
+
+// The flags only a customer develop resolve takes, and the one of them that repeats.
+const CUSTOMER_VALUES = Object.freeze([DEFINITION_FLAG, CATALOGUE_FLAG, CATALOGUE_USERNAME_FLAG, CATALOGUE_TOKEN_ENV_FLAG, SOURCE_IMAGE_FLAG]);
+const CUSTOMER_REQUIRED = Object.freeze([DEFINITION_FLAG, CATALOGUE_FLAG]);
+const REPEATABLE = Object.freeze([SOURCE_IMAGE_FLAG]);
+
+const COMMANDS = Object.freeze({
+  resolve: { positional: true, values: ['--pins', '--out', '--registry', '--engine-image', ...CUSTOMER_VALUES], switches: ['--local'] },
+  target: { positional: true, values: ['--pins', '--registry'], switches: [] },
+  'freeze-graph': {
+    positional: false,
+    values: ['--data-sha', '--kernel-sha', '--deploy-sha', '--editions-root-url', '--overrides', '--out'],
+    switches: [],
+  },
+  'freeze-sources': { positional: true, values: ['--pins', '--overrides', '--out'], switches: [] },
+  'check-overrides': { positional: false, values: ['--overrides'], switches: [] },
+  'check-existing': { positional: true, values: ['--pins', '--artifact', '--engine-image'], switches: [] },
+});
+const REQUIRED = Object.freeze({
+  resolve: ['--pins', '--out', '--registry', '--engine-image'],
+  target: ['--pins', '--registry'],
+  'freeze-graph': ['--data-sha', '--kernel-sha', '--deploy-sha', '--out'],
+  'freeze-sources': ['--pins', '--out'],
+  'check-overrides': ['--overrides'],
+  'check-existing': ['--pins', '--artifact', '--engine-image'],
+});
+
+/** Parse `<command> [<id>] --flag value ...` against the closed vocabulary of the command. */
+export function parseDevelopEditionArgs(argv) {
+  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 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)) {
+      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 = command === 'resolve' && CUSTOMER_VALUES.some((flag) => options[flag] !== undefined);
+  if (customer) {
+    for (const required of CUSTOMER_REQUIRED) {
+      if (options[required] === undefined) {throw new Error(`a customer develop resolve requires ${required}`);}
+    }
+    if (positional.length !== 0) {throw new Error('a customer develop resolve takes no <distribution-id>: the id is the definition\'s');}
+  } 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 REQUIRED[command]) {
+    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 };
+}
+
+function parseOverrides(text) {
+  if (text === undefined || text.trim() === '') {return {};}
+  const parsed = JSON.parse(text);
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('--overrides must be a JSON object mapping pin key -> 40-hex commit');
+  }
+  return parsed;
+}
+
+function writeOnce(path, value) {
+  writeFileSync(path, serializeJson(value), { flag: 'wx' });
+}
+
+function headResolver(env) {
+  const token = env.EVIDENCE_REPOSITORIES_TOKEN;
+  const username = editionWorkspaceConfig().sourceAuthUsername;
+  return (url) => lsRemoteDevelopHead(url, { username, token });
+}
+
+/** A customer develop resolve: the artifact (descriptor and four locks, no catalogue: it is not an offering) goes to --out. */
+async function resolveCustomer(options, env) {
+  const { catalogue, digest } = await fetchCatalogue({
+    ref: options[CATALOGUE_FLAG],
+    username: options[CATALOGUE_USERNAME_FLAG],
+    tokenEnv: options[CATALOGUE_TOKEN_ENV_FLAG],
+    env,
+  });
+  const rawDefinition = readStrictJsonFile(options[DEFINITION_FLAG]);
+  const evidenceTrustPolicy = await descriptorEvidenceTrust({ channel: EditionChannel.Develop });
+  const { id, pins, ...resolved } = await resolveCustomerDevelopEdition({
+    rawDefinition,
+    catalogue,
+    catalogueDigest: digest,
+    pins: readStrictJsonFile(options['--pins']),
+    sourceImages: parseSourceImages(options[SOURCE_IMAGE_FLAG] ?? []),
+    env,
+  });
+  const target = developEditionTarget(id, pins, { registry: options['--registry'] });
+  writeEditionArtifact({
+    outDir: resolve(options['--out']),
+    channel: EditionChannel.Develop,
+    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);
+}
+
+async function run(argv, env) {
+  const { command, id, options } = parseDevelopEditionArgs(argv);
+  switch (command) {
+    case 'target': {
+      console.log(developEditionTarget(id, readStrictJsonFile(options['--pins']), { registry: options['--registry'] }));
+      return;
+    }
+    case 'resolve': {
+      if (options[DEFINITION_FLAG] !== undefined) {return resolveCustomer(options, env);}
+      const pins = readStrictJsonFile(options['--pins']);
+      const workflow = options['--local'] ? LOCAL_WORKFLOW : workflowFromEnv(env);
+      const target = developEditionTarget(id, pins, { registry: options['--registry'] });
+      const evidenceTrustPolicy = await descriptorEvidenceTrust({ channel: EditionChannel.Develop });
+      const { catalogue, ...resolved } = await resolveDevelopEdition({ id, pins, env });
+      const outDir = resolve(options['--out']);
+      writeEditionArtifact({
+        outDir,
+        channel: EditionChannel.Develop,
+        distributionId: id,
+        pins,
+        workflow,
+        evidenceTrustPolicy,
+        engineImage: options['--engine-image'],
+        ...resolved,
+      });
+      writeCatalogue(outDir, catalogue);
+      console.log(target);
+      return;
+    }
+    case 'check-existing': {
+      assertExistingArtifactMatches({
+        artifactDir: resolve(options['--artifact']),
+        distributionId: id,
+        channel: EditionChannel.Develop,
+        evidenceTrustPolicy: await descriptorEvidenceTrust({ channel: EditionChannel.Develop }),
+        pins: readStrictJsonFile(options['--pins']),
+        engineImage: options['--engine-image'],
+      });
+      return;
+    }
+    case 'check-overrides': {
+      assertNoToolingOverride(parseOverrides(options['--overrides']));
+      return;
+    }
+    case 'freeze-graph': {
+      const pins = freezeGraph({
+        runtimeSourceIndex: readStrictJsonFile(runtimeImageSourceIndexPath()),
+        dataSha: options['--data-sha'],
+        kernelSha: options['--kernel-sha'],
+        deploySha: options['--deploy-sha'],
+        editionsRootUrl: options['--editions-root-url'],
+        overrides: parseOverrides(options['--overrides']),
+        resolveHead: headResolver(env),
+      });
+      writeOnce(options['--out'], pins);
+      return;
+    }
+    case 'freeze-sources': {
+      const pins = readStrictJsonFile(options['--pins']);
+      const { parseDistribution } = await loadKernelDistributionSchemas();
+      const declaredSources = composeEdition(parseDistribution, id, snapshotPinSource(pins)).declaredSources;
+      writeOnce(
+        options['--out'],
+        freezeSources({ pins, declaredSources, overrides: parseOverrides(options['--overrides']), resolveHead: headResolver(env) }),
+      );
+      return;
+    }
+    default:
+      throw new Error(`unhandled command ${command}`);
+  }
+}
+
+if (isEntryModule(import.meta.url)) {
+  run(process.argv.slice(2), process.env).catch((error) => {
+    console.error(`[develop-edition] ${error.message}`);
+    process.exit(1);
+  });
+}