@xemahq/xema 0.26.0 → 0.28.0

package/edition/develop-freeze.mjs

@@ -0,0 +1,173 @@
+// develop-freeze — freeze the develop branches into one snapshot of pins.
+//
+// Resolves `refs/heads/develop` ONCE per distinct repository URL, applies the
+// caller's per-key overrides (an override wins and is never looked up), and
+// returns the pins. After this, NOTHING reads a branch: every later step takes
+// the pins. Two phases, because the declared sources are only known once the
+// edition's chain can be read from the checked-out editions root:
+//
+//   freezeGraph    the graph repositories, the data root, the kernel, the deploy checkout, the editions root
+//   freezeSources  one pin per `sources[]` entry the chain declares
+//
+// `resolveHead(url)` is the one network seam (default: `git ls-remote`
+// authenticated through git-source-auth, token from the environment, never argv).
+
+import { execFileSync } from 'node:child_process';
+
+import { gitAuthEnv } from './git-source-auth.mjs';
+import { canonicalPublicHttpsRepositoryUrl } from './lib.mjs';
+import {
+  dataPinKey,
+  EDITIONS_ROOT_PIN_KEY,
+  kernelPinKey,
+  SnapshotPinNamespace,
+  deployPinKey,
+  snapshotPinNamespace,
+  sortedSnapshotPins,
+  sourceNameOfPinKey,
+  sourcePinKey,
+} from './pin-source.mjs';
+
+const DEVELOP_REF = 'refs/heads/develop';
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+
+/** `git ls-remote <url> refs/heads/develop`, authenticated as `username` with `token`; throws naming the repository when absent. */
+export function lsRemoteDevelopHead(url, { username, token, runGit = execFileSync } = {}) {
+  const output = runGit('git', ['ls-remote', url, DEVELOP_REF], {
+    env: gitAuthEnv(url, username, token),
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+  const [sha, ref] = output.split(/\s+/);
+  if (!SHA_PATTERN.test(sha ?? '') || ref !== DEVELOP_REF) {
+    throw new Error(`${url} has no ${DEVELOP_REF}; a develop edition cannot be frozen without it`);
+  }
+  return sha;
+}
+
+/** A resolver that asks `resolveHead` at most once per distinct URL. */
+function memoizedHeads(resolveHead) {
+  const heads = new Map();
+  return (url) => {
+    if (!heads.has(url)) {heads.set(url, resolveHead(url));}
+    return heads.get(url);
+  };
+}
+
+/**
+ * The pins input selects WHICH inputs a snapshot resolves, never which tooling
+ * code runs: the distributions plane that executes is the dispatching ref's own
+ * checkout, so an override for its pin key is refused outright (even one equal
+ * to that checkout), naming the key.
+ */
+export function assertNoToolingOverride(overrides) {
+  if (overrides[dataPinKey()] !== undefined) {
+    throw new Error(
+      `pins override "${dataPinKey()}" is refused: it would select the tooling code this run executes. ` +
+        'The distributions plane is always the dispatching ref\'s own checkout; pins choose inputs, never tooling.',
+    );
+  }
+}
+
+function assertOverrides(overrides, allowed) {
+  for (const [key, sha] of Object.entries(overrides)) {
+    const namespace = snapshotPinNamespace(key);
+    if (!allowed.has(namespace)) {continue;} // another phase's pin
+    if (typeof sha !== 'string' || !SHA_PATTERN.test(sha)) {
+      throw new Error(`override for "${key}" is not a 40-hex commit SHA: ${JSON.stringify(sha)}`);
+    }
+  }
+}
+
+const GRAPH_PHASE = new Set([
+  SnapshotPinNamespace.Graph,
+  SnapshotPinNamespace.Distributions,
+  SnapshotPinNamespace.Kernel,
+  SnapshotPinNamespace.ChartSource,
+  SnapshotPinNamespace.EditionsRoot,
+]);
+const SOURCE_PHASE = new Set([SnapshotPinNamespace.Source]);
+
+/** A repository the workflow checked out is pinned at what it checked out; an override may only agree. */
+function assertCheckedOutPin({ key, sha, flag, what, overrides }) {
+  if (!SHA_PATTERN.test(sha ?? '')) {
+    throw new Error(`${flag} is not a 40-hex commit SHA: ${JSON.stringify(sha)}`);
+  }
+  if (overrides[key] !== undefined && overrides[key] !== sha) {
+    throw new Error(`override for "${key}" is ${overrides[key]}, but ${what} is checked out at ${sha}`);
+  }
+}
+
+/**
+ * @param {object} request
+ * @param {object} request.runtimeSourceIndex the checkout's runtime-image-source-index.json (raw)
+ * @param {string} request.dataSha the commit the data root checkout is at
+ * @param {string} request.kernelSha the commit the kernel checkout is at
+ * @param {string} request.deploySha the commit the deploy checkout is at
+ * @param {string} [request.editionsRootUrl] https URL of the editions root; absent = this repository
+ */
+export function freezeGraph({
+  runtimeSourceIndex,
+  dataSha,
+  kernelSha,
+  deploySha,
+  editionsRootUrl,
+  overrides = {},
+  resolveHead,
+}) {
+  assertNoToolingOverride(overrides);
+  assertOverrides(overrides, GRAPH_PHASE);
+  const head = memoizedHeads(resolveHead);
+  const graph = new Set(runtimeSourceIndex.repositoryPins.map((pin) => pin.repo));
+  for (const [key] of Object.entries(overrides)) {
+    if (snapshotPinNamespace(key) === SnapshotPinNamespace.Graph && !graph.has(key)) {
+      throw new Error(`override names "${key}", which is not a repository in the graph`);
+    }
+  }
+  const checkedOut = [
+    { key: dataPinKey(), sha: dataSha, flag: '--data-sha', what: 'the data root checkout' },
+    { key: kernelPinKey(), sha: kernelSha, flag: '--kernel-sha', what: 'the kernel checkout' },
+    { key: deployPinKey(), sha: deploySha, flag: '--deploy-sha', what: 'the deploy checkout' },
+  ];
+  for (const { key, sha, flag, what } of checkedOut) {assertCheckedOutPin({ key, sha, flag, what, overrides });}
+  if (editionsRootUrl === undefined && overrides[EDITIONS_ROOT_PIN_KEY] !== undefined) {
+    throw new Error(`override names "${EDITIONS_ROOT_PIN_KEY}", but the editions root is this repository`);
+  }
+  const pins = Object.fromEntries(checkedOut.map(({ key, sha }) => [key, sha]));
+  for (const pin of runtimeSourceIndex.repositoryPins) {
+    pins[pin.repo] = overrides[pin.repo] ?? head(pin.repositoryUrl);
+  }
+  if (editionsRootUrl !== undefined) {
+    const url = canonicalPublicHttpsRepositoryUrl(editionsRootUrl, '--editions-root-url');
+    pins[EDITIONS_ROOT_PIN_KEY] = overrides[EDITIONS_ROOT_PIN_KEY] ?? head(url);
+  }
+  return sortedSnapshotPins(pins);
+}
+
+/**
+ * @param {object} request
+ * @param {Record<string,string>} request.pins the graph phase's pins
+ * @param {object[]} request.declaredSources every `sources[]` entry in the chain (`{ name, url, ... }`)
+ */
+export function freezeSources({ pins, declaredSources, overrides = {}, resolveHead }) {
+  assertOverrides(overrides, SOURCE_PHASE);
+  const head = memoizedHeads(resolveHead);
+  const urlByName = new Map();
+  for (const source of declaredSources) {
+    const known = urlByName.get(source.name);
+    if (known !== undefined && known !== source.url) {
+      throw new Error(`source "${source.name}" is declared at two URLs (${known}, ${source.url})`);
+    }
+    urlByName.set(source.name, source.url);
+  }
+  for (const key of Object.keys(overrides)) {
+    if (snapshotPinNamespace(key) === SnapshotPinNamespace.Source && !urlByName.has(sourceNameOfPinKey(key))) {
+      throw new Error(`override names "${key}", but the chain declares no such source`);
+    }
+  }
+  const frozen = { ...pins };
+  for (const [name, url] of urlByName) {
+    frozen[sourcePinKey(name)] = overrides[sourcePinKey(name)] ?? head(url);
+  }
+  return sortedSnapshotPins(frozen);
+}

package/edition/develop-image-coordinate.mjs

@@ -0,0 +1,54 @@
+// develop-image-coordinate — the ONE mapping from a release image repository to
+// the develop repository its producer pushes the same build to.
+//
+//   <host>/<owner>/<name...>   ->   <host>/<owner>/dev/<name...>
+//
+// A producer's develop lane pushes `<devRepository>:<contentHash>` (contract C1)
+// and nothing else reads or writes that namespace, so a release coordinate can
+// never be satisfied by a develop build or the other way round.
+
+import { DEVELOP_IMAGE_NAMESPACE_SEGMENT } from './edition-constants.mjs';
+import { splitImageRef } from './registry-credentials.mjs';
+
+const DEVELOP_NAMESPACE_SEGMENT = DEVELOP_IMAGE_NAMESPACE_SEGMENT;
+
+const OWNER_SEGMENT_INDEX = 0;
+const NAMESPACE_SEGMENT_INDEX = 1;
+const MINIMUM_REPOSITORY_SEGMENTS = 2;
+
+/** `developImageRef('registry.example.com/acme/identity-api') === 'registry.example.com/acme/dev/identity-api'`. */
+export function developImageRef(releaseImageRef) {
+  const { authority, repository } = splitImageRef(releaseImageRef);
+  if (repository.includes('@') || repository.includes(':')) {
+    throw new Error(
+      `image reference "${releaseImageRef}" carries a tag or digest; a develop coordinate maps a bare repository`,
+    );
+  }
+  const segments = repository.split('/');
+  if (segments.length < MINIMUM_REPOSITORY_SEGMENTS) {
+    throw new Error(
+      `image reference "${releaseImageRef}" has no <owner>/<name> repository path; it cannot be mapped to a develop repository`,
+    );
+  }
+  if (segments[NAMESPACE_SEGMENT_INDEX] === DEVELOP_NAMESPACE_SEGMENT) {
+    throw new Error(`image reference "${releaseImageRef}" is already a develop repository`);
+  }
+  const [owner, ...name] = segments;
+  return `${authority}/${owner}/${DEVELOP_NAMESPACE_SEGMENT}/${name.join('/')}`;
+}
+
+/** Whether a repository reference lies in the develop namespace. */
+export function isDevelopImageRef(imageRef) {
+  let repository;
+  try {
+    ({ repository } = splitImageRef(imageRef));
+  } catch {
+    return false;
+  }
+  const segments = repository.split('/');
+  return (
+    segments.length > MINIMUM_REPOSITORY_SEGMENTS &&
+    segments[OWNER_SEGMENT_INDEX].length > 0 &&
+    segments[NAMESPACE_SEGMENT_INDEX] === DEVELOP_NAMESPACE_SEGMENT
+  );
+}

package/edition/develop-seal.mjs

@@ -0,0 +1,77 @@
+// develop-seal — seal a snapshot's images lock against the DEVELOP repositories.
+//
+// The release sealer verifies `<imageRef>:<contentHash>` and writes the digest
+// the registry served. This does the same for a develop edition, with the
+// SAME verifier (`verifyDistributionPlatforms`, required platforms enforced)
+// and the SAME digest decision (`planDigestSeal`), against the repository the
+// producer's develop lane pushes to (`developImageRef`, contract C1).
+//
+// A coordinate that is not there is "not built yet": the producer's CI is not
+// green or still running. EVERY such subject is collected and named at once;
+// any other failure (a 403, a malformed index, an absent required platform)
+// aborts as it does in the release.
+
+import { developImageRef } from './develop-image-coordinate.mjs';
+import { editionsRoot } from './edition-workspace.mjs';
+import { validateImmutableImageLock, loadKernelDistributionSchemas, } from './lib.mjs';
+import { isNotPublishedYet, planDigestSeal } from './seal-image-digests.mjs';
+import { verifyDistributionPlatforms } from './verify-image-platforms.mjs';
+
+function notBuiltYetMessage(subject) {
+  return (
+    `${subject.repo}@${subject.sourceCommit} develop image ` +
+    `${subject.imageRef}:${subject.contentHash} not built yet`
+  );
+}
+
+/**
+ * @param {object} request
+ * @param {object} request.imageLock the snapshot images lock (release refs, unsealed)
+ * @returns the images lock with develop refs and verified digests, kernel-validated
+ */
+export async function sealDevelopImages({
+  imageLock,
+  distributionsRoot = editionsRoot(),
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  run = null,
+}) {
+  const developLock = {
+    ...imageLock,
+    subjects: imageLock.subjects.map((subject) => ({
+      ...subject,
+      imageRef: developImageRef(subject.imageRef),
+    })),
+  };
+  const report = await verifyDistributionPlatforms({
+    imageLock: developLock,
+    distributionsRoot,
+    env,
+    fetchImpl,
+    run,
+    collectFailures: true,
+  });
+  const aborting = report.failures.find(({ error }) => !isNotPublishedYet(error));
+  if (aborting) {throw aborting.error;}
+  if (report.failures.length > 0) {
+    throw new Error(
+      `${report.failures.length} develop image(s) of "${developLock.distributionId}" are not built yet ` +
+        '(the producer\'s CI is not green or still running):\n  ' +
+        report.failures.map(({ subject }) => notBuiltYetMessage(subject)).join('\n  '),
+    );
+  }
+  const { writes, unchanged } = planDigestSeal({ subjects: developLock.subjects, verified: report.subjects });
+  const digests = new Map([...writes, ...unchanged].map(({ key, digest }) => [key, digest]));
+  const schemas = await loadKernelDistributionSchemas();
+  const { parseImageLock } = schemas;
+  return validateImmutableImageLock(
+    parseImageLock({
+      ...developLock,
+      subjects: developLock.subjects.map((subject) => ({
+        ...subject,
+        imageDigest: digests.get(`${subject.kind}:${subject.id}`),
+      })),
+    }),
+    schemas,
+  );
+}

package/edition/develop-snapshot-inputs.mjs

@@ -0,0 +1,104 @@
+// 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 { buildValidatedPlatformServiceIndex } from './build-platform-service-index.mjs';
+import { buildTrustedIndex, validateRuntimeImageSourceIndex } from './build-runtime-image-source-index.mjs';
+import { dataRoot, deployRoot, editionsRoot, kernelRepoDir, runtimeImageSourceIndexPath } from './edition-workspace.mjs';
+import {
+  buildBiomeIndex,
+  distributionBiomeSourceRepositories,
+} from './lib.mjs';
+import {
+  dataPinKey,
+  EDITIONS_ROOT_PIN_KEY,
+  kernelPinKey,
+  deployPinKey,
+  applyPinSource,
+  snapshotPinSource,
+  validateSnapshotPins,
+} from './pin-source.mjs';
+import { composeEdition } from './resolve-distribution.mjs';
+import { createPinnedSourceAuthority } from './source-authority.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 Error(`the snapshot has no pin "${key}" for ${dir}`);}
+  const head = git(dir, ['rev-parse', 'HEAD']);
+  if (head !== pinned) {
+    throw new Error(`${dir} is at ${head}, but the snapshot pins "${key}" at ${pinned}`);
+  }
+  const dirty = git(dir, ['status', '--porcelain']);
+  if (dirty.length > 0) {
+    throw new Error(`${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, {
+    runtimeSourceIndex: committedIndex,
+    declaredSourceNames: composed.declaredSourceNames,
+    editionsRootExternal: editionsRoot() !== dataRoot(),
+  });
+  const sourceAuthority = createPinnedSourceAuthority({
+    pins: applyPinSource(committedIndex, pinSource).repositoryPins,
+  });
+  const platformServiceIndex = buildValidatedPlatformServiceIndex(schemas, sourceAuthority);
+  const biomeIndex = await buildBiomeIndex(platformServiceIndex, distributionBiomeSourceRepositories(), sourceAuthority);
+  const runtimeImageSourceIndex = schemas.parseRuntimeImageSourceIndex(
+    await buildTrustedIndex(schemas, sourceAuthority, undefined, undefined, { biomeIndex, platformServiceIndex }),
+  );
+  await validateRuntimeImageSourceIndex(runtimeImageSourceIndex, schemas, { biomeIndex, platformServiceIndex });
+  return { pinSource, composed, platformServiceIndex, biomeIndex, runtimeImageSourceIndex };
+}