@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/develop-edition-resolve.mjs

@@ -0,0 +1,250 @@
+// develop-edition-resolve — resolve and seal one DEVELOP edition from a snapshot.
+//
+// The whole pipeline, in the order the release runs it (every check reports its refusal; see develop-resolve-report.mjs), over the snapshot's
+// injected inputs: distribution lock -> plane invariants (reservation table,
+// confinement; develop-edition-invariants.mjs) -> authorization base (composed, never
+// written) -> images lock -> develop seal, plus the chart-set lock: the frozen
+// deploy commit's develop chart set (develop-chart-set.mjs). Nothing here writes to the editions
+// trees; the caller writes the artifact (edition-artifact.mjs).
+//
+// What the resolve takes on trust and what it proves is its LANE's, never a flag of the resolve:
+//
+//   the channel lane (`developChannelLane`, `develop resolve --images-from --channel`, every deployment we run):
+//       the engine image is the caller's `--engine-image` digest; every first-party image digest is the build record's
+//       (images-from-record.mjs), satellites checked only for consistency with their producers' channel records; a
+//       git-sourced OCI bundle is taken by the digest its tag serves (develop-git-bundles.mjs
+//       `createDevelopGitBundleDigestReader`); the third-party pins are read as the data root holds them. No cosign,
+//       no content hash, no bundle-signer pre-check and no trust-pin read.
+//   the verified vendor lane of the catalogue-free customer resolve (develop-catalogue-free-vendor.mjs, the official
+//       lane): the engine found and cosign-proven, the images probed by computed content hash, the git-sourced bundles
+//       cosign-verified, the bundle signers asserted, the third-party pins held to the evidence trust pin.
+import { adapterHostRow, assertAdapterBundlesMatchHost, fetchRegistryManifest } from './adapter-bundled-versions.mjs';
+import { biomeSourceTreeIds, readBiomeSourceFacts, sealLock } from './biome-content.mjs';
+import { buildCatalogue } from './catalogue.mjs';
+import { resolveDevelopChartSet } from './develop-chart-set.mjs';
+import { assertDevelopEditionInvariants } from './develop-edition-invariants.mjs';
+import { createDevelopGitBundleDigestReader } from './develop-git-bundles.mjs';
+import { createDevelopImageProbe } from './develop-image-probe.mjs';
+import { BLOCKED, DevelopResolveCheck, RESOLVE_CHECK_DEPENDENCIES, createResolveReport } from './develop-resolve-report.mjs';
+import { assertFrozenCheckouts, buildDevelopSnapshotInputs } from './develop-snapshot-inputs.mjs';
+import { EditionChannel } from './edition-constants.mjs';
+import { sealImages } from './edition-image-seal.mjs';
+import { assertKernelEditionProtocol } from './edition-protocol.mjs';
+import { dataRoot, kernelPackageDir } from './edition-workspace.mjs';
+import { firstPartySources } from './first-party-source-ids.mjs';
+import { resolveImagesFromRecord, sealImagesFromRecord } from './images-from-record.mjs';
+import { kernelRowOfAuthority } from './kernel-package.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
+import { GitSourcedBundle, assertLockBundleSigners, isBundleSignerRefusal } from './locked-bundle-signer.mjs';
+import { admitDistributionLock, ungrantedOptionalLinesOfRefusal } from './operation-grant-admission.mjs';
+import { deployPinKey } from './pin-source.mjs';
+import { admitResolvedLock, composeAuthorizationBase, prepareDistributionWithIndex } from './resolve-distribution.mjs';
+import { externalSourceTrees, resolveImages, sourceTreeLocator } from './resolve-images.mjs';
+import { createPinnedSourceAuthority } from './source-authority.mjs';
+import { loadThirdPartySourcePins } from './third-party-source-pins.mjs';
+
+/**
+ * The steps the resolve runs, named so a test can stand in for the ones that
+ * need a real snapshot and observe that the later ones are never reached.
+ */
+export const DEVELOP_EDITION_STEPS = Object.freeze({
+  assertFrozenCheckouts,
+  buildSnapshotInputs: buildDevelopSnapshotInputs,
+  assertKernelEditionProtocol,
+  prepareDistributionWithIndex,
+  assertDevelopEditionInvariants,
+  assertAdapterBundlesMatchHost,
+  composeAuthorizationBase,
+  resolveImages,
+  sealImages,
+  sealImagesFromRecord,
+  resolveDevelopChartSet,
+});
+
+const stderrProgress = (line) => process.stderr.write(`${line}\n`);
+
+/**
+ * The first half of every develop resolve: the frozen snapshot's inputs and the
+ * distribution lock composed over them, NOT yet admitted. `resolveDevelopEdition`
+ * admits it as one of its checks; `resolveDevelopSnapshot` admits it at once. Both
+ * start here, so the content hash each computes for a subject is the same by construction.
+ */
+async function prepareDevelopSnapshot({ id, pins, steps, phase, developGitBundles }) {
+  const schemas = await loadKernelDistributionSchemas();
+  steps.assertFrozenCheckouts(pins);
+  const inputs = await steps.buildSnapshotInputs({ id, pins, schemas });
+  phase('snapshot inputs built');
+  const prepared = await steps.prepareDistributionWithIndex(id, { channel: EditionChannel.Develop, inputs: developGitBundles === undefined ? inputs : { ...inputs, developGitBundles } });
+  // The schemas the lock was composed with are the ones that admit it.
+  return { inputs, ...prepared };
+}
+
+/**
+ * The image-record snapshot: prepared as the resolve prepares it, then admitted (a refusal
+ * throws). It seals no distribution lock, so it verifies no git-sourced OCI bundle (no registry, no cosign): its lock
+ * rows of a git source carry none, which image-record does not read.
+ */
+export async function resolveDevelopSnapshot({ id, pins, steps = DEVELOP_EDITION_STEPS, phase = () => {} }) {
+  const snapshot = await prepareDevelopSnapshot({ id, pins, steps, phase });
+  admitResolvedLock(snapshot.schemas, snapshot.lock);
+  return snapshot;
+}
+
+/**
+ * The channel lane (see the header): what every deployment we run resolves with.
+ *
+ * @param {object} request
+ * @param {string} request.engineImage `<repository>@sha256:<64 hex>`, the caller's (already validated by the verb)
+ * @param {object} request.record the parsed image build record (`--images-from`)
+ * @param {Function} request.verifySatellites the channel check of its satellites (develop-channel-satellites.mjs)
+ */
+export function developChannelLane({ engineImage, record, verifySatellites }) {
+  return Object.freeze({
+    engineImage: async () => engineImage,
+    developGitBundles: createDevelopGitBundleDigestReader({ registryRoot: dataRoot() }),
+    checkBundleSigners: false,
+    thirdPartyPins: () => loadThirdPartySourcePins(dataRoot()),
+    imagesFrom: { record, verifySatellites },
+  });
+}
+
+const LANE_KEYS = Object.freeze(['engineImage', 'developGitBundles', 'checkBundleSigners', 'thirdPartyPins']);
+
+/** A lane names every choice; one it leaves out is a defect of the caller, never a default. */
+function assertLane(lane) {
+  const missing = LANE_KEYS.filter((key) => lane?.[key] === undefined);
+  if (missing.length > 0) {throw new Error(`resolveDevelopEdition: the lane names no ${missing.join(', ')}`);}
+  if (lane.imagesFrom !== undefined && (lane.imagesFrom.record === undefined || lane.imagesFrom.verifySatellites === undefined)) {
+    throw new Error('resolveDevelopEdition takes an image build record and its satellite check together');
+  }
+}
+
+/**
+ * @param {object} request
+ * @param {object} request.lane `developChannelLane(...)` or the catalogue-free vendor step's verified lane: the engine
+ *   image, the git-bundle reader or verifier, whether bundle signers are pre-checked, the third-party pins, and either
+ *   `imagesFrom` (digests from the build record, no probe and no hash) or none (the probe by computed content hash)
+ * @param {object|null} [request.previousLock] the previous edition's parsed images lock: its composed artifacts carry their generation forward (null: generation 1)
+ */
+export async function resolveDevelopEdition({ id, pins, lane, env = process.env, sealOptions = {}, fetchManifest = fetchRegistryManifest, progress = stderrProgress, steps = DEVELOP_EDITION_STEPS, declaredSources = firstPartySources('naming the develop repository of each first-party image'), previousLock = null }) {
+  assertLane(lane);
+  const { imagesFrom } = lane;
+  const startedAt = Date.now();
+  // One line per phase, with the time since the resolve began, so the step is never silent for long.
+  const phase = (name) => progress(`[develop-edition] ${name} (+${Date.now() - startedAt}ms)`);
+  // Every check runs unless a check it needs was refused; all refusals are reported together, and nothing is sealed or written then.
+  const report = createResolveReport();
+  const checked = (check, fn, options) => report.run(check, RESOLVE_CHECK_DEPENDENCIES[check], fn, options);
+  const chartSetLock = await checked(DevelopResolveCheck.ChartSet, async () => {
+    const chartSet = await steps.resolveDevelopChartSet({ xemaDeploySha: pins[deployPinKey()] });
+    phase('chart set resolved');
+    return chartSet;
+  });
+  const engineImage = await checked(DevelopResolveCheck.EngineImage, async () => {
+    const image = await lane.engineImage();
+    phase('engine image resolved');
+    return image;
+  });
+  await checked(DevelopResolveCheck.EditionProtocol, () => steps.assertKernelEditionProtocol(kernelPackageDir()));
+  // A git-sourced biome's OCI bundle, by the lane's reader (by digest) or verifier (develop-git-bundles.mjs).
+  const snapshot = await checked(DevelopResolveCheck.DistributionLock, () => prepareDevelopSnapshot({ id, pins, steps, phase, developGitBundles: lane.developGitBundles }), {
+    classify: (error) => (isBundleSignerRefusal(error) ? DevelopResolveCheck.BundleSigner : DevelopResolveCheck.DistributionLock),
+  });
+  const lockProduced = snapshot !== BLOCKED;
+  const { schemas, inputs, lock, index } = lockProduced ? snapshot : {};
+  if (lockProduced && lane.checkBundleSigners) {
+    await checked(DevelopResolveCheck.BundleSigner, () => assertLockBundleSigners({ lock, schemas, gitSourcedBundle: GitSourcedBundle.DevelopVerified }));
+  }
+  // The plane invariants, against the graph this candidate froze (develop-edition-invariants.mjs).
+  await checked(DevelopResolveCheck.PlaneInvariants, () => {
+    const graded = steps.assertDevelopEditionInvariants({ id, lock, biomeIndex: inputs.biomeIndex, schemas });
+    phase(`reservation table asserted (${graded.reservedDomains} domains); confinement asserted (${graded.confinedBiomes} declaration(s))`);
+  });
+  await checked(DevelopResolveCheck.OperationAdmission, () => {
+    try {
+      admitDistributionLock(schemas, lock, { report: (line) => report.notice(line) });
+    } catch (error) {
+      ungrantedOptionalLinesOfRefusal(error).forEach((line) => report.notice(line));
+      throw error;
+    }
+    phase('operation requirements admitted');
+  });
+  await checked(DevelopResolveCheck.AdapterBundles, () => steps.assertAdapterBundlesMatchHost({ lock, hostRow: adapterHostRow(index), fetchManifest }));
+  const authorizationLock = await checked(DevelopResolveCheck.AuthorizationBase, async () => {
+    const composed = await steps.composeAuthorizationBase(id, lock, index);
+    phase('distribution lock resolved');
+    return composed;
+  });
+  // Every subject's develop image is probed the moment its hash is known, in
+  // parallel with the hashing of the rest; an absent image refuses here, naming
+  // all of them, before any later phase runs.
+  let recorded;
+  const imageLock = await checked(DevelopResolveCheck.DevelopImages, async () => {
+    if (imagesFrom !== undefined) {
+      const fromRecord = await resolveImagesFromRecord({ id, inputs, lock, record: imagesFrom.record, resolveImages: steps.resolveImages, verifySatellites: imagesFrom.verifySatellites, previousLock });
+      ({ recorded } = fromRecord);
+      phase(`image subjects taken from the build record (${fromRecord.imageLock.subjects.length} subjects); satellites checked against their channel records`);
+      return fromRecord.imageLock;
+    }
+    const probe = createDevelopImageProbe({
+      distributionId: id,
+      declaredSources,
+      env,
+      ...(sealOptions.distributionsRoot === undefined ? {} : { distributionsRoot: sealOptions.distributionsRoot }),
+      ...(sealOptions.fetchImpl === undefined ? {} : { fetchImpl: sealOptions.fetchImpl }),
+      ...(sealOptions.run === undefined ? {} : { run: sealOptions.run }),
+      progress,
+    });
+    const resolved = await steps.resolveImages(id, { inputs, lock, onSubjectHashed: probe.observe, previousLock });
+    phase(`image content hashes computed (${resolved.imageLock.subjects.length} subjects)`);
+    await probe.settle();
+    phase('every develop image is present');
+    return resolved.imageLock;
+  });
+  try {
+    report.settle();
+  } catch (error) {
+    progress(error.message);
+    throw error;
+  }
+  if (report.noticeText() !== '') {progress(report.noticeText());}
+  const sealArguments = { imageLock, declaredSources, env, progress, thirdPartyPins: lane.thirdPartyPins(), ...sealOptions };
+  const sealedImageLock = recorded === undefined
+    ? await steps.sealImages({ channel: EditionChannel.Develop, ...sealArguments })
+    : await steps.sealImagesFromRecord({ ...sealArguments, recorded });
+  phase('images sealed');
+  // 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 biomeSources = {
+    schemas,
+    imageLock: sealedImageLock,
+    locate: sourceTreeLocator(externalSourceTrees(lock)),
+    vendoredCommit: (repo) => authority.vendoredSourceCommitForRepository(repo),
+  };
+  // ONE walk of the biome checkouts: the content hashes and the tree ids both read it.
+  const sourceFactsById = await readBiomeSourceFacts({ ...biomeSources, lock });
+  phase(`biome sources read (${sourceFactsById.size} biomes)`);
+  const sealedLock = await sealLock({ ...biomeSources, unsealed: lock, sourceFactsById, gitSourcedBundle: GitSourcedBundle.DevelopVerified });
+  phase('distribution lock sealed');
+  const sourceTreeIds = await biomeSourceTreeIds({ ...biomeSources, lock, sourceFactsById });
+  const catalogue = buildCatalogue({
+    sourceTreeIds,
+    offeringId: id,
+    channel: EditionChannel.Develop,
+    distributionLock: lock,
+    imageLock: sealedImageLock,
+    chartSetLock,
+    biomeIndex: inputs.biomeIndex,
+    platformServiceIndex: inputs.platformServiceIndex,
+    contractAuthority: inputs.runtimeImageSourceIndex.contractAuthority,
+    kernel: await kernelRowOfAuthority({
+      channel: EditionChannel.Develop,
+      kernelPackageDir: kernelPackageDir(),
+      contractAuthority: inputs.runtimeImageSourceIndex.contractAuthority,
+    }),
+    leaf: inputs.composed.leaf,
+  });
+  phase('catalogue built');
+  return { distributionLock: sealedLock, imageLock: sealedImageLock, authorizationLock, chartSetLock, catalogue, engineImage };
+}

package/edition/develop-edition.mjs

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+// develop-edition — the develop edition's command line.
+//
+// The vendor verbs are the CHANNEL lane every deployment we run uses: images by digest from their producers' build
+// records, read through a registry channel tag, and nothing else. No cosign, no signature or attestation check, no
+// content-hash recomputation, no lock-algorithm check, no seal verification. The customer forms (`--definition`,
+// `--definition-at`) are the official lane and keep their verification.
+//
+//   select-records --branch develop --channel <tag> --out <file>
+//       for every develop-graph member that does not keep its current resolution, read the one manifest
+//       <root>/build-records/<name>:<tag> (a tag the producer's CI moves to its newest green record; tags are never
+//       listed, so <root> may be a pull-through proxy), parse its single build-record layer with the CLI's own
+//       @xemahq/contracts BuildRecordSchema (select-records takes no --kernel: it runs before any member pin exists) and hold it to the member (its producer repository, branch develop). The selection is
+//       { channel, pins, snapshot, images, currentResolution }, written once (wx); images[] entries carry `member`, the
+//       owning repo handle, and the record's digest and contentHash. Each member prints
+//       `<short name>: channel <tag> -> record <12-hex commit> (run <run>)`, a member that keeps its current resolution
+//       (a declared currentResolution, develop-current-resolution.mjs) `xema-docs: current resolution (leaves the edition,
+//       XEMA-2373)` with no registry read. A missing tag or a malformed record refuses the whole run naming the member and
+//       writes nothing (develop-select-records.mjs).
+//   freeze-graph --data-sha <sha>
+//                --deploy-sha <sha> [--editions-root-url <https url>]
+//                [--overrides <json> | --member-pins <selection file>] --out <file>
+//       resolve refs/heads/develop once per develop-graph repository (the data root's
+//       firstPartySources, at each declared URL) and the editions root; the three checked-out
+//       repositories are pinned at what the workflow checked out; write the pins. --member-pins takes a select-records
+//       selection (only .pins, 40-hex, is read) and pins each graph member at its selected record commit instead of its
+//       develop head: the selection must pin exactly the graph minus its currentResolution members (which must equal
+//       the graph members' declared currentResolution), a missing or extra member is refused by name, and a currentResolution
+//       member is pinned at its develop head. --member-pins together with --overrides is refused. The kernel comes from the
+//       pinned xema-base member checkout (--kernel names its contracts at the folded path, kernel-pin-source.mjs): the
+//       kernel pin is that member's pin, and --kernel-sha is refused. The pin must declare an edition protocol this CLI
+//       supports (the check choose-kernel applies to a pin).
+//   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.
+//   image-record <id> --selection <file> --pins <file> --out <file> --channel <tag>
+//       write the edition's image build record (the file `resolve --images-from` reads) from a `select-records --channel
+//       <tag>` selection (develop-image-record.mjs). The subjects are the checked-out snapshot's first-party image
+//       subjects, enumerated with the selection standing in for every hash: each takes the selection's image of its
+//       develop repository (digest AND contentHash), whose selected commit must be the snapshot's, and goes in
+//       `satellites`, checked against its producer's <tag> record as `resolve` checks it. The one declared exception: a
+//       subject of a member that keeps its current resolution (XEMA-2373) has no build record, so its content hash is
+//       computed and its develop image probed by it, and it goes in `images`. Platforms are read from the registry by
+//       digest. Any subject without an image, any commit mismatch refuses the whole run and writes nothing, once (wx).
+//       Third-party subjects are ignored. Takes the roots `resolve` takes.
+//   target  <id> --pins <file> --registry <root> --engine-image <repository>@sha256:<digest> [--images-from <image build record>]
+//       print <root>/<develop segment>/xema-edition-<id>:<tag>, the tag being sha256 of the canonical
+//       { cli, engine, pins, sourceImages } (snapshotEditionTag): every input of the bytes the artifact records,
+//       so the same pins with another engine, source-image map or edition-tooling version are another artifact. With
+//       --images-from the record's digest (imageBuildRecordDigest) is one more input, named imageBuildRecord; resolve
+//       prints the same target. The root is always the caller's registry root (e.g. registry.example.com/acme); the
+//       develop namespace segment and the repository prefix come from edition-contract.json, and no root is implied.
+//   check-existing <id> --pins <file> --artifact <dir> --engine-image <repository>@sha256:<digest>
+//       refuse to reuse a pulled artifact whose descriptor disagrees with this snapshot (its evidence trust the channel
+//       lane's `not-armed`, develop-channel-evidence.mjs).
+//   resolve <id> --pins <file> --out <dir> --registry <root> --engine-image <repository>@sha256:<digest>
+//           --images-from <image build record> --channel <tag> --selection <select-records file>
+//           (--previous-lock <file> --previous-lock-sha256 <hex> | --first-seal) [--local]
+//       resolve the edition from the snapshot, write the descriptor and the four locks to <dir>, print the target. The
+//       engine is the --engine-image digest, recorded as given. Every first-party digest is the build record's
+//       (images-from-record.mjs): no probe and no hash; a subject missing, duplicated or extra in the record refuses.
+//       Each satellite must be listed, {name, digest}, by its producer's build record at the commit the snapshot pins
+//       (develop-channel-satellites.mjs): the record --selection pinned, read by its own record tag
+//       <root>/build-records/<name>:<branch>-<run>-<attempt>, so a channel that moved after selection does not affect
+//       the run. The selection must have been selected through --channel. A git-sourced OCI bundle is taken by the
+//       digest its tag serves (develop-git-bundles.mjs). The evidence verifier and its data-root pin are not loaded: the
+//       descriptor records evidenceTrustPolicy not-armed, stated on stderr (develop-channel-evidence.mjs). The previous
+//       seal is the edition's last images lock, held to the sha256 of its bytes and to the id, or --first-seal. Every
+//       refusal of the run is reported in one table (develop-resolve-report.mjs): independent checks all run, a
+//       dependent one is reported `blocked by <check>`, and when anything is refused nothing is sealed or written. The
+//       workflow run is recorded from GITHUB_REPOSITORY / GITHUB_RUN_ID; --local stamps `local` instead.
+//   resolve --definition <file> --pins <file> --out <dir> --registry <root>
+//           --engine-image <repository>@sha256:<digest> [--source-image <source>=<registry>/<prefix>]...
+//           [--catalogue-username <name> --catalogue-token-env <VAR>] [--cosign <absolute-path>] [--local]
+//       a CUSTOMER develop edition (official lane): the definition resolved against the develop catalogue pinned in
+//       catalogue.pin.json beside it (see catalogue-pin.mjs and resolve-customer-edition.mjs), frozen at the
+//       customer's own pins. --pins holds exactly one `sources/<name>` commit per source the definition
+//       declares (`freeze-sources --definition` writes it); 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, --cache-dir (no --deploy-root, no --kernel: the kernel is the catalogue's, from npm).
+//       It takes the customer edition's OWN previous seal, exactly one of --previous-lock <file> --previous-lock-sha256 <hex>
+//       (the customer edition's last images lock: sha256 of its bytes, its id the definition's) or --first-seal; it carries
+//       the generations of the customer's own composed artifacts forward (vendor rows are the catalogue's, unchanged).
+//   resolve --definition-at <owner>/<repo>,<path>,<dataRoot> --offering <owner>/<repo>,<path>,<dataRoot>
+//           --pins <file> --out <dir> --registry <root> --engine-repository <repository> --engine-signer <certificate identity>
+//           --cosign <absolute-path> --offering-previous-lock <file> --offering-previous-lock-sha256 <hex>
+//           (--previous-lock <file> --previous-lock-sha256 <hex> | --first-seal) [--source-image <source>=<registry>/<prefix>]... [--local]
+//       a CATALOGUE-FREE customer develop edition (official lane, develop-catalogue-free-resolve.mjs): the vendor
+//       offering named by --offering (its directory in the vendor data checkout) is resolved first by the vendor step
+//       (develop-catalogue-free-vendor.mjs, a child of this CLI on the vendor roots, NOT the vendor `resolve` verb) on
+//       the verified lane: the engine found and cosign-proven from --engine-repository/--engine-signer, the images probed
+//       by content hash, the git-sourced bundles cosign-verified, sealed against the OFFERING's previous seal
+//       (--offering-previous-lock, held to its sha256 and the offering's id); then the definition, read from its
+//       repository at --pins "definition-repository", is resolved against the catalogue that step wrote, on its own
+//       roots, carrying the customer's own composed generations from --previous-lock (or --first-seal). --pins is the
+//       complete frozen set (the vendor pins, the definition's sources/<name>, "definition-repository"); no head is read
+//       and nothing is pushed. The edition pins those and the definition digest, no catalogue (the catalogue's content
+//       digest is in the distribution lock only), and records the vendor step's engine. catalogue.pin.json beside the
+//       definition is refused. Takes the vendor roots.
+//   target  --definition <file> --pins <file> --registry <root> --engine-image <repository>@sha256:<digest>
+//           [--source-image <source>=<registry>/<prefix>]...
+//       the same for a customer edition (id = the definition's; the tag covers the pinned catalogue digest).
+//   check-existing --definition <file> --pins <file> --artifact <dir> --engine-image <repository>@sha256:<digest>
+//                  [--catalogue-username <name> --catalogue-token-env <VAR>] [--source-image <source>=<registry>/<prefix>]...
+//       the same for a customer artifact; its descriptor's catalogue provenance pin must also equal the
+//       pinned develop catalogue digest, and its own image rows must be the rows the --source-image map composes. It fetches that catalogue (as `resolve --definition` does) to take the
+//       kernel from it. Takes --data-root, --cache-dir.
+//   freeze-sources --definition <file> --out <file>
+//       a CUSTOMER edition: one `sources/<name>` pin per source the definition declares, each the head of
+//       refs/heads/develop of that source's repository, resolved once; written exclusively (wx).
+//   choose-kernel [--kernel-pin <40-hex>] --out <file>
+//       choose the develop kernel commit in the --kernel checkout (full history; its refs/remotes/origin/develop is the develop head):
+//       the newest first-parent commit whose declared edition protocol this CLI supports
+//       (kernel-protocol-choice.mjs). Writes {chosenSha, headSha, held, reason} (reason: head-supported |
+//       head-ahead | explicit-pin); when held, prints `kernel held at v<N> (<sha12>), head at v<M> (<sha12>):
+//       raise the CLI` to stdout (never persisted). A pin wins and is still checked; nothing supported is refused.
+//       Takes only --kernel (the checkout need not be built).
+//   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.
+//
+// Tokens come from the environment (EVIDENCE_REPOSITORIES_TOKEN, XEMA_GHCR_PULL_TOKEN),
+// never argv. Nothing here writes git or publishes a release edition.
+
+import { resolve } from 'node:path';
+
+import { writeCatalogue } from './catalogue.mjs';
+import { CHANNEL_FLAG, CUSTOMER_ROOTS, DEVELOP_VENDOR_ROOTS, FIRST_SEAL_FLAG, IMAGES_FROM_FLAG, PREVIOUS_LOCK_FLAG, PREVIOUS_LOCK_SHA256_FLAG, SELECTION_FLAG, SELECT_RECORDS_ROOTS, headResolver, parseEditionVerbArgs, runCustomerVerb, writeOnce } from './customer-edition-verbs.mjs';
+import { DEFINITION_FLAG } from './customer-flags.mjs';
+import { resolveCatalogueFree } from './develop-catalogue-free-resolve.mjs';
+import { DEVELOP_CHANNEL_EVIDENCE_TRUST, developResolveEvidenceTrust } from './develop-channel-evidence.mjs';
+import { createChannelSatelliteVerifier } from './develop-channel-satellites.mjs';
+import { developChannelLane, resolveDevelopEdition } from './develop-edition-resolve.mjs';
+import { assertNoToolingOverride, freezeGraph, freezeSources } from './develop-freeze.mjs';
+import { developGraphMembers } from './develop-graph.mjs';
+import { parseSelection, runImageRecord } from './develop-image-record.mjs';
+import { runSelectRecords } from './develop-select-records.mjs';
+import { readSelectionPins } from './develop-selection-pins.mjs';
+import { LOCAL_WORKFLOW, assertExistingArtifactMatches, developEditionTarget, workflowFromEnv, writeEditionArtifact } from './edition-artifact.mjs';
+import { EditionChannel } from './edition-constants.mjs';
+import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, kernelRepoDir, sourcePath } from './edition-workspace.mjs';
+import { ImageBuildRecordError, imageBuildRecordDigest, readImageBuildRecord } from './images-from-record.mjs';
+import { kernelMemberOf } from './kernel-pin-source.mjs';
+import { assertKernelCommitSupported, chooseKernelCommit } from './kernel-protocol-choice.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
+import { kernelPinKey, snapshotPinSource } from './pin-source.mjs';
+import { composeEdition } from './resolve-distribution.mjs';
+import { resolvePreviousSeal } from './resolve-images.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+// The roots a verb takes. A customer form (it names --definition) takes fewer, and never the kernel (the
+// catalogue's kernel is downloaded from npm into the cache root): `target` none, `check-existing` the data
+// root and the cache, `freeze-sources` the data root only, `resolve` all but the deploy root. `check-overrides`
+// takes only the data root in either form: it judges its --overrides JSON against the pin roles the data
+// root declares, so it reads nothing else and refuses every other root flag.
+const DATA_ROOT_ONLY_COMMANDS = Object.freeze(['check-overrides']);
+// `choose-kernel` reads the kernel checkout's git history only, before the kernel is built.
+const KERNEL_ROOT_ONLY_COMMANDS = Object.freeze(['choose-kernel']);
+
+if (isEntryModule(import.meta.url)) {
+  const [command] = process.argv.slice(2);
+  if (DATA_ROOT_ONLY_COMMANDS.includes(command)) {
+    configureEditionWorkspaceFromProcess([WorkspaceRoot.Data], { refuseOthers: true });
+  } else if (command === 'select-records') {
+    configureEditionWorkspaceFromProcess(SELECT_RECORDS_ROOTS, { refuseOthers: true });
+  } else if (KERNEL_ROOT_ONLY_COMMANDS.includes(command)) {
+    configureEditionWorkspaceFromProcess([WorkspaceRoot.Kernel], { refuseOthers: true });
+  } else {
+    const customerForm = process.argv.includes(DEFINITION_FLAG);
+    configureEditionWorkspaceFromProcess(customerForm ? (CUSTOMER_ROOTS[command] ?? DEVELOP_VENDOR_ROOTS) : DEVELOP_VENDOR_ROOTS, {
+      refuseOthers: customerForm && CUSTOMER_ROOTS[command] !== undefined,
+    });
+  }
+}
+
+/** Parse `<command> [<id>] --flag value ...` against the closed vocabulary of the develop command. */
+export const parseDevelopEditionArgs = (argv) => parseEditionVerbArgs(EditionChannel.Develop, argv);
+
+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;
+}
+
+/** The target-tag input of `--images-from`: the record's digest, or nothing when the caller names no record. */
+async function imageBuildRecordTagInput(options) {
+  return options[IMAGES_FROM_FLAG] === undefined ? {} : { imageBuildRecordDigest: imageBuildRecordDigest(await readImageBuildRecord(options[IMAGES_FROM_FLAG])) };
+}
+
+/** The `--selection` the run's image record came from, held to `--channel`. */
+function readChannelSelection(options) {
+  const path = options[SELECTION_FLAG];
+  const selection = parseSelection(readStrictJsonFile(path), developGraphMembers(), path);
+  if (selection.channel !== options[CHANNEL_FLAG]) {
+    throw new ImageBuildRecordError(`selection ${path} was selected through channel ${selection.channel}, not ${options[CHANNEL_FLAG]}`);
+  }
+  return selection;
+}
+
+/** The vendor resolve: the channel lane (develop-edition-resolve.mjs `developChannelLane`). */
+async function resolveVendor({ id, options, env }) {
+  const pins = readStrictJsonFile(options['--pins']);
+  const workflow = options['--local'] ? LOCAL_WORKFLOW : workflowFromEnv(env);
+  const evidenceTrustPolicy = developResolveEvidenceTrust();
+  const record = await readImageBuildRecord(options[IMAGES_FROM_FLAG]);
+  const { catalogue, engineImage, ...resolved } = await resolveDevelopEdition({
+    id,
+    pins,
+    env,
+    lane: developChannelLane({
+      engineImage: options['--engine-image'],
+      record,
+      verifySatellites: createChannelSatelliteVerifier({ channel: options[CHANNEL_FLAG], selection: readChannelSelection(options), env }),
+    }),
+    previousLock: await resolvePreviousSeal({
+      distributionId: id,
+      previousLockPath: options[PREVIOUS_LOCK_FLAG],
+      previousLockSha256: options[PREVIOUS_LOCK_SHA256_FLAG],
+      firstSeal: Boolean(options[FIRST_SEAL_FLAG]),
+    }),
+  });
+  const target = developEditionTarget(id, pins, { registry: options['--registry'], engineImage, imageBuildRecordDigest: imageBuildRecordDigest(record) });
+  const outDir = resolve(options['--out']);
+  writeEditionArtifact({
+    outDir,
+    channel: EditionChannel.Develop,
+    distributionId: id,
+    pins,
+    workflow,
+    evidenceTrustPolicy,
+    engineImage,
+    ...resolved,
+  });
+  writeCatalogue(outDir, catalogue);
+  console.log(target);
+}
+
+async function run(argv, env) {
+  const { command, id, options, customer, catalogueFree } = parseDevelopEditionArgs(argv);
+  switch (command) {
+    case 'target': {
+      if (customer) {return runCustomerVerb({ channel: EditionChannel.Develop, command, options, env });}
+      console.log(developEditionTarget(id, readStrictJsonFile(options['--pins']), { registry: options['--registry'], engineImage: options['--engine-image'], ...(await imageBuildRecordTagInput(options)) }));
+      return;
+    }
+    case 'resolve': {
+      if (customer) {return runCustomerVerb({ channel: EditionChannel.Develop, command, options, env });}
+      if (catalogueFree) {
+        await resolveCatalogueFree({ options, env });
+        return;
+      }
+      await resolveVendor({ id, options, env });
+      return;
+    }
+    case 'select-records':
+      await runSelectRecords({ options, env });
+      return;
+    case 'image-record':
+      await runImageRecord({ id, options, env });
+      return;
+    case 'check-existing': {
+      if (customer) {return runCustomerVerb({ channel: EditionChannel.Develop, command, options, env });}
+      assertExistingArtifactMatches({
+        artifactDir: resolve(options['--artifact']),
+        distributionId: id,
+        channel: EditionChannel.Develop,
+        evidenceTrustPolicy: DEVELOP_CHANNEL_EVIDENCE_TRUST,
+        pins: readStrictJsonFile(options['--pins']),
+        engineImage: options['--engine-image'],
+      });
+      return;
+    }
+    case 'check-overrides': {
+      assertNoToolingOverride(parseOverrides(options['--overrides']));
+      return;
+    }
+    case 'choose-kernel': {
+      const { choice, notice } = chooseKernelCommit({ repoDir: kernelRepoDir(), pin: options['--kernel-pin'] });
+      writeOnce(options['--out'], choice);
+      if (notice !== undefined) {console.log(notice);}
+      return;
+    }
+    case 'freeze-graph': {
+      const channel = EditionChannel.Develop;
+      const kernelMember = kernelMemberOf({ members: developGraphMembers(), kernelRepoDir: kernelRepoDir(), sourcePath }).repo;
+      const pins = freezeGraph({
+        channel,
+        dataSha: options['--data-sha'],
+        kernelMember,
+        kernelSha: options['--kernel-sha'],
+        deploySha: options['--deploy-sha'],
+        editionsRootUrl: options['--editions-root-url'],
+        overrides: parseOverrides(options['--overrides']),
+        ...(options['--member-pins'] === undefined ? {} : { memberPins: readSelectionPins(options['--member-pins'], '--member-pins', developGraphMembers()) }),
+        ...headResolver(EditionChannel.Develop, env),
+      });
+      const kernelPin = pins[kernelPinKey()];
+      assertKernelCommitSupported({ repoDir: kernelRepoDir(), commit: kernelPin, label: `the kernel pin ${kernelPin} (the pin of ${kernelMember})` });
+      writeOnce(options['--out'], pins);
+      return;
+    }
+    case 'freeze-sources': {
+      if (customer) {return runCustomerVerb({ channel: EditionChannel.Develop, command, options, env });}
+      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']), ...headResolver(EditionChannel.Develop, env) }),
+      );
+      return;
+    }
+    default:
+      throw new Error(`unhandled command ${command}`);
+  }
+}
+
+if (isEntryModule(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  run(argv, process.env).then(
+    (code) => {
+      if (typeof code === 'number') {process.exitCode = code;}
+    },
+    (error) => {
+      console.error(`[develop-edition] ${error.message}`);
+      process.exit(1);
+    },
+  );
+}