@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/develop-snapshot-inputs.mjs

@@ -0,0 +1,112 @@
+// 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 { buildTrustedKernelContractAuthority } from './kernel-contract-authority.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, kernelRoot?: string, contractAuthority?: object }} request
+ * `kernelRoot` and `contractAuthority`: a candidate that is the kernel authority states its own (see buildIndexesAtPins).
+ * @returns the injected inputs for the release resolvers, plus the pin source.
+ */
+export async function buildSnapshotInputs({ id, pins, schemas, kernelRoot, contractAuthority }) {
+  const pinSource = snapshotPinSource(pins);
+  const composed = composeEdition(schemas.parseDistribution, id, pinSource);
+  // A stated `contractAuthority` (a candidate that IS the kernel authority) replaces the committed one BEFORE the
+  // parse, as `repinContractAuthority` does: the develop index may still name an authority of another repository,
+  // which the schema refuses and which is irrelevant to this resolve. The schema itself is untouched.
+  const committedDocument = readStrictJsonFile(runtimeImageSourceIndexPath());
+  const committedIndex = schemas.parseRuntimeImageSourceIndex(
+    contractAuthority === undefined ? committedDocument : { ...committedDocument, contractAuthority },
+  );
+  validateSnapshotPins(pins, {
+    declaredSourceNames: composed.declaredSourceNames,
+    editionsRootExternal: editionsRoot() !== dataRoot(),
+  });
+  const { platformServiceIndex, biomeIndex, runtimeImageSourceIndex } = await buildIndexesAtPins({
+    schemas,
+    repositoryPins: applyPinSource(committedIndex, pinSource).repositoryPins,
+    kernelRoot,
+    contractAuthority,
+  });
+  return { pinSource, composed, platformServiceIndex, biomeIndex, runtimeImageSourceIndex };
+}
+
+/**
+ * The develop resolve's inputs: `buildSnapshotInputs`, with the kernel authority BUILT from the pinned member checkout
+ * (`kernelRepoDir()`, at the kernel pin) instead of the index's committed one, which names another repository's history.
+ * `build` is the authority builder (a test stands in for it).
+ */
+export async function buildDevelopSnapshotInputs({ id, pins, schemas, build = buildTrustedKernelContractAuthority }) {
+  const kernelRoot = kernelRepoDir();
+  const contractAuthority = await build({ repositoryDirectory: kernelRoot, schemas, kernelCommit: pins[kernelPinKey()] });
+  return buildSnapshotInputs({ id, pins, schemas, kernelRoot, contractAuthority });
+}

package/edition/develop-store-root.mjs

@@ -0,0 +1,20 @@
+// develop-store-root — the grammar of a first-party source's develop store root (`developImageRegistry` in
+// edition-workspace.json). A leaf module: the workspace parser and the develop coordinate both read it.
+
+import { DEVELOP_IMAGE_NAMESPACE_SEGMENT } from './edition-constants.mjs';
+
+const REGISTRY_HOST = '[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?(?::[0-9]+)?';
+const REGISTRY_PATH_SEGMENT = '[a-z0-9]+(?:[._-][a-z0-9]+)*';
+const DEVELOP_IMAGE_REGISTRY = new RegExp(`^${REGISTRY_HOST}(?:/${REGISTRY_PATH_SEGMENT})+$`);
+
+/** Why `value` is not a develop store root (`<host[:port]>/<path>`, lowercase, no scheme, tag, digest, trailing slash or `/dev`); null when it is. */
+export function developImageRegistryProblem(value) {
+  if (typeof value !== 'string' || !DEVELOP_IMAGE_REGISTRY.test(value)) {
+    return `must be a lowercase <host[:port]>/<path> store root with no scheme, tag, digest or trailing slash; got ${JSON.stringify(value)}`;
+  }
+  if (value.split('/').at(-1) === DEVELOP_IMAGE_NAMESPACE_SEGMENT) {
+    return `must not end in the "${DEVELOP_IMAGE_NAMESPACE_SEGMENT}" lane segment (the develop lane adds it); got ${JSON.stringify(value)}`;
+  }
+  return null;
+}
+

package/edition/dispatched-runtime-components.mjs

@@ -0,0 +1,172 @@
+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);
+}