@xemahq/xema 0.45.1 → 0.46.0

package/edition/canonical-repository-url.mjs

@@ -33,3 +33,15 @@ export function canonicalPublicHttpsRepositoryUrl(raw, context) {
   }
   return parsed.toString();
 }
+
+/**
+ * The `owner/name` of a canonical public HTTPS repository URL (`https://host/owner/name[.git]`): exactly two
+ * path segments, the optional `.git` suffix dropped. Anything else is refused, naming `context`.
+ */
+export function repositoryOwnerName(canonicalUrl, context) {
+  const segments = new URL(canonicalUrl).pathname.replace(/\.git$/, '').split('/').filter((segment) => segment.length > 0);
+  if (segments.length !== 2) {
+    throw new Error(`${context} must name exactly <owner>/<name> on its host; got ${JSON.stringify(canonicalUrl)}`);
+  }
+  return segments.join('/');
+}

package/edition/cosign-certificate-constraints.mjs

@@ -0,0 +1,40 @@
+// cosign-certificate-constraints — the certificate claims every keyless verification here pins.
+//
+// One signer shape, `{certificateIdentity, oidcIssuer, githubWorkflow: {repository, ref}}`, plus the exact
+// workflow commit the certificate must carry. Every `cosign verify*` of this CLI takes its constraints
+// from here, so no call site can leave one of the five out.
+
+const WORKFLOW_SHA = /^[0-9a-f]{40}$/;
+
+function requireText(value, what) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`certificate constraints: ${what} must be a non-empty string; got ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
+/**
+ * @param {{ certificateIdentity: string, oidcIssuer: string, githubWorkflow: { repository: string, ref: string } }} signer
+ * @param {string} workflowSha the 40-hex commit the signing workflow ran at
+ * @returns {string[]} the cosign flags that pin identity, issuer, workflow repository, ref and sha
+ */
+export function certificateConstraintArgs(signer, workflowSha) {
+  if (signer === null || typeof signer !== 'object') {
+    throw new Error('certificate constraints: the signer must be an object');
+  }
+  if (typeof workflowSha !== 'string' || !WORKFLOW_SHA.test(workflowSha)) {
+    throw new Error(`certificate constraints: the workflow sha must be 40 lowercase hex characters; got ${JSON.stringify(workflowSha)}`);
+  }
+  return [
+    '--certificate-identity',
+    requireText(signer.certificateIdentity, 'certificateIdentity'),
+    '--certificate-oidc-issuer',
+    requireText(signer.oidcIssuer, 'oidcIssuer'),
+    '--certificate-github-workflow-repository',
+    requireText(signer.githubWorkflow?.repository, 'githubWorkflow.repository'),
+    '--certificate-github-workflow-ref',
+    requireText(signer.githubWorkflow?.ref, 'githubWorkflow.ref'),
+    '--certificate-github-workflow-sha',
+    workflowSha,
+  ];
+}

package/edition/customer-edition-verbs.mjs

@@ -213,6 +213,12 @@ const COMMANDS = Object.freeze({
     switches: ['--json'],
     required: ['--pins', '--cosign'],
   },
+  'select-records': {
+    positional: false,
+    values: ['--branch', '--registry', '--cosign', '--out', '--at', '--published-pins'],
+    switches: [],
+    required: ['--branch', '--registry', '--cosign', '--out'],
+  },
   'check-overrides': { positional: false, values: ['--overrides'], switches: [], required: ['--overrides'] },
   'choose-kernel': { positional: false, values: ['--kernel-pin', '--out'], switches: [], required: ['--out'] },
   'check-existing': {

package/edition/develop-coverage-readers.mjs

@@ -12,7 +12,7 @@ import { promisify } from 'node:util';
 
 import { AttestationStatus, DEVELOP_EVIDENCE_CHANNEL } from './develop-coverage-verdict.mjs';
 import { COSIGN_ENV, policyCandidates, sha256Digest, validatePinnedTrustedRoot, verifySigstoreEvidenceDescriptor } from './image-evidence.mjs';
-import { resolveImageSourceEvidenceReferrer, writeForeignAuthorityReferrerReport } from './oci-image-source-evidence.mjs';
+import { resolveImageSourceEvidenceReferrer, writeInvalidReferrerReport } from './oci-image-source-evidence.mjs';
 import { BUNDLE_MEDIA_TYPE } from './produce-image-source-evidence.mjs';
 import { loadRegistryCredentialDeclarations, resolveRegistryCredential, splitImageRef } from './registry-credentials.mjs';
 import { isNotPublishedYet } from './seal-image-digests.mjs';
@@ -59,7 +59,8 @@ export function parseCosignVerifyOutput(stdout, digest) {
   });
 }
 
-function defaultRunCosign(cosignPath, args, env) {
+/** Run cosign once; resolves `{code, stdout, stderr}` for a cosign exit, throws when cosign could not run at all. */
+export function defaultRunCosign(cosignPath, args, env) {
   return execFileAsync(cosignPath, args, { env, timeout: COSIGN_CALL_TIMEOUT_MS, maxBuffer: COSIGN_MAX_OUTPUT_BYTES }).then(
     ({ stdout }) => ({ code: 0, stdout, stderr: '' }),
     (error) => {
@@ -69,7 +70,8 @@ function defaultRunCosign(cosignPath, args, env) {
   );
 }
 
-function basicAuthParts(credential) {
+/** The username and password of a resolved basic-auth registry credential. */
+export function basicAuthParts(credential) {
   const decoded = Buffer.from(credential.basicAuth, 'base64').toString('utf8');
   const colon = decoded.indexOf(':');
   return { username: decoded.slice(0, colon), password: decoded.slice(colon + 1) };
@@ -143,7 +145,7 @@ export function createCoverageReaders({ policy, policyRoot, trustedCosign, schem
       subjectDigest: digest,
       schemas,
       expectedContractAuthority,
-      onForeignAuthorityReferrer: writeForeignAuthorityReferrerReport,
+      onInvalidReferrer: writeInvalidReferrerReport,
     });
     if (evidence === null) {return { status: AttestationStatus.None };}
     if (rows.length === 0) {return { status: AttestationStatus.NoRow };}

package/edition/develop-edition.mjs

@@ -45,6 +45,22 @@
 //       annotations-missing | annotation-mismatch | not-built). Prints a table grouped by producer repo
 //       and `covered N/M` (--json: the same as data). Exit 0 only when every subject is covered, 1 when
 //       not, 2 on an operational error. Takes the roots `resolve` takes; writes nothing.
+//   select-records --branch develop --registry <root> --cosign <absolute-path> --out <file> [--at <ISO-8601 UTC>] [--published-pins <file>]
+//       for every develop-graph member, take the newest build record the data root's record workflow signed for
+//       the branch (<root>/build-records/<name>, verified offline by digest against the pinned trusted root, as
+//       signed by <data root>/.github/workflows/record-build.yaml at refs/heads/<branch>, called by the member at the
+//       record's own commit) and write { pins, snapshot, images }, once (wx). Any missing, unsigned, mismatched or
+//       unreadable record refuses the whole run and writes nothing: a newer bad record is never skipped for an older
+//       one. --at takes the newest record completed at or before that time. Only `develop` has a declared signer; the
+//       data root must declare dataRootRepositoryUrl. Takes the roots `resolve` takes (no registry root is implied).
+//       "Newest" is the newest COMMIT on develop, not the highest run: EVERY record of the branch is read and cosign-verified,
+//       the selected commit must equal or descend from every other record's commit (git merge-base on develop fetched
+//       from the member), and among that commit's records the highest run and attempt wins. --published-pins takes a file
+//       this verb wrote (only .pins is read): a member's published commit is kept when the records are not ahead of it
+//       (its own record must exist), a diverged one is refused. Without the flag the rule applies among the records only;
+//       part 07 passes the flag.
+//       Residual: anyone who can delete registry tags can remove newer records, and this then pins the newest remaining
+//       valid one; the guard is part 07's, deploy-latest's owner refuses a snapshot that goes backwards.
 //   choose-kernel [--kernel-pin <40-hex>] --out <file>
 //       choose the develop kernel commit in the --kernel checkout (full history; its refs/remotes/origin/develop is the develop head):
 //       the newest first-parent commit whose declared edition protocol this CLI supports
@@ -74,6 +90,7 @@ import { runDevelopCoverage } from './develop-coverage-run.mjs';
 import { CoverageExit } from './develop-coverage.mjs';
 import { resolveDevelopEdition } from './develop-edition-resolve.mjs';
 import { assertNoToolingOverride, freezeGraph, freezeSources } from './develop-freeze.mjs';
+import { runSelectRecords } from './develop-select-records.mjs';
 import { LOCAL_WORKFLOW, assertExistingArtifactMatches, developEditionTarget, workflowFromEnv, writeEditionArtifact } from './edition-artifact.mjs';
 import { EditionChannel } from './edition-constants.mjs';
 import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, kernelRepoDir } from './edition-workspace.mjs';
@@ -162,6 +179,9 @@ async function run(argv, env) {
         json: options['--json'] === true,
         env,
       });
+    case 'select-records':
+      await runSelectRecords({ options, env });
+      return;
     case 'check-existing': {
       if (customer) {return runCustomerVerb({ channel: EditionChannel.Develop, command, options, env });}
       assertExistingArtifactMatches({

package/edition/develop-record-ancestry.mjs

@@ -0,0 +1,121 @@
+// develop-record-ancestry — which verified record commit is the newest COMMIT on develop.
+//
+// "Newest" is the commit that equals or descends from every other candidate's commit, never the highest run:
+// a re-run of an old commit carries a higher run number and must lose. History comes from git alone: one bare
+// scratch repository per member, fetched blobless from the member's own URL through the same hold and credential
+// environment freeze uses (`withSourceGitEnv`; no token on argv, none beyond the workspace's). Candidates are
+// compared with each other only, never with a published pin.
+//
+// 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.
+//
+// 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).
+
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { withSourceGitEnv } from './git-source-auth.mjs';
+import { RecordRefused } from './record-refused.mjs';
+
+const DEVELOP_REF = 'refs/heads/develop';
+// One external call to a git remote; a fetch that exceeds it fails naming the member, never a verdict.
+const GIT_CALL_TIMEOUT_MS = 300_000;
+const GIT_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
+
+export class IncomparableRecordCommitsError extends RecordRefused {
+  constructor(repo, first, second) {
+    super(repo, `record commits ${first.commit} (${first.tags.join(', ')}) and ${second.commit} (${second.tags.join(', ')}) are not ancestor-related on develop`);
+    this.name = 'IncomparableRecordCommitsError';
+  }
+}
+
+export class RecordCommitNotOnDevelopError extends RecordRefused {
+  constructor(repo, commit, tags) {
+    super(repo, `record commit ${commit} (${tags.join(', ')}) is not in the fetched develop history`);
+    this.name = 'RecordCommitNotOnDevelopError';
+  }
+}
+
+export class DivergedFromPublishedError extends RecordRefused {
+  constructor(repo, selected, published) {
+    super(repo, `the newest record commit ${selected} and the published commit ${published} are not ancestor-related on develop`);
+    this.name = 'DivergedFromPublishedError';
+  }
+}
+
+/** The published commit is newer than every record, and none of its own survives among the candidates. */
+export class PublishedRecordMissingError extends RecordRefused {
+  constructor(repo, published) {
+    super(repo, `no verified build record exists for the published commit ${published}; it is newer than every candidate record`);
+    this.name = 'PublishedRecordMissingError';
+  }
+}
+
+/** `{ status, stdout, stderr }` of one git run; a git that could not be spawned or timed out throws. */
+export function defaultRunGit(args, { cwd, env }) {
+  const result = spawnSync('git', args, { cwd, env, encoding: 'utf8', timeout: GIT_CALL_TIMEOUT_MS, maxBuffer: GIT_MAX_OUTPUT_BYTES });
+  if (result.error !== undefined || result.status === null) {
+    throw new Error(`git ${args[0]} could not run: ${result.error?.message ?? `killed by ${result.signal}`}`);
+  }
+  return { status: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+
+/**
+ * @param {object} request
+ * @param {{repo: string, repositoryUrl: string}} request.member
+ * @param {{commit: string, tag: string}[]} request.candidates verified records' commits with their tags
+ * @param {string} [request.published] the commit already published for this member: kept when the records are not ahead of it
+ * @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
+ */
+export function newestCommitOnDevelop({ member, candidates, published, workspace, env, runGit = defaultRunGit }) {
+  const byCommit = new Map();
+  for (const { commit, tag } of candidates) {
+    byCommit.set(commit, [...(byCommit.get(commit) ?? []), tag]);
+  }
+  const commits = [...byCommit].map(([commit, tags]) => ({ commit, tags }));
+  const scratch = mkdtempSync(join(tmpdir(), 'xema-select-history-'));
+  try {
+    return withSourceGitEnv({ name: member.repo, url: member.repositoryUrl }, { workspace, env }, (gitEnv) => {
+      const git = (args, extraEnv = {}) => runGit(args, { cwd: scratch, env: { ...gitEnv, ...extraEnv } });
+      const init = git(['init', '--bare', '--quiet']);
+      if (init.status !== 0) {throw new Error(`select-records: ${member.repo}: git init failed: ${init.stderr.trim()}`);}
+      const fetched = git(['fetch', '--quiet', '--filter=blob:none', '--no-tags', member.repositoryUrl, `+${DEVELOP_REF}:${DEVELOP_REF}`]);
+      if (fetched.status !== 0) {
+        throw new Error(`select-records: ${member.repo}: git fetch of develop from ${member.repositoryUrl} failed (exit ${fetched.status}): ${fetched.stderr.trim()}`);
+      }
+      // 0 = ancestor (or equal), 1 = not; anything else is git failing, never a verdict
+      const isAncestor = (older, newer) => {
+        const result = git(['merge-base', '--is-ancestor', older, newer]);
+        if (result.status === 0) {return true;}
+        if (result.status === 1) {return false;}
+        throw new Error(`select-records: ${member.repo}: git merge-base ${older} ${newer} failed (exit ${result.status}): ${result.stderr.trim()}`);
+      };
+      const assertOnDevelop = (commit, tags) => {
+        // no lazy fetch: a commit the develop fetch did not bring is not on develop
+        const known = git(['cat-file', '-e', `${commit}^{commit}`], { GIT_NO_LAZY_FETCH: '1' });
+        if (known.status !== 0 || !isAncestor(commit, DEVELOP_REF)) {throw new RecordCommitNotOnDevelopError(member.repo, commit, tags);}
+      };
+      for (const { commit, tags } of commits) {assertOnDevelop(commit, tags);}
+      let selected = commits[0];
+      for (const other of commits.slice(1)) {
+        if (isAncestor(other.commit, selected.commit)) {continue;}
+        if (!isAncestor(selected.commit, other.commit)) {throw new IncomparableRecordCommitsError(member.repo, selected, other);}
+        selected = other;
+      }
+      if (published === undefined) {return 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;}
+      throw new DivergedFromPublishedError(member.repo, selected.commit, published);
+    });
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}

package/edition/develop-select-records.mjs

@@ -0,0 +1,365 @@
+// develop-select-records — the body of `xema edition develop select-records`.
+//
+// For every member of the develop graph, take the newest signed build record the data root's record workflow
+// published for the branch, and write the snapshot it names: the commit to pin, the run it came from, and the
+// images it built. A record is trusted only after cosign verified it, offline against the pinned trusted root,
+// as signed by the data root's `record-build.yaml` at `refs/heads/<branch>`, called by the member's own
+// repository at the record's own commit.
+//
+// "Newest" is the newest COMMIT on develop, never the highest run: every record of the branch is read and
+// verified, the selected commit must equal or descend from every other record's commit (git ancestry, develop
+// fetched from the member), and among that commit's records (re-runs of it) the highest run and attempt wins.
+// With --published-pins <file> (a file this verb wrote; only .pins is read) a member's published commit is kept
+// 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).
+//
+// 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.
+//
+// Rollback residual: anyone who can delete registry tags can remove newer records, and select-records then pins
+// the newest remaining valid one. The guard is deploy-latest's (part 07): its owner refuses a snapshot that goes
+// backwards. This verb checks nothing against current pins.
+
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { canonicalPublicHttpsRepositoryUrl, repositoryOwnerName } from './canonical-repository-url.mjs';
+import { certificateConstraintArgs } from './cosign-certificate-constraints.mjs';
+import { writeOnce } from './customer-edition-verbs.mjs';
+import { basicAuthParts, defaultRunCosign } from './develop-coverage-readers.mjs';
+import { developGraphMembers } from './develop-graph.mjs';
+import { PublishedRecordMissingError, newestCommitOnDevelop } from './develop-record-ancestry.mjs';
+import { editionWorkspaceConfig } from './edition-config.mjs';
+import { dataRoot } from './edition-workspace.mjs';
+import { loadDeclaredPinnedPolicy } from './evidence-trust-policy.mjs';
+import { COSIGN_ENV, prepareTrustedCosignBinary, validatePinnedTrustedRoot } from './image-evidence.mjs';
+import { compareStrings, loadKernelDistributionSchemas } from './lib.mjs';
+import { RecordRefused } from './record-refused.mjs';
+import { loadRegistryCredentialDeclarations, resolveRegistryCredential, splitImageRef } from './registry-credentials.mjs';
+import { isNotPublishedYet } from './seal-image-digests.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+import { assertPreparedExecutable } from './trusted-executable.mjs';
+import { registryClientsFor } from './verify-image-platforms.mjs';
+
+/** The repository segment, under the registry root, that holds a member's build records. */
+export const BUILD_RECORDS_SEGMENT = 'build-records';
+export const RECORD_SIGNER_WORKFLOW = '.github/workflows/record-build.yaml';
+export const RECORD_SIGNER_OIDC_ISSUER = 'https://token.actions.githubusercontent.com';
+/** The branches a record signer is declared for, each with the ref the record workflow runs at. */
+const RECORD_SIGNER_REFS = Object.freeze({ develop: 'refs/heads/develop' });
+/**
+ * A cosign exit whose stderr shows the registry was not reached before any verdict. Only this, a cosign that
+ * could not run, and a timeout are operational; every other non-zero exit of `cosign verify` is a verdict.
+ */
+const COSIGN_TRANSPORT_FAILURE = /dial tcp|i\/o timeout|connection (refused|reset)|no such host|TLS handshake timeout|context deadline exceeded/i;
+const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
+
+/** The record's producer is a kind this CLI has no claims for: a closed set, never guessed at. */
+export class UnknownBuildRecordProducerError extends RecordRefused {
+  constructor(repo, kind) {
+    super(repo, `the record's producer kind ${JSON.stringify(kind)} is not one select-records can verify`);
+    this.name = 'UnknownBuildRecordProducerError';
+  }
+}
+
+export class DataRootRepositoryUndeclaredError extends Error {
+  constructor() {
+    super('edition-workspace.json declares no dataRootRepositoryUrl; select-records cannot name the record signer');
+    this.name = 'DataRootRepositoryUndeclaredError';
+  }
+}
+
+export class KernelLacksBuildRecordSchemaError extends Error {
+  constructor(missing) {
+    super(`the kernel's distribution module does not export ${missing.join(', ')}; select-records needs a kernel with the build-record contract`);
+    this.name = 'KernelLacksBuildRecordSchemaError';
+  }
+}
+
+/** The data root's `owner/name`, from the workspace declaration; refused by name when it declares none. */
+export function declaredDataRootRepositoryUrl() {
+  const url = editionWorkspaceConfig().dataRootRepositoryUrl;
+  if (url === undefined) {throw new DataRootRepositoryUndeclaredError();}
+  return url;
+}
+
+/** The kernel's build-record exports, refused as a set when any is absent. */
+export function requireBuildRecordKernel(schemas) {
+  const names = ['BUILD_RECORD_MEDIA_TYPE', 'BuildRecordSchema', 'buildRecordTag', 'parseBuildRecordTag', 'compareBuildRecordRuns'];
+  const missing = names.filter((name) => schemas?.[name] === undefined);
+  if (missing.length > 0 || typeof schemas.BuildRecordSchema?.safeParse !== 'function') {
+    throw new KernelLacksBuildRecordSchemaError(missing.length > 0 ? missing : ['a BuildRecordSchema with safeParse']);
+  }
+  return schemas;
+}
+
+/** The ref and data-root repository a branch's records are signed by; refused before any network call. */
+export function recordSignerOrigin({ branch, dataRootRepositoryUrl }) {
+  const ref = Object.hasOwn(RECORD_SIGNER_REFS, branch) ? RECORD_SIGNER_REFS[branch] : undefined;
+  if (ref === undefined) {throw new Error(`no record signer declared for branch ${branch}`);}
+  if (dataRootRepositoryUrl === undefined) {throw new DataRootRepositoryUndeclaredError();}
+  const dataRepository = repositoryOwnerName(canonicalPublicHttpsRepositoryUrl(dataRootRepositoryUrl, 'dataRootRepositoryUrl'), 'dataRootRepositoryUrl');
+  return { ref, dataRepository };
+}
+
+/**
+ * The signer of the branch's records: the data root's record workflow at the branch, as the certificate states
+ * it, with the repository that CALLED the workflow (the member) as the workflow-repository claim.
+ */
+export function recordSigner({ branch, dataRootRepositoryUrl, memberRepositoryUrl }) {
+  const { ref, dataRepository } = recordSignerOrigin({ branch, dataRootRepositoryUrl });
+  const member = repositoryOwnerName(canonicalPublicHttpsRepositoryUrl(memberRepositoryUrl, 'repositoryUrl'), 'repositoryUrl');
+  return {
+    certificateIdentity: `https://github.com/${dataRepository}/${RECORD_SIGNER_WORKFLOW}@${ref}`,
+    oidcIssuer: RECORD_SIGNER_OIDC_ISSUER,
+    githubWorkflow: { repository: member, ref },
+    memberRepository: member,
+  };
+}
+
+/**
+ * What a record's producer says, read through the ONE switch over its kind: the repository that called the
+ * record workflow (the cosign caller claim, held equal to the member's) and the run the snapshot names.
+ */
+export function producerClaims({ record, repo, memberRepository }) {
+  switch (record.producer?.kind) {
+    case 'github-actions': {
+      const { repository, runNumber, runAttempt } = record.producer;
+      if (repository !== memberRepository) {throw new RecordRefused(repo, `record is produced by repository ${repository}, not ${memberRepository}`);}
+      return { repository, snapshot: `${runNumber}.${runAttempt}` };
+    }
+    default:
+      throw new UnknownBuildRecordProducerError(repo, record.producer?.kind);
+  }
+}
+
+/** Run one registry client call; ONLY a failure of the client itself is "the registry did not answer". */
+async function fromRegistry(repo, what, call) {
+  try {
+    return await call();
+  } catch (error) {
+    throw new Error(`select-records: ${repo}: the registry did not answer for ${what}: ${error.message}`);
+  }
+}
+
+/** Read one record by its tag: manifest by digest, its single layer, parsed against the kernel's schema. */
+async function readRecord({ kernel, client, repository, repo, tag }) {
+  const served = await fromRegistry(repo, `${repository}:${tag}`, () => client.getManifestByTag(repository, tag));
+  const manifest = await fromRegistry(repo, `${repository}@${served.digest}`, () => client.getManifestByDigest(repository, served.digest));
+  const layers = manifest.document.layers;
+  if (!Array.isArray(layers) || layers.length !== 1) {
+    throw new RecordRefused(repo, `record ${tag} has ${Array.isArray(layers) ? layers.length : 'no'} layers, not exactly one`);
+  }
+  const [layer] = layers;
+  if (layer.mediaType !== kernel.BUILD_RECORD_MEDIA_TYPE) {
+    throw new RecordRefused(repo, `record ${tag} layer media type is ${JSON.stringify(layer.mediaType)}, not ${kernel.BUILD_RECORD_MEDIA_TYPE}`);
+  }
+  const bytes = await fromRegistry(repo, `${repository}@${layer.digest}`, () => client.getBlob(repository, layer.digest));
+  let document;
+  try {
+    document = JSON.parse(bytes.toString('utf8'));
+  } catch (error) {
+    throw new RecordRefused(repo, `record ${tag} is not JSON: ${error.message}`);
+  }
+  const parsed = kernel.BuildRecordSchema.safeParse(document);
+  if (!parsed.success) {throw new RecordRefused(repo, `record ${tag} does not parse as a build record: ${parsed.error.message}`);}
+  return { record: parsed.data, digest: served.digest };
+}
+
+/** The tag's record, verified by digest against the constrained signer, then held to its own repo, branch and tag. */
+async function loadVerifiedRecord({ kernel, client, runCosign, cosignEnv, trustedRootPath, repository, member, branch, dataRootRepositoryUrl, tag }) {
+  const repo = member.repo;
+  const { record, digest } = await readRecord({ kernel, client, repository, repo, tag });
+  const signer = recordSigner({ branch, dataRootRepositoryUrl, memberRepositoryUrl: member.repositoryUrl });
+  const { repository: callerRepository, snapshot } = producerClaims({ record, repo, memberRepository: signer.memberRepository });
+  signer.githubWorkflow.repository = callerRepository;
+  const ref = `${repository}@${digest}`;
+  const args = ['verify', '--offline', '--trusted-root', trustedRootPath, ...certificateConstraintArgs(signer, record.commit), ref];
+  let result;
+  try {
+    result = await runCosign(args, cosignEnv);
+  } catch (error) {
+    // no numeric exit code: cosign did not run (spawn failure) or did not answer (timeout, kill signal)
+    throw new Error(`select-records: ${repo}: cosign could not run for ${ref}: ${error.message}`);
+  }
+  if (result.code !== 0) {
+    if (COSIGN_TRANSPORT_FAILURE.test(result.stderr)) {
+      throw new Error(`select-records: ${repo}: cosign could not reach the registry for ${ref} (exit ${result.code}): ${result.stderr.trim()}`);
+    }
+    throw new RecordRefused(repo, `cosign refused record ${tag} (${digest}) as signed by ${signer.certificateIdentity} (exit ${result.code}): ${result.stderr.trim()}`);
+  }
+  if (record.branch !== branch) {throw new RecordRefused(repo, `record ${tag} is for branch ${record.branch}, not ${branch}`);}
+  if (kernel.buildRecordTag(record) !== tag) {throw new RecordRefused(repo, `record tagged ${tag} says it is ${kernel.buildRecordTag(record)}`);}
+  return { record, snapshot };
+}
+
+/**
+ * @param {object} request
+ * @param {string} request.branch
+ * @param {string} request.registry the registry root, e.g. `registry.example.com/acme`
+ * @param {string} [request.at] ISO-8601 UTC: the newest record completed at or before it
+ * @param {readonly {repo: string, repositoryUrl: string}[]} request.members
+ * @param {string|undefined} request.dataRootRepositoryUrl
+ * @param {object} request.kernel the kernel's distribution exports
+ * @param {(authority: string) => object} request.clientFor registry client of an authority
+ * @param {(args: string[], env: object) => Promise<{code: number, stdout: string, stderr: string}>} request.runCosign
+ * @param {(authority: string) => object} request.cosignEnvFor
+ * @param {string} request.trustedRootPath
+ * @param {Record<string, string>} [request.publishedPins] member repo -> the commit already published (--published-pins)
+ * @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[]}>}
+ */
+export async function selectRecords({ branch, registry, at, members, dataRootRepositoryUrl, kernel, clientFor, runCosign, cosignEnvFor, trustedRootPath, publishedPins, workspace, env, runGit }) {
+  requireBuildRecordKernel(kernel);
+  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) {
+    const repository = `${registry}/${BUILD_RECORDS_SEGMENT}/${member.repo.split('/').at(-1)}`;
+    const { authority } = splitImageRef(repository);
+    const client = clientFor(authority);
+    let tags;
+    try {
+      tags = await client.listTags(repository);
+    } catch (error) {
+      if (isNotPublishedYet(error)) {throw new RecordRefused(member.repo, `${repository} does not exist: no build record was ever published`);}
+      throw new Error(`select-records: ${member.repo}: the registry did not answer for ${repository} tags: ${error.message}`);
+    }
+    const runs = tags
+      .map((tag) => ({ tag, run: kernel.parseBuildRecordTag(tag, branch) }))
+      .filter(({ run }) => run !== undefined)
+      .sort((a, b) => kernel.compareBuildRecordRuns(b.run, a.run));
+    if (runs.length === 0) {throw new RecordRefused(member.repo, `${repository} has no build record for branch ${branch}`);}
+    // EVERY candidate is read and verified; any that fails refuses the run. None is skipped.
+    const verified = [];
+    for (const { tag, run } of runs) {
+      const loaded = await loadVerifiedRecord({
+        kernel, client, runCosign, cosignEnv: { ...COSIGN_ENV, ...cosignEnvFor(authority) }, trustedRootPath,
+        repository, member, branch, dataRootRepositoryUrl, tag,
+      });
+      verified.push({ tag, run, ...loaded });
+    }
+    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({
+      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
+    const ofCommitIn = (pool) => pool.filter(({ record }) => record.commit === commit).sort((a, b) => kernel.compareBuildRecordRuns(b.run, a.run));
+    // a kept published commit may be one --at left out of the eligible records: its own verified record stands
+    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 });
+  }
+  return composeSelection(selected);
+}
+
+/** 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 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 });
+    }
+  }
+  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)) };
+}
+
+/** 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;
+}
+
+/** The `select-records` verb. Writes `--out` once, only after every member was selected. */
+export async function runSelectRecords({
+  options,
+  env = process.env,
+  loadPolicy = loadDeclaredPinnedPolicy,
+  prepareCosign = prepareTrustedCosignBinary,
+  loadKernel = loadKernelDistributionSchemas,
+  trustedRootBytes = (root, pinnedPolicy) => validatePinnedTrustedRoot(root, pinnedPolicy).bytes,
+  cosignPathOf = (handle) => assertPreparedExecutable(handle, 'cosign'),
+  members = developGraphMembers(),
+  runCosign: injectedRunCosign,
+  clientsOverride,
+  runGit,
+  write = writeOnce,
+}) {
+  const dataRootRepositoryUrl = declaredDataRootRepositoryUrl();
+  const { policy, dataRoot: policyRoot } = await loadPolicy();
+  const kernel = requireBuildRecordKernel(await loadKernel());
+  const trustedCosign = prepareCosign({ cosignBinary: options['--cosign'], policy });
+  const cosignPath = cosignPathOf(trustedCosign);
+  const runCosign = injectedRunCosign ?? ((args, cosignEnv) => defaultRunCosign(cosignPath, args, cosignEnv));
+  const scratch = mkdtempSync(join(tmpdir(), 'xema-select-records-'));
+  try {
+    const trustedRootPath = join(scratch, 'trusted-root.json');
+    writeFileSync(trustedRootPath, trustedRootBytes(policyRoot, policy), { flag: 'wx', mode: 0o600 });
+    const declarations = clientsOverride === undefined ? loadRegistryCredentialDeclarations(dataRoot()) : null;
+    const clients = new Map();
+    const clientFor = (authority) => {
+      if (clientsOverride !== undefined) {return clientsOverride(authority);}
+      if (!clients.has(authority)) {
+        clients.set(authority, registryClientsFor([{ imageRef: `${authority}/x` }], { declarations, env }).get(authority));
+      }
+      return clients.get(authority);
+    };
+    // cosign gets the SAME declared credential oras uses, in its environment, never argv.
+    const cosignEnvFor = (authority) => {
+      if (clientsOverride !== undefined) {return {};}
+      const credential = resolveRegistryCredential({ authority, declarations, env });
+      if (credential.access === 'anonymous') {return {};}
+      const { username, password } = basicAuthParts(credential);
+      return { COSIGN_REGISTRY_USERNAME: username, COSIGN_REGISTRY_PASSWORD: password };
+    };
+    const selection = await selectRecords({
+      branch: options['--branch'],
+      registry: options['--registry'],
+      at: options['--at'],
+      members,
+      dataRootRepositoryUrl,
+      kernel,
+      clientFor,
+      runCosign,
+      cosignEnvFor,
+      trustedRootPath,
+      publishedPins: options['--published-pins'] === undefined ? undefined : readPublishedPins(options['--published-pins']),
+      workspace: editionWorkspaceConfig(),
+      env,
+      runGit,
+    });
+    write(options['--out'], selection);
+    return selection;
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+    trustedCosign.dispose();
+  }
+}