@xemahq/kernel-contracts 0.1.0

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

@@ -0,0 +1,212 @@
+import type { WorkingFileBinding } from './working-file';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Agent Workspace Protocol (AWP) — versioned WorkspaceSpec ──
+//
+// The declarative description of the `/workspace/` tree every agent session
+// runs inside. Versioned (`awp/v<n>`) and serializable so it can seed a
+// fine-tune corpus.
+//
+// Replaces the closed `WorkspaceMount` enum + the hardcoded
+// `READWRITE_MOUNT_KEYS` set in the DSL compiler. Biomes additively
+// contribute slots/sub-slots through `WorkspaceSpec` overlays at platform
+// boot — they cannot drop or modify base slots.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export enum SlotMode {
+  ReadOnly = 'read-only',
+  ReadWrite = 'read-write',
+}
+
+/**
+ * Whether a slot is included in every workspace by default (`always`) or
+ * only when a workflow explicitly mounts it (`optional`).
+ *
+ * `always` slots are auto-mounted by the renderer regardless of the
+ * workflow YAML's `with.mounts` block. The action manifest's
+ * `allowedMounts` is the per-action subset of `optional` slots that may be
+ * explicitly declared.
+ */
+export type SlotPresence = 'always' | 'optional';
+
+/**
+ * Who controls a sub-slot's contents. `user` sub-slots are populated from
+ * DSL refIds (workflow author or runtime caller); `platform` sub-slots
+ * are populated by the orchestrator adapter at session start (e.g. the
+ * OpenCode adapter writing `.opencode/biomes/`).
+ */
+export type SlotOwnership = 'user' | 'platform';
+
+/**
+ * Which runtime identifier the `git-push` policy uses as the suffix on
+ * the branch name. Closed enum so manifest overrides and callers stay
+ * type-safe. `sessionId` (default) gives session-scoped branches
+ * (`xema/session/<sessionId>`) — the right choice when each session's
+ * work is short-lived. `projectId` gives a long-lived working branch
+ * shared across sessions (`xema/webapp/<projectId>`) — used by the
+ * Webapp Studio biome where the user accumulates progress.
+ */
+export enum GitPushBranchSuffix {
+  SessionId = 'sessionId',
+  ProjectId = 'projectId',
+}
+
+/**
+ * Concurrency posture for the `git-push` policy when multiple sessions
+ * might write the same branch. `force` (default) blindly overwrites —
+ * safe for session-scoped branches because each session owns its own
+ * suffix. `lease` uses `git push --force-with-lease` so concurrent
+ * writers fail fast with a recoverable conflict instead of clobbering
+ * each other — required when multiple sessions can target the same
+ * long-lived branch (studio working branch).
+ */
+export enum GitPushConcurrencyMode {
+  Force = 'force',
+  Lease = 'lease',
+}
+
+/**
+ * How a slot's contents survive across pod recycle / session resume.
+ *
+ * - `none` (default) — ephemeral. The slot is regenerated at session
+ *   start and never persisted. Use for platform-rendered slots and for
+ *   user-data slots that are deterministic functions of the invocation
+ *   (e.g. `inputs/`).
+ * - `tarball` — captured by the existing snapshot pipeline as
+ *   per-path tarballs in MinIO (`{org}/{project}/{sessionId}/workspace/<path>.tar.gz`)
+ *   and restored on resume. Use for user-authored content that must
+ *   survive worker recycle (e.g. `deliverables/`, `uploads/`).
+ * - `git-push` — captured by pushing the slot's working tree to a
+ *   branch on the SCM remote. The branch name is
+ *   `{branchPrefix}{<branchSuffix>}` where `branchSuffix` picks the
+ *   runtime identifier (sessionId by default; projectId for studio's
+ *   long-lived working branch). `concurrencyMode` selects between
+ *   `--force` (overwrite — fine for session-scoped suffixes) and
+ *   `--force-with-lease` (fail-fast on concurrent writers — required
+ *   for shared long-lived suffixes).
+ */
+export type SlotPersistencePolicy =
+  | { readonly kind: 'none' }
+  | { readonly kind: 'tarball' }
+  | {
+      readonly kind: 'git-push';
+      readonly branchPrefix: string;
+      /** Defaults to `GitPushBranchSuffix.SessionId` when omitted. */
+      readonly branchSuffix?: GitPushBranchSuffix;
+      /** Defaults to `GitPushConcurrencyMode.Force` when omitted. */
+      readonly concurrencyMode?: GitPushConcurrencyMode;
+    };
+
+export interface SubSlotDefinition {
+  readonly key: string;
+  readonly path: string;
+  readonly allowedModes: readonly SlotMode[];
+  readonly defaultMode: SlotMode;
+  readonly ownership: SlotOwnership;
+}
+
+export interface SlotDefinition {
+  readonly key: string;
+  readonly path: string;
+  readonly presence: SlotPresence;
+  readonly allowedModes: readonly SlotMode[];
+  readonly defaultMode: SlotMode;
+  readonly subSlots?: readonly SubSlotDefinition[];
+  /**
+   * When true, the slot's `path` IS the full target file path (no
+   * sub-paths allowed). Mount entries targeting a single-file slot must
+   * have `relPath === ''`. Used for platform-rendered single-file slots
+   * like `agents-md` (`/workspace/AGENTS.md`) and `context-json`
+   * (`/workspace/context.json`).
+   */
+  readonly singleFile?: boolean;
+  /**
+   * Who controls this slot's contents. Mirrors `SubSlotDefinition.ownership`.
+   * `platform` slots are populated by platform-rendered sources (e.g.
+   * `rendered-agents-md`, `agent-definition`); `user` slots are populated
+   * from user-declared inputs. Optional for backward compatibility — when
+   * absent, treated as `user`.
+   */
+  readonly ownership?: SlotOwnership;
+  /**
+   * Short human-facing sentence the renderer drops into AGENTS.md so
+   * the agent knows what each mounted slot is for. Omitting it yields a
+   * bare `- /workspace/<slot>/` line — fine for platform slots that
+   * have obvious purposes; preferred for user-data slots.
+   */
+  readonly humanDescription?: string;
+  /**
+   * How this slot's contents survive across pod recycle. Defaults to
+   * `{ kind: 'none' }` (ephemeral) when omitted. The session snapshot
+   * pipeline reads this field to decide which slots to capture/restore
+   * and via which mechanism (tarball vs git push).
+   */
+  readonly persistencePolicy?: SlotPersistencePolicy;
+}
+
+/**
+ * Workspace-relative paths captured on session pause and restored on
+ * resume, plus per-slot policy overrides. The authoritative SOURCE of
+ * these values is the authored `Composition.workspace.persistence` block
+ * (`@xemahq/agent-composition-contracts`); they are projected onto
+ * `WorkspaceSpec` so workspace-tree consumers (session lifecycle,
+ * workspace-proxy snapshot pipeline) read them off one resolved spec
+ * without re-resolving the composition.
+ *
+ * Replaces the equivalent `persistence` block carried by the legacy
+ * `WorkspaceManifest` (`ManifestPersistence` in `@xemahq/workspace-manifest-dsl`).
+ */
+export interface WorkspacePersistenceSpec {
+  /** Workspace-relative paths. No leading `/`, no `..`. */
+  readonly paths: readonly string[];
+  /**
+   * Per-slot persistence policy overrides, keyed by AWP slot key
+   * (`repos`, etc.). Only `git-push` slots are overridable — `none` /
+   * `tarball` carry no fields to tune. An override never widens the
+   * slot's allowed modes; it only refines branch naming + concurrency.
+   */
+  readonly overrides?: Readonly<Record<string, SlotPersistencePolicy>>;
+}
+
+/**
+ * A single environment variable applied to the agent runtime before
+ * dispatch. `name` is SCREAMING_SNAKE_CASE; `value` is the resolved
+ * literal (the composition author may have used `${input.x}`
+ * interpolation, but the projected spec carries resolved values only).
+ */
+export interface WorkspaceEnvVar {
+  readonly name: string;
+  readonly value: string;
+}
+
+export interface WorkspaceSpec {
+  readonly id: string;
+  readonly version: string;
+  readonly slots: readonly SlotDefinition[];
+  /**
+   * Workspace-relative persist-paths + per-slot policy overrides.
+   * Projected from `Composition.workspace.persistence`. Optional — when
+   * absent the workspace persists only what the slots' own
+   * `persistencePolicy` fields declare. Additive: pre-existing consumers
+   * that never read this field keep compiling.
+   */
+  readonly persistence?: WorkspacePersistenceSpec;
+  /**
+   * Environment variables applied to the agent runtime before dispatch.
+   * Projected from `Composition.workspace.env`. Optional / additive —
+   * absent means the composition declared no env block.
+   */
+  readonly env?: readonly WorkspaceEnvVar[];
+  /**
+   * Working files the platform materialises before the agent's first
+   * turn — the first-class primitive that replaces the legacy
+   * document-sync hardcoded path. Each binding's resolved `path`
+   * contributes to `authority.mayWriteWorkspace` (write authority
+   * narrowed by contract, not by prompt prose).
+   *
+   * Optional / additive — compositions that do not declare a working
+   * file produce no entries, and the worker's working-file engine stays
+   * idle for that session.
+   */
+  readonly workingFiles?: readonly WorkingFileBinding[];
+}

package/src/biome/index.ts

@@ -0,0 +1,10 @@
+export * from './lib/biome-capability-refs';
+export * from './lib/biome-lifecycle';
+export * from './lib/biome-scope';
+export * from './lib/biome-trust-tier';
+export * from './lib/biome-api';
+export * from './lib/biome-lifecycle-hooks';
+export * from './lib/biome-engines';
+export * from './lib/biome-permissions';
+export * from './lib/biome-manifest';
+export * from './lib/trust-tier-policies';

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

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+
+/**
+ * `BiomeApiManifest` — one entry of the biome manifest's `ships.apis[]`
+ * array (plan §25.1). A biome may ship zero, one, or many NestJS
+ * services; each becomes its own Helm sub-chart, its own Docker image,
+ * its own subdomain (`<biomeId>.<name>.api.<domain>`), and its own
+ * capability namespace (`biome:<biomeId>.<apiName>.<verb>@1`).
+ *
+ * `scopes` is the closed list of capability verb scopes this API
+ * advertises. Strings are intentional here (not a TS enum) because the
+ * value space is biome-author-defined; the kernel only validates the
+ * outer shape.
+ */
+export interface BiomeApiManifest {
+  name: string;
+  basePath: string;
+  image: {
+    package: string;
+    port: number;
+  };
+  scopes: readonly string[];
+}
+
+export const BiomeApiManifestSchema = z.object({
+  name: z.string().min(1),
+  basePath: z.string().min(1),
+  image: z.object({
+    package: z.string().min(1),
+    port: z.number().int().positive(),
+  }),
+  scopes: z.array(z.string().min(1)).readonly(),
+}) as z.ZodType<BiomeApiManifest>;

package/src/biome/lib/biome-capability-refs.ts

@@ -0,0 +1,29 @@
+/**
+ * `BIOME_CAPABILITY_REFS` — the closed set of capability refs guarding
+ * biome-lifecycle transitions (plan §4.2, §17.7 Phase 6). Each transition
+ * out of `draft`/`sandbox-installed` requires the corresponding capability
+ * check at `xema-capability-router`; promote-out-of-sandbox defaults to
+ * `requiresApproval=true`.
+ *
+ * Frozen so consumers (biome-host-api lifecycle controller, store, UI)
+ * cannot mutate the ref strings at runtime.
+ */
+export const BIOME_CAPABILITY_REFS = Object.freeze({
+  Install: 'biome:install@1',
+  Promote: 'biome:promote@1',
+  SubmitToStore: 'biome:submit-to-store@1',
+  ApproveInStore: 'biome:approve-in-store@1',
+  Archive: 'biome:archive@1',
+  /**
+   * Sandbox-environment-only real-terminal capability (plan §6.3 + §17.6 Phase
+   * 5 item 4). Guards the `WS /sandbox/terminal/:installationId`
+   * endpoint in `biome-host-api` — the ONLY PTY surface in Xema. The
+   * gateway MUST refuse the invocation when the subject's effective
+   * environment is not `sandbox`.
+   */
+  SandboxTerminal: 'biome:sandbox.terminal@1',
+} as const);
+
+export type BiomeCapabilityRefKey = keyof typeof BIOME_CAPABILITY_REFS;
+export type BiomeCapabilityRef =
+  (typeof BIOME_CAPABILITY_REFS)[BiomeCapabilityRefKey];

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

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+
+/**
+ * `BiomeEngines` — the required `engines` block of the biome manifest
+ * (plan §24.4). `xema` is a semver range; `biome-host-api` refuses to
+ * install a biome whose engine constraint is not satisfied by the
+ * running platform version. The constraint is a hard, fail-fast gate.
+ *
+ * Range syntax is not parsed here — that is the host's responsibility.
+ * The kernel only validates that the field is a non-empty string.
+ */
+export interface BiomeEngines {
+  xema: string;
+}
+
+export const BiomeEnginesSchema = z.object({
+  xema: z.string().min(1),
+}) as z.ZodType<BiomeEngines>;

package/src/biome/lib/biome-lifecycle-hooks.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+
+/**
+ * `BiomeLifecycleHooks` — the optional `lifecycle` block of the biome
+ * manifest (plan §24.5). Each value is the module path (relative to the
+ * biome package root) of a hook module that `biome-host-api` invokes at
+ * the corresponding `BiomeLifecycle` transition.
+ *
+ * Hooks run with the biome's own capability set — they cannot do
+ * anything the biome cannot do as a running participant. The kernel
+ * does not load the modules; it only validates that the manifest
+ * declares well-formed strings.
+ */
+export interface BiomeLifecycleHooks {
+  onInstall?: string;
+  onUninstall?: string;
+  onUpgrade?: string;
+  onEnable?: string;
+  onDisable?: string;
+}
+
+export const BiomeLifecycleHooksSchema = z.object({
+  onInstall: z.string().min(1).optional(),
+  onUninstall: z.string().min(1).optional(),
+  onUpgrade: z.string().min(1).optional(),
+  onEnable: z.string().min(1).optional(),
+  onDisable: z.string().min(1).optional(),
+}) as z.ZodType<BiomeLifecycleHooks>;

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

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+
+/**
+ * `BiomeLifecycle` is the closed set of deliberate, observable stages a
+ * biome (plan §4) moves through from authoring to the Xema Store and
+ * eventually to archival. Generated-by-agent biomes (§7) traverse the
+ * same stages — humans hold every promote-out-of-sandbox gate.
+ *
+ * Linear progression (plan §4.2):
+ *
+ *   draft → sandbox-installed → review-required → org-installed
+ *                                             → store-submitted
+ *                                                → store-approved
+ *                                                   → archived
+ *
+ * String values match the on-wire / on-disk representation written by
+ * `biome-host-api` lifecycle transitions and emitted on audit events.
+ */
+export enum BiomeLifecycle {
+  Draft = 'draft',
+  SandboxInstalled = 'sandbox-installed',
+  ReviewRequired = 'review-required',
+  OrgInstalled = 'org-installed',
+  StoreSubmitted = 'store-submitted',
+  StoreApproved = 'store-approved',
+  Archived = 'archived',
+}
+
+export const BiomeLifecycleSchema = z.nativeEnum(BiomeLifecycle);

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

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+import {
+  CapabilityRefSchema,
+  type CapabilityRef,
+} from '../../capability';
+import {
+  ContributionKind,
+  ContributionKindSchema,
+} from '../../contribution';
+import { BiomeTrustTier, BiomeTrustTierSchema } from './biome-trust-tier';
+import { BiomeEnginesSchema, type BiomeEngines } from './biome-engines';
+import {
+  BiomePermissionsManifestSchema,
+  type BiomePermissionsManifest,
+} from './biome-permissions';
+import {
+  BiomeLifecycleHooksSchema,
+  type BiomeLifecycleHooks,
+} from './biome-lifecycle-hooks';
+import { BiomeApiManifestSchema, type BiomeApiManifest } from './biome-api';
+
+/**
+ * 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.
+ */
+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).
+ */
+export type BiomeManifestSchemaVersion = 1;
+
+/**
+ * Declarative event subscription entry of the biome manifest
+ * (plan §12.4). `event` is the CloudEvents `type` the biome subscribes
+ * to (e.g. `xema.kb.page.published.v1`); `handlerModule` is the module
+ * path relative to the biome package root that `biome-host-api` loads
+ * to dispatch matching events.
+ */
+export interface BiomeEventSubscription {
+  event: string;
+  handlerModule: string;
+}
+
+export const BiomeEventSubscriptionSchema = z.object({
+  event: z.string().min(1),
+  handlerModule: z.string().min(1),
+}) 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[];
+  };
+}
+
+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(),
+  requires: z.record(z.string().min(1), z.string().min(1)).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>;

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

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import {
+  BiomePermissionProfile,
+  BiomePermissionProfileSchema,
+  PermissionGroupSchema,
+  PermissionHintSchema,
+  type PermissionGroup,
+  type PermissionHint,
+} from '../../capability';
+
+/**
+ * `BiomePermissionsManifest` — the optional `permissions` block of the
+ * biome manifest (plan §30.2). It carries:
+ *
+ * - `defaultProfile`: the built-in `BiomePermissionProfile` (plan §30.3)
+ *   the install UI suggests by default. Third-party biomes MUST NOT
+ *   define new profiles — those are kernel-shipped or org-custom only.
+ * - `hints`: one entry per declared `requiresCapabilities[]` ref. The
+ *   hint is author-facing copy used to render the install-time digest;
+ *   it does not itself grant anything.
+ * - `groups`: optional author-side bundling of related capabilities so
+ *   the install UI can render "Grant the *kb-read* group" as one
+ *   toggle. Pure UX sugar — grants are still recorded per-capability.
+ */
+export interface BiomePermissionsManifest {
+  defaultProfile: BiomePermissionProfile;
+  hints: readonly PermissionHint[];
+  groups?: readonly PermissionGroup[];
+}
+
+export const BiomePermissionsManifestSchema = z.object({
+  defaultProfile: BiomePermissionProfileSchema,
+  hints: z.array(PermissionHintSchema).readonly(),
+  groups: z.array(PermissionGroupSchema).readonly().optional(),
+}) as z.ZodType<BiomePermissionsManifest>;

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

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+
+/**
+ * `BiomeScope` is the closed set of installation scopes a biome may live
+ * in (plan §4). A biome installed twice — once in `Org` and once in
+ * `Sandbox` — is two installations with disjoint state (storage,
+ * grants, audit lineage) per §25.2.
+ *
+ * String values match the on-wire representation used by
+ * `biome-host-api` install records and Object Registry projections.
+ */
+export enum BiomeScope {
+  System = 'system',
+  Org = 'org',
+  Project = 'project',
+  Sandbox = 'sandbox',
+}
+
+export const BiomeScopeSchema = z.nativeEnum(BiomeScope);

package/src/biome/lib/biome-trust-tier.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+/**
+ * `BiomeTrustTier` is the closed set of provenance tiers a biome may
+ * carry (plan §21 OQ6). The tier is set at biome publication / install
+ * time and is the primary input to the trust-tier default capability
+ * policy (see `trust-tier-policies.ts`).
+ *
+ * String values match the on-wire representation in `xema-biome.json`
+ * manifests, Store catalog entries, and audit events.
+ */
+export enum BiomeTrustTier {
+  System = 'system',
+  FirstParty = 'first-party',
+  VerifiedStore = 'verified-store',
+  CommunityStore = 'community-store',
+  PrivateOrg = 'private-org',
+  GeneratedSandbox = 'generated-sandbox',
+}
+
+export const BiomeTrustTierSchema = z.nativeEnum(BiomeTrustTier);

package/src/biome/lib/trust-tier-policies.ts

@@ -0,0 +1,99 @@
+import { BiomeTrustTier } from './biome-trust-tier';
+
+/**
+ * Default capability-policy summary per `BiomeTrustTier` (plan §21 OQ6).
+ *
+ * This table is NOT the authorization decision — `authorization-api` is
+ * the source of truth at runtime. It is the kernel-shipped default that
+ * the install UI uses to render the digest, that the boundary CI uses
+ * to spot ill-formed manifests, and that `biome-host-api` uses as the
+ * starting point for the `(BiomeInstall, ExecutionEnvironment)` grant
+ * materialisation.
+ *
+ * Fields:
+ *
+ * - `allowsProdZones`: whether the tier is allowed to be installed in
+ *   any of `org` / `project` / `app` / `session` zones by default.
+ *   `false` means the install is fenced to `sandbox` and/or
+ *   `store-review` regardless of org policy.
+ * - `requiresHumanApproval`: whether install / promote-out-of-sandbox
+ *   defaults to `requiresApproval=true` on the corresponding capability
+ *   call (`biome:install@1`, `biome:promote@1`).
+ * - `allowedEnvironments`: the environment slugs the tier may live in by default —
+ *   one of the eight built-in zones declared in plan §3.4
+ *   (`system | org | project | app | session | sandbox | public |
+ *   store-review`). Org admins may relax or tighten this through
+ *   custom policy; the kernel default is the conservative baseline.
+ *
+ * The frozen const guarantees every `BiomeTrustTier` value is mapped;
+ * adding a tier without extending this table is a compile-time error.
+ */
+export interface BiomeTrustTierDefaultPolicy {
+  readonly allowsProdZones: boolean;
+  readonly requiresHumanApproval: boolean;
+  readonly allowedEnvironments: readonly string[];
+}
+
+export const TRUST_TIER_DEFAULT_CAPABILITY_POLICIES: Readonly<
+  Record<BiomeTrustTier, BiomeTrustTierDefaultPolicy>
+> = Object.freeze({
+  [BiomeTrustTier.System]: Object.freeze({
+    allowsProdZones: true,
+    requiresHumanApproval: false,
+    allowedEnvironments: Object.freeze([
+      'system',
+      'org',
+      'project',
+      'app',
+      'session',
+      'sandbox',
+      'public',
+      'store-review',
+    ] as const),
+  }),
+  [BiomeTrustTier.FirstParty]: Object.freeze({
+    allowsProdZones: true,
+    requiresHumanApproval: false,
+    allowedEnvironments: Object.freeze([
+      'org',
+      'project',
+      'app',
+      'session',
+      'sandbox',
+      'store-review',
+    ] as const),
+  }),
+  [BiomeTrustTier.VerifiedStore]: Object.freeze({
+    allowsProdZones: true,
+    requiresHumanApproval: true,
+    allowedEnvironments: Object.freeze([
+      'org',
+      'project',
+      'app',
+      'session',
+      'sandbox',
+      'store-review',
+    ] as const),
+  }),
+  [BiomeTrustTier.CommunityStore]: Object.freeze({
+    allowsProdZones: false,
+    requiresHumanApproval: true,
+    allowedEnvironments: Object.freeze(['sandbox', 'store-review'] as const),
+  }),
+  [BiomeTrustTier.PrivateOrg]: Object.freeze({
+    allowsProdZones: true,
+    requiresHumanApproval: true,
+    allowedEnvironments: Object.freeze([
+      'org',
+      'project',
+      'app',
+      'session',
+      'sandbox',
+    ] as const),
+  }),
+  [BiomeTrustTier.GeneratedSandbox]: Object.freeze({
+    allowsProdZones: false,
+    requiresHumanApproval: true,
+    allowedEnvironments: Object.freeze(['sandbox'] as const),
+  }),
+});

package/src/capability/index.ts

@@ -0,0 +1,8 @@
+export * from './lib/capability-ref';
+export * from './lib/capability-grant';
+export * from './lib/capability-policy';
+export * from './lib/permission-profile';
+export * from './lib/shell-command-descriptor';
+export * from './lib/meta-tool';
+export * from './lib/capability-contribution';
+export * from './lib/errors';