@xemahq/edition-tooling 0.0.0-stage → 0.1.1

package/edition/edition-ceiling.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+// `xema-edition ceiling`: the biomes a dev deployment may run, resolved at one distributions commit.
+//
+// usage: xema-edition ceiling --distribution <id> --at <distributions sha> --producer-commit <owner/repo>=<sha> [...]
+//   --data-root <dir> --sources-root <dir> --kernel <dir>
+//
+// stdout: a `DevelopCeilingSchema` document (`@xemahq/contracts/develop-ceiling`): schema, distributionsCommit,
+// distributionId and biomes sorted by id, each { id, origin, version, repo, services, runtimeComponents,
+// serviceProcessFacts, trustCeiling? }. No images and no seal.
+//
+// THE SELECTION is the distribution definition `<id>/xema-distribution.json` and the committed `biome-index.json`
+// and `platform-service-index.json`, all read from the data root (the distributions checkout) AT `--at`, resolved
+// by the release resolver itself (`composeManifest` + `resolveDistributionWithIndex`): id, origin, repo and
+// trustCeiling of each biome are the resolution's, never re-derived here.
+//
+// THE PROCESS FACTS (version, services, runtimeComponents, serviceProcessFacts) are the producer's own: its
+// `xema-biome.json` and generated `xema-biome.index.json` AT the producer commit given by `--producer-commit`,
+// projected by `manifestToIndexEntry`, the function that builds `biome-index.json`. A service new on the
+// producer's develop inside a selected biome is admitted; a biome the selection does not name is never read.
+// A selected biome whose producer has no stated commit, or whose manifest is absent at that commit, is refused:
+// there is no fallback to the committed index's facts.
+
+import { DevelopCeilingSchema } from '@xemahq/contracts/develop-ceiling';
+
+import { canonicalPublicHttpsRepositoryUrl, repositoryOwnerName } from './canonical-repository-url.mjs';
+import { developGraphMembers } from './develop-graph.mjs';
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import { EditionChannel } from './edition-channel.mjs';
+import { WorkspaceRoot, configureEditionWorkspaceFromArgv, dataRoot, isEntryModule, sourcePath } from './edition-workspace.mjs';
+import { readGitJsonAtCommit } from './git-json.mjs';
+import {
+  BIOME_GENERATED_INDEX_FILENAME,
+  compareStrings,
+  loadKernelDistributionSchemas,
+  manifestToIndexEntry,
+  serializeJson,
+} from './lib.mjs';
+import { composeManifest, lockedServiceProcessFacts, parseEditionManifest, resolveDistributionWithIndex } from './resolve-distribution.mjs';
+
+const USAGE =
+  'usage: xema-edition ceiling --distribution <id> --at <distributions sha> --producer-commit <owner/repo>=<sha> [--producer-commit ...] --data-root <dir> --sources-root <dir> --kernel <dir>';
+const GIT_COMMIT = /^[0-9a-f]{40}$/;
+const PRODUCER_COMMIT = /^([A-Za-z0-9._-]+\/[A-Za-z0-9._-]+)=([0-9a-f]{40})$/;
+const MANIFEST_FILE = 'xema-biome.json';
+
+/** The ceiling named a producer or a commit this verb cannot read: nothing is guessed. */
+export class CeilingRefused extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CeilingRefused';
+  }
+}
+
+/** `owner/name` -> the sources-root handle (`repos/<name>`) of the first-party repository it is, per the develop graph. */
+function producersByHandle(members) {
+  return new Map(
+    members.map(({ repo, repositoryUrl }) => [
+      repo,
+      repositoryOwnerName(canonicalPublicHttpsRepositoryUrl(repositoryUrl, `firstPartySources["${repo}"].repositoryUrl`), `firstPartySources["${repo}"].repositoryUrl`),
+    ]),
+  );
+}
+
+/** One selected biome's facts, read from its producer's manifest and ledger at the producer commit. */
+async function producerFacts({ selected, producer, commit, repoDir }) {
+  const manifestDirectory = selected.path.slice(`${selected.repo}/`.length);
+  const manifestPath = `${manifestDirectory}/${MANIFEST_FILE}`;
+  const ledgerPath = `${manifestDirectory}/${BIOME_GENERATED_INDEX_FILENAME}`;
+  const rel = `${producer}/${manifestPath}`;
+  let raw;
+  let generatedIndex;
+  try {
+    raw = readGitJsonAtCommit(repoDir, manifestPath, commit);
+    generatedIndex = readGitJsonAtCommit(repoDir, ledgerPath, commit);
+  } catch (error) {
+    throw new CeilingRefused(`biome "${selected.id}": ${rel} or its ${BIOME_GENERATED_INDEX_FILENAME} cannot be read at ${producer}@${commit}: ${error.message}`);
+  }
+  const entry = await manifestToIndexEntry({ raw, generatedIndex, rel, repo: selected.repo, path: selected.path });
+  if (entry.id !== selected.id) {
+    throw new CeilingRefused(`${rel} at ${commit} declares biome "${entry.id}", but the selection names "${selected.id}" there`);
+  }
+  return entry;
+}
+
+/**
+ * @param {object} request
+ * @param {string} request.distributionId
+ * @param {string} request.distributionsCommit 40-hex commit of the data root checkout
+ * @param {ReadonlyMap<string, string>} request.producerCommits `owner/repo` -> the commit its facts are read at
+ * @param {object} request.schemas the kernel's distribution exports
+ * @returns {Promise<object>} the validated ceiling
+ */
+export async function composeCeiling({ distributionId, distributionsCommit, producerCommits, schemas }) {
+  assertCanonicalDistributionId(distributionId);
+  if (!GIT_COMMIT.test(distributionsCommit)) {throw new Error(`--at must be a 40-hex commit; got ${JSON.stringify(distributionsCommit)}`);}
+  const read = (path) => readGitJsonAtCommit(dataRoot(), path, distributionsCommit);
+  const manifest = parseEditionManifest(schemas.parseDistribution, distributionId, read(`${distributionId}/xema-distribution.json`), `${distributionsCommit}:${distributionId}/xema-distribution.json`);
+  const composed = composeManifest(manifest);
+  if (composed.declaredSources.length > 0) {
+    throw new CeilingRefused(`distribution "${distributionId}" declares external sources[]; a ceiling is resolved from the committed indexes alone`);
+  }
+  const { lock } = await resolveDistributionWithIndex(distributionId, {
+    channel: EditionChannel.Release,
+    inputs: {
+      composed,
+      biomeIndex: read('biome-index.json'),
+      platformServiceIndex: read('platform-service-index.json'),
+      sourcesAvailable: false,
+      storePublisherTrust: undefined,
+    },
+  });
+  const producers = producersByHandle(developGraphMembers());
+  const biomes = [];
+  for (const selected of lock.biomes) {
+    const producer = producers.get(selected.repo);
+    if (producer === undefined) {
+      throw new CeilingRefused(`biome "${selected.id}" is selected from "${selected.repo}", which is not a first-party repository of the develop graph`);
+    }
+    const commit = producerCommits.get(producer);
+    if (commit === undefined) {
+      throw new CeilingRefused(`biome "${selected.id}" is selected from ${producer}, but no --producer-commit states the commit its facts are read at`);
+    }
+    const entry = await producerFacts({ selected, producer, commit, repoDir: sourcePath(selected.repo) });
+    biomes.push({
+      id: selected.id,
+      origin: selected.origin,
+      version: entry.version,
+      repo: selected.repo,
+      services: entry.services,
+      runtimeComponents: entry.runtimeComponents,
+      serviceProcessFacts: lockedServiceProcessFacts(entry),
+      ...(selected.trustCeiling === undefined ? {} : { trustCeiling: selected.trustCeiling }),
+    });
+  }
+  biomes.sort((a, b) => compareStrings(a.id, b.id));
+  return DevelopCeilingSchema.parse({ schema: 1, distributionsCommit, distributionId, biomes });
+}
+
+/** `--distribution`, `--at` and the repeatable `--producer-commit <owner/repo>=<sha>` of the argv left after the root flags. */
+export function parseCeilingArgs(argv) {
+  const options = { producerCommits: new Map() };
+  for (let i = 0; i < argv.length; i += 2) {
+    const flag = argv[i];
+    const value = argv[i + 1];
+    if (value === undefined || (value.startsWith('--') && value.length > 2)) {throw new Error(`${flag} requires a value\n${USAGE}`);}
+    if (flag === '--producer-commit') {
+      const match = PRODUCER_COMMIT.exec(value);
+      if (match === null) {throw new Error(`--producer-commit must be <owner/repo>=<40-hex commit>; got ${JSON.stringify(value)}`);}
+      if (options.producerCommits.has(match[1])) {throw new Error(`--producer-commit given twice for ${match[1]}`);}
+      options.producerCommits.set(match[1], match[2]);
+    } else if (flag === '--distribution' || flag === '--at') {
+      const key = flag.slice(2);
+      if (options[key] !== undefined) {throw new Error(`${flag} given twice`);}
+      options[key] = value;
+    } else {
+      throw new Error(`unknown argument ${flag}\n${USAGE}`);
+    }
+  }
+  for (const required of ['distribution', 'at']) {
+    if (options[required] === undefined) {throw new Error(`--${required} is required\n${USAGE}`);}
+  }
+  return options;
+}
+
+async function main() {
+  const rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), [WorkspaceRoot.Data, WorkspaceRoot.Sources, WorkspaceRoot.Kernel]);
+  const options = parseCeilingArgs(rest);
+  const ceiling = await composeCeiling({
+    distributionId: options.distribution,
+    distributionsCommit: options.at,
+    producerCommits: options.producerCommits,
+    schemas: await loadKernelDistributionSchemas(),
+  });
+  process.stdout.write(serializeJson(ceiling));
+}
+
+if (isEntryModule(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`[edition-ceiling] ${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/edition/edition-channel.mjs

@@ -0,0 +1,27 @@
+// 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. verify-evidence selects its policy row by the
+ * descriptor's channel (a predicate channel mismatch is still refused after the signature check); lock readers require one.
+ */
+export const EditionChannel = Object.freeze({ Develop: 'develop', Release: 'release' });
+
+/**
+ * The channel of `--channel <channel>`, which must be all of `rest`; anything
+ * else is a usage error. Shared by every verb that operates on one channel.
+ */
+export function parseChannelArgs(rest) {
+  if (rest.length !== 2 || rest[0] !== '--channel' || !Object.values(EditionChannel).includes(rest[1])) {
+    throw new Error(`--channel <${Object.values(EditionChannel).join('|')}> is required and nothing else is accepted (got ${rest.length === 0 ? 'nothing' : JSON.stringify(rest.join(' '))})`);
+  }
+  return { channel: rest[1] };
+}
+
+/** `channel` is a stated `EditionChannel`; an internal function that needs a lane never defaults one. */
+export function assertEditionChannel(channel) {
+  if (!Object.values(EditionChannel).includes(channel)) {
+    throw new Error(`an edition channel (${Object.values(EditionChannel).join('|')}) is required, got ${JSON.stringify(channel)}`);
+  }
+}

package/edition/edition-chart-set.mjs

@@ -0,0 +1,104 @@
+// 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, and the index chart's own manifest digest (`indexDigest`), 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 { 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: `-h<16 hex>`, the content hash its publisher mints, on both channels (develop: `0.0.0-h<16 hex>`). */
+const CHART_VERSION_COORDINATE = /-h[0-9a-f]{16}$/;
+
+/** The chart-set lock schema every reader accepts; a lock of any other schema is re-resolved, never migrated. */
+export const CHART_SET_LOCK_SCHEMA_VERSION = 4;
+
+/** An OCI manifest digest: `sha256:` and 64 lowercase hex. */
+export const OCI_DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
+
+/** The instruction every refusal of an outdated lock carries. */
+export const RESOLVE_CHART_SET_INSTRUCTION = 're-resolve the chart set with `xema-edition chart-set resolve`';
+
+/**
+ * A chart-set lock (schemaVersion 4) that pins every member by version and OCI
+ * manifest digest, with the `-h<16 hex>` content coordinate, and pins each
+ * publisher's index chart by `indexDigest` (always a sha256 digest).
+ */
+export function assertRosteredChartSetLock(lock, label) {
+  const fail = (why) => {
+    throw new Error(`${label} is not a rostered chart-set lock: ${why}`);
+  };
+  if (lock?.schemaVersion !== CHART_SET_LOCK_SCHEMA_VERSION) {
+    fail(`schemaVersion must be ${CHART_SET_LOCK_SCHEMA_VERSION} (got ${JSON.stringify(lock?.schemaVersion)}); ${RESOLVE_CHART_SET_INSTRUCTION}`);
+  }
+  if (!Array.isArray(lock.publishers) || lock.publishers.length === 0) {fail('publishers must be a non-empty array');}
+  for (const [position, pin] of lock.publishers.entries()) {
+    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 (!CHART_VERSION_COORDINATE.test(String(member.version))) {fail(`${pin.index}: ${name} has no content coordinate (${member.version}); a chart set carries ${CHART_VERSION_COORDINATE}`);}
+      if (!OCI_DIGEST_PATTERN.test(String(member.digest))) {fail(`${pin.index}: ${name} has no sha256 manifest digest`);}
+    }
+    assertIndexDigest(pin, position, fail);
+  }
+  return lock;
+}
+
+/** The `indexDigest` rule: the key is present and is a sha256 digest. */
+function assertIndexDigest(pin, position, fail) {
+  const where = `publisher ${position} (${pin?.index ?? '?'})`;
+  if (!pin || typeof pin !== 'object' || !Object.hasOwn(pin, 'indexDigest')) {
+    fail(`${where} carries no indexDigest key (required: "sha256:<64 hex>")`);
+  }
+  if (!OCI_DIGEST_PATTERN.test(String(pin.indexDigest))) {fail(`${where} has a malformed indexDigest (${JSON.stringify(pin.indexDigest)}); expected "sha256:<64 lowercase hex>"`);}
+}
+
+/**
+ * Write the RELEASE edition's copy of the fleet pin — byte-identical to
+ * `pinText`. Only a rostered pin (schemaVersion 4) with release chart
+ * coordinates is written.
+ */
+export function writeEditionChartSet(editionDir, pinText) {
+  assertRosteredChartSetLock(JSON.parse(pinText), EDITION_CHART_SET_FILE);
+  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;
+}