@xemahq/kernel-contracts 0.1.0

package/src/document-themes/lib/document-theme.ts

@@ -0,0 +1,110 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── DocumentTheme manifest + tokens ──
+//
+// The shape every theme — built-in, biome-shipped, org-authored —
+// conforms to. The registry persists `manifest`, `tokens`, and `css`
+// separately so the FE can fetch only what it needs (manifest for the
+// gallery; manifest+tokens+css when activating a theme on a document).
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { RenderingShape } from '../../document-templates';
+
+/**
+ * Same 3-tier scope as templates. Resolution precedence:
+ * ORG > BIOME > SYSTEM (most specific wins). Themes are scoped at the
+ * registry level; per-page selection is via `Page.themeRef` (a ref into
+ * this registry).
+ */
+export enum DocumentThemeScope {
+  SYSTEM = 'SYSTEM',
+  BIOME = 'BIOME',
+  ORG = 'ORG',
+}
+
+/**
+ * Manifest entry — the metadata fetched for the theme gallery and the
+ * theme dropdown in the document topbar.
+ *
+ * `supportedShapes` lets a theme opt out of rendering shapes that don't
+ * fit it visually (e.g. a heavily-decorated letter theme might exclude
+ * `ANIMATED_SLIDES`). Empty / unset = supports all shapes.
+ *
+ * `supportedFormats` lets a theme constrain itself to a subset of paper
+ * formats (e.g. a poster theme might only support TABLOID). Empty /
+ * unset = supports all formats.
+ */
+export interface DocumentThemeManifest {
+  readonly slug: string;
+  readonly name: string;
+  readonly description: string;
+  readonly supportedShapes?: readonly RenderingShape[];
+  readonly supportedFormats?: readonly string[];
+  readonly previewThumbnailUrl?: string;
+  readonly version: string;
+  readonly scope: DocumentThemeScope;
+}
+
+/**
+ * The token pack — `theme.json`. Closed VOCABULARY (the keys defined
+ * here), open VALUES (the strings each implementation picks).
+ *
+ * Themes are expected to populate the full token surface; missing keys
+ * fall back to the system default theme's tokens at resolution time
+ * (registry-side defaulting, not silent — logged + emitted as a
+ * warning so theme authors notice).
+ */
+export interface DocumentThemeTokens {
+  readonly color: {
+    readonly ink: string;
+    readonly paper: string;
+    readonly accent: string;
+    readonly accentInk: string;
+    readonly muted: string;
+    readonly mutedInk: string;
+    readonly rule: string;
+    readonly success: string;
+    readonly warn: string;
+    readonly danger: string;
+  };
+  readonly type: {
+    readonly familySans: string;
+    readonly familySerif: string;
+    readonly familyMono: string;
+    /** [display, title, h2, h3, body, caption, overline] — pt values. */
+    readonly scalePt: readonly [number, number, number, number, number, number, number];
+    /** Matching line-heights for the scale. */
+    readonly lineHeight: readonly [number, number, number, number, number, number, number];
+    /** Matching weights for the scale. */
+    readonly weight: readonly [number, number, number, number, number, number, number];
+  };
+  readonly space: {
+    /** mm values used by `@page` margins and macro layout. */
+    readonly pageMargin: { top: number; right: number; bottom: number; left: number };
+    /** Generic spacing scale (0/4/8/12/16/24/32/48 — px). */
+    readonly scalePx: readonly [number, number, number, number, number, number, number, number];
+  };
+  readonly radius: {
+    /** Corner radii — px. */
+    readonly scalePx: readonly [number, number, number, number];
+  };
+}
+
+/**
+ * Full theme bundle the kb-api theme endpoint returns on activation.
+ * `css` is the serialized theme stylesheet (already token-substituted
+ * OR using CSS custom properties that reference the same tokens — the
+ * runtime treats it as an opaque string).
+ */
+export interface DocumentTheme {
+  readonly manifest: DocumentThemeManifest;
+  readonly tokens: DocumentThemeTokens;
+  readonly css: string;
+}
+
+/**
+ * Wire-shape reference to a theme — `<scope>:<slug>` (system or
+ * biome) or `<scope>:<orgId>:<slug>` (org). Matches
+ * DocumentTemplateRef's encoding so consumers parse both with one
+ * helper.
+ */
+export type DocumentThemeRef = string;

package/src/document-themes/lib/index.ts

@@ -0,0 +1,2 @@
+export * from './document-theme';
+export * from './component-vocabulary';

package/src/entitlement/index.ts

@@ -0,0 +1 @@
+export * from './lib/entitlement';

package/src/entitlement/lib/entitlement.ts

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+
+/**
+ * The Xema deployment/org edition. Closed set — the build is compiled for
+ * exactly one ceiling edition, and an org is provisioned at exactly one
+ * edition (never above the build ceiling).
+ *
+ * `Community` is the FAIL-CLOSED default: any ambiguity in resolution
+ * (missing config, missing org row, malformed upstream payload) collapses to
+ * `Community`. Enterprise capability is granted only on an explicit, valid
+ * `Enterprise` signal at BOTH the deployment ceiling AND the org row.
+ */
+export enum Edition {
+  Community = 'community',
+  Enterprise = 'enterprise',
+}
+
+export const EditionSchema = z.nativeEnum(Edition);
+
+/**
+ * The closed set of feature keys other Xema features gate on. Each key names a
+ * single Enterprise-gated capability; a key being absent from an
+ * `EntitlementSet.features` map (or set to `false`) means NOT entitled.
+ *
+ * Closed set — adding a gated feature is a kernel change. Never gate on a
+ * free-form string; always reference a member of this enum so the boundary
+ * between "known gated feature" and "typo / unknown feature" stays explicit
+ * (an unknown key can never be entitled).
+ */
+export enum EntitlementKey {
+  /** Nested / hierarchical teams (sub-teams within teams). */
+  TeamsNested = 'teams.nested',
+  /** Delegated team administration (team-scoped admins below the org admin). */
+  TeamsDelegatedAdmin = 'teams.delegatedAdmin',
+  /** SCIM provisioning for teams/membership. */
+  TeamsScim = 'teams.scim',
+  /** Custom (org-authored) roles beyond the built-in role set. */
+  RolesCustom = 'roles.custom',
+  /** Access-request approval workflow. */
+  AccessRequestWorkflow = 'access.requestWorkflow',
+  /** External OIDC identity-provider federation (SSO). */
+  SsoOidcFederation = 'sso.oidc-federation',
+}
+
+export const EntitlementKeySchema = z.nativeEnum(EntitlementKey);
+
+/**
+ * An entitlement decision for a single org: the resolved `edition` plus a
+ * per-feature map. A feature is entitled only when its key maps to `true`;
+ * absent or `false` ⇒ not entitled (fail-closed).
+ */
+export interface EntitlementSet {
+  edition: Edition;
+  features: Partial<Record<EntitlementKey, boolean>>;
+}
+
+export const EntitlementSetSchema = z.object({
+  edition: EditionSchema,
+  features: z.record(EntitlementKeySchema, z.boolean()),
+}) as z.ZodType<EntitlementSet>;
+
+/**
+ * The fully-locked-down Community entitlement: Community edition with every
+ * gated feature off. Returned by every fail-closed path.
+ */
+const COMMUNITY_ENTITLEMENT: EntitlementSet = {
+  edition: Edition.Community,
+  features: {},
+};
+
+/**
+ * Resolve the EFFECTIVE entitlement for an org as
+ * **`effective = min(deploymentCeiling, orgEntitlement)`**.
+ *
+ * FAIL-CLOSED rules (a compromised or stale org row can never exceed the build
+ * edition, and any ambiguity collapses to Community):
+ *
+ * 1. If `deploymentCeiling` is `Community`, the result is ALWAYS Community with
+ *    every gated feature `false`, regardless of what the org row claims. The
+ *    build simply does not contain Enterprise capability to grant.
+ * 2. If the org entitlement is `undefined` (unknown / absent / not yet
+ *    provisioned), the result is the Community default.
+ * 3. If `deploymentCeiling` is `Enterprise` but the org row's edition is
+ *    `Community`, the org is Community and every feature is `false`.
+ * 4. Only when BOTH the ceiling and the org row are `Enterprise` are the org's
+ *    `true` feature flags honored; any non-`true` (absent / `false`) feature
+ *    stays off.
+ *
+ * Never grants MORE than the org explicitly enabled, and never more than the
+ * build ceiling allows. There is no path that returns Enterprise without an
+ * explicit Enterprise signal on both sides.
+ */
+export function resolveEffectiveEntitlement(
+  deploymentCeiling: Edition,
+  orgEntitlement: EntitlementSet | undefined,
+): EntitlementSet {
+  // Rule 1: a Community build can never grant Enterprise.
+  if (deploymentCeiling !== Edition.Enterprise) {
+    return { edition: Edition.Community, features: {} };
+  }
+
+  // Rule 2: unknown / absent org ⇒ Community default.
+  if (!orgEntitlement) {
+    return { edition: Edition.Community, features: {} };
+  }
+
+  // Rule 3: org row not Enterprise ⇒ Community, all features off.
+  if (orgEntitlement.edition !== Edition.Enterprise) {
+    return { edition: Edition.Community, features: {} };
+  }
+
+  // Rule 4: ceiling AND org are Enterprise — honor only explicit `true` flags.
+  const features: Partial<Record<EntitlementKey, boolean>> = {};
+  for (const key of Object.values(EntitlementKey)) {
+    if (orgEntitlement.features[key] === true) {
+      features[key] = true;
+    }
+  }
+  return { edition: Edition.Enterprise, features };
+}
+
+/** Re-exported for callers that want the canonical fail-closed default. */
+export { COMMUNITY_ENTITLEMENT };
+
+/**
+ * Whether a single feature is entitled under an already-resolved EFFECTIVE
+ * entitlement. Fail-closed: returns `true` ONLY when the effective edition is
+ * `Enterprise` AND the feature flag is explicitly `true`. Any absent / `false`
+ * / unknown state ⇒ `false`.
+ *
+ * Always call this against the output of `resolveEffectiveEntitlement` — never
+ * against a raw org row, so the deployment ceiling has already been applied.
+ */
+export function isFeatureEntitled(
+  effective: EntitlementSet,
+  key: EntitlementKey,
+): boolean {
+  return (
+    effective.edition === Edition.Enterprise &&
+    effective.features[key] === true
+  );
+}

package/src/execution-context/index.ts

@@ -0,0 +1,3 @@
+export * from './lib/subject';
+export * from './lib/caller';
+export * from './lib/execution-context';

package/src/execution-context/lib/caller.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+
+/**
+ * Closed caller-kind set (plan v4.3 §A.3).
+ *
+ * Distinguishes how the invocation entered the system — drives audit
+ * shape, default obligations (e.g. `Web` callers default to `audit` +
+ * `redact-secrets`), and route-hint fallbacks. Closed set.
+ */
+export enum CallerKind {
+  Web = 'web',
+  Api = 'api',
+  Agent = 'agent',
+  Workflow = 'workflow',
+  Shell = 'shell',
+  Scheduler = 'scheduler',
+}
+
+export const CallerKindSchema = z.nativeEnum(CallerKind);
+
+/**
+ * `Caller` — entry-point envelope captured on every invocation.
+ *
+ * v4.3 contract shape per plan §A.3:
+ *   { kind: CallerKind; appId?; sessionId?; ip?; userAgent? }
+ *
+ * `appId` and `sessionId` are populated when the caller is an embedded
+ * app or interactive session; `ip` + `userAgent` come from the HTTP edge
+ * (public-gateway-api) and are dropped at internal hops to avoid silent
+ * PII propagation past the audit boundary.
+ */
+export interface Caller {
+  kind: CallerKind;
+  appId?: string;
+  sessionId?: string;
+  ip?: string;
+  userAgent?: string;
+}
+
+export const CallerSchema = z.object({
+  kind: CallerKindSchema,
+  appId: z.string().min(1).optional(),
+  sessionId: z.string().min(1).optional(),
+  ip: z.string().min(1).optional(),
+  userAgent: z.string().min(1).optional(),
+}) as z.ZodType<Caller>;

package/src/execution-context/lib/execution-context.ts

@@ -0,0 +1,205 @@
+import { z } from 'zod';
+import {
+  CapabilityRefSchema,
+  type CapabilityRef,
+} from '../../capability';
+import {
+  ExecutionEnvironmentKind,
+  ExecutionEnvironmentKindSchema,
+} from '../../execution-environment';
+import {
+  DataClassification,
+  DataClassificationSchema,
+  SpaceRefSchema,
+  type SpaceRef,
+} from '../../space';
+import { CallerSchema, type Caller } from './caller';
+import {
+  ActingForRefSchema,
+  SubjectRefSchema,
+  type ActingForRef,
+  type SubjectRef,
+} from './subject';
+
+/**
+ * Closed biome trust-tier set referenced by `ExecutionContext.biome`
+ * (plan v4.3 §A.3).
+ *
+ * Tier ordering goes Untrusted → Community → Verified → Official; OPA
+ * policy bundles MAY gate a capability to a minimum tier, but the kernel
+ * never assumes a fallback default — `signatureVerified=false` on a non-
+ * `Untrusted` tier MUST fail-fast at the gateway.
+ */
+export enum BiomeTrustTier {
+  Official = 'official',
+  Verified = 'verified',
+  Community = 'community',
+  Untrusted = 'untrusted',
+}
+
+export const BiomeTrustTierSchema = z.nativeEnum(BiomeTrustTier);
+
+/**
+ * Biome attestation block carried on `ExecutionContext.biome` (plan
+ * v4.3 §A.3). Set when the capability is provided by a biome (vs. an
+ * embedded built-in). `signatureVerified` is the Cosign verdict from the
+ * biome-fetcher-api at install time.
+ */
+export interface ExecutionContextBiome {
+  id: string;
+  version: string;
+  trustTier: BiomeTrustTier;
+  signatureVerified: boolean;
+}
+
+export const ExecutionContextBiomeSchema = z.object({
+  id: z.string().min(1),
+  version: z.string().min(1),
+  trustTier: BiomeTrustTierSchema,
+  signatureVerified: z.boolean(),
+}) as z.ZodType<ExecutionContextBiome>;
+
+/**
+ * Environment block carried on `ExecutionContext.environment` (plan
+ * v4.3 §A.3).
+ *
+ * `id` is the canonical `environment:<slug>` ref (string-typed here to
+ * keep the envelope JSON-clean — the kernel-side reference type lives in
+ * `@xemahq/execution-environment-contracts`).
+ *
+ * `kind` is the {@link ExecutionEnvironmentKind} value matched against the eight
+ * built-in environments + the `trusted-dev` escape hatch. The internal
+ * identifier `ExecutionEnvironmentKind` is still named "Zone" — the rename to
+ * `ExecutionEnvironmentKind` is scheduled for Phase A.5 (plan §A.1
+ * follow-up sweep), not Phase A.3.
+ */
+export interface ExecutionContextEnvironment {
+  id: string;
+  kind: ExecutionEnvironmentKind;
+}
+
+export const ExecutionContextEnvironmentSchema = z.object({
+  id: z.string().min(1),
+  kind: ExecutionEnvironmentKindSchema,
+}) as z.ZodType<ExecutionContextEnvironment>;
+
+/**
+ * Capability block carried on `ExecutionContext.capability` (plan
+ * v4.3 §A.3).
+ *
+ * `ref` is the canonical capability reference (`<biome>:<verb>@<major>`).
+ * `inputHash` is an optional SHA-256 fingerprint of the JSON-serialised
+ * input — used for cache-key composition and audit replay. Omitted on
+ * invocations whose input is non-deterministic (e.g. streaming uploads).
+ */
+export interface ExecutionContextCapability {
+  ref: CapabilityRef;
+  inputHash?: string;
+}
+
+export const ExecutionContextCapabilitySchema = z.object({
+  ref: CapabilityRefSchema,
+  inputHash: z.string().min(1).optional(),
+}) as z.ZodType<ExecutionContextCapability>;
+
+/**
+ * Resource block carried on `ExecutionContext.resource` (plan v4.3 §A.3).
+ *
+ * Set when the invocation targets a specific persistent object (a
+ * XemaObject, a document, an SCM file). `ref` is the resource reference
+ * (XVFS path or domain ref); `classification` MUST be carried alongside
+ * because policy obligations like `redact-secrets` and
+ * `restrict-output-classification` key on it.
+ */
+export interface ExecutionContextResource {
+  ref: string;
+  classification: DataClassification;
+}
+
+export const ExecutionContextResourceSchema = z.object({
+  ref: z.string().min(1),
+  classification: DataClassificationSchema,
+}) as z.ZodType<ExecutionContextResource>;
+
+/**
+ * Constraints block carried on `ExecutionContext.constraints` (plan
+ * v4.3 §A.3).
+ *
+ * Per-invocation caps + flags the gateway derives from the caller's
+ * grant, the org's environment policy, and the capability's defaults.
+ * `requireCustomerEdge` is a hard runner-selection constraint (see
+ * `RouteHint.requireCustomerEdge` in `@xemahq/policy-contracts`).
+ *
+ * Omitted fields mean "no constraint at this layer"; the runner MUST
+ * still respect downstream layers (e.g. org-level cost budgets).
+ */
+export interface ExecutionContextConstraints {
+  maxCostUsd?: number;
+  maxDurationSeconds?: number;
+  requireApproval?: boolean;
+  requireAudit?: boolean;
+  requireCustomerEdge?: boolean;
+}
+
+export const ExecutionContextConstraintsSchema = z.object({
+  maxCostUsd: z.number().nonnegative().optional(),
+  maxDurationSeconds: z.number().int().nonnegative().optional(),
+  requireApproval: z.boolean().optional(),
+  requireAudit: z.boolean().optional(),
+  requireCustomerEdge: z.boolean().optional(),
+}) as z.ZodType<ExecutionContextConstraints>;
+
+/**
+ * `ExecutionContext` — the per-invocation envelope (plan v4.3 §A.3).
+ *
+ * Constructed by `biomes/xema-capability-router/api/xema-capability-router` at the gateway boundary,
+ * passed verbatim to `authorization-api` for the policy check, and
+ * forwarded to the dispatched runner. Audit, policy, and runner all
+ * read the SAME shape — no parallel envelopes.
+ *
+ * Wave 4 (Phase A.5) wires this through `dispatch.service.ts`. This
+ * package is contract-only — no consumer rewiring lives here.
+ */
+export interface ExecutionContext {
+  id: string;
+  requestId: string;
+  traceId: string;
+  subject: SubjectRef;
+  caller: Caller;
+  space: SpaceRef;
+  environment: ExecutionContextEnvironment;
+  biome?: ExecutionContextBiome;
+  capability: ExecutionContextCapability;
+  resource?: ExecutionContextResource;
+  constraints?: ExecutionContextConstraints;
+  /**
+   * RFC 8693 delegation chain (`act`), outermost-acting-first. Built at the
+   * gateway from `RequestContext.actorChain` and carried through policy → audit
+   * → credential-broker. Empty/omitted for a non-delegated invocation
+   * (plan §W4 / Pillar 3.2).
+   */
+  actorChain?: ActingForRef[];
+  /**
+   * Opaque credential-binding id the PDP selected for this invocation
+   * (`PolicyDecision.credentialBindingId`). When present, the executing
+   * gateway/runner resolves it via the credential-broker. NEVER a secret
+   * (plan §W4 / Pillar 3.2).
+   */
+  credentialBindingId?: string;
+}
+
+export const ExecutionContextSchema = z.object({
+  id: z.string().min(1),
+  requestId: z.string().min(1),
+  traceId: z.string().min(1),
+  subject: SubjectRefSchema,
+  caller: CallerSchema,
+  space: SpaceRefSchema,
+  environment: ExecutionContextEnvironmentSchema,
+  biome: ExecutionContextBiomeSchema.optional(),
+  capability: ExecutionContextCapabilitySchema,
+  resource: ExecutionContextResourceSchema.optional(),
+  constraints: ExecutionContextConstraintsSchema.optional(),
+  actorChain: z.array(ActingForRefSchema).optional(),
+  credentialBindingId: z.string().min(1).optional(),
+}) as z.ZodType<ExecutionContext>;

package/src/execution-context/lib/subject.ts

@@ -0,0 +1,17 @@
+/**
+ * The canonical subject taxonomy now lives in `@xemahq/subject-contracts`
+ * (the single closed `SubjectKind`, the `{ kind, id, roles?, actingFor? }`
+ * `SubjectRef`, the `ActingForRef` delegation pointer, and the
+ * `subjectRefToString`/`parseSubjectRef` composite bridges). This module
+ * re-exports that surface so existing `@xemahq/execution-context-contracts`
+ * importers are unaffected. Do NOT redeclare a `SubjectKind`/`SubjectRef` here.
+ */
+export {
+  SubjectKind,
+  SubjectKindSchema,
+  SubjectRefSchema,
+  ActingForRefSchema,
+  subjectRefToString,
+  parseSubjectRef,
+} from '../../subject';
+export type { SubjectRef, ActingForRef } from '../../subject';

package/src/execution-environment/index.ts

@@ -0,0 +1,3 @@
+export * from './lib/built-in-environments';
+export * from './lib/approval-rule';
+export * from './lib/execution-environment';

package/src/execution-environment/lib/approval-rule.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import {
+  CapabilityRefSchema,
+  type CapabilityRef,
+} from '../../capability';
+
+/**
+ * Per-environment approval rule (plan §3.4 `ExecutionEnvironment.approvalRules[]`,
+ * §30.7 Human-in-the-loop approval at runtime).
+ *
+ * When a runtime invocation matches a rule whose `capability` ref covers the
+ * call, the gateway suspends the invocation, emits an `ApprovalRequested`
+ * CloudEvent, and renders a typed approval dialog. The rule may further
+ * require a specific approver role and/or a minimum approver count.
+ *
+ * `requireApproverCount` defaults are NOT encoded here — the gateway
+ * fail-fasts on a missing/invalid count rather than substituting a silent
+ * default (engineering constitution: no silent fallbacks).
+ */
+export interface ApprovalRule {
+  capability: CapabilityRef;
+  requireRole?: string;
+  requireApproverCount?: number;
+  reason?: string;
+}
+
+export const ApprovalRuleSchema = z.object({
+  capability: CapabilityRefSchema,
+  requireRole: z.string().min(1).optional(),
+  requireApproverCount: z.number().int().positive().optional(),
+  reason: z.string().min(1).optional(),
+}) as z.ZodType<ApprovalRule>;

package/src/execution-environment/lib/built-in-environments.ts

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+
+/**
+ * Closed set of built-in Execution Environment kinds.
+ *
+ * Plan-of-record: v4.3 §2 vocabulary table (`Zone → Environment` row),
+ * §3.4 (the eight built-in environments that cover every story we have
+ * today), and §30.6 (`trusted-dev` environment — the developer escape
+ * hatch).
+ *
+ * v1 ships ONLY these built-ins; custom environments are an explicit v2
+ * extension (plan §16). The downstream `ExecutionEnvironment.scope` type
+ * intentionally widens to `ExecutionEnvironmentKind | string` for future-
+ * proofing, but at v1 the only legal scope values are members of this
+ * enum — see `isExecutionEnvironmentKind`.
+ *
+ * Slugs are stable wire identifiers and MUST NOT change once shipped;
+ * they appear in `ExecutionEnvironmentRef` (`environment:<slug>`), in
+ * capability grants, and in audit logs.
+ */
+export enum ExecutionEnvironmentKind {
+  /** Platform operators / migrations. */
+  System = 'system',
+  /** Org admins; biome install/uninstall. */
+  Org = 'org',
+  /** Project members; default agent/workflow runtime. */
+  Project = 'project',
+  /** Apps configured for an audience. */
+  App = 'app',
+  /** Interactive session bounded by user permissions. */
+  Session = 'session',
+  /**
+   * Biome build/test (Linux container OK here) + agent-generated biome
+   * staging. NOT the same as `TrustedDev` — `Sandbox` is for untrusted
+   * biomes the org is evaluating.
+   */
+  Sandbox = 'sandbox',
+  /** External delegated sessions (chat widgets, customer portals). */
+  Public = 'public',
+  /** Biome inspected for publication; no real org data access. */
+  StoreReview = 'store-review',
+  /**
+   * Local-dev / personal-sandbox environment (plan §30.6). Inside it the
+   * Capability Gateway grants every capability the biome *declared* in
+   * its manifest, no resource glob, no rate limit, no human approval.
+   * Audit-log still records every call so devs can inspect what their
+   * biome *would* do in production. Only `power-user-developer` profile
+   * can be installed here, and the environment is never reachable from
+   * production data.
+   */
+  TrustedDev = 'trusted-dev',
+}
+
+export const ExecutionEnvironmentKindSchema = z.nativeEnum(ExecutionEnvironmentKind);
+
+/**
+ * Stable, ordered list of every built-in environment slug. Seeded at
+ * boot by `authorization-api` / `object-registry-api` per plan §17.5
+ * step 1.
+ *
+ * Ordering is intentional (system → org → project → app → session →
+ * sandbox → public → store-review → trusted-dev) and matches the table
+ * in §3.4 followed by the dev escape hatch from §30.6. Do not reorder
+ * without a coordinated migration of any consumer that relies on
+ * positional iteration.
+ */
+export const BUILT_IN_ENVIRONMENT_SLUGS: readonly ExecutionEnvironmentKind[] = [
+  ExecutionEnvironmentKind.System,
+  ExecutionEnvironmentKind.Org,
+  ExecutionEnvironmentKind.Project,
+  ExecutionEnvironmentKind.App,
+  ExecutionEnvironmentKind.Session,
+  ExecutionEnvironmentKind.Sandbox,
+  ExecutionEnvironmentKind.Public,
+  ExecutionEnvironmentKind.StoreReview,
+  ExecutionEnvironmentKind.TrustedDev,
+] as const;
+
+/**
+ * Narrowing guard: returns `true` iff `slug` is one of the built-in
+ * environment slugs. Used by `ExecutionEnvironmentSchema` and the
+ * authorization-api to refuse custom-scoped environments at v1 (plan §16
+ * non-goal).
+ */
+export function isExecutionEnvironmentKind(
+  slug: string,
+): slug is ExecutionEnvironmentKind {
+  return (BUILT_IN_ENVIRONMENT_SLUGS as readonly string[]).includes(slug);
+}