@xemahq/kernel-contracts 0.1.0 → 0.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xemahq/kernel-contracts",
-  "version": "0.1.0",
-  "description": "Consolidated Xema OS kernel wire contracts — pure types + zod schemas for the 22 protocol surfaces (agent-composition, agent-workspace, biome, capability, contribution, document-templates/themes, entitlement, execution-context/environment, kernel-state, llm-gateway, mcp-tool, object, policy, runner, search-source, service-registry, skill, space, subject, workflow). One package, one npm scope, per-surface subpath exports. No framework/runtime deps.",
+  "version": "0.2.0",
+  "description": "Consolidated Xema OS kernel wire contracts — pure types + zod schemas for the 32 kernel protocol surfaces. One package, one npm scope, wildcard per-surface subpath exports. No framework/runtime deps.",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -10,164 +10,33 @@
     "dist",
     "src"
   ],
-  "scripts": {
-    "clean": "rm -rf dist",
-    "build": "tsc -p tsconfig.json && node scripts/emit-awp-spec.mjs",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "lint": "eslint .",
-    "check:boundary": "node scripts/check-subpath-dag.mjs"
-  },
   "devDependencies": {
-    "@eslint/js": "catalog:",
-    "@types/node": "catalog:",
-    "eslint": "catalog:",
-    "eslint-config-prettier": "catalog:",
+    "@eslint/js": "^9.39.4",
+    "@types/node": "25.2.3",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.31.0",
-    "prettier": "catalog:",
-    "typescript": "catalog:",
-    "typescript-eslint": "catalog:"
+    "prettier": "3.6.2",
+    "typescript": "5.9.3",
+    "typescript-eslint": "^8.56.1"
   },
   "dependencies": {
-    "zod": "catalog:"
+    "zod": "^4.3.6"
   },
   "exports": {
-    "./agent-composition": {
-      "types": "./dist/agent-composition/index.d.ts",
-      "xema-source": "./src/agent-composition/index.ts",
-      "default": "./dist/agent-composition/index.js"
-    },
-    "./agent-workspace": {
-      "types": "./dist/agent-workspace/index.d.ts",
-      "xema-source": "./src/agent-workspace/index.ts",
-      "default": "./dist/agent-workspace/index.js"
-    },
-    "./biome": {
-      "types": "./dist/biome/index.d.ts",
-      "xema-source": "./src/biome/index.ts",
-      "default": "./dist/biome/index.js"
-    },
-    "./capability": {
-      "types": "./dist/capability/index.d.ts",
-      "xema-source": "./src/capability/index.ts",
-      "default": "./dist/capability/index.js"
-    },
-    "./contribution": {
-      "types": "./dist/contribution/index.d.ts",
-      "xema-source": "./src/contribution/index.ts",
-      "default": "./dist/contribution/index.js"
-    },
-    "./document-templates": {
-      "types": "./dist/document-templates/index.d.ts",
-      "xema-source": "./src/document-templates/index.ts",
-      "default": "./dist/document-templates/index.js"
-    },
-    "./document-themes": {
-      "types": "./dist/document-themes/index.d.ts",
-      "xema-source": "./src/document-themes/index.ts",
-      "default": "./dist/document-themes/index.js"
-    },
-    "./entitlement": {
-      "types": "./dist/entitlement/index.d.ts",
-      "xema-source": "./src/entitlement/index.ts",
-      "default": "./dist/entitlement/index.js"
-    },
-    "./execution-context": {
-      "types": "./dist/execution-context/index.d.ts",
-      "xema-source": "./src/execution-context/index.ts",
-      "default": "./dist/execution-context/index.js"
-    },
-    "./execution-environment": {
-      "types": "./dist/execution-environment/index.d.ts",
-      "xema-source": "./src/execution-environment/index.ts",
-      "default": "./dist/execution-environment/index.js"
-    },
-    "./kernel-state": {
-      "types": "./dist/kernel-state/index.d.ts",
-      "xema-source": "./src/kernel-state/index.ts",
-      "default": "./dist/kernel-state/index.js"
-    },
-    "./llm-gateway": {
-      "types": "./dist/llm-gateway/index.d.ts",
-      "xema-source": "./src/llm-gateway/index.ts",
-      "default": "./dist/llm-gateway/index.js"
-    },
-    "./mcp-tool": {
-      "types": "./dist/mcp-tool/index.d.ts",
-      "xema-source": "./src/mcp-tool/index.ts",
-      "default": "./dist/mcp-tool/index.js"
-    },
-    "./object": {
-      "types": "./dist/object/index.d.ts",
-      "xema-source": "./src/object/index.ts",
-      "default": "./dist/object/index.js"
-    },
-    "./policy": {
-      "types": "./dist/policy/index.d.ts",
-      "xema-source": "./src/policy/index.ts",
-      "default": "./dist/policy/index.js"
-    },
-    "./runner": {
-      "types": "./dist/runner/index.d.ts",
-      "xema-source": "./src/runner/index.ts",
-      "default": "./dist/runner/index.js"
-    },
-    "./search-source": {
-      "types": "./dist/search-source/index.d.ts",
-      "xema-source": "./src/search-source/index.ts",
-      "default": "./dist/search-source/index.js"
-    },
-    "./service-registry": {
-      "types": "./dist/service-registry/index.d.ts",
-      "xema-source": "./src/service-registry/index.ts",
-      "default": "./dist/service-registry/index.js"
-    },
-    "./skill": {
-      "types": "./dist/skill/index.d.ts",
-      "xema-source": "./src/skill/index.ts",
-      "default": "./dist/skill/index.js"
-    },
-    "./space": {
-      "types": "./dist/space/index.d.ts",
-      "xema-source": "./src/space/index.ts",
-      "default": "./dist/space/index.js"
-    },
-    "./subject": {
-      "types": "./dist/subject/index.d.ts",
-      "xema-source": "./src/subject/index.ts",
-      "default": "./dist/subject/index.js"
-    },
-    "./workflow": {
-      "types": "./dist/workflow/index.d.ts",
-      "xema-source": "./src/workflow/index.ts",
-      "default": "./dist/workflow/index.js"
+    "./*": {
+      "types": "./dist/*/index.d.ts",
+      "xema-source": "./src/*/index.ts",
+      "default": "./dist/*/index.js"
     },
     "./package.json": "./package.json"
   },
-  "typesVersions": {
-    "*": {
-      "agent-composition": ["dist/agent-composition/index.d.ts"],
-      "agent-workspace": ["dist/agent-workspace/index.d.ts"],
-      "biome": ["dist/biome/index.d.ts"],
-      "capability": ["dist/capability/index.d.ts"],
-      "contribution": ["dist/contribution/index.d.ts"],
-      "document-templates": ["dist/document-templates/index.d.ts"],
-      "document-themes": ["dist/document-themes/index.d.ts"],
-      "entitlement": ["dist/entitlement/index.d.ts"],
-      "execution-context": ["dist/execution-context/index.d.ts"],
-      "execution-environment": ["dist/execution-environment/index.d.ts"],
-      "kernel-state": ["dist/kernel-state/index.d.ts"],
-      "llm-gateway": ["dist/llm-gateway/index.d.ts"],
-      "mcp-tool": ["dist/mcp-tool/index.d.ts"],
-      "object": ["dist/object/index.d.ts"],
-      "policy": ["dist/policy/index.d.ts"],
-      "runner": ["dist/runner/index.d.ts"],
-      "search-source": ["dist/search-source/index.d.ts"],
-      "service-registry": ["dist/service-registry/index.d.ts"],
-      "skill": ["dist/skill/index.d.ts"],
-      "space": ["dist/space/index.d.ts"],
-      "subject": ["dist/subject/index.d.ts"],
-      "workflow": ["dist/workflow/index.d.ts"]
-    }
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.json && node scripts/emit-awp-spec.mjs",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "check:boundary": "node scripts/check-subpath-dag.mjs"
   }
-}
+}

package/src/agent-composition/lib/composition-workspace.ts

@@ -127,7 +127,7 @@ export interface CompositionAgentRunConfig {
  *
  * `mounts` / `seedFiles` / `inputs` carry the manifest DSL's RAW spec
  * fragment shapes verbatim. They are typed loosely here (`unknown`
- * values) on purpose: the manifest DSL (`@xemahq/workspace-manifest-dsl`)
+ * values) on purpose: the manifest DSL (`@xemahq/dsl/workspace-manifest`)
  * is a runtime package (Zod, js-yaml) and this kernel contract package
  * is dependency-free; the consuming workspace pipeline re-validates the
  * fragments with the DSL's `WorkspaceManifestSchema` when it

package/src/agent-tool-inquiry/index.ts

@@ -0,0 +1,16 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/agent-tool-inquiry-contracts — Kernel layer
+//
+// Abstract types for the AGENT_TOOL_INQUIRY InquiryKind: any tool inside
+// an active agent session that needs external input ("pause this turn,
+// ask a recipient, resume on reply") uses these contracts.
+//
+// `toolName` is a free-form string — the Kernel does NOT enumerate tool
+// names. Today's only consumer is the agent runtime's native `question`
+// tool; future custom tools register into the Platform runtime adapter
+// without changes to this package.
+//
+// Pure types + Zod. Zero runtime adapter knowledge.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/agent-tool-inquiry';

package/src/agent-tool-inquiry/lib/agent-tool-inquiry.ts

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+
+/**
+ * Identity of the agent session that initiated the tool inquiry. Used by
+ * the Platform runtime adapter to route the reply back into the right
+ * session when the inquiry resolves. Opaque from this Kernel package's
+ * perspective — the adapter knows how to interpret the fields.
+ */
+export const AgentSessionRefSchema = z.object({
+  sessionExecutorId: z.string().min(1),
+  allocationId: z.string().min(1),
+  /**
+   * Tool-request id supplied by the runtime adapter on the pause event.
+   * The adapter uses this to identify which tool invocation is waiting
+   * for a reply when multiple tools pause concurrently in one session.
+   */
+  toolRequestId: z.string().min(1),
+});
+export type AgentSessionRef = z.infer<typeof AgentSessionRefSchema>;
+
+/**
+ * Optional structured-answer constraints. When `kind === 'choice'`, the
+ * recipient picks from `choices`. When `kind === 'json'`, the reply must
+ * conform to `jsonSchema`. When omitted, the reply is free text. The
+ * adapter is responsible for translating the recipient's answer back to
+ * the tool's expected wire shape.
+ */
+export const AnswerSchemaSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('free_text') }),
+  z.object({
+    kind: z.literal('choice'),
+    choices: z.array(z.string().min(1)).min(1),
+  }),
+  z.object({
+    kind: z.literal('json'),
+    jsonSchema: z.record(z.string(), z.unknown()),
+  }),
+]);
+export type AnswerSchema = z.infer<typeof AnswerSchemaSchema>;
+
+/**
+ * Prompt payload for an AGENT_TOOL_INQUIRY. The runtime-adapter-facing
+ * fields (`agentSessionRef`) are present alongside the human-facing
+ * fields (`promptText`, `answerSchema`) so the Tasks UI and the adapter
+ * read from the same row.
+ *
+ * `toolName` is free-form — `'question'` today, extensible to anything
+ * tomorrow. The Kernel does not enumerate tool names.
+ */
+export const AgentToolInquiryPromptSchema = z.object({
+  toolName: z.string().min(1),
+  agentSlug: z.string().min(1),
+  agentSessionRef: AgentSessionRefSchema,
+  promptText: z.string(),
+  answerSchema: AnswerSchemaSchema.optional(),
+  /**
+   * Optional context blurb the adapter / agent supplies to help the
+   * recipient understand what's being asked (e.g. the last few agent
+   * actions, the surrounding job's purpose). Plain text; UI renders as
+   * markdown.
+   */
+  contextSummary: z.string().optional(),
+});
+export type AgentToolInquiryPrompt = z.infer<
+  typeof AgentToolInquiryPromptSchema
+>;
+
+/**
+ * Reply payload submitted by a recipient. The Kernel keeps the shape
+ * abstract: `replyPayload` is unknown to this package — only the runtime
+ * adapter interprets it back into a tool-specific shape.
+ *
+ * For today's `question` tool routed through the Platform runtime
+ * adapter, `replyPayload` matches the adapter's tool-reply wire shape.
+ * The adapter declares this binding internally; the Kernel does not.
+ */
+export const AgentToolInquiryReplySchema = z.object({
+  replyPayload: z.unknown(),
+});
+export type AgentToolInquiryReply = z.infer<
+  typeof AgentToolInquiryReplySchema
+>;

package/src/agent-workspace/lib/workspace-spec.ts

@@ -154,7 +154,7 @@ export interface SlotDefinition {
  * without re-resolving the composition.
  *
  * Replaces the equivalent `persistence` block carried by the legacy
- * `WorkspaceManifest` (`ManifestPersistence` in `@xemahq/workspace-manifest-dsl`).
+ * `WorkspaceManifest` (`ManifestPersistence` in `@xemahq/dsl/workspace-manifest`).
  */
 export interface WorkspacePersistenceSpec {
   /** Workspace-relative paths. No leading `/`, no `..`. */

package/src/app-runtime/index.ts

@@ -0,0 +1,8 @@
+export * from './lib/biome-install';
+export * from './lib/audience-policy';
+export * from './lib/external-subject';
+export * from './lib/delegated-session';
+export * from './lib/app-client';
+export * from './lib/app-lockfile';
+export * from './lib/branding-config';
+export * from './lib/app';

package/src/app-runtime/lib/app-client.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+
+/**
+ * `AppClient` — a client credential issued to an App for minting delegated
+ * session tokens against `app-runtime-api` (plan §5.2 / §5.3). One App may
+ * have many AppClients (e.g. distinct embed targets, distinct OIDC
+ * upstreams). The `clientSecretHash` is the verifier the runtime stores;
+ * the raw secret is returned ONCE at issue time and never persisted.
+ *
+ * `redirectUris` is the OAuth-style allow-list used by upstream auth flows;
+ * each entry MUST be a non-empty URL. Unknown / empty entries are rejected
+ * at schema parse time rather than silently coerced.
+ */
+export interface AppClient {
+  id: string;
+  appId: string;
+  clientSecretHash?: string;
+  createdAt: string;
+  displayName?: string;
+  redirectUris?: string[];
+}
+
+export const AppClientSchema = z.object({
+  id: z.string().min(1, {
+    message: 'AppClient.id must be a non-empty client identifier.',
+  }),
+  appId: z.string().min(1, {
+    message: 'AppClient.appId must be a non-empty App identifier.',
+  }),
+  clientSecretHash: z.string().min(1).optional(),
+  createdAt: z.string().datetime({
+    message:
+      'AppClient.createdAt must be a strict ISO-8601 datetime string.',
+  }),
+  displayName: z.string().min(1).optional(),
+  redirectUris: z
+    .array(
+      z.string().url({
+        message:
+          'AppClient.redirectUris[] entries must be valid URLs (non-empty).',
+      }),
+    )
+    .optional(),
+}) as z.ZodType<AppClient>;

package/src/app-runtime/lib/app-lockfile.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+
+/**
+ * `AppLockfile` — the pinned resolution emitted at every invocation
+ * boundary that involves an App (workflow run start, interactive session
+ * start, agent sub-agent spawn, app deploy) per plan §10.4. Guarantees
+ * reproducibility without forcing users to manage versions by hand.
+ *
+ * Wire shape:
+ *
+ * ```json
+ * {
+ *   "kernel": "1.0.0",
+ *   "capabilities": { "kb:page.read": "1", "workflow:run.start": "1" },
+ *   "biomes": { "xema.document-buddy": "1.4.2", "xema.software-dev": "1.5.0" },
+ *   "agents": { "code-reviewer": "3.0.0", "presenter-coach": "1.2.0" },
+ *   "workflows": { "product-development": "7.0.0" },
+ *   "deliverableSpecs": { "architecture-doc": "2.1.0" },
+ *   "skills": { "doc-editor": "1.0.4" }
+ * }
+ * ```
+ *
+ * - `kernel` is the resolved `@xemahq/kernel` major.minor.patch (semver).
+ * - `capabilities` maps each `CapabilityRef` (sans `@major`) to the chosen
+ *   `<major>` string per plan §10.2 (capabilities version like syscalls).
+ * - The remaining maps key a logical slug → the chosen published semver of
+ *   that object. Slugs are NOT typed as `XemaObjectRef` here on purpose:
+ *   the lockfile is meant to round-trip as plain JSON for replay; the
+ *   owning resolver is responsible for re-hydrating refs from `(scope,
+ *   slug, version)` at consumption time.
+ */
+export interface AppLockfile {
+  kernel: string;
+  capabilities: Record<string, string>;
+  biomes: Record<string, string>;
+  agents?: Record<string, string>;
+  workflows?: Record<string, string>;
+  deliverableSpecs?: Record<string, string>;
+  skills?: Record<string, string>;
+}
+
+const NonEmptyStringRecordSchema = z.record(z.string().min(1), z.string().min(1));
+
+export const AppLockfileSchema = z.object({
+  kernel: z.string().min(1, {
+    message: 'AppLockfile.kernel must be a non-empty semver string.',
+  }),
+  capabilities: NonEmptyStringRecordSchema,
+  biomes: NonEmptyStringRecordSchema,
+  agents: NonEmptyStringRecordSchema.optional(),
+  workflows: NonEmptyStringRecordSchema.optional(),
+  deliverableSpecs: NonEmptyStringRecordSchema.optional(),
+  skills: NonEmptyStringRecordSchema.optional(),
+}) as z.ZodType<AppLockfile>;

package/src/app-runtime/lib/app.ts

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+import {
+  CapabilityRefSchema,
+  type CapabilityRef,
+} from '../../capability';
+import {
+  ExecutionEnvironmentRefSchema,
+  type ExecutionEnvironmentRef,
+} from '../../execution-environment';
+import {
+  XemaObjectRefSchema,
+  type XemaObjectRef,
+} from '../../object';
+import { BiomeInstallSchema, type BiomeInstall } from './biome-install';
+import { AudiencePolicySchema, type AudiencePolicy } from './audience-policy';
+import { BrandingConfigSchema, type BrandingConfig } from './branding-config';
+import { AppLockfileSchema, type AppLockfile } from './app-lockfile';
+
+/**
+ * Per-App tightening on top of the base `CapabilityPolicy` carried by an
+ * `ExecutionEnvironment` (plan §5.1: `App.capabilityPolicy`). An override may
+ * narrow the allowed resource set, narrow the allowed zones, or impose an
+ * App-level rate cap on a specific capability — it may never WIDEN. The
+ * intersect-only enforcement lands in `xema-capability-router` (Phase 3 /
+ * Phase 7); this contract carries the declared shape only.
+ */
+export interface CapabilityPolicyOverride {
+  capability: CapabilityRef;
+  allowedResources?: readonly string[];
+  allowedEnvironments?: readonly ExecutionEnvironmentRef[];
+  rateLimit?: number;
+}
+
+export const CapabilityPolicyOverrideSchema = z.object({
+  capability: CapabilityRefSchema,
+  allowedResources: z.array(z.string().min(1)).readonly().optional(),
+  allowedEnvironments: z.array(ExecutionEnvironmentRefSchema).readonly().optional(),
+  rateLimit: z.number().int().positive().optional(),
+}) as z.ZodType<CapabilityPolicyOverride>;
+
+/**
+ * `App` — the top-level `XemaObjectKind.App` envelope (plan §5.1). An
+ * `(Org, Project, [Biome@version])` tuple plus configuration, branding,
+ * capability policy, audience policy, and the lockfile pin emitted at
+ * deploy time. Multiple Apps may share the same biomes; the same biome may
+ * be installed in many Apps with different audiences and zones.
+ *
+ * Invariants enforced at parse time:
+ *
+ * - `installedBiomes` MUST be non-empty — an App with zero biomes has no
+ *   capability surface, so this is a fail-fast policy bug.
+ * - `audiences` MUST be non-empty — an App with zero audiences is
+ *   unreachable; declare at least one (e.g. `InternalOrg`) explicitly.
+ * - `defaultZone` and `lockfile` are REQUIRED (no implicit default environment,
+ *   no "best-effort" un-pinned execution).
+ *
+ * Per-App tightening on top of a environment's `CapabilityPolicy` is carried by
+ * `capabilityPolicy` (intersect-only at the gateway, never widen).
+ */
+export interface App {
+  ref: XemaObjectRef;
+  installedBiomes: BiomeInstall[];
+  defaultZone: ExecutionEnvironmentRef;
+  audiences: AudiencePolicy[];
+  capabilityPolicy: CapabilityPolicyOverride[];
+  branding: BrandingConfig;
+  lockfile: AppLockfile;
+}
+
+export const AppSchema = z.object({
+  ref: XemaObjectRefSchema,
+  installedBiomes: z.array(BiomeInstallSchema).min(1, {
+    message:
+      'App.installedBiomes must contain at least one BiomeInstall; an App with zero biomes has no capability surface.',
+  }),
+  defaultZone: ExecutionEnvironmentRefSchema,
+  audiences: z.array(AudiencePolicySchema).min(1, {
+    message:
+      'App.audiences must contain at least one AudiencePolicy; an App with zero audiences is unreachable.',
+  }),
+  capabilityPolicy: z.array(CapabilityPolicyOverrideSchema),
+  branding: BrandingConfigSchema,
+  lockfile: AppLockfileSchema,
+}) as z.ZodType<App>;

package/src/app-runtime/lib/audience-policy.ts

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import {
+  ExecutionEnvironmentRefSchema,
+  type ExecutionEnvironmentRef,
+} from '../../execution-environment';
+
+/**
+ * Closed set of audience kinds an App may expose (plan §5.2):
+ *
+ * - `InternalOrg`     — Xema-identity users with project membership.
+ * - `ExternalSubject` — non-Xema subjects authenticated by the app's
+ *   own upstream (OIDC, magic-link, anon); Xema mints a delegated
+ *   session token (`sub` = external subject, `act` = app client).
+ * - `PublicAnon`      — anonymous sessions, tightly capability-constrained
+ *   (e.g. read-only KB on a marketing-FAQ chatbot).
+ *
+ * Values are stable wire strings — never compare against a free-form string.
+ */
+export enum AudienceKind {
+  InternalOrg = 'internal-org',
+  ExternalSubject = 'external-subject',
+  PublicAnon = 'public-anon',
+}
+
+export const AudienceKindSchema = z.nativeEnum(AudienceKind);
+
+/**
+ * Closed set of upstream-auth types an `ExternalSubject` audience may use.
+ * `anon` is intentionally distinct from `PublicAnon` at the `AudienceKind`
+ * level: a `PublicAnon` audience MAY use the same `anon` upstream marker
+ * here for symmetry, but the policy choice is made at the audience kind.
+ */
+export enum AudienceUpstreamType {
+  Oidc = 'oidc',
+  MagicLink = 'magic-link',
+  Anon = 'anon',
+}
+
+export const AudienceUpstreamTypeSchema = z.nativeEnum(AudienceUpstreamType);
+
+export interface AudienceUpstream {
+  type: AudienceUpstreamType;
+  metadata?: Record<string, unknown>;
+}
+
+export const AudienceUpstreamSchema = z.object({
+  type: AudienceUpstreamTypeSchema,
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}) as z.ZodType<AudienceUpstream>;
+
+export interface AudienceRateLimit {
+  perHourPerSubject?: number;
+}
+
+export const AudienceRateLimitSchema = z.object({
+  perHourPerSubject: z.number().int().positive().optional(),
+}) as z.ZodType<AudienceRateLimit>;
+
+/**
+ * `AudiencePolicy` — one row in `App.audiences[]` (plan §5.2). Declares
+ * which audience kind the app exposes, which execution zones that audience
+ * may invoke, the upstream-auth marker the app uses for non-Xema subjects,
+ * and an optional per-subject rate cap.
+ *
+ * `allowedEnvironments` is REQUIRED and non-empty: an audience with no zones is a
+ * policy bug — fail-fast at schema parse time rather than silently denying
+ * every call at the gateway.
+ */
+export interface AudiencePolicy {
+  kind: AudienceKind;
+  allowedEnvironments: readonly ExecutionEnvironmentRef[];
+  authUpstream?: AudienceUpstream;
+  rateLimit?: AudienceRateLimit;
+}
+
+export const AudiencePolicySchema = z.object({
+  kind: AudienceKindSchema,
+  allowedEnvironments: z
+    .array(ExecutionEnvironmentRefSchema)
+    .min(1, {
+      message:
+        'AudiencePolicy.allowedEnvironments must contain at least one ExecutionEnvironmentRef; an audience with zero zones is a policy bug.',
+    })
+    .readonly(),
+  authUpstream: AudienceUpstreamSchema.optional(),
+  rateLimit: AudienceRateLimitSchema.optional(),
+}) as z.ZodType<AudiencePolicy>;

package/src/app-runtime/lib/biome-install.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { XemaObjectRefSchema, type XemaObjectRef } from '../../object';
+
+/**
+ * One entry in an App's `installedBiomes[]` (plan §5.1). Binds a biome
+ * reference to a version constraint (semver-range string, §10.3 grammar:
+ * `^1.2.0` / `~1.2.0` / `1.2.0` / `latest-compatible`) plus free-form
+ * per-install configuration the biome consumes at boot.
+ *
+ * The version constraint is intentionally typed as a non-empty `string`:
+ * the constraint grammar is a runtime concern of `app-runtime-api` /
+ * `xema-store-api` (it expands during lockfile resolution per §10.4), not a
+ * compile-time refinement. The lockfile (`AppLockfile`) carries the pinned
+ * resolution alongside.
+ */
+export interface BiomeInstall {
+  biomeRef: XemaObjectRef;
+  versionConstraint: string;
+  configuration?: Record<string, unknown>;
+}
+
+export const BiomeInstallSchema = z.object({
+  biomeRef: XemaObjectRefSchema,
+  versionConstraint: z.string().min(1, {
+    message:
+      'BiomeInstall.versionConstraint must be a non-empty semver-range string (e.g. `^1.2.0`, `1.2.0`, `latest-compatible`).',
+  }),
+  configuration: z.record(z.string(), z.unknown()).optional(),
+}) as z.ZodType<BiomeInstall>;