@xemahq/xema 0.26.0 → 0.28.0

package/edition/build-biome-index.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+// build-biome-index — walk every `xema-biome.json` in the monorepo and emit the
+// global biome index (`distributions/biome-index.json`) that the distribution
+// resolver reads. The index is the single source of truth for "which biomes
+// exist, at what tier/target/origin/version, and what they require". It carries
+// PACKAGING-relevant fields only.
+//
+// Usage:
+//   node build-biome-index.mjs [--check] [--source published|workspace] [--unpinned]
+//
+// THE COMMITTED PINS ARE THE AUTHORITY, and this index is a CONSUMER of them.
+// Each repository's commit comes from `runtime-image-source-index.json`'s
+// `repositoryPins`; nothing here asks a repository what its newest built commit
+// is. `--unpinned` is the one way to reach a live resolution and it is a POLICY
+// operation — see `pinAuthority` below.
+//
+// Fail-fast on any manifest missing id/scope/target or with an unknown tier
+// (see manifestToIndexEntry). mjs tooling — clocks are fine; the index itself
+// carries no timestamp so it is reproducible.
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import { WorkspaceRoot, biomeIndexPath, configureEditionWorkspaceFromProcess, isEntryModule, platformServiceIndexPath } from './edition-workspace.mjs';
+import {
+  buildBiomeIndex,
+  distributionBiomeSourceRepositories,
+  loadKernelDistributionSchemas,
+  serializeJson,
+} from './lib.mjs';
+import { commandForSelf } from './remedy-command.mjs';
+import {
+  DistributionSourceMode,
+  committedRepositoryPins,
+  createPinnedSourceAuthority,
+  createSourceAuthority,
+  parseSourceModeArgs,
+} from './source-authority.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.SourceHash]);
+}
+
+/**
+ * WHY THIS INDEX READS THE PINS INSTEAD OF RESOLVING REPOSITORIES ITSELF.
+ *
+ * This index and `runtime-image-source-index.json` used to be derived from the
+ * same fact and DERIVE IT SEPARATELY: each called `commitForRepository`, which
+ * asks the world a live question whose answer moves whenever a build lands.
+ * `resolve-images` refuses any disagreement between them — it re-reads each
+ * biome manifest at the RUNTIME pin and fails with "sourceManifestHash does not
+ * match" — so two derivations minutes apart could produce two artifacts that
+ * cannot resolve together.
+ *
+ * A `--repo <repository>` scope was added to narrow the second derivation to
+ * one repository. It narrowed the COLLATERAL and left the RACE: the scoped
+ * repository was still resolved live, so a build landing between
+ * `build-runtime-image-source-index --repo X` and `build-biome-index --repo X`
+ * split the two artifacts on exactly the repository the operator was refreshing.
+ *
+ * So the scope is gone and the derivation with it. There is ONE artifact whose
+ * job is to decide what commit a repository is at — the runtime image source
+ * index — and everything downstream reads its record. A scoped refresh of this
+ * index is not a mode here any more: it is what you GET, because advancing one
+ * pin is the only thing that can move one repository's entries.
+ *
+ * `--unpinned` is the escape, and it is a POLICY operation rather than a
+ * correctness one. Two cases need it and no third has appeared:
+ *
+ *   - BOOTSTRAP — a repository that has JOINED the source set has no pin yet,
+ *     and `createPinnedSourceAuthority` refuses it rather than resolving it
+ *     live. That refusal is right (a repository joining is a full rebuild, not
+ *     a scoped refresh) and this is how the full rebuild is asked for.
+ *   - WORKSPACE — `--source workspace` snapshots a dirty local tree, which has
+ *     no pin by construction. It therefore IMPLIES `--unpinned`, rather than
+ *     making the operator state both.
+ */
+function parseUnpinned(argv) {
+  const index = argv.indexOf('--unpinned');
+  if (index === -1) {return { unpinned: false, remaining: argv };}
+  return {
+    unpinned: true,
+    remaining: [...argv.slice(0, index), ...argv.slice(index + 1)],
+  };
+}
+
+async function main() {
+  const { unpinned: unpinnedFlag, remaining: afterUnpinned } = parseUnpinned(
+    process.argv.slice(2),
+  );
+  const { mode, remaining } = parseSourceModeArgs(afterUnpinned);
+  const check = remaining.includes('--check');
+  if (remaining.some((argument) => argument !== '--check')) {
+    throw new Error(
+      'usage: build-biome-index.mjs [--check] [--source published|workspace] ' +
+        '[--unpinned]',
+    );
+  }
+  // A workspace snapshot has no pin and never will — see `parseUnpinned`.
+  const unpinned = unpinnedFlag || mode === DistributionSourceMode.Workspace;
+  const schemas = await loadKernelDistributionSchemas();
+  const platformServiceIndex = schemas.parsePlatformServiceSourceIndex(
+    JSON.parse(readFileSync(platformServiceIndexPath(), 'utf8')),
+  );
+  const sourceRepositories = distributionBiomeSourceRepositories();
+  const sourceAuthority = unpinned
+    ? createSourceAuthority({
+        mode,
+        knownRepositories: sourceRepositories.map(({ repo }) => repo),
+      })
+    : // NO DELEGATE, deliberately. A consumer artifact has nothing to resolve,
+      // and passing a live authority it "will not use" makes that a claim about
+      // this call site rather than a property of the object. Without one, any
+      // repository missing from the record REFUSES by name instead of quietly
+      // resolving to whatever its tip happens to be today.
+      createPinnedSourceAuthority({ pins: committedRepositoryPins() });
+  const index = await buildBiomeIndex(
+    platformServiceIndex,
+    sourceRepositories,
+    sourceAuthority,
+  );
+  const serialized = serializeJson(index);
+
+  if (check) {
+    let committed;
+    try {
+      committed = readFileSync(biomeIndexPath(), 'utf8');
+    } catch {
+      console.error(
+        `[dist:index --check] ${biomeIndexPath()} does not exist. Run \`${commandForSelf(import.meta.url)}\`.`,
+      );
+      process.exit(1);
+    }
+    if (committed !== serialized) {
+      const regenerateCommand =
+        mode === DistributionSourceMode.Workspace
+          ? `${commandForSelf(import.meta.url, '--source', 'workspace')} (local-only output; do not publish it)`
+          : commandForSelf(import.meta.url);
+      // WHICH AUTHORITY DISAGREED is the first thing the reader needs, because
+      // the two have different remedies: a PINNED divergence means the index
+      // does not match the pins and regenerating fixes it, while an UNPINNED one
+      // means the fleet has moved and regenerating MOVES EVERY PIN. Saying which
+      // ran is what keeps the second from being done by reflex.
+      console.error(
+        `[dist:index --check] authority: ${
+          unpinned
+            ? 'UNPINNED — every repository was resolved LIVE, so this verdict ' +
+              'is about the fleet right now and regenerating will move pins'
+            : `PINNED — ${
+                committedRepositoryPins().length
+              } committed pin(s), no live resolution`
+        }.`,
+      );
+      console.error(
+        `[dist:index --check] biome-index.json is out of date. Run \`${regenerateCommand}\`.`,
+      );
+      process.exit(1);
+    }
+    console.log(
+      `[dist:index --check] biome-index.json is up to date (${index.length} biomes).`,
+    );
+    return;
+  }
+
+  mkdirSync(dirname(biomeIndexPath()), { recursive: true });
+  writeFileSync(biomeIndexPath(), serialized);
+  console.log(
+    `[dist:index] wrote ${biomeIndexPath()} (${index.length} biomes).`,
+  );
+}
+
+main().catch((error) => {
+  console.error(`[dist:index] ${error.message}`);
+  process.exitCode = 1;
+});

package/edition/build-platform-service-index.mjs

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+
+import { platformServiceIndexPath , WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, sourcePath } from './edition-workspace.mjs';
+import {
+  canonicalPublicHttpsRepositoryUrl,
+  loadKernelDistributionSchemas,
+  readGitJsonAtCommit,
+  serializeJson,
+  sha256Hex,
+} from './lib.mjs';
+import {
+  comparablePlatformService,
+  declaredInstallationClass,
+} from './platform-service-class.mjs';
+import {
+  platformServiceSourceDeclaration,
+  platformServiceSourceDeclarations,
+  platformServiceSourceRepositories,
+} from './platform-service-source-authority.mjs';
+import {
+  DistributionSourceMode,
+  committedRepositoryPins,
+  createPinnedSourceAuthority,
+  createSourceAuthority,
+  parseSourceModeArgs,
+} from './source-authority.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.SourceHash]);
+}
+
+const TRUSTED_WRITE_FLAG = '--trusted-write';
+const CHECK_FLAG = '--check';
+const CHECK_SOURCES_FLAG = '--check-sources';
+const UNPINNED_FLAG = '--unpinned';
+
+/**
+ * THE LAST INDEX IN THIS PLANE THAT COULD NOT BE SCOPED, and the one that
+ * measurably fell behind because of it.
+ *
+ * `build-biome-index.mjs` and `build-runtime-image-source-index.mjs` could both
+ * be narrowed to one repository. This one could not: every run resolved all
+ * eight platform-service source repositories live. So advancing the two services
+ * sourced from `repos/xema-base` REQUIRED moving `event-hub-api`,
+ * `identity-api`, `llm-gateway-api` and `xema-host-web` with them — measured
+ * 2026-09-23, four collateral repositories that then disagreed with the runtime
+ * pins a scoped refresh had just held.
+ *
+ * It did not stay theoretical. Measured on `origin/main` the same day, the two
+ * committed indexes pinned `repos/xema-base` at commits 164 APART —
+ * `platform-service-index.json` at `e1987a11` (2026-09-17) against
+ * `runtime-image-source-index.json` at `fcde2a83` (2026-09-20) — because the
+ * pinnable index had been scope-refreshed and this one could only move by
+ * moving everything. Two committed artifacts, one repository, two commits.
+ *
+ * The fix is not a `--repo` flag here. A flag would have made this index a
+ * SECOND place that decides what commit a repository is at, which is the defect
+ * wearing a narrower costume. It reads the pins instead, like every other
+ * consumer, so a scoped refresh reaches it for free and there is nothing to
+ * keep in step.
+ */
+
+function readJson(path) {
+  return readStrictJsonFile(path);
+}
+
+function git(repo, args) {
+  return execFileSync('git', ['-C', repo, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+}
+
+/**
+ * Every platform service the data root declares (`platformServiceSources`) — the
+ * platform floor. NOT filtered by tier: the kernel distribution-lock schema
+ * requires an exact source identity on EVERY `platformServices[]` entry, so an
+ * index that describes only one tier makes every edition unresolvable. It did:
+ * filtering to `infra` left `xema-kernel-server`, `docs-api`,
+ * `opencode-image-prepuller` and `xema-host-web` with no identity at all.
+ *
+ * The index is derived from the declarations alone: no edition is read, so a
+ * data root that has no edition named `core` builds and checks it the same.
+ */
+function loadPlatformServiceDeclarations() {
+  return platformServiceSourceDeclarations()
+    .slice()
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function trustedSourceAuthority(sourceMode, unpinned) {
+  return unpinned
+    ? createSourceAuthority({
+        mode: sourceMode,
+        knownRepositories: platformServiceSourceRepositories(),
+      })
+    : // No delegate: this artifact decides no commits, so it must not be able
+      // to ask for one. A platform-service repository with no committed pin
+      // refuses by name rather than resolving to its tip.
+      createPinnedSourceAuthority({ pins: committedRepositoryPins() });
+}
+
+function buildTrustedIndex(sourceAuthority) {
+  const declarations = loadPlatformServiceDeclarations();
+  const services = [];
+  for (const declaration of declarations) {
+    const binding = platformServiceSourceDeclaration(declaration.name);
+    const repoDirectory = sourcePath(binding.repo);
+    // Read through the one explicit source authority. Published mode names a
+    // fetchable origin/main commit; workspace mode names a deterministic local
+    // snapshot commit containing tracked and untracked non-ignored files.
+    const before = sourceAuthority.commitForRepository(binding.repo);
+    const sourceManifest = readGitJsonAtCommit(
+      repoDirectory,
+      binding.manifestPath,
+      before,
+    );
+    if (sourceManifest.name !== binding.manifestName) {
+      throw new Error(
+        `${binding.path} at ${before} declares name "${String(sourceManifest.name)}", ` +
+          `but platform service "${declaration.name}" is declared to be sourced from ` +
+          `"${binding.manifestName}"`,
+      );
+    }
+    if (
+      typeof sourceManifest.version !== 'string' ||
+      sourceManifest.version.length === 0
+    ) {
+      throw new Error(
+        `${binding.path} has no exact version at ${before}`,
+      );
+    }
+    const repositoryUrl = canonicalPublicHttpsRepositoryUrl(
+      git(repoDirectory, ['remote', 'get-url', 'origin']),
+      `${binding.repo} origin`,
+    );
+    services.push({
+      name: declaration.name,
+      tier: declaration.tier,
+      ...declaredInstallationClass(declaration),
+      repositoryUrl,
+      repo: binding.repo,
+      path: binding.path,
+      sourceCommit: before,
+      version: sourceManifest.version,
+      sourceManifestHash: sha256Hex(serializeJson(sourceManifest)),
+      imageKey: binding.imageKey,
+    });
+  }
+  return { schemaVersion: 1, services };
+}
+
+function validateOfflineIndex(index) {
+  const declarations = loadPlatformServiceDeclarations();
+  const expected = declarations.map(comparablePlatformService);
+  const actual = index.services.map(comparablePlatformService);
+  if (serializeJson(actual) !== serializeJson(expected)) {
+    throw new Error(
+      'platform-service-index.json does not exactly match the platformServiceSources declared in edition-workspace.json',
+    );
+  }
+  for (const service of index.services) {
+    const canonicalRepositoryUrl = canonicalPublicHttpsRepositoryUrl(
+      service.repositoryUrl,
+      `platform service "${service.name}" repositoryUrl`,
+    );
+    if (canonicalRepositoryUrl !== service.repositoryUrl) {
+      throw new Error(
+        `platform service "${service.name}" repositoryUrl is not canonical`,
+      );
+    }
+    const expectedRepoName = service.repo.split('/').at(-1);
+    // Offline, and still exact: the declared source location is the authority,
+    // so a committed index that names a different repo, manifest or image key
+    // than the declaration fails here without touching Git.
+    const binding = platformServiceSourceDeclaration(service.name);
+    if (service.repo !== binding.repo || service.path !== binding.path) {
+      throw new Error(
+        `platform service "${service.name}" source ${service.repo}:${service.path} ` +
+          `does not match its declared source ${binding.repo}:${binding.path}`,
+      );
+    }
+    if (service.imageKey !== binding.imageKey) {
+      throw new Error(
+        `platform service "${service.name}" imageKey "${service.imageKey}" ` +
+          `does not match its declared image key "${binding.imageKey}"`,
+      );
+    }
+    if (!service.path.startsWith(`${service.repo}/`)) {
+      throw new Error(
+        `platform service "${service.name}" source path is outside its repo`,
+      );
+    }
+    if (
+      !service.repositoryUrl.endsWith(`/${expectedRepoName}.git`) &&
+      !service.repositoryUrl.endsWith(`/${expectedRepoName}`)
+    ) {
+      throw new Error(
+        `platform service "${service.name}" repositoryUrl does not identify ${service.repo}`,
+      );
+    }
+  }
+  return index;
+}
+
+/**
+ * The index as `--trusted-write` produces and validates it, over an explicit
+ * source authority. The develop edition builds its snapshot index here, with a
+ * pinned authority whose pins are the snapshot's, so the release and the
+ * develop lane share one builder and one validation.
+ */
+export function buildValidatedPlatformServiceIndex(schemas, sourceAuthority) {
+  const parsed = schemas.parsePlatformServiceSourceIndex(
+    buildTrustedIndex(sourceAuthority),
+  );
+  return validateOfflineIndex(parsed);
+}
+
+async function main() {
+  const { mode, remaining } = parseSourceModeArgs(process.argv.slice(2));
+  const flags = new Set(remaining);
+  const unpinnedFlag = flags.delete(UNPINNED_FLAG);
+  const unknown = [...flags].filter(
+    (flag) =>
+      flag !== TRUSTED_WRITE_FLAG &&
+      flag !== CHECK_FLAG &&
+      flag !== CHECK_SOURCES_FLAG,
+  );
+  if (unknown.length > 0 || flags.size !== 1) {
+    throw new Error(
+      `usage: node build-platform-service-index.mjs (${CHECK_FLAG} | ${CHECK_SOURCES_FLAG} | ${TRUSTED_WRITE_FLAG}) [--source published|workspace] [${UNPINNED_FLAG}]`,
+    );
+  }
+  // A workspace snapshot has no committed pin by construction, so it IMPLIES
+  // the live authority rather than requiring the operator to state both.
+  const unpinned = unpinnedFlag || mode === DistributionSourceMode.Workspace;
+  const schemas = await loadKernelDistributionSchemas();
+  if (flags.has(CHECK_FLAG)) {
+    if (!existsSync(platformServiceIndexPath())) {
+      throw new Error(`${platformServiceIndexPath()} does not exist`);
+    }
+    const parsed = schemas.parsePlatformServiceSourceIndex(
+      readJson(platformServiceIndexPath()),
+    );
+    validateOfflineIndex(parsed);
+    console.log(
+      `[platform-service-index] offline check passed for ${parsed.services.length} services`,
+    );
+    return;
+  }
+  const parsed = buildValidatedPlatformServiceIndex(schemas, trustedSourceAuthority(mode, unpinned));
+  if (flags.has(CHECK_SOURCES_FLAG)) {
+    if (!existsSync(platformServiceIndexPath())) {
+      throw new Error(`${platformServiceIndexPath()} does not exist`);
+    }
+    const committed = readFileSync(platformServiceIndexPath(), 'utf8');
+    if (committed !== serializeJson(parsed)) {
+      throw new Error(
+        `platform-service-index.json does not match the exact trusted clean sources ` +
+          `(authority: ${
+            unpinned
+              ? 'UNPINNED — every repository resolved LIVE, so this names the ' +
+                'fleet as it is now and regenerating will move pins'
+              : 'PINNED — the committed repositoryPins, no live resolution'
+          }).`,
+      );
+    }
+    console.log(
+      `[platform-service-index] trusted source check passed for ${parsed.services.length} services`,
+    );
+    return;
+  }
+  writeFileSync(platformServiceIndexPath(), serializeJson(parsed));
+  console.log(
+    `[platform-service-index] wrote ${platformServiceIndexPath()} from ${parsed.services.length} clean trusted sources`,
+  );
+}
+
+if (isEntryModule(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`[platform-service-index] ${error.message}`);
+    process.exitCode = 1;
+  });
+}