@xemahq/kernel-contracts 0.2.0 → 0.2.2

package/src/distribution/lib/distribution-selector.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import {
+  BiomeTierSchema,
+  BiomeOriginSchema,
+  type BiomeTier,
+  type BiomeOrigin,
+} from '../../biome';
+
+/**
+ * A `DistributionSelector` declares which biomes an `include[]` entry pulls
+ * into a distribution. Exactly one of the three forms:
+ *
+ * - `{ tier }`     — every biome of that dependency tier (maps to the manifest
+ *                    `xema.scope` field). NEVER pulls `audience: operator`
+ *                    biomes — those require explicit `{ biome }` naming.
+ * - `{ origin }`   — every biome of that provenance posture (first/third-party).
+ * - `{ biome }`    — one biome by id, optional semver `version` range. This is
+ *                    the ONLY form that can pull an `audience: operator` biome
+ *                    (the "force it in" mechanism for our internal distribution).
+ *
+ * Selector matching is resolved against the global biome index; the resolver,
+ * not any consumer, applies these rules (the lockfile is the hard boundary).
+ */
+export type DistributionSelector =
+  | { tier: BiomeTier }
+  | { origin: BiomeOrigin }
+  | { biome: string; version?: string };
+
+export const DistributionSelectorSchema = z.union([
+  z.object({ tier: BiomeTierSchema }).strict(),
+  z.object({ origin: BiomeOriginSchema }).strict(),
+  z
+    .object({ biome: z.string().min(1), version: z.string().min(1).optional() })
+    .strict(),
+]) as z.ZodType<DistributionSelector>;

package/src/distribution/lib/distribution.ts

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+import { BiomeOriginSchema, type BiomeOrigin } from '../../biome';
+import {
+  DistributionSelectorSchema,
+  type DistributionSelector,
+} from './distribution-selector';
+
+/**
+ * Schema-versioning seed for `xema-distribution.json`. Bumped via a coordinated
+ * PR on an incompatible shape change; consumers refuse versions they do not
+ * understand (fail-fast — no best-effort parse).
+ */
+export type DistributionSchemaVersion = 1;
+
+/**
+ * Trust policy of a distribution — gates which provenance postures may ship.
+ * E.g. a locked appliance distribution allows only `first-party`. Gates on
+ * `BiomeOrigin` (the posture carried on the manifest at build time), NOT on
+ * the richer install-time `BiomeTrustTier`.
+ */
+export interface DistributionTrustPolicy {
+  allow: readonly BiomeOrigin[];
+}
+
+export const DistributionTrustPolicySchema = z.object({
+  allow: z.array(BiomeOriginSchema).readonly(),
+}) as z.ZodType<DistributionTrustPolicy>;
+
+/**
+ * `Distribution` — the top-level shape of `xema-distribution.json`: the
+ * PACKAGING primitive that declares which biomes a given Xema build ships.
+ *
+ * This is orthogonal to a biome's dependency tier (`BiomeTier`) and to where it
+ * is deployed (the deployment plane). It contains PACKAGING fields only — no
+ * infra/deploy/values config (that lives in the deployment overlay).
+ *
+ * Composition: `extends` names a parent distribution; the resolver composes
+ * parent → child, with the child's `include`/`exclude` overriding. The resolver
+ * enforces (fail-fast): kernel-tier biomes are always included and cannot be
+ * excluded; an included biome whose `requires` are absent is an error; selectors
+ * never pull `audience: operator` biomes. The deterministic resolved output is a
+ * `DistributionLock` — the single artifact every consumer reads.
+ */
+export interface Distribution {
+  schemaVersion: DistributionSchemaVersion;
+  id: string;
+  displayName: string;
+  description?: string;
+  /** Parent distribution id this one composes onto. */
+  extends?: string;
+  include: readonly DistributionSelector[];
+  /** Biome ids to remove after composition. Cannot remove a kernel-tier biome. */
+  exclude?: readonly string[];
+  trustPolicy?: DistributionTrustPolicy;
+}
+
+export const DistributionSchema = z.object({
+  schemaVersion: z.literal(1),
+  id: z.string().min(1),
+  displayName: z.string().min(1),
+  description: z.string().min(1).optional(),
+  extends: z.string().min(1).optional(),
+  include: z.array(DistributionSelectorSchema).readonly(),
+  exclude: z.array(z.string().min(1)).readonly().optional(),
+  trustPolicy: DistributionTrustPolicySchema.optional(),
+}) as z.ZodType<Distribution>;
+
+/**
+ * Parse + validate a raw `xema-distribution.json`. Fail-fast on any shape error
+ * — never best-effort. Mirrors `parseBiomeManifest`.
+ */
+export function parseDistribution(raw: unknown): Distribution {
+  const result = DistributionSchema.safeParse(raw);
+  if (!result.success) {
+    throw new Error(
+      `Invalid xema-distribution.json: ${result.error.issues
+        .map((i) => `[${i.path.join('.')}] ${i.message}`)
+        .join('; ')}`,
+    );
+  }
+  return result.data;
+}

package/src/distribution/lib/image-lock.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import { BiomeTargetSchema, type BiomeTarget } from '../../biome';
+
+/**
+ * A single deployable image as resolved by the image-manifest step
+ * (`images.lock.json`). Images are CONTENT-ADDRESSED: `contentHash` is a
+ * deterministic sha256 over the biome's source directory tree, so the SAME
+ * biome source produces the SAME hash (and therefore the same image tag)
+ * across every customer/distribution. This is the delta key — CI builds an
+ * image only when its `contentHash` is not already present in the registry.
+ *
+ * `imageRef` is the untagged repository reference; the build-time tag is
+ * `${imageRef}:${contentHash}`.
+ */
+export interface LockedImage {
+  /** The biome this image is built from. */
+  biomeId: string;
+  /** Runtime surface — only `server` biomes produce a container image. */
+  target: BiomeTarget;
+  /** Untagged image repository reference, e.g. `ghcr.io/xema-dev/<biomeId>`. */
+  imageRef: string;
+  /** sha256 over the biome source tree — identical source ⇒ identical hash. */
+  contentHash: string;
+  /** Source repo segment the biome was resolved from (provenance for the build). */
+  repo: string;
+  /** Source directory path (repo-root-relative) the biome was resolved from. */
+  path: string;
+}
+
+export const LockedImageSchema = z.object({
+  biomeId: z.string().min(1),
+  target: BiomeTargetSchema,
+  imageRef: z.string().min(1),
+  contentHash: z.string().min(1),
+  repo: z.string().min(1),
+  path: z.string().min(1),
+}) as z.ZodType<LockedImage>;
+
+/**
+ * `ImageLock` — the deterministic, content-addressed image manifest for a
+ * distribution. Resolved from `distribution.lock.json` by the image-manifest
+ * tooling; the delta-build planner reads it to decide which images are NEW vs
+ * already-built. Like `DistributionLock`, `resolvedAt` is stamped by the
+ * tooling (kernel contracts hold no clock) and is optional so the type is
+ * usable mid-resolution.
+ */
+export interface ImageLock {
+  schemaVersion: 1;
+  distributionId: string;
+  images: readonly LockedImage[];
+  /** ISO-8601 timestamp the resolver stamped (tooling-supplied). */
+  resolvedAt?: string;
+}
+
+export const ImageLockSchema = z.object({
+  schemaVersion: z.literal(1),
+  distributionId: z.string().min(1),
+  images: z.array(LockedImageSchema).readonly(),
+  resolvedAt: z.string().min(1).optional(),
+}) as z.ZodType<ImageLock>;
+
+/**
+ * Parse + validate a raw `images.lock.json`. Fail-fast on any shape error —
+ * the image lock is the hard boundary the delta-build planner reads, so a
+ * malformed lock must never be silently tolerated.
+ */
+export function parseImageLock(raw: unknown): ImageLock {
+  const result = ImageLockSchema.safeParse(raw);
+  if (!result.success) {
+    throw new Error(
+      `Invalid images.lock.json: ${result.error.issues
+        .map((i) => `[${i.path.join('.')}] ${i.message}`)
+        .join('; ')}`,
+    );
+  }
+  return result.data;
+}

package/src/inquiry/lib/enums.ts

@@ -101,3 +101,16 @@ export enum InquiryTimeoutAction {
   APPROVE = 'approve',
   ESCALATE = 'escalate',
 }
+
+/**
+ * Terminal action when an inquiry's `escalationChain` is exhausted (the
+ * final step's deadline passed with no terminal verdict). A deliberately
+ * NARROWER closed set than `InquiryTimeoutAction`: `ESCALATE` is not
+ * representable here — escalating past the last chain step would be an
+ * infinite loop. Defaults to `REJECT` so a misconfigured chain never
+ * silently approves.
+ */
+export enum EscalationExhaustionAction {
+  REJECT = 'reject',
+  APPROVE = 'approve',
+}

package/src/inquiry/lib/inquiry.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 
 import {
+  EscalationExhaustionAction,
   InquiryKind,
   InquiryRecipientStatus,
   InquiryStatus,
@@ -51,6 +52,17 @@ export const InquirySchema = z.object({
   workflowRunId: z.string().min(1),
   jobRunId: z.string().min(1),
   kind: z.nativeEnum(InquiryKind),
+  /**
+   * Optional domain approval-card discriminator. Distinct from the
+   * structural `kind` (which selects policy + gate semantics): an
+   * `inquiryKind` selects a biome-contributed approval-card variant
+   * (custom fields + verdict shape) on the FE and a domain descriptor on
+   * the engine. `null`/absent = the generic card for the structural
+   * `kind`, which is a valid state — never a silent error. When present,
+   * the value MUST match a `ContributionKind.InquiryKind` descriptor
+   * registered with the engine (validated fail-fast at create time).
+   */
+  inquiryKind: z.string().min(1).nullable(),
   title: z.string(),
   prompt: z.record(z.string(), z.unknown()),
   policy: ReplyPolicySchema,
@@ -66,10 +78,10 @@ export const InquirySchema = z.object({
   /**
    * Action when the escalation chain is exhausted (i.e. the final
    * step's deadline passes with no terminal verdict). Closed set:
-   * `REJECT` (default) or `APPROVE`. `ESCALATE` is rejected here at
-   * the schema level — would be a runtime infinite loop.
+   * `REJECT` (default) or `APPROVE`. `ESCALATE` is not representable —
+   * escalating past the last chain step would be a runtime infinite loop.
    */
-  onEscalationExhaustion: z.enum(['reject', 'approve']),
+  onEscalationExhaustion: z.nativeEnum(EscalationExhaustionAction),
   /**
    * Zero-based pointer into `escalationChain`. Bumped each time the
    * engine advances. `0` means "still on the original recipients";
@@ -120,6 +132,12 @@ export const CreateInquiryInputSchema = z
     workflowRunId: z.string().min(1),
     jobRunId: z.string().min(1),
     kind: z.nativeEnum(InquiryKind),
+    /**
+     * Optional domain approval-card discriminator (see `InquirySchema`).
+     * Omitted = generic card for the structural `kind`. When present, the
+     * engine refuses an unregistered value fail-fast.
+     */
+    inquiryKind: z.string().min(1).optional(),
     title: z.string(),
     prompt: z.record(z.string(), z.unknown()),
     policy: ReplyPolicySchema,
@@ -127,7 +145,7 @@ export const CreateInquiryInputSchema = z
     expiresAtIso: z.string(),
     onTimeout: z.nativeEnum(InquiryTimeoutAction),
     escalationChain: z.array(EscalationStepSchema).optional(),
-    onEscalationExhaustion: z.enum(['reject', 'approve']).optional(),
+    onEscalationExhaustion: z.nativeEnum(EscalationExhaustionAction).optional(),
   })
   .superRefine((value, ctx) => {
     // ESCALATE without a chain is meaningless — would have to fall back

package/src/invocation/index.ts

@@ -0,0 +1,9 @@
+export * from './lib/invocation-mode';
+export * from './lib/isolation-level';
+export * from './lib/invocation-status';
+export * from './lib/invocation-priority';
+export * from './lib/execution-requirements';
+export * from './lib/invocation-decision';
+export * from './lib/invoke-request';
+export * from './lib/invoke-response';
+export * from './lib/invocation-record';

package/src/invocation/lib/execution-requirements.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { InvocationMode, InvocationModeSchema } from './invocation-mode';
+import { IsolationLevel, IsolationLevelSchema } from './isolation-level';
+import {
+  InvocationPriority,
+  InvocationPrioritySchema,
+} from './invocation-priority';
+
+/**
+ * Per-invocation hard limits. None are required at the contract level; an
+ * absent field means "no caller-declared limit on this axis" (the platform may
+ * still apply its own). These map directly onto the existing `composition.limits`
+ * consumed by `CompositionBudgetEnforcer` — no new enforcement engine.
+ */
+export interface InvocationLimits {
+  readonly maxDurationMs?: number;
+  readonly maxTokens?: number;
+  readonly maxToolCalls?: number;
+  readonly maxRetries?: number;
+  readonly maxCostUsd?: number;
+}
+
+export const InvocationLimitsSchema = z.object({
+  maxDurationMs: z.number().int().nonnegative().optional(),
+  maxTokens: z.number().int().nonnegative().optional(),
+  maxToolCalls: z.number().int().nonnegative().optional(),
+  maxRetries: z.number().int().nonnegative().optional(),
+  maxCostUsd: z.number().nonnegative().optional(),
+}) as z.ZodType<InvocationLimits>;
+
+/**
+ * What a biome DECLARES about how its invocation should run; the platform
+ * ENFORCES. `mode` is a hint the platform may override by policy; `isolation`
+ * defaults to `Strict` (fresh thread per invocation).
+ */
+export interface ExecutionRequirements {
+  /** Hint; the platform may override the execution mode by policy. */
+  readonly mode?: InvocationMode;
+  /** Thread-context isolation; default `Strict`. */
+  readonly isolation: IsolationLevel;
+  readonly latencyTargetMs?: number;
+  readonly priority?: InvocationPriority;
+  /** Strategy / modelClass hint for model resolution. */
+  readonly modelCapability?: string;
+  /** Deliverable-spec / JSON-schema ref the root output is validated against. */
+  readonly outputSchemaRef?: string;
+  readonly idempotencyKey?: string;
+  /** Maps to the existing `composition.limits` budget axes. */
+  readonly limits?: InvocationLimits;
+}
+
+export const ExecutionRequirementsSchema = z.object({
+  mode: InvocationModeSchema.optional(),
+  isolation: IsolationLevelSchema,
+  latencyTargetMs: z.number().int().nonnegative().optional(),
+  priority: InvocationPrioritySchema.optional(),
+  modelCapability: z.string().min(1).optional(),
+  outputSchemaRef: z.string().min(1).optional(),
+  idempotencyKey: z.string().min(1).optional(),
+  limits: InvocationLimitsSchema.optional(),
+}) as z.ZodType<ExecutionRequirements>;

package/src/invocation/lib/invocation-decision.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+/**
+ * One structured decision produced by a composition invocation. An invocation
+ * MAY emit multiple decisions (e.g. a classify step and a route step).
+ *
+ * `kind` is free-form at the contract layer because the set of decision kinds
+ * is open and biome-owned (e.g. `'classification'`, `'route'`); the runtime
+ * does not interpret it. `payload` carries the decision body verbatim.
+ */
+export interface InvocationDecision {
+  readonly kind: string;
+  readonly payload: Record<string, unknown>;
+  readonly confidence?: number;
+}
+
+export const InvocationDecisionSchema = z.object({
+  kind: z.string().min(1),
+  payload: z.record(z.string(), z.unknown()),
+  confidence: z.number().optional(),
+}) as z.ZodType<InvocationDecision>;

package/src/invocation/lib/invocation-mode.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+
+/**
+ * How the Composition Invocation Runtime executes an invocation.
+ *
+ * The platform owns mode selection (deterministic `selectMode`): a biome MAY
+ * hint a mode via `ExecutionRequirements.mode`, but policy may override it.
+ *
+ * - `Sync` — the caller holds the request open until the composition produces
+ *   its root structured output. The smallest correct slice (Phase 1).
+ * - `Async` — the runtime returns immediately with a `Queued`/`Running`
+ *   invocation; the caller polls the Invocation record for the terminal state.
+ * - `Event` — the runtime returns without an `output`; the result is delivered
+ *   later as a completion event the consumer subscribes to (the default at
+ *   high throughput).
+ *
+ * Closed set — adding a mode is a coordinated kernel change so producer and
+ * consumer stay in lockstep.
+ */
+export enum InvocationMode {
+  Sync = 'sync',
+  Async = 'async',
+  Event = 'event',
+}
+
+export const InvocationModeSchema = z.nativeEnum(InvocationMode);

package/src/invocation/lib/invocation-priority.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+
+/**
+ * Scheduling priority a biome may hint on an invocation. The platform owns the
+ * actual queue ordering; this is an advisory dimension carried on
+ * `ExecutionRequirements`.
+ *
+ * Closed set — adding a priority is a coordinated kernel change.
+ */
+export enum InvocationPriority {
+  Low = 'low',
+  Normal = 'normal',
+  High = 'high',
+}
+
+export const InvocationPrioritySchema = z.nativeEnum(InvocationPriority);

package/src/invocation/lib/invocation-record.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { InvocationMode, InvocationModeSchema } from './invocation-mode';
+import { InvocationStatus, InvocationStatusSchema } from './invocation-status';
+import {
+  InvocationDecision,
+  InvocationDecisionSchema,
+} from './invocation-decision';
+
+/**
+ * The durable Invocation unit — the projection of one row the runtime persists
+ * per invocation. This is the source of truth for an invocation's lifecycle
+ * (never the underlying session).
+ *
+ * `inputRef`/`outputRef` are blob/JSON references (inline JSON in Phase 1,
+ * artifact-store refs once payloads grow). Timestamps are ISO-8601 strings.
+ */
+export interface InvocationRecord {
+  readonly id: string;
+  readonly compositionRef: string;
+  readonly orgId: string;
+  readonly projectId: string | null;
+  readonly threadKey: string;
+  readonly correlationId: string;
+  readonly idempotencyKey: string | null;
+  readonly mode: InvocationMode;
+  readonly status: InvocationStatus;
+  readonly inputRef: string;
+  readonly outputRef: string | null;
+  readonly decisions: readonly InvocationDecision[];
+  readonly costUsd: number | null;
+  readonly durationMs: number | null;
+  readonly modelRef: string | null;
+  readonly auditId: string | null;
+  readonly sessionId: string | null;
+  readonly createdAt: string;
+  readonly lastActiveAt: string;
+}
+
+export const InvocationRecordSchema = z.object({
+  id: z.string().min(1),
+  compositionRef: z.string().min(1),
+  orgId: z.string().min(1),
+  projectId: z.string().min(1).nullable(),
+  threadKey: z.string().min(1),
+  correlationId: z.string().min(1),
+  idempotencyKey: z.string().min(1).nullable(),
+  mode: InvocationModeSchema,
+  status: InvocationStatusSchema,
+  inputRef: z.string().min(1),
+  outputRef: z.string().min(1).nullable(),
+  decisions: z.array(InvocationDecisionSchema).readonly(),
+  costUsd: z.number().nullable(),
+  durationMs: z.number().nullable(),
+  modelRef: z.string().min(1).nullable(),
+  auditId: z.string().min(1).nullable(),
+  sessionId: z.string().min(1).nullable(),
+  createdAt: z.string().min(1),
+  lastActiveAt: z.string().min(1),
+}) as z.ZodType<InvocationRecord>;

package/src/invocation/lib/invocation-status.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+
+/**
+ * The runtime's durable invocation lifecycle.
+ *
+ * DISTINCT from the capability gateway's allow/deny `InvocationStatus`: the
+ * funnel decides whether a call is allowed; THIS status tracks the execution
+ * lifecycle of an allowed invocation. Do not conflate the two.
+ *
+ * - `Pending` — record created, not yet scheduled.
+ * - `Queued` — accepted onto an async/event queue.
+ * - `Running` — the composition is executing.
+ * - `Succeeded` — terminal: produced a schema-valid output.
+ * - `Failed` — terminal: execution or output-schema validation failed.
+ * - `Denied` — terminal: refused (e.g. by policy/limits) before/at execution.
+ * - `TimedOut` — terminal: exceeded a hard duration limit.
+ * - `Cancelled` — terminal: cancelled by a caller/operator.
+ *
+ * Closed set — adding a state is a coordinated kernel change.
+ */
+export enum InvocationStatus {
+  Pending = 'pending',
+  Queued = 'queued',
+  Running = 'running',
+  Succeeded = 'succeeded',
+  Failed = 'failed',
+  Denied = 'denied',
+  TimedOut = 'timed-out',
+  Cancelled = 'cancelled',
+}
+
+export const InvocationStatusSchema = z.nativeEnum(InvocationStatus);

package/src/invocation/lib/invoke-request.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import {
+  ExecutionRequirements,
+  ExecutionRequirementsSchema,
+} from './execution-requirements';
+
+/**
+ * The wire body for `composition:invoke@1` — what a caller sends through the
+ * capability funnel to execute a published composition.
+ *
+ * `CompositionInvokeRequestSchema` is the fail-fast validator the runtime
+ * applies at the wire boundary before any execution.
+ */
+export interface CompositionInvokeRequest {
+  /** Composition slug or `slug@version`. */
+  readonly compositionRef: string;
+  readonly orgId: string;
+  readonly projectId?: string;
+  /** Stable execution-context key — org+mailbox+emailThreadId for mail. */
+  readonly threadKey: string;
+  readonly correlationId?: string;
+  readonly input: Record<string, unknown>;
+  readonly requirements: ExecutionRequirements;
+}
+
+export const CompositionInvokeRequestSchema = z.object({
+  compositionRef: z.string().min(1),
+  orgId: z.string().min(1),
+  projectId: z.string().min(1).optional(),
+  threadKey: z.string().min(1),
+  correlationId: z.string().min(1).optional(),
+  input: z.record(z.string(), z.unknown()),
+  requirements: ExecutionRequirementsSchema,
+}) as z.ZodType<CompositionInvokeRequest>;

package/src/invocation/lib/invoke-response.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { InvocationMode, InvocationModeSchema } from './invocation-mode';
+import { InvocationStatus, InvocationStatusSchema } from './invocation-status';
+import {
+  InvocationDecision,
+  InvocationDecisionSchema,
+} from './invocation-decision';
+
+/**
+ * The response the runtime returns for a `composition:invoke@1` call.
+ *
+ * In `Sync` mode `output` carries the composition root structured output. In
+ * `Event` mode `output` is omitted and the consumer subscribes to the result
+ * completion event instead.
+ */
+export interface CompositionInvokeResponse {
+  readonly invocationId: string;
+  readonly status: InvocationStatus;
+  readonly mode: InvocationMode;
+  /** Sync: composition root structured output. Omitted in event mode. */
+  readonly output?: Record<string, unknown>;
+  readonly decisions?: readonly InvocationDecision[];
+  readonly costUsd?: number;
+  readonly durationMs?: number;
+  readonly modelRef?: string;
+  readonly auditId?: string;
+}
+
+export const CompositionInvokeResponseSchema = z.object({
+  invocationId: z.string().min(1),
+  status: InvocationStatusSchema,
+  mode: InvocationModeSchema,
+  output: z.record(z.string(), z.unknown()).optional(),
+  decisions: z.array(InvocationDecisionSchema).readonly().optional(),
+  costUsd: z.number().optional(),
+  durationMs: z.number().optional(),
+  modelRef: z.string().min(1).optional(),
+  auditId: z.string().min(1).optional(),
+}) as z.ZodType<CompositionInvokeResponse>;

package/src/invocation/lib/isolation-level.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+
+/**
+ * Thread-context isolation an invocation requires.
+ *
+ * - `Strict` — a fresh, never-reused thread context per invocation. The
+ *   default for mail (org+mailbox+emailThreadId): thread context is NEVER
+ *   reused across unrelated emails.
+ * - `PooledThread` — reuse a warm thread within the same `threadKey` (a warm
+ *   session-pool optimization; future, Phase 3).
+ *
+ * Closed set on purpose — both levels are honored by the runtime's pool/thread
+ * management; adding a level is a coordinated kernel change.
+ */
+export enum IsolationLevel {
+  Strict = 'strict',
+  PooledThread = 'pooled-thread',
+}
+
+export const IsolationLevelSchema = z.nativeEnum(IsolationLevel);

package/src/mail-source/index.ts

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