@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/develop-git-bundles.mjs

@@ -0,0 +1,296 @@
+// develop-git-bundles — the OCI bundle of a git-sourced biome, in a DEVELOP edition only (XEMA-2456): a vendor develop
+// resolve, or a customer develop resolve (`--definition`) whose data root declares a pinned evidence trust policy
+// (`customerDevelopGitBundleVerifier`). Each is verified under the trust policy of ITS OWN data root.
+//
+// A release edition never carries an OCI bundle on a git-sourced row: the manifest's `bundleSource` names an artifact
+// the release lane builds, not one built from the pinned commit (resolve-distribution.mjs strips it, the release refuses
+// it). A resolve without a verifier (a customer edition whose data root declares no policy, or any customer release)
+// refuses it on a required row (`assertNoUnverifiedRequiredGitBundles`). A develop edition freezes a git source at its develop head F, and the source's own develop lane
+// publishes the bundle the manifest names, signed keyless by its develop workflow. This module proves that bundle is
+// the one F describes, and only then does the resolve keep it on the row, by DIGEST, with its develop bundle signer:
+//
+//   1. the bundle: the manifest's own `bundleSource.ociRef` at F (`<repository>:<version>`; the kernel holds the tag to
+//      the manifest version) resolved to its digest at the registry. The lock records `<repository>@sha256:<hex>`, never
+//      the tag, so the edition names immutable bytes;
+//   2. the signer: the ONE `develop` row of the source's repository in the data root's trust policy
+//      (`bundleSignerRowFor`). cosign verifies the digest's signature under that row's identity, issuer, workflow
+//      repository and ref, and states the ONE commit P its certificate was issued at (`verifiedBundleSignerCommit`);
+//      `verifyBundleOnRegistry` then holds the signature AND the SLSA provenance to exactly the row and P. P is never
+//      read from bytes cosign has not verified;
+//   3. the content binding of P to F. A version that is already published is never re-attested by the publisher
+//      (`xema biome publish` "already current"), so P is the commit that last published the version, and F may be a
+//      later commit of the same version. Two checks, refused on either, each naming P, F and the mismatching pair:
+//        (a) the kernel's `computeBiomeSourceManifestHash` of the bundle's own `xema-biome.json` equals the
+//            `sourceManifestHash` of the biome at F (the hash the seal and verify hold to the git source at F);
+//        (b) the git tree id of the biome directory at P equals its tree id at F (the catalogue's `sourceTreeIds`
+//            notion), so the bundle was built from the same biome source F holds.
+//      THE GAP, develop only: build inputs outside the biome directory (shared packages, the lockfile, the publisher's
+//      toolchain) are not bound. A change there between P and F reaches no check here. A release never relies on this:
+//      it carries a third-party bundle only through an `oci` source with a third-party pin, whose evidence is bound to
+//      the pinned commit itself.
+//
+// That verification is the OFFICIAL lane's (a customer develop resolve, and the catalogue-free resolve's vendor step).
+// The channel lane every deployment we run resolves with (`createDevelopGitBundleDigestReader`) takes the bundle by
+// step 1 only: the digest the manifest's tag serves, whose own xema-biome.json must name the biome. No cosign, no
+// signer commit, no content binding.
+//
+// Every failure is a `DevelopGitBundleError` naming the biome; all subjects are verified before one is refused.
+
+import { canonicalPublicHttpsRepositoryUrl, repositoryOwnerName } from './canonical-repository-url.mjs';
+import { RefusalError } from './collected-refusals.mjs';
+import { EditionChannel } from './edition-channel.mjs';
+import { editionWorkspaceConfig } from './edition-config.mjs';
+import { dataRoot as configuredDataRoot, editionsRoot } from './edition-workspace.mjs';
+import { loadPinnedDeclaredTrustPolicy } from './evidence-trust-pin.mjs';
+import { sourceTreeIdAt } from './external-source-walk.mjs';
+import { prepareTrustedCosignBinary } from './image-evidence.mjs';
+import { BundleSignerRefusedError, DevelopGitBundleError } from './locked-bundle-signer.mjs';
+import { createRegistryClientResolver } from './oci-image-source-evidence.mjs';
+import { bundleDigestRef, fetchBundleManifest, verifiedBundleSignerCommit, verifyBundleOnRegistry } from './third-party-bundle-registry.mjs';
+import { bundleSignerRowFor } from './third-party-source-evidence.mjs';
+import { OCI_BUNDLE_SOURCE_KIND } from './third-party-subjects.mjs';
+
+/** The key a verified bundle is looked up by: the source name and the biome id of its index entry. */
+export const developGitBundleKey = (sourceName, biomeId) => `${sourceName}\u0000${biomeId}`;
+
+/**
+ * The rows a develop resolve must verify a bundle for: each git-sourced biome of `lock` (a row with a `source`) whose
+ * index entry declares a biome-level OCI `bundleSource`.
+ *
+ * @returns {{biomeId: string, source: {name: string, url: string, commit: string}, entry: object}[]}
+ */
+export function developGitBundleSubjects({ lock, index }) {
+  const entries = new Map(index.filter((entry) => entry.source !== undefined).map((entry) => [developGitBundleKey(entry.source, entry.id), entry]));
+  return lock.biomes.flatMap((biome) => {
+    if (biome.source === undefined) {return [];}
+    const entry = entries.get(developGitBundleKey(biome.source.name, biome.id));
+    return entry?.bundleSource?.kind === OCI_BUNDLE_SOURCE_KIND ? [{ biomeId: biome.id, source: biome.source, entry }] : [];
+  });
+}
+
+const subjectLabel = ({ biomeId, source }) => `biome "${biomeId}" (git source "${source.name}" at ${source.commit})`;
+
+/**
+ * A resolve with no develop bundle verifier (a customer edition, either channel) drops a git-sourced row's OCI
+ * `bundleSource` (resolve-distribution.mjs, at the copy point). For a row the edition installs as `required`, that
+ * drop is never silent: biome-host would get a required biome with no bundle to fetch. Every such row is refused at
+ * once, naming the declared bundle and what is missing (XEMA-2456).
+ *
+ * @param {object} options
+ * @param {object} options.lock the resolved lock (its rows carry `installPolicy`)
+ * @param {object[]} options.index the index it was resolved from (it still holds the manifest's bundleSource)
+ * @param {string} options.required the kernel's `BiomeInstallPolicy.Required`
+ */
+export function assertNoUnverifiedRequiredGitBundles({ lock, index, required }) {
+  const requiredRows = new Set(lock.biomes.filter((biome) => biome.installPolicy === required).map((biome) => biome.id));
+  const refused = developGitBundleSubjects({ lock, index })
+    .filter((subject) => requiredRows.has(subject.biomeId))
+    .map(
+      (subject) =>
+        new DevelopGitBundleError(
+          `${subjectLabel(subject)} is installPolicy required and its manifest declares an OCI bundleSource (${subject.entry.bundleSource.ociRef}), ` +
+            'but this resolve verifies no git-sourced bundle, so its lock row would carry no bundleSource and no bundleSigner and biome-host could not install it. ' +
+            'A develop resolve verifies it when its data root declares a pinned evidenceTrustPolicy (edition-workspace.json) holding the ONE develop ' +
+            `bundle-signer row of the source's repository, and it is given --cosign; a release carries such a biome only as an \`oci\` source with a third-party source pin`,
+        ),
+    );
+  if (refused.length === 1) {throw refused[0];}
+  if (refused.length > 1) {throw new BundleSignerRefusedError(refused);}
+}
+
+/** The biome directory relative to its source repository: the index path is `<source name>/<directory>`. */
+function repositoryPathOf({ source, entry }) {
+  const prefix = `${source.name}/`;
+  if (!entry.path.startsWith(prefix)) {
+    throw new Error(`${subjectLabel({ biomeId: entry.id, source })}: index path ${JSON.stringify(entry.path)} is not under the source "${source.name}"`);
+  }
+  return entry.path.slice(prefix.length);
+}
+
+/** Verify every subject, then refuse them all at once: one refusal is rethrown unchanged, several are one error. */
+async function verifyEach(subjects, verifyOne) {
+  const verified = new Map();
+  const refused = [];
+  for (const subject of subjects) {
+    try {
+      verified.set(developGitBundleKey(subject.source.name, subject.biomeId), await verifyOne(subject));
+    } catch (error) {
+      // A refusal, or a plain Error of the registry, cosign or git: this subject is refused. A defect (TypeError, ...) is not.
+      const refusal = error instanceof RefusalError || error?.constructor === Error;
+      if (!refusal) {throw error;}
+      refused.push(error instanceof DevelopGitBundleError ? error : new DevelopGitBundleError(`${subjectLabel(subject)}: ${error.message}`));
+    }
+  }
+  if (refused.length === 1) {throw refused[0];}
+  if (refused.length > 1) {throw new BundleSignerRefusedError(refused);}
+  return verified;
+}
+
+/** The bundle's own xema-biome.json, which must name the biome the row is for. */
+async function bundleManifestOfBiome({ clientFor, ociRef, biomeId, label }) {
+  const { manifest } = await fetchBundleManifest({ clientFor, ociRef });
+  if (manifest?.xema?.id !== biomeId) {
+    throw new Error(`${label}: ${ociRef} declares xema.id ${JSON.stringify(manifest?.xema?.id)}, not "${biomeId}"`);
+  }
+  return manifest;
+}
+
+/**
+ * One subject on the channel lane: the digest the manifest's `bundleSource.ociRef` tag serves (step 1), its manifest
+ * naming the biome. Nothing is verified beyond that.
+ *
+ * @returns {Promise<{bundleSource: object}>} the bundle source the lock row carries: the declared one, by digest
+ */
+export async function developGitBundleByDigest({ subject, clientFor }) {
+  const { biomeId, entry } = subject;
+  const ociRef = await bundleDigestRef({ clientFor, ociRef: entry.bundleSource.ociRef });
+  await bundleManifestOfBiome({ clientFor, ociRef, biomeId, label: subjectLabel(subject) });
+  return { bundleSource: { ...entry.bundleSource, ociRef } };
+}
+
+/**
+ * The reader a channel-lane develop resolve hands `prepareDistributionWithIndex` (`inputs.developGitBundles`): each
+ * git-sourced OCI bundle by the digest its tag serves (`developGitBundleByDigest`). No trust policy, no cosign.
+ *
+ * @param {object} options
+ * @param {string} options.registryRoot the root whose image-registry-credentials.json the registry is read with
+ */
+export function createDevelopGitBundleDigestReader({ registryRoot, clientFor }) {
+  return Object.freeze({
+    async verify({ subjects }) {
+      if (subjects.length === 0) {return new Map();}
+      const registry = clientFor ?? createRegistryClientResolver({ dataRoot: registryRoot });
+      return verifyEach(subjects, (subject) => developGitBundleByDigest({ subject, clientFor: registry }));
+    },
+  });
+}
+
+/**
+ * One subject, verified (steps 1 to 3 of this file's header). `context` is `{policy, policyRoot, schemas, trustedCosign}`.
+ *
+ * @returns {Promise<{bundleSource: object}>} the bundle source the lock row carries: the declared one, by digest
+ */
+export async function verifyDevelopGitBundle({
+  subject,
+  checkout,
+  context,
+  clientFor,
+  signerCommit = verifiedBundleSignerCommit,
+  verifyOnRegistry = verifyBundleOnRegistry,
+  treeIdAt = sourceTreeIdAt,
+  env = process.env,
+}) {
+  const { biomeId, source, entry } = subject;
+  const label = subjectLabel(subject);
+  if (checkout === undefined) {
+    throw new Error(`${label}: the source walk holds no checkout of "${source.name}"`);
+  }
+  const repository = repositoryOwnerName(canonicalPublicHttpsRepositoryUrl(source.url, `${label} source url`), `${label} source url`);
+  const row = bundleSignerRowFor({ policy: context.policy, repository, channel: EditionChannel.Develop, schemas: context.schemas, label: `${label} develop bundle signer` });
+
+  // 1 + 2: the digest the manifest's tag serves; the commit P cosign verified the develop signature at; signature and
+  // provenance held to the row at P.
+  const ociRef = await bundleDigestRef({ clientFor, ociRef: entry.bundleSource.ociRef });
+  const cosign = { trustedCosign: context.trustedCosign, policy: context.policy, policyRoot: context.policyRoot, row, ociRef, env };
+  const attestedCommit = signerCommit(cosign);
+  verifyOnRegistry({ ...cosign, workflowSha: attestedCommit });
+
+  // 3: the content binding of P to F (see the header for the gap it leaves: build inputs outside the biome directory).
+  const binding = `the bundle ${ociRef} attested at ${attestedCommit} (P) against the source at ${source.commit} (F)`;
+  const manifest = await bundleManifestOfBiome({ clientFor, ociRef, biomeId, label });
+  const bundleManifestHash = await context.schemas.computeBiomeSourceManifestHash(manifest);
+  if (bundleManifestHash !== entry.sourceManifestHash) {
+    throw new DevelopGitBundleError(
+      `${label}: ${binding}: the bundle's xema-biome.json hashes to sourceManifestHash ${bundleManifestHash}, but the manifest at F hashes to ${entry.sourceManifestHash}`,
+    );
+  }
+  const path = repositoryPathOf(subject);
+  const treeAtAttested = treeIdAt({ checkout, commit: attestedCommit, path, env });
+  const treeAtFrozen = treeIdAt({ checkout, commit: source.commit, path, env });
+  if (treeAtAttested !== treeAtFrozen) {
+    throw new DevelopGitBundleError(
+      `${label}: ${binding}: the biome directory ${path} is tree ${treeAtAttested} at P but tree ${treeAtFrozen} at F; publish a new version of the biome from F`,
+    );
+  }
+  return { bundleSource: { ...entry.bundleSource, ociRef } };
+}
+
+/**
+ * The verifier a vendor develop resolve hands `prepareDistributionWithIndex` (`inputs.developGitBundles`). Nothing is
+ * read (no trust policy, no cosign) unless a subject exists.
+ *
+ * @param {object} options
+ * @param {string|undefined} options.cosignBinary the cosign the trust policy pins by digest (`--cosign`)
+ * @param {string} options.dataRoot the root whose pinned trust policy holds the develop bundle-signer rows
+ * @param {string} [options.registryRoot] the root whose image-registry-credentials.json the registry is read with (default: dataRoot)
+ */
+export function createDevelopGitBundleVerifier({ cosignBinary, dataRoot, registryRoot = dataRoot, env = process.env, clientFor, treeIdAt }) {
+  return Object.freeze({
+    async verify({ subjects, checkouts, schemas }) {
+      if (subjects.length === 0) {return new Map();}
+      if (cosignBinary === undefined) {
+        throw new DevelopGitBundleError(
+          `${subjects.map(subjectLabel).join(', ')} declare an OCI bundle; verifying it needs a cosign binary (--cosign), and none was given`,
+        );
+      }
+      const policy = loadPinnedDeclaredTrustPolicy({ dataRoot, declaration: editionWorkspaceConfig().evidenceTrustPolicy, schemas });
+      const trustedCosign = prepareTrustedCosignBinary({ cosignBinary, policy });
+      const context = { policy, policyRoot: dataRoot, schemas, trustedCosign };
+      const registry = clientFor ?? createRegistryClientResolver({ dataRoot: registryRoot });
+      try {
+        return await verifyEach(subjects, (subject) =>
+          verifyDevelopGitBundle({ subject, checkout: checkouts.get(subject.source.name), context, clientFor: registry, env, ...(treeIdAt === undefined ? {} : { treeIdAt }) }),
+        );
+      } finally {
+        trustedCosign.dispose();
+      }
+    },
+  });
+}
+
+/**
+ * The verifier a CUSTOMER resolve (`--definition`) hands `resolveCustomerDistribution`, or undefined. Only a develop
+ * resolve whose configured data root DECLARES an evidence trust policy gets one: the bundles are verified under that
+ * customer policy, held to its pin (`loadPinnedDeclaredTrustPolicy`, read only when a subject exists), never the
+ * vendor's. The registry is read with the editions root's credentials, as the customer's own images are. Without a
+ * declared policy (or on release) there is none, and a required git-sourced row declaring an OCI bundle is refused
+ * (`assertNoUnverifiedRequiredGitBundles`).
+ */
+export function customerDevelopGitBundleVerifier({ channel, cosignBinary, env = process.env, clientFor, treeIdAt }) {
+  if (channel !== EditionChannel.Develop) {return undefined;}
+  if (editionWorkspaceConfig().evidenceTrustPolicy.policy === null) {return undefined;}
+  return createDevelopGitBundleVerifier({
+    cosignBinary,
+    dataRoot: configuredDataRoot(),
+    registryRoot: editionsRoot(),
+    env,
+    ...(clientFor === undefined ? {} : { clientFor }),
+    ...(treeIdAt === undefined ? {} : { treeIdAt }),
+  });
+}
+
+/**
+ * The OFFLINE verifier of a candidate re-seal: the bundle the pinned develop edition already verified for the SAME
+ * source commit, carried forward unchanged, with the signer it was verified under (`pinnedBundleSigner`): the resolve
+ * refuses the row when the current trust policy selects any other signer (a rotated develop row). A subject at another commit, or one the pinned edition carried no bundle
+ * for, is refused: verifying a new bundle reads the registry, which an offline re-seal does not.
+ *
+ * @param {object} pinnedLock the pinned edition's parsed distribution lock
+ */
+export function carriedDevelopGitBundles(pinnedLock) {
+  return Object.freeze({
+    async verify({ subjects }) {
+      return verifyEach(subjects, async (subject) => {
+        const row = pinnedLock.biomes.find(
+          (biome) => biome.id === subject.biomeId && biome.source?.name === subject.source.name && biome.source.commit === subject.source.commit,
+        );
+        if (row?.bundleSource?.kind !== OCI_BUNDLE_SOURCE_KIND || row.bundleSigner === undefined) {
+          throw new DevelopGitBundleError(
+            `${subjectLabel(subject)}: the pinned edition carries no verified bundle at this commit, and an offline re-seal cannot verify one; resolve the develop edition instead`,
+          );
+        }
+        return { bundleSource: row.bundleSource, pinnedBundleSigner: row.bundleSigner };
+      });
+    },
+  });
+}

package/edition/develop-graph.mjs

@@ -0,0 +1,34 @@
+// develop-graph — which repositories a DEVELOP candidate is built from.
+//
+// The develop graph is every first-party repository the data root declares
+// (`firstPartySources` in edition-workspace.json), each at its declared
+// `repositoryUrl`. It is never read from the release pins
+// (`runtime-image-source-index.json#repositoryPins`): develop and release are
+// separate lifecycles, and a repository is first-party on develop before any
+// release pins it. freeze-graph, the snapshot checkout, the snapshot pins'
+// validation and the snapshot's index all take their members from here.
+
+import { firstPartySources } from './first-party-source-ids.mjs';
+import { compareStrings } from './lib.mjs';
+
+/**
+ * The develop graph: `{ repo, repositoryUrl }` per declared first-party
+ * repository, sorted by repo handle, plus `currentResolution` (its ticket) on a
+ * member the data root declares one for (develop-current-resolution.mjs), and `developImageRegistry` (its develop
+ * store root, where its build records live) on a member that declares one.
+ *
+ * @returns {readonly { repo: string, repositoryUrl: string, currentResolution?: string, developImageRegistry?: string }[]}
+ */
+export function developGraphMembers() {
+  return Object.freeze(
+    Object.entries(firstPartySources('the develop graph'))
+      .map(([repo, { repositoryUrl, currentResolution, developImageRegistry }]) =>
+        Object.freeze({
+          repo,
+          repositoryUrl,
+          ...(currentResolution === undefined ? {} : { currentResolution }),
+          ...(developImageRegistry === undefined ? {} : { developImageRegistry }),
+        }))
+      .sort((a, b) => compareStrings(a.repo, b.repo)),
+  );
+}

package/edition/develop-image-coordinate.mjs

@@ -0,0 +1,85 @@
+// develop-image-coordinate — the ONE mapping from a release image repository to
+// the develop repository its producer pushes the same build to.
+//
+//   <host>/<owner>/<name...>   ->   <host>/<owner>/dev/<name...>
+//
+// Every first-party source declares its develop store (`developImageRegistry`, edition-workspace.json): the root
+// replaces `<host>/<owner>` in every develop ref and in the build-record repository,
+//
+//   <host>/<owner>/<name...>   ->   <developImageRegistry>/dev/<name...>
+//   build records of <name>    ->   <developImageRegistry>/build-records/<name>
+//
+// A producer's develop lane pushes `<devRepository>:<contentHash>` (contract C1)
+// and nothing else reads or writes that namespace, so a release coordinate can
+// never be satisfied by a develop build or the other way round.
+
+import { DEVELOP_IMAGE_NAMESPACE_SEGMENT } from './edition-constants.mjs';
+import { splitImageRef } from './registry-credentials.mjs';
+
+const DEVELOP_NAMESPACE_SEGMENT = DEVELOP_IMAGE_NAMESPACE_SEGMENT;
+
+const OWNER_SEGMENT_INDEX = 0;
+const NAMESPACE_SEGMENT_INDEX = 1;
+const MINIMUM_REPOSITORY_SEGMENTS = 2;
+
+/** The `{ authority, owner, name }` of a release ref `<host>/<owner>/<name...>`; refuses what is not a bare release repository. */
+function releaseCoordinate(releaseImageRef) {
+  const { authority, repository } = splitImageRef(releaseImageRef);
+  if (repository.includes('@') || repository.includes(':')) {
+    throw new Error(
+      `image reference "${releaseImageRef}" carries a tag or digest; a develop coordinate maps a bare repository`,
+    );
+  }
+  const segments = repository.split('/');
+  if (segments.length < MINIMUM_REPOSITORY_SEGMENTS) {
+    throw new Error(
+      `image reference "${releaseImageRef}" has no <owner>/<name> repository path; it cannot be mapped to a develop repository`,
+    );
+  }
+  if (segments[NAMESPACE_SEGMENT_INDEX] === DEVELOP_NAMESPACE_SEGMENT) {
+    throw new Error(`image reference "${releaseImageRef}" is already a develop repository`);
+  }
+  const [owner, ...name] = segments;
+  return { authority, owner, name: name.join('/') };
+}
+
+/** `developImageRef('registry.example.com/acme/identity-api') === 'registry.example.com/acme/dev/identity-api'`. */
+export function developImageRef(releaseImageRef) {
+  const { authority, owner, name } = releaseCoordinate(releaseImageRef);
+  return `${authority}/${owner}/${DEVELOP_NAMESPACE_SEGMENT}/${name}`;
+}
+
+/** Whether a repository reference lies in the develop namespace: a `dev` segment after the store root and before the name. */
+export function isDevelopImageRef(imageRef) {
+  let repository;
+  try {
+    ({ repository } = splitImageRef(imageRef));
+  } catch {
+    return false;
+  }
+  const segments = repository.split('/');
+  // structural: the lane segment sits after the store root (whatever its depth) and before the image name
+  return (
+    segments.length > MINIMUM_REPOSITORY_SEGMENTS &&
+    segments[OWNER_SEGMENT_INDEX].length > 0 &&
+    segments.slice(NAMESPACE_SEGMENT_INDEX, -1).includes(DEVELOP_NAMESPACE_SEGMENT)
+  );
+}
+
+/**
+ * The develop image ref of a subject: `<developImageRegistry>/dev/<name...>` for a subject of a declared first-party
+ * source, else (a subject of no declared source, such as a customer's own image) the derivation from its release ref.
+ *
+ * @param {{repo?: string, imageRef: string}} subject
+ * @param {Record<string, {developImageRegistry: string}>} declaredSources `firstPartySources`
+ */
+export function developImageRefFor(subject, declaredSources) {
+  const root = developRootOf(subject.repo, declaredSources);
+  if (root === undefined) {return developImageRef(subject.imageRef);}
+  return `${root}/${DEVELOP_NAMESPACE_SEGMENT}/${releaseCoordinate(subject.imageRef).name}`;
+}
+
+/** The develop store root of the declared first-party source `repo`; undefined when `repo` is no declared source. */
+export function developRootOf(repo, declaredSources) {
+  return Object.hasOwn(declaredSources, repo) ? declaredSources[repo].developImageRegistry : undefined;
+}

package/edition/develop-image-probe.mjs

@@ -0,0 +1,122 @@
+// develop-image-probe — learn EARLY which develop images are not built yet.
+//
+// The develop seal verifies every subject's platforms, and only after it has
+// read all of them can it say which coordinates are absent. A develop edition
+// whose producer CI has not finished therefore failed minutes after the
+// content hashes were known. This probe asks the registry one cheap question
+// per subject — does `<developImageRef>:<contentHash>` resolve to a
+// hash-verified manifest — as soon as that subject's hash exists, in parallel
+// with the hashing of the rest, and `settle()` refuses with ONE error naming
+// every missing coordinate. It verifies existence only: the platform check, the
+// digest decision and the size bounds stay in the seal, which still runs. `settle()` also answers the digest each
+// present coordinate resolved to (`<kind>:<id>` -> digest), for a caller that records it (develop image-record).
+
+import { RefusalError } from './collected-refusals.mjs';
+import { developImageRefFor } from './develop-image-coordinate.mjs';
+import { editionsRoot } from './edition-workspace.mjs';
+import { loadRegistryCredentialDeclarations, splitImageRef } from './registry-credentials.mjs';
+import { isNotPublishedYet } from './seal-image-digests.mjs';
+import { registryClientsFor } from './verify-image-platforms.mjs';
+
+const DEFAULT_PROBE_CONCURRENCY = 6;
+
+/** One subject's line in the "not built yet" refusal of `channel` (develop unless named). */
+export function notBuiltYetMessage(subject, channel = 'develop') {
+  return (
+    `${subject.repo}@${subject.sourceCommit} ${channel} image ` +
+    `${subject.imageRef}:${subject.contentHash} not built yet`
+  );
+}
+
+/** The ONE refusal naming every subject of `channel` (develop unless named) whose coordinate is absent. */
+export function notBuiltYetError(distributionId, missingSubjects, channel = 'develop') {
+  return new RefusalError(
+    `${missingSubjects.length} ${channel} image(s) of "${distributionId}" are not built yet ` +
+      "(the producer's CI is not green or still running):\n  " +
+      missingSubjects.map((subject) => notBuiltYetMessage(subject, channel)).join('\n  '),
+  );
+}
+
+/**
+ * @param {object} request
+ * @param {string} request.distributionId the edition (named in the refusal)
+ * @param {object} request.declaredSources `firstPartySources`: roots the develop ref of each subject
+ * @returns {{ observe(subject: object): void, settle(): Promise<Map<string, string>> }}
+ *   `observe` takes a subject with `repo`, `sourceCommit`, `imageRef` (release ref) and `contentHash`
+ *   and starts its probe; `settle` waits for all of them and throws when any is absent or unreadable.
+ */
+export function createDevelopImageProbe({
+  distributionId,
+  declaredSources,
+  distributionsRoot = editionsRoot(),
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  run = null,
+  concurrency = DEFAULT_PROBE_CONCURRENCY,
+  progress = null,
+}) {
+  const declarations = loadRegistryCredentialDeclarations(distributionsRoot);
+  const clients = new Map();
+  const outcomes = [];
+  const waiting = [];
+  let active = 0;
+
+  function clientFor(subject) {
+    const { authority } = splitImageRef(subject.imageRef);
+    if (!clients.has(authority)) {
+      for (const [key, client] of registryClientsFor([subject], { declarations, env, fetchImpl, run })) {
+        clients.set(key, client);
+      }
+    }
+    return clients.get(authority);
+  }
+
+  async function probeOne(subject) {
+    const startedAt = Date.now();
+    const { repository } = splitImageRef(subject.imageRef);
+    try {
+      const { digest } = await clientFor(subject).getManifestByTag(repository, subject.contentHash);
+      progress?.(`[probe] ${subject.kind}:${subject.id} present ${Date.now() - startedAt}ms`);
+      return { subject, digest };
+    } catch (error) {
+      progress?.(`[probe] ${subject.kind}:${subject.id} ${isNotPublishedYet(error) ? 'ABSENT' : 'FAILED'} ${Date.now() - startedAt}ms`);
+      return { subject, error };
+    }
+  }
+
+  function next() {
+    const start = waiting.shift();
+    if (start !== undefined) {start();}
+  }
+
+  function schedule(subject) {
+    return new Promise((resolve) => {
+      const start = () => {
+        active += 1;
+        probeOne(subject).then((outcome) => {
+          active -= 1;
+          next();
+          resolve(outcome);
+        });
+      };
+      if (active < concurrency) {start();} else {waiting.push(start);}
+    });
+  }
+
+  return {
+    observe(subject) {
+      const developSubject = { ...subject, imageRef: developImageRefFor(subject, declaredSources) };
+      // Credentials resolve here, on the first subject of each registry, so a missing token stops the run now.
+      clientFor(developSubject);
+      outcomes.push(schedule(developSubject));
+    },
+    async settle() {
+      const settled = await Promise.all(outcomes);
+      const aborting = settled.find(({ error }) => error !== undefined && !isNotPublishedYet(error));
+      if (aborting) {throw aborting.error;}
+      const missing = settled.filter(({ error }) => error !== undefined).map(({ subject }) => subject);
+      if (missing.length > 0) {throw notBuiltYetError(distributionId, missing);}
+      return new Map(settled.map(({ subject, digest }) => [`${subject.kind}:${subject.id}`, digest]));
+    },
+  };
+}