@xemahq/xema 0.59.1 → 0.60.1

package/edition/edition-artifact.mjs

@@ -1,529 +0,0 @@
-// edition-artifact — the files of an edition and where they may go.
-//
-// ONE layout for develop and release: an OCI artifact at
-// `<registry root>/<channel segment>/xema-edition-<id>` (release: `editions`, develop: `develop-editions`,
-// from edition-contract.json), addressed by digest, whose titled layers are
-// `xema-edition.json` (the descriptor) plus the lock files. It is written to a
-// scratch directory; the workflow pushes it with oras and signs the digest.
-// Tags are for humans only (an edition resolved from a snapshot: the hash of every input, snapshotEditionTag; vendor release: the
-// coordinate). Admission rests on the signature of the manifest digest, never on
-// a channel label: no reader branches on `provenance.channel`.
-//
-// The artifact is never written to git, so the writer REFUSES a target inside
-// either the data tree or the editions root.
-
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
-import { basename, dirname, join, relative, resolve, sep, isAbsolute } from 'node:path';
-
-import { assertCanonicalDistributionId } from './distribution-paths.mjs';
-import { EDITION_CHART_SET_FILE, assertRosteredChartSetLock } from './edition-chart-set.mjs';
-import {
-  CATALOGUE_PIN_KEY,
-  CustomerPinForm,
-  DEFINITION_PIN_KEY,
-  DIGEST_PIN_KEYS,
-  EDITION_DESCRIPTOR_FILE,
-  EDITION_DESCRIPTOR_SCHEMA,
-  EDITION_LOCKS,
-  EDITION_REPOSITORY_PREFIX,
-  EDITION_REPOSITORY_SEGMENTS,
-  EditionChannel,
-  EditionKind,
-  EditionLockFile,
-  SEALED_EDITION_CHANNEL,
-  SEAL_OF_PATTERN,
-  VENDOR_MEMBER_PIN_PATTERN,
-  admittedEvidenceTrustStates,
-  customerPinFormAdmitted,
-} from './edition-constants.mjs';
-import { dataRoot, editionsRoot } from './edition-workspace.mjs';
-import { serializeJson, sha256Hex } from './lib.mjs';
-import { isSourcePinKey, sortedSnapshotPins } from './pin-source.mjs';
-import { readStrictJsonFile } from './strict-json.mjs';
-
-/** Which GitHub Actions run produced the artifact; recorded in its descriptor. */
-export function workflowFromEnv(env) {
-  const repository = env.GITHUB_REPOSITORY;
-  const runId = env.GITHUB_RUN_ID;
-  if (!repository || !runId) {
-    throw new Error(
-      'an edition records the workflow run that produced it: GITHUB_REPOSITORY and GITHUB_RUN_ID are required ' +
-        '(pass --local to write outside GitHub Actions)',
-    );
-  }
-  return { repository, runId };
-}
-
-/** The workflow stamp of a write that is explicitly not from CI. */
-export const LOCAL_WORKFLOW = Object.freeze({ repository: 'local', runId: 'local' });
-
-const ENGINE_IMAGE_PATTERN = /^[a-z0-9.-]+(:[0-9]+)?(\/[a-z0-9._-]+)+@sha256:[a-f0-9]{64}$/;
-
-/** The deploy engine image, by digest only: `<repository>@sha256:<64 hex>`. No tag form, no default. */
-export function assertEngineImage(image) {
-  if (typeof image !== 'string' || !ENGINE_IMAGE_PATTERN.test(image)) {
-    throw new Error(
-      `--engine-image ${JSON.stringify(image)} is not <repository>@sha256:<64 hex>: the deploy engine is pinned by digest, never by tag`,
-    );
-  }
-  return image;
-}
-
-/**
- * The descriptor (xema.edition/v2): what this artifact is (its `kind`, and for a sealed edition the
- * resolved edition it seals, `sealOf`), which locks it carries, where it came from, whether the data
- * root's editions are evidence-gated, and the deploy engine image that consumes it. Every writer of a
- * descriptor passes here, and the strict parse it ends in holds the contract's rule: no route writes
- * an edition whose evidence trust state its kind and channel do not admit, whatever its caller computed.
- */
-export function editionDescriptor({ kind, sealOf, distributionId, channel, pins, workflow, evidenceTrustPolicy, engineImage }) {
-  assertCanonicalDistributionId(distributionId);
-  return parseEditionDescriptor({
-    schema: EDITION_DESCRIPTOR_SCHEMA,
-    kind,
-    ...(kind === EditionKind.Sealed ? { sealOf } : {}),
-    distributionId,
-    locks: [...EDITION_LOCKS],
-    provenance: {
-      channel,
-      pins: sortedSnapshotPins(pins),
-      workflow: { repository: workflow?.repository, runId: workflow?.runId },
-    },
-    evidenceTrustPolicy,
-    engine: { image: engineImage },
-  });
-}
-
-const COMMIT_PATTERN = /^[0-9a-f]{40}$/;
-const DIGEST_PIN_PATTERN = /^sha256:[0-9a-f]{64}$/;
-const DESCRIPTOR_KEYS = Object.freeze(['schema', 'kind', 'distributionId', 'locks', 'provenance', 'evidenceTrustPolicy', 'engine']);
-
-/**
- * The one parser of a sealed edition's `sealOf`, the digest-pinned ref of the resolved edition it seals: its form is the
- * contract's `sealOf.pattern` (`<registry>/<path>@sha256:<64 hex>`), and its repository is an edition repository
- * (`<registry root>/<channel segment>/xema-edition-<id>`). Returns `{ repository, digest, registryRoot, channel, distributionId }`.
- */
-export function parseSealOf(sealOf) {
-  if (typeof sealOf !== 'string' || !SEAL_OF_PATTERN.test(sealOf)) {
-    throw new Error(
-      `sealOf ${JSON.stringify(sealOf)} does not match the contract's sealOf.pattern ${SEAL_OF_PATTERN.source}: a seal names the resolved edition ` +
-        `<registry root>/<channel segment>/${EDITION_REPOSITORY_PREFIX}<id> by digest`,
-    );
-  }
-  const at = sealOf.lastIndexOf('@');
-  const digest = sealOf.slice(at + 1);
-  const repository = sealOf.slice(0, at);
-  return { repository, digest, ...parseEditionRepository(repository) };
-}
-
-const exactKeys = (value, keys, where) => {
-  if (value === null || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).sort().join() !== [...keys].sort().join()) {
-    throw new Error(`${where} must be exactly {${keys.join(', ')}}`);
-  }
-};
-
-/**
- * The closed customer pin rule (edition-contract.json provenancePins.customerForms). A descriptor whose pins carry the
- * definition pin is a customer edition, and it carries exactly one form: the CATALOGUE form (the catalogue pin, the
- * definition pin and sources/<name> commits, nothing else), or the CATALOGUE-FREE form (no catalogue pin, at least one
- * vendor member pin), each only on the kinds and channels the contract admits it on. A descriptor without the definition
- * pin is not a customer edition and the rule does not apply to it.
- */
-export function assertCustomerPinForm(kind, channel, pins, distributionId) {
-  if (!(DEFINITION_PIN_KEY in pins)) {
-    // only a customer edition records a vendor side: every other edition carries neither form's marker
-    if (CATALOGUE_PIN_KEY in pins) {
-      throw new Error(`${EDITION_DESCRIPTOR_FILE}: the ${kind} ${channel} edition "${distributionId}" carries the catalogue pin without the definition pin: only a customer edition (the definition pin) records the catalogue it was resolved against`);
-    }
-    return;
-  }
-  const where = `${EDITION_DESCRIPTOR_FILE}: the customer ${kind} ${channel} edition "${distributionId}"`;
-  if (CATALOGUE_PIN_KEY in pins) {
-    if (!customerPinFormAdmitted(CustomerPinForm.Catalogue, kind, channel)) {
-      throw new Error(`${where} carries the catalogue pin, but the contract admits the catalogue form on no ${kind} ${channel} edition`);
-    }
-    const stray = Object.keys(pins).filter((key) => key !== CATALOGUE_PIN_KEY && key !== DEFINITION_PIN_KEY && !isSourcePinKey(key));
-    if (stray.length > 0) {
-      throw new Error(`${where} carries the catalogue pin and also ${stray.map((key) => JSON.stringify(key)).join(', ')}: the catalogue form pins only the catalogue, the definition and sources/<name>`);
-    }
-    return;
-  }
-  if (!customerPinFormAdmitted(CustomerPinForm.CatalogueFree, kind, channel)) {
-    throw new Error(`${where} carries no catalogue pin: only a ${catalogueFreeAdmissions()} customer edition may be resolved catalogue-free`);
-  }
-  if (!Object.keys(pins).some((key) => VENDOR_MEMBER_PIN_PATTERN.test(key))) {
-    throw new Error(`${where} carries neither the catalogue pin nor a vendor member pin: a catalogue-free edition records the vendor member pins it was resolved from`);
-  }
-}
-
-const catalogueFreeAdmissions = () =>
-  Object.values(EditionKind)
-    .flatMap((kind) => Object.values(EditionChannel).filter((channel) => customerPinFormAdmitted(CustomerPinForm.CatalogueFree, kind, channel)).map((channel) => `${kind} ${channel}`))
-    .join(' or ');
-
-/**
- * The strict parse of a descriptor: exact keys, the closed kind enum (no default, never inferred), `sealOf` exactly on a
- * sealed edition, closed vocabularies, the evidence trust state the contract admits for the kind on the channel, an engine
- * image by digest. Returns it unchanged.
- */
-export function parseEditionDescriptor(value) {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-    throw new Error(`${EDITION_DESCRIPTOR_FILE} must be a JSON object`);
-  }
-  if (value.schema !== EDITION_DESCRIPTOR_SCHEMA) {
-    throw new Error(`${EDITION_DESCRIPTOR_FILE}: schema is ${JSON.stringify(value.schema)}, expected ${JSON.stringify(EDITION_DESCRIPTOR_SCHEMA)}`);
-  }
-  if (!Object.values(EditionKind).includes(value.kind)) {
-    throw new Error(
-      `${EDITION_DESCRIPTOR_FILE}: kind is ${JSON.stringify(value.kind)}, expected exactly ${Object.values(EditionKind).join(' | ')}; there is no default kind and none is inferred`,
-    );
-  }
-  const sealed = value.kind === EditionKind.Sealed;
-  if (!sealed && 'sealOf' in value) {
-    throw new Error(`${EDITION_DESCRIPTOR_FILE}: kind ${value.kind} carries sealOf; only a sealed edition names the resolved edition it seals`);
-  }
-  exactKeys(value, sealed ? [...DESCRIPTOR_KEYS, 'sealOf'] : DESCRIPTOR_KEYS, EDITION_DESCRIPTOR_FILE);
-  assertCanonicalDistributionId(value.distributionId);
-  if (!Array.isArray(value.locks) || value.locks.length === 0 || value.locks.some((file) => typeof file !== 'string' || file === '')) {
-    throw new Error(`${EDITION_DESCRIPTOR_FILE}: locks must be a non-empty array of file names`);
-  }
-  exactKeys(value.provenance, ['channel', 'pins', 'workflow'], `${EDITION_DESCRIPTOR_FILE} provenance`);
-  if (!Object.values(EditionChannel).includes(value.provenance.channel)) {
-    throw new Error(`${EDITION_DESCRIPTOR_FILE}: provenance.channel must be one of ${Object.values(EditionChannel).join(' | ')}`);
-  }
-  const { pins, workflow } = value.provenance;
-  if (pins === null || typeof pins !== 'object' || Array.isArray(pins)) {
-    throw new Error(`${EDITION_DESCRIPTOR_FILE}: provenance.pins must map pin keys to 40-hex commits (the ${DIGEST_PIN_KEYS.map((key) => `"${key}"`).join(' and ')} pins to sha256 digests)`);
-  }
-  for (const [key, pin] of Object.entries(pins)) {
-    const digestPin = DIGEST_PIN_KEYS.includes(key);
-    const pattern = digestPin ? DIGEST_PIN_PATTERN : COMMIT_PATTERN;
-    if (typeof pin !== 'string' || !pattern.test(pin)) {
-      throw new Error(
-        digestPin
-          ? `${EDITION_DESCRIPTOR_FILE}: provenance.pins["${key}"] must be a sha256:<64 hex> digest`
-          : `${EDITION_DESCRIPTOR_FILE}: provenance.pins must map pin keys to 40-hex commits (${JSON.stringify(key)} is not)`,
-      );
-    }
-  }
-  assertCustomerPinForm(value.kind, value.provenance.channel, pins, value.distributionId);
-  exactKeys(workflow, ['repository', 'runId'], `${EDITION_DESCRIPTOR_FILE} provenance.workflow`);
-  if (!workflow.repository || !workflow.runId || typeof workflow.repository !== 'string' || typeof workflow.runId !== 'string') {
-    throw new Error(`${EDITION_DESCRIPTOR_FILE}: provenance.workflow is {repository, runId}, both non-empty strings`);
-  }
-  if (sealed && value.provenance.channel !== SEALED_EDITION_CHANNEL) {
-    throw new Error(
-      `${EDITION_DESCRIPTOR_FILE}: a sealed edition records provenance.channel ${SEALED_EDITION_CHANNEL} (a seal is ${SEALED_EDITION_CHANNEL}-only); "${value.distributionId}" records ${JSON.stringify(value.provenance.channel)}`,
-    );
-  }
-  // The reader holds the writer's rule (contract evidenceTrust.statesByKind): `not-armed` only on a resolved develop edition.
-  const admitted = admittedEvidenceTrustStates(value.kind, value.provenance.channel);
-  if (!admitted.includes(value.evidenceTrustPolicy)) {
-    throw new Error(
-      `${EDITION_DESCRIPTOR_FILE}: a ${value.kind} ${value.provenance.channel} edition records evidenceTrustPolicy ${admitted.join(' | ')}; ` +
-        `"${value.distributionId}" records ${JSON.stringify(value.evidenceTrustPolicy)}`,
-    );
-  }
-  if (sealed) {
-    const sealOf = parseSealOf(value.sealOf);
-    if (sealOf.distributionId !== value.distributionId) {
-      throw new Error(`${EDITION_DESCRIPTOR_FILE}: sealOf ${value.sealOf} is an edition of "${sealOf.distributionId}", not of "${value.distributionId}"`);
-    }
-    if (sealOf.channel !== value.provenance.channel) {
-      throw new Error(
-        `${EDITION_DESCRIPTOR_FILE}: sealOf ${value.sealOf} is a ${sealOf.channel} edition, but the seal records provenance.channel ${value.provenance.channel}; a seal keeps the channel of the edition it seals`,
-      );
-    }
-  }
-  exactKeys(value.engine, ['image'], `${EDITION_DESCRIPTOR_FILE} engine`);
-  assertEngineImage(value.engine.image);
-  return value;
-}
-
-const REGISTRY_PATTERN = /^[a-z0-9.-]+(:[0-9]+)?(\/[a-z0-9._-]+)+$/;
-/** `.` and `..` match the segment grammar and name no namespace: a registry resolves them away. */
-const isDotSegment = (segment) => segment === '.' || segment === '..';
-const TAG_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$/;
-
-/**
- * The registry ROOT is the caller's `<host>[:port]/<namespace>[/...]`; the CLI appends the channel's
- * namespace segment AND `xema-edition-<id>` itself, so a root already ending in either is refused.
- */
-export function assertRegistry(registryRoot) {
-  if (typeof registryRoot !== 'string' || !REGISTRY_PATTERN.test(registryRoot) || registryRoot.split('/').slice(1).some(isDotSegment)) {
-    throw new Error(
-      `--registry ${JSON.stringify(registryRoot)} is not <registry-host>[:port]/<namespace>[/...] (lowercase, e.g. registry.example.com/acme)`,
-    );
-  }
-  const last = registryRoot.split('/').pop();
-  if (Object.values(EDITION_REPOSITORY_SEGMENTS).includes(last) || last.startsWith(EDITION_REPOSITORY_PREFIX)) {
-    throw new Error(
-      `--registry ${registryRoot} ends in "${last}", which the CLI appends itself: pass the registry root; ` +
-        `the CLI appends <${Object.values(EDITION_REPOSITORY_SEGMENTS).join('|')}>/${EDITION_REPOSITORY_PREFIX}<id>`,
-    );
-  }
-}
-
-function assertChannel(channel) {
-  if (!Object.values(EditionChannel).includes(channel)) {
-    throw new Error(`edition channel ${JSON.stringify(channel)} must be one of ${Object.values(EditionChannel).join(' | ')}`);
-  }
-}
-
-/** `<registry root>/<channel segment>/xema-edition-<id>`: the repository of an edition produced for `channel`. */
-export function editionRepository(distributionId, registryRoot, channel) {
-  assertCanonicalDistributionId(distributionId);
-  assertRegistry(registryRoot);
-  assertChannel(channel);
-  return `${registryRoot}/${EDITION_REPOSITORY_SEGMENTS[channel]}/${EDITION_REPOSITORY_PREFIX}${distributionId}`;
-}
-
-/**
- * The one parser of an edition repository `<root>/<segment>/xema-edition-<id>`, returning
- * `{ registryRoot, channel, distributionId }`. The penultimate segment must be one of the contract's
- * channel segments and the last must carry the repository prefix.
- */
-export function parseEditionRepository(repository) {
-  const segments = typeof repository === 'string' ? repository.split('/') : [];
-  const last = segments.at(-1) ?? '';
-  const segment = segments.at(-2);
-  const channel = Object.values(EditionChannel).find((candidate) => EDITION_REPOSITORY_SEGMENTS[candidate] === segment);
-  if (channel === undefined) {
-    throw new Error(
-      `edition repository ${JSON.stringify(repository)}: its namespace segment ${JSON.stringify(segment)} is not one of ` +
-        Object.values(EDITION_REPOSITORY_SEGMENTS).map((name) => `"${name}"`).join(', '),
-    );
-  }
-  if (!last.startsWith(EDITION_REPOSITORY_PREFIX)) {
-    throw new Error(`edition repository ${JSON.stringify(repository)}: its name ${JSON.stringify(last)} lacks the "${EDITION_REPOSITORY_PREFIX}" prefix`);
-  }
-  const distributionId = last.slice(EDITION_REPOSITORY_PREFIX.length);
-  assertCanonicalDistributionId(distributionId);
-  const registryRoot = segments.slice(0, -2).join('/');
-  assertRegistry(registryRoot);
-  return { registryRoot, channel, distributionId };
-}
-
-/** `<repository>:<tag>`; the tag is for humans, the artifact is addressed by its digest. */
-export function editionTarget(distributionId, registryRoot, channel, tag) {
-  if (typeof tag !== 'string' || !TAG_PATTERN.test(tag)) {
-    throw new Error(`tag ${JSON.stringify(tag)} is not an OCI tag`);
-  }
-  return `${editionRepository(distributionId, registryRoot, channel)}:${tag}`;
-}
-
-/** The version of this CLI, the writer of every descriptor and lock: read lazily, so a bundle that never tags does not need it. */
-let cliVersionMemo;
-export function cliVersion() {
-  if (cliVersionMemo === undefined) {
-    const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
-    if (typeof version !== 'string' || version.length === 0) {throw new Error('@xemahq/xema: no "version" in its package.json');}
-    cliVersionMemo = version;
-  }
-  return cliVersionMemo;
-}
-
-/** `{ <source>: "<registry>/<prefix>" }` sorted by source: the canonical form of a parsed --source-image map. */
-export function canonicalSourceImages(sourceImages = new Map()) {
-  return Object.fromEntries(
-    [...sourceImages.entries()]
-      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-      .map(([name, { imageRegistry, imageNamePrefix }]) => [name, `${imageRegistry}/${imageNamePrefix}`]),
-  );
-}
-
-/**
- * The tag of an edition resolved from a snapshot (a develop edition, a customer release edition): sha256 of the canonical `{ cli, engine, pins, sourceImages }`, plus `imageBuildRecord` (the record's digest) for a develop resolve --images-from. Every input of
- * the bytes the artifact records is inside it. The pins fix the locks and the descriptor's pins: a vendor edition's
- * commits fix its definitions; a customer edition's pins carry its sources' commits, the catalogue digest and the
- * digest of its canonical definition (`definition`: vendor selection, image registry mirror, Store publisher anchors); the
- * descriptor's `engine.image` is not a pin; a customer's `--source-image` map composes its own image rows
- * (`<registry>/<prefix><subject>`) and is not a pin either; and the CLI version is the writer of every
- * byte. A tag over the pins alone named two artifacts that differ in any of the others, and a re-run could
- * only refuse the existing one (`check-existing`) or reuse a stale one. `provenance.workflow` (the run that
- * wrote the bytes) is the one recorded field outside it: a fact about the artifact, not an input to it.
- */
-export function snapshotEditionTag({ pins, engineImage, sourceImages = new Map(), imageBuildRecordDigest, version = cliVersion() }) {
-  return sha256Hex(
-    serializeJson({
-      cli: version,
-      engine: assertEngineImage(engineImage),
-      pins: sortedSnapshotPins(pins),
-      sourceImages: canonicalSourceImages(sourceImages),
-      // A develop resolve from an image build record (--images-from): the record fixes the image rows, and a satellite
-      // digest changes independently of the pins. Absent on the probe path, whose tag inputs are unchanged.
-      ...(imageBuildRecordDigest === undefined ? {} : { imageBuildRecord: assertImageBuildRecordDigest(imageBuildRecordDigest) }),
-    }),
-  );
-}
-
-function assertImageBuildRecordDigest(digest) {
-  if (typeof digest !== 'string' || !/^[0-9a-f]{64}$/.test(digest)) {
-    throw new Error(`an image build record digest must be 64 lowercase hex; got ${JSON.stringify(digest)}`);
-  }
-  return digest;
-}
-
-/** The target of an edition resolved from a snapshot of pins, on either channel: the tag is `snapshotEditionTag`. */
-export function snapshotEditionTarget(channel, distributionId, pins, { registry, engineImage, sourceImages, imageBuildRecordDigest }) {
-  return editionTarget(distributionId, registry, channel, snapshotEditionTag({ pins, engineImage, sourceImages, imageBuildRecordDigest }));
-}
-
-/** A develop edition's target: the tag is `snapshotEditionTag` of the pins, the engine, the source images and any image build record. */
-export function developEditionTarget(distributionId, pins, { registry, engineImage, sourceImages, imageBuildRecordDigest }) {
-  return snapshotEditionTarget(EditionChannel.Develop, distributionId, pins, { registry, engineImage, sourceImages, imageBuildRecordDigest });
-}
-
-function realpathOfPlanned(path) {
-  const absolute = resolve(path);
-  let existing = absolute;
-  const rest = [];
-  while (!existsSync(existing)) {
-    rest.unshift(basename(existing));
-    existing = dirname(existing);
-  }
-  return join(realpathSync(existing), ...rest);
-}
-
-function isWithin(path, directory) {
-  const inside = relative(realpathOfPlanned(directory), path);
-  return !(inside === '..' || inside.startsWith(`..${sep}`) || isAbsolute(inside));
-}
-
-function assertOutsideCommittedTrees(outDir) {
-  const planned = realpathOfPlanned(outDir);
-  for (const [label, tree] of [
-    ['the data tree', dataRoot()],
-    ['the editions root', editionsRoot()],
-  ]) {
-    if (isWithin(planned, tree)) {
-      throw new Error(`refusing to write an edition artifact to ${outDir}: it lies inside ${label} (${tree}), which is committed content`);
-    }
-  }
-}
-
-/** Write the descriptor and the locks of a RESOLVED edition of `channel` to `outDir`; returns the descriptor. */
-export function writeEditionArtifact({
-  outDir,
-  channel,
-  distributionId,
-  pins,
-  workflow,
-  evidenceTrustPolicy,
-  engineImage,
-  distributionLock,
-  imageLock,
-  authorizationLock,
-  chartSetLock,
-}) {
-  assertOutsideCommittedTrees(outDir);
-  const byFile = [
-    [EditionLockFile.Distribution, distributionLock],
-    [EditionLockFile.Images, imageLock],
-    [EditionLockFile.Authorization, authorizationLock],
-    [EditionLockFile.ChartSet, chartSetLock],
-  ];
-  for (const [file, lock] of byFile) {
-    if (lock === null || lock === undefined) {
-      throw new Error(`edition "${distributionId}" has no ${file}: an edition carries all four locks`);
-    }
-  }
-  assertRosteredChartSetLock(chartSetLock, EDITION_CHART_SET_FILE);
-  const descriptor = editionDescriptor({ kind: EditionKind.Resolved, distributionId, channel, pins, workflow, evidenceTrustPolicy, engineImage });
-  mkdirSync(outDir, { recursive: true });
-  for (const [file, value] of [[EDITION_DESCRIPTOR_FILE, descriptor], ...byFile]) {
-    writeFileSync(join(outDir, file), serializeJson(value));
-  }
-  return descriptor;
-}
-
-/**
- * An existing develop tag is reused only if it IS this snapshot: the tag
- * is a hash of its inputs, but a tag is mutable registry state, so the pulled
- * descriptor must say the same edition, the same channel, exactly the same pins,
- * the same engine image, the same evidence trust state and the same lock set. A customer artifact (`catalogueDigest` and
- * `definitionDigest` given) must also record those digests as its catalogue and definition provenance pins. Throws naming
- * the first difference.
- */
-export function assertExistingArtifactMatches({ artifactDir, distributionId, channel, pins, engineImage, evidenceTrustPolicy, catalogueDigest, definitionDigest }) {
-  const descriptorPath = join(artifactDir, EDITION_DESCRIPTOR_FILE);
-  if (!existsSync(descriptorPath)) {
-    throw new Error(`the existing artifact holds no ${EDITION_DESCRIPTOR_FILE}; refusing to reuse a tag that is not an edition`);
-  }
-  const existing = parseEditionDescriptor(readStrictJsonFile(descriptorPath));
-  if (existing.kind !== EditionKind.Resolved) {
-    throw new Error(`the existing artifact is a ${existing.kind} edition; only a resolved edition is reused for a snapshot, refusing to reuse it`);
-  }
-  assertCanonicalDistributionId(distributionId);
-  if (existing.distributionId !== distributionId) {
-    throw new Error(`the existing artifact's distributionId is ${JSON.stringify(existing.distributionId)}, expected ${JSON.stringify(distributionId)}; refusing to reuse it`);
-  }
-  if (existing.provenance.channel !== channel) {
-    throw new Error(`the existing artifact was produced on channel ${JSON.stringify(existing.provenance.channel)}, expected ${JSON.stringify(channel)}; refusing to reuse it`);
-  }
-  if (existing.evidenceTrustPolicy !== evidenceTrustPolicy) {
-    throw new Error(`the existing artifact records evidenceTrustPolicy ${JSON.stringify(existing.evidenceTrustPolicy)}, this data root's is ${JSON.stringify(evidenceTrustPolicy)}; refusing to reuse it`);
-  }
-  if (catalogueDigest !== undefined && existing.provenance.pins[CATALOGUE_PIN_KEY] !== catalogueDigest) {
-    throw new Error(
-      `the existing artifact's catalogue provenance pin is ${JSON.stringify(existing.provenance.pins[CATALOGUE_PIN_KEY])}, ` +
-        `the pinned catalogue is ${catalogueDigest}; refusing to reuse it`,
-    );
-  }
-  if (definitionDigest !== undefined && existing.provenance.pins[DEFINITION_PIN_KEY] !== definitionDigest) {
-    throw new Error(
-      `the existing artifact was resolved from customer definition ${JSON.stringify(existing.provenance.pins[DEFINITION_PIN_KEY])}, ` +
-        `this definition is ${definitionDigest} (its selection, mirror or Store publisher anchors differ); refusing to reuse it`,
-    );
-  }
-  if (serializeJson(existing.provenance.pins) !== serializeJson(sortedSnapshotPins(pins))) {
-    throw new Error('the existing artifact was resolved from different pins than this snapshot (tag and content disagree); refusing to reuse it');
-  }
-  if (existing.engine.image !== assertEngineImage(engineImage)) {
-    throw new Error(`the existing artifact names engine ${existing.engine.image}, not ${engineImage}; refusing to reuse it`);
-  }
-  if (serializeJson(existing.locks) !== serializeJson(EDITION_LOCKS)) {
-    throw new Error('the existing artifact lists a different lock set than an edition carries; refusing to reuse it');
-  }
-  for (const file of existing.locks) {
-    if (!existsSync(join(artifactDir, file))) {
-      throw new Error(`the existing artifact lacks ${file}, which its descriptor lists; refusing to reuse it`);
-    }
-  }
-}
-
-/**
- * Write the SEALED edition of one exact resolved edition to `outDir`: every layer of the resolved artifact other than
- * its descriptor, byte for byte (`layers`: title -> bytes, already proven to be the layers of `sealOf`), plus a sealed
- * descriptor. The seal keeps the resolved edition's distribution, locks, channel, pins and engine image; it records
- * `sealOf`, the run that sealed it, and an evidence trust state its kind admits (contract: armed). Returns the descriptor.
- */
-export function writeSealedEditionArtifact({ outDir, resolved, sealOf, layers, workflow, evidenceTrustPolicy }) {
-  assertOutsideCommittedTrees(outDir);
-  if (resolved.kind !== EditionKind.Resolved) {
-    throw new Error(`${sealOf} is a ${resolved.kind} edition; a seal seals exactly one resolved edition`);
-  }
-  if (layers.has(EDITION_DESCRIPTOR_FILE)) {
-    throw new Error(`the layers of a seal exclude the resolved ${EDITION_DESCRIPTOR_FILE}; the seal writes its own`);
-  }
-  const missing = resolved.locks.filter((file) => !layers.has(file));
-  if (missing.length > 0) {
-    throw new Error(`${sealOf} lacks ${missing.join(', ')}, which its descriptor lists`);
-  }
-  const descriptor = editionDescriptor({
-    kind: EditionKind.Sealed,
-    sealOf,
-    distributionId: resolved.distributionId,
-    channel: resolved.provenance.channel,
-    pins: resolved.provenance.pins,
-    workflow,
-    evidenceTrustPolicy,
-    engineImage: resolved.engine.image,
-  });
-  mkdirSync(outDir, { recursive: true });
-  writeFileSync(join(outDir, EDITION_DESCRIPTOR_FILE), serializeJson(descriptor));
-  for (const [file, bytes] of layers) {
-    writeFileSync(join(outDir, file), bytes);
-  }
-  return descriptor;
-}

package/edition/edition-biome-manifests.mjs

@@ -1,85 +0,0 @@
-#!/usr/bin/env node
-// `xema edition biome-manifests <id> --json`: the PINNED xema-biome.json of every
-// biome of one edition, as JSON.
-//
-// usage: xema edition biome-manifests <id> --json --data-root <dir> --editions-root <dir>
-//   --sources-root <dir> --kernel <dir>
-//
-// For every biome of the edition's resolved lock this reads the manifest AT the
-// commit the lock pins (the way the seal and `xema edition check` read it) and
-// prints one document on stdout:
-//   {"schema":"xema.edition-biome-manifests/v1","distributionId","biomes":[{"id","repo","sourceCommit","manifest"}]}
-// sorted by biome id. A consumer (the store catalogue) reads this instead of
-// reading the sources itself. Read-only. When the lock is absent or a pinned
-// manifest cannot be read it prints NOTHING on stdout, a message on stderr, and exits non-zero.
-
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-
-import { pinnedBiomeManifests } from './biome-content.mjs';
-import { assertCanonicalDistributionId } from './distribution-paths.mjs';
-import { editionPinnedInputs } from './edition-pinned-inputs.mjs';
-import {
-  WorkspaceRoot,
-  configureEditionWorkspaceFromArgv,
-  editionsRoot,
-  isEntryModule,
-} from './edition-workspace.mjs';
-import { loadKernelDistributionSchemas, serializeJson } from './lib.mjs';
-import { externalSourceTrees, sourceTreeLocator } from './resolve-images.mjs';
-import { createPinnedSourceAuthority } from './source-authority.mjs';
-
-export const EDITION_BIOME_MANIFESTS_SCHEMA = 'xema.edition-biome-manifests/v1';
-
-const USAGE =
-  'usage: xema edition biome-manifests <id> --json --data-root <dir> --editions-root <dir> --sources-root <dir> --kernel <dir>';
-
-function readLock(distributionId, file) {
-  try {
-    return JSON.parse(readFileSync(join(editionsRoot(), distributionId, file), 'utf8'));
-  } catch (error) {
-    throw new Error(`edition "${distributionId}" has no readable ${file} under ${editionsRoot()}: ${error.message}`);
-  }
-}
-
-export async function editionBiomeManifests({ distributionId, schemas }) {
-  assertCanonicalDistributionId(distributionId);
-  const lock = schemas.parseDistributionLock(readLock(distributionId, 'distribution.lock.json'));
-  const imageLock = schemas.parseImageLock(readLock(distributionId, 'images.lock.json'));
-  const authority = createPinnedSourceAuthority({ pins: (await editionPinnedInputs(distributionId, { schemas })).repositoryPins });
-  return {
-    schema: EDITION_BIOME_MANIFESTS_SCHEMA,
-    distributionId,
-    biomes: await pinnedBiomeManifests({
-      schemas,
-      lock,
-      imageLock,
-      locate: sourceTreeLocator(externalSourceTrees(lock)),
-      vendoredCommit: (repo) => authority.vendoredSourceCommitForRepository(repo),
-    }),
-  };
-}
-
-async function main() {
-  const rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), [
-    WorkspaceRoot.Data,
-    WorkspaceRoot.Editions,
-    WorkspaceRoot.Sources,
-    WorkspaceRoot.Kernel,
-  ]);
-  const operands = rest.filter((arg) => arg !== '--json');
-  if (operands.length !== 1 || rest.length - operands.length !== 1) {
-    throw new Error(USAGE);
-  }
-  const schemas = await loadKernelDistributionSchemas();
-  // Built whole before anything is written, so a refusal leaves stdout empty.
-  const document = await editionBiomeManifests({ distributionId: operands[0], schemas });
-  process.stdout.write(serializeJson(document));
-}
-
-if (isEntryModule(import.meta.url)) {
-  main().catch((error) => {
-    console.error(`[edition-biome-manifests] ${error.message}`);
-    process.exitCode = 1;
-  });
-}