@xemahq/xema 0.53.0 → 0.55.0

package/edition/develop-edition-resolve.mjs

@@ -1,6 +1,6 @@
 // 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
+// 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
@@ -12,15 +12,21 @@ import { biomeSourceTreeIds, readBiomeSourceFacts, sealLock } from './biome-cont
 import { buildCatalogue } from './catalogue.mjs';
 import { resolveDevelopChartSet } from './develop-chart-set.mjs';
 import { assertDevelopEditionInvariants } from './develop-edition-invariants.mjs';
+import { resolveDevelopEngineImage } from './develop-engine-image.mjs';
 import { createDevelopImageProbe } from './develop-image-probe.mjs';
+import { BLOCKED, DevelopResolveCheck, RESOLVE_CHECK_DEPENDENCIES, createResolveReport } from './develop-resolve-report.mjs';
 import { assertFrozenCheckouts, buildSnapshotInputs } 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 { resolveImagesFromRecord, sealImagesFromRecord } from './images-from-record.mjs';
 import { kernelPackageOfAuthority } from './kernel-package.mjs';
 import { loadKernelDistributionSchemas } from './lib.mjs';
+import { assertLockBundleSigners, isBundleSignerRefusal } from './locked-bundle-signer.mjs';
+import { admitDistributionLock, ungrantedOptionalLinesOfRefusal } from './operation-grant-admission.mjs';
 import { deployPinKey } from './pin-source.mjs';
-import { composeAuthorizationBase, resolveDistributionWithIndex } from './resolve-distribution.mjs';
+import { admitResolvedLock, composeAuthorizationBase, prepareDistributionWithIndex } from './resolve-distribution.mjs';
 import { externalSourceTrees, resolveImages, sourceTreeLocator } from './resolve-images.mjs';
 import { createPinnedSourceAuthority } from './source-authority.mjs';
 import { loadTrustedThirdPartySourcePins } from './third-party-pins-trusted.mjs';
@@ -32,12 +38,15 @@ import { loadTrustedThirdPartySourcePins } from './third-party-pins-trusted.mjs'
 export const DEVELOP_EDITION_STEPS = Object.freeze({
   assertFrozenCheckouts,
   buildSnapshotInputs,
-  resolveDistributionWithIndex,
+  assertKernelEditionProtocol,
+  prepareDistributionWithIndex,
+  resolveDevelopEngineImage,
   assertDevelopEditionInvariants,
   assertAdapterBundlesMatchHost,
   composeAuthorizationBase,
   resolveImages,
   sealImages,
+  sealImagesFromRecord,
   resolveDevelopChartSet,
 });
 
@@ -45,46 +54,118 @@ 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. `resolveDevelopEdition` and the
- * read-only `coverage` verb both start here, so the content hash each computes
- * for a subject is the same by construction.
+ * 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.
  */
-export async function resolveDevelopSnapshot({ id, pins, steps = DEVELOP_EDITION_STEPS, phase = () => {} }) {
+async function prepareDevelopSnapshot({ id, pins, steps, phase }) {
   const schemas = await loadKernelDistributionSchemas();
   steps.assertFrozenCheckouts(pins);
   const inputs = await steps.buildSnapshotInputs({ id, pins, schemas });
   phase('snapshot inputs built');
-  const { lock, index } = await steps.resolveDistributionWithIndex(id, { inputs });
-  return { schemas, inputs, lock, index };
+  const prepared = await steps.prepareDistributionWithIndex(id, { inputs });
+  // The schemas the lock was composed with are the ones that admit it.
+  return { inputs, ...prepared };
+}
+
+/** The read-only `coverage` verb's snapshot: prepared as the resolve prepares it, then admitted (a refusal throws). */
+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;
 }
 
-export async function resolveDevelopEdition({ id, pins, env = process.env, sealOptions = {}, fetchKernelTarball, fetchManifest = fetchRegistryManifest, progress = stderrProgress, steps = DEVELOP_EDITION_STEPS }) {
+/**
+ * @param {object} request
+ * @param {object} [request.imagesFrom] a parsed image build record (images-from-record.mjs): the digests are the record's,
+ *   with no probe and no rehash, and `verifySatellites` (createSatelliteVerifier) admits its satellite entries
+ * @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, engine, cosignBinary, env = process.env, sealOptions = {}, fetchKernelTarball, fetchManifest = fetchRegistryManifest, progress = stderrProgress, steps = DEVELOP_EDITION_STEPS, imagesFrom, verifySatellites, previousLock = null }) {
+  if ((imagesFrom === undefined) !== (verifySatellites === undefined)) {
+    throw new Error('resolveDevelopEdition takes an image build record and its satellite verifier together, or neither');
+  }
   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)`);
-  const { schemas, inputs, lock, index } = await resolveDevelopSnapshot({ id, pins, steps, phase });
+  // 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 steps.resolveDevelopEngineImage({ pins, engine, cosignBinary, env });
+    phase('engine image resolved');
+    return image;
+  });
+  await checked(DevelopResolveCheck.EditionProtocol, () => steps.assertKernelEditionProtocol(kernelPackageDir()));
+  const snapshot = await checked(DevelopResolveCheck.DistributionLock, () => prepareDevelopSnapshot({ id, pins, steps, phase }), {
+    classify: (error) => (isBundleSignerRefusal(error) ? DevelopResolveCheck.BundleSigner : DevelopResolveCheck.DistributionLock),
+  });
+  const lockProduced = snapshot !== BLOCKED;
+  const { schemas, inputs, lock, index } = lockProduced ? snapshot : {};
+  if (lockProduced) {
+    await checked(DevelopResolveCheck.BundleSigner, () => assertLockBundleSigners({ lock, schemas }));
+  }
   // The plane invariants, against the graph this candidate froze (develop-edition-invariants.mjs).
-  const graded = steps.assertDevelopEditionInvariants({ id, lock, biomeIndex: inputs.biomeIndex, schemas });
-  phase(`reservation table asserted (${graded.reservedDomains} domains); confinement asserted (${graded.confinedBiomes} declaration(s))`);
-  await steps.assertAdapterBundlesMatchHost({ lock, hostRow: adapterHostRow(index), fetchManifest });
-  const authorizationLock = await steps.composeAuthorizationBase(id, lock, index);
-  phase('distribution lock resolved');
+  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.
-  const probe = createDevelopImageProbe({
-    distributionId: id,
-    env,
-    ...(sealOptions.distributionsRoot === undefined ? {} : { distributionsRoot: sealOptions.distributionsRoot }),
-    ...(sealOptions.fetchImpl === undefined ? {} : { fetchImpl: sealOptions.fetchImpl }),
-    ...(sealOptions.run === undefined ? {} : { run: sealOptions.run }),
-    progress,
+  let recorded;
+  const imageLock = await checked(DevelopResolveCheck.DevelopImages, async () => {
+    if (imagesFrom !== undefined) {
+      const fromRecord = await resolveImagesFromRecord({ id, inputs, lock, record: imagesFrom, resolveImages: steps.resolveImages, verifySatellites, previousLock });
+      ({ recorded } = fromRecord);
+      phase(`image subjects taken from the build record (${fromRecord.imageLock.subjects.length} subjects); satellites verified`);
+      return fromRecord.imageLock;
+    }
+    const probe = createDevelopImageProbe({
+      distributionId: id,
+      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;
   });
-  const { imageLock } = await steps.resolveImages(id, { inputs, lock, onSubjectHashed: probe.observe });
-  phase(`image content hashes computed (${imageLock.subjects.length} subjects)`);
-  await probe.settle();
-  phase('every develop image is present');
-  const sealedImageLock = await steps.sealImages({ channel: EditionChannel.Develop, imageLock, env, progress, thirdPartyPins: loadTrustedThirdPartySourcePins(dataRoot()), ...sealOptions });
+  try {
+    report.settle();
+  } catch (error) {
+    progress(error.message);
+    throw error;
+  }
+  if (report.noticeText() !== '') {progress(report.noticeText());}
+  const sealArguments = { imageLock, env, progress, thirdPartyPins: loadTrustedThirdPartySourcePins(dataRoot()), ...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.
@@ -100,8 +181,6 @@ export async function resolveDevelopEdition({ id, pins, env = process.env, sealO
   phase(`biome sources read (${sourceFactsById.size} biomes)`);
   const sealedLock = await sealLock({ ...biomeSources, unsealed: lock, sourceFactsById });
   phase('distribution lock sealed');
-  const chartSetLock = await steps.resolveDevelopChartSet({ xemaDeploySha: pins[deployPinKey()] });
-  phase('chart set resolved');
   const sourceTreeIds = await biomeSourceTreeIds({ ...biomeSources, lock, sourceFactsById });
   const catalogue = buildCatalogue({
     sourceTreeIds,
@@ -121,5 +200,5 @@ export async function resolveDevelopEdition({ id, pins, env = process.env, sealO
     leaf: inputs.composed.leaf,
   });
   phase('catalogue built');
-  return { distributionLock: sealedLock, imageLock: sealedImageLock, authorizationLock, chartSetLock, catalogue };
+  return { distributionLock: sealedLock, imageLock: sealedImageLock, authorizationLock, chartSetLock, catalogue, engineImage };
 }

package/edition/develop-edition.mjs

@@ -2,9 +2,16 @@
 // develop-edition — the develop edition's command line.
 //
 //   resolve <id> --pins <file> --out <dir> --registry <root>
-//           --engine-image <repository>@sha256:<digest> [--local]
+//           --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>
@@ -16,10 +23,17 @@
 //       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).
-//   target  <id> --pins <file> --registry <root> --engine-image <repository>@sha256:<digest>
+//   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. The root is always the caller's
+//       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>
@@ -27,10 +41,14 @@
 //       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>] --out <file>
+//                [--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. --kernel-sha is refused
+//       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.
@@ -57,7 +75,7 @@
 //       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, images }, once (wx). Any missing, unsigned, mismatched or
+//       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).
@@ -69,6 +87,14 @@
 //       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.
+//   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
@@ -92,22 +118,28 @@
 import { resolve } from 'node:path';
 
 import { writeCatalogue } from './catalogue.mjs';
-import { CUSTOMER_ROOTS, headResolver, parseEditionVerbArgs, runCustomerVerb, writeOnce } from './customer-edition-verbs.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 { 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 { 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, 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 { 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
@@ -150,21 +182,37 @@ function parseOverrides(text) {
   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 } = 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'] }));
+      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 });}
       const pins = readStrictJsonFile(options['--pins']);
       const workflow = options['--local'] ? LOCAL_WORKFLOW : workflowFromEnv(env);
-      const target = developEditionTarget(id, pins, { registry: options['--registry'], engineImage: options['--engine-image'] });
       const evidenceTrustPolicy = await descriptorEvidenceTrust({ kind: EditionKind.Resolved, channel: EditionChannel.Develop });
-      const { catalogue, ...resolved } = await resolveDevelopEdition({ id, pins, env });
+      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[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,
@@ -173,13 +221,23 @@ async function run(argv, env) {
         pins,
         workflow,
         evidenceTrustPolicy,
-        engineImage: options['--engine-image'],
+        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,
@@ -191,6 +249,9 @@ async function run(argv, env) {
     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;
@@ -224,6 +285,7 @@ async function run(argv, env) {
         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);

package/edition/develop-engine-image.mjs

@@ -0,0 +1,95 @@
+// 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);
+  });
+}

package/edition/develop-freeze.mjs

@@ -9,6 +9,9 @@
 //   freezeGraph    the graph repositories, the data root, the kernel, the deploy checkout, the editions root
 //   freezeSources  one pin per `sources[]` entry the chain declares
 //
+// With `memberPins` (a select-records selection) the members are pinned at the selected build records instead; the one
+// declared exception, a member that keeps its current resolution, is pinned at its develop head.
+//
 // `resolveHead({ name, url })` is the one network seam (default: `git ls-remote` through
 // git-source-auth: the data root's token only for a repository under its
 // `sourceRepositoryUrlPrefix`, no credential for any other, never argv).
@@ -16,6 +19,7 @@
 import { execFileSync } from 'node:child_process';
 
 import { canonicalPublicHttpsRepositoryUrl } from './canonical-repository-url.mjs';
+import { currentResolutionOf } from './develop-current-resolution.mjs';
 import { developGraphMembers } from './develop-graph.mjs';
 import { EditionChannel } from './edition-channel.mjs';
 import { assertCanonicalSourceUrl, assertSourceDeclaresNoCredential, isUnderSourcePrefix, withSourceGitEnv } from './git-source-auth.mjs';
@@ -124,6 +128,17 @@ function assertOverrides(overrides, allowed) {
   }
 }
 
+/** The member pins name exactly the graph minus the current-resolution members; a missing or extra member is refused by name. */
+function assertMemberPinsAreTheGraph(memberPins, members) {
+  const current = new Set(Object.keys(currentResolutionOf(members)));
+  const expected = members.map(({ repo }) => repo).filter((repo) => !current.has(repo));
+  const missing = expected.filter((repo) => !Object.hasOwn(memberPins, repo));
+  const extra = Object.keys(memberPins).filter((repo) => !expected.includes(repo));
+  if (missing.length > 0 || extra.length > 0) {
+    throw new Error(`--member-pins must pin exactly the develop graph minus ${JSON.stringify([...current])}: missing ${JSON.stringify(missing)}, extra ${JSON.stringify(extra)}`);
+  }
+}
+
 const GRAPH_PHASE = new Set([
   SnapshotPinNamespace.Graph,
   SnapshotPinNamespace.Distributions,
@@ -149,6 +164,9 @@ function assertCheckedOutPin({ key, sha, flag, what, overrides }) {
  * @param {string} request.kernelSha the commit the kernel checkout is at
  * @param {string} request.deploySha the commit the deploy checkout is at
  * @param {string} [request.editionsRootUrl] https URL of the editions root; absent = this repository
+ * @param {Record<string, string>} [request.memberPins] the graph members' pins from a selection (`--member-pins`): exactly the
+ *   graph minus the members that keep their current resolution (develop-current-resolution.mjs), which are pinned at their
+ *   develop head; refused together with overrides
  * @param {(source: {name: string, url: string}) => void} request.holdSource the hold of one source; runs for ALL graph sources before the first head
  */
 export function freezeGraph({
@@ -157,9 +175,13 @@ export function freezeGraph({
   deploySha,
   editionsRootUrl,
   overrides = {},
+  memberPins,
   resolveHead,
   holdSource,
 }) {
+  if (memberPins !== undefined && Object.keys(overrides).length > 0) {
+    throw new Error('--member-pins and --overrides are exclusive: the member pins are the selected build records, never overridden');
+  }
   assertNoToolingOverride(overrides);
   assertOverrides(overrides, GRAPH_PHASE);
   const head = memoizedHeads(resolveHead);
@@ -171,6 +193,7 @@ export function freezeGraph({
       throw new Error(`override names "${key}", which is not a repository in the graph`);
     }
   }
+  if (memberPins !== undefined) {assertMemberPinsAreTheGraph(memberPins, members);}
   const checkedOut = [
     { key: dataPinKey(), sha: dataSha, flag: '--data-sha', what: 'the data root checkout' },
     { key: kernelPinKey(), sha: kernelSha, flag: '--kernel-sha', what: 'the kernel checkout' },
@@ -188,7 +211,7 @@ export function freezeGraph({
   }
   const pins = Object.fromEntries(checkedOut.map(({ key, sha }) => [key, sha]));
   for (const member of members) {
-    pins[member.repo] = overrides[member.repo] ?? head({ name: member.repo, url: member.repositoryUrl });
+    pins[member.repo] = overrides[member.repo] ?? memberPins?.[member.repo] ?? head({ name: member.repo, url: member.repositoryUrl });
   }
   if (editionsRootUrl !== undefined) {
     const url = canonicalPublicHttpsRepositoryUrl(editionsRootUrl, '--editions-root-url');

package/edition/develop-graph.mjs

@@ -13,14 +13,16 @@ import { compareStrings } from './lib.mjs';
 
 /**
  * The develop graph: `{ repo, repositoryUrl }` per declared first-party
- * repository, sorted by repo handle.
+ * repository, sorted by repo handle, plus `currentResolution` (its ticket) on a
+ * member the data root declares one for (develop-current-resolution.mjs).
  *
- * @returns {readonly { repo: string, repositoryUrl: string }[]}
+ * @returns {readonly { repo: string, repositoryUrl: string, currentResolution?: string }[]}
  */
 export function developGraphMembers() {
   return Object.freeze(
     Object.entries(firstPartySources('the develop graph'))
-      .map(([repo, { repositoryUrl }]) => Object.freeze({ repo, repositoryUrl }))
+      .map(([repo, { repositoryUrl, currentResolution }]) =>
+        Object.freeze({ repo, repositoryUrl, ...(currentResolution === undefined ? {} : { currentResolution }) }))
       .sort((a, b) => compareStrings(a.repo, b.repo)),
   );
 }