@xemahq/xema 0.59.0 → 0.60.1

package/edition/develop-edition.mjs

@@ -1,379 +0,0 @@
-#!/usr/bin/env node
-// develop-edition — the develop edition's command line.
-//
-//   resolve <id> --pins <file> --out <dir> --registry <root>
-//           --engine-repository <repository> --engine-signer <certificate identity> --cosign <absolute-path> [--local]
-//           [--images-from <image build record>]
-//       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 engine is found and proven here (see `engine`), and 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.
-//       --images-from takes the digests from the everyday job's image build record instead of the registry probe:
-//       no probe and no rehash; satellite entries are cosign-verified against their producer's develop build
-//       records, and a subject missing, duplicated or extra in the record refuses (images-from-record.mjs).
-//       The workflow run is recorded from GITHUB_REPOSITORY / GITHUB_RUN_ID;
-//       --local stamps `local` instead, for a resolve outside GitHub Actions.
-//   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>] [--local]
-//       a CUSTOMER develop edition: 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 (develop-catalogue-free-resolve.mjs): the vendor offering named by
-//       --offering (its directory in the vendor data checkout) is resolved first by a child `resolve` on the vendor
-//       roots, sealed against the OFFERING's previous seal (--offering-previous-lock, as `follow` froze it, held to its
-//       sha256 and the offering's id) with the engine it finds and proves; then the definition, read from its repository at
-//       --pins "definition-repository", is resolved against the catalogue that child 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.
-//   engine  <id> --pins <file> --engine-repository <repository> --engine-signer <certificate identity> --cosign <absolute-path>
-//       print <repository>@sha256:<digest>: the engine xema-deploy CI published (tag sha-<12 hex>) for the
-//       snapshot's xema-deploy commit, its signature verified offline against the pinned trust root as made by
-//       --engine-signer with the signed annotations commit=<that commit> and branch=develop
-//       (develop-engine-image.mjs). The image `target` and `check-existing` take as --engine-image.
-//   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 CLI version are another artifact. With
-//       --images-from the record's digest (imageBuildRecordDigest) is one more input, named imageBuildRecord; resolve
-//       --images-from 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.
-//   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).
-//   freeze-graph --data-sha <sha> --kernel-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. --kernel-sha is refused
-//       unless its declared edition protocol is one this CLI supports (the check choose-kernel applies to a pin).
-//   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-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.
-//   coverage <id> --pins <file> --cosign <absolute-path> [--json]
-//       READ-ONLY: for every image subject of the snapshot, whether its develop image is producer-signed
-//       in the form T72 resolve accepts (attested | signature-verified | no-row | unsigned |
-//       annotations-missing | annotation-mismatch | not-built). Prints a table grouped by producer repo
-//       and `covered N/M` (--json: the same as data). Exit 0 only when every subject is covered, 1 when
-//       not, 2 on an operational error. Takes the roots `resolve` takes; writes nothing.
-//   verify-image-record --image <name>@sha256:<digest> --producer <owner/repo> --registry <root> --cosign <absolute-path>
-//       whether an authenticated develop build record of the producer lists exactly this image name and digest: the
-//       producer's records are read newest run first and verified as select-records verifies them (shared core); a record of a
-//       workflow other than the producer's `.github/workflows/ci.yaml` is skipped, and the newest ci.yaml record that lists the image answers.
-//       Prints { image, digest, producer, commit }: commit is that of the newest verified ci.yaml record (by run number, then attempt)
-//       that lists the digest; it can be an older commit when a later run targeted it, which is safe because the digest binds the bytes.
-//       Refuses (exit 1) when no ci.yaml record lists the image, the record
-//       names another producer, or cosign refuses the identity. Takes the roots `resolve` takes.
-//   select-records --branch develop --registry <root> --cosign <absolute-path> --out <file> [--at <ISO-8601 UTC>] [--published-pins <file>]
-//       for every develop-graph member, take the newest build record the data root's record workflow signed for
-//       the branch (<root>/build-records/<name>, verified offline by digest against the pinned trusted root, as
-//       signed by <data root>/.github/workflows/record-build.yaml at refs/heads/<branch>, called by the member at the
-//       record's own commit) and write { pins, snapshot, behind, images, currentResolution }, once (wx); a member that keeps its current resolution (a declared currentResolution, develop-current-resolution.mjs) is skipped with no registry read, listed in currentResolution, and printed as `xema-docs: current resolution (leaves the edition, XEMA-2373)`; behind is { <repo>: { head, commits } }, develop's head and how many commits the selected one trails it by, and one line per member `<short name>: record <commit>, <N> commits behind HEAD` goes to stdout (always `commits`; short name = the repo's last path segment, refused when two members share one); images[] entries carry `member`, the owning repo handle. Any missing, unsigned, mismatched or
-//       unreadable record refuses the whole run and writes nothing: a newer bad record is never skipped for an older
-//       one. --at takes the newest record completed at or before that time. Only `develop` has a declared signer; the
-//       data root must declare dataRootRepositoryUrl. Takes the roots `resolve` takes (no registry root is implied).
-//       "Newest" is the newest COMMIT on develop, not the highest run: EVERY record of the branch is read and cosign-verified,
-//       the selected commit must equal or descend from every other record's commit (git merge-base on develop fetched
-//       from the member), and among that commit's records the highest run and attempt wins. --published-pins takes a file
-//       this verb wrote (only .pins is read): a member's published commit is kept when the records are not ahead of it
-//       (its own record must exist), a diverged one is refused. Without the flag the rule applies among the records only;
-//       part 07 passes the flag.
-//       Residual: anyone who can delete registry tags can remove newer records, and this then pins the newest remaining
-//       valid one; the guard is part 07's, deploy-latest's owner refuses a snapshot that goes backwards.
-//   follow --definition-at <owner>/<repo>,<path>,<dataRoot> --data-sha <sha> --kernel-sha <sha> --deploy-sha <upper bound>
-//          --engine-repository <registry>/<path> --registry <root> --cosign <absolute-path> (--first | --current-pins <file>) --out <file>
-//       the pins a dev deployment's follow policy selects (develop-follow.mjs), written once (wx) as the COMPLETE frozen
-//       set `resolve` reads; nothing else is read or written. The data root checkout is the definition: the data root's
-//       declared repository, clean at --data-sha, its data root and distribution directory at dataRoot and path, and the
-//       editions root that same repository; the kernel checkout is at --kernel-sha. Members: select-records' newest-commit
-//       rule over their signed build records (the same verifier), with the --current-pins as the published pins (behind or
-//       equal keeps the current pin, diverged is refused by name), pinned as freeze-graph --member-pins pins them (a member
-//       that keeps its current resolution at its develop head). Deploy root: --deploy-sha is an UPPER BOUND, the pin the
-//       newest first-parent commit of the deploy checkout at or below it whose engine <--engine-repository>:sha-<12 hex> is
-//       published (unpublished skipped and counted, none within the walk limit refused by name). Tooling roots:
-//       freeze-graph's rules, then each classified against its current pin by ancestry in its own checkout (behind,
-//       diverged or absent from the checkout is refused by type). Declared sources: their develop heads, newer-wins
-//       against the current pin by the same ancestry rule. Prints {distributionId, definition, follow: first |
-//       from-current, tooling, advanced, kept, added, dropped, deploy: {deploySha, upperBound, skipped}}: --first says so
-//       and classifies nothing. Takes the roots `resolve` takes.
-//   image-record <id> --selection <file> --pins <file> --out <file>
-//       write the edition's image build record (the file `resolve --images-from` reads) from a select-records selection:
-//       the subjects are the checked-out snapshot's first-party image subjects (enumerated as `coverage` does). A subject of
-//       a member that keeps its current resolution (a declared currentResolution, develop-current-resolution.mjs) is probed as resolve probes it
-//       and goes in `images`; every other first-party subject takes the selection's image of its develop repository, whose
-//       selected commit must be the snapshot's, and goes in `satellites`. 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.
-//   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.
-//   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.
-//   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).
-//
-// 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 { CUSTOMER_ROOTS, FIRST_SEAL_FLAG, IMAGES_FROM_FLAG, PREVIOUS_LOCK_FLAG, PREVIOUS_LOCK_SHA256_FLAG, 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 { runDevelopCoverage } from './develop-coverage-run.mjs';
-import { CoverageExit } from './develop-coverage.mjs';
-import { resolveDevelopEdition } from './develop-edition-resolve.mjs';
-import { resolveDevelopEngineImage } from './develop-engine-image.mjs';
-import { runFollow } from './develop-follow.mjs';
-import { assertNoToolingOverride, freezeGraph, freezeSources } from './develop-freeze.mjs';
-import { developGraphMembers } from './develop-graph.mjs';
-import { runImageRecord } from './develop-image-record.mjs';
-import { runSelectRecords } from './develop-select-records.mjs';
-import { readSelectionPins } from './develop-selection-pins.mjs';
-import { runVerifyImageRecord } from './develop-verify-image-record.mjs';
-import { LOCAL_WORKFLOW, assertExistingArtifactMatches, developEditionTarget, editionRepository, workflowFromEnv, writeEditionArtifact } from './edition-artifact.mjs';
-import { EditionChannel, EditionKind } from './edition-constants.mjs';
-import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, kernelRepoDir } from './edition-workspace.mjs';
-import { descriptorEvidenceTrust } from './evidence-trust-policy.mjs';
-import { createSatelliteVerifier, imageBuildRecordDigest, readImageBuildRecord } from './images-from-record.mjs';
-import { assertKernelCommitSupported, chooseKernelCommit } from './kernel-protocol-choice.mjs';
-import { loadKernelDistributionSchemas } from './lib.mjs';
-import { snapshotPinSource } from './pin-source.mjs';
-import { PREVIOUS_SEAL_SIGNER_FLAG, previousSealFromRegistry } from './previous-seal-registry.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 VENDOR_ROOTS = Object.freeze([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Deploy, WorkspaceRoot.Cache]);
-// `coverage` is the P2b gate: 1 means "not covered", so an operational error is a distinct 2.
-const COVERAGE_COMMAND = 'coverage';
-const COVERAGE_OPERATIONAL_EXIT = CoverageExit.Operational;
-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 (KERNEL_ROOT_ONLY_COMMANDS.includes(command)) {
-    configureEditionWorkspaceFromProcess([WorkspaceRoot.Kernel], { refuseOthers: true });
-  } else {
-    const customerForm = process.argv.includes(DEFINITION_FLAG);
-    configureEditionWorkspaceFromProcess(customerForm ? (CUSTOMER_ROOTS[command] ?? VENDOR_ROOTS) : VENDOR_ROOTS, {
-      refuseOthers: customerForm && CUSTOMER_ROOTS[command] !== undefined,
-      ...(command === COVERAGE_COMMAND ? { failureExitCode: COVERAGE_OPERATIONAL_EXIT } : {}),
-    });
-  }
-}
-
-/** 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 on the probe path. */
-async function imageBuildRecordTagInput(options) {
-  return options[IMAGES_FROM_FLAG] === undefined ? {} : { imageBuildRecordDigest: imageBuildRecordDigest(await readImageBuildRecord(options[IMAGES_FROM_FLAG])) };
-}
-
-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;
-      }
-      const pins = readStrictJsonFile(options['--pins']);
-      const workflow = options['--local'] ? LOCAL_WORKFLOW : workflowFromEnv(env);
-      const evidenceTrustPolicy = await descriptorEvidenceTrust({ kind: EditionKind.Resolved, channel: EditionChannel.Develop });
-      const { catalogue, engineImage, ...resolved } = await resolveDevelopEdition({
-        id,
-        pins,
-        env,
-        engine: { repository: options['--engine-repository'], signer: options['--engine-signer'] },
-        cosignBinary: options['--cosign'],
-        previousLock: await resolvePreviousSeal({
-          distributionId: id,
-          previousLockPath: options[PREVIOUS_LOCK_FLAG],
-          previousLockSha256: options[PREVIOUS_LOCK_SHA256_FLAG],
-          firstSeal: Boolean(options[FIRST_SEAL_FLAG]),
-          ...(options[PREVIOUS_SEAL_SIGNER_FLAG] === undefined ? {} : {
-            registry: {
-              find: () => previousSealFromRegistry({
-                repository: editionRepository(id, options['--registry'], EditionChannel.Develop),
-                signerIdentity: options[PREVIOUS_SEAL_SIGNER_FLAG],
-                cosignBinary: options['--cosign'],
-                env,
-              }),
-            },
-          }),
-        }),
-        ...(options[IMAGES_FROM_FLAG] === undefined ? {} : {
-          imagesFrom: await readImageBuildRecord(options[IMAGES_FROM_FLAG]),
-          verifySatellites: createSatelliteVerifier({ registry: options['--registry'], cosignBinary: options['--cosign'], env }),
-        }),
-      });
-      const target = developEditionTarget(id, pins, { registry: options['--registry'], engineImage, ...(await imageBuildRecordTagInput(options)) });
-      const outDir = resolve(options['--out']);
-      writeEditionArtifact({
-        outDir,
-        channel: EditionChannel.Develop,
-        distributionId: id,
-        pins,
-        workflow,
-        evidenceTrustPolicy,
-        engineImage,
-        ...resolved,
-      });
-      writeCatalogue(outDir, catalogue);
-      console.log(target);
-      return;
-    }
-    case 'engine':
-      console.log(
-        await resolveDevelopEngineImage({
-          pins: readStrictJsonFile(options['--pins']),
-          engine: { repository: options['--engine-repository'], signer: options['--engine-signer'] },
-          cosignBinary: options['--cosign'],
-          env,
-        }),
-      );
-      return;
-    case 'coverage':
-      return runDevelopCoverage({
-        id,
-        pins: readStrictJsonFile(options['--pins']),
-        cosignBinary: options['--cosign'],
-        json: options['--json'] === true,
-        env,
-      });
-    case 'follow':
-      await runFollow({ options, env });
-      return;
-    case 'select-records':
-      await runSelectRecords({ options, env });
-      return;
-    case 'image-record':
-      await runImageRecord({ id, options, env });
-      return;
-    case 'verify-image-record':
-      await runVerifyImageRecord({ 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: await descriptorEvidenceTrust({ kind: EditionKind.Resolved, channel: EditionChannel.Develop }),
-        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': {
-      assertKernelCommitSupported({ repoDir: kernelRepoDir(), commit: options['--kernel-sha'], label: `--kernel-sha ${options['--kernel-sha']}` });
-      const pins = freezeGraph({
-        dataSha: options['--data-sha'],
-        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),
-      });
-      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(argv[0] === COVERAGE_COMMAND ? COVERAGE_OPERATIONAL_EXIT : 1);
-    },
-  );
-}

package/edition/develop-engine-image.mjs

@@ -1,95 +0,0 @@
-// develop-engine-image — the engine image a develop edition is deployed with, found and proven.
-//
-// The edition's engine is the one the deploy repository's CI published for EXACTLY the deploy commit the snapshot pins
-// (tag `sha-<12 hex>`, keyless signature by a `workflow_run` follower of a green push CI). The tag only finds the digest.
-// The signature is checked offline against the pinned trust root through the CLI's one cosign path (pinned-cosign.mjs)
-// with the publisher's EXACT identity, issuer, workflow repository and ref (cosign-certificate-constraints.mjs); never a
-// pattern. A follower runs the default branch's copy of the workflow, so the certificate's own workflow commit is not the
-// built one: the built commit is bound by the signed annotations commit=<40 hex> and branch=develop.
-// The digest is what the edition records.
-
-import { RefusalError } from './collected-refusals.mjs';
-import { certificateIdentityArgs } from './cosign-certificate-constraints.mjs';
-import { assertEngineImage } from './edition-artifact.mjs';
-import { assertPublisher, publisherIdentity } from './edition-publisher.mjs';
-import { deployPinKey } from './pin-source.mjs';
-import { cosignEnvironment, withPinnedCosign } from './pinned-cosign.mjs';
-import { splitImageRef } from './registry-credentials.mjs';
-import { isNotPublishedYet } from './seal-image-digests.mjs';
-import { GITHUB_ACTIONS_OIDC_ISSUER } from './third-party-source-evidence.mjs';
-
-const COMMIT_PATTERN = /^[a-f0-9]{40}$/;
-const TAG_PREFIX = 'sha-';
-const TAG_COMMIT_LENGTH = 12;
-const DEVELOP_BRANCH = 'develop';
-const STDERR_TAIL_BYTES = 800;
-
-/** The tag xema-deploy CI gives the engine it publishes for `deploySha`. */
-export const engineTagOf = (deploySha) => `${TAG_PREFIX}${deploySha.slice(0, TAG_COMMIT_LENGTH)}`;
-
-const IDENTITY_PATTERN = /^https:\/\/github\.com\/([^/@]+\/[^/@]+)\/(\.github\/workflows\/[^/@]+)@(.+)$/;
-
-/**
- * The signer an exact certificate identity `https://github.com/<owner>/<name>/.github/workflows/<file>@<ref>` names, held to
- * the publisher grammar of edition-contract.json (so no pattern, no wildcard).
- */
-export function engineSignerOf(identity) {
-  const match = typeof identity === 'string' ? IDENTITY_PATTERN.exec(identity) : null;
-  if (match === null) {
-    throw new RefusalError(`--engine-signer must be the exact certificate identity https://github.com/<owner>/<name>/.github/workflows/<file>@<ref>; got ${JSON.stringify(identity)}`);
-  }
-  const publisher = assertPublisher({ repository: match[1], workflow: match[2], ref: match[3] }, '--engine-signer');
-  return { certificateIdentity: publisherIdentity(publisher), oidcIssuer: GITHUB_ACTIONS_OIDC_ISSUER, githubWorkflow: { repository: publisher.repository, ref: publisher.ref } };
-}
-
-const tail = (text) => String(text).trim().slice(-STDERR_TAIL_BYTES);
-
-/**
- * @param {object} request
- * @param {Record<string, string>} request.pins the snapshot's pins; the xema-deploy commit is read from them
- * @param {{repository: string, signer: string}} request.engine the engine repository and the signer's exact certificate identity
- * @param {string} request.cosignBinary absolute path of cosign
- * @param {object} request.env the environment the registry credentials are named in
- * @param {object} [request.pinned] withPinnedCosign's injections (tests)
- * @returns {Promise<string>} `<repository>@sha256:<digest>`
- */
-export async function resolveDevelopEngineImage({ pins, engine, cosignBinary, env, pinned = {} }) {
-  const deploySha = pins[deployPinKey()];
-  if (typeof deploySha !== 'string' || !COMMIT_PATTERN.test(deploySha)) {
-    throw new RefusalError(`the pin ${deployPinKey()} is ${JSON.stringify(deploySha)}, not a 40-hex commit`);
-  }
-  const { repository } = engine;
-  const signer = engineSignerOf(engine.signer);
-  const tag = engineTagOf(deploySha);
-  const { authority, repository: path } = splitImageRef(repository);
-  return withPinnedCosign({ cosignBinary, env, ...pinned }, async ({ runCosign, cosignEnvFor, clientFor, trustedRootPath }) => {
-    let digest;
-    try {
-      digest = (await clientFor(authority).getManifestByTag(path, tag)).digest;
-    } catch (error) {
-      if (!isNotPublishedYet(error)) {throw error;}
-      throw new RefusalError(
-        `no engine ${repository}:${tag} for the ${deployPinKey()} commit ${deploySha}. The deploy repository's CI publishes one for a green push to develop or main, ` +
-          'or a CI dispatch at that branch; a commit pushed with GITHUB_TOKEN has none until CI is dispatched. ' +
-          `Dispatch that CI at develop, or pin ${deployPinKey()} to a commit that has an engine.`,
-      );
-    }
-    const image = `${repository}@${digest}`;
-    const result = await runCosign(
-      [
-        'verify', '--offline', '--trusted-root', trustedRootPath,
-        ...certificateIdentityArgs(signer),
-        '-a', `commit=${deploySha}`, '-a', `branch=${DEVELOP_BRANCH}`,
-        image,
-      ],
-      cosignEnvironment(cosignEnvFor, authority),
-    );
-    if (result.code !== 0) {
-      throw new RefusalError(
-        `${image} (${tag}) is not signed by the engine signer ${signer.certificateIdentity} with commit=${deploySha} branch=${DEVELOP_BRANCH}; ` +
-          `refusing it as this edition's engine (cosign exit ${result.code}): ${tail(result.stderr)}`,
-      );
-    }
-    return assertEngineImage(image);
-  });
-}