@xemahq/xema 0.26.0 → 0.28.0

package/edition/distribution-paths.mjs

@@ -0,0 +1,191 @@
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+const DISTRIBUTION_ID_PATTERN =
+  /^[a-zA-Z0-9](?:[a-zA-Z0-9._-]{0,126}[a-zA-Z0-9])?$/;
+
+export function assertCanonicalDistributionId(distributionId) {
+  if (
+    typeof distributionId !== 'string' ||
+    !DISTRIBUTION_ID_PATTERN.test(distributionId)
+  ) {
+    throw new Error(
+      'distribution id must be a canonical 1-128 character identifier',
+    );
+  }
+  return distributionId;
+}
+
+function assertContained(root, candidate, label) {
+  const rel = relative(root, candidate);
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new Error(`${label} escapes the distributions root`);
+  }
+}
+
+export function resolveDistributionDirectory(
+  distributionsRoot,
+  distributionId,
+) {
+  assertCanonicalDistributionId(distributionId);
+  const root = realpathSync(distributionsRoot);
+  const expectedDirectory = join(root, distributionId);
+  if (!existsSync(expectedDirectory)) {
+    throw new Error(`distribution "${distributionId}" does not exist`);
+  }
+  const directory = realpathSync(expectedDirectory);
+  assertContained(root, directory, `distribution "${distributionId}"`);
+  if (directory !== expectedDirectory) {
+    throw new Error(
+      `distribution "${distributionId}" directory must not be a symlink`,
+    );
+  }
+  return { root, directory };
+}
+
+export function resolveDistributionFile(
+  distributionsRoot,
+  distributionId,
+  fileName,
+) {
+  const { directory } = resolveDistributionDirectory(
+    distributionsRoot,
+    distributionId,
+  );
+  const expectedPath = join(directory, fileName);
+  if (!existsSync(expectedPath)) {
+    throw new Error(
+      `distribution "${distributionId}" has no ${fileName} (${expectedPath})`,
+    );
+  }
+  const path = realpathSync(expectedPath);
+  assertContained(directory, path, `${fileName} for "${distributionId}"`);
+  if (path !== expectedPath) {
+    throw new Error(
+      `${fileName} for distribution "${distributionId}" must not be a symlink`,
+    );
+  }
+  return path;
+}
+
+export function readBoundDistributionFile({
+  distributionsRoot,
+  distributionId,
+  fileName,
+  parse,
+}) {
+  const path = resolveDistributionFile(
+    distributionsRoot,
+    distributionId,
+    fileName,
+  );
+  const value = parse(JSON.parse(readFileSync(path, 'utf8')));
+  if (value.distributionId !== distributionId) {
+    throw new Error(
+      `${fileName} distributionId "${value.distributionId}" does not match requested distribution "${distributionId}"`,
+    );
+  }
+  return { path, value };
+}
+
+/**
+ * Every edition under `distributionsRoot`, sorted — DISCOVERED, never listed.
+ *
+ * An edition is a directory carrying `xema-distribution.json`; that file is
+ * what makes the directory an edition, so nothing else can be mistaken for one
+ * and a new edition needs no registration anywhere.
+ *
+ * Throws on an empty scan. A gate that iterates editions and finds none must
+ * fail rather than report success over nothing — the repeated defect in this
+ * tree is a check that reports green while executing nothing, and a literal
+ * id list is the other half of it: a narrowed list reads as coverage.
+ *
+ * `refresh-distribution-plane.mjs` carried this three-line scan privately;
+ * it lives here so the write path and the read paths cannot disagree about
+ * what an edition is.
+ */
+export function discoverDistributionIds(distributionsRoot) {
+  const root = realpathSync(distributionsRoot);
+  const ids = readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter((name) => existsSync(join(root, name, 'xema-distribution.json')))
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  if (ids.length === 0) {
+    throw new Error(
+      `found no edition under ${root} — an empty scan is not a result`,
+    );
+  }
+  return ids;
+}
+
+export function distributionOutputPath(
+  distributionsRoot,
+  distributionId,
+  fileName,
+) {
+  const { directory } = resolveDistributionDirectory(
+    distributionsRoot,
+    distributionId,
+  );
+  const path = resolve(directory, fileName);
+  assertContained(directory, path, `${fileName} output`);
+  if (existsSync(path) && realpathSync(path) !== path) {
+    throw new Error(
+      `${fileName} output for distribution "${distributionId}" must not be a symlink`,
+    );
+  }
+  return path;
+}
+
+/**
+ * The directory name holding editions that are NOT yet promoted.
+ *
+ * `discoverDistributionIds` is deliberately a single-level scan, so an edition
+ * one level down is invisible to it and to `dist:check` — which is the whole
+ * mechanism of the holding pen, not an oversight.
+ */
+export const PENDING_EDITIONS_DIRNAME = 'editions-pending-merge';
+
+/**
+ * Every edition under `distributionsRoot`, in BOTH tiers, as
+ * `{ id, directory, pending }` — sorted, promoted tier first.
+ *
+ * WHY BOTH TIERS. A generic test suite must be able to name its subjects
+ * without naming a customer, and a customer's edition is exactly the thing that
+ * is either pending here or has moved to a root of its own. Discovering both
+ * means one expression covers the edition wherever it currently sits, so
+ * promoting it — or removing it — changes no test.
+ *
+ * THE EMPTY CASES ARE ASYMMETRIC ON PURPOSE.
+ *
+ *   * The PROMOTED tier delegates to {@link discoverDistributionIds}, which
+ *     THROWS on an empty scan. An empty promoted tier means the root is wrong,
+ *     and a checker that iterated zero editions and reported success is this
+ *     tree's most-repeated defect.
+ *   * The PENDING tier may legitimately be empty — that is what a fully
+ *     promoted fleet looks like — so it is not an error. A CALLER that narrows
+ *     to a subset of these and finds nothing must say so out loud rather than
+ *     pass in silence; that reporting duty is the caller's, because only the
+ *     caller knows what it narrowed to.
+ */
+export function discoverEditionDirectories(distributionsRoot) {
+  const root = realpathSync(distributionsRoot);
+  const promoted = discoverDistributionIds(root).map((id) => ({
+    id,
+    directory: join(root, id),
+    pending: false,
+  }));
+  const pendingRoot = join(root, PENDING_EDITIONS_DIRNAME);
+  const pending = !existsSync(pendingRoot)
+    ? []
+    : readdirSync(pendingRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .filter((name) =>
+          existsSync(join(pendingRoot, name, 'xema-distribution.json')),
+        )
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+        .map((id) => ({ id, directory: join(pendingRoot, id), pending: true }));
+  return [...promoted, ...pending];
+}

package/edition/edition-artifact.mjs

@@ -0,0 +1,284 @@
+// edition-artifact — the files of an edition and where they may go.
+//
+// ONE layout for develop and release: an OCI artifact at
+// `<registry>/xema-edition-<id>`, 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 (develop: the snapshot hash; 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, 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,
+  EDITION_DESCRIPTOR_FILE,
+  EDITION_DESCRIPTOR_SCHEMA,
+  EDITION_LOCKS,
+  EDITION_REPOSITORY_PREFIX,
+  EditionChannel,
+  EditionLockFile,
+  EvidenceTrustState,
+} from './edition-constants.mjs';
+import { dataRoot, editionsRoot } from './edition-workspace.mjs';
+import { serializeJson } from './lib.mjs';
+import { snapshotHash, 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: what this artifact is, 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.
+ */
+export function editionDescriptor({ distributionId, channel, pins, workflow, evidenceTrustPolicy, engineImage }) {
+  assertCanonicalDistributionId(distributionId);
+  // Every writer of a descriptor passes here: no route writes a release
+  // edition that is not armed, whatever state its caller computed.
+  if (channel === EditionChannel.Release && evidenceTrustPolicy !== EvidenceTrustState.Armed) {
+    throw new Error(
+      `a release edition requires an armed evidence trust policy; "${distributionId}" was to be written ${JSON.stringify(evidenceTrustPolicy)}`,
+    );
+  }
+  return parseEditionDescriptor({
+    schema: EDITION_DESCRIPTOR_SCHEMA,
+    distributionId,
+    locks: [...EDITION_LOCKS],
+    provenance: {
+      channel,
+      pins: channel === EditionChannel.Develop ? sortedSnapshotPins(pins) : { ...pins },
+      workflow: { repository: workflow?.repository, runId: workflow?.runId },
+    },
+    evidenceTrustPolicy,
+    engine: { image: engineImage },
+  });
+}
+
+const COMMIT_PATTERN = /^[0-9a-f]{40}$/;
+const CATALOGUE_DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
+
+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 strict parse of a descriptor: exact keys, closed vocabularies, an engine image by digest. Returns it unchanged. */
+export function parseEditionDescriptor(value) {
+  exactKeys(value, ['schema', 'distributionId', 'locks', 'provenance', 'evidenceTrustPolicy', 'engine'], EDITION_DESCRIPTOR_FILE);
+  if (value.schema !== EDITION_DESCRIPTOR_SCHEMA) {
+    throw new Error(`${EDITION_DESCRIPTOR_FILE}: schema is ${JSON.stringify(value.schema)}, expected ${JSON.stringify(EDITION_DESCRIPTOR_SCHEMA)}`);
+  }
+  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 "${CATALOGUE_PIN_KEY}" pin to a sha256 digest)`);
+  }
+  for (const [key, pin] of Object.entries(pins)) {
+    const pattern = key === CATALOGUE_PIN_KEY ? CATALOGUE_DIGEST_PATTERN : COMMIT_PATTERN;
+    if (typeof pin !== 'string' || !pattern.test(pin)) {
+      throw new Error(
+        key === CATALOGUE_PIN_KEY
+          ? `${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)`,
+      );
+    }
+  }
+  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 (!Object.values(EvidenceTrustState).includes(value.evidenceTrustPolicy)) {
+    throw new Error(`${EDITION_DESCRIPTOR_FILE}: evidenceTrustPolicy must be one of ${Object.values(EvidenceTrustState).join(' | ')}`);
+  }
+  // The reader holds the writer's rule: a release edition that is not armed is
+  // not an edition this plane writes, so it is not one it reads.
+  if (value.provenance.channel === EditionChannel.Release && value.evidenceTrustPolicy !== EvidenceTrustState.Armed) {
+    throw new Error(
+      `${EDITION_DESCRIPTOR_FILE}: a release edition requires an armed evidence trust policy; "${value.distributionId}" records ${JSON.stringify(value.evidenceTrustPolicy)}`,
+    );
+  }
+  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._-]+)+$/;
+const TAG_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$/;
+
+/** The registry is the caller's namespace; the CLI appends `xema-edition-<id>` itself, so a registry already naming an edition repository is refused. */
+export function assertRegistry(registry) {
+  if (typeof registry !== 'string' || !REGISTRY_PATTERN.test(registry)) {
+    throw new Error(
+      `--registry ${JSON.stringify(registry)} is not <registry-host>[:port]/<namespace>[/...] (lowercase, e.g. registry.example.com/acme)`,
+    );
+  }
+  const last = registry.split('/').pop();
+  if (last.startsWith(EDITION_REPOSITORY_PREFIX)) {
+    throw new Error(
+      `--registry ${registry} ends in "${last}", which the CLI appends itself: ` +
+        `the repository would be ${registry}/${EDITION_REPOSITORY_PREFIX}<id>. Pass the namespace only`,
+    );
+  }
+}
+
+/** `<registry>/xema-edition-<id>`: the one repository of an edition, for either channel. */
+export function editionRepository(distributionId, registry) {
+  assertCanonicalDistributionId(distributionId);
+  assertRegistry(registry);
+  return `${registry}/${EDITION_REPOSITORY_PREFIX}${distributionId}`;
+}
+
+/** `<repository>:<tag>`; the tag is for humans, the artifact is addressed by its digest. */
+export function editionTarget(distributionId, registry, tag) {
+  if (typeof tag !== 'string' || !TAG_PATTERN.test(tag)) {
+    throw new Error(`tag ${JSON.stringify(tag)} is not an OCI tag`);
+  }
+  return `${editionRepository(distributionId, registry)}:${tag}`;
+}
+
+/** A develop edition's target: the tag is its snapshot hash. */
+export function developEditionTarget(distributionId, pins, { registry }) {
+  return editionTarget(distributionId, registry, snapshotHash(pins));
+}
+
+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 an 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, channel);
+  const descriptor = editionDescriptor({ 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 snapshot-hash tag is reused only if it IS this snapshot: the tag
+ * is a hash of the pins, 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. Throws naming the first difference.
+ */
+export function assertExistingArtifactMatches({ artifactDir, distributionId, channel, pins, engineImage, evidenceTrustPolicy }) {
+  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));
+  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 (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`);
+    }
+  }
+}

package/edition/edition-biome-manifests.mjs

@@ -0,0 +1,85 @@
+#!/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> --source-hash <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 {
+  WorkspaceRoot,
+  configureEditionWorkspaceFromArgv,
+  editionsRoot,
+  isEntryModule,
+} from './edition-workspace.mjs';
+import { loadKernelDistributionSchemas, serializeJson } from './lib.mjs';
+import { externalSourceTrees, sourceTreeLocator } from './resolve-images.mjs';
+import { committedRepositoryPins, 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> --source-hash <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: committedRepositoryPins() });
+  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.SourceHash,
+    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;
+  });
+}

package/edition/edition-channel.mjs

@@ -0,0 +1,6 @@
+// edition-channel — where an edition was produced. Its own module so the chart-set
+// validator (which a channel selects) and edition-constants (which imports the
+// chart-set file name) do not import each other.
+
+/** Where an edition was produced. Recorded in the descriptor's provenance; readers never branch on it. */
+export const EditionChannel = Object.freeze({ Develop: 'develop', Release: 'release' });

package/edition/edition-chart-set.mjs

@@ -0,0 +1,93 @@
+// edition-chart-set.mjs — every edition carries the chart generation it is
+// rendered with.
+//
+// Owner ruling, 2026-10-04: everything that affects a deployment's rendered
+// runtime manifest is selected by its sealed edition — image digests, the
+// authorization lock, AND the chart generation. Until then the chart set was one
+// fleet-wide pin (chart-set.lock.json at this repository's root) that no edition
+// carried, so xema-deploy rendered every deployment through whichever charts it
+// happened to hold, and an appliance sealed on 2026-09-27 was rendered with
+// charts that assume images built on 2026-10-01.
+//
+// So each edition directory holds `<id>/chart-set.lock.json`: a byte-identical
+// copy of the fleet pin AT THE MOMENT IT IS WRITTEN, with each publisher's
+// ROSTER (chart name → {version, digest}) read from the index, so a
+// consumer selects every chart without asking the registry. It is part of the
+// edition's file set (compute-edition-coordinates.sh), hashed into its
+// coordinate and published with it, and xema-deploy vendors it beside the other
+// halves.
+//
+// ONE FACT, STILL. The fleet pin stays the single answer to "which chart set do
+// editions take now"; resolve-chart-set.mjs is its one writer and writes every
+// edition's copy in the same run, and dist-check refuses a copy that is missing
+// or differs from the pin. N copies of one fact cannot disagree when one writer
+// writes them all and a check refuses any that does.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { EditionChannel } from './edition-channel.mjs';
+import { dataRoot } from './edition-workspace.mjs';
+
+export const EDITION_CHART_SET_FILE = 'chart-set.lock.json';
+/** The fleet pin: this repository's root chart-set.lock.json, beside this file in every layout. */
+export const fleetChartSetLockPath = () => join(dataRoot(), EDITION_CHART_SET_FILE);
+
+export const EditionChartSetCheck = Object.freeze({
+  GREEN: 'green',
+  MISSING: 'missing',
+  STALE: 'stale',
+});
+
+/**
+ * A published chart's version coordinate, per channel: `-h<16 hex>` (content
+ * hash) in a release chart set, `-dev.<12 hex>` (the frozen xema-deploy SHA) in a
+ * develop one. One lock SHAPE serves both; the coordinate is what the producer
+ * of each channel writes, so each producer validates its own channel's (this is
+ * a check of what is being written, not a branch of any reader).
+ */
+const CHART_VERSION_COORDINATE = Object.freeze({
+  [EditionChannel.Release]: /-h[0-9a-f]{16}$/,
+  [EditionChannel.Develop]: /-dev\.[0-9a-f]{12}$/,
+});
+
+/** A chart-set lock (schemaVersion 3) that pins every member by version and OCI manifest digest, with `channel`'s version coordinate. */
+export function assertRosteredChartSetLock(lock, label, channel) {
+  const coordinate = CHART_VERSION_COORDINATE[channel];
+  if (coordinate === undefined) {
+    throw new Error(`${label}: cannot validate a chart-set lock for channel ${JSON.stringify(channel)}; expected ${Object.values(EditionChannel).join(' | ')}`);
+  }
+  const fail = (why) => {
+    throw new Error(`${label} is not a rostered chart-set lock: ${why}`);
+  };
+  if (lock?.schemaVersion !== 3) {fail('schemaVersion must be 3');}
+  if (!Array.isArray(lock.publishers) || lock.publishers.length === 0) {fail('publishers must be a non-empty array');}
+  for (const pin of lock.publishers) {
+    if (!pin?.charts || typeof pin.charts !== 'object' || Array.isArray(pin.charts) || Object.keys(pin.charts).length === 0) {
+      fail(`${pin?.index ?? '?'} carries no roster (charts: name -> member version) — run resolve-chart-set.mjs`);
+    }
+    for (const [name, member] of Object.entries(pin.charts)) {
+      if (!member || typeof member !== 'object' || Array.isArray(member)) {fail(`${pin.index}: ${name} must be {version, digest}`);}
+      if (!coordinate.test(String(member.version))) {fail(`${pin.index}: ${name} has no ${channel} content coordinate (${member.version}); a ${channel} chart set carries ${coordinate}`);}
+      if (!/^sha256:[a-f0-9]{64}$/.test(String(member.digest))) {fail(`${pin.index}: ${name} has no sha256 manifest digest`);}
+    }
+  }
+  return lock;
+}
+
+/**
+ * Write the RELEASE edition's copy of the fleet pin — byte-identical to
+ * `pinText`. Only a rostered pin (schemaVersion 3) with release chart
+ * coordinates is written.
+ */
+export function writeEditionChartSet(editionDir, pinText) {
+  assertRosteredChartSetLock(JSON.parse(pinText), EDITION_CHART_SET_FILE, EditionChannel.Release);
+  writeFileSync(join(editionDir, EDITION_CHART_SET_FILE), pinText);
+}
+
+/** Does the edition carry the fleet pin, byte for byte? */
+export function checkEditionChartSet(editionDir, pinText) {
+  const file = join(editionDir, EDITION_CHART_SET_FILE);
+  if (!existsSync(file)) {return EditionChartSetCheck.MISSING;}
+  return readFileSync(file, 'utf8') === pinText ? EditionChartSetCheck.GREEN : EditionChartSetCheck.STALE;
+}