@xemahq/xema 0.40.3 → 0.41.0

package/edition/develop-coverage-readers.mjs

@@ -0,0 +1,212 @@
+// develop-coverage-readers — the READ-ONLY registry, attestation and signature readers behind
+// `xema edition develop coverage`. Nothing here signs, attests, pushes or writes a lock.
+//
+// Every reader takes the develop coordinate of ONE subject and returns plain data; the verdict is
+// decided elsewhere (develop-coverage-verdict.mjs), so the decision is tested without a registry.
+
+import { execFile } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+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 } 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';
+import { assertPreparedExecutable } from './trusted-executable.mjs';
+import { registryClientsFor } from './verify-image-platforms.mjs';
+
+const execFileAsync = promisify(execFile);
+// One external call to cosign; it reads a registry. A run that exceeds it fails naming the subject, never a verdict.
+const COSIGN_CALL_TIMEOUT_MS = 60_000;
+const COSIGN_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
+/** cosign's exact refusal when a digest carries no signature at all. */
+const NO_SIGNATURES_MESSAGE = 'no signatures found';
+const ANY = '.*';
+
+/**
+ * The signatures cosign verified, as data. `cosign verify --output json` prints one object per signature whose
+ * `optional` holds the signed annotations next to the certificate's claims.
+ *
+ * @param {string} stdout
+ * @param {string} digest the digest that was verified; a signature over another digest is refused
+ * @returns {{ signer: object, annotations: Record<string, string> }[]}
+ */
+export function parseCosignVerifyOutput(stdout, digest) {
+  const payloads = JSON.parse(stdout);
+  if (!Array.isArray(payloads)) {throw new Error('cosign verify output is not a JSON array');}
+  return payloads.map((payload) => {
+    if (payload?.critical?.image?.['docker-manifest-digest'] !== digest) {
+      throw new Error(`cosign verified a signature over ${String(payload?.critical?.image?.['docker-manifest-digest'])}, not ${digest}`);
+    }
+    const optional = payload.optional ?? {};
+    const { Subject, Issuer, githubWorkflowTrigger, githubWorkflowSha, githubWorkflowRepository, githubWorkflowRef, ...rest } = optional;
+    const annotations = Object.fromEntries(Object.entries(rest).filter(([, value]) => typeof value === 'string'));
+    return {
+      signer: {
+        certificateIdentity: Subject ?? '',
+        issuer: Issuer ?? '',
+        trigger: githubWorkflowTrigger ?? '',
+        workflowSha: githubWorkflowSha ?? '',
+        workflowRepository: githubWorkflowRepository ?? '',
+        workflowRef: githubWorkflowRef ?? '',
+      },
+      annotations,
+    };
+  });
+}
+
+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) => {
+      if (typeof error.code === 'number') {return { code: error.code, stdout: error.stdout ?? '', stderr: error.stderr ?? '' };}
+      throw error;
+    },
+  );
+}
+
+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) };
+}
+
+/**
+ * @param {object} request
+ * @param {object} request.policy the pinned trust policy (kernel-parsed)
+ * @param {string} request.policyRoot the directory the policy's trusted root is read from (the data root)
+ * @param {object} request.trustedCosign the digest-pinned cosign handle (prepareTrustedCosignBinary)
+ * @param {object} request.schemas kernel distribution schemas
+ * @param {string} request.dataRoot declares how each registry is read
+ * @param {object} request.env environment the registry credentials are named in
+ * @param {Function} [request.runCosign] (path, args, env) => { code, stdout, stderr }; replaced by tests
+ * @param {Function} [request.fetchImpl] @param {Function} [request.run] oras runner, replaced by tests
+ * @param {Function} [request.clientFor] (authority) => registry client, replaced by tests
+ */
+export function createCoverageReaders({ policy, policyRoot, trustedCosign, schemas, dataRoot, env, runCosign = defaultRunCosign, fetchImpl, run, clientFor: injectedClientFor }) {
+  const cosignPath = assertPreparedExecutable(trustedCosign, 'cosign');
+  const declarations = injectedClientFor === undefined ? loadRegistryCredentialDeclarations(dataRoot) : null;
+  const scratch = mkdtempSync(join(tmpdir(), 'xema-coverage-'));
+  const trustedRootPath = join(scratch, 'trusted-root.json');
+  writeFileSync(trustedRootPath, validatePinnedTrustedRoot(policyRoot, policy).bytes, { flag: 'wx', mode: 0o600 });
+  const clients = new Map();
+  const credentials = new Map();
+
+  function clientFor(subject) {
+    const { authority } = splitImageRef(subject.imageRef);
+    if (injectedClientFor !== undefined) {return injectedClientFor(authority);}
+    if (!clients.has(authority)) {
+      const made = registryClientsFor([subject], { declarations, env, fetchImpl, run });
+      clients.set(authority, made.get(authority));
+    }
+    return clients.get(authority);
+  }
+
+  // cosign is handed the SAME declared credential oras uses, through its environment (never argv), and only after
+  // the oras client of that authority has made its first call: that call is the token-realm check.
+  function cosignRegistryEnv(subject) {
+    if (injectedClientFor !== undefined) {return {};}
+    const { authority } = splitImageRef(subject.imageRef);
+    if (!credentials.has(authority)) {
+      const credential = resolveRegistryCredential({ authority, declarations, env });
+      if (credential.access === 'anonymous') {
+        credentials.set(authority, {});
+      } else {
+        const { username, password } = basicAuthParts(credential);
+        credentials.set(authority, { COSIGN_REGISTRY_USERNAME: username, COSIGN_REGISTRY_PASSWORD: password });
+      }
+    }
+    return credentials.get(authority);
+  }
+
+  async function developDigest(subject) {
+    const { repository } = splitImageRef(subject.imageRef);
+    try {
+      const served = await clientFor(subject).getManifestByTag(repository, subject.contentHash);
+      return served.digest;
+    } catch (error) {
+      if (isNotPublishedYet(error)) {return null;}
+      throw error;
+    }
+  }
+
+  async function readAttestation(subject, digest) {
+    const rows = policyCandidates(policy, schemas.IMAGE_PRODUCER_PREDICATE_TYPE, DEVELOP_EVIDENCE_CHANNEL, subject.imageRef);
+    const evidence = await resolveImageSourceEvidenceReferrer({
+      client: clientFor(subject),
+      imageRepository: subject.imageRef,
+      subjectDigest: digest,
+      schemas,
+    });
+    if (evidence === null) {return { status: AttestationStatus.None };}
+    if (rows.length === 0) {return { status: AttestationStatus.NoRow };}
+    const bound = evidence.records.filter(({ statement }) => {
+      const { artifact, source } = statement.predicate;
+      return (
+        artifact.manifestDigest === digest &&
+        artifact.imageRepository === subject.imageRef &&
+        source.kind === subject.kind &&
+        source.id === subject.id &&
+        source.sourceTreeHash === subject.contentHash
+      );
+    });
+    if (bound.length === 0) {
+      return { status: AttestationStatus.Refused, detail: `no record binds ${subject.kind}:${subject.id} at ${digest} for source tree ${subject.contentHash}` };
+    }
+    const failures = [];
+    for (const record of bound) {
+      const evidenceRoot = mkdtempSync(join(scratch, 'record-'));
+      try {
+        writeFileSync(join(evidenceRoot, 'statement.json'), record.statementBytes, { flag: 'wx', mode: 0o600 });
+        writeFileSync(join(evidenceRoot, 'bundle.sigstore.json'), record.bundleBytes, { flag: 'wx', mode: 0o600 });
+        const { identityPolicy } = verifySigstoreEvidenceDescriptor({
+          evidenceRoot,
+          descriptor: {
+            statementPath: 'statement.json',
+            statementDigest: sha256Digest(record.statementBytes),
+            bundlePath: 'bundle.sigstore.json',
+            bundleDigest: sha256Digest(record.bundleBytes),
+            bundleMediaType: BUNDLE_MEDIA_TYPE,
+          },
+          policy,
+          predicateType: schemas.IMAGE_PRODUCER_PREDICATE_TYPE,
+          channel: DEVELOP_EVIDENCE_CHANNEL,
+          imageRepository: subject.imageRef,
+          parseStatement: schemas.parseImageProducerStatement,
+          policyRoot,
+          trustedCosign,
+        });
+        return { status: AttestationStatus.Verified, detail: identityPolicy.policyId };
+      } catch (error) {
+        failures.push(error instanceof Error ? error.message : String(error));
+      } finally {
+        rmSync(evidenceRoot, { recursive: true, force: true });
+      }
+    }
+    return { status: AttestationStatus.Refused, detail: failures.join('; ') };
+  }
+
+  async function readSignatures(subject, digest) {
+    const ref = `${subject.imageRef}@${digest}`;
+    const args = ['verify', '--offline', '--trusted-root', trustedRootPath, '--certificate-identity-regexp', ANY, '--certificate-oidc-issuer-regexp', ANY, '--output', 'json', ref];
+    const result = await runCosign(cosignPath, args, { ...COSIGN_ENV, ...cosignRegistryEnv(subject) });
+    if (result.code !== 0) {
+      if (result.stderr.includes(NO_SIGNATURES_MESSAGE)) {return [];}
+      throw new Error(`cosign verify ${ref} failed (exit ${result.code}): ${result.stderr.trim()}`);
+    }
+    return parseCosignVerifyOutput(result.stdout, digest);
+  }
+
+  return {
+    developDigest,
+    readAttestation,
+    readSignatures,
+    dispose() {
+      rmSync(scratch, { recursive: true, force: true });
+    },
+  };
+}

package/edition/develop-coverage-run.mjs

@@ -0,0 +1,48 @@
+// develop-coverage-run — the body of `xema edition develop coverage <id> --pins <file> --cosign <path> [--json]`.
+//
+// The snapshot half is `develop resolve`'s own (resolveDevelopSnapshot, then resolveImages), so F is computed
+// exactly as resolve computes it. What follows is read-only: registry digests, referrers and signatures.
+
+import { createCoverageReaders } from './develop-coverage-readers.mjs';
+import { collectCoverage, coverageExitCode, renderCoverageTable } from './develop-coverage.mjs';
+import { DEVELOP_EDITION_STEPS, resolveDevelopSnapshot } from './develop-edition-resolve.mjs';
+import { loadDeclaredPinnedPolicy } from './evidence-trust-policy.mjs';
+import { prepareTrustedCosignBinary } from './image-evidence.mjs';
+
+const stderrProgress = (line) => process.stderr.write(`${line}\n`);
+
+/**
+ * @returns {Promise<number>} the exit code: 0 covered, 1 not covered
+ * @throws on an operational error (unreadable pins, registry, cosign): the entry exits 2
+ */
+export async function runDevelopCoverage({
+  id,
+  pins,
+  cosignBinary,
+  json = false,
+  env = process.env,
+  steps = DEVELOP_EDITION_STEPS,
+  loadPolicy = loadDeclaredPinnedPolicy,
+  prepareCosign = prepareTrustedCosignBinary,
+  readerOptions = {},
+  progress = stderrProgress,
+  write = (text) => process.stdout.write(text),
+}) {
+  const { policy, dataRoot } = await loadPolicy();
+  const trustedCosign = prepareCosign({ cosignBinary, policy });
+  try {
+    const { schemas, inputs, lock } = await resolveDevelopSnapshot({ id, pins, steps, phase: (name) => progress(`[coverage] ${name}`) });
+    const { imageLock } = await steps.resolveImages(id, { inputs, lock });
+    progress(`[coverage] image content hashes computed (${imageLock.subjects.length} subjects)`);
+    const readers = createCoverageReaders({ policy, policyRoot: dataRoot, trustedCosign, schemas, dataRoot, env, ...readerOptions });
+    try {
+      const report = await collectCoverage({ distributionId: id, subjects: imageLock.subjects, policy, readers, progress });
+      write(json ? `${JSON.stringify(report, null, 2)}\n` : renderCoverageTable(report));
+      return coverageExitCode(report);
+    } finally {
+      readers.dispose();
+    }
+  } finally {
+    trustedCosign.dispose();
+  }
+}

package/edition/develop-coverage-verdict.mjs

@@ -0,0 +1,153 @@
+// develop-coverage-verdict — the closed verdict vocabulary of `xema edition develop coverage`
+// and the pure decision that turns what was READ about one develop image into a verdict.
+//
+// A verdict is `attested` (case A: a V4 attestation verifies under a pinned develop row) or
+// `signature-verified` (case B: the producer's signature over the digest, with the signed claim
+// annotations, verifies under a pinned develop row and every check passes). Everything else names
+// what is missing; nothing is skipped and nothing defaults.
+
+/** The closed set of verdicts. */
+export const CoverageVerdict = Object.freeze({
+  Attested: 'attested',
+  SignatureVerified: 'signature-verified',
+  NoRow: 'no-row',
+  Unsigned: 'unsigned',
+  AnnotationsMissing: 'annotations-missing',
+  AnnotationMismatch: 'annotation-mismatch',
+  NotBuilt: 'not-built',
+});
+
+/** The verdicts that count toward `covered N/M` (the P2b gate). */
+export const COVERED_VERDICTS = Object.freeze([CoverageVerdict.Attested, CoverageVerdict.SignatureVerified]);
+
+/** The CLI-local predicate a case-B develop policy row carries (T72 design, section 2). */
+export const DEVELOP_IMAGE_SIGNATURE_PREDICATE = 'https://xema.dev/develop-image-signature/v1';
+
+/** The evidence channel the coverage verb reads rows of. */
+export const DEVELOP_EVIDENCE_CHANNEL = 'develop';
+
+/** The workflow triggers a develop signer's certificate may carry (T72 design, section 3). */
+export const DEVELOP_SIGNER_TRIGGERS = Object.freeze(['push', 'workflow_dispatch']);
+
+/** The one ref a develop signer's certificate may carry. */
+export const DEVELOP_SIGNER_REF = 'refs/heads/develop';
+
+/** The signed claim a develop lane puts on its signature (T72 design, section 3, case-B binding). */
+export const DevelopSignatureAnnotation = Object.freeze({
+  ContentHash: 'dev.xema.content-hash',
+  Service: 'dev.xema.service',
+  SourceCommit: 'dev.xema.source.commit',
+});
+
+/** What reading a V4 attestation of one digest concluded. */
+export const AttestationStatus = Object.freeze({
+  /** No evidence referrer is attached to the digest. */
+  None: 'none',
+  /** A referrer exists, but the pinned policy has no develop producer row for this repository. */
+  NoRow: 'no-row',
+  /** A row exists and the record does not verify or does not bind this subject. */
+  Refused: 'refused',
+  /** A record verifies under a pinned develop row and binds this subject. */
+  Verified: 'verified',
+});
+
+// Worst to best: a subject with several signatures takes the best one, because resolve accepts the digest on any.
+const SIGNATURE_RANK = Object.freeze([
+  CoverageVerdict.AnnotationsMissing,
+  CoverageVerdict.AnnotationMismatch,
+  CoverageVerdict.NoRow,
+  CoverageVerdict.SignatureVerified,
+]);
+
+/** Whether a pinned develop row names exactly the identity a certificate carries. */
+export function rowMatchesSigner(row, signer) {
+  return (
+    row.certificateIdentity === signer.certificateIdentity &&
+    row.oidcIssuer === signer.issuer &&
+    row.githubWorkflow.repository === signer.workflowRepository &&
+    row.githubWorkflow.ref === signer.workflowRef &&
+    DEVELOP_SIGNER_TRIGGERS.includes(signer.trigger)
+  );
+}
+
+/**
+ * The verdict of ONE signature.
+ *
+ * @param {object} request
+ * @param {{ contentHash: string, service: string }} request.expected the in-run hash F and service S
+ * @param {{ certificateIdentity: string, issuer: string, workflowRepository: string, workflowRef: string, trigger: string, workflowSha: string }} request.signer
+ * @param {Record<string, string>} request.annotations the signed annotations
+ * @param {object[]} request.rows pinned develop signature rows of this producer (may be empty)
+ */
+export function classifySignature({ expected, signer, annotations, rows }) {
+  const claimed = {
+    contentHash: annotations[DevelopSignatureAnnotation.ContentHash],
+    service: annotations[DevelopSignatureAnnotation.Service],
+    sourceCommit: annotations[DevelopSignatureAnnotation.SourceCommit],
+  };
+  const missing = Object.entries(DevelopSignatureAnnotation)
+    .filter(([, key]) => typeof annotations[key] !== 'string' || annotations[key] === '')
+    .map(([, key]) => key);
+  if (missing.length > 0) {
+    return { verdict: CoverageVerdict.AnnotationsMissing, detail: `missing ${missing.join(', ')}` };
+  }
+  const mismatches = [];
+  if (claimed.contentHash !== expected.contentHash) {
+    mismatches.push(`content-hash ${claimed.contentHash} != ${expected.contentHash}`);
+  }
+  if (claimed.service !== expected.service) {
+    mismatches.push(`service ${claimed.service} != ${expected.service}`);
+  }
+  if (!DEVELOP_SIGNER_TRIGGERS.includes(signer.trigger)) {
+    mismatches.push(`certificate trigger ${signer.trigger} is not ${DEVELOP_SIGNER_TRIGGERS.join(' or ')}`);
+  }
+  if (signer.workflowRef !== DEVELOP_SIGNER_REF) {
+    mismatches.push(`certificate ref ${signer.workflowRef} is not ${DEVELOP_SIGNER_REF}`);
+  }
+  if (claimed.sourceCommit !== signer.workflowSha) {
+    mismatches.push(`annotated source commit ${claimed.sourceCommit} != certificate commit ${signer.workflowSha}`);
+  }
+  if (mismatches.length > 0) {
+    return { verdict: CoverageVerdict.AnnotationMismatch, detail: mismatches.join('; ') };
+  }
+  if (!rows.some((row) => rowMatchesSigner(row, signer))) {
+    return {
+      verdict: CoverageVerdict.NoRow,
+      detail: rows.length === 0 ? 'no pinned develop row for this producer' : 'no pinned develop row names this signer',
+    };
+  }
+  return { verdict: CoverageVerdict.SignatureVerified, detail: '' };
+}
+
+/**
+ * The verdict of one subject from everything read about it. Case A wins; otherwise the best signature.
+ *
+ * @param {object} request
+ * @param {string|null} request.digest the registry digest served for `<developRef>:<F>`, null when absent
+ * @param {{ status: string, detail?: string }} request.attestation
+ * @param {{ signer: object, annotations: object }[]} request.signatures every signature read from the digest
+ * @param {object[]} request.rows pinned develop signature rows of this producer
+ * @param {{ contentHash: string, service: string }} request.expected
+ * @returns {{ verdict: string, detail: string, signer: object|null }}
+ */
+export function classifySubject({ digest, attestation, signatures, rows, expected }) {
+  if (digest === null) {
+    return { verdict: CoverageVerdict.NotBuilt, detail: 'no manifest at the content-hash tag', signer: null };
+  }
+  if (attestation.status === AttestationStatus.Verified) {
+    return { verdict: CoverageVerdict.Attested, detail: attestation.detail ?? '', signer: null };
+  }
+  if (signatures.length === 0) {
+    if (attestation.status === AttestationStatus.NoRow) {
+      return { verdict: CoverageVerdict.NoRow, detail: 'an attestation exists and the policy has no develop producer row', signer: null };
+    }
+    const refused = attestation.status === AttestationStatus.Refused ? `attestation refused: ${attestation.detail}` : 'no signature and no attestation';
+    return { verdict: CoverageVerdict.Unsigned, detail: refused, signer: null };
+  }
+  const judged = signatures.map((signature) => ({
+    ...classifySignature({ expected, signer: signature.signer, annotations: signature.annotations, rows }),
+    signer: signature.signer,
+  }));
+  judged.sort((left, right) => SIGNATURE_RANK.indexOf(right.verdict) - SIGNATURE_RANK.indexOf(left.verdict));
+  return judged[0];
+}

package/edition/develop-coverage.mjs

@@ -0,0 +1,120 @@
+// develop-coverage — `xema edition develop coverage <id>`: for every image subject an edition selects,
+// is its DEVELOP image producer-signed in the form T72 resolve is expected to accept? A forecast, not a guarantee: the
+// policy is held to its pin, but this CLI's own unpinned verifier code runs, so resolve can still refuse. Read-only: it writes no lock,
+// signature or tag. It is the P2b gate (exit 0 only at 100%).
+//
+// The subjects, their develop refs and content hashes F are the ones `develop resolve` computes (the
+// caller passes the images lock that resolve's own first half produced); the registry digest D is the
+// one served for `<developRef>:<F>`; the verdict is decided by develop-coverage-verdict.mjs.
+
+import { AttestationStatus, COVERED_VERDICTS, DEVELOP_EVIDENCE_CHANNEL, DEVELOP_IMAGE_SIGNATURE_PREDICATE, classifySubject } from './develop-coverage-verdict.mjs';
+import { developImageRef } from './develop-image-coordinate.mjs';
+import { policyCandidates } from './image-evidence.mjs';
+import { mapWithConcurrency } from './map-with-concurrency.mjs';
+
+/** In flight at once, as `develop resolve` probes. */
+export const COVERAGE_CONCURRENCY = 6;
+
+export const COVERAGE_JSON_SCHEMA = 'xema.develop-coverage/v1';
+
+/** Exit codes of the verb; 2 is an operational error and is decided by the entry. */
+export const CoverageExit = Object.freeze({ Covered: 0, NotCovered: 1, Operational: 2 });
+
+/**
+ * The service name a develop lane signs for a subject (`dev.xema.service`): the subject's id in the lock.
+ * One definition; the signing lanes (T72 P1) must sign this.
+ */
+export const expectedService = (subject) => subject.id;
+
+/**
+ * @param {object} request
+ * @param {string} request.distributionId
+ * @param {object[]} request.subjects the images lock subjects (release refs, unsealed), contentHash = F
+ * @param {object} request.policy the pinned trust policy (rows are filtered per develop repository)
+ * @param {{ developDigest: Function, readAttestation: Function, readSignatures: Function }} request.readers
+ * @param {(line: string) => void} [request.progress]
+ */
+export async function collectCoverage({ distributionId, subjects, policy, readers, concurrency = COVERAGE_CONCURRENCY, progress = () => {} }) {
+  const rows = await mapWithConcurrency(subjects, concurrency, async (subject) => {
+    const developSubject = { ...subject, imageRef: developImageRef(subject.imageRef) };
+    const digest = await readers.developDigest(developSubject);
+    let attestation = { status: AttestationStatus.None };
+    let signatures = [];
+    if (digest !== null) {
+      attestation = await readers.readAttestation(developSubject, digest);
+      if (attestation.status !== AttestationStatus.Verified) {signatures = await readers.readSignatures(developSubject, digest);}
+    }
+    const signatureRows = policyCandidates(policy, DEVELOP_IMAGE_SIGNATURE_PREDICATE, DEVELOP_EVIDENCE_CHANNEL, developSubject.imageRef);
+    const decided = classifySubject({
+      digest,
+      attestation,
+      signatures,
+      rows: signatureRows,
+      expected: { contentHash: subject.contentHash, service: expectedService(subject) },
+    });
+    progress(`[coverage] ${subject.kind}:${subject.id} ${decided.verdict}`);
+    return {
+      kind: subject.kind,
+      id: subject.id,
+      producer: subject.repo,
+      developRef: developSubject.imageRef,
+      contentHash: subject.contentHash,
+      digest,
+      verdict: decided.verdict,
+      detail: decided.detail,
+      signer: decided.signer,
+    };
+  });
+  return summarize(distributionId, rows);
+}
+
+function summarize(distributionId, subjects) {
+  const byProducer = new Map();
+  for (const subject of subjects) {
+    const entry = byProducer.get(subject.producer) ?? { producer: subject.producer, total: 0, covered: 0, subjects: [] };
+    entry.total += 1;
+    if (COVERED_VERDICTS.includes(subject.verdict)) {entry.covered += 1;}
+    entry.subjects.push(subject);
+    byProducer.set(subject.producer, entry);
+  }
+  const producers = [...byProducer.values()].sort((left, right) => (left.producer < right.producer ? -1 : left.producer > right.producer ? 1 : 0));
+  for (const producer of producers) {
+    producer.subjects.sort((left, right) => (`${left.kind}:${left.id}` < `${right.kind}:${right.id}` ? -1 : 1));
+  }
+  return {
+    schema: COVERAGE_JSON_SCHEMA,
+    distributionId,
+    covered: producers.reduce((sum, producer) => sum + producer.covered, 0),
+    total: subjects.length,
+    producers,
+  };
+}
+
+/** Exit 0 only when every subject is covered; an edition with no subjects covers nothing. */
+export function coverageExitCode(report) {
+  return report.total > 0 && report.covered === report.total ? CoverageExit.Covered : CoverageExit.NotCovered;
+}
+
+export function summaryLine(report) {
+  return `covered ${report.covered}/${report.total}`;
+}
+
+function signerText(signer) {
+  if (signer === null) {return '';}
+  return `${signer.certificateIdentity} (${signer.issuer}, ${signer.trigger}, ${signer.workflowSha})`;
+}
+
+/** The table, grouped by producer repo, ending in the summary line. */
+export function renderCoverageTable(report) {
+  const lines = [];
+  for (const producer of report.producers) {
+    lines.push(`${producer.producer}  covered ${producer.covered}/${producer.total}`);
+    for (const subject of producer.subjects) {
+      const parts = [`  ${subject.kind}:${subject.id}`, subject.verdict, subject.digest ?? '-'];
+      const tail = [subject.detail, signerText(subject.signer)].filter((text) => text !== '').join(' | ');
+      lines.push(tail === '' ? parts.join('  ') : `${parts.join('  ')}  ${tail}`);
+    }
+  }
+  lines.push(summaryLine(report));
+  return `${lines.join('\n')}\n`;
+}

package/edition/develop-edition-resolve.mjs

@@ -11,9 +11,9 @@ import { biomeSourceTreeIds, readBiomeSourceFacts, sealLock } from './biome-cont
 import { buildCatalogue } from './catalogue.mjs';
 import { resolveDevelopChartSet } from './develop-chart-set.mjs';
 import { createDevelopImageProbe } from './develop-image-probe.mjs';
-import { sealDevelopImages } from './develop-seal.mjs';
 import { assertFrozenCheckouts, buildSnapshotInputs } from './develop-snapshot-inputs.mjs';
 import { EditionChannel } from './edition-constants.mjs';
+import { sealImages } from './edition-image-seal.mjs';
 import { kernelPackageDir } from './edition-workspace.mjs';
 import { kernelPackageOfAuthority } from './kernel-package.mjs';
 import { loadKernelDistributionSchemas } from './lib.mjs';
@@ -33,21 +33,32 @@ export const DEVELOP_EDITION_STEPS = Object.freeze({
   assertAdapterBundlesMatchHost,
   composeAuthorizationBase,
   resolveImages,
-  sealDevelopImages,
+  sealImages,
   resolveDevelopChartSet,
 });
 
 const stderrProgress = (line) => process.stderr.write(`${line}\n`);
 
-export async function resolveDevelopEdition({ id, pins, env = process.env, sealOptions = {}, fetchKernelTarball, fetchManifest = fetchRegistryManifest, progress = stderrProgress, steps = DEVELOP_EDITION_STEPS }) {
-  const startedAt = Date.now();
-  // One line per phase, with the time since the resolve began, so the step is never silent for long.
-  const phase = (name) => progress(`[develop-edition] ${name} (+${Date.now() - startedAt}ms)`);
+/**
+ * The first half of every develop resolve: the frozen snapshot's inputs and the
+ * distribution lock composed over them. `resolveDevelopEdition` and the
+ * read-only `coverage` verb both start here, so the content hash each computes
+ * for a subject is the same by construction.
+ */
+export async function resolveDevelopSnapshot({ id, pins, steps = DEVELOP_EDITION_STEPS, phase = () => {} }) {
   const schemas = await loadKernelDistributionSchemas();
   steps.assertFrozenCheckouts(pins);
   const inputs = await steps.buildSnapshotInputs({ id, pins, schemas });
   phase('snapshot inputs built');
   const { lock, index } = await steps.resolveDistributionWithIndex(id, { inputs });
+  return { schemas, inputs, lock, index };
+}
+
+export async function resolveDevelopEdition({ id, pins, env = process.env, sealOptions = {}, fetchKernelTarball, fetchManifest = fetchRegistryManifest, progress = stderrProgress, steps = DEVELOP_EDITION_STEPS }) {
+  const startedAt = Date.now();
+  // One line per phase, with the time since the resolve began, so the step is never silent for long.
+  const phase = (name) => progress(`[develop-edition] ${name} (+${Date.now() - startedAt}ms)`);
+  const { schemas, inputs, lock, index } = await resolveDevelopSnapshot({ id, pins, steps, phase });
   await steps.assertAdapterBundlesMatchHost({ lock, hostRow: adapterHostRow(index), fetchManifest });
   const authorizationLock = await steps.composeAuthorizationBase(id, lock, index);
   phase('distribution lock resolved');
@@ -66,7 +77,7 @@ export async function resolveDevelopEdition({ id, pins, env = process.env, sealO
   phase(`image content hashes computed (${imageLock.subjects.length} subjects)`);
   await probe.settle();
   phase('every develop image is present');
-  const sealedImageLock = await steps.sealDevelopImages({ imageLock, env, progress, ...sealOptions });
+  const sealedImageLock = await steps.sealImages({ channel: EditionChannel.Develop, imageLock, env, progress, ...sealOptions });
   phase('images sealed');
   // The unsealed lock becomes the one v5 grammar only here, once the images it
   // owns are sealed: each biomeContentHash is recomputed from the frozen sources.