@xemahq/xema 0.59.0 → 0.60.1

package/edition/develop-snapshot-inputs.mjs

@@ -1,93 +0,0 @@
-// develop-snapshot-inputs — every input of a DEVELOP edition's resolve, built
-// from ONE frozen snapshot of pins and nothing else.
-//
-// The release resolvers read their inputs from committed files: the platform
-// service index, the biome index, the runtime image source index and the
-// edition chain. A develop edition has no committed copy of any of them at its
-// pins, so each is REBUILT here by the release builder itself, over a pinned
-// source authority whose pins are the snapshot's. There is no second builder:
-// the same functions that regenerate the committed indexes produce the
-// snapshot's, and they are handed to the release resolvers as injected inputs
-// (`resolveDistributionWithIndex(id, { inputs })`, `resolveImages(id, { inputs,
-// lock })`). A snapshot whose pins equal the committed ones therefore resolves
-// to the committed locks, which `develop-snapshot-inputs.test.mjs` proves.
-//
-// No fallback: the authority has no delegate, so a repository the snapshot does
-// not pin refuses by name instead of resolving to a branch tip.
-
-import { execFileSync } from 'node:child_process';
-
-import { RefusalError } from './collected-refusals.mjs';
-import { dataRoot, deployRoot, editionsRoot, kernelRepoDir, runtimeImageSourceIndexPath } from './edition-workspace.mjs';
-import { buildIndexesAtPins } from './indexes-at-pins.mjs';
-import {
-  dataPinKey,
-  EDITIONS_ROOT_PIN_KEY,
-  kernelPinKey,
-  deployPinKey,
-  applyPinSource,
-  snapshotPinSource,
-  validateSnapshotPins,
-} from './pin-source.mjs';
-import { composeEdition } from './resolve-distribution.mjs';
-import { readStrictJsonFile } from './strict-json.mjs';
-
-function git(dir, args) {
-  return execFileSync('git', ['-C', dir, ...args], {
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-  }).trim();
-}
-
-/**
- * A checkout the resolve reads must BE the frozen commit and be clean: the vendor
- * tree is walked for parents and runs the builders, the editions root holds the
- * edition and its adopted authorization lock.
- */
-export function assertFrozenCheckout({ dir, pins, key }) {
-  const pinned = pins[key];
-  if (pinned === undefined) {throw new RefusalError(`the snapshot has no pin "${key}" for ${dir}`);}
-  const head = git(dir, ['rev-parse', 'HEAD']);
-  if (head !== pinned) {
-    throw new RefusalError(`${dir} is at ${head}, but the snapshot pins "${key}" at ${pinned}`);
-  }
-  const dirty = git(dir, ['status', '--porcelain']);
-  if (dirty.length > 0) {
-    throw new RefusalError(`${dir} is not clean, so it is not the frozen commit ${pinned} ("${key}"):\n${dirty}`);
-  }
-}
-
-/**
- * Every checkout a develop resolve reads: the vendor tree, the kernel the
- * authorization lock is sealed with, the chart tree the chart-set lock digests,
- * and the editions root when it is another repository.
- */
-export function assertFrozenCheckouts(pins) {
-  assertFrozenCheckout({ dir: dataRoot(), pins, key: dataPinKey() });
-  assertFrozenCheckout({ dir: kernelRepoDir(), pins, key: kernelPinKey() });
-  assertFrozenCheckout({ dir: deployRoot(), pins, key: deployPinKey() });
-  if (editionsRoot() !== dataRoot()) {
-    assertFrozenCheckout({ dir: editionsRoot(), pins, key: EDITIONS_ROOT_PIN_KEY });
-  }
-}
-
-/**
- * @param {{ id: string, pins: Record<string,string>, schemas: object }} request
- * @returns the injected inputs for the release resolvers, plus the pin source.
- */
-export async function buildSnapshotInputs({ id, pins, schemas }) {
-  const pinSource = snapshotPinSource(pins);
-  const composed = composeEdition(schemas.parseDistribution, id, pinSource);
-  const committedIndex = schemas.parseRuntimeImageSourceIndex(
-    readStrictJsonFile(runtimeImageSourceIndexPath()),
-  );
-  validateSnapshotPins(pins, {
-    declaredSourceNames: composed.declaredSourceNames,
-    editionsRootExternal: editionsRoot() !== dataRoot(),
-  });
-  const { platformServiceIndex, biomeIndex, runtimeImageSourceIndex } = await buildIndexesAtPins({
-    schemas,
-    repositoryPins: applyPinSource(committedIndex, pinSource).repositoryPins,
-  });
-  return { pinSource, composed, platformServiceIndex, biomeIndex, runtimeImageSourceIndex };
-}

package/edition/develop-verify-image-record.mjs

@@ -1,109 +0,0 @@
-// develop-verify-image-record — the body of `xema edition develop verify-image-record`.
-//
-// Does an authenticated build record bind this image digest to this producer? The producer's records of the
-// develop branch are read newest run first and each is verified by the shared core (`develop-record-verify.mjs`:
-// cosign keyless identity of the data root's record workflow, caller repository = the producer, ref, workflow
-// sha = the record's commit, and the record's producer repository = the producer). Only a record produced by the
-// producer's own CI workflow (`.github/workflows/ci.yaml`) can name the images it serves: a verified record of
-// another workflow is skipped, and the answer is the newest ci.yaml record that lists the exact `name@digest`.
-//
-// Deterministic: `listBuildRecordRuns` (develop-record-verify.mjs:205) sorts the tags by the kernel's
-// `compareBuildRecordRuns` (build-record.ts:218-228: run number, then attempt), highest first, and the first
-// match wins; a record that fails verification refuses the call before any older one is read.
-//
-// The returned `commit` is the commit of the newest verified ci.yaml record (by run number, then attempt) that lists
-// the digest. That can be an older commit when a later run targeted it (a manual ci.yaml run on an older commit gets a
-// higher run number), and for an image the producer REUSED by content hash it is NOT the commit that built the image.
-// This is safe because the digest is what binds the bytes: every ci.yaml record lists every image served at its commit,
-// built or reused, so the record names the running digest without a rebuild.
-//
-// Every refusal is a `RecordRefused` naming the producer: no ci.yaml record lists the image, the record names
-// another producer, or cosign refuses the identity. A registry or cosign that could not answer is a plain Error.
-// On success it prints `{image, digest, producer, commit}`.
-
-import {
-  cosignEnvironment,
-  listBuildRecordRuns,
-  loadVerifiedRecord,
-  withRecordVerifier,
-} from './develop-record-verify.mjs';
-import { serializeJson } from './lib.mjs';
-import { RecordRefused } from './record-refused.mjs';
-
-/** The only branch with a declared record signer. */
-export const VERIFY_IMAGE_RECORD_BRANCH = 'develop';
-/** The only workflow whose records name a producer's served images. */
-export const PRODUCER_IMAGE_WORKFLOW = '.github/workflows/ci.yaml';
-
-const IMAGE_REFERENCE = /^([^@\s]+)@(sha256:[0-9a-f]{64})$/;
-const PRODUCER_REPOSITORY = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
-
-/** `name@sha256:<64 hex>` split into its name and digest; anything else is refused. */
-export function parseImageReference(image) {
-  const match = IMAGE_REFERENCE.exec(image);
-  if (match === null) {throw new Error(`--image must be <name>@sha256:<64 hex digest>; got ${JSON.stringify(image)}`);}
-  return { name: match[1], digest: match[2] };
-}
-
-/** The producer member the records are read for: its repository `owner/name` and the URL the signer constrains. */
-function producerMember(producer) {
-  if (!PRODUCER_REPOSITORY.test(producer)) {throw new Error(`--producer must be <owner>/<repo>; got ${JSON.stringify(producer)}`);}
-  return { repo: producer, repositoryUrl: `https://github.com/${producer}.git` };
-}
-
-/**
- * @param {object} request
- * @param {string} request.image `<name>@sha256:<digest>`
- * @param {string} request.producer `<owner>/<repo>`
- * @param {string} request.registry the registry root that holds `build-records/<repo>`
- * @returns {Promise<{image: string, digest: string, producer: string, commit: string}>}
- */
-export async function verifyImageRecord({ image, producer, ...verifier }) {
-  const { name, digest } = parseImageReference(image);
-  const record = await findVerifiedProducerImageRecord({
-    producer,
-    ...verifier,
-    wanted: `lists ${name}@${digest}`,
-    matches: (candidate) => candidate.images.some((listed) => listed.name === name && listed.digest === digest),
-  });
-  return { image: name, digest, producer, commit: record.commit };
-}
-
-/**
- * The newest verified develop ci.yaml record of `producer` (newest run first) for which `matches(record)` holds.
- * Every record read on the way is cosign-verified, so a newer bad record refuses before an older one is read.
- * Refused, naming `wanted`, when no verified ci.yaml record matches.
- *
- * @param {object} request
- * @param {string} request.producer `<owner>/<repo>`
- * @param {(record: object) => boolean} request.matches
- * @param {string} request.wanted what a match is, for the refusal ("lists <name>@<digest>")
- */
-export async function findVerifiedProducerImageRecord({ producer, matches, wanted, registry, dataRootRepositoryUrl, kernel, clientFor, runCosign, cosignEnvFor, trustedRootPath }) {
-  const member = producerMember(producer);
-  const branch = VERIFY_IMAGE_RECORD_BRANCH;
-  const { repository, authority, client, runs } = await listBuildRecordRuns({ kernel, clientFor, registry, member, branch });
-  for (const { tag } of runs) {
-    const { record } = await loadVerifiedRecord({
-      kernel, client, runCosign, cosignEnv: cosignEnvironment(cosignEnvFor, authority), trustedRootPath,
-      repository, member, branch, dataRootRepositoryUrl, tag,
-    });
-    if (record.producer.workflow !== PRODUCER_IMAGE_WORKFLOW) {continue;}
-    if (matches(record)) {return record;}
-  }
-  throw new RecordRefused(producer, `no verified ${PRODUCER_IMAGE_WORKFLOW} build record of ${repository} for branch ${branch} ${wanted}`);
-}
-
-/** The `verify-image-record` verb. */
-export async function runVerifyImageRecord({ options, env = process.env, write = (text) => process.stdout.write(text), ...verifierInjections }) {
-  return withRecordVerifier({ cosignBinary: options['--cosign'], env, ...verifierInjections }, async (verifier) => {
-    const verified = await verifyImageRecord({
-      image: options['--image'],
-      producer: options['--producer'],
-      registry: options['--registry'],
-      ...verifier,
-    });
-    write(serializeJson(verified));
-    return verified;
-  });
-}

package/edition/dispatched-runtime-components.mjs

@@ -1,172 +0,0 @@
-import { compareStrings } from './string-order.mjs';
-
-/** A `runtime-image` edge target that is neither `{biomeId, componentKey}` nor `{supplementalRuntimeComponentId}`, or is both. */
-export class DispatchedEdgeError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = 'DispatchedEdgeError';
-  }
-}
-
-/** A dispatched `supplemental:<id>` the runtime-image source index does not declare as a supplemental subject. */
-export class UndeclaredSupplementalRuntimeComponentError extends Error {
-  constructor(supplementalRuntimeComponentId, dispatchingBiomes, context) {
-    super(
-      `${context}: supplemental runtime component "${supplementalRuntimeComponentId}", dispatched by biome ` +
-        `${dispatchingBiomes.map((id) => `"${id}"`).join(', ')}, is not declared as a runtime-component subject ` +
-        'by the runtime image source index — refusing rather than shipping the dispatcher without the image it launches.',
-    );
-    this.name = 'UndeclaredSupplementalRuntimeComponentError';
-    this.supplementalRuntimeComponentId = supplementalRuntimeComponentId;
-    this.dispatchingBiomes = dispatchingBiomes;
-  }
-}
-
-// The `supplementalRuntimeComponentId` field is read as plain data. Since edition
-// protocol v10 the kernel types it (`DispatchedRuntimeComponentSchema`, a union of
-// two strict objects); this projection keeps reading it as data and refuses a target
-// that is neither form, or both.
-const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0;
-
-/** True for the supplemental form of a projected edge. */
-export const isSupplementalEdge = (edge) => edge.supplementalRuntimeComponentId !== undefined;
-
-/** The identity of a projected edge: `supplemental:<id>` or `<biomeId>\0<componentKey>`. */
-export const dispatchedEdgeIdentity = (edge) =>
-  isSupplementalEdge(edge)
-    ? `supplemental:${edge.supplementalRuntimeComponentId}`
-    : `${edge.biomeId}\0${edge.componentKey}`;
-
-/**
- * Project one generated-index `runtime-image` edge target into the typed union
- * the index entry carries. A target that is neither form, or both, is refused
- * naming the dispatching biome; no `undefined` identity can form.
- */
-export function projectDispatchedTarget(dispatchingBiomeId, target) {
-  const supplemental = target?.supplementalRuntimeComponentId;
-  const biomeForm = target?.biomeId !== undefined || target?.componentKey !== undefined;
-  if (supplemental !== undefined) {
-    if (biomeForm || !isNonEmptyString(supplemental)) {
-      throw new DispatchedEdgeError(
-        `biome "${dispatchingBiomeId}" has a runtime-image edge target that mixes supplementalRuntimeComponentId with ` +
-          'biomeId/componentKey, or names an empty id — a target is exactly one form',
-      );
-    }
-    return { supplementalRuntimeComponentId: supplemental };
-  }
-  if (!isNonEmptyString(target?.biomeId) || !isNonEmptyString(target?.componentKey)) {
-    throw new DispatchedEdgeError(
-      `biome "${dispatchingBiomeId}" has a runtime-image edge target that is neither { biomeId, componentKey } nor ` +
-        '{ supplementalRuntimeComponentId }',
-    );
-  }
-  return { biomeId: target.biomeId, componentKey: target.componentKey };
-}
-
-const edgeLabel = (edge) =>
-  isSupplementalEdge(edge) ? `supplemental:${edge.supplementalRuntimeComponentId}` : `${edge.biomeId}/${edge.componentKey}`;
-
-/**
- * The runtime components an edition must carry because a biome it rosters
- * DISPATCHES them: the kernel's `runtime-image` edges, projected per biome into
- * the index as `dispatchesRuntimeComponents` and followed here against the
- * index entry of each target biome.
- *
- * "Needs that image" and nothing else. The target biome is NOT rostered — it is
- * not installed, booted or required — only its runtime component's image
- * enters the edition, as a runtime-component row of the image lock.
- *
- * The closure is one step by construction: the kernel admits
- * `dispatchesRuntimeComponents` on a `service` component only, and a target is
- * a runtime component, which is never a standing service — so a dispatched
- * image dispatches nothing further, and an unrostered target biome's own
- * services (and their edges) are not in the edition at all.
- *
- * Targets are resolved against FIRST-PARTY server entries only: the image plane
- * reads a target's coordinates from the first-party biome index, which carries
- * no biome drawn from a declared source. A biome drawn from a declared source
- * that dispatches is refused for the same reason.
- *
- * A supplemental edge (`{supplementalRuntimeComponentId}`) names no biome: it
- * is carried as a row `{ supplementalRuntimeComponentId, consumers }` without
- * a biome lookup.
- *
- * Returns one row per distinct (target biome, component key), sorted, with the
- * rostered biomes that dispatch it. Every unresolvable edge is refused, naming
- * the consumer and the target.
- *
- * @param {string} context  the edition the refusal names, e.g. `distribution "appliance-base"`
- * @param {object[]} consumers  the rostered index entries
- * @param {object[]} index  the index the targets are resolved against
- */
-export function resolveDispatchedRuntimeComponents(context, consumers, index) {
-  const rows = new Map();
-  for (const consumer of [...consumers].sort((a, b) => compareStrings(a.id, b.id))) {
-    const edges = consumer.dispatchesRuntimeComponents ?? [];
-    if (edges.length === 0) {continue;}
-    if (consumer.source !== undefined) {
-      throw new Error(
-        `${context}: biome "${consumer.id}", drawn from declared source "${consumer.source}", dispatches ` +
-          `runtime components (${edges.map(edgeLabel).join(', ')}). ` +
-          'A dispatched image is resolved from the first-party biome index, which carries no biome from a ' +
-          'declared source — refusing rather than shipping the dispatcher without the images it launches.',
-      );
-    }
-    for (const edge of edges) {
-      if (isSupplementalEdge(edge)) {
-        // Carried as a requirement owned by the dispatching biome. Whether the
-        // runtime image source index declares it is the image plane's refusal.
-        const supplementalKey = dispatchedEdgeIdentity(edge);
-        const row = rows.get(supplementalKey) ?? {
-          supplementalRuntimeComponentId: edge.supplementalRuntimeComponentId,
-          consumers: [],
-        };
-        if (!row.consumers.includes(consumer.id)) {row.consumers.push(consumer.id);}
-        rows.set(supplementalKey, row);
-        continue;
-      }
-      const edgeText = `biome "${consumer.id}" dispatches runtime component "${edge.componentKey}" of biome "${edge.biomeId}"`;
-      const candidates = index.filter(
-        (entry) => entry.id === edge.biomeId && entry.target === 'server' && entry.source === undefined,
-      );
-      if (candidates.length === 0) {
-        throw new Error(
-          `${context}: ${edgeText}, but the biome index has no first-party server biome "${edge.biomeId}" — ` +
-            'refusing rather than shipping the dispatcher without the image it launches.',
-        );
-      }
-      if (candidates.length > 1) {
-        throw new Error(
-          `${context}: ${edgeText}, but the biome index has ${candidates.length} first-party server biomes ` +
-            `"${edge.biomeId}" (${candidates.map((entry) => entry.repo).join(', ')}), so the target is ambiguous.`,
-        );
-      }
-      const [target] = candidates;
-      const image = (target.runtimeComponentKeys ?? {})[edge.componentKey];
-      if (image === undefined) {
-        const keys = Object.keys(target.runtimeComponentKeys ?? {});
-        throw new Error(
-          `${context}: ${edgeText}, but "${edge.biomeId}" declares no runtime component keyed ` +
-            `"${edge.componentKey}" (its runtime components: ${keys.length > 0 ? keys.join(', ') : 'none'}). ` +
-            'Either no component has that key, or it is a standing service or worker — a dispatched ' +
-            'component must be one its own biome never schedules.',
-        );
-      }
-      const key = `${target.id}\0${edge.componentKey}`;
-      const row = rows.get(key) ?? { target, componentKey: edge.componentKey, image, consumers: [] };
-      if (!row.consumers.includes(consumer.id)) {row.consumers.push(consumer.id);}
-      rows.set(key, row);
-    }
-  }
-  return [...rows.entries()]
-    .sort(([a], [b]) => compareStrings(a, b))
-    .map(([, row]) => row);
-}
-
-/** Sort order of projected edges: biome edges by (biomeId, componentKey), then supplemental edges by id. */
-export function compareDispatchedEdges(a, b) {
-  if (isSupplementalEdge(a) !== isSupplementalEdge(b)) {return isSupplementalEdge(a) ? 1 : -1;}
-  return isSupplementalEdge(a)
-    ? compareStrings(a.supplementalRuntimeComponentId, b.supplementalRuntimeComponentId)
-    : compareStrings(a.biomeId, b.biomeId) || compareStrings(a.componentKey, b.componentKey);
-}