@xemahq/xema 0.59.0 → 0.60.1

package/edition/build-ledger.mjs

@@ -1,107 +0,0 @@
-// 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

@@ -1,292 +0,0 @@
-#!/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;
-  });
-}