@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/build-ledger.mjs

@@ -0,0 +1,107 @@
+// The committed build ledger (`build-ledger.json`): which commits of each source
+// repository published images, and (schema v2) which `imageRef:contentHash`
+// coordinates are published with which platforms.
+//
+// `node:` builtins plus the workspace locator only, so `source-authority.mjs`
+// (which resolves from a bare checkout) can read it.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { dataRoot } from './edition-workspace.mjs';
+
+export const BUILD_LEDGER_FILE = 'build-ledger.json';
+
+export class BuildLedgerError extends Error {
+  constructor(message) {
+    super(`${BUILD_LEDGER_FILE} is malformed: ${message}`);
+    this.name = 'BuildLedgerError';
+  }
+}
+
+const SHA1_PATTERN = /^[0-9a-f]{40}$/u;
+const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
+const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/u;
+const PLATFORM_PATTERN = /^[a-z0-9]+\/[a-z0-9]+(\/[a-z0-9]+)?$/u;
+
+const isRecord = (value) =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function parseImages(repo, images) {
+  if (!isRecord(images)) {
+    throw new BuildLedgerError(`repositories["${repo}"].images must be an object`);
+  }
+  for (const [imageRef, image] of Object.entries(images)) {
+    const where = `repositories["${repo}"].images["${imageRef}"]`;
+    if (!isRecord(image) || !isRecord(image.contentHashes)) {
+      throw new BuildLedgerError(`${where}.contentHashes must be an object`);
+    }
+    for (const [hash, entry] of Object.entries(image.contentHashes)) {
+      const at = `${where}.contentHashes["${hash}"]`;
+      if (!SHA256_PATTERN.test(hash)) {
+        throw new BuildLedgerError(`${at}: key is not 64 lowercase hex characters`);
+      }
+      if (
+        !isRecord(entry) ||
+        !Array.isArray(entry.platforms) ||
+        entry.platforms.length === 0 ||
+        entry.platforms.some(
+          (platform) => typeof platform !== 'string' || !PLATFORM_PATTERN.test(platform),
+        ) ||
+        new Set(entry.platforms).size !== entry.platforms.length
+      ) {
+        throw new BuildLedgerError(
+          `${at}.platforms must be a non-empty list of distinct "os/arch" strings`,
+        );
+      }
+      if (typeof entry.digest !== 'string' || !DIGEST_PATTERN.test(entry.digest)) {
+        throw new BuildLedgerError(`${at}.digest must be "sha256:<64 hex>"`);
+      }
+    }
+  }
+}
+
+/**
+ * Parse a ledger document strictly. Returns `{ schemaVersion, repositories }`
+ * where each repository is `{ commits, images }`; `images` is null for v1.
+ */
+export function parseBuildLedger(raw) {
+  if (
+    !isRecord(raw) ||
+    (raw.schemaVersion !== 1 && raw.schemaVersion !== 2) ||
+    !isRecord(raw.repositories)
+  ) {
+    throw new BuildLedgerError('expected schemaVersion 1 or 2 with a repositories object');
+  }
+  const repositories = {};
+  for (const [repo, value] of Object.entries(raw.repositories)) {
+    // v1 is removed once the data root is re-projected at v2.
+    if (raw.schemaVersion === 1) {
+      if (!Array.isArray(value)) {
+        throw new BuildLedgerError(`repositories["${repo}"] must be a commit list`);
+      }
+      repositories[repo] = { commits: value, images: null };
+      continue;
+    }
+    if (!isRecord(value) || !Array.isArray(value.commits)) {
+      throw new BuildLedgerError(`repositories["${repo}"].commits must be a list`);
+    }
+    if (value.commits.some((commit) => typeof commit !== 'string' || !SHA1_PATTERN.test(commit))) {
+      throw new BuildLedgerError(`repositories["${repo}"].commits holds a non-40-hex entry`);
+    }
+    parseImages(repo, value.images);
+    repositories[repo] = { commits: value.commits, images: value.images };
+  }
+  return { schemaVersion: raw.schemaVersion, repositories };
+}
+
+/** The parsed ledger of a data root, or null when none is projected. Malformed THROWS. */
+export function readBuildLedger(distributionsDir = dataRoot()) {
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(join(distributionsDir, BUILD_LEDGER_FILE), 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') {return null;}
+    throw error;
+  }
+  return parseBuildLedger(raw);
+}

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

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+
+import { canonicalPublicHttpsRepositoryUrl } from './canonical-repository-url.mjs';
+import { platformServiceIndexPath , WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, sourcePath } from './edition-workspace.mjs';
+import {
+  loadKernelDistributionSchemas,
+  readGitJsonAtCommit,
+  serializeJson,
+  sha256Hex,
+} from './lib.mjs';
+import {
+  comparablePlatformService,
+  declaredInstallationClass,
+  sourceDeclaredRequirements,
+  sourceOwnedCapabilityDomains,
+} 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]);
+}
+
+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 with any set of editions (or none) 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),
+      ...sourceOwnedCapabilityDomains(sourceManifest, `${binding.path} at ${before}`),
+      ...sourceDeclaredRequirements(sourceManifest, `${binding.path} at ${before}`),
+      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;
+  });
+}