@xemahq/xema 0.53.0 → 0.55.0

package/edition/develop-image-probe.mjs

@@ -8,8 +8,10 @@
 // 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.
+// 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 { developImageRef } from './develop-image-coordinate.mjs';
 import { editionsRoot } from './edition-workspace.mjs';
 import { loadRegistryCredentialDeclarations, splitImageRef } from './registry-credentials.mjs';
@@ -28,7 +30,7 @@ export function notBuiltYetMessage(subject, channel = 'develop') {
 
 /** The ONE refusal naming every subject of `channel` (develop unless named) whose coordinate is absent. */
 export function notBuiltYetError(distributionId, missingSubjects, channel = 'develop') {
-  return new Error(
+  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  '),
@@ -38,7 +40,7 @@ export function notBuiltYetError(distributionId, missingSubjects, channel = 'dev
 /**
  * @param {object} request
  * @param {string} request.distributionId the edition (named in the refusal)
- * @returns {{ observe(subject: object): void, settle(): Promise<void> }}
+ * @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.
  */
@@ -71,9 +73,9 @@ export function createDevelopImageProbe({
     const startedAt = Date.now();
     const { repository } = splitImageRef(subject.imageRef);
     try {
-      await clientFor(subject).getManifestByTag(repository, subject.contentHash);
+      const { digest } = await clientFor(subject).getManifestByTag(repository, subject.contentHash);
       progress?.(`[probe] ${subject.kind}:${subject.id} present ${Date.now() - startedAt}ms`);
-      return { subject };
+      return { subject, digest };
     } catch (error) {
       progress?.(`[probe] ${subject.kind}:${subject.id} ${isNotPublishedYet(error) ? 'ABSENT' : 'FAILED'} ${Date.now() - startedAt}ms`);
       return { subject, error };
@@ -112,6 +114,7 @@ export function createDevelopImageProbe({
       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]));
     },
   };
 }

package/edition/develop-image-record.mjs

@@ -0,0 +1,194 @@
+// develop-image-record — the body of `xema edition develop image-record <id> --selection <file> --pins <file> --out <file>`.
+//
+// Writes the edition's image build record (images-from-record.mjs, the file `resolve --images-from` reads) from the
+// records `select-records` selected. Its subjects are per-edition (`<kind>:<id>`), so they come from the checked-out
+// snapshot, which select-records cannot know: the subjects are enumerated as `coverage` enumerates them
+// (resolveDevelopSnapshot, then resolveImages on the normal hashing path, no recorded images).
+//
+//   a first-party subject of a currentResolution member (develop-current-resolution.mjs) is probed as resolve probes it
+//   (createDevelopImageProbe): the digest `<develop repository>:<contentHash>` resolves to goes in `images`, with the
+//   computed hash and the snapshot's source commit.
+//   every other first-party subject takes the selection's image named by its develop repository: digest and hash from
+//   the selection, source commit the one selection.pins names for the repository, which must be the snapshot's. It goes
+//   in `satellites`. Several subjects may share one image.
+//   a third-party subject is ignored: it keeps its pinned seal at resolve.
+//
+// Each entry's platforms are read from the registry BY DIGEST (resolvePublishedPlatforms: the index's runnable
+// children, attestations skipped, each proven by its image config; or the single manifest's config). Every problem is
+// collected and refused at once (ImageBuildRecordError); nothing is written then. The output passes parseImageBuildRecord.
+
+
+import { writeOnce } from './customer-edition-verbs.mjs';
+import { keepsCurrentResolution } from './develop-current-resolution.mjs';
+import { DEVELOP_EDITION_STEPS, resolveDevelopSnapshot } from './develop-edition-resolve.mjs';
+import { developGraphMembers } from './develop-graph.mjs';
+import { developImageRef } from './develop-image-coordinate.mjs';
+import { createDevelopImageProbe } from './develop-image-probe.mjs';
+import { parseSelectionPins } from './develop-selection-pins.mjs';
+import { editionsRoot } from './edition-workspace.mjs';
+import { firstPartySources } from './first-party-source-ids.mjs';
+import { ImageBuildRecordError, parseImageBuildRecord, requireImageBuildRecordKernel, subjectKeyOf } from './images-from-record.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
+import { loadRegistryCredentialDeclarations, splitImageRef } from './registry-credentials.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+import { compareStrings } from './string-order.mjs';
+import { registryClientsFor, resolvePublishedPlatforms } from './verify-image-platforms.mjs';
+
+const SELECTION_REQUIRED = Object.freeze(['pins', 'snapshot', 'images', 'behind']);
+const IMAGE_TEXT_KEYS = Object.freeze(['name', 'digest', 'contentHash', 'member']);
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * A selection `select-records` wrote, checked strictly: its four sections are present and shaped, each image names its
+ * owning `member`, and `pins` and `currentResolution` pass the one selection-pins validation (40-hex pins, and
+ * `currentResolution` exactly what the graph members declare).
+ *
+ * @param {unknown} document
+ * @param {readonly {repo: string}[]} members the develop graph
+ * @param {string} source the file, named in the refusal
+ */
+export function parseSelection(document, members, source) {
+  if (!isPlainObject(document)) {throw new ImageBuildRecordError(`selection ${source} must be a JSON object`);}
+  const problems = SELECTION_REQUIRED.filter((key) => document[key] === undefined).map((key) => `has no "${key}"`);
+  for (const key of ['snapshot', 'behind']) {
+    if (document[key] !== undefined && !isPlainObject(document[key])) {problems.push(`"${key}" must be an object`);}
+  }
+  if (document.images !== undefined && !Array.isArray(document.images)) {problems.push('"images" must be an array');}
+  (Array.isArray(document.images) ? document.images : []).forEach((image, index) => {
+    for (const key of IMAGE_TEXT_KEYS) {
+      if (!isPlainObject(image) || typeof image[key] !== 'string') {problems.push(`images[${index}].${key} must be a string`);}
+    }
+    if (isPlainObject(image) && image.members !== undefined && !Array.isArray(image.members)) {problems.push(`images[${index}].members must be an array`);}
+  });
+  if (problems.length > 0) {throw new ImageBuildRecordError(`selection ${source} is refused:\n  ${problems.join('\n  ')}`);}
+  parseSelectionPins(document, source, '--selection', members);
+  return document;
+}
+
+const platformOf = ({ platform }) => ({ os: platform.os, architecture: platform.architecture, ...(platform.variant === undefined ? {} : { variant: platform.variant }) });
+
+/** A cached reader of the platforms a develop image serves, read by digest through one registry client per authority. */
+export function createPlatformReader(clientFor) {
+  const cache = new Map();
+  return (repository, digest) => {
+    const key = `${repository}@${digest}`;
+    if (!cache.has(key)) {
+      const { authority, repository: path } = splitImageRef(repository);
+      cache.set(key, resolvePublishedPlatforms({ client: clientFor(authority), repository: path, digest, coordinate: key })
+        .then(({ platforms }) => platforms.map(platformOf)));
+    }
+    return cache.get(key);
+  };
+}
+
+/**
+ * @param {object} request
+ * @param {string} request.id the edition
+ * @param {object} request.pins the snapshot pins
+ * @param {object} request.selection a parsed selection
+ * @param {object} request.steps resolve steps (tests replace them)
+ * @param {Function} [request.resolveSnapshot] ({id, pins, steps}) => {inputs, lock}; replaced by tests
+ * @param {Function} request.createProbe ({distributionId}) => the develop image probe
+ * @param {(repository: string, digest: string) => Promise<object[]>} request.platformsOf
+ * @param {object} request.declaredSources `firstPartySources`
+ * @param {Function} [request.loadKernel] the kernel loader (tests replace it)
+ * @returns {Promise<{schemaVersion: 1, images: object[], satellites: object[]}>}
+ */
+export async function buildImageRecord({ id, pins, selection, steps = DEVELOP_EDITION_STEPS, resolveSnapshot = resolveDevelopSnapshot, createProbe, platformsOf, declaredSources, loadKernel = loadKernelDistributionSchemas }) {
+  const kernel = requireImageBuildRecordKernel(await loadKernel());
+  const { inputs, lock } = await resolveSnapshot({ id, pins, steps });
+  const probe = createProbe({ distributionId: id });
+  const isFirstParty = (subject) => Object.hasOwn(declaredSources, subject.repo);
+  const { imageLock } = await steps.resolveImages(id, {
+    inputs,
+    lock,
+    onSubjectHashed: (subject) => {
+      if (isFirstParty(subject) && keepsCurrentResolution(declaredSources[subject.repo])) {probe.observe(subject);}
+    },
+  });
+  const probed = await probe.settle();
+  const problems = [];
+  const built = [];
+  const satellites = [];
+  for (const subject of imageLock.subjects.filter(isFirstParty)) {
+    const key = subjectKeyOf(subject);
+    const repository = developImageRef(subject.imageRef);
+    if (keepsCurrentResolution(declaredSources[subject.repo])) {
+      built.push({ subject: key, repository, contentHash: subject.contentHash, digest: probed.get(key), sourceSha: subject.sourceCommit });
+      continue;
+    }
+    const image = selection.images.find(({ name }) => name === repository);
+    if (image === undefined) {
+      problems.push(`${key} (${subject.repo}): the selection has no image ${repository}`);
+      continue;
+    }
+    if (image.member !== subject.repo) {
+      problems.push(`${key} (${subject.repo}): the selection's image ${repository} belongs to member ${image.member}, not ${subject.repo}`);
+      continue;
+    }
+    const selected = selection.pins[image.member];
+    if (selected !== subject.sourceCommit) {
+      problems.push(`${key} (${subject.repo}): the selection pins ${selected}, not ${subject.sourceCommit}, the commit the snapshot pins`);
+      continue;
+    }
+    // The subject's COMPUTED hash is the one recorded: the heads path's probe already finds dev/<image>:<computed hash>, so
+    // producer CI and this CLI agree on the hash, and a selected hash that differs is a real mismatch, never overwritten.
+    if (image.contentHash !== subject.contentHash) {
+      problems.push(`${key} (${subject.repo}): the selection's content hash ${image.contentHash} is not the computed ${subject.contentHash}`);
+      continue;
+    }
+    // A composed image's members[{service, key}] are the build record's own, copied unchanged and never recomputed; the kernel's
+    // ImageBuildRecord parse refuses them on any other entry.
+    satellites.push({ subject: key, repository, contentHash: subject.contentHash, digest: image.digest, sourceSha: selected, ...(image.members === undefined ? {} : { members: image.members }) });
+  }
+  const withPlatforms = async (entries) => {
+    const out = [];
+    for (const entry of entries) {
+      try {
+        out.push({ ...entry, platforms: await platformsOf(entry.repository, entry.digest) });
+      } catch (error) {
+        problems.push(`${entry.subject}: the platforms of ${entry.repository}@${entry.digest} could not be read: ${error.message}`);
+      }
+    }
+    return out.sort((a, b) => compareStrings(a.subject, b.subject));
+  };
+  const record = { schemaVersion: kernel.IMAGE_BUILD_RECORD_SCHEMA_VERSION, images: await withPlatforms(built), satellites: await withPlatforms(satellites) };
+  if (problems.length > 0) {
+    throw new ImageBuildRecordError(`the image build record of "${id}" cannot be written (${problems.length} problem(s)):\n  ${problems.join('\n  ')}`);
+  }
+  return parseImageBuildRecord(record, 'develop image-record', { loadKernel: async () => kernel });
+}
+
+/** The `image-record` verb. Writes `--out` once, only after every subject is covered. */
+export async function runImageRecord({
+  id,
+  options,
+  env = process.env,
+  steps = DEVELOP_EDITION_STEPS,
+  members = developGraphMembers(),
+  declaredSources = firstPartySources('enumerating the first-party image subjects'),
+  createProbe = (request) => createDevelopImageProbe({ ...request, env }),
+  resolveSnapshot,
+  clientFor,
+  write = writeOnce,
+}) {
+  const selection = parseSelection(readStrictJsonFile(options['--selection']), members, options['--selection']);
+  const declarations = clientFor === undefined ? loadRegistryCredentialDeclarations(editionsRoot()) : null;
+  const clients = new Map();
+  const registryClient = clientFor ?? ((authority) => {
+    if (!clients.has(authority)) {clients.set(authority, registryClientsFor([{ imageRef: `${authority}/x` }], { declarations, env }).get(authority));}
+    return clients.get(authority);
+  });
+  const record = await buildImageRecord({
+    id,
+    pins: readStrictJsonFile(options['--pins']),
+    selection,
+    steps,
+    ...(resolveSnapshot === undefined ? {} : { resolveSnapshot }),
+    createProbe,
+    platformsOf: createPlatformReader(registryClient),
+    declaredSources,
+  });
+  write(options['--out'], record);
+  return record;
+}

package/edition/develop-record-ancestry.mjs

@@ -9,9 +9,12 @@
 // With a published commit for the member, the records may not take it backwards: behind or equal keeps the published
 // commit (its own record must then exist), ahead selects the records' commit, otherwise the run is refused.
 //
+// The result also carries develop's head (`git rev-parse refs/heads/develop`) and `behind`, the commits the selected
+// one trails that head by (`git rev-list --count <selected>..refs/heads/develop`), both from the same fetch.
+//
 // Refusals (`RecordRefused`): a commit absent from the fetched develop history, two commits that are not
 // ancestor-related. Operational (plain Error): git cannot be spawned, a fetch fails, or merge-base answers
-// anything but 0 (ancestor) or 1 (not an ancestor).
+// anything but 0 (ancestor) or 1 (not an ancestor), or rev-parse or rev-list fails or answers a non-number.
 
 import { spawnSync } from 'node:child_process';
 import { mkdtempSync, rmSync } from 'node:fs';
@@ -72,7 +75,8 @@ export function defaultRunGit(args, { cwd, env }) {
  * @param {object} request.workspace the workspace config the source hold reads
  * @param {object} request.env
  * @param {Function} [request.runGit] (args, {cwd, env}) => {status, stdout, stderr}; replaced by tests
- * @returns {string} the selected commit
+ * @returns {{commit: string, head: string, behind: number}} the selected commit, develop's head in the same fetch, and
+ *   how many commits the selected one is behind that head (0 when it is the head)
  */
 export function newestCommitOnDevelop({ member, candidates, published, workspace, env, runGit = defaultRunGit }) {
   const byCommit = new Map();
@@ -109,10 +113,24 @@ export function newestCommitOnDevelop({ member, candidates, published, workspace
         if (!isAncestor(selected.commit, other.commit)) {throw new IncomparableRecordCommitsError(member.repo, selected, other);}
         selected = other;
       }
-      if (published === undefined) {return selected.commit;}
+      // develop's head and the chosen commit's distance from it, read in the same scratch the choice was made in
+      const withDistance = (commit) => {
+        const headResult = git(['rev-parse', DEVELOP_REF]);
+        const head = headResult.stdout.trim();
+        if (headResult.status !== 0 || !/^[0-9a-f]{40}$/.test(head)) {
+          throw new Error(`select-records: ${member.repo}: git rev-parse ${DEVELOP_REF} failed (exit ${headResult.status}): ${headResult.stderr.trim() || head}`);
+        }
+        const counted = git(['rev-list', '--count', `${commit}..${DEVELOP_REF}`]);
+        const behind = Number(counted.stdout.trim());
+        if (counted.status !== 0 || !/^\d+$/.test(counted.stdout.trim())) {
+          throw new Error(`select-records: ${member.repo}: git rev-list --count ${commit}..${DEVELOP_REF} failed (exit ${counted.status}): ${counted.stderr.trim() || counted.stdout.trim()}`);
+        }
+        return { commit, head, behind };
+      };
+      if (published === undefined) {return withDistance(selected.commit);}
       assertOnDevelop(published, ['published pin']);
-      if (isAncestor(selected.commit, published)) {return published;} // equal, or the records are behind it
-      if (isAncestor(published, selected.commit)) {return selected.commit;}
+      if (isAncestor(selected.commit, published)) {return withDistance(published);} // equal, or the records are behind it
+      if (isAncestor(published, selected.commit)) {return withDistance(selected.commit);}
       throw new DivergedFromPublishedError(member.repo, selected.commit, published);
     });
   } finally {

package/edition/develop-resolve-report.mjs

@@ -0,0 +1,159 @@
+import { isRefusal } from './collected-refusals.mjs';
+
+// develop-resolve-report — every refusal of one develop resolve, in one report.
+//
+// `xema edition develop resolve` runs a set of checks. A check that needs the output of another is a DEPENDENT of
+// it; every other check is independent. The collector runs each check, records a refusal instead of throwing it, and
+// skips (records as blocked) every check whose dependency was refused or blocked. `settle()` then throws ONE error whose
+// message is the table, so an operator sees what to fix, and who owns each fix, after a single run. Nothing is
+// downgraded: every refusal stays a refusal, and a run with a row writes nothing.
+
+/** The checks of a develop resolve, in the order the report lists them. */
+export const DevelopResolveCheck = Object.freeze({
+  EditionProtocol: 'edition-protocol',
+  DistributionLock: 'distribution-lock',
+  BundleSigner: 'bundle-signer',
+  PlaneInvariants: 'plane-invariants',
+  OperationAdmission: 'operation-admission',
+  AdapterBundles: 'adapter-bundles',
+  AuthorizationBase: 'authorization-base',
+  DevelopImages: 'develop-images',
+  EngineImage: 'engine-image',
+  ChartSet: 'chart-set',
+});
+
+/** Who fixes a refused check. */
+export const ResolveCheckOwner = Object.freeze({
+  Producer: 'producer (the repository the refusal names)',
+  XemaCli: 'xema-cli',
+  EditionOwner: 'edition-owner (the repository that declares the edition)',
+  DeployOwner: 'deploy-owner (the repository that builds the engine and the charts)',
+});
+
+export const RESOLVE_CHECK_OWNERS = Object.freeze({
+  [DevelopResolveCheck.EditionProtocol]: ResolveCheckOwner.XemaCli,
+  [DevelopResolveCheck.DistributionLock]: ResolveCheckOwner.EditionOwner,
+  [DevelopResolveCheck.BundleSigner]: ResolveCheckOwner.EditionOwner,
+  [DevelopResolveCheck.PlaneInvariants]: ResolveCheckOwner.EditionOwner,
+  [DevelopResolveCheck.OperationAdmission]: ResolveCheckOwner.Producer,
+  [DevelopResolveCheck.AdapterBundles]: ResolveCheckOwner.Producer,
+  [DevelopResolveCheck.AuthorizationBase]: ResolveCheckOwner.EditionOwner,
+  [DevelopResolveCheck.DevelopImages]: ResolveCheckOwner.Producer,
+  [DevelopResolveCheck.EngineImage]: ResolveCheckOwner.DeployOwner,
+  [DevelopResolveCheck.ChartSet]: ResolveCheckOwner.DeployOwner,
+});
+
+const C = DevelopResolveCheck;
+
+/**
+ * What each check needs verified before it runs: a check that consumes a predecessor's result is not run on the state a
+ * refused predecessor left behind, it is reported `blocked by` the refusal at the root.
+ * The checks that read the lock but consume no other check's verdict are independent of each other on purpose, so one run
+ * names all of them: the plane invariants (the graph), the operation admission (the lock's requirements) and the adapter
+ * bundles (the lock against the registry). The authorization base is composed from, and the images are hashed from, the
+ * lock AFTER those verified it. Chart set and engine image read only the pins.
+ */
+export const RESOLVE_CHECK_DEPENDENCIES = Object.freeze({
+  [C.EditionProtocol]: [],
+  [C.DistributionLock]: [C.EditionProtocol],
+  [C.BundleSigner]: [C.DistributionLock],
+  [C.PlaneInvariants]: [C.DistributionLock],
+  [C.OperationAdmission]: [C.DistributionLock],
+  [C.AdapterBundles]: [C.DistributionLock],
+  [C.AuthorizationBase]: [C.DistributionLock, C.BundleSigner, C.PlaneInvariants, C.OperationAdmission],
+  [C.DevelopImages]: [C.DistributionLock, C.BundleSigner, C.PlaneInvariants, C.OperationAdmission],
+  [C.EngineImage]: [],
+  [C.ChartSet]: [],
+});
+
+/** How a recorded check ended. */
+export const ResolveRowStatus = Object.freeze({ Refused: 'refused', Blocked: 'blocked' });
+
+/** What `run` returns for a check that did not produce a value: refused, or blocked by a dependency. */
+export const BLOCKED = Symbol('develop-resolve-blocked');
+
+const CHECK_ORDER = Object.values(DevelopResolveCheck);
+const COLUMNS = Object.freeze(['CHECK', 'OWNER', 'STATUS', 'DETAIL']);
+const DETAIL_INDENT = '    ';
+
+const statusOf = (row) => (row.status === ResolveRowStatus.Blocked ? `blocked by ${row.blockedBy}` : ResolveRowStatus.Refused);
+
+const NOTICE_HEADING = 'NOTICE: ungranted optional operations';
+
+/** The notices as one section: never a refusal, so it is separate from the table. Empty when there are none. */
+export const renderResolveNotices = (notices) =>
+  notices.length === 0 ? '' : [`${NOTICE_HEADING} (${notices.length})`, ...notices.map((notice) => `${DETAIL_INDENT}${notice}`)].join('\n');
+
+/** The report rows as one plain-text table, in the order of {@link DevelopResolveCheck}; a multi-line detail is indented under its row. */
+export function renderResolveReport(rows) {
+  const sorted = [...rows].sort((a, b) => CHECK_ORDER.indexOf(a.check) - CHECK_ORDER.indexOf(b.check));
+  const cells = sorted.map((row) => {
+    const [firstLine = '', ...more] = (row.detail ?? '').split('\n');
+    return { columns: [row.check, row.owner, statusOf(row), firstLine], more };
+  });
+  const widths = COLUMNS.slice(0, -1).map((name, i) => Math.max(name.length, ...cells.map((c) => c.columns[i].length)));
+  const line = (values) => [...values.slice(0, -1).map((v, i) => v.padEnd(widths[i])), values.at(-1)].join('  ').trimEnd();
+  const body = cells.flatMap(({ columns, more }) => [line(columns), ...more.map((m) => `${DETAIL_INDENT}${m}`.trimEnd())]);
+  return [`develop resolve refused: ${rows.length} check(s) did not pass; nothing was sealed or written`, line(COLUMNS), ...body].join('\n');
+}
+
+/** The one error of a develop resolve that had a refusal; `.rows` are the recorded rows, the message is the table. */
+export class DevelopResolveRefusedError extends Error {
+  constructor(rows, notices = []) {
+    super([renderResolveReport(rows), renderResolveNotices(notices)].filter((part) => part !== '').join('\n\n'));
+    this.name = 'DevelopResolveRefusedError';
+    this.rows = rows;
+    this.notices = notices;
+  }
+}
+
+export function createResolveReport() {
+  const rows = [];
+  const byCheck = new Map();
+  const notices = [];
+  const record = (row) => {
+    rows.push(row);
+    byCheck.set(row.check, row);
+  };
+
+  return {
+    rows,
+    notices,
+    /** Add one line to the NOTICE section; it never refuses and never changes the exit code. */
+    notice(line) {
+      notices.push(line);
+    },
+    /** The NOTICE section as text ('' when there is none). */
+    noticeText: () => renderResolveNotices(notices),
+    /**
+     * Run `fn` as `check`, unless a check it depends on was refused or blocked (it is then blocked by the root refusal).
+     * `classify(error)` may name another check the thrown error belongs to; that check is then the one refused,
+     * and `check` is blocked by it.
+     */
+    async run(check, dependsOn, fn, { classify = () => check } = {}) {
+      const blocker = dependsOn.map((dependency) => byCheck.get(dependency)).find((row) => row !== undefined);
+      if (blocker !== undefined) {
+        // Always the refusal at the root: a check blocked by a blocked check names the check that was refused.
+        const blockedBy = blocker.status === ResolveRowStatus.Blocked ? blocker.blockedBy : blocker.check;
+        record({ check, owner: RESOLVE_CHECK_OWNERS[check], status: ResolveRowStatus.Blocked, blockedBy });
+        return BLOCKED;
+      }
+      try {
+        return await fn();
+      } catch (error) {
+        // A defect (a TypeError, a failed system call, a registry answering 5xx) is not a refusal: it propagates as thrown.
+        if (!isRefusal(error)) {throw error;}
+        const filedUnder = classify(error);
+        record({ check: filedUnder, owner: RESOLVE_CHECK_OWNERS[filedUnder], status: ResolveRowStatus.Refused, detail: error.message, error });
+        if (filedUnder !== check) {
+          record({ check, owner: RESOLVE_CHECK_OWNERS[check], status: ResolveRowStatus.Blocked, blockedBy: filedUnder });
+        }
+        return BLOCKED;
+      }
+    },
+    /** Throw the one error when any check was refused or blocked. */
+    settle() {
+      if (rows.length > 0) {throw new DevelopResolveRefusedError(rows, notices);}
+    },
+  };
+}

package/edition/develop-select-records.mjs

@@ -13,6 +13,15 @@
 // when the records are not ahead of it, and a diverged one is refused; without it the rule applies among the
 // records only (part 07 passes the flag).
 //
+// The output also carries `behind: { <repo>: { head, commits } }`: develop's head and how many commits the selected
+// commit trails it by, from the same fetch (0 when the record is the head). The verb prints one line per member, in
+// repo order, after writing --out, formatted by develop-selection-line.mjs (`<short name>: record <commit>, <N> commits behind HEAD`,
+// always `commits`, never singular; short name = the repo's last path segment, unambiguous across members).
+//
+// A member that declares a currentResolution (develop-current-resolution.mjs) is skipped, its registry never read; the
+// selection lists it as `currentResolution: { <repo>: <ticket> }` and the verb prints `<short name>: current resolution
+// (leaves the edition, <ticket>)` in its place. Every other member without a record still refuses.
+//
 // Every failure is a hard refusal naming the repository, and nothing is written. Two classes: `RecordRefused`
 // (the record is missing, or cosign or the record itself says no) and a plain Error (the registry or cosign
 // could not answer), which the operator retries rather than reads.
@@ -22,6 +31,7 @@
 // backwards. This verb checks nothing against current pins.
 
 import { writeOnce } from './customer-edition-verbs.mjs';
+import { currentResolutionOf, keepsCurrentResolution } from './develop-current-resolution.mjs';
 import { developGraphMembers } from './develop-graph.mjs';
 import { PublishedRecordMissingError, newestCommitOnDevelop } from './develop-record-ancestry.mjs';
 import {
@@ -32,10 +42,11 @@ import {
   requireBuildRecordKernel,
   withRecordVerifier,
 } from './develop-record-verify.mjs';
+import { assertShortNamesUnambiguous, formatSelectionLine } from './develop-selection-line.mjs';
+import { readSelectionPins } from './develop-selection-pins.mjs';
 import { editionWorkspaceConfig } from './edition-config.mjs';
 import { compareStrings } from './lib.mjs';
 import { RecordRefused } from './record-refused.mjs';
-import { readStrictJsonFile } from './strict-json.mjs';
 
 // The record-verification names this verb's tests and callers read from here, owned by the shared core.
 export {
@@ -64,16 +75,19 @@ const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
  * @param {object} request.workspace the workspace config the source hold reads
  * @param {object} request.env
  * @param {Function} [request.runGit] replaced by tests
- * @returns {Promise<{pins: object, snapshot: object, images: object[]}>}
+ * @returns {Promise<{pins: object, snapshot: object, behind: object, images: object[], currentResolution: object}>}
  */
 export async function selectRecords({ branch, registry, at, members, dataRootRepositoryUrl, kernel, clientFor, runCosign, cosignEnvFor, trustedRootPath, publishedPins, workspace, env, runGit }) {
   requireBuildRecordKernel(kernel);
+  assertShortNamesUnambiguous(members);
   recordSignerOrigin({ branch, dataRootRepositoryUrl });
   if (at !== undefined && (!ISO_UTC.test(at) || Number.isNaN(Date.parse(at)))) {
     throw new Error(`--at must be an ISO-8601 UTC time (YYYY-MM-DDTHH:MM:SSZ); got ${JSON.stringify(at)}`);
   }
   const selected = [];
   for (const member of members) {
+    // the one declared exception (develop-current-resolution.mjs): no registry read, no record
+    if (keepsCurrentResolution(member)) {continue;}
     const { repository, authority, client, runs } = await listBuildRecordRuns({ kernel, clientFor, registry, member, branch });
     // EVERY candidate is read and verified; any that fails refuses the run. None is skipped.
     const verified = [];
@@ -87,7 +101,7 @@ export async function selectRecords({ branch, registry, at, members, dataRootRep
     const eligible = at === undefined ? verified : verified.filter(({ record }) => Date.parse(record.completedAt) <= Date.parse(at));
     if (eligible.length === 0) {throw new RecordRefused(member.repo, `no build record for branch ${branch} completed at or before ${at}`);}
     const published = publishedPins?.[member.repo];
-    const commit = newestCommitOnDevelop({
+    const { commit, head, behind } = newestCommitOnDevelop({
       member, candidates: eligible.map(({ record, tag }) => ({ commit: record.commit, tag })), published, workspace, env, runGit,
     });
     // records of one commit are re-runs of it: the highest run, then attempt
@@ -96,46 +110,36 @@ export async function selectRecords({ branch, registry, at, members, dataRootRep
     const ofCommit = ofCommitIn(eligible).length > 0 ? ofCommitIn(eligible) : ofCommitIn(verified);
     if (ofCommit.length === 0) {throw new PublishedRecordMissingError(member.repo, commit);}
     const chosen = ofCommit[0];
-    selected.push({ member, ...chosen });
+    selected.push({ member, head, behind, ...chosen });
   }
-  return composeSelection(selected);
+  return { ...composeSelection(selected), currentResolution: currentResolutionOf(members) };
 }
 
 /** The snapshot a selection writes. A name built by two records is refused: an image has one builder. */
 export function composeSelection(selected) {
   const pins = {};
   const snapshot = {};
+  const behind = {};
   const owners = new Map();
   const images = [];
-  for (const { member, record, snapshot: run } of selected) {
+  for (const { member, record, snapshot: run, head, behind: commits } of selected) {
     pins[member.repo] = record.commit;
+    behind[member.repo] = { head, commits };
     snapshot[member.repo] = run;
     for (const image of record.images) {
       if (owners.has(image.name)) {
         throw new RecordRefused(member.repo, `image ${image.name} is also built by ${owners.get(image.name)}; an image has one builder`);
       }
       owners.set(image.name, member.repo);
-      images.push({ name: image.name, digest: image.digest, contentHash: image.contentHash });
+      images.push({ name: image.name, digest: image.digest, contentHash: image.contentHash, member: member.repo, ...(image.members === undefined ? {} : { members: image.members }) });
     }
   }
   const sorted = (object) => Object.fromEntries(Object.entries(object).sort(([a], [b]) => compareStrings(a, b)));
-  return { pins: sorted(pins), snapshot: sorted(snapshot), images: images.sort((a, b) => compareStrings(a.name, b.name)) };
+  return { pins: sorted(pins), snapshot: sorted(snapshot), behind: sorted(behind), images: images.sort((a, b) => compareStrings(a.name, b.name)) };
 }
 
 /** The `pins` of a file this verb wrote: member repo -> 40-hex commit. Nothing else of the file is read. */
-export function readPublishedPins(path) {
-  const document = readStrictJsonFile(path);
-  const { pins } = document ?? {};
-  if (pins === null || typeof pins !== 'object' || Array.isArray(pins)) {
-    throw new Error(`--published-pins ${path} has no "pins" object`);
-  }
-  for (const [repo, commit] of Object.entries(pins)) {
-    if (typeof commit !== 'string' || !/^[0-9a-f]{40}$/.test(commit)) {
-      throw new Error(`--published-pins ${path}: pin ${JSON.stringify(repo)} is not a 40-hex commit: ${JSON.stringify(commit)}`);
-    }
-  }
-  return pins;
-}
+export const readPublishedPins = (path) => readSelectionPins(path, '--published-pins');
 
 /** The `select-records` verb. Writes `--out` once, only after every member was selected. */
 export async function runSelectRecords({
@@ -144,6 +148,7 @@ export async function runSelectRecords({
   members = developGraphMembers(),
   runGit,
   write = writeOnce,
+  print = (text) => process.stdout.write(text),
   ...verifierInjections
 }) {
   return withRecordVerifier({ cosignBinary: options['--cosign'], env, ...verifierInjections }, async (verifier) => {
@@ -159,6 +164,9 @@ export async function runSelectRecords({
       runGit,
     });
     write(options['--out'], selection);
+    for (const member of members) {
+      print(`${formatSelectionLine(member, selection)}\n`);
+    }
     return selection;
   });
 }

package/edition/develop-selection-line.mjs

@@ -0,0 +1,30 @@
+// develop-selection-line — the one stdout line `select-records` prints per member, and the check that lines are unambiguous.
+//
+//   <short name>: record <40-hex commit>, <N> commits behind HEAD
+//   <short name>: current resolution (leaves the edition, <ticket>)
+//
+// The short name is the repo handle's last path segment. The develop-edition workflow in xema-distributions
+// (develop-edition.yaml) parses these lines with the same pattern; change both together.
+
+import { keepsCurrentResolution } from './develop-current-resolution.mjs';
+
+export const shortNameOf = (repo) => repo.split('/').at(-1);
+
+/** One graph member's line (no newline): its current-resolution line, or its record, commit and distance from develop HEAD. */
+export function formatSelectionLine(member, selection) {
+  const { repo } = member;
+  if (keepsCurrentResolution(member)) {
+    return `${shortNameOf(repo)}: current resolution (leaves the edition, ${member.currentResolution})`;
+  }
+  return `${shortNameOf(repo)}: record ${selection.pins[repo]}, ${selection.behind[repo].commits} commits behind HEAD`;
+}
+
+/** Two members with one short name would print indistinguishable lines: refused by name. */
+export function assertShortNamesUnambiguous(members) {
+  const seen = new Map();
+  for (const { repo } of members) {
+    const name = shortNameOf(repo);
+    if (seen.has(name)) {throw new Error(`select-records: members ${seen.get(name)} and ${repo} share the short name "${name}"; the printed lines would be ambiguous`);}
+    seen.set(name, repo);
+  }
+}

package/edition/develop-selection-pins.mjs

@@ -0,0 +1,30 @@
+// develop-selection-pins — the `pins` of a file `select-records` wrote: member repo -> 40-hex commit. Nothing else of
+// the file is read here. `flag` names the option the file came in on (--published-pins, --member-pins), for the refusal.
+
+import { currentResolutionProblem } from './develop-current-resolution.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+/**
+ * @param {readonly {repo: string}[]} [members] when given, the file's `currentResolution` must also be exactly
+ *   what these graph members declare (develop-current-resolution.mjs)
+ * @returns {Record<string, string>} the file's `pins`, each a 40-hex commit
+ */
+export const readSelectionPins = (path, flag, members) => parseSelectionPins(readStrictJsonFile(path), path, flag, members);
+
+/** The same over a document already read: the ONE validation of a selection's `pins` (and `currentResolution`). */
+export function parseSelectionPins(document, path, flag, members) {
+  const { pins } = document ?? {};
+  if (pins === null || typeof pins !== 'object' || Array.isArray(pins)) {
+    throw new Error(`${flag} ${path} has no "pins" object`);
+  }
+  for (const [repo, commit] of Object.entries(pins)) {
+    if (typeof commit !== 'string' || !/^[0-9a-f]{40}$/.test(commit)) {
+      throw new Error(`${flag} ${path}: pin ${JSON.stringify(repo)} is not a 40-hex commit: ${JSON.stringify(commit)}`);
+    }
+  }
+  if (members !== undefined) {
+    const problem = currentResolutionProblem(document.currentResolution, members);
+    if (problem !== null) {throw new Error(`${flag} ${path}: ${problem}`);}
+  }
+  return pins;
+}