@xemahq/kernel-contracts 0.1.0

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

@@ -0,0 +1,266 @@
+import { z } from 'zod';
+import {
+  CapabilityPolicySchema,
+  CapabilityError,
+  CapabilityErrorCode,
+  type CapabilityPolicy,
+} from '../../capability';
+import {
+  BUILT_IN_ENVIRONMENT_SLUGS,
+  ExecutionEnvironmentKind,
+  isExecutionEnvironmentKind,
+} from './built-in-environments';
+import { ApprovalRuleSchema, type ApprovalRule } from './approval-rule';
+
+/**
+ * Canonical Execution Environment Reference grammar (plan §3.4):
+ *
+ *   `environment:<slug>`
+ *
+ * where `<slug>` matches `/^[a-z][a-z0-9-]*$/` (kebab, must start with a
+ * letter). The grammar is intentionally tight so the reference can never
+ * silently absorb a free-form string.
+ *
+ * v1 only mints refs whose slug is an `ExecutionEnvironmentKind` value
+ * (plan §16 forbids custom environments). The type still validates the
+ * *grammar* — semantic "built-in-only" enforcement lives one layer up
+ * in `authorization-api`, which calls
+ * `isExecutionEnvironmentKind(parseEnvironmentRef(ref).slug)`.
+ */
+const EXECUTION_ENVIRONMENT_REF_REGEX = /^environment:[a-z][a-z0-9-]*$/;
+
+/**
+ * Template-literal alias rather than a `unique symbol` brand — refs are
+ * serialized over the wire and JSON cannot carry a symbol; the literal
+ * alias still provides editor autocomplete on hand-written refs while
+ * accepting any string that matches the runtime regex.
+ */
+export type ExecutionEnvironmentRef = `environment:${string}` & {
+  readonly __executionEnvironmentRef?: never;
+};
+
+export const ExecutionEnvironmentRefSchema: z.ZodType<ExecutionEnvironmentRef> = z
+  .string()
+  .regex(EXECUTION_ENVIRONMENT_REF_REGEX, {
+    message:
+      'ExecutionEnvironmentRef must match `environment:<slug>` (lowercase kebab; must start with a letter).',
+  }) as unknown as z.ZodType<ExecutionEnvironmentRef>;
+
+export interface ParsedExecutionEnvironmentRef {
+  readonly slug: string;
+  readonly raw: ExecutionEnvironmentRef;
+}
+
+/**
+ * Structured error thrown by `parseEnvironmentRef` / `formatEnvironmentRef`.
+ * Carries the stable `EXECUTION_ENVIRONMENT_REF_INVALID` code. Subclass
+ * of `CapabilityError` so call sites that already branch on capability-
+ * layer errors get this for free; the dedicated code keeps the denial
+ * taxonomy crisp.
+ */
+export class ExecutionEnvironmentRefParseError extends CapabilityError {
+  constructor(args: { message: string; raw: string }) {
+    super({
+      code: CapabilityErrorCode.CapabilityRefInvalid,
+      message: args.message,
+      capability: args.raw,
+    });
+    this.name = 'ExecutionEnvironmentRefParseError';
+  }
+}
+
+/** Stable wire code for `ExecutionEnvironmentRefParseError`. */
+export const EXECUTION_ENVIRONMENT_REF_INVALID = 'EXECUTION_ENVIRONMENT_REF_INVALID';
+
+/**
+ * Parse an `ExecutionEnvironmentRef` string into its structured parts.
+ * Throws `ExecutionEnvironmentRefParseError` on any grammar violation —
+ * never returns `null`, never silently coerces.
+ */
+export function parseEnvironmentRef(ref: string): ParsedExecutionEnvironmentRef {
+  if (typeof ref !== 'string' || ref.length === 0) {
+    throw new ExecutionEnvironmentRefParseError({
+      message: 'ExecutionEnvironmentRef must be a non-empty string.',
+      raw: String(ref),
+    });
+  }
+  if (!EXECUTION_ENVIRONMENT_REF_REGEX.test(ref)) {
+    throw new ExecutionEnvironmentRefParseError({
+      message: `ExecutionEnvironmentRef "${ref}" does not match \`environment:<slug>\`.`,
+      raw: ref,
+    });
+  }
+  const slug = ref.slice('environment:'.length);
+  return { slug, raw: ref as ExecutionEnvironmentRef };
+}
+
+/**
+ * Format an `ExecutionEnvironmentRef` from a slug. Performs the same
+ * validation as `parseEnvironmentRef` so every value produced round-
+ * trips cleanly.
+ */
+export function formatEnvironmentRef(slug: string): ExecutionEnvironmentRef {
+  const raw = `environment:${slug}`;
+  if (!EXECUTION_ENVIRONMENT_REF_REGEX.test(raw)) {
+    throw new ExecutionEnvironmentRefParseError({
+      message: `formatEnvironmentRef produced invalid ref "${raw}".`,
+      raw,
+    });
+  }
+  return raw as ExecutionEnvironmentRef;
+}
+
+/**
+ * Pre-built `ExecutionEnvironmentRef` for every built-in environment.
+ * Consumers should refer to a built-in by
+ * `BUILT_IN_ENVIRONMENT_REFS[ExecutionEnvironmentKind.Sandbox]` rather
+ * than reconstructing the string.
+ */
+export const BUILT_IN_ENVIRONMENT_REFS: Record<
+  ExecutionEnvironmentKind,
+  ExecutionEnvironmentRef
+> = Object.freeze(
+  BUILT_IN_ENVIRONMENT_SLUGS.reduce(
+    (acc, slug) => {
+      acc[slug] = formatEnvironmentRef(slug);
+      return acc;
+    },
+    {} as Record<ExecutionEnvironmentKind, ExecutionEnvironmentRef>,
+  ),
+);
+
+/**
+ * Runtime budget caps the environment advertises to the gateway (plan §3.4
+ * `ExecutionEnvironment.runtimeLimits`). All fields are optional — omitted means
+ * "no cap from the environment", but the gateway may still apply org- or
+ * grant-level caps. None of these fields fall back to a hidden default.
+ */
+export interface RuntimeLimits {
+  maxTokens?: number;
+  maxCostUsd?: number;
+  maxDurationSeconds?: number;
+  maxToolCalls?: number;
+}
+
+export const RuntimeLimitsSchema = z.object({
+  maxTokens: z.number().int().nonnegative().optional(),
+  maxCostUsd: z.number().nonnegative().optional(),
+  maxDurationSeconds: z.number().int().nonnegative().optional(),
+  maxToolCalls: z.number().int().nonnegative().optional(),
+}) as z.ZodType<RuntimeLimits>;
+
+/**
+ * Allow-list of knowledge scope refs reachable from this environment (plan §3.4
+ * `ExecutionEnvironment.allowedKnowledgeScopes`).
+ *
+ * v1 keeps the shape minimal — the ref string is sufficient for the
+ * sandbox→prod boundary check that lands in Phase 4. Detailed per-scope
+ * sub-schemas (e.g. spaces, page subtrees, redaction rules) are scheduled
+ * for the knowledge-base-api Phase 4+ companion plan.
+ */
+export interface KnowledgePolicy {
+  allowedRefs: readonly string[];
+}
+
+export const KnowledgePolicySchema = z.object({
+  allowedRefs: z.array(z.string().min(1)).readonly(),
+}) as z.ZodType<KnowledgePolicy>;
+
+/**
+ * Allow-list of connector binding refs reachable from this environment (plan §3.4
+ * `ExecutionEnvironment.allowedConnectors`).
+ *
+ * v1 keeps the shape minimal — the ref string is sufficient for the
+ * sandbox→prod boundary check that lands in Phase 4. Per-connector
+ * permission detail (per-repo globs, per-tracker projects, etc.) is
+ * scheduled for the connector-gateway-api companion plan.
+ */
+export interface ConnectorPolicy {
+  allowedRefs: readonly string[];
+}
+
+export const ConnectorPolicySchema = z.object({
+  allowedRefs: z.array(z.string().min(1)).readonly(),
+}) as z.ZodType<ConnectorPolicy>;
+
+/**
+ * Allow-list of biome refs that may run inside this environment (plan §3.4
+ * `ExecutionEnvironment.allowedBiomes`).
+ *
+ * v1 keeps the shape minimal — the ref string is sufficient for the
+ * built-in-environment install policy that lands in Phase 4 / Phase 6. Lifecycle-
+ * stage restrictions (draft / published / archived) are scheduled for the
+ * biome-host-api companion plan.
+ */
+export interface BiomePolicy {
+  allowedRefs: readonly string[];
+}
+
+export const BiomePolicySchema = z.object({
+  allowedRefs: z.array(z.string().min(1)).readonly(),
+}) as z.ZodType<BiomePolicy>;
+
+/**
+ * Allow-list of mount-source refs reachable from this environment (plan §3.4
+ * `ExecutionEnvironment.allowedMounts`).
+ *
+ * v1 keeps the shape minimal — the ref string is sufficient for the
+ * XVFS read/write boundary check that lands in Phase 4 / Phase 5. Per-mount
+ * read/write splitting and path globs are scheduled for the xema-shell-api
+ * companion plan.
+ */
+export interface MountPolicy {
+  allowedRefs: readonly string[];
+}
+
+export const MountPolicySchema = z.object({
+  allowedRefs: z.array(z.string().min(1)).readonly(),
+}) as z.ZodType<MountPolicy>;
+
+/**
+ * `ExecutionEnvironment` — the canonical permission-plane object (plan §3.4).
+ *
+ * An environment declares the capability surface, knowledge/connector/biome/mount
+ * allow-lists, approval rules, and runtime budget that apply to every
+ * invocation tagged with this environment's ref.
+ *
+ * `scope` widens to `ExecutionEnvironmentKind | string` to keep room for
+ * v2 custom environments; at v1 the only legal scope values are
+ * `ExecutionEnvironmentKind` members. Use
+ * `isExecutionEnvironmentKind(scope)` to enforce that at construction
+ * sites.
+ */
+export interface ExecutionEnvironment {
+  ref: ExecutionEnvironmentRef;
+  /**
+   * The environment's logical scope. v1 only accepts
+   * `ExecutionEnvironmentKind` slugs; the string-side of the union is
+   * reserved for v2 custom environments (plan §16 non-goal at v1).
+   */
+  scope: ExecutionEnvironmentKind | string;
+  allowedCapabilities: CapabilityPolicy[];
+  allowedKnowledgeScopes: KnowledgePolicy[];
+  allowedConnectors: ConnectorPolicy[];
+  allowedBiomes: BiomePolicy[];
+  allowedMounts: MountPolicy[];
+  approvalRules: ApprovalRule[];
+  runtimeLimits: RuntimeLimits;
+}
+
+export const ExecutionEnvironmentSchema = z.object({
+  ref: ExecutionEnvironmentRefSchema,
+  scope: z.string().min(1).refine(
+    (s) => isExecutionEnvironmentKind(s),
+    {
+      message:
+        'ExecutionEnvironment.scope must be an ExecutionEnvironmentKind slug at v1; custom environments are a v2 extension (plan §16).',
+    },
+  ),
+  allowedCapabilities: z.array(CapabilityPolicySchema),
+  allowedKnowledgeScopes: z.array(KnowledgePolicySchema),
+  allowedConnectors: z.array(ConnectorPolicySchema),
+  allowedBiomes: z.array(BiomePolicySchema),
+  allowedMounts: z.array(MountPolicySchema),
+  approvalRules: z.array(ApprovalRuleSchema),
+  runtimeLimits: RuntimeLimitsSchema,
+}) as z.ZodType<ExecutionEnvironment>;

package/src/kernel-state/index.ts

@@ -0,0 +1,3 @@
+export * from './lib/kernel-state';
+export * from './lib/key-grammar';
+export * from './lib/adapter-kind';

package/src/kernel-state/lib/adapter-kind.ts

@@ -0,0 +1,18 @@
+/**
+ * KernelState adapter kinds (plan §6 Phase D.3 — locked decision L9).
+ *
+ * The plan explicitly closes the set to TWO adapters. There is no
+ * Postgres adapter for KernelState; Postgres is reserved for service
+ * domain data. Two DB engines max in any deployment is a load-bearing
+ * invariant — do NOT extend this enum without updating L9.
+ *
+ * - `Sqlite` — file at `~/.xema/dev/kernel-state.sqlite` (dev) or
+ *   `/var/lib/xema/kernel-state.sqlite` (single-instance). Advisory
+ *   locking via `BEGIN IMMEDIATE`; watches via in-process pub-sub.
+ * - `Etcd` — direct etcd client. Leases via etcd TTL; watches via etcd
+ *   streams.
+ */
+export enum KernelStateAdapterKind {
+  Sqlite = 'sqlite',
+  Etcd = 'etcd',
+}

package/src/kernel-state/lib/kernel-state.ts

@@ -0,0 +1,139 @@
+/**
+ * KernelState client contract (plan §6 Phase D.3).
+ *
+ * KernelState is the kernel's single strongly-consistent KV / lease /
+ * watch primitive. Every adapter (SQLite or etcd — see
+ * `KernelStateAdapterKind`) implements this interface; every callsite
+ * (Service Registry writer, runner attestation store, desired-state
+ * controller, route registry, etc.) talks to KernelState through this
+ * one shape.
+ *
+ * All keys MUST pass `validateKernelStateKey` (see `./key-grammar`).
+ * Adapters MUST throw fail-fast — never silently coerce or drop.
+ */
+
+export interface KernelStateEntry {
+  key: string;
+  /**
+   * Adapter-agnostic JSON value. Adapters serialize as JSON on write
+   * and parse on read; callers MUST NOT pass binary or non-JSON-safe
+   * values.
+   */
+  value: unknown;
+  /**
+   * Monotonic revision assigned by the adapter on every successful
+   * write of `key`. Used for CAS in `PutOptions.ifRevision`. Adapters
+   * MUST guarantee strictly-increasing revisions per-key.
+   */
+  revision: number;
+  /**
+   * Optional lease this entry is associated with. If set, the entry
+   * is deleted when the lease expires or is revoked.
+   */
+  leaseId?: string;
+  /**
+   * Absolute UTC ISO-8601 timestamp at which the adapter accepted the
+   * write.
+   */
+  modifiedAt: string;
+}
+
+/**
+ * Change events delivered to `watch()` callbacks. The closed kind set
+ * makes it impossible to silently swallow a new event type.
+ */
+export enum KernelStateChangeKind {
+  Put = 'put',
+  Delete = 'delete',
+}
+
+export interface KernelStateChange {
+  kind: KernelStateChangeKind;
+  key: string;
+  /**
+   * Present for `Put`; absent for `Delete`. Adapters MUST NOT collapse
+   * a delete-then-put pair into a single event — consumers rely on the
+   * full sequence to maintain in-memory caches.
+   */
+  entry?: KernelStateEntry;
+  /**
+   * Revision of the change. Strictly increasing across all keys in a
+   * single watch subscription so consumers can resume after a
+   * disconnect by passing the last seen revision to a future API
+   * extension. Adapters MUST NOT reuse revisions.
+   */
+  revision: number;
+}
+
+/**
+ * Lease handle returned by `acquireLease` / `renewLease`. The lease is
+ * the only mechanism for expiring keys. Mirrors etcd's lease semantics
+ * intentionally so the etcd adapter is a pass-through.
+ */
+export interface KernelStateLease {
+  leaseId: string;
+  /**
+   * Absolute UTC ISO-8601 timestamp at which the lease (and every
+   * entry attached to it) expires unless renewed.
+   */
+  expiresAt: string;
+  ttlSeconds: number;
+}
+
+/**
+ * Options accepted by `put`. All fields are optional; the default is
+ * a blind unconditional write with no lease attachment.
+ */
+export interface PutOptions {
+  /**
+   * Optimistic-concurrency check: write only if the current revision
+   * of `key` equals this value. `0` means "create only — fail if the
+   * key already exists". Adapters MUST throw a typed
+   * `KernelStateRevisionMismatchError` on mismatch (no silent
+   * overwrite).
+   */
+  ifRevision?: number;
+  /**
+   * Attach the new entry to an existing lease. When the lease
+   * expires, the entry is deleted. Mutually exclusive with `ttlSeconds`
+   * below — passing both is a programming error and adapters MUST
+   * throw.
+   */
+  leaseId?: string;
+  /**
+   * Shorthand for "create a one-off lease of this TTL and attach this
+   * single key to it". The lease is owned by the entry; renewing it
+   * requires a separate `acquireLease`/`renewLease` flow.
+   */
+  ttlSeconds?: number;
+}
+
+/**
+ * The KernelState client. Every adapter implements exactly this
+ * surface — no extension methods, no provider-specific escape hatches.
+ *
+ * Implementations MUST:
+ * - call `validateKernelStateKey(key)` on every key before any I/O.
+ * - throw on `get` / `delete` of an invalid key (fail-fast).
+ * - return `null` from `get` when the key is valid but absent (this
+ *   is the ONLY non-error "missing" state — `list` returns `[]`).
+ * - deliver an initial snapshot to a `watch` subscriber synchronously
+ *   on subscribe, then subsequent `KernelStateChange[]` batches in
+ *   revision order.
+ * - return a function from `watch` that fully detaches the
+ *   subscription when invoked.
+ * - throw on `renewLease` of an unknown / already-expired lease (no
+ *   silent re-acquire).
+ */
+export interface KernelState {
+  get(key: string): Promise<KernelStateEntry | null>;
+  list(prefix: string): Promise<KernelStateEntry[]>;
+  put(key: string, value: unknown, opts?: PutOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  watch(
+    prefix: string,
+    cb: (events: KernelStateChange[]) => void,
+  ): () => void;
+  acquireLease(key: string, ttlSeconds: number): Promise<KernelStateLease>;
+  renewLease(leaseId: string): Promise<KernelStateLease>;
+}

package/src/kernel-state/lib/key-grammar.ts

@@ -0,0 +1,105 @@
+/**
+ * KernelState key grammar (plan §6 Phase D.4).
+ *
+ * Every key written to KernelState MUST start with one of the prefixes
+ * below. The boundary CI script `check-kernel-state-key-ownership.mjs`
+ * parses every `kernelState.put(...)` call site at build time and
+ * validates the prefix against the writer's declared role; this enum
+ * is the single source of truth that script reads from.
+ *
+ * String values include trailing `/` so concatenation
+ * (`KernelStateKeyPrefix.Services + name`) yields a valid key with
+ * exactly one separator.
+ */
+export enum KernelStateKeyPrefix {
+  Runners = '/xema/runners/',
+  Biomes = '/xema/biomes/',
+  Capabilities = '/xema/capabilities/',
+  Routes = '/xema/routes/',
+  Services = '/xema/services/',
+  DesiredState = '/xema/desired-state/',
+  Leases = '/xema/leases/',
+  Locks = '/xema/locks/',
+  Config = '/xema/config/',
+  Policies = '/xema/policies/',
+}
+
+/**
+ * Frozen, ordered list of every valid prefix. Exported so tooling
+ * (boundary check, docs gen) can iterate without re-deriving from the
+ * enum at runtime.
+ */
+export const KERNEL_STATE_KEY_PREFIXES: readonly KernelStateKeyPrefix[] =
+  Object.freeze([
+    KernelStateKeyPrefix.Runners,
+    KernelStateKeyPrefix.Biomes,
+    KernelStateKeyPrefix.Capabilities,
+    KernelStateKeyPrefix.Routes,
+    KernelStateKeyPrefix.Services,
+    KernelStateKeyPrefix.DesiredState,
+    KernelStateKeyPrefix.Leases,
+    KernelStateKeyPrefix.Locks,
+    KernelStateKeyPrefix.Config,
+    KernelStateKeyPrefix.Policies,
+  ]);
+
+/**
+ * Fail-fast guard: throws when `key` is not anchored to one of the
+ * known prefixes. Used by every adapter at the write boundary AND by
+ * the boundary CI script at scan time.
+ *
+ * Rejection cases:
+ * - non-string input
+ * - empty string
+ * - prefix not in the closed set above
+ * - key equal to a prefix (no body after the trailing `/`)
+ */
+export function validateKernelStateKey(key: string): KernelStateKeyPrefix {
+  if (typeof key !== 'string' || key.length === 0) {
+    throw new Error(
+      `KernelState key must be a non-empty string, received: ${typeof key}`,
+    );
+  }
+  const match = KERNEL_STATE_KEY_PREFIXES.find((prefix) =>
+    key.startsWith(prefix),
+  );
+  if (match === undefined) {
+    throw new Error(
+      `KernelState key "${key}" does not start with a known prefix. ` +
+        `Valid prefixes: ${KERNEL_STATE_KEY_PREFIXES.join(', ')}`,
+    );
+  }
+  if (key.length === match.length) {
+    throw new Error(
+      `KernelState key "${key}" is exactly the prefix; a body segment after the trailing "/" is required.`,
+    );
+  }
+  return match;
+}
+
+/**
+ * Prefix-side validation for `list()` / `watch()` arguments. Unlike
+ * `validateKernelStateKey`, the input MAY be exactly a known prefix
+ * (e.g. `/xema/services/` to scan every service entry) — that is the
+ * intended "scan everything under this owner" use case.
+ *
+ * Rejection cases:
+ * - non-string input
+ * - empty string
+ * - prefix that does not start with one of the known top-level prefixes
+ */
+export function validateKernelStatePrefix(prefix: string): KernelStateKeyPrefix {
+  if (typeof prefix !== 'string' || prefix.length === 0) {
+    throw new Error(
+      `KernelState prefix must be a non-empty string, received: ${typeof prefix}`,
+    );
+  }
+  const match = KERNEL_STATE_KEY_PREFIXES.find((p) => prefix.startsWith(p));
+  if (match === undefined) {
+    throw new Error(
+      `KernelState prefix "${prefix}" does not start with a known prefix. ` +
+        `Valid prefixes: ${KERNEL_STATE_KEY_PREFIXES.join(', ')}`,
+    );
+  }
+  return match;
+}

package/src/llm-gateway/index.ts

@@ -0,0 +1,2 @@
+export * from './lib/errors';
+export * from './lib/caller';

package/src/llm-gateway/lib/caller.ts

@@ -0,0 +1,48 @@
+/**
+ * Generic envelope identifying *which* domain object an LLM call is
+ * being attributed to. Carried through the LLM gateway end-to-end
+ * (gateway session JWT → usage event → pipeline-history `LlmUsageRecord`)
+ * so every call is traceable regardless of which platform feature
+ * issued it — pipeline runs, chat threads, interactive sessions,
+ * ad-hoc direct calls, future call kinds.
+ *
+ * Single source of truth for both the gateway service and every platform
+ * consumer. Submodule services that cannot yet depend on this package
+ * (because they are vendored independently) keep a value-identical local
+ * copy guarded by `scripts/check-llm-caller-parity.mjs`. That parity
+ * script is deleted once every submodule consumes this package.
+ */
+export enum LlmCallerKind {
+  /** A pipeline run (FK to `PipelineRun.id` in pipeline-history). */
+  PIPELINE_RUN = 'pipeline_run',
+  /** A bootstrap chat thread (e.g. clarification flow before launch). */
+  CHAT_THREAD = 'chat_thread',
+  /** An interactive session (long-lived agent worker). */
+  AGENT_SESSION = 'agent_session',
+  /**
+   * A direct call with no enclosing user-facing artifact — e.g. internal
+   * embedding requests, system bootstrap probes, ad-hoc API usage.
+   */
+  DIRECT = 'direct',
+}
+
+/**
+ * Stable wire shape carried alongside every gateway session.
+ *
+ * - `kind` + `id` together identify the originating object.
+ * - `orgId` is always present (billing/audit anchor).
+ * - `projectId` is set when the call is project-scoped (most are).
+ * - `groupKey` is set when the caller is tied to a workflow's structural
+ *   group bucket. Kernel-neutral name; a sub-app biome (e.g. software-dev)
+ *   maps its own `phaseKey` value onto this field at compile time.
+ *
+ * Adding new fields is non-breaking; renaming or repurposing existing
+ * ones is breaking and requires updates on both gateway and consumers.
+ */
+export interface LlmCaller {
+  kind: LlmCallerKind;
+  id: string;
+  orgId: string;
+  projectId?: string;
+  groupKey?: string;
+}