@xemahq/biome-sdk 0.1.1

package/src/host/lib/bootstrap-contributions-service.ts

@@ -0,0 +1,233 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// `BootstrapContributionsService<TKind, TManifest>` — the generic template
+// that replaces the 14 hand-rolled `*Seeder*Service` classes scattered
+// across `apps/`.
+//
+// Plan-of-record: Phase C.3 of
+// `.claude/plans/following-up-the-xema-os-plan-md-abstract-stream.md`.
+//
+// Why this template exists
+// ------------------------
+// Adding a new content kind takes exactly:
+//   - one enum entry in `ContributionKind`,
+//   - one Zod schema in the kind-specific contracts package,
+//   - one tiny `ContributionKindHandler` implementation,
+//   - one `BootstrapContributionsService` subclass that injects the
+//     handler and the contribution source.
+//
+// Framework agnosticism
+// ---------------------
+// The SDK is published as zero-runtime-dep TypeScript. We deliberately
+// avoid `@nestjs/common` at this layer so the template is reusable by:
+//   - NestJS services (via a thin `onApplicationBootstrap` adapter),
+//   - the future `xema-kernel-server` (which does not run NestJS for the
+//     bootstrap phase),
+//   - test harnesses that exercise contributions in isolation.
+//
+// The contract is a single async method `bootstrap()` that callers may
+// hook into `onApplicationBootstrap` / `OnModuleInit` / `main()` as they
+// see fit.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import {
+  type Contribution,
+  type ContributionIngestContext,
+  type ContributionKind,
+  type ContributionKindHandler,
+  AnyContributionEnvelopeSchema,
+} from '@xemahq/kernel-contracts/contribution';
+
+/**
+ * Provenance metadata for a single contribution envelope discovered during
+ * boot. Subclasses produce these in `loadContributions()`; the template
+ * stamps them through to the handler's `ingest` ctx.
+ *
+ * `envelope` is left `unknown` on purpose — the bootstrap loop validates
+ * shape via `AnyContributionEnvelopeSchema` and the kind-specific manifest
+ * via the handler's `manifestSchema`. Callers MUST NOT pre-cast.
+ */
+export interface DiscoveredContribution {
+  readonly envelope: unknown;
+  readonly biomeId: string;
+  readonly biomeVersion: string;
+  /** Optional human-readable origin string (path, URL). Diagnostics only. */
+  readonly origin?: string;
+}
+
+/**
+ * Outcome of a single `bootstrap()` pass. Returned for observability —
+ * callers may log it, surface it through `/doctor`, or assert against it
+ * in tests.
+ */
+export interface BootstrapContributionsResult {
+  readonly kind: ContributionKind;
+  readonly ingested: number;
+  readonly rejected: readonly BootstrapContributionsRejection[];
+}
+
+export interface BootstrapContributionsRejection {
+  readonly biomeId: string;
+  readonly origin: string | undefined;
+  readonly reason: string;
+}
+
+/**
+ * Error thrown when the bootstrap loop encounters a malformed envelope or
+ * a manifest that fails its kind-specific Zod schema. The template fails
+ * fast (throws) by default — consumers that prefer best-effort ingestion
+ * can override `onRejection` to swallow errors and accumulate rejections
+ * instead.
+ */
+export class BootstrapContributionsError extends Error {
+  public readonly biomeId: string;
+  public readonly origin: string | undefined;
+  public override readonly cause: unknown;
+
+  public constructor(args: {
+    message: string;
+    biomeId: string;
+    origin?: string;
+    cause?: unknown;
+  }) {
+    super(args.message);
+    this.name = 'BootstrapContributionsError';
+    this.biomeId = args.biomeId;
+    this.origin = args.origin;
+    this.cause = args.cause;
+  }
+}
+
+/**
+ * Generic boot-time template. Subclasses provide:
+ *   1. `handler` — the per-kind ingestion handler (with Zod schema).
+ *   2. `loadContributions()` — discover candidate envelopes from disk,
+ *      biome manifests, or a fixture set.
+ *
+ * The template owns the validation + dispatch loop. Implementations of
+ * `handler.ingest` may assume the envelope is fully type-checked.
+ *
+ * Idempotency note
+ * ----------------
+ * The template re-walks contributions on every `bootstrap()` call. Handlers
+ * MUST treat duplicate registrations as no-ops or fail-fast on
+ * conflict — the template does NOT dedupe across calls.
+ */
+export abstract class BootstrapContributionsService<
+  TKind extends ContributionKind,
+  TManifest,
+> {
+  protected abstract readonly handler: ContributionKindHandler<TManifest, TKind>;
+
+  /**
+   * Discover candidate envelopes. Subclasses typically scan biome
+   * `contributions/` directories or read a JSON manifest; tests may return
+   * an in-memory fixture set.
+   *
+   * Envelopes that do not match `handler.kind` are SILENTLY ignored by
+   * the dispatcher — the template assumes the caller is a kind-specific
+   * service that loads ALL contributions and filters by kind itself. This
+   * is intentional: the same `contributions/` directory feeds many
+   * handlers, and forcing every loader to pre-filter would duplicate the
+   * walk logic in every subclass.
+   */
+  protected abstract loadContributions(): Promise<readonly DiscoveredContribution[]>;
+
+  /**
+   * Run the bootstrap pass. Designed to be called from NestJS's
+   * `onApplicationBootstrap` (after every provider is ready) or from a
+   * standalone process's `main()`. Returns the ingestion result so
+   * callers can log / assert against it.
+   */
+  public async bootstrap(): Promise<BootstrapContributionsResult> {
+    const discovered = await this.loadContributions();
+    const rejected: BootstrapContributionsRejection[] = [];
+    let ingested = 0;
+
+    for (const candidate of discovered) {
+      const envelopeParse = AnyContributionEnvelopeSchema.safeParse(
+        candidate.envelope,
+      );
+      if (!envelopeParse.success) {
+        await this.onRejection(
+          {
+            biomeId: candidate.biomeId,
+            origin: candidate.origin,
+            reason: `envelope shape invalid: ${envelopeParse.error.message}`,
+          },
+          rejected,
+        );
+        continue;
+      }
+
+      const envelope = envelopeParse.data;
+      if (envelope.kind !== this.handler.kind) {
+        // Cross-kind envelope intentionally ignored — see `loadContributions`
+        // doc-comment.
+        continue;
+      }
+
+      const manifestParse = this.handler.manifestSchema.safeParse(
+        envelope.manifest,
+      );
+      if (!manifestParse.success) {
+        await this.onRejection(
+          {
+            biomeId: candidate.biomeId,
+            origin: candidate.origin,
+            reason: `manifest invalid for kind "${envelope.kind}": ${manifestParse.error.message}`,
+          },
+          rejected,
+        );
+        continue;
+      }
+
+      const typedContribution: Contribution<TKind, TManifest> = {
+        kind: this.handler.kind,
+        slug: envelope.slug,
+        source: envelope.source,
+        version: envelope.version,
+        manifest: manifestParse.data,
+      };
+
+      const ctx: ContributionIngestContext = {
+        biomeId: candidate.biomeId,
+        biomeVersion: candidate.biomeVersion,
+      };
+
+      await this.handler.ingest(typedContribution, ctx);
+      ingested += 1;
+    }
+
+    return {
+      kind: this.handler.kind,
+      ingested,
+      rejected,
+    };
+  }
+
+  /**
+   * Default rejection policy — fail-fast. Throws a structured error that
+   * carries the biome id and origin for diagnostics. Subclasses MAY
+   * override to accumulate rejections instead of throwing (e.g. a
+   * non-mandatory biome whose contribution failed validation should not
+   * take down the whole boot).
+   */
+  protected async onRejection(
+    rejection: BootstrapContributionsRejection,
+    accumulator: BootstrapContributionsRejection[],
+  ): Promise<void> {
+    accumulator.push(rejection);
+    const errorArgs: {
+      message: string;
+      biomeId: string;
+      origin?: string;
+    } = {
+      message: `Contribution rejected for kind "${this.handler.kind}" from biome "${rejection.biomeId}": ${rejection.reason}`,
+      biomeId: rejection.biomeId,
+    };
+    if (rejection.origin !== undefined) {
+      errorArgs.origin = rejection.origin;
+    }
+    throw new BootstrapContributionsError(errorArgs);
+  }
+}

package/src/host/lib/default-state.ts

@@ -0,0 +1,40 @@
+import type { BiomeManifest } from './biome-manifest';
+
+/**
+ * Pure resolver: given a biome manifest, returns whether it should be
+ * enabled by default in the absence of any per-org override. Used by
+ * `biome-host-api`'s state resolver and (in Phase 2) by the IaC
+ * reconciler to compute the seed state of a new install.
+ *
+ * Rules:
+ *   - mandatory biomes (kernel + any explicitly mandatory) always
+ *     resolve to enabled — defence-in-depth alongside the boot guard
+ *     and write-time refusal of `disable` on mandatory biomes.
+ *   - kernel, system, base, and platform scopes default to enabled.
+ *     `system` biomes (Wave 18 — the systemd / dbus / sshd / libc
+ *     analogues) are the always-on userspace base that every base and
+ *     domain biome assumes is present; defaulting them to disabled would
+ *     be like shipping a Linux box with dbus masked. Base biomes (L2.5 —
+ *     Wave 16E-3) are foundational primitives any biome may depend on;
+ *     disabling one would break every domain biome that consumes it.
+ *   - `system` here means "on by tier"; the *undisableable* subset is
+ *     expressed orthogonally by `mandatory: true` (the dbus-vs-sshd
+ *     distinction — a system biome may still be admin-disabled unless it
+ *     also declares `mandatory`). See `enablement-resolver`'s
+ *     `computeFixedReason`.
+ *   - third-party defaults to disabled until install (Phase 4).
+ *
+ * No silent fallback — an unknown scope is a programmer error and
+ * resolves to `false`, which surfaces in the admin UI as "disabled by
+ * default" rather than silently defaulting to enabled.
+ */
+export function defaultEnabledFor(manifest: BiomeManifest): boolean {
+  const xema = manifest.xema;
+  if (xema.mandatory === true) return true;
+  if (xema.scope === 'kernel') return true;
+  if (xema.scope === 'system') return true;
+  if (xema.scope === 'base') return true;
+  if (xema.scope === 'platform') return true;
+  if (xema.scope === 'third-party') return false;
+  return false;
+}

package/src/host/lib/integration-cross-validate.ts

@@ -0,0 +1,140 @@
+import {
+  collectFilterExprPathRefs,
+  isAllowedEnvelopePath,
+  type AdapterKindRef,
+} from '@xemahq/kernel-contracts/connector';
+
+import type { ServerBiomeManifest, WebhookFilter } from './biome-manifest';
+
+/**
+ * Subset of `WorkflowDocument` (from `@xemahq/dsl/workflow`) this
+ * validator needs. We avoid importing the DSL here so this SDK stays
+ * dependency-free at the kernel layer; the caller passes already-parsed
+ * workflow documents.
+ */
+export interface ShippedWorkflowSummary {
+  /** The id used inside the YAML's `metadata.name`. */
+  readonly id: string;
+  /** The webhook event slugs declared under `on.webhook[].event`. */
+  readonly webhookEvents: readonly string[];
+  /**
+   * The `requires.integrations[].adapterKind` slugs the workflow asks
+   * for. May be empty for workflows that don't touch external systems.
+   */
+  readonly requiredAdapterKinds: readonly string[];
+}
+
+export class IntegrationCrossValidationError extends Error {
+  readonly issues: readonly string[];
+  constructor(biomeId: string, issues: readonly string[]) {
+    super(
+      `biome "${biomeId}": integration cross-validation failed:\n  - ${issues.join('\n  - ')}`,
+    );
+    this.name = 'IntegrationCrossValidationError';
+    this.issues = issues;
+  }
+}
+
+/**
+ * Cross-check a server biome manifest against the workflow documents
+ * it ships. Fails fast on the four invariants the plan locks in:
+ *
+ *  1. Every workflow's `requires.integrations[].adapterKind` MUST be
+ *     declared in the manifest's `integrationRequirements[]`.
+ *  2. Every `webhookFilters[].workflowId` MUST resolve to a shipped
+ *     workflow id.
+ *  3. Every `webhookFilters[].event` MUST appear in the referenced
+ *     workflow's `on.webhook[].event` set.
+ *  4. A manifest with `webhookFilters` MUST also declare at least one
+ *     `integrationRequirements` entry. (Shape rule the Zod schema
+ *     already enforces; restated here so the error message lands on
+ *     the biome-host boot path instead of the parse path.)
+ *
+ * Returns nothing on success; throws `IntegrationCrossValidationError`
+ * with the full issue list on failure so biome-host refuses to start
+ * with all problems reported at once.
+ */
+export function crossValidateIntegrationContract(
+  manifest: ServerBiomeManifest,
+  workflows: readonly ShippedWorkflowSummary[],
+): void {
+  const issues: string[] = [];
+  const requirements = manifest.xema.integrationRequirements ?? [];
+  const webhookFilters: readonly WebhookFilter[] = manifest.xema.webhookFilters ?? [];
+  const requirementKinds = new Set(requirements.map((r) => r.adapterKind));
+  const workflowsById = new Map(workflows.map((w) => [w.id, w]));
+
+  // (1) workflow requires.integrations ⊆ manifest integrationRequirements
+  for (const workflow of workflows) {
+    for (const kind of workflow.requiredAdapterKinds) {
+      if (!requirementKinds.has(kind)) {
+        issues.push(
+          `workflow "${workflow.id}" declares requires.integrations.adapterKind="${kind}" ` +
+            `but the manifest does not list it under integrationRequirements`,
+        );
+      }
+    }
+  }
+
+  // (2) + (3) webhookFilters reference real (workflowId, event) pairs
+  // (4) every $envelope path in the predicate is permitted for at
+  //     least one of the workflow's required AdapterKinds — fails fast
+  //     on typos like `$envelope.branchName` (real field: `branch`).
+  for (const filter of webhookFilters) {
+    const workflow = workflowsById.get(filter.workflowId);
+    if (!workflow) {
+      issues.push(
+        `webhookFilters entry references workflowId="${filter.workflowId}" ` +
+          `which is not among the shipped workflows`,
+      );
+      continue;
+    }
+    if (!workflow.webhookEvents.includes(filter.event)) {
+      issues.push(
+        `webhookFilters entry for workflow "${filter.workflowId}" references event="${filter.event}" ` +
+          `which is not declared under that workflow's on.webhook[].event set ` +
+          `(known events: ${workflow.webhookEvents.join(', ') || '(none)'})`,
+      );
+    }
+    collectPredicatePathIssues(filter, workflow.requiredAdapterKinds, issues);
+  }
+
+  if (issues.length > 0) {
+    throw new IntegrationCrossValidationError(manifest.xema.id, issues);
+  }
+}
+
+/**
+ * Walk the filter's predicate AST and push an issue for every
+ * `$envelope.<path>` that none of the workflow's required adapter
+ * kinds accepts. Workflows declaring zero `requires.integrations[]`
+ * skip path validation — there is no schema to check against. Biome-
+ * contributed adapter kinds whose schema isn't registered fall back
+ * to "allow" inside `isAllowedEnvelopePath`, so this only catches the
+ * built-in-kind typo class.
+ */
+function collectPredicatePathIssues(
+  filter: WebhookFilter,
+  requiredAdapterKinds: readonly AdapterKindRef[],
+  issues: string[],
+): void {
+  if (requiredAdapterKinds.length === 0) return;
+  const entityKind = filter.entityKind;
+  const paths = collectFilterExprPathRefs(filter.predicate);
+  for (const ref of paths) {
+    if (ref.source !== '$envelope') continue;
+    const acceptedBy = requiredAdapterKinds.filter((kind) =>
+      isAllowedEnvelopePath(kind, ref.path, entityKind),
+    );
+    if (acceptedBy.length === 0) {
+      const scope = entityKind
+        ? `(adapterKind in [${requiredAdapterKinds.join(', ')}], entityKind="${entityKind}")`
+        : `any required adapterKind (${requiredAdapterKinds.join(', ')})`;
+      issues.push(
+        `webhookFilters entry for workflow "${filter.workflowId}" event="${filter.event}" ` +
+          `references $envelope.${ref.path} which is not a known field on the canonical ` +
+          `envelope for ${scope}`,
+      );
+    }
+  }
+}

package/src/host/lib/system-overlay-contribution.ts

@@ -0,0 +1,53 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Biome extension surface: system-overlay contributions ──
+//
+// Pluggable section-2c entries for the LLM-readable Xema system overlay
+// (`/workspace/.xema/system-overlay.md`). A first- or third-party biome
+// may register one or more contributions to inject domain-specific
+// platform rules (compliance overlays, sub-app envelopes, …) into every
+// Xema run that loads the biome.
+//
+// Biomes declare this module by listing `systemOverlayContributions`
+// in `xema.ships.modules[]` of their `xema-biome.json`. The convention
+// loads `<biomeRoot>/dist/system-overlay-contributions/index.js`; its
+// default export is an array of `SystemOverlayContribution`s. The
+// biome-host merges every contribution into the composer's section-2c
+// phase, sorted by `priority` (descending).
+//
+// Contributions are rendered as plain markdown — the composer adds no
+// section header beyond what the contribution itself emits.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Minimal run-context handed to a contribution's `render`. Kept narrow
+ * so the contribution stays a pure function of its declared inputs;
+ * adding new fields here is an opt-in, additive change.
+ */
+export interface SystemOverlayRunContext {
+  readonly orgId: string;
+  readonly projectId: string | null;
+  readonly role: string;
+  readonly surface: string;
+  readonly phaseKey: string | null;
+  readonly runId: string | null;
+}
+
+/**
+ * One section that a biome contributes to system overlay 2c.
+ *
+ * `render` returns either a non-empty string (markdown) or `null` when
+ * the contribution does not apply to the current run. The composer skips
+ * `null` outputs entirely; an empty string is treated as a contribution
+ * misconfiguration and refused (use `null` for "skip").
+ */
+export interface SystemOverlayContribution {
+  /** Stable id for the contribution; used for diagnostics + dedup. */
+  readonly id: string;
+  /**
+   * Higher numbers render earlier within section 2c. Default-ranked
+   * contributions should pick a priority in the 0–999 range; reserve
+   * ≥1000 for platform-critical rules (e.g. legal/compliance).
+   */
+  readonly priority: number;
+  readonly render: (ctx: SystemOverlayRunContext) => string | null;
+}

package/src/host/lib/topology.ts

@@ -0,0 +1,174 @@
+import type { BiomeManifest, ServerBiomeManifest } from './biome-manifest';
+
+/**
+ * Tier order for boot-time ordering: kernel boots first, then system,
+ * then base, then platform, then third-party. Used to bias the
+ * topological-sort visit order so the resulting boot sequence is stable
+ * across different valid topo-sorts.
+ *
+ * Plan-of-record v4.6 §22.5.7 ("Linux-faithful" model): `system` biomes
+ * (Wave 18) sit between kernel and base — the systemd / dbus / sshd /
+ * libc analogues. Base biomes (L2.5) sit between system and platform.
+ * Domain biomes may depend on every layer below them; lower layers MUST
+ * NOT depend on higher layers.
+ */
+export const TIER_ORDER: Readonly<Record<string, number>> = {
+  kernel: 0,
+  system: 1,
+  base: 2,
+  platform: 3,
+  'third-party': 4,
+};
+
+/**
+ * For each scope, the set of scopes a biome of that scope MAY depend on.
+ * Plan-of-record v4.6 §22.5.8 dependency rules:
+ *   - kernel       → kernel only
+ *   - system       → kernel, system
+ *   - base         → kernel, system, base
+ *   - platform     → kernel, system, base, platform
+ *   - third-party  → kernel, system, base, platform, third-party
+ */
+const ALLOWED_DEPENDENCY_SCOPES: Readonly<Record<string, ReadonlySet<string>>> = {
+  kernel: new Set(['kernel']),
+  system: new Set(['kernel', 'system']),
+  base: new Set(['kernel', 'system', 'base']),
+  platform: new Set(['kernel', 'system', 'base', 'platform']),
+  'third-party': new Set(['kernel', 'system', 'base', 'platform', 'third-party']),
+};
+
+/**
+ * Generic dependency-layering check used by every scope. A biome may only
+ * depend on biomes whose scope sits AT or BELOW its own per
+ * `ALLOWED_DEPENDENCY_SCOPES`. Returns the offending dependency ids, if any.
+ * Server-only — web biomes use `requiresServerBiomes` (refs into the server
+ * tier, no nested deps).
+ *
+ * Plan-of-record v4.6 §22.5.8 ("Linux-faithful" dependency rules):
+ *   - kernel       → kernel only
+ *   - system       → kernel, system
+ *   - base         → kernel, system, base
+ *   - platform     → kernel, system, base, platform
+ *   - third-party  → kernel, system, base, platform, third-party
+ */
+export function findIllegalDependencies(
+  manifest: ServerBiomeManifest,
+  allManifestsById: ReadonlyMap<string, ServerBiomeManifest>,
+): string[] {
+  const allowed = ALLOWED_DEPENDENCY_SCOPES[manifest.xema.scope];
+  if (!allowed) return [];
+  const deps = manifest.xema.dependencies ?? [];
+  const illegal: string[] = [];
+  for (const depId of deps) {
+    const dep = allManifestsById.get(depId);
+    if (!dep) continue; // missing dep handled by the dep-resolver pass
+    if (!allowed.has(dep.xema.scope)) {
+      illegal.push(depId);
+    }
+  }
+  return illegal;
+}
+
+/**
+ * Topological sort of server biomes by dependency, biased by tier so
+ * kernel biomes land before platform biomes before third-party biomes
+ * for any free choice in the topo order. Cycles fail fast.
+ *
+ * Web biomes are never topo-sorted: they only declare cross-target refs
+ * (`requiresServerBiomes`) and no nested deps among themselves.
+ */
+export function topoSortServerBiomes(
+  manifestsById: ReadonlyMap<string, ServerBiomeManifest>,
+): string[] {
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+  const result: string[] = [];
+
+  function visit(id: string, stack: string[]): void {
+    if (visited.has(id)) return;
+    if (visiting.has(id)) {
+      throw new Error(
+        `biome-host: dependency cycle detected: ${[...stack, id].join(' → ')}`,
+      );
+    }
+    const m = manifestsById.get(id);
+    if (!m) return;
+    visiting.add(id);
+    for (const depId of m.xema.dependencies ?? []) {
+      visit(depId, [...stack, id]);
+    }
+    visiting.delete(id);
+    visited.add(id);
+    result.push(id);
+  }
+
+  // Visit in stable id order biased by tier so the sort is deterministic.
+  const ids = Array.from(manifestsById.keys()).sort((a, b) => {
+    const ma = manifestsById.get(a);
+    const mb = manifestsById.get(b);
+    if (!ma || !mb) return a.localeCompare(b);
+    const ta = TIER_ORDER[ma.xema.scope] ?? 99;
+    const tb = TIER_ORDER[mb.xema.scope] ?? 99;
+    if (ta !== tb) return ta - tb;
+    return a.localeCompare(b);
+  });
+  for (const id of ids) visit(id, []);
+  return result;
+}
+
+/**
+ * Validate every declared server-biome dependency resolves to a known
+ * manifest. Throws on the first unsatisfied dep with a clear message.
+ */
+export function validateServerDependencies(
+  manifestsById: ReadonlyMap<string, ServerBiomeManifest>,
+): void {
+  for (const manifest of manifestsById.values()) {
+    const deps = manifest.xema.dependencies ?? [];
+    for (const depId of deps) {
+      if (!manifestsById.has(depId)) {
+        throw new Error(
+          `biome-host: server biome "${manifest.xema.id}" declares dependency "${depId}" ` +
+            `which is not registered. Known server biomes: [${Array.from(manifestsById.keys()).join(', ')}].`,
+        );
+      }
+    }
+    const illegal = findIllegalDependencies(manifest, manifestsById);
+    if (illegal.length > 0) {
+      const scope = manifest.xema.scope;
+      const allowed = Array.from(ALLOWED_DEPENDENCY_SCOPES[scope] ?? []).join(', ');
+      throw new Error(
+        `biome-host: ${scope} biome "${manifest.xema.id}" depends on biomes with disallowed scope ` +
+          `[${illegal.join(', ')}]. A ${scope} biome may only depend on biomes with scope: [${allowed}].`,
+      );
+    }
+  }
+}
+
+/**
+ * For each web manifest's `requiresServerBiomes`, ensure every referenced
+ * server id is present in the server catalog. Throws on the first
+ * unsatisfied ref with a clear message. `optionalServerBiomes` are NOT
+ * validated — they are best-effort integrations the web biome works without.
+ *
+ * Skipped when the server catalog is empty by deployment configuration
+ * (e.g. a cluster that doesn't host server biomes) — caller is
+ * responsible for that decision.
+ */
+export function validateWebToServerCrossDeps(
+  webManifestsById: ReadonlyMap<string, BiomeManifest>,
+  serverIds: ReadonlySet<string>,
+): void {
+  for (const manifest of webManifestsById.values()) {
+    if (manifest.xema.target !== 'web') continue;
+    const refs = manifest.xema.requiresServerBiomes ?? [];
+    for (const ref of refs) {
+      if (!serverIds.has(ref)) {
+        throw new Error(
+          `biome-host: web biome "${manifest.xema.id}" requires server biome "${ref}" ` +
+            `which is not registered. Known server biomes: [${Array.from(serverIds).join(', ')}].`,
+        );
+      }
+    }
+  }
+}