@xemahq/xema 0.26.0 → 0.28.0

package/edition/producer-evidence-bundle.mjs

@@ -0,0 +1,157 @@
+import { readFileSync, statSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+
+import {
+  canonicalJson,
+  decodeExactUtf8,
+  sha256Digest,
+} from './image-evidence.mjs';
+import {
+  BUNDLE_MEDIA_TYPE,
+  validateProducedBundle,
+} from './produce-image-source-evidence.mjs';
+
+export const PRODUCER_EVIDENCE_INDEX_FILE = 'producer-evidence.json';
+export const PRODUCER_EVIDENCE_INDEX_MEDIA_TYPE =
+  'application/vnd.xema.image-source-evidence.index.v1+json';
+export const PRODUCER_STATEMENT_MEDIA_TYPE = 'application/vnd.in-toto+json';
+export const MAX_PRODUCER_EVIDENCE_FILE_BYTES = 4 * 1024 * 1024;
+
+function assertRelativeArtifactPath(value, label) {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    value.startsWith('/') ||
+    value.split('/').some((part) => !part || part === '.' || part === '..')
+  ) {
+    throw new Error(`${label} is not a contained relative path`);
+  }
+  return value;
+}
+
+function readBounded(root, relativePath, label) {
+  const safePath = assertRelativeArtifactPath(relativePath, label);
+  const path = join(root, safePath);
+  const stat = statSync(path);
+  if (!stat.isFile() || stat.size > MAX_PRODUCER_EVIDENCE_FILE_BYTES) {
+    throw new Error(
+      `${label} must be a regular file no larger than ${MAX_PRODUCER_EVIDENCE_FILE_BYTES} bytes`,
+    );
+  }
+  return readFileSync(path);
+}
+
+/**
+ * Fields that identify the immutable build are stable. producerRun identifies
+ * one signing execution and intentionally changes on every retry/refresh.
+ */
+export function stableProducerStatementBinding(statement) {
+  const { producerRun: _producerRun, ...predicate } = statement.predicate;
+  return {
+    _type: statement._type,
+    subject: statement.subject,
+    predicateType: statement.predicateType,
+    predicate,
+  };
+}
+
+export function producerStatementMatchesInput(statement, expectedStatement) {
+  return (
+    canonicalJson(stableProducerStatementBinding(statement)) ===
+    canonicalJson(stableProducerStatementBinding(expectedStatement))
+  );
+}
+
+/** Read and structurally validate one producer evidence directory. */
+export function readProducerEvidenceDirectory({ directory, schemas }) {
+  if (!isAbsolute(directory)) {
+    throw new Error('producer evidence directory must be absolute');
+  }
+  if (!schemas?.parseImageProducerStatement) {
+    throw new Error('trusted kernel distribution schemas are required');
+  }
+  const indexBytes = readBounded(
+    directory,
+    PRODUCER_EVIDENCE_INDEX_FILE,
+    'producer evidence index',
+  );
+  let index;
+  try {
+    index = JSON.parse(decodeExactUtf8(indexBytes, 'producer evidence index'));
+  } catch (error) {
+    throw new Error(`producer evidence index is not exact UTF-8 JSON: ${error.message}`);
+  }
+  if (
+    index?.schemaVersion !== 1 ||
+    !Array.isArray(index.producerEvidence) ||
+    index.producerEvidence.length === 0
+  ) {
+    throw new Error('producer evidence index is not non-empty schemaVersion 1');
+  }
+
+  const seen = new Set();
+  const records = [];
+  for (const entry of index.producerEvidence) {
+    const key = `${entry?.subjectKind}:${entry?.subjectId}`;
+    if (
+      typeof entry?.subjectKind !== 'string' ||
+      typeof entry?.subjectId !== 'string' ||
+      entry.evidence === null ||
+      typeof entry.evidence !== 'object' ||
+      seen.has(key)
+    ) {
+      throw new Error(`producer evidence index has a malformed or duplicate entry ${key}`);
+    }
+    seen.add(key);
+    const descriptor = entry.evidence;
+    const statementBytes = readBounded(
+      directory,
+      descriptor.statementPath,
+      `${key} statement`,
+    );
+    const bundleBytes = readBounded(
+      directory,
+      descriptor.bundlePath,
+      `${key} bundle`,
+    );
+    if (
+      descriptor.bundleMediaType !== BUNDLE_MEDIA_TYPE ||
+      sha256Digest(statementBytes) !== descriptor.statementDigest ||
+      sha256Digest(bundleBytes) !== descriptor.bundleDigest
+    ) {
+      throw new Error(`${key} artifacts do not match their descriptor`);
+    }
+    validateProducedBundle(statementBytes, bundleBytes);
+    const statement = schemas.parseImageProducerStatement(
+      JSON.parse(decodeExactUtf8(statementBytes, `${key} statement`)),
+    );
+    if (
+      statement.predicate.source.kind !== entry.subjectKind ||
+      statement.predicate.source.id !== entry.subjectId
+    ) {
+      throw new Error(`${key} index identity does not match its signed statement`);
+    }
+    records.push({
+      key,
+      entry,
+      descriptor,
+      statement,
+      statementBytes,
+      bundleBytes,
+    });
+  }
+  return { index, indexBytes, records };
+}
+
+export function producerEvidenceLayerFiles(records) {
+  return [
+    {
+      path: PRODUCER_EVIDENCE_INDEX_FILE,
+      mediaType: PRODUCER_EVIDENCE_INDEX_MEDIA_TYPE,
+    },
+    ...records.flatMap(({ descriptor }) => [
+      { path: descriptor.statementPath, mediaType: PRODUCER_STATEMENT_MEDIA_TYPE },
+      { path: descriptor.bundlePath, mediaType: BUNDLE_MEDIA_TYPE },
+    ]),
+  ];
+}

package/edition/registry-credentials.mjs

@@ -0,0 +1,193 @@
+// Registry credential DECLARATIONS and image-reference parsing.
+//
+// This module owns the committed `image-registry-credentials.json` contract:
+// which registry authorities may be read, whether each is read anonymously or
+// with a credential taken from a NAMED environment variable, and how an image
+// reference splits into authority and repository. It performs no I/O against a
+// registry; `oras.mjs` owns the transport.
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { dataRoot } from './edition-workspace.mjs';
+import { isCanonicalRegistryAuthority } from './lib.mjs';
+
+export const REGISTRY_CREDENTIALS_FILE = 'image-registry-credentials.json';
+
+/**
+ * Closed set. `anonymous` means "this registry is deliberately read without a
+ * credential"; `authenticated` means "a credential is mandatory". There is no
+ * third state, and in particular no "try authenticated, fall back to
+ * anonymous" — that fallback is exactly how a private registry silently
+ * degrades into an unverifiable one.
+ */
+const REGISTRY_ACCESS_MODES = Object.freeze(['anonymous', 'authenticated']);
+
+
+export const OCI_INDEX_MEDIA_TYPES = Object.freeze([
+  'application/vnd.oci.image.index.v1+json',
+  'application/vnd.docker.distribution.manifest.list.v2+json',
+]);
+
+export const OCI_MANIFEST_MEDIA_TYPES = Object.freeze([
+  'application/vnd.oci.image.manifest.v1+json',
+  'application/vnd.docker.distribution.manifest.v2+json',
+]);
+
+const ENV_VAR_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+
+// Docker Hub is the one registry whose wire authority is not its reference
+// authority (`docker.io` resolves to `registry-1.docker.io`, and single-segment
+// repositories are implicitly `library/*`). Implementing that rewrite silently
+// would make one registry behave differently from every other. Refuse instead.
+const AUTHORITIES_REQUIRING_EXPLICIT_REWRITE = new Set([
+  'docker.io',
+  'index.docker.io',
+  'registry.hub.docker.com',
+]);
+
+/**
+ * Split `registry.example.com/acme/service` into its registry authority and repository
+ * path. The image lock already guarantees the shape; this re-derives it rather
+ * than trusting a caller-supplied split.
+ */
+export function splitImageRef(imageRef) {
+  if (typeof imageRef !== 'string' || imageRef.length === 0) {
+    throw new Error('image reference must be a non-empty string');
+  }
+  const slash = imageRef.indexOf('/');
+  if (slash <= 0 || slash === imageRef.length - 1) {
+    throw new Error(
+      `image reference "${imageRef}" has no registry authority and repository path`,
+    );
+  }
+  const authority = imageRef.slice(0, slash);
+  const repository = imageRef.slice(slash + 1);
+  if (!isCanonicalRegistryAuthority(authority)) {
+    throw new Error(
+      `image reference "${imageRef}" does not start with a canonical registry authority`,
+    );
+  }
+  return { authority, repository };
+}
+
+export function assertCredentialDeclaration(entry, index) {
+  const label = `${REGISTRY_CREDENTIALS_FILE} registries[${index}]`;
+  if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+    throw new Error(`${label} must be an object`);
+  }
+  if (
+    typeof entry.authority !== 'string' ||
+    !isCanonicalRegistryAuthority(entry.authority)
+  ) {
+    throw new Error(`${label}.authority must be a canonical registry authority`);
+  }
+  if (!REGISTRY_ACCESS_MODES.includes(entry.access)) {
+    throw new Error(
+      `${label}.access must be one of ${REGISTRY_ACCESS_MODES.join(', ')}`,
+    );
+  }
+  const keys = Object.keys(entry).sort().join(',');
+  if (entry.access === 'authenticated') {
+    if (keys !== 'access,authTokenEnv,authority,username') {
+      throw new Error(
+        `${label} must declare exactly access, authTokenEnv, authority, username`,
+      );
+    }
+    if (!ENV_VAR_NAME_PATTERN.test(entry.authTokenEnv)) {
+      throw new Error(
+        `${label}.authTokenEnv must be an UPPER_SNAKE environment variable NAME (never an inlined secret)`,
+      );
+    }
+    if (typeof entry.username !== 'string' || entry.username.length === 0) {
+      throw new Error(`${label}.username must be a non-empty string`);
+    }
+  } else if (keys !== 'access,authority') {
+    throw new Error(`${label} must declare exactly access and authority`);
+  }
+  return entry;
+}
+
+/**
+ * Read the committed registry credential DECLARATION. The file names
+ * environment variables; it never contains a secret. See
+ * `.claude/rules/biome-sources.md` constraint C2.
+ */
+export function loadRegistryCredentialDeclarations(
+  distributionsRoot = dataRoot(),
+) {
+  const path = join(distributionsRoot, REGISTRY_CREDENTIALS_FILE);
+  const raw = JSON.parse(readFileSync(path, 'utf8'));
+  const keys = Object.keys(raw ?? {}).sort().join(',');
+  if (
+    typeof raw !== 'object' ||
+    raw === null ||
+    Array.isArray(raw) ||
+    raw.schemaVersion !== 1 ||
+    !Array.isArray(raw.registries) ||
+    (keys !== 'registries,schemaVersion' &&
+      keys !== '$comment,registries,schemaVersion') ||
+    ('$comment' in raw &&
+      (!Array.isArray(raw.$comment) ||
+        raw.$comment.some((line) => typeof line !== 'string')))
+  ) {
+    throw new Error(`${REGISTRY_CREDENTIALS_FILE} is not strict schema v1`);
+  }
+  const byAuthority = new Map();
+  for (const [index, entry] of raw.registries.entries()) {
+    assertCredentialDeclaration(entry, index);
+    if (byAuthority.has(entry.authority)) {
+      throw new Error(
+        `${REGISTRY_CREDENTIALS_FILE} declares "${entry.authority}" more than once`,
+      );
+    }
+    byAuthority.set(entry.authority, entry);
+  }
+  return byAuthority;
+}
+
+/**
+ * Resolve a declared authority to the credential it will actually use.
+ *
+ * A NAMED-but-unset environment variable FAILS FAST. It must never fall
+ * through to an unauthenticated request: that is how a 403 on a private
+ * package turns into "the platform is missing" instead of "your token is
+ * missing".
+ */
+export function resolveRegistryCredential({
+  authority,
+  declarations,
+  env = process.env,
+}) {
+  const declaration = declarations.get(authority);
+  if (!declaration) {
+    throw new Error(
+      `registry "${authority}" has no entry in ${REGISTRY_CREDENTIALS_FILE}; ` +
+        'declare it with access "anonymous" or "authenticated" before reading from it',
+    );
+  }
+  if (AUTHORITIES_REQUIRING_EXPLICIT_REWRITE.has(authority)) {
+    throw new Error(
+      `registry "${authority}" needs a documented authority/repository rewrite that this client deliberately does not perform`,
+    );
+  }
+  if (declaration.access === 'anonymous') {
+    return { authority, access: 'anonymous', basicAuth: null };
+  }
+  const token = env[declaration.authTokenEnv];
+  if (typeof token !== 'string' || token.length === 0) {
+    throw new Error(
+      `registry "${authority}" requires a pull credential in $${declaration.authTokenEnv}, ` +
+        'and that variable is unset or empty. Export a token with read:packages ' +
+        'scope for this registry; an unauthenticated read is NOT attempted, because ' +
+        'a 403 on a private package is indistinguishable from a missing image.',
+    );
+  }
+  return {
+    authority,
+    access: 'authenticated',
+    basicAuth: Buffer.from(`${declaration.username}:${token}`, 'utf8').toString(
+      'base64',
+    ),
+  };
+}

package/edition/release-catalogue.mjs

@@ -0,0 +1,39 @@
+// release-catalogue — the catalogue of a RELEASE offering, from its committed, sealed locks.
+
+import { readFileSync } from 'node:fs';
+
+import { biomeSourceTreeIds } from './biome-content.mjs';
+import { buildCatalogue } from './catalogue.mjs';
+import { EditionChannel } from './edition-constants.mjs';
+import { biomeIndexPath, platformServiceIndexPath, runtimeImageSourceIndexPath } from './edition-workspace.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
+import { loadEditionManifest } from './resolve-distribution.mjs';
+import { externalSourceTrees, sourceTreeLocator } from './resolve-images.mjs';
+import { committedRepositoryPins, createPinnedSourceAuthority } from './source-authority.mjs';
+
+/** The catalogue of release offering `id`, from the committed locks (`locks` as `readCommittedEdition` returns them). */
+export async function releaseCatalogue(id, locks) {
+  const schemas = await loadKernelDistributionSchemas();
+  const authority = createPinnedSourceAuthority({ pins: committedRepositoryPins() });
+  // The WRITER of the catalogue's tree ids: the real `git rev-parse <commit>:<path>` of every biome.
+  const sourceTreeIds = await biomeSourceTreeIds({
+    schemas,
+    lock: locks.distributionLock,
+    imageLock: locks.imageLock,
+    locate: sourceTreeLocator(externalSourceTrees(locks.distributionLock)),
+    vendoredCommit: (repo) => authority.vendoredSourceCommitForRepository(repo),
+  });
+  return buildCatalogue({
+    sourceTreeIds,
+    offeringId: id,
+    channel: EditionChannel.Release,
+    distributionLock: locks.distributionLock,
+    imageLock: locks.imageLock,
+    chartSetLock: locks.chartSetLock,
+    biomeIndex: JSON.parse(readFileSync(biomeIndexPath(), 'utf8')),
+    platformServiceIndex: schemas.parsePlatformServiceSourceIndex(JSON.parse(readFileSync(platformServiceIndexPath(), 'utf8'))),
+    contractAuthority: schemas.parseRuntimeImageSourceIndex(JSON.parse(readFileSync(runtimeImageSourceIndexPath(), 'utf8'))).contractAuthority,
+    leaf: loadEditionManifest(schemas.parseDistribution, id),
+  });
+}
+

package/edition/release-channel-guard.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// release-channel-guard — release tooling's content assertions over an editions
+// tree.
+//
+// No check here reads a channel label, a schema name or a file name to decide
+// what an edition IS: admission rests on the cosign signature of the artifact's
+// manifest digest, and the descriptor's `provenance.channel` is a record, never
+// a gate. What stays is what the BYTES must satisfy: a release images lock names
+// release repositories only, and a release lock set is whole (the companion
+// chart-set lock beside the distribution and authorization locks).
+//
+//   node release-channel-guard.mjs <checkout-dir>
+//     refuses if any edition directory under <checkout-dir> breaks either.
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { isDevelopImageRef } from './develop-image-coordinate.mjs';
+import { EDITION_CHART_SET_FILE, assertRosteredChartSetLock } from './edition-chart-set.mjs';
+import { EditionChannel, EditionLockFile } from './edition-constants.mjs';
+import { isEntryModule } from './edition-workspace.mjs';
+
+/** Throws when `value` (a parsed JSON document) names a develop image repository. `where` names it in the refusal. */
+export function assertReleaseContent(value, where) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {return;}
+  const developSubject = (value.subjects ?? []).find((subject) => isDevelopImageRef(subject?.imageRef));
+  if (developSubject) {
+    throw new Error(
+      `${where} names the develop image repository ${developSubject.imageRef} (subject ${developSubject.kind}:${developSubject.id}); ` +
+        'a release lock names release repositories only',
+    );
+  }
+  // A chart-set lock (one with a roster of publishers) carries release chart
+  // coordinates only: a develop chart set copied into a release is refused.
+  if (Array.isArray(value.publishers)) {
+    assertRosteredChartSetLock(value, where, EditionChannel.Release);
+  }
+}
+
+/** Throws when an edition directory holds a lock naming a develop image repository, or a release lock without its companions. */
+export function assertReleaseEditionTree(dir) {
+  for (const file of [EditionLockFile.Distribution, EditionLockFile.Images, EditionLockFile.Authorization, EditionLockFile.ChartSet]) {
+    const path = join(dir, file);
+    if (existsSync(path)) {assertReleaseContent(JSON.parse(readFileSync(path, 'utf8')), path);}
+  }
+  assertReleaseLockSet(dir);
+}
+
+/**
+ * The release lock set. A directory holding the distribution or the
+ * authorization lock must hold the whole set, including the `chart-set.lock.json`
+ * the release writes with them and hashes into the edition's coordinate, so a
+ * lock copied alone into an edition directory is refused.
+ *
+ * What this guarantees is PRESENCE, not binding: the companion chart-set lock
+ * must exist beside the locks. It does not check that the set's locks agree
+ * with one another or with a recorded digest (nothing records one: the release
+ * envelope does not carry a lock-set digest), so it is not "hash-bound" and
+ * must not be described as such.
+ */
+export const RELEASE_COMPANION_FILES = Object.freeze([EDITION_CHART_SET_FILE]);
+
+/**
+ * The release locks an edition directory holds (the distribution and the
+ * authorization lock). A directory holding either IS a release edition: a
+ * develop resolve writes nothing into an editions tree, so a lock committed
+ * there was written by the release resolve.
+ */
+export function heldReleaseLocks(dir) {
+  return [EditionLockFile.Distribution, EditionLockFile.Authorization].filter((file) => existsSync(join(dir, file)));
+}
+
+function assertReleaseLockSet(dir) {
+  const held = heldReleaseLocks(dir);
+  if (held.length === 0) {return;}
+  const missing = RELEASE_COMPANION_FILES.filter((file) => !existsSync(join(dir, file)));
+  if (missing.length > 0) {
+    throw new Error(
+      `${dir} holds ${held.join(' and ')} but not ${missing.join(' and ')}: a release edition carries its locks as one set, ` +
+        'so a lock without its companions is not a release edition. ' +
+        'Resolve the edition whole, or remove the stray lock.',
+    );
+  }
+}
+
+/** The guard over every direct subdirectory of a checkout (each is an edition or holds none). */
+export function assertReleaseCheckout(root) {
+  let checked = 0;
+  for (const entry of readdirSync(root).sort()) {
+    if (entry.startsWith('.') || entry === 'node_modules') {continue;}
+    const dir = join(root, entry);
+    if (!statSync(dir).isDirectory()) {continue;}
+    assertReleaseEditionTree(dir);
+    checked += 1;
+  }
+  return checked;
+}
+
+if (isEntryModule(import.meta.url)) {
+  try {
+    const [root, ...rest] = process.argv.slice(2);
+    if (!root || rest.length > 0) {throw new Error('usage: node release-channel-guard.mjs <checkout-dir>');}
+    const checked = assertReleaseCheckout(resolve(root));
+    console.log(`[release-channel-guard] ${checked} directories hold no develop content.`);
+  } catch (error) {
+    console.error(`[release-channel-guard] ${error.message}`);
+    process.exit(1);
+  }
+}

package/edition/release-edition-artifact.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// release-edition-artifact — write the OCI artifact of a RELEASE edition from
+// the committed, sealed locks of the editions root.
+//
+//   artifact <id> --channel release --registry <namespace> --coordinate <tag>
+//            --engine-image <repository>@sha256:<digest> --out <dir> [--local]
+//
+// The artifact has the layout of every edition (edition-artifact.mjs): the
+// descriptor plus the four locks and the offering's catalogue.json, written to <dir>, and the target
+// `<registry>/xema-edition-<id>:<coordinate>` is printed. The workflow pushes
+// <dir> with oras and signs the manifest DIGEST with cosign; the tag is for
+// humans. A lock set that is not sealed is refused: an unsealed images lock names
+// no image digests, so nothing could be admitted against it.
+
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { verifyBiomeContentHashes } from './biome-content.mjs';
+import { writeCatalogue } from './catalogue.mjs';
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import { LOCAL_WORKFLOW, assertEngineImage, editionTarget, workflowFromEnv, writeEditionArtifact } from './edition-artifact.mjs';
+import { assertRosteredChartSetLock } from './edition-chart-set.mjs';
+import { EditionChannel, EditionLockFile } from './edition-constants.mjs';
+import { WorkspaceRoot, configureEditionWorkspaceFromProcess, editionsRoot, isEntryModule } from './edition-workspace.mjs';
+import { descriptorEvidenceTrust } from './evidence-trust-policy.mjs';
+import { loadKernelDistributionSchemas, validateImmutableImageLock } from './lib.mjs';
+import { releaseCatalogue } from './release-catalogue.mjs';
+import { assertReleaseEditionTree } from './release-channel-guard.mjs';
+import { externalSourceTrees, sourceTreeLocator } from './resolve-images.mjs';
+import { committedRepositoryPins, createPinnedSourceAuthority } from './source-authority.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel]);
+}
+
+const VALUE_FLAGS = Object.freeze(['--channel', '--registry', '--coordinate', '--engine-image', '--out']);
+const REQUIRED_FLAGS = VALUE_FLAGS;
+const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
+
+/** Parse `artifact <id> --flag value ...`; only the release channel is written by this verb. */
+export function parseReleaseArtifactArgs(argv) {
+  const [command, ...rest] = argv;
+  if (command !== 'artifact') {throw new Error(`unknown command ${JSON.stringify(command)}; expected artifact`);}
+  const options = {};
+  const positional = [];
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === '--local') {
+      options[arg] = true;
+    } else if (VALUE_FLAGS.includes(arg)) {
+      const value = rest[i + 1];
+      if (value === undefined || (value.startsWith('--') && value.length > 2)) {throw new Error(`${arg} requires a value`);}
+      options[arg] = value;
+      i += 1;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`unknown argument ${arg} for artifact`);
+    } else {
+      positional.push(arg);
+    }
+  }
+  if (positional.length !== 1) {throw new Error('artifact takes exactly one <distribution-id>');}
+  for (const required of REQUIRED_FLAGS) {
+    if (options[required] === undefined) {throw new Error(`artifact requires ${required}`);}
+  }
+  if (options['--channel'] !== EditionChannel.Release) {
+    throw new Error(
+      `--channel ${JSON.stringify(options['--channel'])}: this verb writes ${EditionChannel.Release} editions from the committed locks; ` +
+        'a develop edition is resolved from a snapshot by `xema edition develop resolve`',
+    );
+  }
+  assertCanonicalDistributionId(positional[0]);
+  assertEngineImage(options['--engine-image']);
+  return { id: positional[0], options };
+}
+
+/** The images lock must be sealed: every subject names the registry digest of its image. */
+export function assertSealedImageLock(lock, label) {
+  const subjects = lock?.subjects ?? [];
+  if (subjects.length === 0) {throw new Error(`${label} carries no subjects, so it seals nothing`);}
+  const unsealed = subjects.filter((subject) => !DIGEST_PATTERN.test(String(subject?.imageDigest)));
+  if (unsealed.length > 0) {
+    throw new Error(
+      `${label} is not sealed: ${unsealed.length} of ${subjects.length} subjects carry no imageDigest ` +
+        `(first: ${unsealed[0].kind}:${unsealed[0].id}). Run \`xema edition seal\` first.`,
+    );
+  }
+}
+
+/**
+ * The four committed locks of a release edition, validated. Nothing is published from a set
+ * that is not sealed and intact: the images lock names every digest, the distribution lock is
+ * the SEALED grammar (an unsealed one is refused), and every `biomeContentHash` is recomputed
+ * from its inputs and compared, so a lock edited after its seal is refused, naming the biome.
+ */
+export async function readCommittedEdition(id, root = editionsRoot()) {
+  const dir = join(root, id);
+  assertReleaseEditionTree(dir);
+  const read = (file) => JSON.parse(readFileSync(join(dir, file), 'utf8'));
+  const schemas = await loadKernelDistributionSchemas();
+  const imageLock = validateImmutableImageLock(schemas.parseImageLock(read(EditionLockFile.Images)), schemas);
+  assertSealedImageLock(imageLock, join(dir, EditionLockFile.Images));
+  const distributionLock = read(EditionLockFile.Distribution);
+  let sealed;
+  try {
+    sealed = schemas.parseDistributionLock(distributionLock);
+  } catch (error) {
+    throw new Error(
+      `${join(dir, EditionLockFile.Distribution)} is not a sealed distribution lock, so nothing is published from it. ` +
+        `Run \`xema edition seal ${id}\` first. (${error.message})`,
+      { cause: error },
+    );
+  }
+  const authority = createPinnedSourceAuthority({ pins: committedRepositoryPins() });
+  await verifyBiomeContentHashes({
+    schemas,
+    lock: sealed,
+    imageLock,
+    locate: sourceTreeLocator(externalSourceTrees(sealed)),
+    vendoredCommit: (repo) => authority.vendoredSourceCommitForRepository(repo),
+  });
+  return {
+    distributionLock,
+    imageLock: read(EditionLockFile.Images),
+    authorizationLock: read(EditionLockFile.Authorization),
+    chartSetLock: assertRosteredChartSetLock(read(EditionLockFile.ChartSet), join(dir, EditionLockFile.ChartSet), EditionChannel.Release),
+  };
+}
+
+async function run(argv, env) {
+  const { id, options } = parseReleaseArtifactArgs(argv);
+  const target = editionTarget(id, options['--registry'], options['--coordinate']);
+  const workflow = options['--local'] ? LOCAL_WORKFLOW : workflowFromEnv(env);
+  const locks = await readCommittedEdition(id);
+  // Refuses (EvidenceTrustRequiredError) unless the policy is ARMED on the
+  // release channel: a release artifact is never written not-armed.
+  const evidenceTrustPolicy = await descriptorEvidenceTrust({ channel: EditionChannel.Release });
+  const outDir = resolve(options['--out']);
+  writeEditionArtifact({
+    outDir,
+    channel: EditionChannel.Release,
+    distributionId: id,
+    pins: {},
+    workflow,
+    evidenceTrustPolicy,
+    engineImage: options['--engine-image'],
+    ...locks,
+  });
+  writeCatalogue(outDir, await releaseCatalogue(id, locks));
+  console.log(target);
+}
+
+if (isEntryModule(import.meta.url)) {
+  run(process.argv.slice(2), process.env).catch((error) => {
+    console.error(`[edition-artifact] ${error.message}`);
+    process.exit(1);
+  });
+}