@xemahq/biome-sdk 0.1.1

package/src/host/lib/biome-manifest.ts

@@ -0,0 +1,1060 @@
+import {
+  CAPABILITY_SLUG_PATTERN,
+  FilterExprSchema,
+} from '@xemahq/kernel-contracts/connector';
+import { ContributionKindSchema } from '@xemahq/kernel-contracts/contribution';
+import { CapabilityRefSchema } from '@xemahq/kernel-contracts/capability';
+import {
+  BiomeEnginesSchema,
+  BiomeEventSubscriptionSchema,
+  BiomeLifecycleHooksSchema,
+  BiomePermissionsManifestSchema,
+  type BiomeEventSubscription,
+} from '@xemahq/kernel-contracts/biome';
+import {
+  ProvisioningGuardSchema,
+  ProvisioningStepKindSchema,
+  ProvisioningTriggerSchema,
+} from '@xemahq/kernel-contracts/provisioning';
+import {
+  MigrationRunnerKind,
+  OrgDatabasePurpose,
+} from '@xemahq/kernel-contracts/org-database';
+import {
+  DataLocalitySchema,
+  RuntimeIsolationLevelSchema,
+  RunnerTrustTier,
+} from '@xemahq/kernel-contracts/runner';
+import { z } from 'zod';
+
+/**
+ * `xema-biome.json` — declarative description of a Xema biome's
+ * identity and the contributions it ships. The schema is a discriminated
+ * union on `xema.target`.
+ */
+
+/**
+ * Biome tier (Layered Biome Architecture — plan-of-record v4.6 §22.5.7,
+ * "Linux-faithful" model):
+ *  - `kernel`      — L1 universal, mandatory. Must boot before any other biome.
+ *                    Analogue: vmlinuz / the Linux kernel image.
+ *  - `system`      — L2 system biomes (Wave 18): the systemd / dbus / sshd /
+ *                    libc analogues. Independent biomes that boot after the
+ *                    kernel and before any base/domain biome. Examples:
+ *                    identity (referenced as external submodule), audit,
+ *                    biome-host, biome-fetcher, public-gateway,
+ *                    workload-runtime, authorization, …
+ *  - `base`        — L2.5 base biomes (Wave 16E-3, Wave 17): foundational
+ *                    user-facing primitives any domain biome may depend on
+ *                    (agent-runtime, integration-platform, document-rendering,
+ *                    workflow-runtime). Linux analogy: shared libraries +
+ *                    high-level daemons (libsystemd, libdbus).
+ *  - `platform`    — L3 first-party domain biomes (software-dev, …) and
+ *                    integration biomes (integration-<provider>/…).
+ *  - `third-party` — external (future: npm or git).
+ */
+export const BiomeScopeSchema = z.enum([
+  'kernel',
+  'system',
+  'base',
+  'platform',
+  'third-party',
+]);
+export type BiomeScope = z.infer<typeof BiomeScopeSchema>;
+
+/** Target the biome executes in. */
+export const BiomeTargetSchema = z.enum(['server', 'web']);
+export type BiomeTarget = z.infer<typeof BiomeTargetSchema>;
+
+/**
+ * The Contribution Protocol (`@xemahq/kernel-contracts/contribution`) is the
+ * single authoritative enum for kinds a biome may ship; `ContributionKind`
+ * is re-exported from this package's `index.ts`.
+ *
+ * Conventional on-disk directory name per `ships.content[]` / `ships.modules[]`
+ * string. Used ONLY for the `ships`-based file-walk seeders that have not yet
+ * migrated to the `contributions/` directory protocol. New code MUST use the
+ * `xema.contributions` block (or inline contributions) instead of
+ * `ships.content` / `ships.modules`.
+ *
+ * Keys are the camelCase tokens accepted in `xema-biome.json`; the mapping
+ * returns `null` for any key it does not recognise so callers can fail fast.
+ */
+const LEGACY_SHIPS_CONTENT_DIR: Readonly<Record<string, string>> = {
+  agents: 'agents',
+  workflowConfig: 'workflow-config',
+  deliverableSpecs: 'deliverable-specs',
+  workspaceManifests: 'workspace-manifests',
+  workspaceManifestTemplates: 'workspace-manifest-templates',
+  toolProfiles: 'tool-profiles',
+  mcpCatalog: 'mcp-catalog',
+  mcpTools: 'mcp-tools',
+  openCodeSkills: 'skills',
+  openCodeTools: 'opencode-tools',
+  openCodePlugins: 'opencode-plugins',
+  roleCapabilities: 'role-capabilities',
+  artifactTypes: 'artifact-types',
+  biomeInstallSchema: 'install-schema',
+  icons: 'icons',
+  projectKits: 'project-kits',
+  provisioningScaffolds: 'provisioning',
+};
+
+const LEGACY_SHIPS_MODULES_DIR: Readonly<Record<string, string>> = {
+  agents: 'agents',
+  actions: 'actions',
+  mountSourceKinds: 'mount-source-kinds',
+  deliverableSpecKinds: 'deliverable-spec-kinds',
+  runtimeMountKinds: 'runtime-mount-kinds',
+  workspaceSpecOverlay: 'workspace-spec-overlay',
+  systemOverlayContributions: 'system-overlay-contributions',
+  adapterKinds: 'adapter-kinds',
+  integrationProviders: 'integration-providers',
+};
+
+/**
+ * Resolve a legacy `ships.content[]` value to its conventional directory
+ * name, or `null` for unknown tokens. Used by the legacy file-walk
+ * catalog/seeders; new code should use the contributions protocol.
+ */
+export function contentKindToDir(kind: string): string {
+  const dir = LEGACY_SHIPS_CONTENT_DIR[kind];
+  if (!dir) {
+    throw new Error(
+      `biome-host-sdk: unknown legacy ships.content[] value "${kind}". ` +
+        `Either migrate the biome to xema.contributions or extend LEGACY_SHIPS_CONTENT_DIR.`,
+    );
+  }
+  return dir;
+}
+
+/**
+ * Resolve a legacy `ships.modules[]` value to its conventional directory
+ * name. Same legacy-only scope as `contentKindToDir`.
+ */
+export function moduleKindToDir(kind: string): string {
+  const dir = LEGACY_SHIPS_MODULES_DIR[kind];
+  if (!dir) {
+    throw new Error(
+      `biome-host-sdk: unknown legacy ships.modules[] value "${kind}". ` +
+        `Either migrate the biome to xema.contributions or extend LEGACY_SHIPS_MODULES_DIR.`,
+    );
+  }
+  return dir;
+}
+
+/**
+ * Org-managed database declaration for biomes that need a dedicated
+ * schema in a provisioned org database.
+ */
+export const BiomeDatabaseDeclarationSchema = z
+  .object({
+    purpose: z.literal(OrgDatabasePurpose.Biome),
+    runnerKind: z.literal(MigrationRunnerKind.Prisma),
+  })
+  .strict();
+export type BiomeDatabaseDeclaration = z.infer<typeof BiomeDatabaseDeclarationSchema>;
+
+/**
+ * Per-API declaration shipped under `xema.ships.apis[]` (Phase 9).
+ * Each entry becomes one subdomain (`<name>.api.<base-domain>`)
+ * served by a biome-shipped NestJS service. biome-host-api applies
+ * the Helm sub-chart at install time and writes a route-registry
+ * entry the ingress shim consults. Validated structurally here;
+ * detailed contract semantics live in `@xemahq/biome-api-sdk`.
+ */
+export const BiomeApiDeclarationSchema = z
+  .object({
+    name: z
+      .string()
+      .min(1)
+      .regex(
+        /^[a-z][a-z0-9-]*$/,
+        'API name must be lowercase kebab-case; becomes the subdomain slug',
+      ),
+    basePath: z
+      .string()
+      .regex(/^\/.*$/)
+      .optional(),
+    /** Workspace package name + port — the deployment image. */
+    image: z
+      .object({
+        package: z.string().min(1),
+        port: z.number().int().min(1).max(65_535),
+      })
+      .strict(),
+    openapiSpec: z.string().optional(),
+    scopes: z.array(z.enum(['public', 'org', 'project', 'installation'])).min(1),
+  })
+  .strict();
+export type BiomeApiDeclaration = z.infer<typeof BiomeApiDeclarationSchema>;
+
+/**
+ * Phase-C Contribution Protocol entry. The body of an
+ * `*.contribution.json` file under a biome's `contributions/` directory,
+ * or an inline entry under `xema.contributions.inline[]` in
+ * `xema-biome.json`.
+ *
+ * Validated structurally here (kind + slug + opaque manifest). The
+ * authoritative per-kind manifest validation lives in the kind-specific
+ * contracts package and is exercised at boot by the generic
+ * `BootstrapContributionsService` template (see
+ * `bootstrap-contributions-service.ts`).
+ *
+ * See `.claude/plans/following-up-the-xema-os-plan-md-abstract-stream.md` §6.C.1.
+ */
+export const BiomeContributionEntrySchema = z
+  .object({
+    kind: ContributionKindSchema,
+    /**
+     * Kind-local slug; uniqueness is per `(kind, biomeId)`. The full
+     * `<namespace>/<local-slug>` slug expected by the kernel
+     * `ContributionSlugSchema` is composed at install time by the biome
+     * host (`namespace = biomeId`).
+     */
+    id: z
+      .string()
+      .min(1)
+      .regex(
+        /^[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._-]*)*$/,
+        'Contribution id must be lowercase kebab/dot-case, optionally with nested `/` segments',
+      ),
+    manifest: z.unknown(),
+  })
+  .strict();
+export type BiomeContributionEntry = z.infer<typeof BiomeContributionEntrySchema>;
+
+/**
+ * Per-biome Contribution Protocol declaration. Either points at a
+ * `contributions/` directory containing one `*.contribution.json` per
+ * entry, OR carries the entries inline. Both forms are allowed in one
+ * manifest — directory entries are walked first, inline entries layered
+ * on top with last-write-wins on `(kind, id)` collision (the host fails
+ * fast on duplicates at boot).
+ *
+ * Phase C plan-of-record: §6.C.1.
+ */
+export const BiomeContributionsSchema = z
+  .object({
+    /**
+     * Directory under the biome root (relative path). Defaults to
+     * `./contributions` when omitted but the block is present. The host
+     * silently ignores a missing directory — empty contribution sets are
+     * legal.
+     */
+    directory: z.string().min(1).optional(),
+    /** Inline contribution entries. */
+    inline: z.array(BiomeContributionEntrySchema).optional(),
+  })
+  .strict();
+export type BiomeContributions = z.infer<typeof BiomeContributionsSchema>;
+
+export const BiomeShipsSchema = z
+  .object({
+    /**
+     * @deprecated PHASE-C-SWEEP: superseded by top-level
+     * `xema.contributions`. Kept as a free-form string array until the
+     * codemod sweep migrates every biome to the Contribution Protocol.
+     * Values are matched against `ContributionKind` at registration time.
+     */
+    content: z.array(z.string().min(1)).optional(),
+    /**
+     * @deprecated PHASE-C-SWEEP: superseded by top-level
+     * `xema.contributions`. See `content` above — same rationale.
+     */
+    modules: z.array(z.string().min(1)).optional(),
+    apis: z.array(BiomeApiDeclarationSchema).optional(),
+  })
+  .strict();
+export type BiomeShips = z.infer<typeof BiomeShipsSchema>;
+
+/**
+ * Hosting/trust posture for a server biome. Used by integration-host
+ * plumbing (Phase 7) to decide whether to load adapter-contribution
+ * modules in-process or via a sidecar deployment. Manifests authored
+ * by Xema and audited third parties may set `first-party`; everything
+ * else defaults to `third-party`.
+ */
+export const BiomeTrustTierSchema = z.enum(['first-party', 'third-party']);
+export type BiomeTrustTier = z.infer<typeof BiomeTrustTierSchema>;
+
+/**
+ * AdapterKind slug — accepts a built-in slug verbatim, plus any
+ * lowercase kebab-case slug a biome-contributed kind could register.
+ * The runtime registry in integration-adapters-api is the authority on
+ * which slugs actually resolve; manifest parsing only enforces shape.
+ */
+const AdapterKindRefSchema = z
+  .string()
+  .min(1)
+  .regex(/^[a-z][a-z0-9-]*$/, 'adapterKind must be lowercase kebab-case');
+
+/**
+ * Execution mode for a shipped agent. Mirrors the `mode:` field in the
+ * agent .md frontmatter (and the `executionMode` column in
+ * llm-registry's `agent_definitions` table). Closed enum — every agent
+ * is either the session's primary or a delegate available via the
+ * `task` tool.
+ *
+ * The on-disk convention for backwards compatibility is that a missing
+ * frontmatter `mode:` is treated as `primary`. The manifest declaration
+ * is the authoritative answer; the cross-validator
+ * (`crossValidateAgentDeclarations`) accepts a declared `primary` against
+ * a missing frontmatter mode but rejects any other mismatch.
+ */
+export const BiomeAgentModeSchema = z.enum(['primary', 'subagent']);
+export type BiomeAgentMode = z.infer<typeof BiomeAgentModeSchema>;
+
+/**
+ * Declaration of a single agent shipped by a biome. Path is implicit:
+ * `<biomeRoot>/agents/<slug>.md` (the convention enforced by
+ * `enumerateContentAcrossBiomeTree`). The slug also becomes the
+ * agent's canonical id in llm-registry, so it must match the filename.
+ *
+ * `mode` is duplicated between the manifest and the .md frontmatter on
+ * purpose: the manifest field makes the agent roster greppable and
+ * lets biome-host refuse to boot on drift; the frontmatter is what
+ * the agent-definition seeder consumes when materialising the agent
+ * into the registry. The boot-time cross-validator ensures both agree.
+ */
+export const BiomeAgentDeclarationSchema = z
+  .object({
+    slug: z
+      .string()
+      .min(1)
+      .regex(
+        /^[a-z][a-z0-9-_]*$/,
+        'agent slug must be lowercase kebab/underscore-case and match the .md basename',
+      ),
+    mode: BiomeAgentModeSchema,
+  })
+  .strict();
+export type BiomeAgentDeclaration = z.infer<typeof BiomeAgentDeclarationSchema>;
+
+const CapabilitySlugSchema = z
+  .string()
+  .min(1)
+  .regex(CAPABILITY_SLUG_PATTERN, 'capability slug must be <domain>.<verb-qualifier>');
+
+/**
+ * Declared integration dependency. The install wizard surfaces these
+ * as a consent screen; `biome-host-api` refuses to activate a
+ * `BiomeInstallation` whose non-optional requirements are not bound.
+ * `purpose` is mandatory (one short sentence) so users see *why* the
+ * biome needs the integration.
+ */
+export const IntegrationRequirementSchema = z
+  .object({
+    adapterKind: AdapterKindRefSchema,
+    optional: z.boolean().optional(),
+    purpose: z.string().min(1),
+    capabilities: z.array(CapabilitySlugSchema).min(1),
+  })
+  .strict();
+export type IntegrationRequirement = z.infer<typeof IntegrationRequirementSchema>;
+
+/**
+ * Per-(workflow, event) filter expression. The workflow YAML's
+ * `on.webhook[].event` value must match `event` here; the workflow
+ * compiler enforces this at publish time. `workflowId` is the
+ * shipped-workflow id (the `id` field inside the YAML), not a runtime
+ * `WorkflowDefinition.id`. At install time `biome-host-api` resolves
+ * the bundle and copies the relevant entries onto the
+ * `WorkflowDefinition.biomeWebhookFilters` column so the dispatcher
+ * can evaluate without re-reading the manifest.
+ */
+export const WebhookFilterSchema = z
+  .object({
+    workflowId: z
+      .string()
+      .min(1)
+      .regex(/^[a-z][a-z0-9-]*$/, 'workflowId must be lowercase kebab-case'),
+    event: z.string().min(1),
+    /**
+     * Optional canonical entity kind the filter targets (e.g. `push`,
+     * `change_request`, `item`). When set, the manifest cross-validator
+     * narrows `$envelope.*` path checking to that entity kind's
+     * payload — typos against the specific kind fail fast at boot.
+     * Omitted = union path check across every entity kind under the
+     * referenced workflow's required adapter kinds (over-permissive
+     * but still catches the obvious typo class).
+     */
+    entityKind: z.string().min(1).optional(),
+    predicate: FilterExprSchema,
+  })
+  .strict();
+export type WebhookFilter = z.infer<typeof WebhookFilterSchema>;
+
+/**
+ * Server-side capability declarations. Validated at boot for shape +
+ * closed-set membership; runtime enforcement is Phase 4 (network
+ * allow-list, MCP ACL, secret scope). Declaring intent now means every
+ * biome already states it — no migration when enforcement turns on.
+ */
+export const ServerBiomeCapabilitiesSchema = z
+  .object({
+    mcp: z.array(z.string().min(1)).optional(),
+    network: z
+      .object({ allowList: z.array(z.string().min(1)) })
+      .strict()
+      .optional(),
+    secrets: z.array(z.string().min(1)).optional(),
+  })
+  .strict();
+export type ServerBiomeCapabilities = z.infer<typeof ServerBiomeCapabilitiesSchema>;
+
+/** Web-side capability declarations. Same Phase-4 timing as server. */
+export const WebBiomeCapabilitiesSchema = z
+  .object({
+    slots: z.array(z.string().min(1)).optional(),
+    apiClients: z.array(z.string().min(1)).optional(),
+  })
+  .strict();
+export type WebBiomeCapabilities = z.infer<typeof WebBiomeCapabilitiesSchema>;
+
+/**
+ * How the `provisioning-plan-resolver` expands one scaffold declaration
+ * into resolved steps. Closed enum — `each-app-target` evaluates
+ * `selector.configPointer` against the session's `customConfig` and emits
+ * one step per matched array element (webapp-studio's `/appTargets`).
+ * Adding a strategy is a one-line schema change here plus a matching
+ * branch in the resolver.
+ */
+export const ProvisioningScaffoldMatchKindSchema = z.enum(['each-app-target']);
+export type ProvisioningScaffoldMatchKind = z.infer<
+  typeof ProvisioningScaffoldMatchKindSchema
+>;
+
+/**
+ * Declaration of one provisioning scaffold a biome ships. The scaffold
+ * *content* (command spec + template files) lives at
+ * `<biomeRoot>/provisioning/<id>.yaml`; this manifest entry is the
+ * lightweight "I ship this scaffold, and here is when/whether it runs"
+ * declaration the resolver reads.
+ *
+ * `selector` is what makes provisioning "run only if instructed" — a
+ * scaffold whose `configPointer` resolves to nothing in the session's
+ * `customConfig` never enters the plan.
+ */
+export const ProvisioningScaffoldDeclarationSchema = z
+  .object({
+    id: z
+      .string()
+      .min(1)
+      .regex(
+        /^[a-z][a-z0-9-]*$/,
+        'scaffold id must be lowercase kebab-case and match the provisioning/<id>.yaml basename',
+      ),
+    kind: ProvisioningStepKindSchema,
+    triggers: z.array(ProvisioningTriggerSchema).min(1),
+    guard: ProvisioningGuardSchema,
+    selector: z
+      .object({
+        /**
+         * JSON Pointer (RFC 6901) into the session's `customConfig`. The
+         * resolver expands the scaffold only when this resolves; for
+         * `each-app-target` it must resolve to an array.
+         */
+        configPointer: z.string().min(1),
+        matchKind: ProvisioningScaffoldMatchKindSchema,
+      })
+      .strict(),
+  })
+  .strict();
+export type ProvisioningScaffoldDeclaration = z.infer<
+  typeof ProvisioningScaffoldDeclarationSchema
+>;
+
+const BiomeIdSchema = z
+  .string()
+  .min(1)
+  .regex(/^[a-z][a-z0-9-]*$/, 'biome id must be kebab-case');
+
+/**
+ * Per-handler declarative event subscription. Type-aliased to the kernel
+ * `BiomeEventSubscription` so the SDK's manifest field and the eventual
+ * `xema-biome.json` parser share one shape. See plan §12.4.
+ */
+export type BiomeManifestSubscribe = BiomeEventSubscription;
+
+/**
+ * `requires`: biome id → semver range. Same shape as the kernel biome
+ * manifest's `requires` block (plan §12.4); the platform refuses to
+ * enable a biome/biome whose `requires` cannot be satisfied by the
+ * other enabled biomes/biomes in the org.
+ */
+export type BiomeManifestRequires = Readonly<Record<string, string>>;
+
+/**
+ * Additive XSI fields layered onto the per-target `xema` block in Phase
+ * 1A (plan §17.2 item 2). Pure additive — no rename of the SDK package
+ * itself yet (that happens in Phase 6). All fields are OPTIONAL at this
+ * phase; `engines` is promoted to required in Phase 6.
+ *
+ * - `subscribes[]` — declarative event wiring (§12.4). Each entry binds
+ *   one CloudEvents `type` to a handler module path.
+ * - `requires` — typed semver dependency declaration on other
+ *   biomes/biomes (§12.4).
+ * - `contributes[]` — closed `ContributionKind` enum from
+ *   `@xemahq/kernel-contracts/contribution`. The biome-host uses this to know
+ *   which slot registries to walk on install (§12.1).
+ * - `requiresCapabilities[]` — capability refs the biome needs the host
+ *   to grant before any of its handlers/contributions execute (§30.2).
+ * - `exposesCapabilities[]` — capability refs the biome itself
+ *   implements and offers to others (§30.2).
+ * - `permissions` — install-time consent metadata (default profile +
+ *   per-ref hints + UX groupings) for `requiresCapabilities[]` (§30.2).
+ * - `lifecycle` — module paths the host invokes on
+ *   install/upgrade/enable/disable/uninstall transitions (§24.5).
+ * - `engines.xema` — semver range the host enforces against the running
+ *   platform version (§24.4). Optional in 1A; required in Phase 6.
+ *
+ * Kernel-owned types are referenced through the kernel packages — never
+ * redefined here.
+ */
+const XsiManifestExtensionsShape = {
+  subscribes: z.array(BiomeEventSubscriptionSchema).optional(),
+  requires: z.record(z.string().min(1), z.string().min(1)).optional(),
+  contributes: z.array(ContributionKindSchema).optional(),
+  /**
+   * Phase-C Contribution Protocol entries (the actual envelopes, not just
+   * the kind whitelist). Replaces the legacy `ships.content` +
+   * `ships.modules` per-kind file-walk seeders with a single generic
+   * `BootstrapContributionsService` template; see Phase C.1 of the
+   * plan-of-record. Either inline entries or a pointer to a
+   * `contributions/` directory at the biome root.
+   */
+  contributions: BiomeContributionsSchema.optional(),
+  requiresCapabilities: z.array(CapabilityRefSchema).optional(),
+  exposesCapabilities: z.array(CapabilityRefSchema).optional(),
+  permissions: BiomePermissionsManifestSchema.optional(),
+  lifecycle: BiomeLifecycleHooksSchema.optional(),
+  engines: BiomeEnginesSchema.optional(),
+} as const;
+
+/**
+ * `runtimeRequirements` — what a biome NEEDS from the runtime/runner that
+ * executes it. This is the *requirements* half of the scheduling contract:
+ * the package states constraints; the installer decides who installs it;
+ * the runtime binding decides where it may run; the router schedules onto a
+ * matching healthy runner.
+ *
+ * HARD RULE — requirements, NEVER placement. A manifest MAY declare
+ * required/preferred labels, resource hints, allowed isolation levels,
+ * allowed data localities, and a minimum runner trust tier. It MUST NOT
+ * name a concrete target: `runtimeId`, `runnerId`, `runnerName`, `host`,
+ * `serverUrl`, or any infra address. Those are placement decisions owned by
+ * the scheduler, never the package. Enforced two ways: this object is
+ * `.strict()` (an unknown key — including any placement field — fails the
+ * parse fast) AND `tooling/boundaries/check-biome-no-placement.mjs` scans
+ * the raw manifest for forbidden keys anywhere in the tree with an
+ * actionable message.
+ *
+ * Enums are reused from `@xemahq/kernel-contracts/runner` so the requirement side
+ * (this manifest) and the capability side (a runtime/runner descriptor)
+ * speak the same closed vocabulary and can never drift.
+ */
+const RuntimeRequirementsSchema = z
+  .object({
+    /**
+     * Capability/tag labels the executing runner must (`required`) or
+     * preferably should (`preferred`) advertise — e.g.
+     * `xema.runner/docker`, `xema.runner/gpu`, `region`. Matched against a
+     * runner's advertised `labels` by the router's selector.
+     */
+    labels: z
+      .object({
+        required: z.array(z.string().min(1)).optional(),
+        preferred: z.array(z.string().min(1)).optional(),
+      })
+      .strict()
+      .optional(),
+    /**
+     * Coarse resource hints (Kubernetes-style quantity strings). Advisory
+     * scheduling input, not a hard guarantee at this phase.
+     */
+    resources: z
+      .object({
+        cpu: z.string().min(1).optional(),
+        memory: z.string().min(1).optional(),
+      })
+      .strict()
+      .optional(),
+    /**
+     * Isolation boundaries the biome ACCEPTS. A runtime whose provided
+     * isolation is not in this set is ineligible. Omit to accept any.
+     */
+    isolation: z
+      .object({
+        allowed: z.array(RuntimeIsolationLevelSchema).min(1),
+      })
+      .strict()
+      .optional(),
+    /**
+     * Data localities the biome ACCEPTS (e.g. pin to `customer-private`).
+     * A runtime/runner whose locality is not in this set is ineligible.
+     */
+    locality: z
+      .object({
+        allowed: z.array(DataLocalitySchema).min(1),
+      })
+      .strict()
+      .optional(),
+    /**
+     * Minimum attestation trust tier the executing runner must meet.
+     */
+    trustTier: z
+      .object({
+        minimum: z.nativeEnum(RunnerTrustTier),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+export type RuntimeRequirements = z.infer<typeof RuntimeRequirementsSchema>;
+
+const ServerBiomeXemaSchema = z
+  .object({
+    id: BiomeIdSchema,
+    displayName: z.string().min(1),
+    description: z.string().optional(),
+    scope: BiomeScopeSchema,
+    target: z.literal('server'),
+    /**
+     * What this biome needs from the runtime/runner that executes it
+     * (labels, resources, isolation, locality, trust). Requirements only —
+     * a manifest may NOT name a concrete runtime/runner/host (see
+     * {@link RuntimeRequirementsSchema}). Server biomes only; web biomes are
+     * static bundles served by the host shell and never run on a runner.
+     */
+    runtimeRequirements: RuntimeRequirementsSchema.optional(),
+    /**
+     * Whether biome-host must refuse to start without this biome
+     * resolving. Defaults to `true` for `scope: 'kernel'` and `false`
+     * for every other scope. Manifests may set this explicitly.
+     */
+    mandatory: z.boolean().optional(),
+    /**
+     * Server biome ids this biome depends on. Biome-host topologically
+     * sorts the server set at boot and fails fast on cycles or unsatisfied
+     * dependencies. A kernel biome may only depend on other kernel
+     * biomes (enforced by biome-host).
+     */
+    dependencies: z.array(BiomeIdSchema).optional(),
+    /**
+     * Biome id(s) this biome EXTENDS. An extending biome is the
+     * same-or-upgraded variant of the biome(s) it extends and MAY re-ship
+     * their content (agent slugs, workspace manifests, skills); when both
+     * are installed the extending biome's version takes precedence. This is
+     * the machine-readable form of the "the commercial cultivar extends this
+     * community reference biome" relationship — e.g. `document-buddy`
+     * (platform cultivar) extends `document-buddy-reference` (community
+     * reference). Distinct from `dependencies`: an extended biome need NOT be
+     * installed (the extension is self-contained), whereas a dependency must
+     * resolve at boot. `extends` is what lets the agent-slug uniqueness
+     * invariant tolerate the re-shipped slug — see
+     * tooling/boundaries/check-agent-duplication.mjs.
+     */
+    extends: z.union([BiomeIdSchema, z.array(BiomeIdSchema)]).optional(),
+    ships: BiomeShipsSchema.optional(),
+    capabilities: ServerBiomeCapabilitiesSchema.optional(),
+    /**
+     * Hosting posture for adapter-contribution modules (Phase 7). Other
+     * biome kinds ignore this field. Defaults to `third-party`.
+     */
+    trustTier: BiomeTrustTierSchema.optional(),
+    /**
+     * Integration dependencies the biome needs to be useful. Surfaced
+     * to the install wizard as a consent screen. Non-optional entries
+     * gate the `BiomeInstallation` state transition to `active`.
+     */
+    integrationRequirements: z.array(IntegrationRequirementSchema).optional(),
+    /**
+     * Per-(workflow, event) filter expressions evaluated by the
+     * workflow-engine dispatcher at webhook time. Each entry MUST
+     * resolve to a workflow shipped by this biome and an event that
+     * workflow declares under `on.webhook[].event`. The DSL compiler
+     * cross-validates at publish time; manifest parsing only enforces
+     * shape.
+     */
+    webhookFilters: z.array(WebhookFilterSchema).optional(),
+    /**
+     * Workflows the biome wants exposed as MCP tools. The MCP gateway
+     * (`mcp-gateway-api`) projects each entry into the catalog-mode
+     * tool listing surfaced to agents via OpenCode. When an agent
+     * invokes the tool, the gateway dispatches the workflow run
+     * (auto-attaching the calling installation's id, JWT-derived org
+     * + actor context) and returns the named deliverable plus an
+     * optional workspace mount entry so the result lands on disk
+     * automatically.
+     *
+     * Each `key` is unique within the biome and becomes the MCP tool
+     * id (`<biomeId>__<key>`). `workflowSlug` MUST resolve to a
+     * workflow this biome ships; the workflow-engine cross-validates
+     * at publish time. `outputProjection.deliverable.slug` picks one
+     * of the workflow's declared `produces:` entries to surface as the
+     * tool's primary content payload. The optional `mount` block
+     * issues a `POST /workspace/mounts/apply` on the calling agent's
+     * session so the result file appears under `/workspace/<slot>/...`
+     * — seamless from the agent's point of view.
+     */
+    mcpWorkflowTools: z
+      .array(
+        z
+          .object({
+            key: z
+              .string()
+              .min(1)
+              .regex(/^[a-z][a-z0-9-]*$/, 'key must be lowercase-kebab'),
+            workflowSlug: z.string().min(1),
+            displayName: z.string().min(1),
+            description: z.string().min(1),
+            outputProjection: z
+              .object({
+                kind: z.literal('deliverable'),
+                slug: z.string().min(1),
+              })
+              .strict(),
+            mount: z
+              .object({
+                slot: z.enum(['inputs', 'references', 'deliverables']),
+                as: z.string().min(1),
+              })
+              .strict()
+              .optional(),
+          })
+          .strict(),
+      )
+      .optional(),
+    /**
+     * Plain handler functions the biome's API service exposes as MCP
+     * tools. The platform wraps them via the `biome_code_tools`
+     * provider — biome authors never see MCP protocol bytes.
+     *
+     * Each entry's `key` is unique within the biome and maps to a
+     * decorated method on the biome's API service via the
+     * `@BiomeCodeTool` decorator from `@xemahq/biome-api-sdk`. The
+     * full descriptor (inputSchema, displayName, output kind) is
+     * authoritative on the biome API side and surfaced through
+     * `GET /code-tools-manifest`; this manifest entry is the
+     * lightweight "I ship this tool" declaration the platform reads
+     * at install time.
+     */
+    mcpTools: z
+      .array(
+        z
+          .object({
+            key: z
+              .string()
+              .min(1)
+              .regex(/^[a-z][a-z0-9-]*$/, 'key must be lowercase-kebab'),
+            handler: z
+              .object({
+                kind: z.literal('biome_api'),
+                method: z.enum(['POST']).default('POST'),
+              })
+              .strict(),
+          })
+          .strict(),
+      )
+      .optional(),
+    /**
+     * Tools the biome recommends are made available when a user
+     * adopts it. Surfaced in the install UX as "this biome recommends
+     * these tools" — NOT auto-injected into every session. Each entry
+     * matches the kernel `ToolSelectionEntry` shape from
+     * `@xemahq/kernel-contracts/mcp-tool`. The frontend picker drops these
+     * directly into the session's selection on user opt-in.
+     *
+     * Validation: shape-only at boot. `resourceId` references resolve
+     * at install time (e.g. biome-installation-id is materialized by
+     * biome-host-api when the installation is created). Cross-tenant
+     * misuse is blocked downstream by the resolver (Layer 2) and the
+     * PATCH-time validator (Layer 1) when the user actually adopts the
+     * selection.
+     */
+    defaultToolSelection: z
+      .array(
+        z
+          .discriminatedUnion('kind', [
+            z
+              .object({
+                kind: z.literal('provider'),
+                providerKind: z.enum([
+                  'mcp_server',
+                  'catalog',
+                  'biome_workflow_tools',
+                  'biome_code_tools',
+                ]),
+                resourceId: z.string().min(1).max(256),
+              })
+              .strict(),
+            z
+              .object({
+                kind: z.literal('tool'),
+                providerKind: z.enum([
+                  'mcp_server',
+                  'catalog',
+                  'biome_workflow_tools',
+                  'biome_code_tools',
+                ]),
+                resourceId: z.string().min(1).max(256),
+                toolName: z.string().min(1).max(256),
+              })
+              .strict(),
+          ]),
+      )
+      .max(64)
+      .optional(),
+    /**
+     * Explicit roster of agents this biome ships. Required when
+     * `ships.content` includes `'agents'`; forbidden otherwise. Each
+     * entry pins one `agents/<slug>.md` file with its execution mode
+     * (primary vs subagent).
+     *
+     * Why both this field AND the on-disk `agents/` scan exist:
+     *   - The declaration makes the roster greppable from outside the
+     *     biome tree (`grep '"slug": "build"' biomes/*\/xema-biome.json`).
+     *   - It lets biome-host fail fast at boot when an agent file is
+     *     added or removed without updating the manifest — the prior
+     *     convention silently accepted drift.
+     *   - The closed `mode` enum surfaces primary-vs-subagent intent at
+     *     install time instead of requiring readers to parse YAML
+     *     frontmatter from every .md.
+     *
+     * Cross-validated by `crossValidateAgentDeclarations` at
+     * biome-host boot; the seeder still reads frontmatter for the rest
+     * of each agent's attributes.
+     */
+    agents: z.array(BiomeAgentDeclarationSchema).optional(),
+    /**
+     * Workspace-provisioning scaffolds the biome ships (Epic A). Each
+     * entry pins one `provisioning/<id>.yaml` recipe and declares when it
+     * runs + how the resolver expands it. Required ⟺ `ships.content`
+     * includes `provisioningScaffolds`; cross-validated in `superRefine`.
+     */
+    provisioning: z.array(ProvisioningScaffoldDeclarationSchema).optional(),
+    /**
+     * Biome-specific org-managed database declaration. When present the
+     * host provisions an org database, runs the declared migrations, and
+     * injects the org database identifiers into the runtime workload env.
+     */
+    database: BiomeDatabaseDeclarationSchema.optional(),
+    /** Reserved for Phase 4 third-party signing. Validated only when present. */
+    signature: z
+      .object({
+        algorithm: z.string().min(1),
+        value: z.string().min(1),
+        keyId: z.string().min(1),
+      })
+      .strict()
+      .optional(),
+    // XSI Phase 1A additive fields. See `XsiManifestExtensionsShape`
+    // doc-comment above for the per-field meaning + plan citations.
+    ...XsiManifestExtensionsShape,
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    validateServerPluginWebhookAndIntegrationRequirements(value, ctx);
+    validateServerBiomeAgentDeclarations(value, ctx);
+    validateServerPluginProvisioningDeclarations(value, ctx);
+  });
+
+const WebBiomeXemaSchema = z
+  .object({
+    id: BiomeIdSchema,
+    displayName: z.string().min(1),
+    description: z.string().optional(),
+    scope: BiomeScopeSchema,
+    target: z.literal('web'),
+    mandatory: z.boolean().optional(),
+    /**
+     * Server biomes this web biome REQUIRES — its backend counterpart(s).
+     * Web biomes never depend on other web biomes — intentional, keeps the
+     * dependency graph two-tiered (web → server). Cross-target validation at
+     * boot ensures every referenced server id resolves in the catalog;
+     * otherwise biome-host refuses to start. Per-org, a web biome whose
+     * required server biomes are not all enabled resolves to ORPHANED.
+     */
+    requiresServerBiomes: z.array(BiomeIdSchema).optional(),
+    /**
+     * Server biomes this web biome can OPTIONALLY integrate with (e.g. a
+     * GitHub/Jira connector). The web biome stays active without them; they
+     * are NOT part of the cross-target boot validation and never cause an
+     * ORPHANED state.
+     */
+    optionalServerBiomes: z.array(BiomeIdSchema).optional(),
+    capabilities: WebBiomeCapabilitiesSchema.optional(),
+    signature: z
+      .object({
+        algorithm: z.string().min(1),
+        value: z.string().min(1),
+        keyId: z.string().min(1),
+      })
+      .strict()
+      .optional(),
+    // XSI Phase 1A additive fields — same shape on both targets so the
+    // biome-host can read them uniformly regardless of where the biome
+    // executes. See `XsiManifestExtensionsShape` above.
+    ...XsiManifestExtensionsShape,
+  })
+  .strict();
+
+export const BiomeXemaSchema = z.discriminatedUnion('target', [
+  ServerBiomeXemaSchema,
+  WebBiomeXemaSchema,
+]);
+export type BiomeXema = z.infer<typeof BiomeXemaSchema>;
+export type ServerBiomeXema = z.infer<typeof ServerBiomeXemaSchema>;
+export type WebBiomeXema = z.infer<typeof WebBiomeXemaSchema>;
+
+function validateServerPluginWebhookAndIntegrationRequirements(
+  value: ServerBiomeXema,
+  ctx: z.RefinementCtx,
+): void {
+  if (value.webhookFilters && value.webhookFilters.length > 0) {
+    const requirements = value.integrationRequirements ?? [];
+    if (requirements.length === 0) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['webhookFilters'],
+        message:
+          'webhookFilters is set but integrationRequirements is empty — a biome gating workflows on webhook events must declare which integration(s) it requires',
+      });
+    }
+  }
+  if (value.integrationRequirements && value.integrationRequirements.length > 0) {
+    const shipsInstallSchema = value.ships?.content?.includes('biomeInstallSchema') ?? false;
+    if (!shipsInstallSchema) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['ships', 'content'],
+        message:
+          'biomes declaring integrationRequirements must also ship a `biomeInstallSchema` content kind so the install wizard can render a resource-selection form',
+      });
+    }
+  }
+}
+
+function validateServerBiomeAgentDeclarations(
+  value: ServerBiomeXema,
+  ctx: z.RefinementCtx,
+): void {
+  const shipsAgents = value.ships?.content?.includes('agents') ?? false;
+  const hasAgents = (value.agents?.length ?? 0) > 0;
+  if (shipsAgents && !hasAgents) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['agents'],
+      message:
+        'ships.content includes "agents" — manifest must declare each shipped agent under `agents[]` (slug + mode). The boot-time cross-validator enforces parity with on-disk agents/*.md files.',
+    });
+  }
+  if (!shipsAgents && hasAgents) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['agents'],
+      message:
+        'agents[] is declared but ships.content does not include "agents" — add "agents" to ships.content or remove the agents[] block',
+    });
+  }
+  if (hasAgents) {
+    const slugs = new Set<string>();
+    value.agents?.forEach((decl, idx) => {
+      if (slugs.has(decl.slug)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['agents', idx, 'slug'],
+          message: `duplicate agent slug "${decl.slug}" — each slug maps to a single agents/<slug>.md file`,
+        });
+      }
+      slugs.add(decl.slug);
+    });
+  }
+}
+
+function validateServerPluginProvisioningDeclarations(
+  value: ServerBiomeXema,
+  ctx: z.RefinementCtx,
+): void {
+  const shipsProvisioning = value.ships?.content?.includes('provisioningScaffolds') ?? false;
+  const hasProvisioning = (value.provisioning?.length ?? 0) > 0;
+  if (shipsProvisioning && !hasProvisioning) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['provisioning'],
+      message:
+        'ships.content includes "provisioningScaffolds" — manifest must declare each scaffold under `provisioning[]`',
+    });
+  }
+  if (!shipsProvisioning && hasProvisioning) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['provisioning'],
+      message:
+        'provisioning[] is declared but ships.content does not include "provisioningScaffolds" — add it or remove the provisioning[] block',
+    });
+  }
+}
+
+const ManifestNameSchema = z
+  .string()
+  .min(1)
+  .regex(/^@[^/]+\/[^/]+$/, 'biome package name must be scoped');
+
+export const BiomeManifestSchema = z
+  .object({
+    name: ManifestNameSchema,
+    version: z.string().min(1),
+    xema: BiomeXemaSchema,
+  })
+  .passthrough(); // tolerate extra top-level npm fields
+
+export type BiomeManifest = z.infer<typeof BiomeManifestSchema>;
+export type ServerBiomeManifest = BiomeManifest & { xema: ServerBiomeXema };
+export type WebBiomeManifest = BiomeManifest & { xema: WebBiomeXema };
+
+export class BiomeManifestParseError extends Error {
+  readonly issues: readonly z.core.$ZodIssue[];
+  constructor(issues: readonly z.core.$ZodIssue[]) {
+    super(
+      `Invalid xema-biome.json: ${issues
+        .map((i) => `[${i.path.join('.')}] ${i.message}`)
+        .join('; ')}`,
+    );
+    this.name = 'BiomeManifestParseError';
+    this.issues = issues;
+  }
+}
+
+export function parseBiomeManifest(raw: unknown): BiomeManifest {
+  const result = BiomeManifestSchema.safeParse(raw);
+  if (!result.success) {
+    throw new BiomeManifestParseError(result.error.issues);
+  }
+  return result.data;
+}
+
+export function isServerBiomeManifest(
+  manifest: BiomeManifest,
+): manifest is ServerBiomeManifest {
+  return manifest.xema.target === 'server';
+}
+
+export function isWebBiomeManifest(
+  manifest: BiomeManifest,
+): manifest is WebBiomeManifest {
+  return manifest.xema.target === 'web';
+}
+
+/**
+ * Whether `mandatory` is true for this manifest, applying the default
+ * (kernel → true; everything else → false) when the field is omitted.
+ */
+export function isBiomeMandatory(manifest: BiomeManifest): boolean {
+  if (typeof manifest.xema.mandatory === 'boolean') {
+    return manifest.xema.mandatory;
+  }
+  return manifest.xema.scope === 'kernel';
+}