@xemahq/xema 0.59.1 → 0.60.1

package/edition/edition-ceiling.mjs

@@ -1,180 +0,0 @@
-#!/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 { 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, {
-    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

@@ -1,20 +0,0 @@
-// 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] };
-}

package/edition/edition-chart-set.mjs

@@ -1,104 +0,0 @@
-// 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;
-}