@xemahq/xema 0.59.1 → 0.60.1

package/edition/develop-record-verify.mjs

@@ -1,216 +0,0 @@
-// develop-record-verify — the verify core of a signed build record, shared by `develop select-records` and
-// `develop verify-image-record`.
-//
-// 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; the record must also name that member as its producer, its own branch and its own tag.
-// Both verbs read records through `loadVerifiedRecord`: there is one copy of this logic.
-//
-// Two failure 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.
-
-
-import { canonicalPublicHttpsRepositoryUrl, repositoryOwnerName } from './canonical-repository-url.mjs';
-import { certificateConstraintArgs } from './cosign-certificate-constraints.mjs';
-import { editionWorkspaceConfig } from './edition-config.mjs';
-import { loadKernelDistributionSchemas } from './lib.mjs';
-import { cosignEnvironment, withPinnedCosign } from './pinned-cosign.mjs';
-import { RecordRefused } from './record-refused.mjs';
-import { splitImageRef } from './registry-credentials.mjs';
-import { isNotPublishedYet } from './seal-image-digests.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;
-
-/** 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. */
-export 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 };
-}
-
-
-/** The registry repository that holds a member's build records. */
-export function recordsRepositoryOf(registry, member) {
-  return `${registry}/${BUILD_RECORDS_SEGMENT}/${member.repo.split('/').at(-1)}`;
-}
-
-/**
- * Every record tag a member published for `branch`, newest run first, with the registry client of its authority.
- * Refused when none was ever published; a registry that did not answer is a plain Error.
- */
-export async function listBuildRecordRuns({ kernel, clientFor, registry, member, branch }) {
-  const repository = recordsRepositoryOf(registry, member);
-  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}`);}
-  return { repository, authority, client, runs };
-}
-
-/**
- * Prepare everything record verification needs (the declared pinned policy, the trusted cosign, the pinned trusted
- * root, the registry clients and their credentials), hand it to `use`, and dispose of it. The injections are
- * replaced by tests.
- */
-export async function withRecordVerifier({ cosignBinary, env, loadKernel = loadKernelDistributionSchemas, ...pinned }, use) {
-  const dataRootRepositoryUrl = declaredDataRootRepositoryUrl();
-  return withPinnedCosign(
-    { cosignBinary, env, ...pinned, afterPolicy: async () => ({ kernel: requireBuildRecordKernel(await loadKernel()) }) },
-    ({ kernel, clientFor, runCosign, cosignEnvFor, trustedRootPath }) => use({ dataRootRepositoryUrl, kernel, clientFor, runCosign, cosignEnvFor, trustedRootPath }),
-  );
-}
-
-/** The environment cosign runs with for one authority: the pinned base plus its declared credential (pinned-cosign.mjs). */
-export { cosignEnvironment };

package/edition/develop-resolve-report.mjs

@@ -1,159 +0,0 @@
-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

@@ -1,172 +0,0 @@
-// 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).
-//
-// 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.
-//
-// 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 { 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 {
-  cosignEnvironment,
-  listBuildRecordRuns,
-  loadVerifiedRecord,
-  recordSignerOrigin,
-  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';
-
-// The record-verification names this verb's tests and callers read from here, owned by the shared core.
-export {
-  DataRootRepositoryUndeclaredError,
-  KernelLacksBuildRecordSchemaError,
-  UnknownBuildRecordProducerError,
-  declaredDataRootRepositoryUrl,
-  recordSigner,
-} from './develop-record-verify.mjs';
-
-const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
-
-/**
- * @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, 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 = [];
-    for (const { tag, run } of runs) {
-      const loaded = await loadVerifiedRecord({
-        kernel, client, runCosign, cosignEnv: cosignEnvironment(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, 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
-    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, head, behind, ...chosen });
-  }
-  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, 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, 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), 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 const readPublishedPins = (path) => readSelectionPins(path, '--published-pins');
-
-/** The `select-records` verb. Writes `--out` once, only after every member was selected. */
-export async function runSelectRecords({
-  options,
-  env = process.env,
-  members = developGraphMembers(),
-  runGit,
-  write = writeOnce,
-  print = (text) => process.stdout.write(text),
-  ...verifierInjections
-}) {
-  return withRecordVerifier({ cosignBinary: options['--cosign'], env, ...verifierInjections }, async (verifier) => {
-    const selection = await selectRecords({
-      branch: options['--branch'],
-      registry: options['--registry'],
-      at: options['--at'],
-      members,
-      ...verifier,
-      publishedPins: options['--published-pins'] === undefined ? undefined : readPublishedPins(options['--published-pins']),
-      workspace: editionWorkspaceConfig(),
-      env,
-      runGit,
-    });
-    write(options['--out'], selection);
-    for (const member of members) {
-      print(`${formatSelectionLine(member, selection)}\n`);
-    }
-    return selection;
-  });
-}

package/edition/develop-selection-line.mjs

@@ -1,30 +0,0 @@
-// 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

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