@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/platform-service-class.mjs

@@ -0,0 +1,85 @@
+import { isKernelCapabilityDomain } from './kernel-capability-domain.mjs';
+import { componentAudienceRequirements, componentOperationRequirements, componentOptionalPeers, componentOwnedAudienceNamespaces } from './operation-requirements.mjs';
+import { compareStrings } from './string-order.mjs';
+
+/**
+ * A platform service's installation class, as the index carries it.
+ *
+ * The class is the service's OWN declaration (`core/xema-distribution.json`
+ * `platformServices[].installationClass`). There is no default and no list of
+ * names here: a service that declares none has none in the index, and the
+ * resolver refuses it by name rather than reading a guessed class.
+ */
+export function declaredInstallationClass(declaration) {
+  return declaration.installationClass === undefined
+    ? {}
+    : { installationClass: declaration.installationClass };
+}
+
+/**
+ * The capability domains a platform service OWNS, as the index carries them:
+ * sorted and non-empty, or no key at all.
+ *
+ * Ownership is the SERVICE's own statement, read from its source manifest
+ * (`xema.ownsCapabilityDomains` in the manifest `platformServiceSources` names,
+ * at the pinned commit), the same field a biome manifest uses. An edition or
+ * the data root never asserts it. The manifest is bound into the index by
+ * `sourceManifestHash`, so the claim cannot drift from the source. Uniqueness
+ * across the index is the kernel's index schema's to grade.
+ *
+ * @param {unknown} sourceManifest the parsed source manifest
+ * @param {string} where names the manifest in a refusal
+ */
+export function sourceOwnedCapabilityDomains(sourceManifest, where) {
+  const domains = sourceManifest?.xema?.ownsCapabilityDomains;
+  if (domains === undefined) {return {};}
+  if (!Array.isArray(domains) || domains.length === 0) {
+    throw new Error(
+      `${where}: xema.ownsCapabilityDomains must be a non-empty array of capability domains; ` +
+        'omit it to own none',
+    );
+  }
+  for (const domain of domains) {
+    if (!isKernelCapabilityDomain(domain)) {
+      throw new Error(
+        `${where}: xema.ownsCapabilityDomains contains ${JSON.stringify(domain)}, ` +
+          'which is not a valid capability domain',
+      );
+    }
+  }
+  const sorted = [...domains].sort(compareStrings);
+  const repeated = sorted.find((domain, index) => sorted[index - 1] === domain);
+  if (repeated !== undefined) {
+    throw new Error(`${where}: xema.ownsCapabilityDomains names "${repeated}" more than once`);
+  }
+  return { ownsCapabilityDomains: sorted };
+}
+
+/**
+ * What a platform service declares it requires and owns, as the index carries it, read from the
+ * same declaration as {@link sourceOwnedCapabilityDomains} (the `xema` block of its source manifest):
+ * `requiresOperations`, `requiresAudiences`, `ownsAudienceNamespaces` and `optionalPeers`. Each is sorted, unique and
+ * non-empty, or no key at all. Declared INTENT: the lock admits or refuses each
+ * (`admitOperationGrants`, `admitExactAudiences`).
+ *
+ * @param {unknown} sourceManifest the parsed source manifest
+ * @param {string} where names the manifest in a refusal
+ */
+export function sourceDeclaredRequirements(sourceManifest, where) {
+  const xema = sourceManifest?.xema ?? {};
+  const requiresOperations = componentOperationRequirements(xema, where);
+  const requiresAudiences = componentAudienceRequirements(xema, where);
+  const ownsAudienceNamespaces = componentOwnedAudienceNamespaces(xema, where);
+  const optionalPeers = componentOptionalPeers(xema, where);
+  return {
+    ...(requiresOperations === null ? {} : { requiresOperations }),
+    ...(requiresAudiences === null ? {} : { requiresAudiences }),
+    ...(ownsAudienceNamespaces === null ? {} : { ownsAudienceNamespaces }),
+    ...(optionalPeers === null ? {} : { optionalPeers }),
+  };
+}
+
+/** The (name, tier, declared class) a declaration and an index entry must agree on. */
+export function comparablePlatformService(entry) {
+  return { name: entry.name, tier: entry.tier, ...declaredInstallationClass(entry) };
+}

package/edition/platform-service-ownership.mjs

@@ -0,0 +1,91 @@
+import { sourcePath } from './edition-workspace.mjs';
+import { readGitJsonAtCommit, serializeJson, sha256Hex } from './lib.mjs';
+import { sourceDeclaredRequirements, sourceOwnedCapabilityDomains } from './platform-service-class.mjs';
+
+/** The index-row fields re-derived from a service's own source manifest and compared on read. */
+const DERIVED_ROW_FIELDS = Object.freeze([
+  'ownsCapabilityDomains',
+  'requiresOperations',
+  'requiresAudiences',
+  'ownsAudienceNamespaces',
+]);
+
+/** Why a platform service's capability-domain ownership was refused. */
+export const PlatformServiceOwnershipFault = Object.freeze({
+  /** The pinned source manifest could not be read. */
+  ManifestUnavailable: 'manifest-unavailable',
+  /** The manifest bytes do not hash to the index entry's `sourceManifestHash`. */
+  ManifestHashMismatch: 'manifest-hash-mismatch',
+  /** An index entry's ownership or requirement field differs from the source manifest's. */
+  OwnershipMismatch: 'ownership-mismatch',
+});
+
+export class PlatformServiceOwnershipError extends Error {
+  constructor(fault, message) {
+    super(`[${fault}] ${message}`);
+    this.name = 'PlatformServiceOwnershipError';
+    this.fault = fault;
+  }
+}
+
+/**
+ * The source manifest of one index entry, at the commit the entry pins. The
+ * entry's `path` is workspace-relative (`<repo>/<manifestPath>`).
+ */
+export function readPinnedSourceManifest(entry) {
+  const manifestPath = entry.path.slice(`${entry.repo}/`.length);
+  try {
+    return readGitJsonAtCommit(sourcePath(entry.repo), manifestPath, entry.sourceCommit);
+  } catch (cause) {
+    throw new PlatformServiceOwnershipError(
+      PlatformServiceOwnershipFault.ManifestUnavailable,
+      `platform service "${entry.name}": cannot read ${entry.path} at ${entry.sourceCommit} ` +
+        `(${cause.message}); a resolve that reads the platform-service index needs the pinned sources`,
+    );
+  }
+}
+
+/**
+ * Re-derive each platform service's ownership and requirement fields (`DERIVED_ROW_FIELDS`) from its pinned
+ * source manifest and refuse the index when an entry disagrees. The index is a
+ * hand-editable file; the SERVICE's own manifest is the authority for which
+ * service owns a domain, and so for where grants land.
+ *
+ * Returns the index rows with the RE-DERIVED value, never the index's.
+ *
+ * @param {{ services: object[] }} index
+ * @param {{ names?: Set<string>, readManifest?: (entry: object) => unknown }} [options]
+ *   `names` restricts the check to those services; `readManifest` is the test seam.
+ */
+export function verifiedPlatformServiceIndex(index, { names, readManifest = readPinnedSourceManifest } = {}) {
+  const services = index.services.map((entry) => {
+    if (names !== undefined && !names.has(entry.name)) {return entry;}
+    const manifest = readManifest(entry);
+    const actualHash = sha256Hex(serializeJson(manifest));
+    if (actualHash !== entry.sourceManifestHash) {
+      throw new PlatformServiceOwnershipError(
+        PlatformServiceOwnershipFault.ManifestHashMismatch,
+        `platform service "${entry.name}": ${entry.path} at ${entry.sourceCommit} hashes to ${actualHash}, ` +
+          `but the index pins sourceManifestHash ${entry.sourceManifestHash}`,
+      );
+    }
+    const where = `${entry.path} at ${entry.sourceCommit}`;
+    const derived = { ...sourceOwnedCapabilityDomains(manifest, where), ...sourceDeclaredRequirements(manifest, where) };
+    for (const field of DERIVED_ROW_FIELDS) {
+      if (serializeJson(entry[field] ?? null) !== serializeJson(derived[field] ?? null)) {
+        throw new PlatformServiceOwnershipError(
+          PlatformServiceOwnershipFault.OwnershipMismatch,
+          `platform service "${entry.name}": the index claims ${field} ${JSON.stringify(entry[field] ?? [])}, ` +
+            `its source manifest declares ${JSON.stringify(derived[field] ?? [])} ` +
+            `(sourceManifestHash ${entry.sourceManifestHash})`,
+        );
+      }
+    }
+    // The derived fields equal the entry's (checked above), so they are written over it IN PLACE: the row keeps its
+    // key order, and `serializeJson` of the verified row is the claimed row's. A biome edge's owner identity is that
+    // serialization of the row the builder wrote (validateServiceDependencyOwnerParity); moving a field to the end
+    // would refuse every edge to a service that declares a derived field before a later one.
+    return { ...entry, ...derived };
+  });
+  return { ...index, services };
+}

package/edition/platform-service-source-authority.mjs

@@ -0,0 +1,105 @@
+import { workspaceSection } from './edition-config.mjs';
+
+/**
+ * The ONE authority for what a declared platform service IS, source-wise.
+ *
+ * the data root's `edition-workspace.json#platformServiceSources` declares the
+ * platform services, their tier and installation class, and where their source
+ * lives. The library owns the SCHEMA of that section (workspace-sections.mjs) and
+ * this module reads it; for every declared platform service it names
+ *
+ *   - `repo` + `manifestPath` — the exact source manifest whose `name`/`version`
+ *     are the service's identity, read at the repository's published commit;
+ *   - `manifestName` — the name that manifest MUST declare, which is what stops
+ *     a name-only substitution from silently re-pointing a service;
+ *   - `imageKey` — the join to the independent images.lock authority;
+ *   - `runtimeBinding` — the actual runtime image subject that CARRIES this
+ *     service, or `null` when the service is its own repository-root image.
+ *
+ * That last field is the partition the whole image plane turns on, and it is
+ * declared exactly once, here:
+ *
+ *   - `runtimeBinding === null` — an INDEPENDENTLY SOURCED service. Its image is
+ *     built from its repository root, and `resolve-images.mjs` mints a
+ *     `platform`-kind subject for it whose id is `imageKey`. These are the five
+ *     generic submodules.
+ *   - `runtimeBinding !== null` — the service's image is a subject something ELSE
+ *     produces: a supplemental subject declared by
+ *     `build-runtime-image-source-index.mjs`, or a component of a selected biome.
+ *     No `platform`-kind subject is minted; the binding names the real one.
+ *
+ * Both halves still carry an exact source identity, because
+ * `LockedPlatformService.source` is REQUIRED by the kernel distribution-lock
+ * schema at schemaVersion 2. Before this module existed, the index generator
+ * resolved every service to a hardcoded `submodules/<name>`, so it could only
+ * ever describe the five submodules, and every edition failed to resolve on
+ * `xema-kernel-server` — declared since bc8d5c6 and never resolvable.
+ *
+ * Adding a platform service is therefore ONE data entry in the data root and no
+ * code change: the platform service index is derived from these rows, so there
+ * is no second list to forget.
+ *
+ * A row is a hand-declared fact only where nothing can derive it. It cannot be
+ * derived: `docs-api` is sourced from a package named `xema-docs`,
+ * `xema-kernel-server` sits at a sub-path of a carved repository, and
+ * `opencode-image-prepuller` ships no package of its own at all — it is a
+ * DaemonSet whose sole purpose is to keep the `opencode-worker` image warm, so
+ * its identity is exactly the identity of the biome that declares that image.
+ */
+
+const declarations = () =>
+  workspaceSection('platformServiceSources', 'resolving a platform service to its source');
+
+/** Every declared platform service, sorted by name. */
+export const platformServiceSourceDeclarations = () =>
+  declarations()
+    .map((declaration) =>
+      Object.freeze({
+        ...declaration,
+        /** Aggregate-workspace-relative manifest path, the lock's `source.path`. */
+        path: `${declaration.repo}/${declaration.manifestPath}`,
+      }),
+    )
+    .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+
+/**
+ * The declaration for one platform service. Fails fast and names the service —
+ * source resolution never falls back to a guessed location.
+ */
+export function platformServiceSourceDeclaration(name) {
+  const declaration = platformServiceSourceDeclarations().find((entry) => entry.name === name);
+  if (!declaration) {
+    throw new Error(
+      `platform service "${name}" has no source declaration in the "platformServiceSources" ` +
+        'section of edition-workspace.json; declare its repo, manifest path, ' +
+        'manifest name, image key and runtime binding there',
+    );
+  }
+  return declaration;
+}
+
+/** Every source repository a platform service is read from, deduplicated. */
+export const platformServiceSourceRepositories = () => [
+  ...new Set(platformServiceSourceDeclarations().map((declaration) => declaration.repo)),
+];
+
+/**
+ * The logical-platform-service → actual-runtime-subject bindings, in the exact
+ * shape `runtime-image-source-index.json#platformServiceBindings` carries.
+ * DERIVED from the declarations above so the partition has one definition.
+ */
+export const platformServiceRuntimeBindings = () =>
+  platformServiceSourceDeclarations()
+    .filter((declaration) => declaration.runtimeBinding !== null)
+    .map((declaration) =>
+      Object.freeze({
+        platformService: declaration.name,
+        subjectKind: declaration.runtimeBinding.subjectKind,
+        subjectId: declaration.runtimeBinding.subjectId,
+      }),
+    );
+
+/** True when the service's image is produced by some other subject. */
+export function platformServiceHasRuntimeBinding(name) {
+  return platformServiceSourceDeclaration(name).runtimeBinding !== null;
+}

package/edition/positive-closure.mjs

@@ -0,0 +1,162 @@
+// positive-closure — the packaging plane's projection onto the kernel's ONE
+// closure algorithm (`resolveBiomeClosure`, `@xemahq/contracts/distribution`).
+//
+// The KERNEL owns the rule; this module owns only the projection of THIS
+// plane's facts onto it — biome-index entries and lock entries become
+// `ClosureBiomeFacts`, and a lock's `resolution` section becomes a `why`
+// answer. Two callers use the rule:
+//
+//   * an EDITION (`resolve-distribution.mjs`, `selectByPositiveClosure`) — its
+//     declared roots against the biome catalogue, starting from nothing;
+//   * a RUNTIME INSTALLATION (`runtimeInstallationClosure` below) — one
+//     org-installed biome against what its base edition already PROVIDES (the
+//     sealed lock's roster) and PERMITS (the candidates the caller admits).
+//
+// Neither re-implements any part of the closure; a second closure here would be
+// a rival answer to the question the kernel exists to answer once.
+
+/** Project one biome-index entry onto the facts the closure reads. */
+export function closureBiomeFacts(entry) {
+  return {
+    id: entry.id,
+    tier: entry.tier,
+    ...(entry.installationClass === undefined
+      ? {}
+      : { installationClass: entry.installationClass }),
+    ...(entry.audience === undefined ? {} : { audience: entry.audience }),
+    services: Array.isArray(entry.services) ? entry.services : [],
+    ...(entry.dependencyContract === undefined
+      ? {}
+      : { dependencyContract: entry.dependencyContract }),
+    ...(entry.serviceResources === undefined
+      ? {}
+      : { serviceResources: entry.serviceResources }),
+    ...(entry.providesResources === undefined
+      ? {}
+      : { providesResources: entry.providesResources }),
+  };
+}
+
+/**
+ * The closure of ONE runtime-installed biome against a sealed base edition.
+ *
+ * - `baseLock` is the base edition's distribution lock (read with the kernel's
+ *   tolerant reader by the caller). Its roster is what the base PROVIDES; each
+ *   rostered biome's facts are taken from `index` by id, because a lock entry
+ *   carries no dependency contract or resource provisions.
+ * - `permitted` is the catalogue the base edition PERMITS an installation to
+ *   draw on — the caller decides it (store visibility, trust policy, sources);
+ *   it defaults to every `index` entry the base does not already ship.
+ * - The installed biome is a `runtime-installation-root`. A biome the base
+ *   already ships is never re-added and never traversed.
+ *
+ * Returns the kernel result unchanged: the entities the installation ADDS, with
+ * provenance, and every resource binding of an added biome against added ∪
+ * present. Refusals are the kernel's, prefixed with the installation subject.
+ */
+export function runtimeInstallationClosure({
+  schemas,
+  baseLock,
+  index,
+  biomeId,
+  permitted,
+}) {
+  const indexById = new Map(index.map((entry) => [entry.id, entry]));
+  const presentIds = new Set(baseLock.biomes.map((biome) => biome.id));
+  const presentBiomes = baseLock.biomes.map((biome) => {
+    const entry = indexById.get(biome.id);
+    if (entry === undefined) {
+      throw new Error(
+        `runtime installation of "${biomeId}": base edition "${baseLock.distributionId}" ships ` +
+          `biome "${biome.id}", which the catalogue does not describe — the base's provisions ` +
+          'cannot be read, so its satisfaction of an edge cannot be decided',
+      );
+    }
+    return closureBiomeFacts(entry);
+  });
+  const candidates = (permitted ?? index.filter((entry) => !presentIds.has(entry.id))).map(
+    closureBiomeFacts,
+  );
+  try {
+    return schemas.resolveBiomeClosure({
+      roots: [
+        {
+          entity: { kind: schemas.ClosureEntityKind.Biome, id: biomeId },
+          provenance: {
+            kind: schemas.ClosureProvenanceKind.RuntimeInstallationRoot,
+          },
+        },
+      ],
+      candidates: { biomes: candidates, platformServices: [] },
+      present: {
+        biomes: presentBiomes,
+        platformServices: baseLock.platformServices.map(({ name, tier }) => ({
+          name,
+          tier,
+        })),
+      },
+    });
+  } catch (error) {
+    if (error instanceof schemas.BiomeClosureError) {
+      throw new Error(
+        `runtime installation of "${biomeId}" into base edition "${baseLock.distributionId}": ${error.message}`,
+        { cause: error },
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * `why <name>` — the deterministic explanation of one entity's presence in a
+ * lock, rendered from the lock's `resolution` section alone. Returns the lines
+ * to print. A biome id is looked up first, then a platform-service name; a
+ * selector-model lock records no provenance and says so rather than guessing.
+ */
+export function explainInclusion(schemas, lock, name) {
+  if (lock.resolution === undefined) {
+    return {
+      found: false,
+      lines: [
+        `${lock.distributionId}: this edition resolves by the selector model ` +
+          '(include/exclude); its lock records no provenance. Opt the edition into ' +
+          '`resolution: "positive-closure"` to make `why` answerable.',
+      ],
+    };
+  }
+  const entry =
+    lock.resolution.entries.find(
+      (candidate) =>
+        candidate.entity.kind === schemas.ClosureEntityKind.Biome &&
+        candidate.entity.id === name,
+    ) ??
+    lock.resolution.entries.find(
+      (candidate) =>
+        candidate.entity.kind === schemas.ClosureEntityKind.PlatformService &&
+        candidate.entity.id === name,
+    );
+  if (entry === undefined) {
+    return {
+      found: false,
+      lines: [
+        `${lock.distributionId}: "${name}" is not in this edition — it is not a root, no ` +
+          'operation root names it, and no dependency or reached operation of anything in ' +
+          'the edition requires it.',
+      ],
+    };
+  }
+  const lines = [`${lock.distributionId}: ${entry.entity.kind} "${entry.entity.id}" is in because:`];
+  for (const provenance of entry.provenance) {
+    if (provenance.chain === undefined) {
+      lines.push(`  - ${schemas.describeProvenance(provenance)}`);
+      continue;
+    }
+    lines.push(
+      `  - ${provenance.kind}, from root ${provenance.root.kind} "${provenance.root.id}":`,
+    );
+    provenance.chain.forEach((hop, step) => {
+      lines.push(`      ${step + 1}. ${schemas.describeHop(hop)}`);
+    });
+  }
+  return { found: true, lines };
+}

package/edition/previous-image-lock.mjs

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+
+/**
+ * Parse a PREVIOUS images lock (the committed file, or a `--previous-lock`): the lock this relock carries composed artifacts
+ * forward FROM, never one it vouches for. Its `contractAuthority` is held to the authority's SHAPE only (the kernel's authority
+ * schema, with `repositoryUrl` open to any string): a lock stated under an earlier authority (a rebind of the kernel contract
+ * repository) is still readable. Every other field stays strict, and the NEW lock stays strict throughout.
+ * Nothing may treat the returned authority as the current one; the previous lock feeds only `carryForwardComposedArtifacts`.
+ */
+export function parsePreviousImageLock(schemas, document) {
+  const lenientAuthority = schemas.KernelContractAuthoritySchema.extend({ repositoryUrl: z.string().min(1) });
+  const authority = lenientAuthority.safeParse(document?.contractAuthority);
+  if (!authority.success) {
+    throw new Error(
+      `Invalid images.lock.json: ${authority.error.issues.map((issue) => `[contractAuthority.${issue.path.join('.')}] ${issue.message}`).join('; ')}`,
+    );
+  }
+  // The strict parse sees the current repository URL in the authority's place, so it judges every other field; the previous
+  // lock's own authority is then put back.
+  const parsed = schemas.parseImageLock({
+    ...document,
+    contractAuthority: { ...authority.data, repositoryUrl: schemas.XEMA_KERNEL_CONTRACT_REPOSITORY_URL },
+  });
+  return { ...parsed, contractAuthority: authority.data };
+}