@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/develop-image-record.mjs

@@ -0,0 +1,260 @@
+// develop-image-record — the body of `xema-edition develop image-record <id> --selection <file> --pins <file> --out <file>
+// --channel <tag>`. (`--registry <root>` is still accepted for one release and unused.)
+//
+// Writes the edition's image build record (images-from-record.mjs, the file `resolve --images-from` reads) from the
+// records `select-records --channel <tag>` selected. Its subjects are per-edition (`<kind>:<id>`), so they come from the
+// checked-out snapshot, which select-records cannot know: they are enumerated by resolveImages over the admitted
+// snapshot (resolveDevelopSnapshot) with the SELECTION standing in for every hash (`createSelectedImages`), so no
+// content hash is computed for them:
+//
+//   every first-party subject takes the selection's image named by its develop repository: digest AND contentHash from
+//   the selection, source commit the snapshot's (freeze-graph --member-pins pinned it at the selected commit). It goes
+//   in `satellites`. Several subjects may share one image. A composed subject's members keep the snapshot's rows
+//   (service, packageDir) and each takes as its key the contentHash of the member service's own selected develop image
+//   (`selectedMembers`): the contract's key, stated by the producer, never computed or compared. Each satellite is then checked against the
+//   producer record the selection pinned, read by its own record tag (develop-channel-satellites.mjs): it must sit at
+//   the snapshot's commit and list the image. The channel tag moving after selection does not affect the run.
+//   THE ONE DECLARED EXCEPTION (XEMA-2373): a subject of a member that keeps its current resolution
+//   (develop-current-resolution.mjs, today xema-docs) has no build record, so its content hash IS computed and its develop
+//   image probed by it (createDevelopImageProbe): the digest `<develop repository>:<contentHash>` resolves to goes in
+//   `images`, with the computed hash and the snapshot's source commit. It ends when that member leaves the edition.
+//   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
+// refused (ImageBuildRecordError), the subjects' at once; nothing is written then. The output passes parseImageBuildRecord.
+
+import { writeOnce } from './customer-edition-verbs.mjs';
+import { createChannelSatelliteVerifier } from './develop-channel-satellites.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 { developImageRefFor } 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(['channel', 'pins', 'snapshot', 'images']);
+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 --channel` wrote, checked strictly: its 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}"`);
+  if (document.channel !== undefined && typeof document.channel !== 'string') {problems.push('"channel" must be a string');}
+  if (document.snapshot !== undefined && !isPlainObject(document.snapshot)) {problems.push('"snapshot" 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;
+}
+
+/**
+ * The selection as `resolveImages` consumes it (`recordedImages`): `take` gives each first-party subject the selected
+ * image's content hash (and a composed subject its members' keys, `selectedMembers`), never computed; `computesHash`
+ * names the declared XEMA-2373 exception, the subjects of a member that keeps its current resolution, which
+ * resolveImages hashes; `settle` refuses, all at once, every subject with no digest (no selected image of its develop
+ * repository) and every composed member with no selected image of its own. Which member's record listed the image is
+ * not checked.
+ *
+ * @param {object} selection a parsed selection
+ * @param {{distributionId: string, declaredSources: object}} context `declaredSources` is `firstPartySources`
+ */
+export function createSelectedImages(selection, { distributionId, declaredSources }) {
+  const problems = [];
+  const images = new Map();
+  const unresolved = (subject) => ({ sourceCommit: subject.sourceCommit, contentHash: null });
+  return {
+    computesHash: (subject) => Object.hasOwn(declaredSources, subject.repo) && keepsCurrentResolution(declaredSources[subject.repo]),
+    take(subject) {
+      const key = subjectKeyOf(subject);
+      const repository = developImageRefFor(subject, declaredSources);
+      const image = selection.images.find(({ name }) => name === repository);
+      if (image === undefined) {
+        problems.push(`${key} (${subject.repo}) has no digest: the selection has no image ${repository}`);
+        return unresolved(subject);
+      }
+      const members = selectedMembers(key, subject, selection, problems, declaredSources);
+      images.set(key, { image, members });
+      return { sourceCommit: subject.sourceCommit, contentHash: image.contentHash, ...(members === undefined ? {} : { members }) };
+    },
+    settle() {
+      if (problems.length > 0) {
+        throw new ImageBuildRecordError(`the image build record of "${distributionId}" cannot be written (${problems.length} problem(s)):\n  ${problems.join('\n  ')}`);
+      }
+    },
+    /** The selected image a subject took, or undefined for one it did not (a hashed or third-party subject). */
+    imageOf: (subject) => images.get(subjectKeyOf(subject))?.image,
+    /** The member rows a composed subject took (`{service, packageDir, key}`), or undefined. */
+    membersOf: (subject) => images.get(subjectKeyOf(subject))?.members,
+  };
+}
+
+/**
+ * A composed subject's members, each with its KEY: the contract's key is the member service's own image-input content
+ * hash, the value its own subject carries, and the producer's build record states it as the `contentHash` of the
+ * service's own develop image (the composed image's namespace plus the service name). It is taken from the selected
+ * image unchanged: never computed, never compared. A member with no selected image of its own is a problem naming the
+ * member and the composed subject. A subject that is not composed gives undefined.
+ */
+export function selectedMembers(key, subject, selection, problems, declaredSources) {
+  if (subject.members === undefined) {return undefined;}
+  if (!subject.imageRef.endsWith(subject.id)) {
+    problems.push(`${key}: its imageRef ${subject.imageRef} does not end in its id, so its members' develop images cannot be named`);
+    return undefined;
+  }
+  const namespace = subject.imageRef.slice(0, subject.imageRef.length - subject.id.length);
+  const missing = [];
+  const members = subject.members.map((member) => {
+    const repository = developImageRefFor({ repo: subject.repo, imageRef: `${namespace}${member.service}` }, declaredSources);
+    const image = selection.images.find(({ name }) => name === repository);
+    if (image === undefined) {missing.push(`${member.service} (${repository})`);}
+    return { ...member, key: image?.contentHash };
+  });
+  if (missing.length > 0) {
+    problems.push(`${key}: the selection has no image of its member${missing.length > 1 ? 's' : ''} ${missing.join(', ')}, whose content hash is that member's key`);
+    return undefined;
+  }
+  return members;
+}
+
+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 (the XEMA-2373 exception only)
+ * @param {(repository: string, digest: string) => Promise<object[]>} request.platformsOf
+ * @param {object} request.declaredSources `firstPartySources`
+ * @param {Function} [request.loadKernel] the kernel loader (tests replace it)
+ * @param {(claims: {subject: object, entry: object}[]) => Promise<void>} request.verifySatellites the channel check of
+ *   the satellite entries: each is listed by the producer record the selection pinned, at the pinned commit
+ * @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, verifySatellites }) {
+  const kernel = requireImageBuildRecordKernel(await loadKernel());
+  const { inputs, lock } = await resolveSnapshot({ id, pins, steps });
+  const selected = createSelectedImages(selection, { distributionId: id, declaredSources });
+  const { imageLock } = await steps.resolveImages(id, { inputs, lock, recordedImages: selected });
+  const firstParty = imageLock.subjects.filter((subject) => Object.hasOwn(declaredSources, subject.repo));
+  const current = firstParty.filter((subject) => keepsCurrentResolution(declaredSources[subject.repo]));
+  let probed = new Map();
+  if (current.length > 0) {
+    const probe = createProbe({ distributionId: id });
+    current.forEach((subject) => probe.observe(subject));
+    probed = await probe.settle();
+  }
+  const problems = [];
+  const built = current.map((subject) => ({ subject: subjectKeyOf(subject), repository: developImageRefFor(subject, declaredSources), contentHash: subject.contentHash, digest: probed.get(subjectKeyOf(subject)), sourceSha: subject.sourceCommit }));
+  const claimed = firstParty.filter((subject) => !keepsCurrentResolution(declaredSources[subject.repo])).map((subject) => {
+    const image = selected.imageOf(subject);
+    const members = selected.membersOf(subject)?.map(({ service, key }) => ({ service, key })).sort((a, b) => compareStrings(a.service, b.service));
+    const entry = { subject: subjectKeyOf(subject), repository: image.name, contentHash: image.contentHash, digest: image.digest, sourceSha: subject.sourceCommit, ...(members === undefined ? {} : { members }) };
+    return { subject, entry };
+  });
+  try {
+    await verifySatellites(claimed);
+  } catch (error) {
+    if (!(error instanceof ImageBuildRecordError)) {throw error;}
+    problems.push(error.message);
+  }
+  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(claimed.map(({ entry }) => entry)) };
+  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, declaredSources, env }),
+  resolveSnapshot,
+  clientFor,
+  write = writeOnce,
+  ...channelInjections
+}) {
+  const selection = parseSelection(readStrictJsonFile(options['--selection']), members, options['--selection']);
+  const channel = options['--channel'];
+  if (channel === undefined) {
+    throw new Error('image-record requires --channel <tag>');
+  }
+  if (selection.channel !== channel) {
+    throw new ImageBuildRecordError(`selection ${options['--selection']} was selected through channel ${selection.channel}, not ${channel}`);
+  }
+  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,
+    verifySatellites: createChannelSatelliteVerifier({ channel, selection, env, ...channelInjections }),
+  });
+  write(options['--out'], record);
+  return record;
+}

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

@@ -0,0 +1,90 @@
+// develop-select-records — the body of `xema-edition develop select-records --branch develop --channel <tag>
+// --out <file>`. (`--registry <root>` is still accepted for one release and unused.)
+//
+// For every member of the develop graph that does not keep its current resolution, read the one manifest
+// <root>/build-records/<name>:<tag> (a tag the producer's CI moves to its newest green record; tags are never listed,
+// so <root> may be a pull-through proxy), parse its single build-record layer with the kernel's BuildRecordSchema and
+// hold it to the member: its producer repository and branch (develop-channel-record.mjs). No cosign and no git
+// ancestry: the records are unsigned, their trust is the registry write ACL, and the tag only moves forward.
+//
+// The selection is { channel, pins, snapshot, images, currentResolution }, written once (wx); images[] entries carry
+// `member`, the owning repo handle, and the record's digest and contentHash. Each member prints one line, in repo order,
+// after --out is written (develop-selection-line.mjs): `<short name>: channel <tag> -> record <commit12> (run <run>)`;
+// short name = the repo's last path segment, refused when two members share one.
+//
+// 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 failure is a hard refusal naming the repository, and nothing is written. Two classes: `RecordRefused`
+// (the tag is missing, or the record itself says no) and a plain Error (the registry could not answer), which the
+// operator retries rather than reads.
+
+import { writeOnce } from './customer-edition-verbs.mjs';
+import { withChannelReader } from './develop-build-record.mjs';
+import { loadChannelRecord } from './develop-channel-record.mjs';
+import { currentResolutionOf, keepsCurrentResolution } from './develop-current-resolution.mjs';
+import { developGraphMembers } from './develop-graph.mjs';
+import { assertShortNamesUnambiguous, formatSelectionLine } from './develop-selection-line.mjs';
+import { compareStrings } from './lib.mjs';
+import { RecordRefused } from './record-refused.mjs';
+
+// The record name this verb's tests and callers read from here, owned by the shared core.
+export { UnknownBuildRecordProducerError } from './develop-build-record.mjs';
+
+/**
+ * The selection of a channel tag: every member that does not keep its current resolution takes the record the tag
+ * names. A missing tag or a record that does not hold refuses the whole run, naming the member.
+ */
+export async function selectChannelRecords({ branch, channel, members, kernel, clientFor }) {
+  assertShortNamesUnambiguous(members);
+  const selected = [];
+  for (const member of members) {
+    if (keepsCurrentResolution(member)) {continue;}
+    const loaded = await loadChannelRecord({ kernel, clientFor, member, branch, channel });
+    selected.push({ member, ...loaded });
+  }
+  return { ...composeSelection(selected, { channel }), currentResolution: currentResolutionOf(members) };
+}
+
+/** The snapshot a channel selection writes. A name built by two records is refused: an image has one builder. */
+export function composeSelection(selected, { channel }) {
+  const pins = {};
+  const snapshot = {};
+  const owners = new Map();
+  const images = [];
+  for (const { member, record, snapshot: run } of selected) {
+    pins[member.repo] = record.commit;
+    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, member: member.repo, ...(image.members === undefined ? {} : { members: image.members }) });
+    }
+  }
+  const sorted = (object) => Object.fromEntries(Object.entries(object).sort(([a], [b]) => compareStrings(a, b)));
+  return { channel, pins: sorted(pins), snapshot: sorted(snapshot), images: images.sort((a, b) => compareStrings(a.name, b.name)) };
+}
+
+/** The `select-records` verb. Writes `--out` once, only after every member was selected. */
+export async function runSelectRecords({
+  options,
+  env = process.env,
+  members = developGraphMembers(),
+  write = writeOnce,
+  print = (text) => process.stdout.write(text),
+  ...readerInjections
+}) {
+  const channel = options['--channel'];
+  if (channel === undefined) {throw new Error('select-records requires --channel <tag>: the records are read through the tag the producer\'s CI moves');}
+  return withChannelReader({ env, ...readerInjections }, async ({ kernel, clientFor }) => {
+    const selection = await selectChannelRecords({ branch: options['--branch'], channel, members, kernel, clientFor });
+    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,29 @@
+// develop-selection-line — the one stdout line `select-records` prints per member, and the check that lines are unambiguous.
+//
+//   <short name>: channel <tag> -> record <12-hex commit> (run <run>)
+//   <short name>: current resolution (leaves the edition, <ticket>)
+//
+// The short name is the repo handle's last path segment.
+
+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 the channel record it was selected at. */
+export function formatSelectionLine(member, selection) {
+  const { repo } = member;
+  if (keepsCurrentResolution(member)) {
+    return `${shortNameOf(repo)}: current resolution (leaves the edition, ${member.currentResolution})`;
+  }
+  return `${shortNameOf(repo)}: channel ${selection.channel} -> record ${selection.pins[repo].slice(0, 12)} (run ${selection.snapshot[repo]})`;
+}
+
+/** 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,36 @@
+// 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 (--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`);
+  }
+  assertCommitPins(pins, `${flag} ${path}`);
+  if (members !== undefined) {
+    const problem = currentResolutionProblem(document.currentResolution, members);
+    if (problem !== null) {throw new Error(`${flag} ${path}: ${problem}`);}
+  }
+  return pins;
+}
+
+/** A pin map's every value is a 40-hex commit (a selection's pins, follow's --current-pins); returns it. `label` names the input. */
+export function assertCommitPins(pins, label) {
+  for (const [key, commit] of Object.entries(pins)) {
+    if (typeof commit !== 'string' || !/^[0-9a-f]{40}$/.test(commit)) {
+      throw new Error(`${label}: pin ${JSON.stringify(key)} is not a 40-hex commit: ${JSON.stringify(commit)}`);
+    }
+  }
+  return pins;
+}