@xemahq/kernel-contracts 0.7.0 → 0.9.0

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

@@ -1,39 +1,58 @@
-import { z } from 'zod';
 import {
-  CapabilityRefSchema,
-  type CapabilityRef,
-} from '../../capability';
+  CAPABILITY_SLUG_PATTERN,
+  FilterExprSchema,
+} from '../../connector';
+import { ContributionKindSchema } from '../../contribution';
+import { CapabilityRefSchema } from '../../capability';
 import {
-  ContributionKind,
-  ContributionKindSchema,
-} from '../../contribution';
-import { BiomeTrustTier, BiomeTrustTierSchema } from './biome-trust-tier';
-import { BiomeEnginesSchema, type BiomeEngines } from './biome-engines';
+  ProvisioningGuardSchema,
+  ProvisioningStepKindSchema,
+  ProvisioningTriggerSchema,
+} from '../../provisioning';
 import {
-  BiomePermissionsManifestSchema,
-  type BiomePermissionsManifest,
-} from './biome-permissions';
+  MigrationRunnerKind,
+  OrgDatabasePurpose,
+} from '../../org-database';
+import {
+  DataLocalitySchema,
+  RuntimeIsolationLevelSchema,
+  RunnerTrustTier,
+} from '../../runner';
+import { z } from 'zod';
+import {
+  BiomeAudience,
+  BiomeAudienceSchema,
+  DEFAULT_BIOME_AUDIENCE,
+} from './biome-audience';
+import {
+  BiomeEnginesSchema,
+} from './biome-engines';
 import {
   BiomeLifecycleHooksSchema,
-  type BiomeLifecycleHooks,
 } from './biome-lifecycle-hooks';
-import { BiomeApiManifestSchema, type BiomeApiManifest } from './biome-api';
+import {
+  BiomePermissionsManifestSchema,
+} from './biome-permissions';
 
 /**
- * Canonical filename of the new biome manifest at the root of every
- * biome source package (plan §4.1). The legacy `xema-biome.json` name
- * is NOT recognised by this contracts package — Phase 6 (plan §17.7)
- * renames it in a single coordinated PR, with no dual parser.
+ * `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`.
+ *
+ * This is the SINGLE canonical biome-manifest schema for the platform: the
+ * `{ name, version, xema: { … } }` wrapped shape. The legacy flat
+ * `{ schemaVersion, id, name, … }` shape was deleted — there is no dual
+ * parser and no backward-compat shim. `@xemahq/biome-sdk/host` re-exports
+ * everything in this module; it owns no second copy.
  */
-export const BIOME_MANIFEST_FILENAME = 'xema-biome.json';
 
 /**
- * Schema-versioning seed for the biome manifest. Bumped via a
- * coordinated PR whenever the manifest shape changes incompatibly;
- * downstream consumers refuse manifests whose `schemaVersion` they do
- * not understand (fail-fast — no silent best-effort parse).
+ * Canonical filename of the biome manifest at the root of every biome
+ * source package. The platform validates and parses ONLY this file's
+ * top-level `{ name, version, xema }` shape; everything else in the
+ * bundle is free-form.
  */
-export type BiomeManifestSchemaVersion = 1;
+export const BIOME_MANIFEST_FILENAME = 'xema-biome.json';
 
 /**
  * Declarative event subscription entry of the biome manifest
@@ -53,50 +72,1105 @@ export const BiomeEventSubscriptionSchema = z.object({
 }) as z.ZodType<BiomeEventSubscription>;
 
 /**
- * `BiomeManifest` — the top-level shape of `xema-biome.json` (plan §4,
- * §12, §24.4, §24.5, §25). This is the NEW shape introduced in Phase
- * 1A; the SDK-side parser is still housed under `biome-host-sdk` until
- * the Phase 6 rename, but the schema itself lives here from day one.
- */
-export interface BiomeManifest {
-  schemaVersion: BiomeManifestSchemaVersion;
-  id: string;
-  name: string;
-  version: string;
-  trustTier: BiomeTrustTier;
-  engines: BiomeEngines;
-  requiresCapabilities: readonly CapabilityRef[];
-  exposesCapabilities: readonly CapabilityRef[];
-  contributes: readonly ContributionKind[];
-  subscribes?: readonly BiomeEventSubscription[];
-  /** biome-id → semver range. */
-  requires?: Readonly<Record<string, string>>;
-  permissions?: BiomePermissionsManifest;
-  lifecycle?: BiomeLifecycleHooks;
-  ships?: {
-    apis?: readonly BiomeApiManifest[];
-    content?: readonly string[];
-  };
+ * Manifest-shape biome SCOPE — the dependency/boot tier a biome declares in
+ * its `xema.scope` field. Value-identical to the kernel `BiomeTier` set
+ * (`kernel|system|base|platform`). Kept as a manifest-internal schema (not
+ * re-exported) so it does not collide with the kernel `BiomeScope`
+ * (installation scope) / `BiomeTier` (dependency tier) enums that the rest
+ * of `@xemahq/kernel-contracts/biome` already exposes.
+ *
+ * Biome tier (Layered Biome Architecture — "Linux-faithful" model):
+ *  - `kernel`   — L1 universal, mandatory. Boots before any other biome.
+ *  - `system`   — L2 system biomes (systemd / dbus / sshd analogues).
+ *  - `base`     — L2.5 foundational user-facing primitives.
+ *  - `platform` — L3 first-party domain + integration biomes.
+ */
+const ManifestBiomeScopeSchema = z.enum([
+  'kernel',
+  'system',
+  'base',
+  'platform',
+]);
+
+/**
+ * The Contribution Protocol (`@xemahq/kernel-contracts/contribution`) is the
+ * single authoritative enum for kinds a biome may ship.
+ *
+ * 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;
 }
 
-export const BiomeManifestSchema = z.object({
-  schemaVersion: z.literal(1),
-  id: z.string().min(1),
-  name: z.string().min(1),
-  version: z.string().min(1),
-  trustTier: BiomeTrustTierSchema,
-  engines: BiomeEnginesSchema,
-  requiresCapabilities: z.array(CapabilityRefSchema).readonly(),
-  exposesCapabilities: z.array(CapabilityRefSchema).readonly(),
-  contributes: z.array(ContributionKindSchema).readonly(),
-  subscribes: z.array(BiomeEventSubscriptionSchema).readonly().optional(),
+/**
+ * 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),
+    /**
+     * Relative directory (from the manifest) of this API's source tree, e.g.
+     * `./api/mailops-api`. Used by `tooling/codegen/generate-service-bootstrap.mjs`
+     * to locate where to emit the `<name>.bootstrap.generated.ts` descriptor.
+     */
+    path: z.string().min(1).optional(),
+    /**
+     * Service-bootstrap SSOT fields (consumed by `XemaServiceModule.forBiome`
+     * via the generated `BiomeServiceDescriptor`). Declaring them HERE — once,
+     * in the manifest — is what removes the duplicate string literals from each
+     * service's `app.module.ts`. All optional with safe codegen defaults.
+     */
+    displayName: z.string().min(1).optional(),
+    serviceKind: z
+      .enum(['platform-service', 'biome-api', 'cli'])
+      .optional(),
+    /** Registry names this API calls (→ descriptor.requiresServices + consumes). */
+    requiresServices: z.array(z.string().min(1)).optional(),
+    /** Capability refs this API exposes (→ descriptor.exposesCapabilities). */
+    exposesCapabilities: z.array(z.string().min(1)).optional(),
+  })
+  .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>;
+
+/**
+ * Manifest-shape 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`.
+ *
+ * Kept manifest-internal (not re-exported) so it does not collide with the
+ * kernel `BiomeTrustTier` provenance enum (`first-party | verified-store |
+ * community-store | …`) already exposed by this package.
+ */
+const ManifestBiomeTrustTierSchema = z.enum(['first-party', 'third-party']);
+
+/**
+ * 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
+ * `BiomeEventSubscription` so the SDK's manifest field and the
+ * `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. All fields are OPTIONAL.
+ *
+ * - `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).
+ *
+ * Kernel-owned types are referenced through the sibling biome contract
+ * modules — 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(),
-  ships: z
-    .object({
-      apis: z.array(BiomeApiManifestSchema).readonly().optional(),
-      content: z.array(z.string().min(1)).readonly().optional(),
-    })
-    .optional(),
-}) as z.ZodType<BiomeManifest>;
+  engines: BiomeEnginesSchema.optional(),
+  /**
+   * WHO the biome is for. `org` (default) — a normal biome available to
+   * organizations and eligible for the store. `operator` — Xema platform
+   * operators only: distribution selectors skip it (it ships only when
+   * explicitly named), it is never store-listed, hidden from org UIs, and
+   * gated to `platform_admin`. See `BiomeAudience` in `./biome-audience`.
+   */
+  audience: BiomeAudienceSchema.optional(),
+  /**
+   * Whether the biome appears in the store catalog. Defaults to `true` for
+   * `org`-audience biomes; an `operator` biome is NEVER store-listed
+   * regardless of this flag. Set `false` for a normal biome that should ship
+   * and be installable but stay out of the store (the lighter "hidden"
+   * option). Resolve via `isBiomeStoreListed` — never read raw.
+   */
+  storeListed: z.boolean().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>;
+
+/**
+ * Optional presentation metadata a biome declares for host-shell surfaces
+ * (launchpad tiles, portal biome rails, the portal-admin biome picker). It is
+ * purely cosmetic — never consulted for resolution, enablement, or routing —
+ * so every field is optional and a host may fall back to its own defaults.
+ *
+ * - `icon` is a stable key the host resolves to a glyph (the closed set of
+ *   renderable keys lives in the host shell, not here, so new biomes are never
+ *   blocked by an enum bump).
+ * - `category` groups biomes in the picker/rail (e.g. "Finance"). It is also
+ *   the seed source for distribution default portals.
+ * - `summary` is a short one-liner for tiles, distinct from the longer
+ *   freeform `description`.
+ * - `accent` is an optional CSS color token for the biome's glyph/card.
+ */
+const BiomeDisplaySchema = z
+  .object({
+    icon: z.string().min(1).optional(),
+    category: z.string().min(1).optional(),
+    summary: z.string().min(1).optional(),
+    accent: z.string().min(1).optional(),
+  })
+  .strict();
+
+export type BiomeDisplay = z.infer<typeof BiomeDisplaySchema>;
+
+const ServerBiomeXemaSchema = z
+  .object({
+    id: BiomeIdSchema,
+    displayName: z.string().min(1),
+    description: z.string().optional(),
+    display: BiomeDisplaySchema.optional(),
+    scope: ManifestBiomeScopeSchema,
+    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(),
+    /**
+     * 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: ManifestBiomeTrustTierSchema.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 the agent runtime. 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(),
+    display: BiomeDisplaySchema.optional(),
+    scope: ManifestBiomeScopeSchema,
+    target: z.literal('web'),
+    /**
+     * A platform/system web surface that renders in the org rail rather
+     * than the store. Defaults to `false`. A `systemSurface` web biome is a
+     * first-party operational surface (e.g. an admin/console panel) that the
+     * host shell mounts in the organization navigation rail; it is NOT a
+     * store-listed, org-installable biome. Resolve via `isSystemSurface` —
+     * never read raw.
+     */
+    systemSurface: 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 a web biome is a platform/system web surface that renders in the
+ * org rail rather than the store. Applies the default (`false`) when the
+ * field is omitted, and is always `false` for server biomes (the field is
+ * web-only). Never read `xema.systemSurface` raw — go through this so the
+ * default is applied in exactly one place.
+ */
+export function isSystemSurface(manifest: BiomeManifest): boolean {
+  if (manifest.xema.target !== 'web') {
+    return false;
+  }
+  return manifest.xema.systemSurface ?? false;
+}
+
+/**
+ * Effective audience of a biome, applying the default (`org`) when the
+ * manifest omits the field. Never read `xema.audience` raw — go through this so
+ * the default is applied in exactly one place.
+ */
+export function getBiomeAudience(manifest: BiomeManifest): BiomeAudience {
+  return manifest.xema.audience ?? DEFAULT_BIOME_AUDIENCE;
+}
+
+/**
+ * Whether the biome should appear in the store catalog. An `operator`-audience
+ * biome is NEVER store-listed (hidden from orgs by definition); otherwise the
+ * manifest `storeListed` flag wins, defaulting to `true`.
+ */
+export function isBiomeStoreListed(manifest: BiomeManifest): boolean {
+  if (getBiomeAudience(manifest) === BiomeAudience.Operator) {
+    return false;
+  }
+  return manifest.xema.storeListed ?? true;
+}